Single-FOV MERFISH Image Decoding And Cell Segmentation
Domain: life_sciences — Cell & Imaging Biology

Summary: Run the full MERFISH image-analysis pipeline on one field of view of U2OS cells: decode transcripts against a 130-gene MHD4 codebook, segment nuclei from the DAPI tile, assign transcripts to cells, and emit a cell-by-gene count matrix plus quality metrics.

Task prompt:
You are working on an Ubuntu VM to run the full MERFISH image-analysis pipeline
for one field of view of a human U2OS cell population stained against a
130-gene panel.

Task directory:
- `base`

Inputs (all under `base/input`; treat as read-only):
- `experiment.json` plus `primary_images.json`, `nuclei.json` and the per-FOV
  manifests `primary_images-fov_000.json` / `nuclei-fov_000.json`. These
  describe a starfish Experiment with one FOV, 8 hybridization rounds, and
  2 color channels.
- 16 primary fluorescence TIFFs
  `primary_images-fov_000-Z0-H<h>-C<c>.tiff` (h in 0..7, c in 0..1); each is
  2048x2048.
- 1 DAPI nuclear stain TIFF `nuclei-fov_000-Z0-H0-C0.tiff`.
- `codebook.json` mapping 130 target genes and 10 Blank controls to 16-bit
  MHD4 (Hamming-distance-4 with 1-bit error correction) binary codewords.
- `experiment.json` `extras.scale_factors` gives per-(round, channel)
  normalization scalars.
- `output_contract.json` lists the exact output files, columns, and dtypes
  your pipeline must produce.
- `runtime_env/pyproject.toml`, `runtime_env/uv.lock`, and
  `runtime_env/python-version` pin the Python 3.11 environment that
  starfish 0.3.4 and Cellpose 3.1.1 need. The canonical agent-facing entry
  point `base/software/merfish_runtime.sh`
  behaves like a Python interpreter, keeps its `uv` cache and resolved
  environment under `base/output`,
  and uses `runtime_env/pyproject.toml` (with the staged `uv.lock`) as the
  frozen runtime manifest. You can invoke it directly
  (`software/merfish_runtime.sh your_script.py`) or materialize the env
  yourself with `uv sync --frozen --project input/runtime_env` and then run
  the resulting `.venv/bin/python`.

Recommended workflow:
1. Load the starfish Experiment and sanity-check the image and codebook.
2. Preprocess: high-pass filter or background-subtract, normalize intensity
   using the provided `scale_factors`, and confirm the pre-registered tiles
   are still aligned.
3. Run starfish BlobDetector on each round/channel and extract 16-bit
   intensity traces per spot.
4. Decode with an MHD4-aware decoder (starfish `CheckAll`) with 1-bit error
   correction; filter by magnitude and distance thresholds.
5. Run Cellpose on the DAPI image with a pretrained nuclei model and a
   diameter appropriate for U2OS (roughly 30-50 px).
6. Assign decoded transcripts to the nearest segmented cell; mark transcripts
   outside every cell as extracellular and exclude them from the
   cell-by-gene matrix.
7. Build the cell-by-gene count matrix for the 130 real genes (exclude
   blanks) and compute the quality metrics listed in `output_contract.json`.

Outputs must go into `base/output`:
- `decoded_transcripts.csv` with columns `gene, x, y, is_exact, total_magnitude`.
- `segmentation.tiff` - 2048x2048 `uint16` labeled mask (background=0).
- `cell_by_gene.csv` - leading `cell_id` column followed by the 130 real genes
  in codebook order; integer counts.
- `quality_metrics.json` - scalar keys `total_decoded_transcripts`,
  `blank_rate`, `exact_match_fraction`, `n_cells`, `assigned_fraction`,
  `mean_transcripts_per_cell`.

All coordinates (`x`, `y`) in `decoded_transcripts.csv` must be pixel
coordinates within the 2048x2048 FOV so they line up with the segmentation
mask.

Required actions:
Invoke the canonical Python entry point `software/merfish_runtime.sh` (or materialize the env with `uv sync --frozen --project input/runtime_env/`).
Load the staged starfish experiment (16 primary TIFFs + 1 DAPI TIFF + manifests + codebook) and sanity-check alignment.
Preprocess images: high-pass / background subtract, apply per-(round, channel) `scale_factors`, confirm registration.
Detect fluorescent spots with starfish `BlobDetector` and decode with the MHD4-aware `CheckAll` decoder plus 1-bit error correction.
Segment nuclei from the DAPI tile using Cellpose 3.1.1 with the `nuclei` model and a diameter around 30-50 px for U2OS cells.
Assign decoded transcripts to the nearest labeled cell and mark out-of-cell transcripts as extracellular.
Emit `decoded_transcripts.csv`, `segmentation.tiff`, `cell_by_gene.csv`, and `quality_metrics.json` under `output/` in pixel coordinates.

Software: Python
uv
starfish
Cellpose
PyTorch

Input files:
name: Starfish experiment manifest
format: json
description: Top-level starfish Experiment v5.0.0 manifest with per-(round, channel) `scale_factors`.
name: MHD4 codebook
format: json
description: 140 targets (130 real genes + 10 `Blank-*` controls) with 16-bit MHD4 codewords.
name: Primary images manifest
format: json
description: Starfish top-level primary-images manifest trimmed to `fov_000` only.
name: Nuclei images manifest
format: json
description: Starfish top-level nuclei manifest trimmed to `fov_000` only.
name: Primary FOV tile manifest
format: json
description: Per-FOV manifest enumerating 16 primary tiles for (round 0-7, channel 0-1).
name: Nuclei FOV tile manifest
format: json
description: Per-FOV manifest for the single DAPI tile.
name: Primary fluorescence tiles
format: tiff
description: 16 pre-registered 2048x2048 tiles (h in 0..7, c in 0..1) to decode against the codebook.
name: DAPI nuclear stain tile
format: tiff
description: Single 2048x2048 DAPI image used to segment nuclei.
name: Task brief
format: txt
description: Evaluator-safe solve-time brief (no thresholds, no gold reference).
name: Output contract
format: json
description: Required output paths, columns, and dtypes; no per-gene expected counts.
name: Runtime dependency manifest
format: toml
description: Pinned dependencies (`starfish==0.3.4`, `cellpose==3.1.1`, `torch`, NumPy/SciPy/pandas/scikit-image) for `uv sync --frozen`.
name: Runtime dependency lockfile
format: toml
description: Resolved uv lockfile (87 packages against Python 3.11) consumed by `uv sync --frozen` and the `software/merfish_runtime.sh` wrapper.
name: Python version pin
format: text
description: Python version pin (`3.11`) consumed by `uv`.
name: Canonical Python entry point
format: bash
description: Wrapper that behaves like a Python interpreter; forwards args to `uv run --frozen --project input/runtime_env/pyproject.toml python "$@"` with the agent-scoped uv env under `output/.agent_runtime_env/`.