🧬 Analysis Template

A notebook-first template for single-cell/spatial analysis projects. Uses pixi for environment management.

If you're building a reusable Python library, use the scverse cookiecutter instead.

---

🚀 Getting Started

You've initialized a new repo from this template—great! Follow these steps to set up your project.

Step 1: Install pixi

Skip this if you already have pixi installed.

# macOS / Linux
curl -fsSL https://pixi.sh/install.sh | bash

# Or with Homebrew (macOS)
brew install pixi

Restart your terminal after installation. See pixi installation docs for Windows and other options.

Step 1b: Install GitHub CLI (optional)

Recommended if you're working on a remote server and need to authenticate with GitHub.

# macOS
brew install gh

# Linux (no sudo required)
curl -sS https://webi.sh/gh | sh

Then authenticate: gh auth login. See GitHub CLI installation docs for more options.

Step 2: Clone your repo locally

git clone <your-repo-url>
cd <your-project-name>

The URL depends on your authentication method:

• HTTPS: https://github.com/owner/repo.git
• SSH: git@github.com:owner/repo.git
• GitHub CLI: gh repo clone owner/repo

Step 3: Customize the template

Before installing the environment, update these files with your project details:

File	What to change
src/myanalysis/	Rename this folder to your project slug (e.g., src/myproject/)
pyproject.toml	Update name to match your renamed folder
pixi.toml	Update name, description, authors, kernel display-name, and myanalysis → your package name in [pypi-dependencies]

Step 4: Set up the environment

pixi install                   # create environment from pixi.toml
pixi run pre-commit install    # set up code quality hooks
pixi run install-kernel        # register Jupyter kernel

💡 Tip: Use pixi shell to enter the environment interactively—then you can run commands directly without the pixi run prefix.

Step 5: Verify your setup

pixi run test                  # should pass (tests your package imports correctly)
pixi run lab                   # opens Jupyter Lab

In Jupyter Lab, check that your kernel appears (look for the name you set in pixi.toml).

Step 6: Make your first commit

git add -A
git commit -m "Initial project setup"
git push

💡 Pre-commit hooks will run and may reformat some files. If so, just git add -A && git commit -m "Initial project setup" again.

🎉 You're ready to start analyzing!

---

📊 Start Your Analysis

• Demo notebook: Check out analysis/demo_scRNA_workflow.ipynb for a complete scRNA-seq workflow example using scanpy's PBMC 3k dataset.
• New notebooks: Copy analysis/XX-2026-01-27_sample_notebook.ipynb as a starting point. Follow the naming convention: [INITIALS]-[YYYY]-[MM]-[DD]_description.ipynb.
• Add your data: Create folders under data/ and register paths in src/<your-package>/_constants.py.
• Replace this README with your project documentation once you're set up.

---

☕ Daily Workflow

cd your-project
pixi shell                     # activate environment
jupyter lab                    # work in notebooks, or start via jupyter-hub
# ... do your analysis ...
exit                           # leave pixi shell when done

Or run commands directly without entering the shell:

pixi run lab                   # start Jupyter Lab
pixi run python script.py      # run a script

---

📚 Reference

📦 What is pixi?

Pixi is a modern package manager that handles both conda and PyPI packages in one tool:

• 🔒 Creates isolated environments per project
• 🔀 Installs from conda-forge AND PyPI together
• 📌 Locks exact versions for reproducibility (pixi.lock)
• 💻 Works cross-platform (macOS, Linux, Windows)

You don't need conda or pip installed — pixi handles everything!

➕ Adding packages

All dependencies live in pixi.toml. To add a new package:

# From conda-forge (preferred for scientific packages)
pixi add numpy
pixi add "scanpy>=1.10"

# From PyPI (when not on conda-forge)
pixi add --pypi some-package

Or edit pixi.toml directly and run pixi install.

💡 Tip: Prefer PyPI packages when available — mixing conda and pip can cause dependency conflicts.

👉 See pixi documentation for more details.

📓 Data and notebook conventions

• Notebook naming: [INITIALS]-[YYYY]-[MM]-[DD]_description.ipynb
• Data layout (one folder per dataset):
  • data/<dataset>/raw/ — original data files
  • data/<dataset>/processed/ — preprocessed data
  • data/<dataset>/resources/ — reference data, annotations
  • data/<dataset>/results/ — analysis outputs
• Figures: figures/ or data/<dataset>/results/
• Import paths via the local package:

from yourpackage import FilePaths

🔧 Pre-commit & code quality

This template uses pre-commit hooks to automatically check your code before each commit:

Tool	What it does
Ruff	Lints and formats Python code + notebooks
Biome	Formats JSON/JSONC files
pyproject-fmt	Formats pyproject.toml

Hooks run automatically on git commit. To run manually:

pre-commit run --all-files

💡 If a check reformats your code, just git add the changes and commit again.

🖥️ GPU notes

Platform	PyTorch	JAX
macOS (Apple Silicon)	✅ MPS acceleration	❌ CPU only
Linux (NVIDIA GPU)	✅ CUDA	✅ CUDA 12

The template auto-configures packages per platform. Linux also gets rapids-singlecell for GPU-accelerated analysis.

🖧 Cluster usage

For cluster usage (e.g., ETH Euler):

• 📚 General docs: https://docs.hpc.ethz.ch/
• 🚀 Notebooks via JupyterHub: https://jupyter.euler.hpc.ethz.ch/hub/