Merge pull request #13 from JesseMckinzie/add_read_the_docs_v2

Add Read the Docs

README.md

@@ -110,7 +110,7 @@ that contains the ROIs who's features values fall within the slider values.
 
 The new labels resulting from the range slider selector can then be used to run Nyxus on by using the labels image as the `Segmentation` parameter.
 
-![](docs/source/img/run_on_colormap_labels.png)
+![](https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/run_on_colormap_labels.png)
 
 # Limitations
 

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     = source
+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/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/Examples.rst

@@ -0,0 +1,109 @@
+Examples
+--------
+
+Running Feature Calculations
+============================
+
+After loading the Napari GUI, the Nyxus plugin can be loaded from the `Plugins` menu in the toolbar by going to Plugins -> nyxus-napari.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/plugin_menu.png
+
+A widget will appear in the Napari viewer to run Nyxus.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/nyxus_loaded.png
+
+As shown by the example above, Nyxus will take in Intensity and Segmentation images. These parameters can either be a stack
+of images or a single image pair. To load an image pair, use File -> Open File(s)... and select the images to load.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/open_image.png 
+
+Note that this method can also be used to open a stack of image, by using File -> Open Folder... instead of images. 
+
+If the segmentation is loaded as an Image type in the napari viewer, it must first be converted to the Labels type. The image can converted as shown below.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/convert_to_labels.png
+
+The loaded files can then be selected with the Intensity and Segmentation drop down menus. Other parameters can also be changed,
+such as which features to calculate. For more information on the available features, see https://nyxus.readthedocs.io/en/latest/featurelist.html.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/setup_calculation.png
+
+After running Nyxus, the feature calculations will also appear in the Napari viewer.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/feature_results.png
+
+
+Interacting with feature calculations
+=====================================
+
+The Nyxus Napari plugin provides functionality to interact with the table containing the feature calculations. First, click on the segmentation image and then select `show selected` in the layer controls. 
+
+
+Then, if a value is clicked in the `label` column of the table, the respective ROI will be highlighted in the segmentation image in the viewer.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/click_label.png
+
+To select the ROI and have it added to a separate Labels image, the label in the table can be double clicked. Each double clicked label will be added to the same Labels image as show below. To unselect, the ROI, double click its respective label again.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/double_click_label.png
+
+This feature can also be used in the opposite way, i.e. if an ROI is clicked in the segmentation image, the respective row in the 
+feature table will be highlighted.
+
+If one of the column headers are double clicked, a colormap will be generated in the Napari viewer showing the values of the features in the clicked
+column. For example, if `Intensity` features are calculated, the `INTEGRATED_INTENSITY` column can be clicked and the colormap will appear.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/feature_colormap.png
+
+Once the colormap is loaded, a slider will appear in the window with the minimum value being the minimum value of the feature colormap and the 
+maximum value of the slider is the maximum value of the colormap. By adjusting the ranges in the slider, a new label image will appear in the viewer
+that contains the ROIs who's features values fall within the slider values.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/slider_feature.png
+
+The new labels resulting from the range slider selector can then be used to run Nyxus on by using the labels image as the `Segmentation` parameter.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/run_on_colormap_labels.png
+
+
+Feature calculation heat map
+============================
+
+To visualize how features change between images, ROIs, or annotations, a heat map can be added to the feature calculation table.
+To add a heatmap, first run Nyxus on image-segmentation pair(s). Next, the heat map can be added through by first selecting a colormap option:
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/heatmap_drop_down.png
+
+Next, it can be selected whether to toggle the option to remove the feature calculation values. Hiding the feature calculations values will hide the 
+values in each cell and make each cell the same size. This can make visualization of the feature calculations easier.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/heatmap_toggle.png
+
+After clicking the ``Generate Heatmap`` button, the feature calculation table will have the colormap applied.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/heatmap.png
+
+
+Extracting annotations from filenames
+=====================================
+
+The Nyxus plugin also provides the ability to extract annotations from the image names. To extract annotations, the column name must first be selected.
+After selecting the column name, a ``filepattern`` must be supplied to give the pattern of the annotation. For more information on what a filepattern is,
+see https://github.com/PolusAI/filepattern. Finally, supply one of the variables to extract. 
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/annotation_input.png
+
+After clicking ``Extract annotation``, the annotation will appear as a new column in the feature calculation table.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/annotation_column.png
+
+Sorting the feature calculation table
+=====================================
+
+To sort the feature calculation table by a column, enter a column into the text box shown below. Note that this column can be any of the present columns,
+including annotations. 
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/sort_box.png
+
+After clicking ``Sort``, the table will be sorted by the selected column. To sort by multiple columns, enter the columns into the box in order, separated by
+spaces.

docs/source/conf.py

@@ -0,0 +1,93 @@
+# -*- coding: utf-8 -*-
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+import subprocess
+
+sys.path.insert(0, os.path.abspath('../..'))
+# sys.path.insert(0, str(Path(__file__).parent.parent.parent.absolute()))
+sys.setrecursionlimit(10000)
+# sys.path.insert(0, str(Path(__file__).parent.parent.parent.absolute()))
+# sys.setrecursionlimit(1500)
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'napari-nyxus'
+author = 'Jesse McKinzie'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.napoleon',
+    'sphinx.ext.autodoc',
+    'sphinx_autodoc_typehints',
+    'sphinx.ext.autosummary',
+    'autodocsumm'
+]
+
+napoleon_use_param = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['..']
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+
+html_sidebars = {'**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']}
+
+# autodoc settings
+autodoc_mock_imports = []
+
+autodoc_member_order = 'groupwise'
+autodoc_typehints = 'description'
+
+autoclass_content = 'class'  # Shows both the class docstring and __init__
+
+autodoc_default_options = {
+    'members': True,
+    'inherited-members': True,
+    'special-members': '__getitem__,__call__,__setitem__',
+    'show-inheritance': True
+    # 'autosummary': True
+    # 'exclude-members': '__weakref__'
+}
+
+# Autosummary settings
+autosummary_generate = True
+
+# Set the master doc
+master_doc = 'index'
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['html']

docs/source/index.rst

@@ -0,0 +1,79 @@
+Nyxus Napari
+------------
+
+Nyxus Napari is a Napari plugin for running feature calculations on image-segmentation image pairs, using the
+Nyxus application to compute features. Nyxus is a feature-rich, highly optimized, Python/C++ application capable 
+of analyzing images of arbitrary size and assembling complex regions of interest (ROIs) split across multiple image tiles and files. 
+
+For more information on Nyxus, see https://github.com/PolusAI/nyxus.
+
+Installation
+============
+
+To install Napari, it is recommended to first create a separate Conda environment. 
+
+.. code-block:: bash
+
+   conda create -y -n napari-env -c conda-forge python=3.9
+   conda activate napari-env
+
+
+After creating the Conda environment,
+install Napari using pip 
+
+.. code-block:: bash
+
+   python -m pip install "napari[all]"
+   python -m pip install "napari[all]" --upgrade
+
+
+or using conda
+
+.. code-block:: bash
+
+   conda install -c conda-forge napari
+   conda update napari
+
+
+Next, Nyxus must be installed. Note that the version of Nyxus must be greater than or equal to `0.50` to run the Napari plugin.
+
+.. code-block:: bash
+
+   pip install nyxus
+
+
+or build from source using the instructions at https://github.com/PolusAI/nyxus#building-from-source using the conda build for the
+python API.
+
+After installing Napari and Nyxus, the Nyxus Napari plugin can be installed by cloning this repo and then building the plugin from the source. 
+An example of this process is provided below.
+
+.. code-block:: bash
+
+   git clone https://github.com/PolusAI/napari-nyxus.git
+   cd napari_nyxus
+   pip install -e .
+
+
+Napari can then be ran by running 
+
+.. code-block:: bash
+
+   napari
+
+
+Use
+===
+After installing the plugin, start Napari by running the command `napari` from the command line. Once the Napari 
+GUI is loaded, the Nyxus plugin can be loaded from the `Plugins` menu in the toolbar by going to Plugins -> nyxus-napari.
+
+.. image:: https://github.com/PolusAI/napari-nyxus/raw/main/docs/source/img/plugin_menu.png
+
+A widget will appear in the Napari viewer to run Nyxus.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   Examples
+

environment.yml

@@ -0,0 +1,12 @@
+channels:
+  - conda-forge
+  - https://repo.continuum.io/pkgs/free
+  - defaults
+dependencies:
+  - python=3.10
+  - pip:
+    - sphinx
+    - sphinx_rtd_theme
+    - autodocsumm
+    - sphinx-autodoc-typehints
+    - sphinx_rtd_theme==1.0.0