Update documentation (#82)

Author: constantinpape

README.md

@@ -7,52 +7,3 @@ In addition to the analysis functionality, CochleaNet implements data pre-proces
 This functionality is applicable to any imaging data from flamingo microscopes, not only clear-tissue data or cochleae. We aim to also extend the segmentation and analysis functionality to other kinds of samples imaged in the flamingo in the future.
 
 For installation and usage instructions, check out [the documentation](https://computational-cell-analytics.github.io/cochlea-net/). For more details on the underlying methodology check out [our preprint](https://doi.org/10.1101/2025.11.16.688700).
-
-<!---
-The `flamingo_tools` library implements functionality for:
-- converting the lightsheet data into a format compatible with [BigDataViewer](https://imagej.net/plugins/bdv/) and [BigStitcher](https://imagej.net/plugins/bigstitcher/).
-- Cell / nucleus segmentation via a 3D U-net.
-- ... and more functionality is planned!
-
-This is work in progress!
-
-
-## Requirements & Installation
-
-You need a python environment with the following dependencies: [pybdv](https://github.com/constantinpape/pybdv) and [z5py](https://github.com/constantinpape/z5).
-You install these dependencies with [mamba](https://github.com/mamba-org/mamba) or [conda](https://docs.conda.io/en/latest/) via: 
-```bash
-conda install -c conda-forge z5py pybdv cluster_tools
-```
-(for an existing conda environment). You can also set up a new environment with all required dependencies using the file `environment.yaml`:
-```bash
-conda env create -f environment.yaml
-```
-This will create the environment `flamingo`, which you can then activate via `conda activate flamingo`.
-Finally, to install `flamingo_tools` into the environment run
-```bash
-pip install -e .
-```
-
-## Usage
-
-We provide a command line tool, `convert_flamingo`, for converting data from the flamingo microscope to a data format compatible with BigDataViewer / BigStitcher:
-```bash
-convert_flamingo -i /path/to/data -o /path/to/output.n5 --file_ext .tif
-```
-Here, `/path/to/data` is the filepath to the folder with the flamingo data to be converted, `/path/to/output.n5` is the filepath where the converted data will be stored, and `--file_ext .tif` declares that the files are stored as tif stacks.
-Use `--file_ext .raw` isntead if the data is stored in raw files.
-
-The data will be converted to the [bdv.n5 format](https://github.com/bigdataviewer/bigdataviewer-core/blob/master/BDV%20N5%20format.md).
-It can be opened with BigDataViewer via `Plugins->BigDataViewer->Open XML/HDF5`.
-Or with BigStitcher as described [here](https://imagej.net/plugins/bigstitcher/open-existing).
-
-You can also check out the following example scripts:
-- `create_synthetic_data.py`: create small synthetic test data to check that the scripts work. 
-- `convert_flamingo_data_examples.py`: convert flamingo data to a file format comatible with BigDataViewer / BigStitcher with parameters defined in the python script. Contains two example functions:
-    - `convert_synthetic_data` to convert the synthetic data created via `create_synthetic_data.py`.
-    - `convert_flamingo_data_moser` to convert sampled flamingo data from the Moser group.
-- `load_data.py`: Example script for how to load sub-regions from the converted data into python.
-
-For advanced examples to segment data with a U-Net, check out the `scripts` folder.
---->

doc/documentation.md

@@ -60,25 +60,55 @@ CochleaNet can be used via:
 ### Napari Plugin
 
 The plugins for segmentation (SGNs and IHCS) and detection (ribbon synapses) is available under `Plugins->CochleaNet->Segmentation/Detection` in napari:
+<img src="https://raw.githubusercontent.com/computational-cell-analytics/cochlea-net/refs/heads/master/doc/img/cochlea-net-plugin-selection.png" alt="The CochleaNet plugins available in napari.">
+
 
 The segmentation plugin offers the choice of different models under `Select Model:` (see [Available Models](#available-models) for details). `Image data` enables the choice which image data (napari layer) the model is applied to.
 The segmentation is started by clicking the `Run Segmentation` button. After the segmentation has finished, a new segmentation layer with the result (here `IHC`) will be added:
+<img src="https://raw.githubusercontent.com/computational-cell-analytics/cochlea-net/refs/heads/master/doc/img/cochlea-net-plugin-segmentation.png" alt="The CochleaNet segmentation plugin." width="768">
 
-The detection model works similarly. It currently provides the model for synapse detection. The predictions are added as a point layer (``):
+The detection model works similarly. It currently provides the model for synapse detection. The predictions are added as a point layer (`Synapses`):
+<img src="https://raw.githubusercontent.com/computational-cell-analytics/cochlea-net/refs/heads/master/doc/img/cochlea-net-plugin-detection.png" alt="The CochleaNet detection plugin." width="768">
 
 For more information on how to use napari, check out the tutorials at [www.napari.org](https://napari.org/stable/).
 
 **To use the napari plugin you have to install `napari` and `pyqt` in your environment. See [installation](#installation) for details.**
 
 ### Command Line Interface
 
-TODO
+The command line interface provides the following commands:
+
+`flamingo_tools.convert_data`: Convert data from a flamingo microscope into the [bdv.n5 format](https://github.com/bigdataviewer/bigdataviewer-core/blob/master/BDV%20N5%20format.md) (compatible with  [BigStitcher](https://imagej.net/plugins/bigstitcher/)) or into [ome.zarr format](https://ngff.openmicroscopy.org/). You can use this command as follows:
+```bash
+flamingo_tools.convert_data -i /path/to/data -o /path/to/output.n5 --file_ext .tif
+```
+Use `--file_ext .raw` instead if the data is stored in raw files. By default, the data will be exported to the n5 format. It can be opened with BigDataViewer via `Plugins->BigDataViewer->Open XML/HDF5` or with BigStitcher as described [here](https://imagej.net/plugins/bigstitcher/open-existing).
+
+`flamingo_tools.run_segmentation`: To segment cells in volumetric light microscopy data.
+
+`flamingo_tools.run_detection`: To detect synapses in volumetric light microscopy data.
+
+For more information on any of the command run `flamingo_tools.<COMMAND> -h` (e.g. `flamingo_tools.run_segmentation -h`) in your terminal.
 
 ### Python Library
 
-TODO
+CochleaNet's functionality is implemented in the `flamingo_tools` python library. It implements:
+- `measurements`: functionality to measure morphological attributes and intensity statistics for segmented cells.
+- `mobie`: functionality to export flamingo image data or segmentation results to a MoBIE project.
+- `segmentation`: functionality to apply segmentation and detection models to large volumetric image data.
+- `training`: functionality to train segmentation and detection networks.
 
 
 ## Available Models
 
-TODO
+CochleaNet provides five different models:
+- `SGN`: for segmenting spiral ganglion neurons (SGNs) in high-resolution, isotropic light-sheet microscopy data.
+    - This model was trained on image data with parvalbumin (PV) stain, with a voxel size of 0.38 micrometer.
+- `IHC`: for segmenting inner hair cells (IHCs) in high-resolution, isotropic light-sheet microscopy data.
+    - This model was trained on image data with Vglut3 stain, with a voxel size of 0.38 micrometer.
+- `Synapses`: for detecting afferent ribbon synapses in high-resolution isotropic light-sheet microscopy data.
+    - This model was trained on image data with CtBP2 stain, with a voxel size of 0.38 micrometer.
+- `SGN-lowres`: for segmenting SGNS in lower-resolution, anisotropic light-sheet microscopy data.
+    - This model was trained on image data with PV stain, with a voxel size of 0.76 X 0.76 X 3.0 micrometer.
+- `SGN-lowres`: for segmenting SGNS in lower-resolution, anisotropic light-sheet microscopy data.
+    - This model was trained on image data with Myosin VIIa stain, with a voxel size of 0.76 X 0.76 X 3.0 micrometer.

flamingo_tools/classification/__init__.py

@@ -1,2 +1,5 @@
+"""@private
+"""
+
 from .classification_gui import run_classification_gui
 from .training_and_prediction import train_classifier, predict_classifier

flamingo_tools/data_conversion.py

@@ -1,3 +1,6 @@
+"""Functionality for converting data from flamingo microscopes to other data formats.
+"""
+
 import multiprocessing as mp
 import os
 import re

flamingo_tools/extract_block_util.py

@@ -1,3 +1,6 @@
+"""@private
+"""
+
 import os
 from typing import Optional, List, Union, Tuple
 

flamingo_tools/file_utils.py

@@ -1,3 +1,6 @@
+"""Utilities for reading image data.
+"""
+
 import os
 import warnings
 from typing import Optional, Union

flamingo_tools/measurements.py

@@ -1,3 +1,6 @@
+"""Functionality for measuring morphology and fluorescence intensities of segmented cells.
+"""
+
 import multiprocessing as mp
 import os
 import warnings

flamingo_tools/mobie.py

@@ -1,3 +1,6 @@
+"""Functionality for exporting data to a MoBIE project.
+"""
+
 import os
 import multiprocessing as mp
 import tempfile

flamingo_tools/model_utils.py

@@ -1,3 +1,6 @@
+"""Utility functionality for downloading CochleaNet models.
+"""
+
 import os
 from typing import Dict, Optional, Union
 

flamingo_tools/plugin/__init__.py

@@ -0,0 +1,2 @@
+"""@private
+"""