Improve documentation

doc/source/usage.rst

@@ -1,72 +1,107 @@
+.. _installation:
+
+Installation
+============
+Create a virtual Python environment by executing the venv module:
+
+.. code-block:: console
+
+    $ python -m venv .foa3d_env
+
+Activate the newly created environment:
+
+.. code-block:: console
+
+    $ source .foa3d_env/bin/activate
+
+Install the wheel tool:
+
+.. code-block:: console
+
+    $ pip install wheel
+
+Build the Python wheel file by executing:
+
+.. code-block:: console
+
+    $ python setup.py bdist_wheel
+
+Install the wheel using pip:
+
+.. code-block:: console
+
+    $ pip install dist/foa3d-0.1.0-py3-none-any.whl
+
 .. _usage:
 
 Usage
 =====
 
 .. _format:
 
-Microscopy image format
------------------------
-The Foa3D tool accepts as input 3D RGB or grayscale image stacks in TIF/TIFF or NumPy format.
+Microscopy image formats
+------------------------
+Foa3D supports 3D grayscale or RGB image stacks in TIF/TIFF or NumPy format.
 Alternatively, a .yml stitch file generated by the ZetaStitcher tool for large volumetric stack alignment and stitching
 [`ZetaStitcher GitHub <https://github.com/lens-biophotonics/ZetaStitcher>`_]
-may be also provided. This .yml file can be generated following the detailed documentation available at
+may be also provided as input. This .yml file can be generated following the detailed documentation available at
 [`ZetaStitcher Documentation <https://lens-biophotonics.github.io/ZetaStitcher/>`_]
-from a collection of 3D stacks composing a tiled mesoscopic image of a brain tissue sample.
-In detail, the Foa3D tool employs the 3D stack alignment information included in the .yml file
-to programmatically access and process basic image sub-volumes,
-thus enabling the analysis of high-resolution microscopy reconstructions
-of considerable size even on low-resource machines.
+from a collection of 3D stacks composing a tiled reconstruction of a brain tissue sample.
+In detail, the Foa3D tool employs the 3D stack alignment information included in such file
+to programmatically access and process basic image sub-volumes of suitable size,
+thus enabling the analysis of high-resolution mesoscopic microscopy images
+(e.g., 10¹ - 10³ GB) which exceed the typical memory available on low-resource machines.
 The .yml and the image stack files must be located within the same directory.
 
 .. code-block:: console
 
-   $ python -m foa3d zetastitch.yml
+   $ foa3d path/to/zetastitch.yml
 
 .. _resolution:
 
 Microscopy image resolution
 ---------------------------
-The values (in μm) of the lateral and longitudinal pixel size should be specified via CLI,
-along with the full width at half maximum of the optical system's point spread function:
+The lateral and longitudinal voxel size (in μm) must be specified via CLI,
+along with the full width at half maximum of the point spread function of the employed microscopy apparatus:
 
 .. code-block:: console
 
    $ ... --px-size-xy 0.4 --px-size-z 1 --psf-fwhm-x 1.5 --psf-fwhm-y 1.4 --psf-fwhm-z 3.1
 
-This information is employed at the preprocessing stage of the pipeline to isotropize the image spatial resolution,
-by blurring the coronal XY-plane of the sliced microscopy sub-volumes;
-two-photon scanning and light-sheet fluorescence microscopes are indeed characterized by a poorer resolution
-along the direction of the optical axis: if not properly corrected, this anisotropy would then introduce
-a systematic bias in the resulting 3D fiber orientations. 
+This information is required at the preprocessing stage of the pipeline to properly isotropize the spatial resolution
+of the raw microscopy images. In detail, since two-photon scanning and light-sheet fluorescence microscopes are in
+general characterized by a poorer resolution along the direction of the optical axis, the XY-plane of the sliced
+image sub-volumes tipically needs to be blurred. A tailored Gaussian smoothing kernel is used in this regard.
+If not properly corrected, the residual anisotropy would otherwise introduce a systematic bias in the assessed
+3D fiber orientations.
 
 .. _frangi:
 
 Frangi filter configuration
 ---------------------------
-Fiber enhancement is achieved via a multiscale 3D Frangi filter [`Frangi, et al., 1998 <https://doi.org/10.1007/BFb0056195>`_].
+Fiber enhancement and masking is achieved via a multiscale 3D Frangi filter [`Frangi, et al., 1998 <https://doi.org/10.1007/BFb0056195>`_].
 The spatial scales of the filter (in μm) can be provided via the ``-s/--scales`` option.
 As discussed in [`Sorelli, et al., 2023 <https://doi.org/10.1038/s41598-023-30953-w>`_],
 the optimal scales which best preserve the original intensity
 and cross-sectional size of the 3D tubular structures present in the analized images
 correspond to half of their expected radius.
-The Frangi filter is also characterized by three sensitivity parameters, α, β, and γ.
+The response of the Frangi filter is also affected by three sensitivity parameters, α, β, and γ.
 In detail, lower α values tend to amplify the response of the filter to the presence of elongated structures,
 whereas an increase in β determines a relatively higher sensitivity to blob-shaped structures.
-Usually, the α and β sensitivity parameters are heuristically fixed for the specific application
+Usually, the α and β sensitivity parameters need to be heuristically fixed for the specific application
 or image modality of interest:
 the default values, namely ``α=0.001`` and ``β=1``, were shown to lead to a marked selective enhancement of
-tubular fiber structures, and to a considerable rejection of the cell soma in two-photon fluorescence microscopy images.
+tubular fiber structures, and to a considerable rejection of the neuronal soma.
 Whereas α and β are linked to grey-level-invariant geometrical features,
 the γ sensitivity is related to the image contrast:
 if not specified by the user, this parameter is automatically set to half of the maximum Hessian norm computed
-at each spatial scale of interest.
-In the example below, the Frangi filter is tuned for fibers having a cross-sectional diameter of 5 and 10 μm,
-with an automatic contrast sensitivity:
+at each spatial scale of interest for each sliced image sub-volume.
+In the example below, the 3D Frangi filter is tuned so as to favour the enhancement of fiber structures having a
+cross-sectional diameter of 5 and 10 μm, with an automatic (local) contrast sensitivity:
 
 .. code-block:: console
 
-   $ ... -a 0.001 -b 10 -s 1.25 2.5
+   $ ... -a 0.00001 -b 0.1 -s 1.25 2.5
 
 .. _parallelization:
 
@@ -87,17 +122,17 @@ The ``--job`` and ``--ram`` options may be otherwise specified via CLI in order
 
 Soma rejection
 --------------
-A neuronal soma fluorescence channel may be optionally provided to the Foa3D tool,
-in order to improve the specificity of the fiber orientation maps
+A neuronal soma fluorescence channel may be optionally provided to Foa3D,
+in order to improve the specificity of the resulting fiber orientation maps
 achieved thanks to the inherent attenuation of non-tubular objects offered by the Frangi filter.
 This is performed via a postprocessing step which further suppresses neuronal bodies
-using Yen's automatic thresholding algorithm.
-The enhanced neuronal body rejection may be activated via the ``-n/--neuron-mask`` option modifying,
+applying Yen's automatic thresholding algorithm to an optionally provided channel.
+The enhanced neuronal body rejection may be activated via the ``-c/--cell-msk`` option modifying,
 if required, the default channel related to the soma fluorescence:
 
 .. code-block:: console
 
-   $ ... -n --ch-fiber 0 --ch-neuron 1
+   $ ... -c --fb-ch 0 --bc-ch 1
 
 .. _odf:
 
@@ -121,16 +156,47 @@ the ``-o/--odf-res`` option:
 
 .. code-block:: console
 
-   $ ... --odf-res 25 50
+   $ ... --odf-res 25 50 100 200
 
-The Foa3D tool also provides the possibility to directly repeat the fiber ODFs estimation,
-skipping the Frangi filtering stage, if a pre-computed fiber orientation vector map is feeded as input
-in place of the raw microscopy image reconstruction. NumPy and HDF5 files are both supported:
+Foa3D also provides the possibility to directly execute the multiscale analysis of fiber ODFs,
+skipping the Frangi filter stage, on pre-computed fiber orientation vector fields (NumPy or TIFF format):
 
 .. code-block:: console
 
-   $ python -m foa3d.py fiber_vec.h5 --odf-res 100
+   $ foa3d.py path/to/fiber_vector_field.npy --odf-res 500 1000
 
 The fiber ODFs returned by the Foa3D tool may be accessed using the open source MRtrix3 software package
 for medical image processing and visualization
-[`Tournier, et al., 2019 <https://doi.org/10.1016/j.neuroimage.2019.116137>`_].
+[`Tournier, et al., 2019 <https://doi.org/10.1016/j.neuroimage.2019.116137>`_].
+
+Output
+------
+#. Frangi filter stage
+
+    * Normalized response of the Frangi filter (<i>frangi_filter_cfg_sbfx</i>, format: TIFF or NumPy)
+
+    * Thresholded response of the Frangi filter (<i>fiber_msk_cfg_sbfx</i>, format: TIFF or NumPy)
+
+    * Optional mask of neuronal cell bodies (<i>soma_msk_cfg_sbfx</i>, format: TIFF or NumPy)
+
+    * Fiber orientation vector field (<i>fiber_vec_cfg_sbfx</i>, format: TIFF or NumPy)
+
+    * Fiber orientation colormap (<i>fiber_cmap_cfg_sbfx</i>, format: TIFF or NumPy): 
+
+    * Fractional anisotropy (<i>frac_anis_cfg_sbfx</i>, format: TIFF or NumPy)
+
+#. Orientation distribution functions stage
+
+    * Orientation distribution functions (<i>odf_mrtrixview_cfg_sbfx</i>, format: NIfTI)
+
+    * ODF background (<i>bg_mrtrixview_cfg_sbfx</i>, format: NIfTI)
+
+    * Total orientation dispersion (<i>odi_tot_cfg_sbfx</i>, format: TIFF)
+
+    * Primary orientation dispersion (<i>odi_pri_cfg_sbfx</i>, format: TIFF)
+
+    * Secondary orientation dispersion (<i>odi_sec_cfg_sbfx</i>, format: TIFF)
+
+    * Orientation dispersion anisotropy (<i>odi_anis_cfg_sbfx</i>, format: TIFF)
+
+    * Disarray index (<i>disarray_cfg_sbfx</i>, format: TIFF)

foa3d/pipeline.py

@@ -162,28 +162,28 @@ def init_odf_volumes(vec_img_shp, tmp_dir, odf_scale, odf_degrees=6):
 
     Returns
     -------
-    odf: NumPy memory-map object or HDF5 dataset (axis order=(X,Y,Z,C), dtype=float32)
+    odf: NumPy memory-map object (axis order=(X,Y,Z,C), dtype=float32)
         initialized array of ODF spherical harmonics coefficients
 
-    bg_mrtrix: NumPy memory-map object or HDF5 dataset (axis order=(X,Y,Z), dtype=uint8)
+    bg_mrtrix: NumPy memory-map object (axis order=(X,Y,Z), dtype=uint8)
         initialized background for ODF visualization in MRtrix3
 
-    odi_pri: NumPy memory-map object or HDF5 dataset (axis order=(Z,Y,X), dtype=uint8)
+    odi_pri: NumPy memory-map object (axis order=(Z,Y,X), dtype=uint8)
         initialized array of primary orientation dispersion parameters
 
-    odi_sec: NumPy memory-map object or HDF5 dataset (axis order=(Z,Y,X), dtype=uint8)
+    odi_sec: NumPy memory-map object (axis order=(Z,Y,X), dtype=uint8)
         initialized array of secondary orientation dispersion parameters
 
-    odi_tot: NumPy memory-map object or HDF5 dataset (axis order=(Z,Y,X), dtype=uint8)
+    odi_tot: NumPy memory-map object (axis order=(Z,Y,X), dtype=uint8)
         initialized array of total orientation dispersion parameters
 
-    odi_anis: NumPy memory-map object or HDF5 dataset (axis order=(Z,Y,X), dtype=uint8)
+    odi_anis: NumPy memory-map object (axis order=(Z,Y,X), dtype=uint8)
         initialized array of orientation dispersion anisotropy parameters
 
-    disarray: NumPy memory-map object or HDF5 dataset (axis order=(Z,Y,X), dtype=float32)
+    disarray: NumPy memory-map object (axis order=(Z,Y,X), dtype=float32)
         local angular disarray
 
-    vec_tensor_eigen: NumPy memory-map object or HDF5 dataset (axis order=(Z,Y,X,C), dtype=float32)
+    vec_tensor_eigen: NumPy memory-map object (axis order=(Z,Y,X,C), dtype=float32)
         initialized array of fiber orientation tensor eigenvalues
     """