Build documentation

.github/workflows/build.yml

@@ -12,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12"]
 
     steps:
       - name: Checkout

.github/workflows/build_docs.yaml

@@ -0,0 +1,65 @@
+name: Build and Deploy Docs
+
+on:
+  push:
+    paths:
+      - "elf/**/*.py"   # Trigger on any changes in python files.
+    branches:
+      - master        # Run the workflow only on pushes to the main branch
+  workflow_dispatch:
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@v4
+
+    - name: Set up Micromamba
+      uses: mamba-org/setup-micromamba@v2
+      with:
+        micromamba-version: "latest"
+        environment-file: environment.yaml
+        init-shell: bash
+        cache-environment: true
+        post-cleanup: 'all'
+
+    - name: Install package
+      shell: bash -l {0}
+      run: pip install -e .
+
+    - name: Install pdoc
+      shell: bash -l {0}
+      run: pip install pdoc
+
+    - name: Generate Documentation
+      shell: bash -l {0}
+      run: pdoc elf/ -d google -o doc/
+
+    - name: Verify Documentation Output
+      run: ls -la doc/
+
+    - name: Upload Documentation Artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: doc/
+
+  deploy:
+    name: Deploy Documentation
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GiHub Pages
+        uses: actions/deploy-pages@v4

build_doc.py

@@ -0,0 +1,16 @@
+import argparse
+from subprocess import run
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--out", "-o", action="store_true")
+    args = parser.parse_args()
+
+    cmd = ["pdoc", "--docformat", "google"]
+
+    if args.out:
+        cmd.extend(["--out", "tmp/"])
+    cmd.append("elf/")
+
+    run(cmd)

elf/__init__.py

@@ -1 +1,50 @@
+"""[elf](https://github.com/constantinpape/elf) implements image analysis functionality for large microscopy data.
+
+# Overview
+
+`elf` provides functionality for different image analysis tasks. The main functionality is:
+- `elf.evaluation`: Common metrics for evaluating segmentation results.
+- `elf.io`: Common interface for reading file formats for large microscopy data.
+- `elf.parallel`: Parallel implementations of image analysis functions.
+- `elf.segmentation`: Segmentation functions based on clustering, (lifted) multicut, mutex watershed and more.
+- `elf.tracking`: Graph-based tracking algorithms.
+- `elf.wrapper`: Wrapper for large microscopy data to enable on-the-fly processing.
+
+# Installation
+
+`elf` is available on conda-forge. You can install it into an existing conda environment via:
+```
+conda install -c conda-forge python-elf
+```
+
+We also provide a environment for a development environment. To set it up:
+1. Clone the elf repository:
+```
+git clone https://github.com/constantinpape/elf
+```
+2. Enter the root elf directory:
+```
+cd elf
+```
+3. Create the development environment:
+```
+conda create -f environment.yaml
+```
+4. Activate the environment:
+```
+conda activate elf-dev
+```
+5. Install elf in development mode:
+```
+pip install -e .
+```
+
+# Usage & Examples
+
+Example scripts for many of `elf`'s features can be found in [example](https://github.com/constantinpape/elf/tree/master/example).
+
+`elf` also provides command line functionality. Currently provided are the command line interfaces:
+- `view_container`: Visualize the content of any file supported by `elf.io` with napari.
+"""
+
 from .__version__ import __version__

elf/color/__init__.py

@@ -1 +1,4 @@
+"""Glasbey and random color palettes for visualizing instance segmentations.
+"""
+
 from .palette import glasbey, random_colors

elf/evaluation/__init__.py

@@ -1,3 +1,6 @@
+"""Common metrics for evaluating instance segmentation results.
+"""
+
 from .cremi_score import cremi_score
 from .dice import dice_score, symmetric_best_dice_score
 from .rand_index import rand_index

elf/htm/__init__.py

@@ -1,2 +1,7 @@
+"""Visualization of high-throughput / high-content microscopy data via napari.
+
+Examples for using this functionality are in [example/htm](https://github.com/constantinpape/elf/tree/master/example/htm).
+"""
+
 from .parser import parse_simple_htm
 from .visualization import view_plate, view_positional_images

elf/ilastik/__init__.py

@@ -0,0 +1,2 @@
+"""Convenience functionality for parsing outputs from the ilastik carving workflow.
+"""

elf/io/__init__.py

@@ -1,2 +1,5 @@
+"""Common interface for reading and writing microscopy data formats for large imaging data.
+"""
+
 from .files import open_file, supported_extensions
 from .files import is_group, is_dataset, is_h5py, is_z5py, is_knossos

elf/label_multiset/__init__.py

@@ -1,3 +1,6 @@
+"""Implementation of the label multiset format used by paintera.
+"""
+
 from .create import create_multiset_from_labels, downsample_multiset, merge_multisets
 from .label_multiset import LabelMultiset
 from .serialize import serialize_multiset, deserialize_multiset, deserialize_labels

elf/mesh/__init__.py

@@ -1 +1,4 @@
+"""Functionality for converting 3D segmentation masks to and from meshes.
+"""
+
 from .mesh import marching_cubes

elf/parallel/__init__.py

@@ -1,3 +1,6 @@
+"""Parallel implementations of image analysis functionality.
+"""
+
 from .copy_dataset import copy_dataset
 from .distance_transform import distance_transform
 from .operations import (apply_operation, add, divide, multiply, subtract,

elf/segmentation/__init__.py

@@ -1,3 +1,8 @@
+"""Graph-based instance segmentation based on clustering, (lifted) multicut, mutex watershed and more.
+
+Examples for graph-based segmentation with `elf.segmentation` can be found in [example/segmentation](https://github.com/constantinpape/elf/tree/master/example/segmentation) and for embedding-based segmentation in [example/embeddings](https://github.com/constantinpape/elf/tree/master/example/embeddings).
+"""
+
 from .clustering import (agglomerative_clustering,
                          cluster_segmentation, cluster_segmentation_mala,
                          mala_clustering)

elf/skeleton/__init__.py

@@ -1 +1,4 @@
+"""Functionality for skeletonizing 3D segmentations and reading / writing skeletons to different file formats.
+"""
+
 from .skeletonize import skeletonize, get_method_names

elf/tracking/__init__.py

@@ -0,0 +1,5 @@
+"""Graph-based tracking functionality. The currently available implementation is based on [motile](https://github.com/funkelab/motile).
+
+For using this functionality, you have to install motile as an additional dependency.
+An example for how to use `elf.tracking` can be found in [example/tracking](https://github.com/constantinpape/elf/tree/master/example/tracking).
+"""

elf/transformation/__init__.py

@@ -1,3 +1,6 @@
+"""Functionality for applying affine and resize transformations to large image data.
+"""
+
 from .affine import (affine_matrix_2d, affine_matrix_3d,
                      compute_affine_matrix, scale_from_matrix, translation_from_matrix,
                      transform_subvolume_affine, transform_roi_with_affine)

elf/util.py

@@ -1,7 +1,16 @@
 import numbers
+import sys
+
 from itertools import product
 from math import ceil
-from typing import List, Sequence, Tuple, Union, TYPE_CHECKING
+from typing import List, Literal, Sequence, Tuple, Union, TYPE_CHECKING
+
+# Ellipsis as type annontation is only supported for python >= 3.11.
+# To support earlier version we use Literal[...] as type annotation, according to ChatGPT that should work.
+if sys.version_info.minor >= 11:
+    EllipsisType = Ellipsis
+else:
+    EllipsisType = Literal[...]
 
 if TYPE_CHECKING:
     import numpy as np
@@ -68,7 +77,7 @@ def int_to_start_stop(i: int, size: int) -> slice:
 # But it's worth taking a look at @clbarnes more general implementation too
 # https://github.com/clbarnes/h5py_like
 def normalize_index(
-    index: Union[int, slice, Ellipsis, Tuple[Union[int, slice, Ellipsis], ...]],
+    index: Union[int, slice, EllipsisType, Tuple[Union[int, slice, EllipsisType], ...]],
     shape: Tuple[int, ...]
 ) -> Tuple[Tuple[slice, ...], Tuple[int, ...]]:
     """Normalize an index for a given shape, so that is expressed as tuple of slices with correct coordinates.

elf/visualisation/__init__.py

@@ -1,3 +1,6 @@
+"""Napari-based visualization of segmentation results and other visualization functionality.
+"""
+
 from .edge_visualisation import visualise_edges, visualise_attractive_and_repulsive_edges
 from .grid_views import simple_grid_view
 from .object_visualisation import visualise_iou_scores, visualise_dice_scores, visualise_voi_scores

elf/wrapper/__init__.py

@@ -1,2 +1,5 @@
+"""Wrapper for large image data to implement lazy data processing.
+"""
+
 from .base import SimpleTransformationWrapper, TransformationWrapper
 from .generic import NormalizeWrapper, ThresholdWrapper, RoiWrapper