Add cohort template building and export analysis levels

docs/howto/cohort_template.md

@@ -0,0 +1,123 @@
+# Cohort templates
+
+SPIMquant can build a study-specific (cohort) SPIM template from your subjects,
+and prepare it for use as a `--template` in later SPIMquant runs.
+
+The workflow is:
+
+1. Subjects are registered to `--template` (e.g. ABAv3) as in the `participant`
+   level, and each stain is resampled to template space at `--cohort-template-level`
+   (default: `--registration_level`).
+2. A multivariate template is built from these images with
+   [FireANTs](https://github.com/rohitrango/FireANTs) on GPU. All stains are built
+   jointly, so every stain template is in the same space.
+3. The cohort template drifts away from the original template's space during
+   building, so the original template's anat is registered (affine + deformable,
+   greedy) to the cohort template. The original atlases, brain mask and anat are
+   warped into cohort template space with this registration.
+4. The `cohort_template_export` level writes a `template_description.json`, a
+   SPIMquant `templates:` config entry, and optionally uploads everything to Zenodo.
+
+## Building the template
+
+```
+spimquant /path/to/bids /path/to/output cohort_template \
+    --cohort-template-name lecanemab \
+    --cohort-template-stains YoPro Iba1 Abeta \
+    --cohort-template-n-gpus 2
+```
+
+This runs any registration that has not been run yet, so it can be run on a fresh
+output directory or one with existing `participant` outputs.
+
+Options:
+
+- `--cohort-template-name`: the `tpl-` label of the new template (alphanumeric).
+- `--cohort-template-stains`: stains to build from (default: all). The registration
+  stain (e.g. YoPro) is always the first template channel, and is the image the
+  original template is registered to. Stains with strong subject-specific signal
+  (e.g. Abeta plaques) still contribute to the registration metric, so you may
+  prefer to restrict this to anatomical stains.
+- `--cohort-template-extra-inputs`: other SPIMquant output directories, from
+  datasets registered to the same `--template`, to pool into the template. Subjects
+  missing any of the stains are skipped.
+- `--cohort-template-iterations`, `--cohort-template-n-gpus`: FireANTs settings.
+  Other FireANTs parameters are in the `cohort_template:` section of
+  `config/snakebids.yml`.
+
+Outputs are in `<output>/cohort_template/`:
+
+```
+tpl-lecanemab/
+├── tpl-lecanemab_stain-YoPro_SPIM.nii.gz          # one per stain
+├── tpl-lecanemab_anat.nii.gz                      # original anat, warped
+├── tpl-lecanemab_desc-brain_mask.nii.gz           # original mask, warped
+├── tpl-lecanemab_seg-<seg>_dseg.nii.gz/.tsv       # original atlases, warped
+├── tpl-lecanemab_from-ABAv3_to-lecanemab_xfm.nii.gz
+├── tpl-lecanemab_from-lecanemab_to-ABAv3_xfm.nii.gz
+└── tpl-lecanemab_stain-YoPro_from-ABAv3_to-lecanemab_regqc.html
+tpl-ABAv3/
+└── tpl-ABAv3_desc-lecanemab_stain-YoPro_SPIM.nii.gz   # cohort template in ABAv3 space
+```
+
+Check the `regqc.html` report to confirm the atlases line up with the cohort template.
+
+FireANTs is only installed in the `gpu` pixi environment, so run this level from
+it, e.g. `pixi run -e gpu spimquant ...`. It uses the fused CUDA ops if they are
+installed, falling back to the plain implementation otherwise.
+
+Shape averaging (`cohort_template.fireants.shape_avg`) is off by default: it adds
+a full-resolution registration per iteration, runs out of memory at the 25um
+ABAv3 resolution on a 40GB GPU, and in testing gave a worse subject fit than the
+plain average. To lower memory use and run time, resample the subject images
+before template building with e.g. `--cohort-template-resample-mm 0.05`, useful
+when using a finer `--cohort-template-level`. On an 18-subject cohort, a 50um
+template built in ~7 min vs ~50 min at 25um.
+
+The fused CUDA ops (`fireants-fused-ops`, from the `akhanf/khanlab` channel) are
+installed in the gpu environment and reduce FireANTs' GPU memory use.
+
+## Preparing the template for SPIMquant
+
+```
+spimquant /path/to/bids /path/to/output cohort_template_export \
+    --cohort-template-name lecanemab \
+    --cohort-template-stains YoPro Iba1 Abeta
+```
+
+Use the same `cohort_template` options as when building. This writes
+`tpl-lecanemab/template_description.json`, `tpl-lecanemab_buildinfo.tar.gz` (image
+list, FireANTs config and logs), and `tpl-lecanemab_spimquant.yml`, a SPIMquant
+config file that adds the template and selects it.
+
+To upload to Zenodo, create a draft upload on Zenodo and pass its deposition ID,
+with a Zenodo access token in the environment:
+
+```
+export SNAKEMAKE_STORAGE_ZENODO_ACCESS_TOKEN=<token>
+spimquant /path/to/bids /path/to/output cohort_template_export \
+    --cohort-template-name lecanemab \
+    --cohort-template-stains YoPro Iba1 Abeta \
+    --cohort-template-zenodo-deposition 12345678
+```
+
+The config file then points at `https://zenodo.org/records/<id>/files/...` URLs,
+which resolve once you publish the deposition. Without a deposition, it points at
+the absolute paths of the exported files.
+
+## Using the template
+
+Pass the config file to any SPIMquant run, in place of `--template`:
+
+```
+spimquant /path/to/bids /path/to/output participant \
+    --configfile tpl-lecanemab_spimquant.yml
+```
+
+The registration stain must be one of the cohort template's stains (see
+`--stains_for_reg`).
+
+To make the template a built-in `--template` choice, open a PR that moves its
+`templates:` entry into `spimquant/config/snakebids.yml` (with the Zenodo URLs, or
+paths relative to `spimquant/resources/` after copying `tpl-lecanemab` there), and
+adds the name to the `--template` choices.

mkdocs.yml

@@ -23,6 +23,7 @@ nav:
       - Segmentation Methods: howto/segmentation.md
       - MRI Registration: howto/mri_registration.md
       - Reusing Previous Outputs: howto/reuse_derivatives.md
+      - Cohort Templates: howto/cohort_template.md
   - Reference:
       - CLI Reference: reference/cli_reference.md
       - Output Files: reference/outputs.md

pyproject.toml

@@ -74,6 +74,7 @@ snakemake-storage-plugin-s3 = ">=0.3.3,<0.4"
 snakemake-storage-plugin-gcs = ">=1.1.4,<2"
 snakemake-storage-plugin-fs = ">=1.1.2,<2"
 snakemake-storage-plugin-cached-http = ">=0.3.0,<0.4.0"
+snakemake-storage-plugin-zenodo = ">=0.1.5,<0.2"
 snakemake-executor-plugin-slurm = ">=1.4.0,<2"
 conda = ">=25.5.0,<26"
 gcsfs = ">=2025.5.1,<2026"
@@ -133,6 +134,9 @@ platforms = ["linux-64-cuda"]
 [tool.pixi.feature.gpu.dependencies]
 cuda-version = "12.6.*"
 pytorch-gpu = "*"
+# cohort template building (khanlab fork, from akhanf/khanlab)
+fireants = ">=1.4.0.post1"
+fireants-fused-ops = ">=1.2.0"
 
 
 # ----------------------------------------------------------------------