Metadata-Version: 2.4
Name: mrsnappy
Version: 0.1.0
Summary: 3D fluorescent puncta detection for microscopy z-stacks.
Author: Marco Rothstein
License: MIT License
        
        Copyright (c) 2026 Marco A. Rojas-Cessa
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/marcorojas-cessa/SNAPpy
Project-URL: Source, https://github.com/marcorojas-cessa/SNAPpy
Project-URL: Issues, https://github.com/marcorojas-cessa/SNAPpy/issues
Keywords: microscopy,fluorescence,puncta,spot-detection,bioimage-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: joblib>=1.3
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: scikit-image>=0.21
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.10
Requires-Dist: tifffile>=2023.7.10
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# 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:

```bash
python -m pip install mrsnappy
```

Then check that the command-line tool is available:

```bash
snappy --help
snappy list-models
```

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

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

If you are installing from a local checkout:

```bash
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:

```bash
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:

```bash
snappy list-models
```

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

```bash
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`:

```bash
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:

```csv
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:

```text
dataset_root/
  test/
    image_001.tif
    image_002.tif
```

run:

```bash
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:

```bash
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.

```python
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](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](docs/installation.md)
- [Bundled lab models](docs/models.md)
- [Workflow overview](docs/workflow.md)

## Citation

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