Create sphinx doc

.github/workflows/compile_docs.yml

@@ -0,0 +1,37 @@
+name: Sphinx docs to gh-pages
+
+# Workflow from: https://github.com/uibcdf/action-sphinx-docs-to-gh-pages
+
+on:
+  push:
+    branches:
+      - main
+
+# workflow_dispatch:        # Un comment line if you also want to trigger action manually
+
+jobs:
+  sphinx_docs_to_gh-pages:
+    runs-on: ubuntu-latest
+    name: Sphinx docs to gh-pages
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Make conda environment
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          python-version: 3.7    # Python version to build the html sphinx documentation
+          environment-file: docs/build_environment.yaml    # Path to the documentation conda environment
+          auto-update-conda: false
+          auto-activate-base: false
+          show-channel-urls: true
+      - name: Installing the library
+        shell: bash -l {0}
+        run: |
+          python setup.py install
+      - name: Running the Sphinx to gh-pages Action
+        uses: uibcdf/action-sphinx-docs-to-gh-pages@v1.0-beta.2
+          with:
+            branch: main
+            dir_docs: docs
+            sphinxopts: ''

.gitignore

@@ -69,7 +69,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+# docs/_build/
 
 # PyBuilder
 target/

README.md

@@ -1,12 +1,19 @@
 # biapol-utilities
 [![Python Version](https://img.shields.io/pypi/pyversions/biapol-utilities.svg?color=green)](https://python.org)
-[![tests](https://github.com/BiAPoL/biapol-utilities/workflows/tests/badge.svg)](https://github.com/BiAPoL/biapol-utilities/actions)
+[![test](https://github.com/BiAPoL/biapol-utilities/actions/workflows/test.yml/badge.svg)](https://github.com/BiAPoL/biapol-utilities/actions/workflows/test.yml)
 [![Contributors](https://img.shields.io/github/contributors-anon/BiAPoL/biapol-utilities)](https://github.com/BiAPoL/biapol-utilities/graphs/contributors)
 [![codecov](https://codecov.io/gh/BiAPoL/biapol-utilities/branch/master/graph/badge.svg)](https://codecov.io/gh/BiAPoL/biapol-utilities)
-[![GitHub stars](https://img.shields.io/github/stars/BiAPoL/biapol-utilities?style=social)](https://github.com/BiAPoL/biapol-utilities/)
 
 Collection of utility functions from the biapol group at DFG cluster of excellence "Physics of Life" (POL) @ TU Dresden, Dresden, Germany
 
+## Ressources:
+
+* Documentation page: https://biapol.github.io/biapol-utilities
+* Blog page: https://biapol.github.io/blog/
+* Github: https://github.com/BiAPoL
+* Homepage: https://physics-of-life.tu-dresden.de/en/research/core-groups/bio-image-analysis
+* Report bugs:https://github.com/BiAPoL/biapol-utilities/issues
+
 ## Acknowledgements
 Developing biapol-utilities is a community effort. We would like to thank everybody who helped developing and testing. In particular, thanks goes to the contributions of 
 - the developers of cellpose for label-matching functions

biapol_utilities/label/_compare_labels.py

@@ -6,18 +6,20 @@
 
 
 def compare_labels(label_image_x, label_image_y):
-    """
+    r"""
+    Evaluate differences between two label images.
+
     Compares two label images to determine the
     label-wise Jaccard- and Dice scores.
     The Jaccard-score is defined as the intersection over union of two labelled
-    images [1].
-    The Dice score S can be derived from the Jaccard-score J through the
-    following relation:
-    .. math:: S = \frac{2J}{1+J}.
-    
-    See also
+    images [#]_. The Dice score S can be derived from the Jaccard-score J
+    through the following relation:
+
+    .. math:: S = \frac{2J}{1+J}
+
+    See Also
     --------
-    .. [1] https://en.wikipedia.org/wiki/Jaccard_index
+    .. [#] https://en.wikipedia.org/wiki/Jaccard_index
 
     Parameters
     ----------
@@ -30,10 +32,9 @@ def compare_labels(label_image_x, label_image_y):
     Returns
     -------
     pandas DataFrame with columns `['label', 'jaccard_score', 'dice_score']`.
-    Each row corresponds to the measured quantitiy (Jaccard- or Dice score)
-    of the respective label.
+    Each row corresponds to the measured quantitiy (Jaccard- or Dice score) of
+    the respective label.
     """
-
     # Convert image to 1D array. Makes elemt-wise comparison of arrays simpler.
     label_image_x = label_image_x.ravel()
     label_image_y = label_image_y.ravel()

biapol_utilities/label/_intersection_over_union.py

@@ -22,7 +22,7 @@ def intersection_over_union_matrix(label_image_x, label_image_y):
     except for the duplicated overlap area, so the overlap matrix is
     subtracted to find the union matrix.
 
-    From: https://github.com/MouseLand/cellpose/blob/6fddd4da98219195a2d71041fb0e47cc69a4b3a6/cellpose/metrics.py#L165
+    Source: [#]_
 
     Parameters
     ----------
@@ -36,9 +36,9 @@ def intersection_over_union_matrix(label_image_x, label_image_y):
     iou: ND-array, float
         matrix of IOU pairs of size [x.max()+1, y.max()+1]
 
-    See Also
+    References
     --------
-    ..[0] https://clij.github.io/clij2-docs/reference_generateJaccardIndexMatrix
+    .. [#] https://clij.github.io/clij2-docs/reference_generateJaccardIndexMatrix
     """
 
     # Calculate overlap matrix

biapol_utilities/label/_match_labels.py

@@ -4,6 +4,7 @@
 from skimage.segmentation import relabel_sequential
 from ._intersection_over_union import intersection_over_union_matrix
 
+
 def match_labels_stack(label_stack, method=intersection_over_union_matrix, **kwargs):
     """Match labels from subsequent slices with specified method
 
@@ -24,18 +25,20 @@ def match_labels_stack(label_stack, method=intersection_over_union_matrix, **kwa
     """
 
     if method == intersection_over_union_matrix:
-        
+
         # iterate over masks
         for i in range(len(label_stack)-1):
             label_stack[i+1] = match_labels(label_stack[i], label_stack[i+1],
                                             method=method, **kwargs)
-            
+
     return label_stack
 
-def match_labels(label_image_x, label_image_y, method=intersection_over_union_matrix, **kwargs):
-    """Match labels in label_image_y with labels in label_image_x based on similarity
-    as defined by the passed method.
-
+
+def match_labels(label_image_x, label_image_y,
+                 method=intersection_over_union_matrix, **kwargs):
+    """
+    Match labels in label_image_y with labels in label_image_x.
+
     Parameters
     ----------
     label_image_x : nd-array
@@ -44,11 +47,11 @@ def match_labels(label_image_x, label_image_y, method=intersection_over_union_ma
         Image the labels of which should be paired with labels from imageA
     method : str, optional
         Pairing method to be used. The default is 'iou' (intersection over union).
-        
-        *iou (intersection over union)*: The intersection over union is used to 
+
+        *iou (intersection over union)*: The intersection over union is used to
             measure the overlap between labels in both images. The label with
             highest overlap is chosen as counterpart label
-            
+
             iou_streshold: float, optional
                 Threshold value above which two labels are accepted as overlapping.
                 The default value is 0.25
@@ -58,31 +61,30 @@ def match_labels(label_image_x, label_image_y, method=intersection_over_union_ma
     nd-array
         Processed version of imageB with labels corresponding to imageA.
     """
-
     if method == intersection_over_union_matrix:
         threshold = kwargs.get('iou_threshold', 0.25)
-    
+
     # relabel label_image_y to keep overlap matrix small
     label_image_y, _, _ = relabel_sequential(label_image_y)
-    
-    
+
+
     # Calculate image similarity matrix img_sim based on chosen method
     img_sim = method(label_image_y, label_image_x)[1:,1:]
     mmax = label_image_x.max()
-    
+
     if img_sim.size > 0:
-        
+
         # Keep only ious above threshold
         img_sim[img_sim < threshold] = 0.0
         img_sim[img_sim < img_sim.max(axis=0)] = 0.0
-        
+
         # Pick value with highest IoU value
         istitch = img_sim.argmax(axis=1) + 1
         ino = np.nonzero(img_sim.max(axis=1) == 0.0)[0]  # Find unpaired labels
-        
+
         # append unmatched labels and background to lookup table
-        istitch[ino] = np.arange(mmax+1, mmax+len(ino)+1, 1, int)  
+        istitch[ino] = np.arange(mmax+1, mmax+len(ino)+1, 1, int)
         mmax += len(ino)
         istitch = np.append(np.array(0), istitch)
-        
+
         return istitch[label_image_y]

docs/.nojekyll

@@ -0,0 +1 @@
+

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 0adea3e74d7f00115f5ef1a66df3e43d
+tags: 645f666f9bcd5a90fca523b33c5a78b7