napari-mapzebrain-segmentation

A napari plugin for exploring and interacting with the mapzebrain zebrafish brain atlas created by the Baier lab, Max Planck Institute for Biological Intelligence. Functions are also available to create new segmentation masks or region definitions in napari using the atlas. See more usage documentation in our plugin documentation.

Disclaimer -- Beta version

This plugin is currently in beta and under active development. We invite users to explore, test, and contribute, but please be aware of the following:

• Work in progress: The plugin is not yet feature-complete and may contain bugs, unfinished features, or unstable behavior.
• Breaking changes possible: Functionality and behavior may change, and backward compatibility is not guaranteed during this phase.
• Limited documentation: Current documentation is minimal and maintained via Google Docs an in plugin tooltips. A more comprehensive solution (e.g., ReadTheDocs) may be introduced in the future.

Basic guidance for installation and usage is available. If you encounter any issues or have ideas for improvement, feedback, bug reports, and contributions are warmly welcomed.

Reporting bugs, or making feature requests

If you encounter any bugs, or have ideas for new features, please file an issue on GitHub. For bugs, please include a detailed description of the problem, and if possible, a minimal reproducible example. If you are interested in contributing to the plugin, please see the contributing section below.

Installation

The plugin is currently tested on Python version 3.10, and napari version 0.4.19. It is recommended to use a virtual environment to install the plugin with these two versions. The plugin is not yet available on the napari-hub, so it must be installed from this repository.

Installing napari

If you haven't already, install napari. napari can be installed as a standalone executable, or as a Python package through conda or pip. Installation as a Python package is recommended. Detailed instructions are available in the napari installation guide, but as an example:

conda create -y -n napari-env -c conda-forge python=3.10
conda activate napari-env
conda install -c conda-forge napari=0.4.19 pyqt
conda update napari

Installing the plugin

While the plugin is not public, you can install it from the repository by either cloning the repository and installing it with pip:

git clone https://github.com/MetaCell/napari-mapzebrain-segmentation.git
cd napari-mapzebrain-segmentation
pip install .

If it is a struggle to clone the repository due to permissions, you could consider instead using the GitHub CLI, see installation notes here.

gh repo clone MetaCell/napari-mapzebrain-segmentation
cd napari-mapzebrain-segmentation
pip install .

Or directly from the repository:

pip install git+https://github.com/MetaCell/napari-mapzebrain-segmentation.git

When the plugin is made public, it will be available on the napari-hub. At that point, it can be installed from a GUI menu inside of napari, or via the command

pip install napari-mapzebrain-segmentation

Updating the plugin

cd napari-mapzebrain-segmentation
git pull
pip install .

Usage

To start up napari with the plugin:

python examples/start_napari_mapzebrain.py

Alteratively, you can use the plugin within napari from the plugin menu. See more documentation here.

Features

Feature	Status
Load markers from Mapzebrain API	✅
Load brain reference from Mapzebrain API	✅
Load regions one at a time from Mapzebrain API	✅
Modify existing region boundaries	✅
Save regions to new tiff files in Mapzebrain format	✅
Cache downloaded files to avoid repeated downloads	✅
Set a local region hierarchy and region masks outside of the API	✅
Combine all region annotations into a single mask	✅
Region hierarchy visualisation	✅
Update region hierarchy within napari	✅
Load region data from heirarchy or combined mask	✅
Mirror regions across midline	✅
Erode and dilate regions (optionally within the bounds of another mask)	✅
Remove stray pixels in a region mask	✅
Save region hierarchy to a new file	✅
Create splines for region boundaries	✅
Estimate region boundaries from a set of shapes spaced along Z	✅
Fill between slices along Z for region boundaries	✅
Work with shapes created from coronal, dorsal, and sagittal reference	✅

Contributing

Clone the package, install in editable mode:

git clone https://github.com/MetaCell/napari-mapzebrain-segmentation.git
cd napari-mapzebrain-segmentation
pip install -e ".[develop, testing]"

Formatting, testing, and linting:

ruff format .
ruff check .
pytest . --disable-warnings -vv -s

Unit testing coverage:

pytest --cov=napari_mapzebrain_segmentation .
coverage report -m --omit="*/_tests/*" 

Mypy type checking:

pip install mypy
mypy --install-types
mypy src/ --ignore-missing-imports --exclude=".*_tests.*" --disable-error-code=misc

License

Distributed under the terms of the BSD-3 license, "napari-mapzebrain-segmentation" is free and open source software