probe_tracking

Pipeline for processing light-sheet microscopy images of mouse brains and registering them to the Allen Mouse Brain Atlas for Neuropixels probe track reconstruction.

---

Overview

Raw Zeiss CZI files (multi-tile, two-channel) are fused into TIFF stacks, then registered to the Allen CCF 10 µm atlas using brainreg. Probe tracks are manually traced in napari using brainglobe-segmentation.

Cohorts:

• Batch v2 — RZ034, RZ036–RZ039, RZ047, RZ049–RZ053 (11 animals)
• Batch v4 — RZ054, RZ055, RZ057–RZ059, RZ061–RZ063, RZ065, RZ068, RZ070 (11 animals)

To switch between batches, set ACTIVE_BATCH in config.py.

---

Pipeline steps

[1] pre_flight_check.py       Validate CZI metadata before batch run
         ↓
[2] batch_process.py          Main pipeline — all animals in active batch
    OR  process_rz034.py      Special case — RZ034 (different objective)
         ↓
    (manual) napari + brainglobe-segmentation
             conda activate napari-env && napari
             Load brainreg output, trace probe tracks, save

Step 1 — Pre-flight check

Reads CZI headers only (no pixel data). Validates tile count, channel count, voxel sizes, mosaic dimensions, and illumination mode across all animals.

conda activate brain-stitcher
python pre_flight_check.py

Step 2 — Tile fusion + registration

For each brain:

1. Copy CZI from H: → temp\ (~170–206 GB, deleted after fusion)
2. Fuse cam1 (autofluorescence) → fused_tiff_cam1/slice_XXXX.tif
3. Fuse cam2 (DiI probe signal) → fused_tiff_cam2/slice_XXXX.tif
4. Delete temp CZI
5. Run brainreg (~57 min/brain)

conda activate brain-stitcher
python batch_process.py          # full batch, ~12 hours
python process_rz034.py          # RZ034 only, ~7 hours

Restart-safe: set RESUME = True (default) to skip completed steps.

Step 3 — Manual probe track tracing

1. Open napari with brainglobe-segmentation:

   conda activate napari-env
   napari

2. Load brainreg output (sample space) for the animal
3. Trace probe tracks → save → generate region CSVs

---

Switching batches

All scripts read from config.py. To process a different batch, open config.py and change the single line:

ACTIVE_BATCH = _V4   # change to _V2 for the previous cohort

Each batch definition (_V2, _V4) contains its own source directory, output directory, animal list, and voxel sizes.

---

File reference

File	Purpose
config.py	Batch definitions, active batch selector, shared parameters
fusion_utils.py	Shared tile-fusion helpers (make_feather_mask, extract_2d)
pre_flight_check.py	CZI metadata validation
batch_process.py	Main pipeline for standard batches
process_rz034.py	Special-case pipeline for RZ034 (different objective)
environment.yml	brain-stitcher conda environment spec

---

Acquisition parameters

Parameter	Batch v2 RZ036–RZ053	Batch v4 RZ054–RZ070	RZ034
Objective	EC Plan-Neofluar 5x/0.16	EC Plan-Neofluar 5x/0.16	Fluar 2.5x/0.12
Immersion	RIMS n = 1.496	RIMS n = 1.493	n = 1.489
Zoom	0.4	0.36	0.8
XY voxel (raw)	2.5601 µm	2.5601 µm	2.30 µm
Z step (raw)	10.0 µm	10.0 µm	2.30 µm (isotropic)
XY downsample	4× → 10.24 µm	4× → 10.24 µm	4× → 9.20 µm
Z downsample	none → 10.0 µm	none → 10.0 µm	every 4th → 9.20 µm
Tiles	24 or 28	24 or 28	18
Channels	561 nm + 638 nm	561 nm + 638 nm	561 nm + 638 nm
Illumination	dual (merged by ZEN)	dual (merged by ZEN)	single
CZI size	~170 GB	~155–206 GB	~1 TB

Note: The zoom changed between v2 and v4 but the XY pixel size is identical (2.5601 µm) — confirmed from CZI metadata. The zoom change did not affect the effective pixel size.

---

Environments

Two conda environments are required:

Environment	Used for
brain-stitcher	Tile fusion + brainreg registration
napari-env	Manual track tracing (napari + brainglobe-segmentation)

conda env create -f environment.yml   # creates brain-stitcher

---

Output directory structure

D:\brain_stitching_v4\          (or brain_stitching_v2\ for batch v2)
├── RZ054\
│   ├── fused_tiff_cam1\        slice_0000.tif … slice_XXXX.tif
│   ├── fused_tiff_cam2\        slice_0000.tif … slice_XXXX.tif
│   └── brainreg_output\
│       ├── registered_atlas.tiff
│       ├── deformation_field_0.tiff
│       ├── deformation_field_1.tiff
│       ├── deformation_field_2.tiff
│       └── segmentation\sample_space\tracks\
│           ├── track_0_points.npy
│           └── …
├── RZ055\
│   └── (same structure)
└── batch_log_YYYYMMDD_HHMMSS.txt

D:\brain_stitching_v2\RZ034\    (processed separately via process_rz034.py)
└── (same structure, 9.20 µm isotropic voxels)