Skip to main content

TEXAS — TetraEther indeX of Ammonia oxidizerS: a proxy system model for TEX₈₆ paleothermometry

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

# 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)

Source distribution for texas-psm 1.0.2
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)

Table of built distributions (wheels) for texas-psm 1.0.2
File Interpreter ABI Platform Actions
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.

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