texas-psm 0.1.0__tar.gz

texas_psm-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: texas-psm
+Version: 0.1.0
+Summary: Bayesian GDGT–temperature utilities
+Author-email: Ronnakrit Rattanasriampaipong <rattanasriampaipong.r@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PaleoLipidRR/TEXAS
+Project-URL: Bug Tracker, https://github.com/PaleoLipidRR/TEXAS/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.18
+Requires-Dist: xarray>=0.16
+Requires-Dist: cmdstanpy>=1.0
+Requires-Dist: typing-extensions>=3.7.4
+Requires-Dist: scipy>=1.7
+Requires-Dist: pandas>=1.3
+Requires-Dist: baysparpy>=0.0.2
+Requires-Dist: baysplinepy>=0.0.1
+Requires-Dist: stanio>=0.4
+Provides-Extra: plotting
+Requires-Dist: matplotlib>=3.5; extra == "plotting"
+Requires-Dist: proplot==0.9.7; extra == "plotting"
+Requires-Dist: cmocean; extra == "plotting"
+Requires-Dist: setuptools<81; extra == "plotting"
+Requires-Dist: plotly; extra == "plotting"
+Provides-Extra: dev
+Requires-Dist: ipykernel; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mkdocs; extra == "dev"
+Requires-Dist: jupyterlab; extra == "dev"
+Requires-Dist: ipywidgets; extra == "dev"
+Requires-Dist: tqdm; extra == "dev"
+Requires-Dist: anywidget; extra == "dev"
+Requires-Dist: ipylab; extra == "dev"
+Requires-Dist: duckdb; extra == "dev"
+Requires-Dist: pyarrow; extra == "dev"
+Requires-Dist: sqlalchemy; extra == "dev"
+Requires-Dist: pydantic; extra == "dev"
+Provides-Extra: regrid
+Requires-Dist: geopandas; extra == "regrid"
+Requires-Dist: shapely; extra == "regrid"
+Requires-Dist: cartopy; extra == "regrid"
+Requires-Dist: pyproj<3.6; extra == "regrid"
+Requires-Dist: rtree; extra == "regrid"
+Requires-Dist: pyogrio; extra == "regrid"
+Requires-Dist: mapclassify; extra == "regrid"
+Requires-Dist: geopy; extra == "regrid"
+Requires-Dist: xesmf; extra == "regrid"
+Requires-Dist: esmpy; extra == "regrid"
+Requires-Dist: gsw>=3.3; extra == "regrid"
+Provides-Extra: all
+Requires-Dist: texas-psm[plotting]; extra == "all"
+Requires-Dist: texas-psm[dev]; extra == "all"
+Requires-Dist: texas-psm[regrid]; extra == "all"
+
+# TEXAS — Temperature Estimation via a Bayesian Approach with Stan
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
+
+**TEXAS** (`texas-psm`) is a Python package for **Bayesian GDGT–temperature calibration**. It fits hierarchical generalized-logistic models to isoGDGT proxy data (TEX86 / Ring Index) using Stan, then reconstructs paleotemperatures from new sediment records with full posterior uncertainty.
+
+---
+
+## What it does
+
+TEXAS implements a two-stage workflow:
+
+| Stage | Description |
+|---|---|
+| **Forward calibration** | Fit a generalized logistic curve (Ring Index → 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 new Ring Index observations by marginalizing over posterior parameter draws. Returns a full posterior temperature distribution per sample. |
+
+Optional non-thermal corrections for GDGT-2/3 ratio and NO₃ concentration are supported.
+
+---
+
+## Getting started
+
+### Option A — No-code: Streamlit web app
+
+Upload a CSV and get paleotemperature reconstructions in your browser — no Python or Stan installation required.
+
+> **Streamlit deployment coming soon.**
+
+The app accepts a CSV with Ring Index columns and returns downloadable posterior temperature estimates with uncertainty.
+
+---
+
+### Option B — Docker (recommended for reproducibility)
+
+No Stan setup required — CmdStan and all dependencies are pre-installed.
+
+```bash
+# Clone the repo
+git clone https://github.com/PaleoLipidRR/TEXAS.git
+cd TEXAS
+
+# Build and start the container
+docker compose up
+```
+
+Then open JupyterLab at `http://localhost:8888` and run the notebooks in `notebooks/manuscripts/`.
+
+> **Pre-built image on GHCR coming soon.** Until then, the image is built locally from `docker/Dockerfile`.
+
+---
+
+### Option C — pip install (Python users)
+
+```bash
+pip install texas-psm
+```
+
+**One-time CmdStan install** (required; sets a flag for the conda C++ compiler on Linux/macOS):
+
+```bash
+TBB_CXX_TYPE=gcc python -c "import cmdstanpy; cmdstanpy.install_cmdstan(version='2.36.0')"
+```
+
+TEXAS will search for CmdStan in `~/.cmdstan/`, `/opt/cmdstan/`, or the `CMDSTAN` environment variable.
+
+---
+
+### Option D — conda + pip from source (for development)
+
+```bash
+git clone https://github.com/PaleoLipidRR/TEXAS.git
+cd TEXAS
+
+conda env create -f environment.yml
+conda activate texas-env
+
+pip install -e .
+```
+
+Then install CmdStan as shown in Option C above.
+
+---
+
+## Example usage
+
+```python
+import numpy as np
+from TEXAS import predict_RI_from_T, predict_T_from_RI
+from TEXAS.stan.sampler import get_posterior
+from TEXAS.stan.io import save_posterior
+
+# 1. Forward calibration — fit logistic curve to training data
+posterior, diagnostics = get_posterior(
+    data,
+    model_name="gen_logi_fixed_hier_crtp_multiv",
+    temptype="SST",
+)
+save_posterior(posterior)
+
+# 2. Forward prediction — evaluate the calibration curve at 20–30 °C
+result = predict_RI_from_T(
+    temperatures=np.linspace(20, 30, 50),
+    posterior="gen_logi_fixed_hier_crtp_multiv_SST",
+)
+result["p50"]   # median calibration curve
+
+# 3. Inverse reconstruction — predict temperature from new Ring Index observations
+result = predict_T_from_RI(
+    scaledRI=my_ri_array,
+    prior_mu_t=15.0,        # prior mean temperature (°C)
+    prior_sigma_t=10.0,     # prior uncertainty (°C)
+    fwd_posterior_name="gen_logi_fixed_hier_crtp_multiv_SST",
+    temptype="SST",
+)
+result["p50"]   # median temperature reconstruction (°C)
+result["p5"]    # 5th percentile
+result["p95"]   # 95th percentile
+```
+
+---
+
+## Repository layout
+
+```
+src/TEXAS/
+  predict.py        High-level API: predict_RI_from_T / predict_T_from_RI
+  stan/             Sampler, compiler, I/O, and invT orchestration
+  stan_models/      Stan model files (.stan)
+  data/             Input data builders, filters, and screening
+  ensemble/         Posterior ensemble generation and model detection
+  models/           Logistic curve functions and classical calibrations
+  plotting/         Prior/posterior distribution plots and range utilities
+  utils/            Path constants, system info
+notebooks/
+  manuscripts/      Finalized analysis notebooks for the paper
+streamlit_app/      Drag-and-drop web interface (Streamlit)
+docker/             Dockerfile and compose configuration
+docs/               MkDocs documentation source
+```
+
+---
+
+## API at a glance
+
+| Function | Description |
+|---|---|
+| `predict_RI_from_T(temperatures, posterior, ...)` | Forward prediction: temperature → Ring Index (pure Python, wraps `generate_ensemble_auto`) |
+| `predict_T_from_RI(scaledRI, prior_mu_t, prior_sigma_t, fwd_posterior_name, ...)` | Inverse reconstruction: Ring Index → temperature with full posterior uncertainty (runs Stan) |
+| `get_posterior(data, model_name, temptype, ...)` | Run forward calibration Stan sampling |
+| `save_posterior(ds)` / `load_posterior(name)` | Persist / load forward posterior as compressed NetCDF |
+| `get_invT_posterior(...)` | Run inverse-T sampling and return full posterior xr.Dataset |
+| `predict_temperature_from_RI(...)` | Run inverse-T and return `{p5, p50, p95, scaledRI, metadata}` |
+| `generate_ensemble_auto(temperatures, posterior, ...)` | Sample draws from a posterior and compute calibration-curve percentiles |
+| `summarize_sampler_diagnostics(fit)` | Compute divergences, R-hat, ESS, E-BFMI from a CmdStanMCMC fit |
+| `plot_prior_distributions(posterior)` | Plot prior distributions from posterior metadata |
+
+Full API reference: [https://paleolipidRR.github.io/TEXAS](https://paleolipidRR.github.io/TEXAS) *(coming soon)*
+
+---
+
+## Documentation
+
+Full API reference and method details: [https://paleolipidRR.github.io/TEXAS](https://paleolipidRR.github.io/TEXAS) *(coming soon)*
+
+---
+
+## Citation
+
+If you use TEXAS in your research, please cite:
+
+> Rattanasriampaipong, R. et al. (in prep). *TEXAS: Bayesian GDGT–temperature calibration using Stan.* AGU Paleoceanography and Paleoclimatology.
+
+A `CITATION.cff` and software DOI will be added upon submission.
+
+---
+
+## License
+
+MIT © Ronnakrit Rattanasriampaipong

texas_psm-0.1.0/README.md

@@ -0,0 +1,181 @@
+# TEXAS — Temperature Estimation via a Bayesian Approach with Stan
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
+
+**TEXAS** (`texas-psm`) is a Python package for **Bayesian GDGT–temperature calibration**. It fits hierarchical generalized-logistic models to isoGDGT proxy data (TEX86 / Ring Index) using Stan, then reconstructs paleotemperatures from new sediment records with full posterior uncertainty.
+
+---
+
+## What it does
+
+TEXAS implements a two-stage workflow:
+
+| Stage | Description |
+|---|---|
+| **Forward calibration** | Fit a generalized logistic curve (Ring Index → 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 new Ring Index observations by marginalizing over posterior parameter draws. Returns a full posterior temperature distribution per sample. |
+
+Optional non-thermal corrections for GDGT-2/3 ratio and NO₃ concentration are supported.
+
+---
+
+## Getting started
+
+### Option A — No-code: Streamlit web app
+
+Upload a CSV and get paleotemperature reconstructions in your browser — no Python or Stan installation required.
+
+> **Streamlit deployment coming soon.**
+
+The app accepts a CSV with Ring Index columns and returns downloadable posterior temperature estimates with uncertainty.
+
+---
+
+### Option B — Docker (recommended for reproducibility)
+
+No Stan setup required — CmdStan and all dependencies are pre-installed.
+
+```bash
+# Clone the repo
+git clone https://github.com/PaleoLipidRR/TEXAS.git
+cd TEXAS
+
+# Build and start the container
+docker compose up
+```
+
+Then open JupyterLab at `http://localhost:8888` and run the notebooks in `notebooks/manuscripts/`.
+
+> **Pre-built image on GHCR coming soon.** Until then, the image is built locally from `docker/Dockerfile`.
+
+---
+
+### Option C — pip install (Python users)
+
+```bash
+pip install texas-psm
+```
+
+**One-time CmdStan install** (required; sets a flag for the conda C++ compiler on Linux/macOS):
+
+```bash
+TBB_CXX_TYPE=gcc python -c "import cmdstanpy; cmdstanpy.install_cmdstan(version='2.36.0')"
+```
+
+TEXAS will search for CmdStan in `~/.cmdstan/`, `/opt/cmdstan/`, or the `CMDSTAN` environment variable.
+
+---
+
+### Option D — conda + pip from source (for development)
+
+```bash
+git clone https://github.com/PaleoLipidRR/TEXAS.git
+cd TEXAS
+
+conda env create -f environment.yml
+conda activate texas-env
+
+pip install -e .
+```
+
+Then install CmdStan as shown in Option C above.
+
+---
+
+## Example usage
+
+```python
+import numpy as np
+from TEXAS import predict_RI_from_T, predict_T_from_RI
+from TEXAS.stan.sampler import get_posterior
+from TEXAS.stan.io import save_posterior
+
+# 1. Forward calibration — fit logistic curve to training data
+posterior, diagnostics = get_posterior(
+    data,
+    model_name="gen_logi_fixed_hier_crtp_multiv",
+    temptype="SST",
+)
+save_posterior(posterior)
+
+# 2. Forward prediction — evaluate the calibration curve at 20–30 °C
+result = predict_RI_from_T(
+    temperatures=np.linspace(20, 30, 50),
+    posterior="gen_logi_fixed_hier_crtp_multiv_SST",
+)
+result["p50"]   # median calibration curve
+
+# 3. Inverse reconstruction — predict temperature from new Ring Index observations
+result = predict_T_from_RI(
+    scaledRI=my_ri_array,
+    prior_mu_t=15.0,        # prior mean temperature (°C)
+    prior_sigma_t=10.0,     # prior uncertainty (°C)
+    fwd_posterior_name="gen_logi_fixed_hier_crtp_multiv_SST",
+    temptype="SST",
+)
+result["p50"]   # median temperature reconstruction (°C)
+result["p5"]    # 5th percentile
+result["p95"]   # 95th percentile
+```
+
+---
+
+## Repository layout
+
+```
+src/TEXAS/
+  predict.py        High-level API: predict_RI_from_T / predict_T_from_RI
+  stan/             Sampler, compiler, I/O, and invT orchestration
+  stan_models/      Stan model files (.stan)
+  data/             Input data builders, filters, and screening
+  ensemble/         Posterior ensemble generation and model detection
+  models/           Logistic curve functions and classical calibrations
+  plotting/         Prior/posterior distribution plots and range utilities
+  utils/            Path constants, system info
+notebooks/
+  manuscripts/      Finalized analysis notebooks for the paper
+streamlit_app/      Drag-and-drop web interface (Streamlit)
+docker/             Dockerfile and compose configuration
+docs/               MkDocs documentation source
+```
+
+---
+
+## API at a glance
+
+| Function | Description |
+|---|---|
+| `predict_RI_from_T(temperatures, posterior, ...)` | Forward prediction: temperature → Ring Index (pure Python, wraps `generate_ensemble_auto`) |
+| `predict_T_from_RI(scaledRI, prior_mu_t, prior_sigma_t, fwd_posterior_name, ...)` | Inverse reconstruction: Ring Index → temperature with full posterior uncertainty (runs Stan) |
+| `get_posterior(data, model_name, temptype, ...)` | Run forward calibration Stan sampling |
+| `save_posterior(ds)` / `load_posterior(name)` | Persist / load forward posterior as compressed NetCDF |
+| `get_invT_posterior(...)` | Run inverse-T sampling and return full posterior xr.Dataset |
+| `predict_temperature_from_RI(...)` | Run inverse-T and return `{p5, p50, p95, scaledRI, metadata}` |
+| `generate_ensemble_auto(temperatures, posterior, ...)` | Sample draws from a posterior and compute calibration-curve percentiles |
+| `summarize_sampler_diagnostics(fit)` | Compute divergences, R-hat, ESS, E-BFMI from a CmdStanMCMC fit |
+| `plot_prior_distributions(posterior)` | Plot prior distributions from posterior metadata |
+
+Full API reference: [https://paleolipidRR.github.io/TEXAS](https://paleolipidRR.github.io/TEXAS) *(coming soon)*
+
+---
+
+## Documentation
+
+Full API reference and method details: [https://paleolipidRR.github.io/TEXAS](https://paleolipidRR.github.io/TEXAS) *(coming soon)*
+
+---
+
+## Citation
+
+If you use TEXAS in your research, please cite:
+
+> Rattanasriampaipong, R. et al. (in prep). *TEXAS: Bayesian GDGT–temperature calibration using Stan.* AGU Paleoceanography and Paleoclimatology.
+
+A `CITATION.cff` and software DOI will be added upon submission.
+
+---
+
+## License
+
+MIT © Ronnakrit Rattanasriampaipong

texas_psm-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "texas-psm"
+version = "0.1.0"
+authors = [{ name = "Ronnakrit Rattanasriampaipong", email = "rattanasriampaipong.r@gmail.com" }]
+description = "Bayesian GDGT–temperature utilities"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+dependencies = [
+  "numpy>=1.18",
+  "xarray>=0.16",
+  "cmdstanpy>=1.0",
+  "typing-extensions>=3.7.4",
+  "scipy>=1.7",
+  "pandas>=1.3",
+  "baysparpy>=0.0.2",
+  "baysplinepy>=0.0.1",
+  "stanio>=0.4"
+]
+
+[project.optional-dependencies]
+plotting = [
+    "matplotlib>=3.5",
+    "proplot==0.9.7",
+    "cmocean",
+    "setuptools<81",
+    "plotly"
+]
+
+dev = [
+  "ipykernel",
+  "pytest",
+  "mkdocs",
+  "jupyterlab",
+  "ipywidgets",
+  "tqdm",
+  "anywidget",
+  "ipylab",
+  "duckdb",
+  "pyarrow",
+  "sqlalchemy",
+  "pydantic"
+]
+
+regrid = [
+  "geopandas",
+  "shapely",
+  "cartopy",
+  "pyproj<3.6",
+  "rtree",
+  "pyogrio",
+  "mapclassify",
+  "geopy",
+  "xesmf",
+  "esmpy",
+  "gsw>=3.3"
+]
+
+all = [
+  "texas-psm[plotting]",
+  "texas-psm[dev]",
+  "texas-psm[regrid]"
+]
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["TEXAS*"]
+
+[tool.setuptools.package-data]
+TEXAS = ["stan_models/*.stan"]
+
+[project.urls]
+"Homepage" = "https://github.com/PaleoLipidRR/TEXAS"
+"Bug Tracker" = "https://github.com/PaleoLipidRR/TEXAS/issues"
+
+[tool.conda-lock.dependencies]
+pip = [
+    "pygwalker"
+]

texas_psm-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

texas_psm-0.1.0/src/TEXAS/__init__.py

@@ -0,0 +1,92 @@
+# TEXAS/__init__.py
+
+__version__ = "0.1.0"
+
+# ─── Stan interface ──────────────────────────────────────────────────────
+from .stan.compiler import StanCompiler
+from .stan.sampler import (
+    StanSampler,
+    get_posterior,
+    sampler_invT_posterior,
+)
+from .stan.io import (
+    load_posterior,
+    save_posterior,
+    save_invT_posterior,
+)
+from .stan.invT import get_invT_posterior, predict_temperature_from_RI
+from .predict import predict_RI_from_T, predict_T_from_RI
+
+# ─── Data builder for inverse‐T models ──────────────────────────────────
+from .data.builder import build_invT_inputData, InvTConfig
+
+# ─── Pure-Python logistic helpers ───────────────────────────────────────
+from .models.logistics import (
+    logistic,
+    logistic_fixed_upper,
+    inverse_logistic_fixed_upper,
+    generalized_logistic,
+    generalized_logistic_fixed_upper,
+)
+from .models.multivariate import (
+    generalized_logistic_fixed_upper_multivariate,
+    simple_logistic_fixed_upper_multivariate,
+)
+
+# ─── Ensemble generation ────────────────────────────────────────────────
+from .ensemble.generator import generate_ensemble, generate_ensemble_auto
+from .ensemble.detection import detect_model_and_params
+
+# ─── Diagnostics utilities ─────────────────────────────────────────────
+from .diagnostics import summarize_sampler_diagnostics, create_summary_table
+
+# ─── Plotting / dataviz ─────────────────────────────────────────────────
+from .plotting import (
+    compute_sample_range,
+    compute_density_based_range,
+    compute_suffix_specific_range,
+    compute_dataset_specific_range,
+    plot_prior_distributions,
+)
+
+__all__ = [
+    # version
+    "__version__",
+    # stan — calibration
+    "StanCompiler",
+    "StanSampler",
+    "get_posterior",
+    "load_posterior",
+    "save_posterior",
+    "save_invT_posterior",
+    # stan — inverse temperature
+    "get_invT_posterior",
+    "predict_temperature_from_RI",
+    # high-level prediction API
+    "predict_RI_from_T",
+    "predict_T_from_RI",
+    # data builder
+    "build_invT_inputData",
+    "InvTConfig",
+    # models — logistic curves
+    "logistic",
+    "logistic_fixed_upper",
+    "inverse_logistic_fixed_upper",
+    "generalized_logistic",
+    "generalized_logistic_fixed_upper",
+    "generalized_logistic_fixed_upper_multivariate",
+    "simple_logistic_fixed_upper_multivariate",
+    # ensemble
+    "generate_ensemble",
+    "generate_ensemble_auto",
+    "detect_model_and_params",
+    # diagnostics
+    "summarize_sampler_diagnostics",
+    "create_summary_table",
+    # plotting
+    "compute_sample_range",
+    "compute_density_based_range",
+    "compute_suffix_specific_range",
+    "compute_dataset_specific_range",
+    "plot_prior_distributions",
+]

texas_psm-0.1.0/src/TEXAS/constants.py

@@ -0,0 +1,19 @@
+# TEXAS/constants.py
+
+# Optional predictors
+OPTIONAL_PREDICTORS = ["gdgt23ratio", "no3"]
+
+# Suffixes for logistic model parameter variants
+DEFAULT_SUFFIXES = ["crtp", "culmesocore", "culmeso", "meso", "cul", "downcore"]
+
+# Maps predictor data-variable name → Stan/posterior coefficient name
+PREDICTOR_BETA_NAMES = {
+    "gdgt23ratio": "beta_G23",
+    "no3": "beta_NO3",
+}
+
+# Stan direct keys (if used across multiple places)
+DIRECT_KEYS = ["scaledRI", "prior_mu_t", "prior_sigma_t",
+    "calibration_model_name", "N_cul", "N_meso", "N_crtp", "N",
+    "prior_mu_t", "prior_sigma_t", "M"
+]

texas_psm-0.1.0/src/TEXAS/data/__init__.py

@@ -0,0 +1,20 @@
+# TEXAS/data/__init__.py
+
+from .builder import (
+    build_invT_inputData,
+    InvTConfig
+)
+from .filter import (
+    filter_stan_compatible,
+    ensure_numpy,
+)
+
+from .screening import MahalanobisOutlierDetector
+
+__all__ = [
+    "build_invT_inputData",
+    "InvTConfig",
+    "filter_stan_compatible",
+    "ensure_numpy",
+    'MahalanobisOutlierDetector'
+]