Installation

Installation#

TEXAS can be run via Docker (recommended) or installed directly with pip, uv, or conda.

Option

Best for

CmdStan handled for you?

A — Docker

Zero setup; reproducible; no Python/Stan toolchain to manage

✅ bundled in the image

B — conda-lock

Exact pinned reproducibility outside Docker

✅ bundled on all platforms

C — pip / uv

Lightweight installs into an existing Python/venv workflow

❌ one extra step (see below)

D — from source

Development (editable install)

❌ conda-managed or manual

CmdStan is never a Python package. Options A and B bundle it; options C and D require one extra step to install the CmdStan C++ toolchain (and, on a bare machine, a C++ compiler). This is a property of Stan itself — every model compiles to a native binary — not a limitation of pip or uv. See CmdStan: install, discovery, and verification.

Option B — conda-lock (exact reproducible environment)#

For the most reproducible setup outside of Docker, use the pre-solved conda-lock files published alongside this repository. Every package version and checksum is pinned — the environment will be identical on any machine of the same platform. CmdStan is bundled on all platforms — no separate install step needed.

!!! note “Windows — CmdStan version” CmdStan 2.35.0 is included on Windows (the latest version compatible with esmf on Windows). Linux and macOS get 2.36.0. The minor version difference has no effect on TEXAS.

With conda-lock (multi-platform lock file — recommended):

=== “Linux”

```bash
conda install -c conda-forge conda-lock
conda-lock install -n texas-env conda-lock.yml
conda activate texas-env
pip install texas-psm
```

=== “Windows (WSL2)”

Run from WSL2 terminal:

```bash
conda install -c conda-forge conda-lock
conda-lock install -n texas-env conda-lock.yml
conda activate texas-env
pip install texas-psm
```

=== “macOS (Apple Silicon)”

```bash
conda install -c conda-forge conda-lock
conda-lock install -n texas-env conda-lock.yml   # uses conda-osx-arm64.lock
conda activate texas-env
pip install texas-psm
```

=== “macOS (Intel)”

```bash
conda install -c conda-forge conda-lock
conda-lock install -n texas-env conda-lock.yml   # uses conda-osx-64.lock
conda activate texas-env
pip install texas-psm
```

Without conda-lock (platform-specific explicit file — works with plain conda):

# Pick the file for your platform
conda create -n texas-env --file conda-linux-64.lock    # Linux x86_64
conda create -n texas-env --file conda-osx-arm64.lock   # macOS Apple Silicon
conda create -n texas-env --file conda-osx-64.lock      # macOS Intel
conda create -n texas-env --file conda-win-64.lock      # Windows

conda activate texas-env
pip install texas-psm

Option C — pip install (Python users)#

!!! warning Do not run pip install against the system Python. Modern Debian/Ubuntu systems mark the system Python as externally managed (PEP 668) and will refuse the install. Always install into a virtual environment first.

=== “Linux / macOS / Windows (WSL2)”

Run from a bash terminal. For Windows, open your WSL2 terminal (not PowerShell or CMD).

**Step 1 — create and activate an isolated environment:**

```bash
conda create -n texas-env python=3.10 pip
conda activate texas-env
```

**Step 2 — install TEXAS:**

```bash
pip install texas-psm
```

**Step 3 — install CmdStan** (required before *sampling*; the one-call helper
installs the tested version and verifies it):

```bash
texas-install-cmdstan          # or, in Python: TEXAS.install_cmdstan()
```

Prefer to manage it manually? The equivalent low-level call is
`TBB_CXX_TYPE=gcc python -c "import cmdstanpy; cmdstanpy.install_cmdstan(version='2.36.0')"`.

=== “Windows (native Anaconda Prompt)”

Run all commands from the **Anaconda Prompt** (not PowerShell or CMD).

**Step 1 — create and activate an environment:**

```cmd
conda create -n texas-env python=3.10 pip
conda activate texas-env
```

**Step 2 — install CmdStan via conda-forge** (pre-built — no compiler needed):

```cmd
conda install -c conda-forge cmdstan=2.36.0
```

**Step 3 — install TEXAS:**

```cmd
pip install texas-psm
```

!!! warning "Windows-specific pitfalls"
    - Do **not** install `m2w64-toolchain` — it conflicts with the conda-forge `cmdstan` package.
    - Do **not** use `TBB_CXX_TYPE=gcc` — that is Linux/macOS syntax and will fail in CMD.
    - Do **not** run `cmdstanpy.install_cmdstan()` — the conda-forge package is pre-compiled; calling `install_cmdstan()` will try to compile from source and fail.

=== “Google Colab”

```python
!pip install texas-psm
import TEXAS
TEXAS.install_cmdstan()      # installs CmdStan to /root/.cmdstan and verifies
```

Colab runtimes are **ephemeral** — `/root/.cmdstan` is wiped when the runtime
resets or disconnects, so re-run `TEXAS.install_cmdstan()` once per new session.
It compiles CmdStan (~2–5 min) using Colab's preinstalled `g++`/`make`, and sets
`TBB_CXX_TYPE=gcc` for you.

Using uv instead of pip#

uv is a fast, drop-in replacement for pip/venv. TEXAS and all of its core dependencies are published on PyPI, so uv installs it with no extra configuration.

Standalone environment:

uv venv                       # create .venv/ with an isolated interpreter
source .venv/bin/activate
uv pip install cmdstanpy
python -c "import cmdstanpy; cmdstanpy.install_cmdstan(version='2.36.0')"
uv pip install texas-psm      # add extras as needed, e.g. "texas-psm[plotting]"

As a dependency of a uv-managed project:

uv add texas-psm              # or: uv add "texas-psm[plotting]"

Cloning the repo (contributor / notebook workflow):

To develop TEXAS or run the manuscript notebooks (notebooks/manuscripts/SI_code*.ipynb) from a checkout, let uv own a project .venv:

git clone --depth 1 https://github.com/PaleoLipidRR/TEXAS.git
cd TEXAS
uv sync --all-extras          # creates .venv/ and installs everything, incl. Jupyter + notebook deps

Then select .venv/bin/python as your notebook kernel (VS Code auto-detects it; for a named Jupyter kernel run uv run python -m ipykernel install --user --name texas-uv).

!!! tip “Which sync command?” - uv sync — core runtime only (no Jupyter). Cannot serve a notebook kernel. - uv sync --extra dev — adds Jupyter/ipykernel + the notebook analysis deps (scikit-learn, statsmodels, seaborn, openpyxl, odrpack). - uv sync --all-extras — the above plus plotting (ultraplot), maps (cartopy, regionmask), and regrid (geopandas, xesmf). Recommended for the SI notebooks.

!!! note “Python 3.12” uv on Python 3.12 is supported: the project pins a [tool.uv] override so pyproj resolves to a version with a 3.12 wheel (the regrid extra’s pyproj<3.6 cap has no 3.12 wheel and would otherwise force a source build). No action needed on your part.

!!! note “Optional extras under uv” - texas-psm[plotting] (ultraplot) and texas-psm[maps] (cartopy, regionmask) install cleanly from PyPI. - The regrid extra installs xesmf and the rest of the geo stack from PyPI, but esmpy (the ESMF bindings xesmf needs at runtime) is not on PyPI — install it from conda-forge: conda install -c conda-forge esmpy. (esmpy is deliberately kept out of the extra: a non-PyPI package in any extra makes uv lock fail for the whole project.) For heavy regridding, prefer the conda environment (Option D). - CmdStan is not a Python package — install it once via cmdstanpy.install_cmdstan() or conda-forge cmdstan, exactly as for the pip route above.

CmdStan: install, discovery, and verification#

CmdStan is the Stan C++ toolchain. It is never a Python package — pip/uv install cmdstanpy (the Python bindings), but the compiler itself is a separate directory (cmdstan-X.Y.Z/) containing bin/stanc and a Makefile. Every Stan model compiles to a native binary the first time it runs, so a working CmdStan and a C++ compiler must both be present.

The one-call install (pip / uv users)#

After pip install texas-psm (or uv add texas-psm), the simplest way to get CmdStan is:

import TEXAS
TEXAS.install_cmdstan()      # installs the tested version, verifies, and reports READY

Or from any shell (PowerShell, CMD, bash, zsh):

texas-install-cmdstan        # add --version X.Y.Z or --overwrite as needed

This installs the version TEXAS is tested against into ~/.cmdstan/, points TEXAS at it, runs the texas-doctor check, and — unlike a bare cmdstanpy.install_cmdstan() — repairs a broken/partial install in place (see Troubleshooting). It is a no-op if a working CmdStan already resolves, and it steps aside for conda-managed installs. On Windows it also installs the RTools C++ compiler as part of the call. TEXAS never installs CmdStan automatically — you always call this yourself.

The manual routes below (cmdstanpy.install_cmdstan(), conda-forge cmdstan) remain fully supported; use them if you prefer to manage the version yourself.

Where CmdStan lives#

Install route

CmdStan location

CMDSTAN set for you?

Docker / conda-lock / conda cmdstan

inside the conda env ($CONDA_PREFIX/…)

✅ by the env’s activation script

cmdstanpy.install_cmdstan()

~/.cmdstan/cmdstan-<version>/ (Windows: C:\Users\<you>\.cmdstan\…)

❌ discovered by TEXAS, but you can set it

Manual download

wherever you unpacked it

❌ set CMDSTAN yourself

How TEXAS discovers it#

TEXAS.utils.paths.find_cmdstan() searches, in order, and stops at the first directory that contains a runnable bin/stanc (stanc.exe on Windows):

Priority

Location

Typical source

1

CMDSTAN environment variable

conda activation, or set manually

2

$CONDA_PREFIX/bin/cmdstan

interactively-activated conda/mamba env

3

<python prefix>/bin/cmdstan

Docker/mamba where PATH was set but no activation script ran

4

highest cmdstan-* in /opt/cmdstan/, ~/.cmdstan/, /usr/local/cmdstan/

install_cmdstan() default (~/.cmdstan/)

5

whatever cmdstanpy is already configured to use

prior set_cmdstan_path()

set_cmdstan_path() is always called on the winning path so cmdstanpy stays consistent. Any version ≥ 2.23.0 is accepted (2.23.0 introduced reduce_sum); across the well-known directories the highest installed version wins. If CMDSTAN is set but its bin/stanc is missing or unusable, TEXAS emits a UserWarning and continues down the list. If nothing is found, a RuntimeError is raised with install instructions.

Setting CMDSTAN manually#

Use this to pin a specific install (e.g. the one install_cmdstan() created) instead of whatever conda manages. Set it before importing TEXAS.

=== “PowerShell (Windows)”

```powershell
# current session
$env:CMDSTAN = "$HOME\.cmdstan\cmdstan-2.36.0"
# persist across sessions
setx CMDSTAN "$HOME\.cmdstan\cmdstan-2.36.0"   # reopen the terminal to pick it up
# confirm
echo $env:CMDSTAN
```

=== “bash / zsh (Linux, macOS, WSL2)”

```bash
# current session
export CMDSTAN=~/.cmdstan/cmdstan-2.36.0
# persist: add the same line to ~/.bashrc or ~/.zshrc
# confirm
echo "$CMDSTAN"
```

=== “CMD / Anaconda Prompt (Windows)”

```cmd
set CMDSTAN=%USERPROFILE%\.cmdstan\cmdstan-2.36.0
echo %CMDSTAN%
```

Verify the whole toolchain#

One command checks cmdstanpy, the CmdStan path/version, a C++ compiler, and the cache directories — and tells you exactly what is missing. It runs on every platform and shell (PowerShell, CMD, bash, zsh):

texas-doctor            # or:  python -c "import TEXAS; TEXAS.doctor()"

A healthy machine prints Stan sampling: READY. If not, the report names the failure — including the case where CMDSTAN points at a directory whose bin/stanc was never built — and prints the exact fix for your platform. See Troubleshooting → CmdStan for the failure modes.

Option D — conda from source (development)#

git clone --depth 1 https://github.com/PaleoLipidRR/TEXAS.git
cd TEXAS
conda env create -f environment.yml
conda activate texas-env
pip install -e .          # editable install — required for development

Always use pip install -e . (editable mode). A plain pip install . or pip install texas-psm puts a static copy in site-packages: STAN_MODELS_DIR will point there (no pre-compiled binaries), and any local code changes will be silently ignored by the running kernel. After cloning, or any time you find the wrong package version is active, re-run pip install -e . and restart your Jupyter kernel.

The conda environment sets CMDSTAN automatically to the bundled CmdStan. To use a different install (e.g. one from cmdstanpy.install_cmdstan()), set CMDSTAN yourself — see Setting CMDSTAN manually for PowerShell / bash / CMD syntax — then run texas-doctor to confirm it resolved.

Reproducing the manuscript notebooks on a new machine#

The SI notebooks (notebooks/manuscripts/SI_code1–3) need more than the package: the Stan toolchain, cached posteriors, and some external climatology/model data. Full checklist:

1. Code + environment#

git clone https://github.com/PaleoLipidRR/TEXAS.git
cd TEXAS

  • conda (recommended for the notebooks — the tested stack): conda env create -f environment.yml && conda activate texas-env && pip install -e .. This pins matplotlib<3.5 and python=3.10, the versions the notebooks were authored against.

  • uv (lightweight): uv sync --all-extras. Newer stack (matplotlib 3.10, numpy 2, ultraplot 2.x) — a few notebook plotting idioms need the updated syntax the notebooks now use.

2. CmdStan + environment check#

Install CmdStan — Options A/B bundle it; pip/uv users get it in one call:

texas-install-cmdstan     # or, in Python: TEXAS.install_cmdstan()

Then verify everything at once:

texas-doctor      # or: python -c "import TEXAS; TEXAS.doctor()"

It reports cmdstanpy, the CmdStan path/version, a C++ compiler, and the cache dirs, and prints Stan sampling: READY when the machine is set up.

3. Posteriors + training data (Zenodo)#

import TEXAS
TEXAS.download_all()          # forward posteriors + training CSVs → data/cache/, data/spreadsheets/

4. External data (WOA23 + model fields) — manual, public sources#

The data/external/ folder (paleoDEMS plate model, Tierney22 / Zhu19 netCDFs) travels with the clone. Two datasets do not and must be fetched separately:

  • WOA23 climatology — World Ocean Atlas 2023, decadal average decav91C0, temperature and nitrate, 0.25° grid (files like woa23_decav91C0_t00_04.nc, woa23_decav91C0_n00_04.nc). Download from NOAA NCEI (https://www.ncei.noaa.gov/products/world-ocean-atlas) and place them so the notebook paths resolve (see step 5): …/WOA23/decav91C0/temperature/ and …/nitrate/.

5. Set the two path variables#

Each notebook’s setup cell defines local_github_path and local_onedrive_path. Point them at your clone and at wherever you placed the WOA23 / external datasets:

from pathlib import Path
local_github_path   = Path.home() / "Documents/GitHub/TEXAS"   # your clone
local_onedrive_path = Path.home() / "data/texas-external"      # where you put WOA23 etc.

Under Docker these default to /home/micromamba/app and /mnt/onedrive; on a bare machine adjust as above.

6. Run#

Select the texas-env (conda) or .venv (uv) kernel and run top-to-bottom.