Merge pull request #75 from HelmholtzAI-Consultants-Munich/add-docume…

…ntation

Add documentation

.gitignore

@@ -19,7 +19,7 @@ __pycache__/
 
 # Distribution / packaging
 .Python
-build/
+# build/
 develop-eggs/
 dist/
 downloads/
@@ -80,7 +80,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+# docs/_build/
 
 # PyBuilder
 target/
@@ -151,7 +151,7 @@ dmypy.json
 .idea/
 
 .DS_Store
-docs/
+# docs/
 test-napari.pub
 data/
 BentoML/

README.md

@@ -29,3 +29,5 @@ Our platform encourages the use of data centric practices. With the user friendl
 - Focus on data curation: no interaction with model parameters during training and inference
 
 #### *Get more with less!*
+
+<img src="https://github.com/HelmholtzAI-Consultants-Munich/data-centric-platform/blob/main/src/client/readme_figs/dcp_pipeline.png"  width="200" height="200">

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/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: 71b4048acfc6728554424ff4c6c99afc
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/html/_sources/dcp_client.gui.rst.txt

@@ -0,0 +1,34 @@
+dcp\_client.gui package
+=======================
+
+.. automodule:: dcp_client.gui
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+dcp\_client.gui.main\_window module
+-----------------------------------
+
+.. automodule:: dcp_client.gui.main_window
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+dcp\_client.gui.napari\_window module
+-------------------------------------
+
+.. automodule:: dcp_client.gui.napari_window
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+dcp\_client.gui.welcome\_window module
+--------------------------------------
+
+.. automodule:: dcp_client.gui.welcome_window
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/build/html/_sources/dcp_client.rst.txt

@@ -0,0 +1,19 @@
+dcp\_client package
+===================
+
+
+.. toctree::
+   :maxdepth: 4
+
+   dcp_client.gui
+   dcp_client.utils
+
+
+dcp\_client.app module
+----------------------
+
+.. automodule:: dcp_client.app
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

docs/build/html/_sources/dcp_client.utils.rst.txt

@@ -0,0 +1,51 @@
+dcp\_client.utils package
+=========================
+
+.. automodule:: dcp_client.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+dcp\_client.utils.bentoml\_model module
+---------------------------------------
+
+.. automodule:: dcp_client.utils.bentoml_model
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+dcp\_client.utils.fsimagestorage module
+---------------------------------------
+
+.. automodule:: dcp_client.utils.fsimagestorage
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+dcp\_client.utils.settings module
+---------------------------------
+
+.. automodule:: dcp_client.utils.settings
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+dcp\_client.utils.sync\_src\_dst module
+---------------------------------------
+
+.. automodule:: dcp_client.utils.sync_src_dst
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+dcp\_client.utils.utils module
+------------------------------
+
+.. automodule:: dcp_client.utils.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

docs/build/html/_sources/dcp_client_installation.rst.txt

@@ -0,0 +1,150 @@
+.. _DCP Client:
+
+DCP Client
+===========
+
+The client of our data centric platform for microscopy imaging.
+
+.. image:: https://img.shields.io/badge/stability-work_in_progress-lightgrey.svg
+   :alt: stability-wip
+
+Installation
+-------------
+
+Before starting make sure you have navigated to ``data-centric-platform/src/client``. All future steps expect you are in the client directory. This installation has been tested using a conda environment with python version 3.9 on a mac local machine. In your dedicated environment run:
+
+.. code-block:: bash
+
+   pip install -e .
+
+Running the client: A step-by-step guide!
+------------------------------------------
+
+1. **Configurations**
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+   Before launching the GUI you will need to set up your client configuration file, ``dcp_client/config.cfg``. Please, obey the `formal JSON format <https://www.json.org/json-en.html>`_. Here, we will define how the client will interact with the server. There are currently two options available: running the server locally, or connecting to the running instance on the FZJ jusuf-cloud. To connect to a locally running server, set:
+
+   .. code-block:: json
+
+      "server":{
+                 "user": "local",
+                 "host": "local",
+                 "data-path": "None",
+                 "ip": "localhost",
+                 "port": 7010
+      }
+
+   To connect to the running service on jusuf-cloud, set:
+
+   .. code-block:: json
+
+        "server":{
+               "user": "rocky",
+               "host": "jsc-vm",
+               "data-path": "/home/rocky/dcp-data/my-project",
+               "ip": "134.94.198.230",
+               "port": 7010
+        }
+
+   Before continuing, you need to make sure that DCP server is running, either locally or on the cloud. See :doc: `dcp_server_installation` for instructions on how to launch the server. **Note:** In order for this connection to succeed, you will need to have contacted the team developing DCP, so they can add your IP to the list of accepted requests.
+
+   To make it easier for you we provide you with two config files, one works when running a local server and one for remote - just make sure you rename the config file you wish to use to ``config.cfg``. The default is local configuration.
+
+2. **Launching the client**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+   After setting your config simply run:
+
+   .. code-block:: bash
+
+      python dcp_client/main.py
+
+3. **Welcome window**
+~~~~~~~~~~~~~~~~~~~~~~
+
+   The welcome window should have now popped up.
+
+   .. image:: https://raw.githubusercontent.com/HelmholtzAI-Consultants-Munich/data-centric-platform/main/src/client/readme_figs/client_welcome_window.png
+         :width: 400
+         :height: 200
+         :align: center
+
+
+   Here you will need to select the directories which we will be using throughout the data centric workflow. The following directories need to be defined:
+
+   - **Uncurated Dataset Path:**
+
+   This folder is intended to store all images of your dataset. These images may be accompanied by corresponding segmentations. If present, segmentation files should share the same filename as their associated image, appended with a suffix as specified in ``server/dcp_server/config.cfg`` file (default: '_seg').
+
+   - **Curation in Progress Path (Optional):**
+
+   Images for which the segmentation is a work in progress should be moved here. Each image in this folder can have one or multiple segmentations corresponding to it (by changing the filename of the segmentation in the napari layer list after editing it, see **Viewer**). If you do not want to use an intermediate working dir, you can skip setting a path to this directory (it is not required). No future functions affect this directory, it is only used to move to and from the uncurated and curated directories.
+
+   - **Curated Dataset Path:**
+
+   This folder is intended to contain images along with their final segmentations. **Only** move images here when the segmentation is complete and finalised, you won't be able to change them after they have been moved here. These are then used for training your model.
+
+4. **Setting paths**
+~~~~~~~~~~~~~~~~~~~~~
+
+   After setting the paths for these three folders, you can click the **Start** button. If you have set the server configuration to the cloud, you will receive a message notifying you that your data will be uploaded to the cloud. Click **Ok** to continue.
+
+5. **Data Overview**
+~~~~~~~~~~~~~~~~~~~~
+
+   The main working window will appear next. This gives you an overview of the directories selected in the previous step along with three options:
+
+   - **Generate Labels:** Click this button to generate labels for all images in the "Uncurated dataset" directory. This will call the ``segment_image`` service from the server
+   - **View image and fix label:** Click this button to launch your viewer. The napari software is used for visualising, and editing the images segmentations. See **Viewer**
+   - **Train Model:** Click this model to train your model on the images in the "Curated dataset" directory. This will call the ``train`` service from the server
+
+   .. image:: https://raw.githubusercontent.com/HelmholtzAI-Consultants-Munich/data-centric-platform/main/src/client/readme_figs/client_data_overview_window.png
+      :width: 500
+      :height: 200
+      :align: center
+
+6. **The viewer**
+~~~~~~~~~~~~~~~~~~~~
+
+   In DCP, we use [napari](https://napari.org/stable) for viewing our images and masks, adding, editing or removing labels. An example of the viewer can be seen below. After adding or removing any objects and editing existing objects wherever necessary, there are two options available:
+
+   - Click the **Move to Curation in progress folder** if you are not 100% certain about the labels you have created. You can also click on the label in the labels layer and change the name. This will result in several label files being created in the *In progress folder*, which can be examined later on.  **Note:** When changing the layer name in Napari, the user should rename it such that they add their initials or any other new info after _seg. E.g., if the labels of 1_seg.tiff have been changed in the Napari viewer, then the appropriate naming would for example be: 1_seg_CB.tiff and not 1_CB_seg.tiff.
+   - Click the **Move to Curated dataset folder** if you are certain that the labels you are now viewing are final and require no more curation. These images and labels will later be used for training the machine learning model, so make sure that you select this option only if you are certain about the labels. If several labels are displayed (opened from the 'Curation in progress' step), make sure to **click** on the single label in the labels layer list you wish to be moved to the *Curated data folder*. The other images will then be automatically deleted from this folder.
+
+   .. image:: https://raw.githubusercontent.com/HelmholtzAI-Consultants-Munich/data-centric-platform/main/src/client/readme_figs/client_napari_viewer.png
+      :width: 900
+      :height: 500
+      :align: center
+
+Data centric workflow [intended usage summary]
+----------------------------------------------
+
+The intended usage of DCP would include the following:
+
+1. Setting up configuration, run client (with server already running) and select data directories
+2. Generate labels for data in *Uncurated data folder*
+3. Visualise the resulting labels with the viewer and correct labels wherever necessary - once done move the image *Curated data folder*. Repeat this step for a couple of images until a few are placed into the *Curated data folder*. Depending on the qualitative evaluation of the label generation you might want to include fewer or more images, i.e. if the resulting masks require few edits, then few images will most likely be sufficient, whereas if many edits to the mask are required it is likely that more images are needed in the *Curated data folder*. You can always start with a small number and adjust later
+4. Train the model with the images in the *Curated data folder*
+5. Repeat steps 2-4 until you are satisfied with the masks generated for the remaining images in the *Uncurated data folder*. Every time the model is trained in step 4, the masks generated in step 2 should be of higher quality, until the model need not be trained any more 
+
+   .. image:: https://raw.githubusercontent.com/HelmholtzAI-Consultants-Munich/data-centric-platform/main/src/client/readme_figs/dcp_pipeline.png
+      :width: 400
+      :height: 400
+      :align: center
+
+DCP Shortcuts
+-------------
+
+- In the Data Overview window, clicking on an image and the hitting the **Enter** key, is equivalent to clicking the 'View Image and Fix Label' button
+- The viewer accepts all Napari Shortcuts. The current list of the shortcuts for macOS can be see below:
+
+.. image:: https://raw.githubusercontent.com/HelmholtzAI-Consultants-Munich/data-centric-platform/add-documentation/src/client/readme_figs/napari_shortcuts.png
+   :width: 600
+   :height: 500
+   :align: center
+
+
+
+
+

docs/build/html/_sources/dcp_server.rst.txt

@@ -0,0 +1,52 @@
+dcp\_server package
+===================
+
+.. automodule:: dcp_server
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :exclude-members: dcp\_server.main module
+
+Submodules
+----------
+
+dcp\_server.fsimagestorage module
+---------------------------------
+
+.. automodule:: dcp_server.fsimagestorage
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+dcp\_server.models module
+-------------------------
+
+.. automodule:: dcp_server.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+dcp\_server.segmentationclasses module
+--------------------------------------
+
+.. automodule:: dcp_server.segmentationclasses
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+dcp\_server.serviceclasses module
+---------------------------------
+
+.. automodule:: dcp_server.serviceclasses
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+dcp\_server.utils module
+------------------------
+
+.. automodule:: dcp_server.utils
+   :members:
+   :undoc-members:
+   :show-inheritance: