Skip to main content

TEXAS — A proxy system model for TetraEther indeX of Ammonia oxidizerS

License: MIT Python 3.10+ PyPI Zenodo

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 whole chain around it: sensor, archive, observation, and the inversion back to temperature. The distribution name and the import already carry that split (pip install texas-psm, import TEXAS). It fits hierarchical generalized-logistic Stan models to isoGDGT proxy data (Scaled RI) for thermal responses — with optional non-thermal corrections for AOA ecology (GDGT-2/3 ratio) and nutrient effects (NO₃) — and 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 (Scaled RI → temperature) 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 non-thermal predictors — the GDGT-2/GDGT-3 (G23) and 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, so a sample with a given G23 behaves like water that is γ·G23 °C colder. Because the predictors translate the curve rather than adding an offset to the response, the predicted Scaled RI stays inside (b, 1) for any finite predictor value — the bound a ratio has by definition is reproduced 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 ν. Because dRI/dT varies about sixfold across the calibrated range, there is no single thermal sensitivity to quote for this proxy.


Quick start

Open in Colab

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 the texas-install-cmdstan command), which installs the tested version and verifies the toolchain. Docker and conda-lock bundle it. The forward predict_proxy_from_T is pure Python and needs no CmdStan. See Installation.

import TEXAS

# Download pre-computed posteriors from Zenodo (~0.3 MB for univariate)
TEXAS.download_posteriors(["tx.GHPU.sst.sri03.p0"])   # univariate SST calibration
# 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,
    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:

# Univariate SST posterior — ~0.3 MB
TEXAS.download_posteriors(["tx.GHPU.sst.sri03.p0"])

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["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/3 correction ──────────────────────
# 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
streamlit_app/      Drag-and-drop web interface (Streamlit)
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. Paleoceanography and Paleoclimatology, in press.

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.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for texas-psm 1.0.0
File Size Uploaded Provenance Actions
texas_psm-1.0.0.tar.gz 1.4 MB Without provenance Details for texas_psm-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for texas-psm 1.0.0
File Interpreter ABI Platform Actions
texas_psm-1.0.0-py3-none-any.whl Python 3 none any Details for texas_psm-1.0.0-py3-none-any.whl

Total release size: 2.6 MB

Release files / texas_psm-1.0.0.tar.gz

Download URL texas_psm-1.0.0.tar.gz
Size 1.4 MB
Tags Source
SHA-256 checksum
How to use checksums
3742028f38cd76667f046273c16b4241c4416721a1c923766f30fe8c99ef0524
BLAKE2b-256 checksum
How to use checksums
78ce9ee98731c651b57f02419cb001a7b91a9f5c4e6132b8ed1fce050f518437
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.20

Release files / texas_psm-1.0.0-py3-none-any.whl

Download URL texas_psm-1.0.0-py3-none-any.whl
Size 1.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
08a62c52b782bb9bb4bc592ad002f18e2117c786ae99ea15d86752f18c59f3a7
BLAKE2b-256 checksum
How to use checksums
1694e1942bac7a4637519ceaf48ec58e77818c72f388e77221ccf79d4a85687d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.20

Security for texas-psm 1.0.0

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page