Environment Setup¶

pyCyto uses pixi for reproducible, multi-environment dependency management. A single pixi.toml at the repo root defines all environments — no conda env files required.

Table of Contents¶

Quick Start (pixi)
Available Environments
Running with an Environment
Fiji / TrackMate Setup
- Option A: Auto-download via PyImageJ (recommended)
- Option B: Pre-installed Fiji
Apptainer / Singularity (HPC)
Troubleshooting
Legacy: mamba / conda

Quick Start (pixi)¶

# 1. Install pixi (once, per user)
curl -fsSL https://pixi.sh/install.sh | bash
# Restart your shell or: source ~/.bashrc

# 2. Clone the repository
git clone git@github.com:bpi-oxford/Cytotoxicity-Pipeline.git
cd Cytotoxicity-Pipeline

# 3. Install all environments
pixi install            # default CPU environment
pixi install -e cellpose
pixi install -e stardist
pixi install -e imagej
pixi install -e gpu

Available Environments¶

Environment	Key contents	Use case
`default`	JupyterLab, Dask, analysis stack, Sphinx docs	Notebooks, pipeline, documentation
`cellpose`	PyTorch, Cellpose ≥ 4, CUDA 11.8	GPU segmentation
`stardist`	TensorFlow 2.12, StarDist	StarDist segmentation
`imagej`	PyImageJ, OpenJDK 11	TrackMate / Fiji integration
`gpu`	Cellpose + TrackMate combined	Full GPU tracking pipeline
`preprocessing`	antspyx (ANTs), scikit-image	Image registration and denoising
`rapids`	dask-cuda, RAPIDS	GPU-accelerated data processing

Running with an Environment¶

# Run a script in the default environment
pixi run python scripts/my_script.py

# Run in a specific environment
pixi run -e cellpose python scripts/batch_segmentation.py

# Start JupyterLab (default environment)
pixi run jupyter

# Start JupyterLab (GPU environment)
pixi run -e gpu jupyter

Fiji / TrackMate Setup¶

Fiji is required for TrackMate-based cell tracking (cyto.tracking.trackmate). There are two options:

Option A: Auto-download via PyImageJ (recommended)¶

PyImageJ can download and cache a full Fiji distribution automatically on first use. No manual installation needed:

import imagej
ij = imagej.init('sc.fiji:fiji')   # downloads ~500 MB once, caches in ~/.jgo and ~/.m2

On shared NFS filesystems (e.g., HPC clusters), warm the cache once on the login node so compute nodes can reuse it:

pixi run -e imagej python -c "import imagej; imagej.init('sc.fiji:fiji')"

Set fiji_dir = "" in your pipeline YAML or benchmark.user.toml to use this mode.

Option B: Pre-installed Fiji¶

Download Fiji and install the TrackMate CSV Importer plugin:

# Download and unzip Fiji
wget https://downloads.micron.ox.ac.uk/fiji_update/mirrors/fiji-latest/fiji-linux64.zip
unzip fiji-linux64.zip -d /opt/
rm fiji-linux64.zip

# Install the TrackMate CSV Importer update site
/opt/Fiji.app/ImageJ-linux64 --headless --ij2 --update add-update-site \
    TrackMateCSVImporter https://sites.imagej.net/TrackMateCSVImporter/
/opt/Fiji.app/ImageJ-linux64 --headless --ij2 --update update

TrackMate CSV Importer enables loading pre-computed spot CSVs (from pyCyto’s tabulation stage) directly into TrackMate without re-running detection. Plugin page: https://imagej.net/plugins/trackmate/extensions/csv-importer

Then set fiji_dir in your pipeline config:

# In pipeline YAML or benchmark.user.toml
[trackmate]
fiji_dir = "/opt/Fiji.app"

Apptainer / Singularity (HPC)¶

For reproducible HPC execution, pyCyto provides Apptainer (formerly Singularity) container images. This is the recommended approach for production benchmark runs.

# Build the GPU image (from repo root, requires Apptainer on the build node)
bash containers/apptainer/build.sh

# Run a script inside the container
apptainer exec --nv containers/images/cyto-gpu.sif \
    pixi run -e gpu python scripts/benchmark/run_benchmark.py

See Containerized Execution for the full container guide.

Troubleshooting¶

MPI (cluster jobs)¶

mpi4py is installed from conda-forge (OpenMPI). For cluster jobs requiring the system MPI:

module load mpi
pixi run pip install --no-binary mpi4py mpi4py

CUDA library conflicts¶

If you see CUDA/CuDNN version mismatch errors:

pixi run -e cellpose python -c "import torch; print(torch.cuda.is_available())"
# Should print: True

If not, ensure the cluster module environment is clean before running pixi (module purge may help).

Import errors for optional dependencies¶

pyCyto guards optional heavy dependencies with try/except in cyto/__init__.py. If you see ImportError for pyclesperanto, ants, or similar, install the relevant pixi environment and run with pixi run -e <env>.

Legacy: mamba / conda¶

Deprecated. The env.yaml / envs/env-*.yaml conda files are no longer maintained. Use pixi environments instead.

If you have an existing conda-based install and cannot migrate:

# Legacy (not recommended)
mamba env create -f env.yaml
mamba activate cyto

No support is provided for conda-based setups. All new features and dependency updates target pixi only.