Metadata-Version: 2.4
Name: napari-spofi
Version: 0.0.4
Summary: napari plugin to interactively train and test a StarDist model
Author: Christian Schulze
Author-email: drchrisch@gmail.com
License: BSD-3-Clause
Project-URL: Bug Tracker, https://github.com/drchrisch/napari-spofi/issues
Project-URL: Documentation, https://github.com/drchrisch/napari-spofi#README.md
Project-URL: Source Code, https://github.com/drchrisch/napari-spofi
Project-URL: User Support, https://github.com/drchrisch/napari-spofi/issues
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: napari
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: magicgui
Requires-Dist: qtpy
Requires-Dist: scikit-image
Requires-Dist: pyclesperanto
Requires-Dist: tensorflow
Requires-Dist: stardist
Provides-Extra: testing
Requires-Dist: tox; extra == "testing"
Requires-Dist: napari; extra == "testing"
Requires-Dist: pyqt5; extra == "testing"
Dynamic: license-file

# napari-spofi

[![License BSD-3](https://img.shields.io/pypi/l/napari-spofi.svg?color=green)](https://github.com/githubuser/napari-spofi/raw/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/napari-spofi.svg?color=green)](https://pypi.org/project/napari-spofi)
[![Python Version](https://img.shields.io/pypi/pyversions/napari-spofi.svg?color=green)](https://python.org)
[![tests](https://github.com/githubuser/napari-spofi/workflows/tests/badge.svg)](https://github.com/githubuser/napari-spofi/actions)
[![codecov](https://codecov.io/gh/githubuser/napari-spofi/branch/main/graph/badge.svg)](https://codecov.io/gh/githubuser/napari-spofi)
[![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/napari-spofi)](https://napari-hub.org/plugins/napari-spofi)

napari plugin to interactively train and test a StarDist model

----------------------------------

This [napari] plugin was generated with [Cookiecutter] using [@napari]'s [cookiecutter-napari-plugin] template.

<!--
Don't miss the full getting started guide to set up your new package:
https://github.com/napari/cookiecutter-napari-plugin#getting-started


and review the napari docs for plugin developers:
https://napari.org/stable/plugins/index.html
-->

## Description

This plugin provides tools for annotating spots in a 3D two-channel image (hdf5 type input file),
submitting tiles for StarDist model generation or model re-training, and refining initial annotations
based on predictions (kind of human-in-the-loop approach).

The objects of interest in the image are sphere-like spots with a diameter of just a
few pixels and are thus well suited for StarDist instance segmentation. The image 
dimensions are typically 1024x1024 pixels in xy and ≥ 64 sections in z.

## Installation

With python and pip installed (e.g., via miniconda or miniforge),
it is recommended to create a new environment and install `napari-spofi` using pip.

    pip install napari napari-spofi

## Starting `napari-spofi`

Start `napari` and select "spot finder (napari-spofi)" from the "plugin" menu.

### Annotate image
One should start the model generation with processed images (background removed, denoised, ...).
Go to the 'annotation' section of the widget and create a new directory for annotations. Add an image
folder containing at least one h5 file containing dataframes with foreground and background signals (e.g., 'ch1_processed' & 'ch2_processed') (default names can be changed in resources/spofi_defaults.json).
Select an image file, chose foreground and background channels. Load the image file.

Inspect the image for distinct regions. To help locate relevant tile positions, make
the 'checkerboard' layer visible. While the 'tiles' layer is active, double-click a tile
to add it to the list of tiles to process. This list will be used to generate a set of 
images and masks for training purposes.

Switch to napari's 2D view. Navigate to the centre section of each spot in the active tile
and annotate by adding points (one point per spot) using the 'true' points layer. 
Annotate tiles in one or multiple images.
Click the 'extract spots' button to prepare training data. First, the algorithm tries to find the maximum intensity position in the manually assigned spot region.
Then a spot mask is generated using one of the two available procedures. Either, pixels with relative minimal intensities as given by the intensity threshold are used to
define the spot area. Alternatively a watershed segmentation on the difference of Gaussians filtered foreground image is used.
In both cases, the procedures focus in on a sub-region around annotated spot positions.

There is a "suggest spots" option that uses a Laplacian of Gaussian method to locate spots. This may be used as a first step to aid manual annotation.

### Train a StarDist model
Go to the 'training' section of the widget. Adjust the "number of epochs". For a first
check, 100 epochs is a good start. The plugin uses a simplified setup for StarDist
configurations (please see [StarDist](https://github.com/stardist/stardist/) for a full discussion).

Start training and watch the 'loss' and 'val_loss' values, which should decrease
steadily while their ratio should roughly remain at 1 as training progresses.

The retrain option allows the selection of an existing model for retraining.

### Predict instances
Go to the 'prediction' section of the widget to start spot prediction for the
currently loaded image. Select the appropriate model from the given annotation
directory. The 'threshold' value is calculated from the validation data and can be
adjusted. Start a new prediction and load the predicted spots when the process has
finished. (It is possible to load an existing prediction).

### Polish annotation
Predicted spots will be loaded into a new layer 'predicted'. The
'predicted' layer is not editable and gives an overview of the spots found. Check
your annotation in the active tiles ('true' layer).
Adjust the positions of the spots or remove any incorrect spots from the 'true'
layer. Extract the spots and train a new model or retrain the model.

## Contributing

Contributions are very welcome.

## License

Distributed under the terms of the [BSD-3] license,
"napari-spofi" is free and open source software

## Issues

If you encounter any problems, please file an issue along with a detailed description.

[napari]: https://github.com/napari/napari
[Cookiecutter]: https://github.com/audreyr/cookiecutter
[@napari]: https://github.com/napari
[MIT]: http://opensource.org/licenses/MIT
[BSD-3]: http://opensource.org/licenses/BSD-3-Clause
[GNU GPL v3.0]: http://www.gnu.org/licenses/gpl-3.0.txt
[GNU LGPL v3.0]: http://www.gnu.org/licenses/lgpl-3.0.txt
[Apache Software License 2.0]: http://www.apache.org/licenses/LICENSE-2.0
[Mozilla Public License 2.0]: https://www.mozilla.org/media/MPL/2.0/index.txt
[cookiecutter-napari-plugin]: https://github.com/napari/cookiecutter-napari-plugin

[napari]: https://github.com/napari/napari
[tox]: https://tox.readthedocs.io/en/latest/
[pip]: https://pypi.org/project/pip/
[PyPI]: https://pypi.org/
