Doc updates (#71)

Update documentation and function doc strings

Author: constantinpape

README.md

@@ -1,21 +1,10 @@
-# Synaptic Reconstruction
+# SynapseNet: Deep Learning for Automatic Synapse Reconstruction
 
-Reconstruction of synaptic structures in electron microscopy.
+SynapseNet is a tool for segmentation and analysis of synapses in electron microscopy.
 
-THIS IS WORK IN PROGRESS!
+To learn how to use SynapseNet, check out [the documentation](https://computational-cell-analytics.github.io/synapse-net/).
+To learn more about how it works, check out [our preprint](TODO).
 
-## Installation
-
-- Make sure conda or mamba is installed.
-    - If you don't have a conda installation yet we recommend [micromamba](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html)
-- Create the environment with all required dependencies: `mamba env create -f environment.yaml`
-- Activate the environment: `mamba activate synaptic-reconstruction`
-- Install the package: `pip install -e .`
-
-## Tools
-
-### Segmentation Correction
-
-https://napari.org/stable/howtos/layers/labels.html
-
-### Distance Measurements
+See an example reconstruction of a mossy fibre synapse with SynapseNet.
+Automatic segmentation of synaptic vesicles are rendered in orange, active zones in blue and two mitochondria in red and cyan.
+![Reconstruction of a mossy fiber synapse](doc/images/synapse-reconstruction.png)

doc/images/synapse-reconstruction.png

@@ -1,2 +1,57 @@
-# Synaptic Reconstruction
-lorem ipsum...
+# SynapseNet: Deep Learning for Automatic Synapse Reconstruction
+
+SynapseNet is a tool for automatic segmentation and analysis of synapses in electron micrographs.
+It provides deep neural networks for:
+- Synaptic vesicle segmentation in ssTEM (2d data) and (cryo-)electron tomography (3d data)
+- Active zone membrane segmentation in electron tomography
+- Mitochondrion segmentation in electron tomography
+- Synaptic compartment segmentation in electron tomography
+- Synaptic ribbon and pre-synaptic density segmentation for ribbon synapses in electron tomography
+It also offers functionality for quantifying synaptic ultrastructure based on segmentation results, for example by measuring vesicle or structure morphology, measuring distances between vesicles and structures, or assigning vesicles into different pools.
+SynapseNet mainly targets electron tomography, but can also be appled to other types of electron microscopy,
+especially throught the [domain adaptation](domain-adaptation) functionality.
+
+SynapseNet offers a [napari plugin](napari-plugin), [command line interface](command-line-interface), and [python library](python-library).
+Please cite our [bioRxiv preprint](TODO) if you use it in your research.
+
+**The rest of the documentation will be updated in the next days!**
+
+## Requirements & Installation
+
+- Requirements: Tested on Linux but should work on Mac/Windows.
+    - GPU needed to use 3d segmentation networks
+- Installation via conda and local pip install
+    - GPU support
+
+- Make sure conda or mamba is installed.
+    - If you don't have a conda installation yet we recommend [micromamba](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html)
+- Create the environment with all required dependencies: `mamba env create -f environment.yaml`
+- Activate the environment: `mamba activate synaptic-reconstruction`
+- Install the package: `pip install -e .`
+
+## Napari Plugin
+
+lorem ipsum
+
+## Command Line Functionality
+
+- segmentation cli
+- export to imod
+    - vesicles / spheres
+    - objects
+
+## Python Library
+
+- segmentation functions
+- distance and morphology measurements
+- imod
+
+### Domain Adaptation
+
+- explain domain adaptation
+- link to the example script
+
+### Network Training
+
+- explain / diff to domain adaptation
+- link to the example script

doc/start_page.md

@@ -75,6 +75,7 @@ def eval_compartments():
     print("Compartment Evaluation:")
     print("Avergage pieces per compartment:", avg, "+-", std)
     print("Max pieces per compartment:", max_)
+    print("Number of compartments:", len(pieces_per_compartment))
 
 
 def eval_mitos():
@@ -124,11 +125,11 @@ def check_mitos():
 def main():
     # check_mitos()
 
-    eval_mitos()
-    print()
+    # eval_mitos()
+    # print()
     eval_compartments()
-    print()
-    eval_az()
+    # print()
+    # eval_az()
 
 
 main()

scripts/cooper/full_reconstruction/qualitative_evaluation.py

@@ -10,8 +10,9 @@
 
 from synaptic_reconstruction.file_utils import get_data_path
 from synaptic_reconstruction.distance_measurements import (
-    measure_segmentation_to_object_distances,
     filter_blocked_segmentation_to_object_distances,
+    load_distances,
+    measure_segmentation_to_object_distances,
 )
 
 from synaptic_reconstruction.morphology import compute_radii, compute_object_morphology
@@ -172,8 +173,9 @@ def load_dist(measurement_path, seg_ids=None):
 
     # Filter out the blocked vesicles.
     if apply_extra_filters:
+        rav_dists, ep1, ep2, all_rav_ids = load_distances(distance_paths["ribbon"])
         rav_ids = filter_blocked_segmentation_to_object_distances(
-            vesicles, distance_paths["ribbon"], seg_ids=rav_ids, line_dilation=4, verbose=True,
+            vesicles, rav_dists, ep1, ep2, all_rav_ids, filter_seg_ids=rav_ids, line_dilation=4, verbose=True,
         )
         rav_ids = filter_border_vesicles(vesicles, seg_ids=rav_ids)
 

scripts/inner_ear/processing/run_analyis.py

@@ -1,6 +1,6 @@
 import os
 import multiprocessing as mp
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, List, Optional, Tuple, Union
 
 import numpy as np
 
@@ -18,7 +18,25 @@
     skfmm = None
 
 
-def compute_geodesic_distances(segmentation, distance_to, resolution=None, unsigned=True):
+def compute_geodesic_distances(
+    segmentation: np.ndarray,
+    distance_to: np.ndarray,
+    resolution: Optional[Union[int, float, Tuple[int, int, int]]] = None,
+    unsigned: bool = True,
+) -> np.ndarray:
+    """Compute the geodesic distances between a segmentation and a distance target.
+
+    This function require scikit-fmm to be installed.
+
+    Args:
+        segmentation: The binary segmentation.
+        distance_to: The binary distance target.
+        resolution: The voxel size of the data, used to scale the distances.
+        unsigned: Whether to return the unsigned or signed distances.
+
+    Returns:
+        Array with the geodesic distance values.
+    """
     assert skfmm is not None, "Please install scikit-fmm to use compute_geodesic_distance."
 
     invalid = segmentation == 0
@@ -43,14 +61,12 @@ def compute_geodesic_distances(segmentation, distance_to, resolution=None, unsig
     return distances
 
 
-# TODO update this
 def _compute_centroid_distances(segmentation, resolution, n_neighbors):
-    # TODO enable eccentricity centers instead
     props = regionprops(segmentation)
     centroids = np.array([prop.centroid for prop in props])
     if resolution is not None:
-        pass  # TODO scale the centroids
-
+        scale_factor = np.array(resolution)[:, None]
+        centroids *= scale_factor
     pair_distances = pairwise_distances(centroids)
     return pair_distances
 
@@ -313,11 +329,13 @@ def create_pairwise_distance_lines(
         endpoints1: One set of distance end points.
         endpoints2: The other set of distance end points.
         seg_ids: The segmentation pair corresponding to each distance.
-        n_neighbors: ...
-        pairs: ...
-        bb: ....
-        scale: ...
-        remove_duplicates: ...
+        n_neighbors: The number of nearest neighbors to take into consideration
+            for creating the distance lines.
+        pairs: Optional list of ids to use for creating the distance lines.
+        bb: Bounding box for restricing the distance line creation.
+        scale: Scale factor for resizing the distance lines.
+            Use this if the corresponding segmentations were downscaled for visualization.
+        remove_duplicates: Remove duplicate id pairs from the distance lines.
 
     Returns:
         The lines for plotting in napari.
@@ -386,8 +404,10 @@ def create_object_distance_lines(
         endpoints1: One set of distance end points.
         endpoints2: The other set of distance end points.
         seg_ids: The segmentation ids corresponding to each distance.
-        max_distance: ...
-        scale: ...
+        max_distance: Maximal distance for drawing the distance line.
+        filter_seg_ids: Segmentation ids to restrict the distance lines.
+        scale: Scale factor for resizing the distance lines.
+            Use this if the corresponding segmentations were downscaled for visualization.
 
     Returns:
         The lines for plotting in napari.
@@ -416,13 +436,32 @@ def create_object_distance_lines(
     return lines, properties
 
 
-def keep_direct_distances(segmentation, measurement_path, line_dilation=0, scale=None):
-    """Filter out all distances that are not direct.
-    I.e. distances that cross another segmented object.
-    """
+def keep_direct_distances(
+    segmentation: np.ndarray,
+    distances: np.ndarray,
+    endpoints1: np.ndarray,
+    endpoints2: np.ndarray,
+    seg_ids: np.ndarray,
+    line_dilation: int = 0,
+    scale: Optional[Tuple[int, int, int]] = None,
+) -> List[List[int, int]]:
+    """Filter out all distances that are not direct; distances that are occluded by another segmented object.
 
-    distances, ep1, ep2, seg_ids = load_distances(measurement_path)
-    distance_lines, properties = create_object_distance_lines(distances, ep1, ep2, seg_ids, scale=scale)
+    Args:
+        segmentation: The segmentation from which the distances are derived.
+        distances: The measurd distances.
+        endpoints1: One set of distance end points.
+        endpoints2: The other set of distance end points.
+        seg_ids: The segmentation ids corresponding to each distance.
+        line_dilation: Dilation factor of the distance lines for determining occlusions.
+        scale: Scaling factor of the segmentation compared to the distance measurements.
+
+    Returns:
+        The list of id pairs that are kept.
+    """
+    distance_lines, properties = create_object_distance_lines(
+        distances, endpoints1, endpoints2, seg_ids, scale=scale
+    )
 
     ids_a, ids_b = properties["id_a"], properties["id_b"]
     filtered_ids_a, filtered_ids_b = [], []
@@ -459,10 +498,35 @@ def keep_direct_distances(segmentation, measurement_path, line_dilation=0, scale
 
 
 def filter_blocked_segmentation_to_object_distances(
-    segmentation, measurement_path, line_dilation=0, scale=None, seg_ids=None, verbose=False,
-):
-    distances, ep1, ep2, seg_ids = load_distances(measurement_path)
-    distance_lines, properties = create_object_distance_lines(distances, ep1, ep2, seg_ids, scale=scale)
+    segmentation: np.ndarray,
+    distances: np.ndarray,
+    endpoints1: np.ndarray,
+    endpoints2: np.ndarray,
+    seg_ids: np.ndarray,
+    line_dilation: int = 0,
+    scale: Optional[Tuple[int, int, int]] = None,
+    filter_seg_ids: Optional[List[int]] = None,
+    verbose: bool = False,
+) -> List[int]:
+    """Filter out all distances that are not direct; distances that are occluded by another segmented object.
+
+    Args:
+        segmentation: The segmentation from which the distances are derived.
+        distances: The measurd distances.
+        endpoints1: One set of distance end points.
+        endpoints2: The other set of distance end points.
+        seg_ids: The segmentation ids corresponding to each distance.
+        line_dilation: Dilation factor of the distance lines for determining occlusions.
+        scale: Scaling factor of the segmentation compared to the distance measurements.
+        filter_seg_ids: Segmentation ids to restrict the distance lines.
+        verbose: Whether to print progressbar.
+
+    Returns:
+        The list of id pairs that are kept.
+    """
+    distance_lines, properties = create_object_distance_lines(
+         distances, endpoints1, endpoints2, seg_ids, scale=scale
+    )
     all_seg_ids = properties["id"]
 
     filtered_ids = []

synaptic_reconstruction/distance_measurements.py

@@ -1,7 +1,17 @@
 import os
+from typing import List, Optional, Union
 
 
-def get_data_path(folder, n_tomograms=1):
+def get_data_path(folder: str, n_tomograms: Optional[int] = 1) -> Union[str, List[str]]:
+    """Get the path to all tomograms stored as .rec or .mrc files in a folder.
+
+    Args:
+        folder: The folder with tomograms.
+        n_tomograms: The expected number of tomograms.
+
+    Returns:
+        The filepath or list of filepaths of the tomograms in the folder.
+    """
     file_names = os.listdir(folder)
     tomograms = []
     for fname in file_names:
@@ -11,7 +21,5 @@ def get_data_path(folder, n_tomograms=1):
 
     if n_tomograms is None:
         return tomograms
-
     assert len(tomograms) == n_tomograms, f"{folder}: {len(tomograms)}, {n_tomograms}"
-
     return tomograms[0] if n_tomograms == 1 else tomograms

synaptic_reconstruction/file_utils.py

@@ -0,0 +1 @@
+edge_filter.py

synaptic_reconstruction/ground_truth/.gitignore

@@ -4,7 +4,21 @@
 from skimage.segmentation import relabel_sequential
 
 
-def find_additional_objects(ground_truth, segmentation, matching_threshold=0.5):
+def find_additional_objects(
+    ground_truth: np.ndarray,
+    segmentation: np.ndarray,
+    matching_threshold: float = 0.5
+) -> np.ndarray:
+    """Compare ground-truth annotations with a segmentation to find objects not in the annotation.
+
+    Args:
+        ground_trut:
+        segmentation:
+        matching_threshold:
+
+    Returns:
+    """
+
     segmentation = relabel_sequential(segmentation)[0]
 
     # Match the objects in the segmentation to the ground-truth.