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

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 CmdStan** (required before importing TEXAS):

```bash
pip install cmdstanpy
TBB_CXX_TYPE=gcc python -c "import cmdstanpy; cmdstanpy.install_cmdstan(version='2.36.0')"
```

**Step 3 — install TEXAS:**

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

=== “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 cmdstanpy
import cmdstanpy; cmdstanpy.install_cmdstan(version="2.36.0")
!pip install texas-psm
```

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

TEXAS searches for CmdStan in the following priority order:

Priority

Location

1

CMDSTAN environment variable (auto-set by conda; also honoured when set manually)

2

/opt/cmdstan/cmdstan-2.36.0

3

~/.cmdstan/cmdstan-2.36.0 — default target of cmdstanpy.install_cmdstan()

4

/usr/local/cmdstan/cmdstan-2.36.0

5

Whatever cmdstanpy is already configured to use

set_cmdstan_path() is always called on the winning path. If CMDSTAN is set but points to a broken directory, TEXAS emits a warning and continues down the list. If nothing is found, a RuntimeError is raised with explicit install instructions.

To use a specific CmdStan installation instead of the one conda manages:

export CMDSTAN=~/.cmdstan/cmdstan-2.36.0

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. If you installed CmdStan manually via cmdstanpy.install_cmdstan() and want to use that version instead:

export CMDSTAN=~/.cmdstan/cmdstan-2.36.0

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; for pip/uv see Option C), 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.