From bb5d3e40078aab10184b7d025fa9c7b42556c404 Mon Sep 17 00:00:00 2001 From: msorelli Date: Tue, 15 Oct 2024 10:00:08 +0200 Subject: [PATCH] Improve documentation --- doc/source/usage.rst | 138 ++++++++++++++++++++++++++++++++----------- foa3d/pipeline.py | 16 ++--- 2 files changed, 110 insertions(+), 44 deletions(-) diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 60e9cd0..40773ca 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -1,3 +1,37 @@ +.. _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 @@ -5,68 +39,69 @@ 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 `_] -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 `_] -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 `_]. +Fiber enhancement and masking is achieved via a multiscale 3D Frangi filter [`Frangi, et al., 1998 `_]. The spatial scales of the filter (in μm) can be provided via the ``-s/--scales`` option. As discussed in [`Sorelli, et al., 2023 `_], 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 `_]. \ No newline at end of file +[`Tournier, et al., 2019 `_]. + +Output +------ +#. Frangi filter stage + + * Normalized response of the Frangi filter (frangi_filter_cfg_sbfx, format: TIFF or NumPy) + + * Thresholded response of the Frangi filter (fiber_msk_cfg_sbfx, format: TIFF or NumPy) + + * Optional mask of neuronal cell bodies (soma_msk_cfg_sbfx, format: TIFF or NumPy) + + * Fiber orientation vector field (fiber_vec_cfg_sbfx, format: TIFF or NumPy) + + * Fiber orientation colormap (fiber_cmap_cfg_sbfx, format: TIFF or NumPy): + + * Fractional anisotropy (frac_anis_cfg_sbfx, format: TIFF or NumPy) + +#. Orientation distribution functions stage + + * Orientation distribution functions (odf_mrtrixview_cfg_sbfx, format: NIfTI) + + * ODF background (bg_mrtrixview_cfg_sbfx, format: NIfTI) + + * Total orientation dispersion (odi_tot_cfg_sbfx, format: TIFF) + + * Primary orientation dispersion (odi_pri_cfg_sbfx, format: TIFF) + + * Secondary orientation dispersion (odi_sec_cfg_sbfx, format: TIFF) + + * Orientation dispersion anisotropy (odi_anis_cfg_sbfx, format: TIFF) + + * Disarray index (disarray_cfg_sbfx, format: TIFF) diff --git a/foa3d/pipeline.py b/foa3d/pipeline.py index c8f80d2..66fe7e9 100644 --- a/foa3d/pipeline.py +++ b/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 """