Deploy to GitHub pages

.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: a1cadf375ab5b6d26fb199c590b807a2
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/frangi.rst.txt

@@ -0,0 +1,4 @@
+foa3d.frangi
+------------
+.. automodule:: foa3d.frangi
+    :members:

_sources/index.rst.txt

@@ -0,0 +1,21 @@
+Welcome to Foa3D's documentation!
+=================================
+
+.. mdinclude:: ../../README.md
+
+Latest package
+--------------
+.. exec::
+    from foa3d import __version__ as ver
+    print(f'The latest built package can be downloaded from `here <foa3d-{ver}-py3-none-any.whl>`_ (version {ver}).')
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+
+   usage
+   modules
+
+.. image:: _static/hbp_logo.png
+   :width: 150
+   :align: center

_sources/input.rst.txt

@@ -0,0 +1,4 @@
+foa3d.input
+-----------
+.. automodule:: foa3d.input
+    :members:

_sources/modules.rst.txt

@@ -0,0 +1,15 @@
+Python module index
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   frangi
+   input
+   odf
+   output
+   pipeline
+   preprocessing
+   printing
+   slicing
+   utils

_sources/odf.rst.txt

@@ -0,0 +1,4 @@
+foa3d.odf
+---------
+.. automodule:: foa3d.odf
+    :members:

_sources/output.rst.txt

@@ -0,0 +1,4 @@
+foa3d.output
+------------
+.. automodule:: foa3d.output
+    :members:

_sources/pipeline.rst.txt

@@ -0,0 +1,4 @@
+foa3d.pipeline
+--------------
+.. automodule:: foa3d.pipeline
+    :members:

_sources/preprocessing.rst.txt

@@ -0,0 +1,4 @@
+foa3d.preprocessing
+-------------------
+.. automodule:: foa3d.preprocessing
+    :members:

_sources/printing.rst.txt

@@ -0,0 +1,4 @@
+foa3d.printing
+--------------
+.. automodule:: foa3d.printing
+    :members:

_sources/slicing.rst.txt

@@ -0,0 +1,4 @@
+foa3d.slicing
+-------------
+.. automodule:: foa3d.slicing
+    :members:

_sources/usage.rst.txt

@@ -0,0 +1,202 @@
+.. _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 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 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 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
+
+   $ foa3d path/to/zetastitch.yml
+
+.. _resolution:
+
+Microscopy image resolution
+---------------------------
+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 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 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 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 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 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 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.00001 -b 0.1 -s 1.25 2.5
+
+.. _parallelization:
+
+Parallelization
+---------------
+In order to speed up the fiber orientation analysis on large brain tissue sections, the Foa3D pipeline divides
+the input image reconstruction into basic slices of suitable shape, and feeds them to separate concurrent workers.
+By default, Foa3D will use all available logical cores, splitting the multiscale fiber enhancement among parallel
+threads - e.g., 16 image slices will be simultaneously processed at 2 spatial scales of interest on a 32-core CPU.
+The size of these slices is automatically set depending on the currently available RAM.
+The ``--job`` and ``--ram`` options may be otherwise specified via CLI in order to limit the employed resources:
+
+.. code-block:: console
+
+   $ ... --jobs 8 --ram 32
+
+.. _somamask:
+
+Soma rejection
+--------------
+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
+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
+
+   $ ... -c --fb-ch 0 --bc-ch 1
+
+.. _odf:
+
+Orientation distribution functions
+----------------------------------
+High-resolution fiber orientation data obtained at the native pixel size of the imaging system can be integrated into 
+orientation distribution functions (ODFs), providing a comprehensive statistical description
+of 3D fiber tract orientations within larger spatial compartments or super-voxels.
+ODFs are highly suitable for a multimodal quantitative comparison with spatial fiber architectures
+mapped by other high-resolution optical modalities, as 3D-Polarized Light Imaging
+[`Axer, et al., 2016 <https://doi.org/10.3389/fnana.2016.00040>`_].
+Furthermore, the spatial downscaling produced by the ODF estimation allows to bridge the gulf between the meso-
+and macro-scale connectomics that is generally targeted by diffusion magnetic resonance imaging (dMRI).
+The Foa3D tool features the generation of fiber ODFs from the 3D orientation vector fields returned by
+the Frangi filtering stage via the fast analytical approach described in
+[`Alimi, et al., 2020 <https://doi.org/10.1016/j.media.2020.101760>`_].
+Alimi's method is computationally efficient and is characterized by improved angular precision and resolution
+with respect to deriving the ODFs by modeling local directional histograms of discretized fiber orientations.
+The multiscale estimation of fiber ODFs may be enabled by providing a list of super-voxel sides (in μm) via
+the ``-o/--odf-res`` option:
+
+.. code-block:: console
+
+   $ ... --odf-res 25 50 100 200
+
+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
+
+   $ 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>`_].
+
+Output
+------
+#. Frangi filter stage
+
+    * Normalized response of the Frangi filter (*frangi_filter_cfg_sbfx*, format: TIFF or NumPy, type: uint8)
+
+    * Binarized response of the Frangi filter (*fiber_msk_cfg_sbfx*, format: TIFF or NumPy, type: uint8)
+
+    * Optional mask of neuronal cell bodies (*soma_msk_cfg_sbfx*, format: TIFF or NumPy, type: uint8)
+
+    * Fiber orientation vector field (*fiber_vec_cfg_sbfx*, format: TIFF or NumPy, type: float32)
+
+    * Fiber orientation colormap (*fiber_cmap_cfg_sbfx*, format: TIFF or NumPy, type: uint8): 
+
+    * Fractional anisotropy (*frac_anis_cfg_sbfx*, format: TIFF or NumPy, type: float32)
+
+#. Orientation distribution functions (ODF) stage
+
+    * ODF (*odf_mrtrixview_cfg_sbfx*, format: NIfTI, type: float32)
+
+    * ODF background (*bg_mrtrixview_cfg_sbfx*, format: NIfTI, type: uint8)
+
+    * Total orientation dispersion (*odi_tot_cfg_sbfx*, format: TIFF, type: float32)
+
+    * Primary orientation dispersion (*odi_pri_cfg_sbfx*, format: TIFF, type: float32)
+
+    * Secondary orientation dispersion (*odi_sec_cfg_sbfx*, format: TIFF, type: float32)
+
+    * Orientation dispersion anisotropy (*odi_anis_cfg_sbfx*, format: TIFF, type: float32)
+
+    * Disarray index (*disarray_cfg_sbfx*, format: TIFF, type: float32)

_sources/utils.rst.txt

@@ -0,0 +1,4 @@
+foa3d.utils
+-----------
+.. automodule:: foa3d.utils
+    :members: