Installation#

To use TEXAS on your own data, install the package from PyPI with pip or uv. That is all most users need, and the four bundled calibrations (the two defaults and their thermal-only counterparts) come with it. You do not need to clone the repository, or to download uv.lock or pyproject.toml: those files only work inside a full checkout, for people forking the repository or running the manuscript notebooks.

You want to

Use

CmdStan

Reconstruct temperatures from your own data

Option A — pip or uv

one command

Try TEXAS without installing anything

Google Colab

one call in the notebook

Fork the repository, or run the manuscript notebooks

Option B — uv from a clone or Option C — Docker

one command / bundled

Work in conda, with exact pinned versions

Option D — conda-lock or Option E — conda from source

bundled

CmdStan is never a Python package. Every Stan model compiles to a native binary, so pip and uv users install the CmdStan C++ toolchain once in a separate step (and, on a bare machine, a C++ compiler). See CmdStan: install, discovery, and verification.



Forking the repository or running the notebooks#

The options below all start from a clone, because they use files the PyPI package does not ship: the lock files, the notebooks and the Docker configuration. Editable installs matter here, so local code changes take effect. For the full list of what the manuscript notebooks need, see Reproducing the manuscript notebooks.

Option B — uv from a clone#

uv.lock pins every dependency, and uv sync installs them into a project .venv with TEXAS itself in editable mode:

git clone https://github.com/PaleoLipidRR/TEXAS.git    # or your fork
cd TEXAS
git lfs install && git lfs pull    # the training data and SI tables are LFS objects
uv sync --all-extras               # creates .venv/ with everything, incl. Jupyter + notebook deps
uv run texas-install-cmdstan

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

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, seaborn, openpyxl, pyarrow).

  • uv sync --all-extras — the above plus plotting (ultraplot, cmocean), maps (cartopy, regionmask, pykrige, joblib), and regrid (xesmf). Recommended for the SI notebooks.


Option C — Docker#

Docker bundles CmdStan, all Python dependencies, and the Stan compiler into a single image. No environment setup required.

Accounts you need before starting:

Service

Required?

Notes

Docker account

✅ Free account

Required to download and run Docker Desktop on Windows and macOS

GitHub

❌ No

Cloning and pulling the pre-built image are both anonymous

Zenodo

❌ No

Downloading posteriors is anonymous

Linux users

Docker Engine on Linux does not require a Docker account — install it directly via apt without signing in.

Step 1 — Install Docker#

Install Docker Engine and the Compose plugin:

# Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
    | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
    https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
    | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Add your user to the docker group so you can run Docker without sudo:

sudo usermod -aG docker $USER
newgrp docker

Verify the install:

docker info
docker compose version

TEXAS runs inside WSL2 (Windows Subsystem for Linux). Docker Desktop manages the bridge between Windows and WSL2.

1 — Install WSL2 (skip if already installed):

Open PowerShell as Administrator and run:

wsl --install

Restart your PC when prompted. This installs Ubuntu by default.

2 — Install Docker Desktop:

Download and install Docker Desktop for Windows.

During setup, ensure “Use the WSL 2 based engine” is selected.

3 — Enable WSL2 integration:

Open Docker Desktop → Settings → Resources → WSL Integration → enable integration for your distro (e.g. Ubuntu).

4 — Verify from WSL2 terminal:

Open your WSL2 distro (Ubuntu) and run:

docker info
docker compose version

If these fail, restart Docker Desktop and try again.

Download and install Docker Desktop for Mac.

  • Apple Silicon (M1/M2/M3): choose the Apple Silicon installer.

  • Intel: choose the Intel chip installer.

After installing, launch Docker Desktop from Applications and wait for it to show “Docker Desktop is running” in the menu bar.

Verify:

docker info
docker compose version

Apple Silicon performance

The pre-built image is linux/amd64. On Apple Silicon it runs under QEMU emulation — Stan compilation and sampling will be noticeably slower. For repeated use, Option A (pip or uv) in a native arm64 Python environment is faster.

macOS — Docker permissions prompt

On first run, macOS may ask whether Docker Desktop can access your Documents or Downloads folder. Click Allow. If you dismiss it, the volume mount will silently fail and JupyterLab will show an empty file browser — re-run ./run.sh and allow access when prompted.


Step 2 — Clone the repository#

New to git?

git clone downloads a copy of the TEXAS code to your own computer — think of it like downloading a folder. You cannot accidentally break or modify the original repository. Everything runs locally on your machine.

A shallow clone (--depth 1) is recommended — it downloads only the current state of the code without the full commit history, saving several GB of disk space.

git clone --depth 1 https://github.com/PaleoLipidRR/TEXAS.git
cd TEXAS
chmod +x run.sh

Open your WSL2 terminal (e.g. Ubuntu) and run:

git clone --depth 1 https://github.com/PaleoLipidRR/TEXAS.git
cd TEXAS
chmod +x run.sh

Note

Clone inside the WSL2 filesystem (e.g. ~/Documents/GitHub/) — not on the Windows filesystem (/mnt/c/...). Cloning into /mnt/c/ causes slow I/O and file permission issues inside the container.

git clone --depth 1 https://github.com/PaleoLipidRR/TEXAS.git
cd TEXAS
chmod +x run.sh

Step 3 — Launch#

Run the interactive launcher:

./run.sh

You will be prompted to:

Prompt

Recommended answer

Which profile?

full — JupyterLab with Stan

Mount Google Drive / OneDrive?

y if your data is there, otherwise n

Pull pre-built image from GHCR?

Y — downloads ~2–3 GB, no build required

Once the image is pulled and the container starts, open http://localhost:8890 in your browser.

Port 8890, not 8888

run.sh uses port 8890 to avoid conflicts with any native JupyterLab or Anaconda installation that may already be running on port 8888 — common on Windows and macOS with Anaconda installed. The JupyterLab startup log will print http://127.0.0.1:8890/lab — use that URL.

Windows/WSL2 — kernel selector on first open

When you open a notebook for the first time in the Docker container, JupyterLab may show a kernel name like SI_code00_PreProcessing.ipynb (3bf86915) in the kernel selection dialog instead of “Python 3”. This is a leftover preference saved inside the .ipynb file from a previous session on a different machine. Click the dropdown, select Python 3 (ipykernel), and click Select — it will work normally after that.

Disk space — plan for ~3.5 GB total

Component

Size

Location

Git clone (tracked files)

~624 MB

Where you cloned

Docker image — base OS + system libs

~300 MB

Docker’s internal storage

Docker image — conda env (Python stack + JupyterLab)

~1.2 GB

Docker’s internal storage

Docker image — CmdStan 2.36.0 (compiled C++ toolchain)

~400 MB

Docker’s internal storage

Posteriors downloaded from Zenodo

~475 MB

data/cache/ inside the clone

Total

~2.8–3.5 GB

The Docker image is stored in Docker’s internal storage — not inside the cloned repo folder. On Windows, Docker Desktop uses a VHDX virtual disk that grows over time. To reclaim space later: Docker Desktop → Troubleshoot → Clean / Purge data, or run:

docker image rm ghcr.io/paleolipidrr/texas:latest

Subsequent launches after the first pull start in seconds — no re-download needed.


Downloading posteriors#

The four bundled calibrations ship inside the package, so reconstructions work without a download. The full set of forward calibration posteriors (.nc files, ~475 MB) is stored on Zenodo and is not included in the Docker image or the repository. Download it once inside JupyterLab:

import TEXAS
TEXAS.download_all()

This saves posteriors to data/cache/TEXAS_posterior_cache/ inside the cloned repo, which is bind-mounted into the container — so they persist across sessions.

To check exactly where files were saved, or to list downloaded posteriors:

from TEXAS.utils.paths import POSTERIOR_CACHE_DIR, SPREADSHEETS_DIR

print("Posteriors:", POSTERIOR_CACHE_DIR)
print("Training data:", SPREADSHEETS_DIR)

# List all downloaded posteriors
list(POSTERIOR_CACHE_DIR.glob("*.nc"))

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

For the most reproducible setup outside of Docker, use the pre-solved conda-lock files published alongside this repository. Run these commands from a clone. 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.

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

conda install -c conda-forge conda-lock
conda-lock install -n texas-env conda-lock.yml
conda activate texas-env
pip install -e .

Run from WSL2 terminal:

conda install -c conda-forge conda-lock
conda-lock install -n texas-env conda-lock.yml
conda activate texas-env
pip install -e .
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 -e .
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 -e .

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

Option E — 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_code00–SI_code03) 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
  • uv: uv sync --all-extras (Option B). Newer stack (matplotlib 3.10, numpy 2, ultraplot 2.x); the notebooks use the updated plotting syntax it needs.

  • Docker: docker compose up (Option C). Everything is bundled.

  • conda: conda env create -f environment.yml && conda activate texas-env && pip install -e . (Option E). This pins matplotlib>=3.9,<3.11 and python=3.10, the versions the notebooks were authored against.

2. CmdStan + environment check#

Install CmdStan — Docker and conda bundle it; 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) — public sources#

data/external/ is gitignored, so these do not come with the clone:

  • Regridded model fields and plate model — the Tierney et al. (2022) and Zhu et al. (2019) netCDFs and the paleoDEMS plate model, read by SI_code03 for Fig. 12. They are being added to the Zenodo data record; until then that figure cannot be regenerated from public files alone.

  • WOA23 climatology — World Ocean Atlas 2023 annual means: temperature, decadal average decav91C0, 0.25° and 1° (woa23_decav91C0_t00_04.nc, woa23_decav91C0_t00_01.nc), and nitrate, all-years 1° (woa23_all_n00_01.nc). TEXAS.download_woa23() fetches all three from NOAA NCEI (>1 GB) into data/external/woa23/; or download them from https://www.ncei.noaa.gov/products/world-ocean-atlas. 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 .venv (uv) or texas-env (conda) kernel and run top-to-bottom.