strict & fixing Docs (#49)

* fix sphinx docs * test sphinx docs * add refs (bibtex) * drop SVG & GIF * fix paths * add pep8speaks * fix notebook
Borda · Apr 9, 2020 · 3629b7a · 3629b7a
1 parent 087e677
commit 3629b7a
Show file tree

Hide file tree

Showing 27 changed files with 190 additions and 154 deletions.
diff --git a/.pep8speaks.yml b/.pep8speaks.yml
@@ -0,0 +1,28 @@
+# File : .pep8speaks.yml
+
+scanner:
+    diff_only: True  # If False, the entire file touched by the Pull Request is scanned for errors. If True, only the diff is scanned.
+    linter: pycodestyle  # Other option is flake8
+
+pycodestyle:  # Same as scanner.linter value. Other option is flake8
+    max-line-length: 110  # Default is 79 in PEP 8
+    ignore:  # Errors and warnings to ignore
+        - W504  # line break after binary operator
+        - E402  # module level import not at top of file
+        - E731  # do not assign a lambda expression, use a def
+        - C406  # Unnecessary list literal - rewrite as a dict literal.
+        - E741  # ambiguous variable name
+
+no_blank_comment: True  # If True, no comment is made on PR without any errors.
+descending_issues_order: False  # If True, PEP 8 issues in message will be displayed in descending order of line numbers in the file
+
+message:  # Customize the comment made by the bot,
+    opened:  # Messages when a new PR is submitted
+        header: "Hello @{name}! Thanks for opening this PR. "
+                # The keyword {name} is converted into the author's username
+        footer: "Do see the [Hitchhiker's guide to code style](https://goo.gl/hqbW4r)"
+                # The messages can be written as they would over GitHub
+    updated:  # Messages when new commits are added to the PR
+        header: "Hello @{name}! Thanks for updating this PR. "
+        footer: ""  # Why to comment the link to the style guide everytime? :)
+    no_errors: "There are currently no PEP 8 issues detected in this Pull Request. Cheers! :beers: "
diff --git a/README.md b/README.md
@@ -32,7 +32,7 @@ For evaluation, we have manually placed landmarks in each image pair. There are
 We do not put any landmarks in the background.
 For more information about annotation creation and landmarks handling, we refer to the special repository - [Dataset: histology landmarks](http://borda.github.com/dataset-histology-landmarks).
 
-![images-landmarks](figures/images-landmarks.jpg)
+![images-landmarks](docs/source/_figures/images-landmarks.jpg)
 
 The dataset is defined by a CSV file containing paths to target and sensed image and their related landmarks _(see `./data_images/pairs-imgs-lnds_mix.csv`)_. With the change of the cover table, the benchmarks can be used for any other image dataset.
 
@@ -150,7 +150,7 @@ Moreover we developed two additional script for converting large images, handlin
 
 Even though this framework is completely customizable we include several image registration methods commonly used in medical imaging.
 
-![visualise-regist-results](figures/registration_visual_landmarks.jpg)
+![visualise-regist-results](docs/source/_figures/registration_visual_landmarks.jpg)
 
 ### Install methods and run benchmarks
 
@@ -187,7 +187,7 @@ The general Image Registration benchmarks contain couple required and optional p
 * `--unique` each experiment has creation stamp included in its name (prevent overwriting experiments with the same method)
 * `--visual` generate a simple visualisation of particular image registrations
 
-![preprocessing-hist-matching](figures/Rat-Kidney_histogram-matching.jpg)
+![preprocessing-hist-matching](docs/source/_figures/Rat-Kidney_histogram-matching.jpg)
 
 Measure your computer performance using average execution time on several simple image registrations.
 The registration consists of loading images, denoising, feature detection, transform estimation and image warping. 
@@ -278,7 +278,9 @@ Some more image registration methods integrated in ImageJ are listed in [Registr
 
 ### Add custom registration method
 
-The only limitation of adding costume image registration methods that it has to be launched from python script or command line. The new registration benchmark should be inherited from [ImRegBenchmark](birl/benchmark.py) as for example [BmTemplate](birl/bm_template.py).
+The only limitation of adding costume image registration methods that it has to be launched from python script or command line.
+The new registration benchmark should be inherited from [ImRegBenchmark](birl/benchmark.py)
+ as for example [BmTemplate](birl/bm_template.py).
 
 The benchmark workflow is the following:
 1. `self._prepare()` prepare the experiment, e.g. create experiment folder, copy configurations, etc.
@@ -321,7 +323,7 @@ The project is using the standard [BSD license](http://opensource.org/licenses/B
 For complete references see [bibtex](docs/references.bib).
 1. Borovec, J., Munoz-Barrutia, A., & Kybic, J. (2018). **[Benchmarking of image registration methods for differently stained histological slides](https://www.researchgate.net/publication/325019076_Benchmarking_of_image_registration_methods_for_differently_stained_histological_slides)**. In IEEE International Conference on Image Processing (ICIP) (pp. 3368–3372), Athens. [DOI: 10.1109/ICIP.2018.8451040](https://doi.org/10.1109/ICIP.2018.8451040)
 2. Borovec, J. (2019). **[BIRL: Benchmark on Image Registration methods with Landmark validation](https://www.researchgate.net/publication/338291737_BIRL_Benchmark_on_Image_Registration_methods_with_Landmark_validation)**. arXiv preprint [arXiv:1912.13452](https://arxiv.org/abs/1912.13452).
-3. Borovec, J., Kybic, J., et al. (2020). **[ANHIR: Automatic Non-rigid Histological Image Registration Challenge](https://ieeexplore.ieee.org/document/9058666)**. In IEEE Transaction on Medical Imaging (TMI). [DOI: 10.1109/TMI.2020.2986331](https://www.doi.org/10.1109/TMI.2020.2986331)
+3. Borovec, J., Kybic, J., et al. (2020). **[ANHIR: Automatic Non-rigid Histological Image Registration Challenge](https://ieeexplore.ieee.org/document/9058666)**. In IEEE Transaction on Medical Imaging (TMI). [DOI: 10.1109/TMI.2020.2986331](https://www.doi.org/10.1109/TMI.2020.2986331).
 
 ## Appendix - Useful information
 

diff --git a/birl/__init__.py b/birl/__init__.py
@@ -38,7 +38,7 @@
 ## References
 1. Borovec, J., Munoz-Barrutia, A., & Kybic, J. (2018).
  Benchmarking of image registration methods for differently stained histological slides.
- In IEEE International Conference on Image Processing (ICIP) (pp. 3368–3372), Athens.
+ In IEEE International Conference on Image Processing (ICIP) (pp. 3368-3372), Athens.
  DOI: 10.1109/ICIP.2018.8451040
 2. Borovec, J. (2019). BIRL: Benchmark on Image Registration methods with Landmark validation.
  arXiv preprint arXiv:1912.13452.

diff --git a/birl/benchmark.py b/birl/benchmark.py
@@ -56,13 +56,15 @@ class ImRegBenchmark(Experiment):
     1. check all necessary paths and required parameters
     2. load cover file and set all paths as absolute
     3. run individual registration experiment in sequence or in parallel
-       (nb_workers > 1); if the particular experiment folder exist (assume
-       completed experiment) and skip it
-        a) create experiment folder and init experiment
-        b) generate execution command
-        c) run the command (an option to lock it in single thread)
-        d) evaluate experiment, set the expected outputs and visualisation
-        e) clean all extra files if any
+        (nb_workers > 1); if the particular experiment folder exist (assume
+        completed experiment) and skip it:
+
+            a) create experiment folder and init experiment
+            b) generate execution command
+            c) run the command (an option to lock it in single thread)
+            d) evaluate experiment, set the expected outputs and visualisation
+            e) clean all extra files if any
+
     4. visualise results abd evaluate registration results
 
     .. note:: The actual implementation simulates the "IDEAL" registration while

diff --git a/birl/utilities/data_io.py b/birl/utilities/data_io.py
@@ -176,7 +176,7 @@ def save_landmarks_pts(path_file, landmarks):
         point1-x point1-y [point1-z]
         point2-x point2-y [point2-z]
 
-    .. ref:: https://simpleelastix.readthedocs.io/PointBasedRegistration.html
+    .. seealso:: https://simpleelastix.readthedocs.io/PointBasedRegistration.html
 
     :param str path_file: path to the output file
     :param landmarks: np.array<np_points, dim>
@@ -504,7 +504,7 @@ def image_resize(img, scale=1., v_range=255, dtype=int):
 def convert_image_from_mhd(path_image, path_out_dir=None, img_ext='.png', scaling=None):
     """ convert standard image to MHD format
 
-    .. ref:: https://www.programcreek.com/python/example/96382/SimpleITK.WriteImage
+    .. seealso:: https://www.programcreek.com/python/example/96382/SimpleITK.WriteImage
 
     :param str path_image: path to the input image
     :param str path_out_dir: path to output directory, if None use the input dir
@@ -540,7 +540,7 @@ def convert_image_from_mhd(path_image, path_out_dir=None, img_ext='.png', scalin
 def convert_image_to_mhd(path_image, path_out_dir=None, to_gray=True, overwrite=True, scaling=None):
     """ converting standard image to MHD (Nifty format)
 
-    .. ref:: https://stackoverflow.com/questions/37290631
+    .. seealso:: https://stackoverflow.com/questions/37290631
 
     :param str path_image: path to the input image
     :param str path_out_dir: path to output directory, if None use the input dir

diff --git a/birl/utilities/dataset.py b/birl/utilities/dataset.py
@@ -190,7 +190,7 @@ def save_large_image(img_path, img):
     """ saving large images more then 50k x 50k
 
     .. note:: For the saving we have to use openCV while other
-    lib (matplotlib, Pillow, ITK) is not able to save larger images then 32k.
+     lib (matplotlib, Pillow, ITK) is not able to save larger images then 32k.
 
     :param str img_path: path to the new image
     :param ndarray img: image
@@ -726,7 +726,7 @@ def scale_large_images_landmarks(images, landmarks):
 def convert_landmarks_to_itk(lnds, image_size):
     """converting used landmarks to ITK format
 
-    .. ref:: https://github.com/SuperElastix/elastix/issues/156#issuecomment-511712784
+    .. seealso:: https://github.com/SuperElastix/elastix/issues/156#issuecomment-511712784
 
     :param ndarray lnds: landmarks
     :param (int,int) image_size: image size - height, width
@@ -748,7 +748,7 @@ def convert_landmarks_to_itk(lnds, image_size):
 def convert_landmarks_from_itk(lnds, image_size):
     """converting ITK format to used in ImageJ
 
-    .. ref:: https://github.com/SuperElastix/elastix/issues/156#issuecomment-511712784
+    .. seealso:: https://github.com/SuperElastix/elastix/issues/156#issuecomment-511712784
 
     :param ndarray lnds: landmarks
     :param (int,int) image_size: image height, width

diff --git a/birl/utilities/drawing.py b/birl/utilities/drawing.py
@@ -416,22 +416,16 @@ def draw_heatmap(data, row_labels=None, col_labels=None, ax=None,
     """
     Create a draw_heatmap from a numpy array and two lists of labels.
 
-    https://matplotlib.org/gallery/images_contours_and_fields/image_annotated_heatmap.html
-
-    Arguments:
-        data       : A 2D numpy array of shape (N,M)
-        row_labels : A list or array of length N with the labels
-                     for the rows
-        col_labels : A list or array of length M with the labels
-                     for the columns
-    Optional arguments:
-        ax         : A matplotlib.axes.Axes instance to which the draw_heatmap
-                     is plotted. If not provided, use current axes or
-                     create a new one.
-        cbar_kw    : A dictionary with arguments to
-                     :meth:`matplotlib.Figure.colorbar`.
-        cbar_label  : The label for the colorbar
-    All other arguments are directly passed on to the imshow call.
+    .. seealso:: https://matplotlib.org/gallery/images_contours_and_fields/image_annotated_heatmap.html
+
+    :param data: A 2D numpy array of shape (N,M)
+    :param row_labels: A list or array of length N with the labels for the rows
+    :param col_labels: A list or array of length M with the labels for the columns
+    :param ax: A matplotlib.axes.Axes instance to which the draw_heatmap is plotted.
+     If not provided, use current axes or create a new one.
+    :param cbar_kw: A dictionary with arguments to :meth:`matplotlib.Figure.colorbar`.
+    :param cbar_label: The label for the colorbar
+
     """
     cbar_kw = {} if cbar_kw is None else cbar_kw
     ax = plt.figure(figsize=data.shape[::-1]).gca() if ax is None else ax

diff --git a/bm_ANHIR/evaluate_submission.py b/bm_ANHIR/evaluate_submission.py
@@ -233,7 +233,7 @@ def _round_val(row, col):
 def compute_scores(df_experiments, min_landmarks=1.):
     """ compute all main metrics
 
-    .. ref:: https://anhir.grand-challenge.org/Evaluation/
+    .. seealso:: https://anhir.grand-challenge.org/Evaluation/
 
     :param DF df_experiments: complete experiments
     :param float min_landmarks: required number of submitted landmarks in range (0, 1),

diff --git a/bm_experiments/bm_DROP.py b/bm_experiments/bm_DROP.py
@@ -3,24 +3,24 @@
 
 DROP is a approach for image registration and motion estimation based on Markov Random Fields.
 
-.. ref:: https://www.mrf-registration.net
+.. seealso:: https://www.mrf-registration.net
 
 Related Publication:
-Deformable Medical Image Registration: Setting the State of the Art with Discrete Methods
- Authors: Ben Glocker, Aristeidis Sotiras, Nikos Komodakis, Nikos Paragios
- Published in: Annual Review of Biomedical Engineering, Vol. 12, 2011, pp. 219-244
 
+    1. Deformable Medical Image Registration: Setting the State of the Art with Discrete Methods
+        Authors: Ben Glocker, Aristeidis Sotiras, Nikos Komodakis, Nikos Paragios
+        Published in: Annual Review of Biomedical Engineering, Vol. 12, 2011, pp. 219-244
 
-Installation for Linux
-----------------------
 
-1. Download executable according your operation system,
- https://www.mrf-registration.net/deformable/index.html
-2. Copy/extract executables and libraries to you favourite destination
-3. Install all missing libraries such as QT4 with OpenGL support
-4. Test calling the executable `./dropreg2d` which should return something like::
+**Installation for Linux**
 
-    Usage: dropreg2d <source> <target> <result> <paramfile> [mask]
+    1. Download executable according your operation system,
+        https://www.mrf-registration.net/deformable/index.html
+    2. Copy/extract executables and libraries to you favourite destination
+    3. Install all missing libraries such as QT4 with OpenGL support
+    4. Test calling the executable `./dropreg2d` which should return something like::
+
+        Usage: dropreg2d <source> <target> <result> <paramfile> [mask]
 
 Usage
 -----
@@ -48,7 +48,7 @@
 
 .. note:: This method is not optimized nor suitable for large images, so all used images
  are first scaled to be 2000x2000 pixels and then the registration is performed.
-  After registration is resulting image scaled back. The landmarks are scalded accordingly.
+ After registration is resulting image scaled back. The landmarks are scalded accordingly.
 
 Glocker, Ben, et al. "Deformable medical image registration: setting the state of the art
  with discrete methods." Annual review of biomedical engineering 13 (2011): 219-244.
@@ -81,7 +81,7 @@ class BmDROP(ImRegBenchmark):
     For the app installation details, see module details.
 
     .. note:: DROP requires gray scale images in MHD format where pixel values
-    are in range (0, 255) of uint8.
+        are in range (0, 255) of uint8.
 
     Example
     -------

diff --git a/bm_experiments/bm_DROP2.py b/bm_experiments/bm_DROP2.py
@@ -3,23 +3,23 @@
 
 DROP is a approach for image registration and motion estimation based on Markov Random Fields.
 
-.. ref:: https://github.com/biomedia-mira/drop2
+.. seealso:: https://github.com/biomedia-mira/drop2
 
 Related Publication:
-Deformable Medical Image Registration: Setting the State of the Art with Discrete Methods
- Authors: Ben Glocker, Aristeidis Sotiras, Nikos Komodakis, Nikos Paragios
- Published in: Annual Review of Biomedical Engineering, Vol. 12, 2011, pp. 219-244
 
+    1. Deformable Medical Image Registration: Setting the State of the Art with Discrete Methods
+        Authors: Ben Glocker, Aristeidis Sotiras, Nikos Komodakis, Nikos Paragios
+        Published in: Annual Review of Biomedical Engineering, Vol. 12, 2011, pp. 219-244
 
-Installation for Linux
-----------------------
 
-1. Download source code: https://github.com/biomedia-mira/drop2
-2. Install all required libraries such as ITK, and build following the instructions
-    OR run building script `build.sh` included in the repository
-3. Test calling the executable `./build/drop/apps/dropreg/dropreg` which should return something like::
+**Installation for Linux**
 
-    Usage: dropreg --help
+    1. Download source code: https://github.com/biomedia-mira/drop2
+    2. Install all required libraries such as ITK, and build following the instructions
+        OR run building script `build.sh` included in the repository
+    3. Test calling the executable `./build/drop/apps/dropreg/dropreg` which should return something like::
+
+        Usage: dropreg --help
 
 Usage
 -----

diff --git a/bm_experiments/bm_RVSS.py b/bm_experiments/bm_RVSS.py
@@ -1,7 +1,7 @@
 """
 Benchmark for ImageJ plugin - RVSS
 
-.. ref::  https://imagej.net/Register_Virtual_Stack_Slices
+.. seealso::  https://imagej.net/Register_Virtual_Stack_Slices
 
 Installation
 ------------

diff --git a/bm_experiments/bm_bUnwarpJ.py b/bm_experiments/bm_bUnwarpJ.py
@@ -1,7 +1,7 @@
 """
 Benchmark for ImageJ plugin - bUnwarpJ
 
-.. ref::  http://imagej.net/BUnwarpJ
+.. seealso:: http://imagej.net/BUnwarpJ
 
 Installation
 ------------

diff --git a/bm_experiments/bm_elastix.py b/bm_experiments/bm_elastix.py
@@ -7,36 +7,35 @@
 * https://github.com/SuperElastix/elastix/wiki/Getting-started
 * https://blog.yuwu.me/wp-content/uploads/2017/10/elastix_manual_v4.8.pdf
 
-Installation
-------------
+**Installation**
 
-1. Download compiled executables from https://github.com/SuperElastix/elastix/releases
-2. Try to run both executables locally `elastix --help` and `transformix --help`
-    * add path to the lib `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/Applications/elastix/lib`
-    * define permanent path or copy libraries `cp /elastix/lib/* /usr/local/lib/`
+    1. Download compiled executables from https://github.com/SuperElastix/elastix/releases
+    2. Try to run both executables locally `elastix --help` and `transformix --help`
+
+        * add path to the lib `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/Applications/elastix/lib`
+        * define permanent path or copy libraries `cp /elastix/lib/* /usr/local/lib/`
 
 Example
 -------
 
-1. Perform sample image registration:
-    ```bash
-    ~/Applications/elastix/bin/elastix \
-        -f ./data_images/images/artificial_reference.jpg \
-        -m ./data_images/images/artificial_moving-affine.jpg \
-        -out ./results/elastix \
-        -p ./configs/elastix_affine.txt
-    ```
-2. Besides using `transformix` for deforming images, you can also use `transformix`
- to evaluate the transformation at some points. This means that the input points are specified
- in the fixed image domain, since the transformation direction is from fixed to moving image.
- Perform image/points warping:
-    ```bash
-    ~/Applications/elastix/bin/transformix \
-        -tp ./results/elastix/TransformParameters.0.txt \
-        -out ./results/elastix \
-        -in ./data_images/images/artificial_moving-affine.jpg \
-        -def ./data_images/landmarks/artificial_reference.pts
-    ```
+    1. Perform sample image registration::
+
+        ~/Applications/elastix/bin/elastix \
+            -f ./data_images/images/artificial_reference.jpg \
+            -m ./data_images/images/artificial_moving-affine.jpg \
+            -out ./results/elastix \
+            -p ./configs/elastix_affine.txt
+
+    2. Besides using `transformix` for deforming images, you can also use `transformix`
+        to evaluate the transformation at some points. This means that the input points are specified
+        in the fixed image domain, since the transformation direction is from fixed to moving image.
+        Perform image/points warping::
+
+        ~/Applications/elastix/bin/transformix \
+            -tp ./results/elastix/TransformParameters.0.txt \
+            -out ./results/elastix \
+            -in ./data_images/images/artificial_moving-affine.jpg \
+            -def ./data_images/landmarks/artificial_reference.pts
 
 Usage
 -----

diff --git a/bm_experiments/evaluate_experiment.py b/bm_experiments/evaluate_experiment.py
@@ -7,12 +7,14 @@
  * `registration-results.csv` coordinate file with path to landmarks and images
  * particular experiment with warped landmarks
 
-Sample Usage:
+Sample Usage
+------------
 .. code-block:: bash
- python evaluate_experiment.py \
-    -e ./results/BmUnwarpJ \
-    -d ./data_images \
-    --visual
+
+    python evaluate_experiment.py \
+        -e ./results/BmUnwarpJ \
+        -d ./data_images \
+        --visual
 
 Copyright (C) 2016-2019 Jiri Borovec <[email protected]>
 """