You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Template for single-cell/spatial **analysis** repos. If you're building a Python library, use the [scverse cookiecutter](https://github.com/scverse/cookiecutter-scverse) instead.
3
+
A notebook-first template for single-cell/spatial analysis projects. Uses [pixi](https://pixi.sh) for environment management.
4
4
5
-
> 📝 **After setup, replace this README** with project-specific docs so collaborators know what the project does. Include: a one-line goal, data locations, key notebooks to run, and who to ping.
5
+
> If you're building a reusable Python library, use the [scverse cookiecutter](https://github.com/scverse/cookiecutter-scverse) instead.
6
6
7
7
---
8
8
9
-
## 📦 What is pixi?
9
+
## 🚀 Getting Started
10
10
11
-
[Pixi](https://pixi.sh) is a modern package manager that handles both **conda** and **PyPI** packages in one tool. Think of it as a replacement for conda/mamba + pip that:
11
+
**You've initialized a new repo from this template—great!** Follow these steps to set up your project.
12
12
13
-
- 🔒 Creates **isolated environments** per project (like conda environments)
14
-
- 🔀 Installs packages from **conda-forge AND PyPI** together
15
-
- 📌 Locks exact versions for **reproducibility** (`pixi.lock`)
16
-
- 💻 Works **cross-platform** (macOS, Linux, Windows)
13
+
### Step 1: Install pixi
17
14
18
-
**You don't need conda or pip installed** — pixi handles everything!
pre-commit install # set up code quality hooks (run once)
40
-
pixi run lab # start Jupyter Lab
41
-
pixi run test# run tests
42
-
pixi run install-kernel # add Jupyter kernel (run once)
32
+
# macOS
33
+
brew install gh
34
+
35
+
# Linux (no sudo required)
36
+
curl -sS https://webi.sh/gh | sh
37
+
```
38
+
39
+
Then authenticate: `gh auth login`. See [GitHub CLI installation docs](https://github.com/cli/cli#installation) for more options.
40
+
41
+
### Step 2: Clone your repo locally
42
+
43
+
```bash
44
+
git clone <your-repo-url>
45
+
cd<your-project-name>
43
46
```
44
47
45
-
### ☕ Daily workflow
48
+
The URL depends on your authentication method:
49
+
-**HTTPS**: `https://github.com/owner/repo.git`
50
+
-**SSH**: `git@github.com:owner/repo.git`
51
+
-**GitHub CLI**: `gh repo clone owner/repo`
52
+
53
+
### Step 3: Customize the template
54
+
55
+
Before installing the environment, update these files with your project details:
46
56
47
-
Once set up, your typical workflow is:
57
+
| File | What to change |
58
+
|------|----------------|
59
+
|`src/myanalysis/`|**Rename this folder** to your project slug (e.g., `src/myproject/`) |
60
+
|`pyproject.toml`| Update `name` to match your renamed folder |
61
+
|`pixi.toml`| Update `name`, `description`, `authors`, kernel `display-name`, and `myanalysis` → your package name in `[pypi-dependencies]`|
62
+
63
+
### Step 4: Set up the environment
64
+
65
+
```bash
66
+
pixi install # create environment from pixi.toml
67
+
pixi run pre-commit install # set up code quality hooks
68
+
pixi run install-kernel # register Jupyter kernel
69
+
```
70
+
71
+
💡 **Tip**: Use `pixi shell` to enter the environment interactively—then you can run commands directly without the `pixi run` prefix.
72
+
73
+
### Step 5: Verify your setup
74
+
75
+
```bash
76
+
pixi run test# should pass (tests your package imports correctly)
77
+
pixi run lab # opens Jupyter Lab
78
+
```
79
+
80
+
In Jupyter Lab, check that your kernel appears (look for the name you set in `pixi.toml`).
81
+
82
+
### Step 6: Make your first commit
83
+
84
+
```bash
85
+
git add -A
86
+
git commit -m "Initial project setup"
87
+
git push
88
+
```
89
+
90
+
💡 Pre-commit hooks will run and may reformat some files. If so, just `git add -A && git commit -m "Initial project setup"` again.
91
+
92
+
🎉 **You're ready to start analyzing!**
93
+
94
+
---
95
+
96
+
## 📊 Start Your Analysis
97
+
98
+
-**Demo notebook**: Check out `analysis/demo_scRNA_workflow.ipynb` for a complete scRNA-seq workflow example using scanpy's PBMC 3k dataset.
99
+
-**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`.
100
+
-**Add your data**: Create folders under `data/` and register paths in `src/<your-package>/_constants.py`.
101
+
-**Replace this README** with your project documentation once you're set up.
102
+
103
+
---
104
+
105
+
## ☕ Daily Workflow
48
106
49
107
```bash
50
108
cd your-project
51
109
pixi shell # activate environment
52
-
jupyter lab # work in notebooks
110
+
jupyter lab # work in notebooks, or start via jupyter-hub
53
111
# ... do your analysis ...
54
112
exit# leave pixi shell when done
55
113
```
56
114
57
-
Or run commands without entering the shell:
115
+
Or run commands directly without entering the shell:
58
116
59
117
```bash
60
-
pixi run lab #runs Jupyter in pixi environment
61
-
pixi run python my_script.py # runs script in pixi environment
118
+
pixi run lab #start Jupyter Lab
119
+
pixi run python script.py # run a script
62
120
```
63
121
64
122
---
65
123
66
-
## ➕ Adding packages
124
+
## 📚 Reference
67
125
68
-
All dependencies live in `pixi.toml`. To add a new package:
126
+
<details>
127
+
<summary><strong>📦 What is pixi?</strong></summary>
69
128
70
-
### Option 1: Command line (recommended)
129
+
[Pixi](https://pixi.sh) is a modern package manager that handles both **conda** and **PyPI** packages in one tool:
71
130
72
-
```bash
73
-
# Add from conda-forge (preferred for scientific packages)
74
-
pixi add numpy
75
-
pixi add "scanpy>=1.10"
131
+
- 🔒 Creates **isolated environments** per project
132
+
- 🔀 Installs from **conda-forge AND PyPI** together
133
+
- 📌 Locks exact versions for **reproducibility** (`pixi.lock`)
134
+
- 💻 Works **cross-platform** (macOS, Linux, Windows)
76
135
77
-
# Add from PyPI (when not available on conda-forge)
78
-
pixi add --pypi some-pypi-only-package
79
-
```
136
+
**You don't need conda or pip installed** — pixi handles everything!
2. Rename the package directory `src/myanalysis/` to your project slug, and update the `name` in `pyproject.toml` to match.
107
-
3. Adjust paths in `src/<your-package>/_constants.py` to match your datasets.
108
-
4. Update `.github/copilot-instructions.md` with your project name, goal, and dataset locations. This helps AI coding assistants (GitHub Copilot, Claude, etc.) understand your project.
109
-
5. 📝 **Replace this README** with project-specific docs: what the project does, how to run key notebooks, and who to contact.
160
+
</details>
110
161
111
-
---
112
-
113
-
## 📓 Data and notebooks
162
+
<details>
163
+
<summary><strong>📓 Data and notebook conventions</strong></summary>
@@ -122,64 +172,50 @@ Then run `pixi install` to update the environment.
122
172
-**Import paths** via the local package:
123
173
124
174
```python
125
-
frommyanalysisimport FilePaths
175
+
fromyourpackageimport FilePaths
126
176
```
127
177
128
-
---
129
-
130
-
## 🔧 Tooling & code quality
131
-
132
-
This template uses **pre-commit hooks** to automatically check your code before each commit. This catches common issues early and keeps code consistent across the team.
133
-
134
-
### What are pre-commit hooks?
135
-
136
-
[Pre-commit](https://pre-commit.com/) is a tool that runs checks on your code **every time you run `git commit`**. If any check fails, the commit is blocked until you fix the issue. This ensures:
Now hooks run automatically on `git commit`. To run all checks manually:
191
+
Hooks run automatically on `git commit`. To run manually:
160
192
161
193
```bash
162
194
pre-commit run --all-files
163
195
```
164
196
165
-
💡 **Tip**: If a check reformats your code, just `git add` the changes and commit again!
197
+
💡 If a check reformats your code, just `git add` the changes and commit again.
166
198
167
-
---
199
+
</details>
168
200
169
-
## 🖥️ GPU notes
201
+
<details>
202
+
<summary><strong>🖥️ GPU notes</strong></summary>
170
203
171
204
| Platform | PyTorch | JAX |
172
205
|----------|---------|-----|
173
206
|**macOS** (Apple Silicon) | ✅ MPS acceleration | ❌ CPU only |
174
-
|**Linux** (NVIDIA GPU) | ✅ CUDA | ✅ CUDA 12 via `jax[cuda12]`|
207
+
|**Linux** (NVIDIA GPU) | ✅ CUDA | ✅ CUDA 12 |
175
208
176
-
The template automatically configures the right packages per platform. Linux also gets [rapids-singlecell](https://rapids-singlecell.readthedocs.io/) for GPU-accelerated single-cell analysis.
209
+
The template auto-configures packages per platform. Linux also gets [rapids-singlecell](https://rapids-singlecell.readthedocs.io/) for GPU-accelerated analysis.
0 commit comments