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,136 @@
+.. _usage:
+
+Usage
+=====
+
+.. _format:
+
+Microscopy image format
+-----------------------
+The Foa3D tool accepts as input 3D RGB or grayscale 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
+[`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.
+The .yml and the image stack files must be located within the same directory.
+
+.. code-block:: console
+
+   $ python -m foa3d 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:
+
+.. 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. 
+
+.. _frangi:
+
+Frangi filter configuration
+---------------------------
+Fiber enhancement 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 γ.
+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
+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.
+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:
+
+.. code-block:: console
+
+   $ ... -a 0.001 -b 10 -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 the Foa3D tool,
+in order to improve the specificity of the 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,
+if required, the default channel related to the soma fluorescence:
+
+.. code-block:: console
+
+   $ ... -n --ch-fiber 0 --ch-neuron 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
+
+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:
+
+.. code-block:: console
+
+   $ python -m foa3d.py fiber_vec.h5 --odf-res 100
+
+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>`_].

_sources/utils.rst.txt

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

_static/_sphinx_javascript_frameworks_compat.js

@@ -0,0 +1,134 @@
+/*
+ * _sphinx_javascript_frameworks_compat.js
+ * ~~~~~~~~~~
+ *
+ * Compatability shim for jQuery and underscores.js.
+ *
+ * WILL BE REMOVED IN Sphinx 6.0
+ * xref RemovedInSphinx60Warning
+ *
+ */
+
+/**
+ * select a different prefix for underscore
+ */
+$u = _.noConflict();
+
+
+/**
+ * small helper function to urldecode strings
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
+ */
+jQuery.urldecode = function(x) {
+    if (!x) {
+        return x
+    }
+    return decodeURIComponent(x.replace(/\+/g, ' '));
+};
+
+/**
+ * small helper function to urlencode strings
+ */
+jQuery.urlencode = encodeURIComponent;
+
+/**
+ * This function returns the parsed url parameters of the
+ * current request. Multiple values per key are supported,
+ * it will always return arrays of strings for the value parts.
+ */
+jQuery.getQueryParameters = function(s) {
+    if (typeof s === 'undefined')
+        s = document.location.search;
+    var parts = s.substr(s.indexOf('?') + 1).split('&');
+    var result = {};
+    for (var i = 0; i < parts.length; i++) {
+        var tmp = parts[i].split('=', 2);
+        var key = jQuery.urldecode(tmp[0]);
+        var value = jQuery.urldecode(tmp[1]);
+        if (key in result)
+            result[key].push(value);
+        else
+            result[key] = [value];
+    }
+    return result;
+};
+
+/**
+ * highlight a given string on a jquery object by wrapping it in
+ * span elements with the given class name.
+ */
+jQuery.fn.highlightText = function(text, className) {
+    function highlight(node, addItems) {
+        if (node.nodeType === 3) {
+            var val = node.nodeValue;
+            var pos = val.toLowerCase().indexOf(text);
+            if (pos >= 0 &&
+                !jQuery(node.parentNode).hasClass(className) &&
+                !jQuery(node.parentNode).hasClass("nohighlight")) {
+                var span;
+                var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
+                if (isInSVG) {
+                    span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+                } else {
+                    span = document.createElement("span");
+                    span.className = className;
+                }
+                span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+                node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+                    document.createTextNode(val.substr(pos + text.length)),
+                    node.nextSibling));
+                node.nodeValue = val.substr(0, pos);
+                if (isInSVG) {
+                    var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+                    var bbox = node.parentElement.getBBox();
+                    rect.x.baseVal.value = bbox.x;
+                    rect.y.baseVal.value = bbox.y;
+                    rect.width.baseVal.value = bbox.width;
+                    rect.height.baseVal.value = bbox.height;
+                    rect.setAttribute('class', className);
+                    addItems.push({
+                        "parent": node.parentNode,
+                        "target": rect});
+                }
+            }
+        }
+        else if (!jQuery(node).is("button, select, textarea")) {
+            jQuery.each(node.childNodes, function() {
+                highlight(this, addItems);
+            });
+        }
+    }
+    var addItems = [];
+    var result = this.each(function() {
+        highlight(this, addItems);
+    });
+    for (var i = 0; i < addItems.length; ++i) {
+        jQuery(addItems[i].parent).before(addItems[i].target);
+    }
+    return result;
+};
+
+/*
+ * backward compatibility for jQuery.browser
+ * This will be supported until firefox bug is fixed.
+ */
+if (!jQuery.browser) {
+    jQuery.uaMatch = function(ua) {
+        ua = ua.toLowerCase();
+
+        var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
+            /(webkit)[ \/]([\w.]+)/.exec(ua) ||
+            /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
+            /(msie) ([\w.]+)/.exec(ua) ||
+            ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
+            [];
+
+        return {
+            browser: match[ 1 ] || "",
+            version: match[ 2 ] || "0"
+        };
+    };
+    jQuery.browser = {};
+    jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
+}