Skip to content

qi2lab human olfactory bulb example

Overview

The goal of this example is to retrieve a 3D MERFISH experiment generated by the qi2lab at ASU and process it from raw microscope data through transcript quantification and cell assignment. This is a 119-gene MERFISH and 2-gene smFISH experiment on post-mortem human olfactory bulb tissue.

Preliminaries

You need to make sure you have a working uv environment with merfish3d-analysis properly installed, proseg installed if you plan to run downstream RNA-based segmentation refinement, and our human olfactory bulb 3D MERFISH dataset downloaded. The dataset is approximately 0.7 TB, and you will need roughly another ~0.5 TB of space to create the qi2labDataStore structure we use to perform tile registration, global registration, segmentation, pixel decoding, filtering, and cell assignment.

Downloaded data

In the downloaded data, the directory structure should be as follows:

/path/to/download/ 
├── raw_data/ 
  ├── data_r0001_tile000_xyz/
  ├── data_r0001_tile000_xyz.csv
  ...
  ...
  ├── data_r0009_tile041_xyz/
  ├── data_r0009_tile041_xyz.csv
  ├── codebook.csv
  ├── bit_order.csv
  ├── hot_pixel_flir.tiff
  └── scan_metadata.csv

Processing steps

All required processing commands are installed with merfish3d-analysis and should be invoked through uv run. Commands that support multiple GPUs accept --num-gpus; the default is one GPU. The commands below reproduce the two-GPU workflow used for this dataset.

All of the commands given here are run from the terminal.

Each command list below can be queried using --help to discover all of the available parameters, if the defaults are not correct for your dataset. For example, 

uv run qi2lab-decode --help

Create the datastore and estimate flatfields

uv run qi2lab-datastore /path/to/data

This default invocation performs camera conversion and hot-pixel correction, then estimates and applies illumination flatfields. The fiducial flatfield is estimated from every tile in round 1. Each readout-channel flatfield uses up to 100 unique tile images by default; change that limit with --max-flatfield-images. The estimated maps are saved as /path/to/data/illuminations.ome.tif by default.

To reuse an existing illuminations.ome.tif instead of estimating new maps, place it in the experiment root and pass --use-illuminations:

uv run qi2lab-datastore /path/to/data --use-illuminations

Preprocess with fiducial-only deconvolution

uv run qi2lab-preprocess /path/to/data --num-gpus 2 --no-decon

--no-decon disables readout-channel deconvolution. Fiducial deconvolution remains enabled and is used for local registration and global fiducial fusion. Readout feature prediction instead uses the flatfield-corrected readout images. The command also performs local affine registration, SOFIMA residual estimation, readout feature prediction, and direct-to-Zarr global fiducial fusion.

To rerun only global registration and fused fiducial OME-Zarr creation on an existing datastore:

uv run qi2lab-preprocess /path/to/data \
  --num-gpus 2 \
  --global-registration-only \
  --overwrite

poly-dT cell segmentation

The values for Cellpose-SAM need to be pre-determined using the Cellpose GUI. qi2lab-segment defaults to the Cellpose-SAM v2 model (cpsam_v2) and does not force a diameter unless you explicitly pass one.

uv run qi2lab-segment /path/to/data --normalization 0.5 99.0 --cellprob-threshold 0.0

Pixel decoding, chromatic-affine estimation, and FDR filtering

Because there are 2 smFISH bits at the end of the codebook, we instruct the merfish3d-analysis pixel decoder to process only the initial 16 bits of the codebook.

uv run qi2lab-decode /path/to/data \
  --num-gpus 2 \
  --estimate-chromatic-affines

During iterative normalization, --estimate-chromatic-affines estimates chromatic transforms from decoded RNA on-bit centroids assigned to valid, nonblank codewords. The resulting calibration is stored in the datastore and used by the final decoding pass. Normalization and final tile decoding both use the requested two GPUs.

Datastore viewing

Open the read-only viewer with:

uv run viewer /path/to/data

Use local native mode to inspect stored tile images, local warped mode to test chromatic, affine, and SOFIMA transform overlays, and global fused mode to view the fused Zarr with datastore, Proseg, Baysor, or Cellpose overlays when present.