mrsnappy 0.1.0

3D fluorescent puncta detection for microscopy z-stacks.

SNAPpy

SNAPpy is a Python implementation of a two-stage workflow for detecting fluorescent puncta in 3D microscopy z-stacks. It first finds candidate puncta with configurable 3D image-processing recipes, then uses local 3D features and an SVM classifier to remove false candidates.

The package includes bundled ch1, ch2, and ch3 models optimized for Rothstein lab z-stack images. These models are intended to make routine lab processing simple while preserving the lower-level API for training, benchmarking, and custom model development.

Installation

After the first PyPI release, install SNAPpy with:

python -m pip install mrsnappy

Then check that the command-line tool is available:

snappy --help
snappy list-models

Until the first PyPI release is published, install the current GitHub version with:

python -m pip install "git+https://github.com/marcorojas-cessa/SNAPpy.git"

If you are installing from a local checkout:

git clone https://github.com/marcorojas-cessa/SNAPpy.git
cd SNAPpy
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

For development:

python -m pip install -e ".[dev]"

Naming

• The repository and project are named SNAPpy.
• The PyPI distribution name is mrsnappy.
• The terminal command is snappy.
• The Python import package is snap_py.

Python packages are installed with pip, so the install command is python -m pip install ..., not python install .... The PyPI name snappy is already used by an unrelated project, so SNAPpy uses mrsnappy as its install name while keeping snappy as the command-line tool.

Quick Start

List the bundled lab models:

snappy list-models

Run the optimized ch1 model on one 3D TIFF stack:

snappy predict-lab \
  --channel ch1 \
  --image /path/to/zstack.tif \
  --output /path/to/detections.csv

Run the optimized ch2 or ch3 models by changing --channel:

snappy predict-lab --channel ch2 --image image.tif --output ch2_detections.csv
snappy predict-lab --channel ch3 --image image.tif --output ch3_detections.csv

The output CSV contains x, y, z, and score columns. Coordinates are written in image voxel coordinates, with z corresponding to the stack axis.

Typical output:

x,y,z,score
42.3,88.1,12.0,1.74
51.9,91.5,13.2,0.62

Dataset Split Prediction

For a dataset arranged as:

dataset_root/
  test/
    image_001.tif
    image_002.tif

run:

snappy predict-lab-split \
  --channel ch1 \
  --dataset-root /path/to/dataset_root \
  --split test \
  --output-root /path/to/predictions

Custom Model Prediction

Use this only if you trained or optimized your own model:

snappy predict \
  --image /path/to/zstack.tif \
  --config /path/to/config.json \
  --model /path/to/model.joblib \
  --output /path/to/detections.csv

The config must contain a pipeline_defaults object describing the detection recipe.

Bundled Lab Models

Channel	Source run	Validation main F1	Test main F1	Notes
ch1	native_ch1_replay_v12	0.941	0.919	Strong performance on the ch1 validation and held-out test split.
ch2	native_ch2_replay_v5	0.862	0.885	Balanced precision/recall on the ch2 held-out test split.
ch3	native_ch3_replay_v5	0.935	0.858	High recall but lower strict localization F1; review detections for quantitative localization-sensitive analyses.

These bundled models were optimized on existing Rothstein lab channel-specific data. They should be validated on any new microscope, acquisition settings, sample preparation, or staining condition before being used for final quantitative conclusions.

Python API

The command-line interface is the simplest way to process routine lab images. Use the Python API when integrating SNAPpy into another analysis script.

from snap_py import load_lab_model, predict_image
from snap_py.io import write_points_csv

lab_model = load_lab_model("ch1")
coords, scores = predict_image(
    "image.tif",
    lab_model.recipe,
    lab_model.model_path,
    score_threshold=lab_model.score_threshold,
)
write_points_csv("detections.csv", coords, scores)

How It Works

SNAPpy uses a two-stage workflow:

1. It preprocesses the 3D image, subtracts background when requested, and searches for local maxima in 3D.
2. It refines each candidate with local Gaussian-style fitting and measures intensity, shape, contrast, and background features.
3. It applies a trained classifier to keep candidates that resemble true puncta and reject likely artifacts.
4. It writes final 3D puncta coordinates and decision scores.

See docs/workflow.md for a more detailed explanation.

Repository Scope

This repository contains the installable SNAPpy package, bundled lab-use models, documentation, and lightweight tests. Raw microscopy data, benchmark result trees, cluster logs, and manuscript-generation artifacts are intentionally excluded.

More Documentation

• Installation guide
• Bundled lab models
• Workflow overview

Citation

If you use SNAPpy in a publication, cite the associated manuscript once available.