Stan models shipped with TEXAS#

src/TEXAS/stan_models/ holds seven .stan files: the three forward calibrations the revised manuscript fits, the three inverse (proxy → temperature) models it runs, and one straight-line reference model used in the SI figures. Everything else ever written for this project lives in archive/submission-2026-04/stan_models/, whose README names each retired file, says why it was retired, and shows how to run one by absolute path.

pyproject.toml declares package data as stan_models/*.stan — a non-recursive glob — so only these seven reach the wheel.

Naming convention#

{transform}_{curve}_{params}_{datasources}_{variant}.stan

position

values used in the shipped set

transform

(none) = forward calibration; invT_ = inverse

curve

gen_logi = generalized logistic (Richards); linear

params

fixed = upper asymptote pinned at 1

data sources

culmeso = culture + mesocosm; hier_crtp = hierarchical coretop

variant

univ / multiv = without / with non-thermal predictors; priorApprox = stage-2 fit using stage-1 hyperpriors; eiv = errors-in-variables; t0shift = predictors shift T₀; marginal = ensemble marginalized analytically; unconstrained = no bound on T

Forward calibration#

file

role

gen_logi_fixed_culmeso.stan

Stage 1. One generalized logistic fitted jointly to the culture and mesocosm data — the controlled experiments, which constrain the shape of the response. Its posterior mean and SD for {t0, k, b, v} are the hyperpriors every priorApprox model consumes, so this fit runs first.

gen_logi_fixed_hier_crtp_univ_priorApprox.stan

Stage 2, thermal only (compset GHPU). Coretop fit of the Scaled Ring Index against temperature with no non-thermal predictors; the two bundled thermal-only posteriors come from it. It is also the source of R2_thermal, which the EIV model requires as data.

gen_logi_fixed_hier_crtp_multiv_priorApprox_eiv_t0shift.stan

The production calibration (compset GHEB). Coretop fit with the G₂/₃ ratio and NO₃ entering as a shift of the curve’s location parameter — the manuscript’s T₀-shift parameterization — plus Bayesian errors-in-variables on those predictors and on the RI. The two bundled multivariate posteriors (tx.GHEB.sst/thm.sri03.G23-N1p0) were fitted with it.

All three share the curve

RI = b + (1 - b) / (1 + exp(-k * (T - T0)))^(1/v)

with the upper asymptote fixed at 1 and Q fixed at 1. T₀ is the curve’s location parameter, not its inflection point. The steepest response sits at T0 - ln(v)/k, several °C below T₀ for the fitted ν, and the slope varies severalfold across the sampled range — so there is no single thermal sensitivity to quote for this curve.

In the T₀-shift model the predictors move T₀ rather than the mean:

T0_eff[i] = T0 + gamma_G23 * g23_true[i] + gamma_NO3 * log10(no3_true[i])
mu[i]     = b + (1 - b) / (1 + exp(-k * (T[i] - T0_eff[i])))^(1/v)

Because they act inside the logistic, mu stays within (b, 1) for any finite predictor value and any finite coefficient. That bounded-by-construction property is why the parameterization was adopted.

Inverse reconstruction#

file

role

invT_gen_logi_fixed_univ_marginal_unconstrained.stan

Univariate inverse — proxy only, no predictors. Used by the quickstart and by SI_code03.

invT_gen_logi_fixed_multiv_marginal_unconstrained.stan

Multivariate inverse for the additive (β-on-μ) forward arm of the initial submission (compset GHEA). Kept so the posteriors on version 0.2.0 of the data record remain reconstructable; not used by the published analyses.

invT_gen_logi_fixed_multiv_marginal_unconstrained_t0shift.stan

Multivariate inverse for the T₀-shift forward arm. The production inverse.

predict_T_from_proxyObs() selects among these for you: the univariate file when no predictor arrays are supplied, a multivariate file when they are, and the t0shift file when the forward posterior being marginalized over was fitted with the T₀-shift parameterization.

Reference model#

linear_model.stan fits proxy = slope · T + intercept with both coefficients constrained non-negative. It is the straight-line form the sigmoid calibrations are compared against in the SI figures, and is used by the preprocessing and analysis notebooks. It is deliberately not a general-purpose linear regression.

How the marginal likelihood works#

The inverse question is: given an observed proxy value, what temperature produced it — allowing for the fact that the calibration curve is itself uncertain? TEXAS answers it by drawing M parameter sets from the forward posterior and integrating over them.

The direct way would be to sample an N × M matrix of temperatures, one per observation per forward draw. The shipped models instead sample N temperatures and do that integral analytically inside the log-density:

for (n in 1:N) {
  vector[M] llk;
  for (m in 1:M)
    llk[m] = normal_lpdf(proxyObs[n] | fwd(t_est[n], params[m]), sigma[m]);
  lp += log_sum_exp(llk) - log(M);   // log[(1/M) * sum_m exp(llk_m)]
}

log_sum_exp(llk) - log(M) is the marginalization — the log of the mean likelihood across the ensemble. It targets the same posterior as the matrix formulation from a parameter space two orders of magnitude smaller, with far better sampling geometry. Why the geometry matters, and what it does to the effective sample size, is worked through in Why marginalization improves inverse TEXAS sampling.

How threading works#

All three inverse models wrap that observation loop in Stan’s reduce_sum, which splits the N observations into chunks evaluated on separate CPU threads. The chunk size is the grainsize data variable:

  • grainsize = 1 → maximum parallelism (best on many cores)

  • grainsize = N → no parallelism, bit-for-bit the same result

Threading is active only when the model is compiled with STAN_THREADS=True and run with threads_per_chain > 1; otherwise reduce_sum evaluates the same code sequentially. It pays off when N is large — hundreds of observations — and the M loop is expensive; below roughly N = 20 the overhead can outweigh the gain. Understanding reduce_sum and ll_chunk explains the mechanism without assuming any Stan.

The forward calibrations are not threaded. Their cost is in the hierarchical structure and the latent EIV variables, not in one long independent loop, so there is nothing for reduce_sum to split.

See also#