Merge pull request #880 from TheDeanLab/more-docs

Getting closer

Author: AdvancedImagingUTSW

docs/source/api.rst

@@ -1,4 +1,4 @@
-API
+Software API
 =============
 
 .. autosummary::

docs/source/implementations/implementations.rst

@@ -1,5 +1,5 @@
 ===========================================
-Example Microscopes
+Implemented Microscopes
 ===========================================
 
 As an example of the flexibility of the **navigate** software, we describe several

docs/source/index.rst

@@ -6,23 +6,26 @@
 ############
 
 
-**navigate** is an open-source Python software for general microscope control. It focuses
-on smart microscopy applications by providing reusable acquisition and analysis routines,
-termed :ref:`features <features>`, that can be chained
-in arbitrary orders to create custom acquisition protocols. **navigate** is designed to accommodate the needs of
+**navigate** is an open-source Python software for light-sheet microscope control. It
+focuses on smart microscopy applications by providing reusable acquisition and
+analysis routines, termed :ref:`features <features>`, that can be chained
+in arbitrary orders to create custom acquisition protocols.
+**navigate** is designed to accommodate the needs of
 a diverse user base, from biologists with no programming experience to advanced
 technology developers.
 
 **Project Philosophy**
 =========================
 
 * Prioritize standard library imports for maximum stability, and minimize external
-dependencies.
+  dependencies.
 * Abstraction layer to drive different camera types, etc.
 * Plugin architecture for extensibility.
-* Maximize productivity for biological users through robust graphical user interface-based workflows.
+* Maximize productivity for biological users through robust graphical user
+  interface-based workflows.
 * Performant and responsive.
-* Brutally obvious, well-documented, clean code organized in an industry standard Model-View-Controller architecture.
+* Brutally obvious, well-documented, clean code organized in an industry standard
+  Model-View-Controller architecture.
 
 .. note::
 
@@ -43,16 +46,16 @@ dependencies.
 
 .. toctree::
    :caption: Getting Started
-   :maxdepth: 2
+   :maxdepth: 1
 
    quick_start
-   implementations/implementations
    software_installation
    i_want_to
 
+
 .. toctree::
    :caption: User Guide
-   :maxdepth: 2
+   :maxdepth: 1
 
    user_guide/hardware_overview
    user_guide/file_formats
@@ -63,31 +66,43 @@ dependencies.
 
 .. toctree::
    :caption: Development
-   :maxdepth: 2
+   :maxdepth: 1
 
    contributing/software_architecture
    contributing/contributing_guidelines
    contributing/feature_container
    user_guide/restapi
    plugin/plugin_home
 
+.. toctree::
+   :caption: Plugins
+   :maxdepth: 1
+
+   navigate Plugin Template <https://github.com/TheDeanLab/navigate-plugin-template>
+   navigate Confocal Projection Plugin <https://github.com/TheDeanLab/navigate-confocal-projection>
+   navigate at Scale <https://github.com/TheDeanLab/navigate-at-scale>
+   navigate MMCore Plugin <https://github.com/TheDeanLab/navigate-mmcore-plugin>
+   navigate ilastik Server <https://github.com/TheDeanLab/navigate-ilastik-server>
+
 .. toctree::
    :caption: Reference
-   :maxdepth: 2
+   :maxdepth: 1
 
+   implementations/implementations
    api
 
 
 **Authors**
 ============
-**Navigate** includes key contributions from numerous individuals, both past and present,
-in `The Dean Lab <https://www.dean-lab.org>`_. Please see the accompanying manuscript for a full list of contributors.
+**navigate** includes key contributions from numerous individuals, both past and
+present, in `The Dean Lab <https://www.dean-lab.org>`_. Please see the accompanying manuscript
+for a full list of contributors. :ref:`Outside contributors <contributing/contributing_guidelines>` are welcome.
 
 **Funding**
 ============
 **navigate** is supported by the
-`UT Southwestern and University of North Carolina Center for Cell Signaling
-<https://cellularsignaltransduction.org>`_, a Biomedical Technology Development and Dissemination (BTDD)
-Center funded by the NIH National Institute of General Medical Science (RM1GM145399), and
-the `Center for Metastatic Tumor Imaging <https://www.metastasis-imaging.org>`_ program, a
-Cellular Cancer Biology Imaging Research (CCBIR) program funded by the NIH National Cancer Institute (U54CA268072).
+
+- NIH National Institute of General Medical Science (RM1GM145399).
+- NIH National Cancer Institute (1U54CA268072).
+- `Simmons Comprehensive Cancer Center <https://www.utsouthwestern.edu/departments/simmons/>`_ Translational Seed Grant.
+- `UTSW President's Research Council <https://engage.utsouthwestern.edu/pages/membership-giving/membership-giving---presidents-research-council>`_

docs/source/software_installation.rst

@@ -12,7 +12,8 @@ Operating System Compatibility
 
 .. important::
    **navigate** is developed for use on Windows-based systems. This is due to the
-   compatibility of device drivers for various microscope hardware components, such as
+   compatibility of :ref:`device drivers <firmware_overview>` for various microscope
+   hardware components, such as
    cameras, stages, and data acquisition cards, which are predominantly designed for the
    Windows environment.
 
@@ -21,8 +22,8 @@ Operating System Compatibility
    include improper positioning of widgets and problems with resizing the GUI window.
    As such, the use of **navigate** on MacOS is not recommended.
 
-   The software is untested on Linux systems.Users considering the use of **navigate** 
-   software on Linux should proceed with caution and be prepared for potential 
+   The software is untested on Linux systems. Users considering the use of **navigate**
+   software on Linux should proceed with caution and be prepared for potential
    compatibility issues, especially with respect to device drivers.
 
 .. note::
@@ -33,16 +34,16 @@ Hardware Considerations
 -----------------------
 
 **navigate** will run on a mid-range laptop with at least 8 GB of RAM and a processor
-with two cores. Most of its operations are undemanding. Saving data at a reasonable 
-rate, however, will require an SSD. The hardware configuration for an example 
+with two cores. Most of its operations are undemanding. Saving data at a reasonable
+rate, however, will require an SSD. The hardware configuration for an example
 microscope control machine is shown below.
 
 .. important::
    Scientific cameras are capable of rapidly generating large amounts of high-resolution data.
-   As such, the read/write speed of the data storage device is a critical for smooth operation 
+   As such, the read/write speed of the data storage device is a critical for smooth operation
    of the software. For example, for a standard Hamamatsu camera with a 2048 x 2048 sensor,
    operating at 16-bit depth and 20 frames per second, the data save rate is approximately ~167 MB/s.
-   While such capabilities are well within the capabilities of modern SSDs, they are beyond the 
+   While such capabilities are well within the capabilities of modern SSDs, they are beyond the
    capabilities of most HDDs. Therefore, it is recommended to use a fast SSD data saving operations.
 
 
@@ -97,7 +98,7 @@ microscope control machine is shown below.
         - **Interface**: PCI-E x 8
 
     .. note::
-       The specifications listed are based on an example system configuration and can 
+       The specifications listed are based on an example system configuration and can
        be adjusted based on specific needs and availability.
 
 ---------------------
@@ -157,7 +158,7 @@ To install the bleeding edge version of **navigate**, run the following command:
 
 .. note::
 
-    If you are running the software on a computer that is not connected to microscope 
+    If you are running the software on a computer that is not connected to microscope
     hardware, you can add the flag ``-sh`` (``--synthetic-hardware``) to launch the
     program:
 
@@ -175,13 +176,16 @@ Open an ``Anaconda Prompt (Miniconda3)`` and enter the following.
     (base) conda activate navigate
     (navigate) navigate
 
-.. note::
+.. tip::
 
     If you are running Windows, you can create a desktop shortcut to **navigate** by
     right-clicking the Desktop, navigating to New and then Shortcut and entering
     ``%windir%\system32\cmd.exe "/c" C:\path\to\miniconda\Scripts\activate.bat navigate && navigate``
     into the location text box.
 
+    This provides a convenient executable shortcut to launch the software, which is
+    advantageous for users who are not comfortable with the command line.
+
 
 Developer install
 =================

docs/source/user_guide/file_formats.rst

@@ -50,34 +50,28 @@ Image Writing Benchmarks
 ------------------------
 
 To evaluate the performance of saving imaging data in different formats, we conducted
-benchmarks on a Linux-based system. We assessed the average disk write time for TIFF,
+benchmarks on a Linux-based system. We assessed the median disk write time for TIFF,
 OME-TIFF, H5, N5, and OME-Zarr formats across image resolutions of 512x512,
 1024x1024, and 2048x2048 under two conditions: (A) capturing 1000 single-plane
 images and (B) acquiring a single z-stack composed of 1000 planes. All times
-are measured in milliseconds. Bottom panel for both A and B has a reduced y-axis to
-highlight the differences in write times between the formats. Results are also
-presented in a table format below.
-
-The initial setup for writing H5/N5 files introduces
-significant overhead, and to a lesser extent for TIFF and OME-TIFF files, which
-elevates the average write time. However, the median write time remains consistently
-low and stable across most of the acquisition. For z-stack imaging, TIFF and OME-TIFF
-formats achieved write speeds of up to approximately 400 Hz for a 2048x2048 camera
+are measured in milliseconds. Results are presented below. For z-stack imaging, TIFF
+and OME-TIFF formats achieved write speeds of up to approximately 400 Hz for a 2048x2048 camera
 resolution, surpassing the operational speeds of most contemporary sCMOS cameras.
 The Big-TIFF variant was used for both TIFF and OME-TIFF formats to accommodate the
 large file sizes.
 
+Timelapse Imaging
+~~~~~~~~~~~~~~~~~
 
-.. image:: images/benchmarks.png
-    :width: 50%
-    :align: center
+1000 images acquired, with a single Z plane. Median write time reported in
+milliseconds.
 
 .. table::
    :widths: auto
    :align: center
 
    +-------------+---------+----------+-------+-------+---------+
-   | Z=1, T=1000 | TIFF    | OME-TIFF | H5    | N5    | OME-Zarr|
+   |             | TIFF    | OME-TIFF | H5    | N5    | OME-Zarr|
    +=============+=========+==========+=======+=======+=========+
    | 512x512     | 4.06    | 15.26    | 2.79  | 12.09 | 1.35    |
    +-------------+---------+----------+-------+-------+---------+
@@ -86,12 +80,17 @@ large file sizes.
    | 2048x2048   | 22.25   | 38.57    | 34.71 | 29.56 | 11.85   |
    +-------------+---------+----------+-------+-------+---------+
 
+Z-Stack Imaging
+~~~~~~~~~~~~~~~
+
+1 image acquired, with 1000 Z planes. Median write speed time in milliseconds.
+
 .. table::
    :widths: auto
    :align: center
 
    +--------------+---------+----------+-------+-------+---------+
-   | Z=1000, T=1  | TIFF    | OME-TIFF | H5    | N5    | OME-Zarr|
+   |              | TIFF    | OME-TIFF | H5    | N5    | OME-Zarr|
    +==============+=========+==========+=======+=======+=========+
    | 512x512      | 0.21    | 0.17     | 4.76  | 1.80  | 1.30    |
    +--------------+---------+----------+-------+-------+---------+
@@ -100,6 +99,17 @@ large file sizes.
    | 2048x2048    | 2.35    | 2.14     | 75.56 | 14.08 | 8.60    |
    +--------------+---------+----------+-------+-------+---------+
 
+Additional Sources of Overhead
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The initial setup for writing H5/N5 files introduces
+significant overhead, and to a lesser extent for TIFF and OME-TIFF files, which
+elevates the average write time. However, the median write time remains consistently
+low and stable across most of the acquisition.
+
+Computer Specifications for Benchmarks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The computer specifications that the benchmarks were performed on are as follows:
 
 -   Architecture: x86_64

docs/source/user_guide/hardware_overview.rst

@@ -28,7 +28,7 @@ configure each of these devices is provided :doc:`here <hardware/supported_hardw
         * Imagine Optics
    * - *Filter Wheel*
      -
-        * Applied Scientific Instrumentation with Tiger Controller
+        * ASI with Tiger Controller
         * Sutter Lambda 10-3
         * Sutter Lambda LS
    * - *Galvanometers*
@@ -44,8 +44,8 @@ configure each of these devices is provided :doc:`here <hardware/supported_hardw
    * - *Stages*
      -
         * Analog controlled galvanometers and piezoelectric stages.
-        * Applied Scientific Instrumentation with Tiger Controller
-        * Applied Scientific Instrumentation with MFC2000 Controller
+        * ASI with Tiger Controller
+        * ASI with MFC2000 Controller
         * Mad City Labs Nano-Drive
         * Physik Instrumente
         * Sutter MP285
@@ -57,3 +57,47 @@ configure each of these devices is provided :doc:`here <hardware/supported_hardw
    * - *Zoom*
      -
         * Dynamixel MX-28R
+
+
+Device Firmware
+===============
+
+.. _firmware_overview:
+
+
+**navigate** has been tested with the following firmware. Devices that are controlled
+with analog or digital voltages are omitted.
+
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - **Manufacturer**
+     - **Firmware Version**
+   * - *ASI*
+     -
+        * Tiger Controller 2.2.0.
+
+   * - *Dynamixel*
+     -
+        * Dynamixel MX-28R
+
+   * - *National Instruments*
+     -
+        * NI-DAQmx Device Drivers: 22.5.0, 22.8.0, 23.3.0, 23.8.0
+
+   * - *Hamamatsu*
+     -
+        * DCAM API: 20.7.641, 21.7.4321, 22.9.6509, 22.11.4321, 23.12.6736
+        * Camera Firmware: 2.21B, 2.53.A, 3.20.A, 4.30.B,
+        * Active Silicon CoaXpress: 1.10, 1.13, 1.21.
+
+   * - *Photometrics*
+     -
+        * PVCAM: 3.9.13
+
+   * - *Physik Instrumente*
+     -
+        * PIMikroMove: 2.36.1.0
+        * PI_GCS2_DLL: 3.22.0.0

docs/source/user_guide/restapi.rst

@@ -10,3 +10,5 @@ piece of software, but slower than direct access of the data in memory.
 
 An example of using our REST-API to communicate with ilastik, a widely used image segmentation tool,
 is provided in our Case Studies section :doc:`here <case_studies/ilastik_segmentation>`.
+The navigate ilastik Server plugin can be found `here <https://github
+.com/TheDeanLab/navigate-ilastik-server>`_.