Merge pull request #152 from computational-cell-analytics/doc-updates

Documentation updates

Author: constantinpape

doc/annotation_tools.md

@@ -105,7 +105,7 @@ You can activate tiling by passing the parameters `tile_shape`, which determines
     - If you're using the command line functions you can pass them via the options `--tile_shape 1024 1024 --halo 128 128`
     - Note that prediction with tiling only works when the embeddings are cached to file, so you must specify an `embedding_path` (`-e` in the CLI).
     - You should choose the `halo` such that it is larger than half of the maximal radius of the objects your segmenting.
-- The applications pre-compute the image embeddings produced by SegmentAnything and (optionally) store them on disc. If you are using a CPU this step can take a while for 3d data or timeseries (you will see a progress bar with a time estimate). If you have access to a GPU without graphical interface (e.g. via a local computer cluster or a cloud provider), you can also pre-compute the embeddings there and then copy them to your laptop / local machine to speed this up. You can use the command `micro_sam.precompute_embeddings` for this (it is installed with the rest of the applications). You can specify the location of the precomputed embeddings via the `embedding_path` argument.
+- The applications pre-compute the image embeddings produced by SegmentAnything and (optionally) store them on disc. If you are using a CPU this step can take a while for 3d data or timeseries (you will see a progress bar with a time estimate). If you have access to a GPU without graphical interface (e.g. via a local computer cluster or a cloud provider), you can also pre-compute the embeddings there and then copy them to your laptop / local machine to speed this up. You can use the command `micro_sam.precompute_state` for this (it is installed with the rest of the applications). You can specify the location of the precomputed embeddings via the `embedding_path` argument.
 - Most other processing steps are very fast even on a CPU, so interactive annotation is possible. An exception is the automatic segmentation step (2d segmentation), which takes several minutes without a GPU (depending on the image size). For large volumes and timeseries segmenting an object in 3d / tracking across time can take a couple settings with a CPU (it is very fast with a GPU).
 - You can also try using a smaller version of the SegmentAnything model to speed up the computations. For this you can pass the `model_type` argument and either set it to `vit_b` or to `vit_l` (default is `vit_h`). However, this may lead to worse results.
 - You can save and load the results from the `committed_objects` / `committed_tracks` layer to correct segmentations you obtained from another tool (e.g. CellPose) or to save intermediate annotation results. The results can be saved via `File -> Save Selected Layer(s) ...` in the napari menu (see the tutorial videos for details). They can be loaded again by specifying the corresponding location via the `segmentation_result` (2d and 3d segmentation) or `tracking_result` (tracking) argument.

doc/installation.md

@@ -30,9 +30,9 @@ Once you have it installed you can simply replace the `conda` commands with `mam
 ## From installer
 
 We also provide installers for Linux, Mac and Windows:
-- [Linux](https://owncloud.gwdg.de/index.php/s/HRp948SDkaWzCuV)
-- [Mac](https://owncloud.gwdg.de/index.php/s/HpGzlXrgJ8VDgnI)
-- [Windows](https://owncloud.gwdg.de/index.php/s/BVipOmDPR2TXmxk)
+- [Linux](https://owncloud.gwdg.de/index.php/s/Cw9RmA3BlyqKJeU)
+- [Mac](https://owncloud.gwdg.de/index.php/s/7YupGgACw9SHy2P)
+- [Windows](https://owncloud.gwdg.de/index.php/s/1iD1eIcMZvEyE6d)
 
 Note that these installers are stil experimental and not yet fully tested.
 If you encounter problems with them then please consider installing `micro_sam` via [conda](#from-conda) instead.

doc/python_library.md

@@ -12,8 +12,18 @@ The library
 - provides functionality for quantitative and qualitative evaluation of Segment Anything models in `micro_sam.evaluation`.
 
 This functionality is used to implement the interactive annotation tools and can also be used as a standalone python library.
-Check out the documentation under `Submodules` for more details.
+Some preliminary examples for how to use the python library can be found [here](https://github.com/computational-cell-analytics/micro-sam/tree/master/examples/use_as_library). Check out the `Submodules` documentation for more details.
 
 ## Training your own model
 
-TODO
+We reimplement the training logic described in the [Segment Anything publication](https://arxiv.org/abs/2304.02643) to enable finetuning on custom data.
+We use this functionality to provide the [finetuned microscopy models](#finetuned-models) and it can also be used to finetune models on your own data.
+In fact the best results can be expected when finetuning on your own data, and we found that it does not require much annotated training data to get siginficant improvements in model performance.
+So a good strategy is to annotate a few images with one of the provided models using one of the interactive annotation tools and, if the annotation is not working as good as expected yet, finetune on the annotated data.
+<!--
+TODO: provide link to the paper with results on how much data is needed
+-->
+
+The training logic is implemented in `micro_sam.training` and is based on [torch-em](https://github.com/constantinpape/torch-em). Please check out [examples/finetuning](https://github.com/computational-cell-analytics/micro-sam/tree/master/examples/finetuning) to see how you can finetune on your own data with it. The script `finetune_hela.py` contains an example for finetuning on a small custom microscopy dataset and `use_finetuned_model.py` shows how this model can then be used in the interactive annotatin tools.
+
+More advanced examples, including quantitative and qualitative evaluation, of finetuned models can be found in [finetuning](https://github.com/computational-cell-analytics/micro-sam/tree/master/finetuning), which contains the code for training and evaluating our microscopy models.

micro_sam/evaluation/__init__.py

@@ -1,3 +1,6 @@
+"""Functionality for evaluating Segment Anything models on microscopy data.
+"""
+
 from .automatic_mask_generation import (
     run_amg_inference,
     run_amg_grid_search,

micro_sam/evaluation/automatic_mask_generation.py

@@ -1,3 +1,6 @@
+"""Inference and evaluation for the automatic instance segmentation functionality.
+"""
+
 import os
 from glob import glob
 from pathlib import Path
@@ -190,9 +193,9 @@ def evaluate_amg_grid_search(result_dir: Union[str, os.PathLike], criterion: str
         criterion: The metric to use for determining the best parameters.
 
     Returns:
-        The best value for `pred_iou_thresh`.
-        The best value for ``stability_score_thresh.
-        The evaluation score for the best setting.
+        - The best value for `pred_iou_thresh`.
+        - The best value for `stability_score_thresh`.
+        - The evaluation score for the best setting.
     """
 
     # load all the grid search results

micro_sam/evaluation/evaluation.py

@@ -1,3 +1,7 @@
+"""Evaluation functionality for segmentation predictions from `micro_sam.evaluation.automatic_mask_generation`
+and `micro_sam.evaluation.inference`.
+"""
+
 import os
 from pathlib import Path
 from typing import List, Optional, Union

micro_sam/evaluation/experiments.py

@@ -1,7 +1,11 @@
+"""Predefined experiment settings for experiments with different prompt strategies.
+"""
+
 from typing import Dict, List, Optional
 
 # TODO fully define the dict type
-ExperimentSettings = List[Dict]
+ExperimentSetting = Dict
+ExperimentSettings = List[ExperimentSetting]
 """@private"""
 
 
@@ -63,7 +67,7 @@ def default_experiment_settings() -> ExperimentSettings:
     return experiment_settings
 
 
-def get_experiment_setting_name(setting: ExperimentSettings) -> str:
+def get_experiment_setting_name(setting: ExperimentSetting) -> str:
     """Get the name for the given experiment setting.
 
     Args:

micro_sam/evaluation/inference.py

@@ -1,3 +1,6 @@
+"""Inference with Segment Anything models and different prompt strategies.
+"""
+
 import os
 import pickle
 import warnings

micro_sam/evaluation/livecell.py

@@ -1,3 +1,7 @@
+"""Inference and evaluation for the [LiveCELL dataset](https://www.nature.com/articles/s41592-021-01249-6) and
+the different cell lines contained in it.
+"""
+
 import argparse
 import json
 import os
@@ -147,6 +151,7 @@ def run_livecell_amg(
 ) -> None:
     """Run automatic mask generation grid-search and inference for livecell.
 
+    Args:
         checkpoint: The segment anything model checkpoint.
         input_folder: The folder with the livecell data.
         model_type: The type of the segmenta anything model.

micro_sam/evaluation/model_comparison.py

@@ -1,3 +1,6 @@
+"""Functionality for qualitative comparison of Segment Anything models on microscopy data.
+"""
+
 import os
 from functools import partial
 from glob import glob