TEXAS — TetraEther indeX of Ammonia oxidizerS: a proxy system model for TEX₈₆ paleothermometry
TEXAS-PSM (texas-psm) is a Python package implementing a Bayesian proxy
system model for the TEX86 paleothermometer. TEXAS is its sensor model —
the calibration linking temperature to the index — while TEXAS-PSM is the
framework around it: sensor, archive, and observation submodels, plus the
inversion back to temperature. This release implements the sensor model and the
inversion; the archive model is not yet implemented, and the observation model
propagates analytical uncertainty only. The distribution name and the import
reflect that split (pip install texas-psm, import TEXAS).
The package fits hierarchical generalized-logistic Stan models that link temperature to an isoGDGT index (Scaled RI), with optional nonthermal predictors for AOA ecology (GDGT-2/GDGT-3 ratio) and nutrient availability (NO₃⁻). It then reconstructs paleotemperatures from new sediment records with full posterior uncertainty.
📦 Installation 📖 Documentation 🤝 Contributing 📄 License
What it does
TEXAS implements a two-stage workflow:
| Stage | Description |
|---|---|
| Forward calibration | Fit a generalized logistic curve (temperature → Scaled RI) to culture, mesocosm, and/or coretop data using a hierarchical Bayesian Stan model. Outputs a compressed posterior .nc file. |
| Inverse reconstruction (invT) | Predict paleotemperatures from Scaled RI observations by marginalizing over posterior parameter draws. Returns a full posterior temperature distribution per sample. |
Optional nonthermal predictors — the GDGT-2/GDGT-3 ratio (G23) and nitrate (NO₃⁻) — enter inside the logistic, as a shift of the curve's location parameter T₀:
T₀_eff = T₀ + γ_{G23}·G23 + γ_{NO₃}·log₁₀(NO₃)
Scaled RI = b + (1 − b) / (1 + exp(−k·(T − T₀_eff)))^(1/ν)
The γ coefficients are in °C per predictor unit: a positive γ_{G23}·G23 shifts the curve to warmer temperatures, so the sample yields the Scaled RI of water γ_{G23}·G23 °C colder. Because the predictors shift the curve along the temperature axis rather than adding an offset to Scaled RI, predictions stay inside (b, 1) for any finite predictor value by construction, with no truncation or clipping. They are fitted through an Error-in-Variables (EIV) Stan model that separates analytical measurement error from oceanographic process noise. Inverse models use reduce_sum for within-chain parallelism.
T₀ is the curve's location, not its inflection point. The steepest response sits at
T₀ − ln(ν)/k, roughly 4–5 °C below T₀ for the fitted ν. BecausedRI/dTvaries about sixfold across the calibrated range, there is no single thermal sensitivity to quote for this proxy.
Quick start
pip install texas-psm # inside a virtual environment
# or, with uv: uv pip install texas-psm (or `uv add texas-psm` in a uv project)
Inverse reconstruction runs Stan, so pip/uv users need CmdStan installed once — run
TEXAS.install_cmdstan()(or thetexas-install-cmdstancommand), which installs the tested version and verifies the toolchain. Docker and conda-lock bundle it. The forwardpredict_proxy_from_Tis pure Python and needs no CmdStan. See Installation.
import TEXAS
# The temperature-only (univariate) SST calibration ships with the package,
# so no download is needed here. Other calibrations: TEXAS.download_posteriors().
# Posterior names are CESM-style case ids (tx.<compset>.<temp>.<proxy>.<predictors>);
# legacy long names (gen_logi_fixed_...) are also accepted everywhere. See
# "How posterior files are named" in the docs quickstart.
# Forward: temperature → Scaled RI
result = TEXAS.predict_proxy_from_T(
temperatures=[15, 20, 25, 30],
posterior="tx.GHPU.sst.sri03.p0",
)
# Inverse: Scaled RI → temperature
result = TEXAS.predict_T_from_proxyObs(
proxyObs=my_ri_array, # your Scaled RI values (see compute_scaledRI below)
prior_mu_t=15.0, prior_sigma_t=10.0,
fwd_posterior="tx.GHPU.sst.sri03.p0",
temptype="SST",
)
result["p50"] # median temperature (°C)
result["p5"] # 5th percentile
result["p95"] # 95th percentile
That is all you need to use TEXAS on your own data. To fork the repository or run the manuscript notebooks (uv sync from a clone, Docker, or conda), see Installation.
Data and posteriors
Pre-computed posteriors and training data are hosted on Zenodo: https://doi.org/10.5281/zenodo.19666744
import TEXAS
TEXAS.download_all() # posteriors + training CSVs
TEXAS.download_posteriors() # forward posteriors only (~475 MB total;
# multivariate EIV posteriors are ~78-81 MB each)
TEXAS.download_training_data() # training CSVs + CMEMS NO₃ field
Pass names= to download only what you need:
# Single-predictor SST calibration (G23 only) — ~78 MB
TEXAS.download_posteriors(["tx.GHEB.sst.sri03.G23"])
The default multivariate and temperature-only calibrations (tx.GHEB.*.sri03.G23-N1p0, tx.GHPU.*.sri03.p0, for both SST and thermocline temperature) ship inside the package and need no download.
Load a posterior directly from disk (no cache lookup):
import xarray as xr
ds = xr.load_dataset("/path/to/posterior.nc")
result = TEXAS.predict_T_from_proxyObs(..., fwd_posterior=ds)
Check what is cached:
TEXAS.list_posteriors()
| Install method | Posteriors | Training data |
|---|---|---|
pip install texas-psm |
~/.texas/cache/TEXAS_posterior_cache/ |
~/.texas/data/spreadsheets/ |
From source (pip install -e .) |
data/cache/TEXAS_posterior_cache/ |
data/spreadsheets/ |
Example usage
import numpy as np
import xarray as xr
from TEXAS import compute_scaledRI, predict_proxy_from_T, predict_T_from_proxyObs
# ── Compute Scaled Ring Index from raw GDGT abundances ────────────────────────
# df: a pandas DataFrame with one row per sample and the six isoGDGT columns
df["scaledRI_cren3"] = compute_scaledRI(
df["GDGT-0"], df["GDGT-1"], df["GDGT-2"], df["GDGT-3"],
df["cren"], df["cren_prime"], # cren_weight=3 by default (RI₀₋₃)
)
# ── Forward prediction (temperature → proxy) ──────────────────────────────────
result = predict_proxy_from_T(
temperatures=np.linspace(5, 35, 100),
posterior="tx.GHPU.sst.sri03.p0",
)
# result["p50"], result["p5"], result["p95"] — numpy arrays
# ── Inverse reconstruction (proxy → temperature) ──────────────────────────────
result = predict_T_from_proxyObs(
proxyObs=df["scaledRI_cren3"].values,
prior_mu_t=15.0, prior_sigma_t=10.0,
fwd_posterior="tx.GHPU.sst.sri03.p0",
temptype="SST",
save_results=True, # write quantile .nc + .npz to the invT cache dir
)
# ── Multivariate model with NO₃⁻ and GDGT-2/GDGT-3 predictors ────────────────
# This is the default: omitting fwd_posterior selects the full multivariate
# T₀-shift calibration, which ships inside the package — no download needed.
# Pass temptype="thermoT" for the thermocline-integrated calibration.
result = predict_T_from_proxyObs(
proxyObs=df["scaledRI_cren3"].values,
prior_mu_t=15.0, prior_sigma_t=10.0,
fwd_posterior="tx.GHEB.sst.sri03.G23-N1p0", # the default; may be omitted
temptype="SST",
gdgt23ratio=df["gdgt23ratio"].values,
no3=df["no3"].values, # or: site_lat=, site_lon= for a modern CMEMS nitrate lookup
)
# ── Pass a pre-loaded dataset (Colab / Google Drive) ──────────────────────────
# (downloads are named by case id; v0.2.0-era files keep their legacy name)
ds = xr.load_dataset("/content/drive/MyDrive/posteriors/tx.GHPU.sst.sri03.p0.fwd.nc")
result = predict_T_from_proxyObs(..., fwd_posterior=ds)
Repository layout
src/TEXAS/
predict.py High-level API: predict_proxy_from_T / predict_T_from_proxyObs
stan/ Sampler, compiler, I/O, and invT orchestration
stan_models/ Stan model files (.stan) — bundled in the pip package
data/ Input data builders, filters, screening, ocean property lookups
ensemble/ Posterior ensemble generation and model detection
models/ Logistic curve functions and classical calibrations
utils/ Path constants, system info, Zenodo download utilities
notebooks/
quickstart_demo.ipynb Minimal end-to-end path: GDGTs -> Scaled RI -> temperature
quickstart_extended.ipynb Longer walkthrough: a published record, model comparison
manuscripts/ Finalized SI notebooks behind the paper (SI_code00 .. SI_code03)
reviewer_response/ Analyses answering review comments, not cited in the paper
docker/ Dockerfile and compose configuration
docs/ Jupyter Book documentation source (guides, API, explainers)
tests/ Unit tests
API at a glance
| Function | Description |
|---|---|
compute_scaledRI(gdgt0, …, cren_prime) |
Compute Scaled RI (RI₀₋₃ by default) from six isoGDGT abundances |
predict_proxy_from_T(temperatures, posterior, …) |
Forward: temperature → proxy percentiles (pure Python) |
predict_T_from_proxyObs(proxyObs, prior_mu_t, prior_sigma_t, fwd_posterior, …) |
Inverse: proxy → temperature with full uncertainty (runs Stan); accepts name string or xr.Dataset |
download_posteriors(names, …) |
Download forward posteriors from Zenodo (with per-file size notice) |
download_training_data(…) |
Download training CSVs + CMEMS NO₃ field from Zenodo |
list_posteriors() |
Print and return .nc stems in the local cache |
lookup_modern_no3(lat, lon, ocean_dataset) |
Modern NO₃ at drill-site coordinates from the CMEMS nitrate climatology (ocean_prop_ds); lookup_no3_from_woa is a deprecated alias |
build_fwd_data(t_cul, proxy_cul, …) |
Build validated Stan data dict for forward calibration |
get_posterior(data, stan_file, temptype, proxy_name, …) |
Run forward calibration Stan sampling |
save_posterior(ds) / load_posterior(name) |
Persist / load forward posterior as compressed NetCDF |
set_cache_dir(path) |
Override cache root at runtime |
summarize_sampler_diagnostics(fit) |
Divergences, R-hat, ESS, E-BFMI |
Full API reference: https://paleolipidrr.github.io/TEXAS
Citation
If you use TEXAS in your research, please cite:
Rattanasriampaipong, R., Tierney, J. E., Elling, F. J., & Inglis, G. N. (2026). TEXAS: A proxy system model for TEX86 paleothermometry. ESS Open Archive (preprint). https://doi.org/10.22541/essoar.15002926/v3 — under review at Paleoceanography and Paleoclimatology.
and the software version you used (Zenodo concept DOI, which resolves to the latest release: 10.5281/zenodo.19671664). See CITATION.cff for machine-readable citation metadata.
License
MIT © Ronnakrit Rattanasriampaipong — see LICENSE for the full text.
Metadata
Release files for texas-psm 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| texas_psm-1.0.2.tar.gz | 1.4 MB | Without provenance | Details for texas_psm-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| texas_psm-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for texas_psm-1.0.2-py3-none-any.whl |
Total release size: 2.7 MB
Release files / texas_psm-1.0.2.tar.gz
| Download URL | texas_psm-1.0.2.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bf584cb15f9d08475a379bffd2ae37659f9e980c8710158061cb4e231ebdd9dc
|
|
BLAKE2b-256 checksum How to use checksums |
1be6a8dd4da8f60c661b8c62d6c7eabecc3a032ce287d82e8c3ce0cb46ef14bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.8
|
Release files / texas_psm-1.0.2-py3-none-any.whl
| Download URL | texas_psm-1.0.2-py3-none-any.whl |
|---|---|
| Size | 1.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
34412ff8fb0b2fcfa46b3dbb305fb853f00afbceb3b5ffaea1e88f45211c43f8
|
|
BLAKE2b-256 checksum How to use checksums |
f304cf473e811416216a3c7285fecd9cc6dfa97bd2c516d7e030c382e4385687
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.8
|
Security for texas-psm 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.