{"name":"napari-sigma","display_name":"Structurally-aware Intensity-ordered GMM-MRF Algorithm","visibility":"public","icon":null,"categories":[],"schema_version":"0.3.0","on_activate":null,"on_deactivate":null,"contributions":{"commands":[{"id":"napari-sigma.widget","title":"Open SIGMA","python_name":"napari_sigma._widget:SIGMAWidget","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"napari-sigma.write_single","title":"Save SIGMA layer with metadata","python_name":"napari_sigma._writer:write_single_image","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"napari-sigma.reader","title":"Read SIGMA-supported image","python_name":"napari_sigma._reader:napari_get_reader","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"napari-sigma.write_labels","title":"Save SIGMA labels with metadata","python_name":"napari_sigma._writer:write_single_labels","short_title":null,"category":null,"icon":null,"enablement":null}],"readers":[{"command":"napari-sigma.reader","filename_patterns":["*.tif","*.tiff","*.png","*.jpg","*.jpeg"],"accepts_directories":false}],"writers":[{"command":"napari-sigma.write_single","layer_types":["image"],"filename_extensions":[".tif",".tiff",".png",".jpg",".jpeg"],"display_name":"Save SIGMA layer with metadata"},{"command":"napari-sigma.write_labels","layer_types":["labels"],"filename_extensions":[".tif",".tiff",".png",".jpg",".jpeg"],"display_name":"Save SIGMA labels with metadata"}],"widgets":[{"command":"napari-sigma.widget","display_name":"SIGMA","autogenerate":false}],"sample_data":null,"themes":null,"menus":{},"submenus":null,"keybindings":null,"configurations":{}},"package_metadata":{"metadata_version":"2.4","name":"napari-sigma","version":"0.0.6","dynamic":["license-file"],"platform":null,"supported_platform":null,"summary":"SIGMA (Structurally-aware Intensity-ordered GMM-MRF Algorithm) is a microscopy toolkit for structural and dynamic analysis.","description":"# SIGMA (Structurally-aware Intensity-ordered GMM-MRF Algorithm)\n\n[![License: MIT](https://img.shields.io/pypi/l/napari-sigma.svg?color=green)](./LICENSE)\n[![PyPI](https://img.shields.io/pypi/v/napari-sigma.svg?color=green)](https://pypi.org/project/napari-sigma/)\n[![Python](https://img.shields.io/pypi/pyversions/napari-sigma.svg?color=green)](https://pypi.org/project/napari-sigma/)\n[![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/napari-sigma)](https://napari-hub.org/plugins/napari-sigma)\n[![npe2](https://img.shields.io/badge/napari-npe2-blue)](https://napari.org/stable/plugins/index.html)\n\nSIGMA is an annotation-free, image-adaptive napari framework for fluorescence image analysis. It combines an image-specific Gaussian mixture model (GMM) with intensity-ordered class assignment and a Markov random field (MRF) prior guided by local structural constraints derived from Hessian analysis. By estimating model parameters from each image, SIGMA is designed to retain faint or thin fluorescent structures while limiting mergers between closely apposed objects.\n\nIts four connected workflows quantify cellular morphology, dynamics, and spatial organization:\n\n- **Segmentation**: image-specific GMM-MRF segmentation guided by tubular or sheet-like structural responses\n- **Morphology Analysis**: object geometry, skeleton branches, endpoints, junctions, and network topology\n- **Tracking**: adjacent-frame object matching, remodeling-event classification, visualization, and link refinement\n- **Proximity Analysis**: image-resolution overlap, distance, Manders coefficients, and ROI-restricted spatial association\n\nSIGMA supports 2D, 3D, and time-series data and can run on CPU, CUDA, or Apple MPS when available.\n\n## Installation\n\nCreate a clean environment and install the published napari plugin:\n\n```bash\nconda create -n sigma python=3.11\nconda activate sigma\npip install --upgrade \"napari-sigma[all]\"\nnapari-sigma\n```\n\nThe `all` extra installs a compatible napari 0.9 release with the PyQt6 backend and napari's optional runtime dependencies. The `napari-sigma` launcher selects PyQt6 before napari imports Qt and ignores inherited plugin paths from other Qt installations for that process. Then select **SIGMA** from napari's **Plugins** menu.\n\nFor an existing installation, upgrade the complete extra rather than upgrading only napari:\n\n```bash\npython -m pip install --upgrade \"napari-sigma[all]\"\nnapari-sigma\n```\n\nPyQt5 does not normally need to be uninstalled: the launcher selects PyQt6 and its matching plugins before napari starts. It configures Qt only inside its own process and does not modify global environment variables. A fresh environment remains the safest recovery path for an environment with unrelated binary-level Qt conflicts. The standard `napari` command remains available when another backend is preferred.\n\nStarting with 0.0.4, SIGMA uses `opencv-python-headless`: image resizing and video export remain available, while napari supplies the GUI. Do not install multiple OpenCV variants together because they share the `cv2` namespace. When upgrading a dedicated SIGMA environment from an older release, remove the old OpenCV variants before reinstalling:\n\n```bash\npython -m pip uninstall opencv-python opencv-contrib-python opencv-contrib-python-headless opencv-python-headless\npython -m pip install --upgrade \"napari-sigma[all]\"\n```\n\nIf other applications in the same environment need OpenCV's own GUI, use a separate environment for SIGMA instead.\n\nOn minimal Ubuntu/Debian installations, Qt also needs system libraries that pip does not supply:\n\n```bash\nsudo apt-get install libegl1 libopengl0 libdbus-1-3 libxcb-cursor0 \\\n  libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 \\\n  libxcb-render-util0 libxcb-shape0 libxcb-glx0 libxcb-xinerama0 libxcb-xinput0 libxcb-xfixes0 \\\n  libxkbcommon-x11-0\n```\n\n### Development installation\n\nFrom the repository root:\n\n```bash\nconda create -n sigma-dev python=3.11\nconda activate sigma-dev\npip install -e \".[all]\"\nnapari-sigma\n```\n\n## Input data\n\nThe napari reader currently supports:\n\n- TIFF: `.tif`, `.tiff`\n- PNG: `.png`\n- JPEG: `.jpg`, `.jpeg`\n\nMicroscope container formats such as CZI, ND2, LIF, and LSM should first be exported to one of the supported formats.\n\nSIGMA preserves available physical-size and axis metadata. If physical size metadata is unavailable, pixel or voxel size defaults to `1.0`.\n\n## Quick start\n\n1. Start napari and open **Plugins > SIGMA**.\n2. In the **Segmentation** tab, select **Open File** and load a fluorescence image. TIFF is recommended when axis metadata or calibrated pixel and voxel sizes are needed.\n3. Confirm the interpreted channel, time, and slice ranges. Supported image organizations include `YX`, `ZYX`, `TYX`, and `TZYX`. Spatial 3D images open in napari's 3D display mode by default, while 2D time series remain in 2D.\n4. Review the physical scale under **Image Info** and correct it before any analysis that reports calibrated measurements.\n5. Select a computational device: **Auto** selects an available GPU when computation starts; **CPU**, **CUDA**, and **MPS** can also be requested explicitly. Unavailable devices fall back to CPU.\n6. Use **Segmentation** to extract local structural evidence and infer a binary foreground mask.\n7. Use **Morphology Analysis** to measure connected structures and their skeleton topology.\n8. For time series, use **Tracking** to associate objects across adjacent frames and classify linear, fission, fusion, or split-merge transitions.\n9. For aligned fluorescence channels, use **Proximity Analysis** to quantify spatial association between independently segmented structures.\n\nEach workflow operates on napari layers. Check the selected layer before running a command, especially when raw, processed, structural-response, and segmentation layers are open together. Results are returned as regular napari layers regardless of the selected computational device.\n\nStarting SIGMA does not reload or replace existing layers. Use **Open File** to load a file through SIGMA, or select the SIGMA reader in napari's normal opening flow. Plotting libraries and charts load when the Morphology Analysis tab is first opened; the first plot may need to build a font cache. Proximity runs in a background worker; clicking the computation action again requests cancellation.\n\n### Development checks\n\n```bash\npython -m unittest discover -s tests -v\n```\n\nGUI tests require a display (on headless Linux, use `xvfb-run -a`). Release builds are gated on regression tests on macOS/Linux and Python 3.11/3.13. See [CHANGELOG.md](./CHANGELOG.md) for changes that affect measurements and saved data.\n\n## Documentation\n\n- [Segmentation](./docs/segmentation.md)\n- [Morphology Analysis](./docs/morphology-analysis.md)\n- [Tracking](./docs/tracking.md)\n- [Proximity Analysis](./docs/proximity-analysis.md)\n\n## Example data\n\nThe repository includes example fluorescence data for every documented workflow. Segmentation and morphology use the same raw images; tracking and proximity analysis also include aligned segmentation inputs so those workflows can be run directly.\n\n- **2D segmentation and morphology:** [`2d_example_raw.tif`](./example/2d/2d_example_raw.tif)\n- **3D mitochondrial segmentation and morphology:** [`3d_example_Mitochondria.tif`](./example/3d/3d_example_Mitochondria.tif)\n- **3D ER segmentation and morphology:** [`3d_example_ER.tif`](./example/3d/3d_example_ER.tif)\n- **Tracking:** [`tracking_example.tif`](./example/Tracking/tracking_example.tif) and [`tracking_example_segmentation.tif`](./example/Tracking/tracking_example_segmentation.tif)\n- **Mitochondria-ER proximity assay:** [`mitochondria raw`](./example/Proximity_analysis/proximity_assay_example_mito.tif), [`mitochondria segmentation`](./example/Proximity_analysis/proximity_assay_example_mito_segmentation.tif), [`ER raw`](./example/Proximity_analysis/proximity_assay_example_ER.tif), and [`ER segmentation`](./example/Proximity_analysis/proximity_assay_example_ER_segmentation.tif)\n\nUse TIFF for workflows that depend on axis metadata or physical pixel and voxel sizes. Files used together must have matching spatial dimensions, time axes, physical scales, and, for proximity analysis, spatial alignment.\n\nFollow the corresponding guides for the complete examples:\n\n- [Segmentation](./docs/segmentation.md): 2D mitochondria, 3D mitochondria, and 3D ER\n- [Morphology Analysis](./docs/morphology-analysis.md): object and skeleton analysis of the same three datasets\n- [Tracking](./docs/tracking.md): adjacent-frame matching, event classification, visualization, and refinement\n- [Proximity Analysis](./docs/proximity-analysis.md): full-volume and ROI-restricted mitochondria-ER analysis\n\n## Segmentation\n\nThe Segmentation page contains five sections.\n\n### Data / Axes / Device\n\n- Open the source image.\n- Select CPU, CUDA, or MPS.\n- Select channel and frame ranges.\n- Review the interpreted axis layout.\n\n### Image Info\n\n- Review image shape, axes, and physical scale.\n- Apply corrected pixel or voxel sizes.\n\n### Preprocessing\n\n- Select the raw image layer used by preprocessing.\n- Optionally apply median filtering, Gaussian background subtraction, and XY upsampling before extraction.\n\n### Structural Awareness Extraction\n\n- Extract Hessian-derived vesselness, sheetness, or their voxelwise combined response.\n- Configure kernel radius, sigma range, PSF ratio, and response rescaling.\n- Run on the selected computational device.\n\n### GMM-MRF Segmentation\n\n- Select raw and structural-response layers.\n- Configure neighborhood smoothness and structure-weighted regularization.\n- Set the numbers of intensity-ordered foreground and background Gaussian components and the EM sampling budgets.\n- Run segmentation and return upsampled results to the original spatial resolution.\n\n## Morphology Analysis\n\nMorphology Analysis labels connected objects and provides calibrated 2D or 3D measurements:\n\n- object size and shape measurements\n- skeleton and branch statistics\n- endpoint and junction detection\n- branch-length distributions and topology summaries\n- object and branch table export\n\n## Tracking\n\nTracking operates on segmented time series under an adjacent-frame, minimum-displacement assumption and provides:\n\n- intensity-weighted point sampling and frame-to-frame matching\n- candidate-link costs based on distance, bidirectional coverage, and matched-point support\n- linear, fission, fusion, and split-merge event classification\n- matched-frame, event, and unlinked-object visualization\n- interactive link refinement with undo support\n- event table import and export\n\nThe **Max distance** control is expressed in the pixel or voxel units shown by the interface. Spatial anisotropy from the layer scale is incorporated into matching.\n\n## Proximity Analysis\n\nProximity Analysis compares source and target structures segmented independently in aligned fluorescence channels. It provides:\n\n- overlap and union measurements\n- Dice and Jaccard coefficients\n- Manders M1 and M2 coefficients\n- surface and nearest-distance measurements\n- full-image and polygon-ROI analysis\n- summary table export\n\nThese measurements describe spatial association at the image resolution. They do not estimate physical membrane separation or, by themselves, establish molecular contact.\n\n## Build validation\n\nBuild and validate the distribution locally:\n\n```bash\npython -m pip install --upgrade build twine\npython -m build\npython -m twine check dist/*\n```\n\n## Release process\n\nSIGMA is published as **`napari-sigma`**. The GitHub workflow uses PyPI Trusted Publishing; no long-lived PyPI API token is stored in the repository.\n\n1. Update `src/napari_sigma/_version.py`.\n2. Run the build validation commands above.\n3. Commit the release changes.\n4. Create and push a matching version tag, for example:\n\n```bash\ngit tag v0.0.1\ngit push origin v0.0.1\n```\n\nThe tag triggers distribution validation and publishes the built package to PyPI. The PyPI Trusted Publisher must be configured for this repository, the `test_and_deploy.yml` workflow, and the `pypi` environment.\n\n## Runtime dependencies\n\nCore runtime dependencies include napari, PyTorch, NumPy, SciPy, scikit-image, scikit-learn, OpenCV, tifffile, Pillow, matplotlib, dask, QtPy, and openpyxl. See [`pyproject.toml`](./pyproject.toml) for the authoritative version requirements.\n\n## License\n\nSIGMA is distributed under the [MIT License](./LICENSE).\n\n## Issues\n\nWhen reporting a problem, include:\n\n- operating system and hardware\n- Python, napari, Qt, and SIGMA versions\n- computational device (`cpu`, `cuda`, or `mps`)\n- input shape and axis interpretation\n- traceback or warning output\n","description_content_type":"text/markdown","keywords":"napari,microscopy,segmentation,morphology,tracking,proximity-analysis","home_page":null,"download_url":null,"author":null,"author_email":"Huibao Feng <fenghuibao@gmail.com>","maintainer":null,"maintainer_email":null,"license":null,"classifier":["Development Status :: 3 - Alpha","Framework :: napari","Intended Audience :: Developers","Operating System :: OS Independent","Programming Language :: Python","Programming Language :: Python :: 3","Programming Language :: Python :: 3 :: Only","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Topic :: Scientific/Engineering :: Image Processing"],"requires_dist":["dask[array]>=2024.1.0","matplotlib>=3.7.0","napari<0.10,>=0.9.0","numpy>=1.24.0","opencv-python-headless>=4.7.0","openpyxl>=3.1.0","pillow>=9.0.0","qtpy>=2.4.0","scikit-image>=0.20.0","scikit-learn>=1.3.0","scipy>=1.10.0","tifffile>=2023.1.1","torch>=2.0.0","napari[optional,pyqt6]<0.10,>=0.9.0; extra == \"all\""],"requires_python":">=3.11","requires_external":null,"project_url":["Homepage, https://github.com/fenghuibao/napari-sigma","Repository, https://github.com/fenghuibao/napari-sigma","Issues, https://github.com/fenghuibao/napari-sigma/issues"],"provides_extra":["all"],"provides_dist":null,"obsoletes_dist":null},"npe1_shim":false}