Simplify code

doc/source/usage.rst

@@ -41,17 +41,15 @@ Usage
 
 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.
+Foa3D accepts 3D grayscale or RGB image stacks in TIFF format.
+Alternatively, a YAML stitch file created by the ZetaStitcher tool for large volumetric stack alignment
+and stitching [`ZetaStitcher GitHub <https://github.com/lens-biophotonics/ZetaStitcher>`_] can be used as input.
+To generate this stitch file from a collection of adjacent 3D stacks composing a tiled reconstruction of brain tissue,
+refer to the documentation at [`ZetaStitcher GitHub <https://github.com/lens-biophotonics/ZetaStitcher>`_].
+In particular, the Foa3D tool uses the 3D stack alignment information contained in such a file to programmatically
+access and process basic image sub-volumes of appropriate size, allowing for the analysis of high-resolution mesoscopic
+microscopy images that exceed the typical memory available on low-resource machines.
+The YAML and image stack files must be in the same directory.
 
 .. code-block:: console
 
@@ -61,8 +59,8 @@ The .yml and the image stack files must be located within the same directory.
 
 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:
+The lateral and longitudinal voxel size (in μm) must be specified via the command line,
+along with the 3D full width at half maximum of the point spread function of the employed microscopy apparatus:
 
 .. code-block:: console
 
@@ -71,7 +69,7 @@ along with the full width at half maximum of the point spread function of the em
 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.
+image sub-volumes typically 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.
 
@@ -82,7 +80,7 @@ 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
+the optimal scales that 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 γ.
@@ -103,16 +101,20 @@ cross-sectional diameter of 5 and 10 μm, with an automatic (local) contrast sen
 
    $ ... -a 0.00001 -b 0.1 -s 1.25 2.5
 
+Please keep in mind that the above automatic local adjustment of the γ sensitivity may produce discontinuities
+between the fiber orientation vector fields resulting from adjacent image slices.
+
 .. _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:
+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 appropriate shape and assigns them to separate concurrent workers.
+By default, Foa3D will use all available logical cores—for instance, a batch of 32 image slices will be simultaneously
+processed on a 32-core CPU. The multiscale Frangi filter, on the other hand, is not currently parallelized in order to
+avoid unnecessary overhead and resource oversubscription within the nested parallel loop. The size of the basic image
+slices is automatically determined by the available RAM. The ``--job`` and ``--ram`` options can be specified
+differently via the command line to limit the employed resources.
 
 .. code-block:: console
 
@@ -122,13 +124,11 @@ 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 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:
+A neuronal soma fluorescence channel may be optionally provided to Foa3D for improving the specificity of the resulting 
+fiber orientation maps, which is otherwise dependent on the inherent attenuation of non-tubular objects offered by the 
+Frangi filter. This is performed via a postprocessing step that further suppresses neuronal bodies by 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
 
@@ -191,7 +191,7 @@ by selecting the "export all" option (-e or --exp-all) via CLI.
 
 #. Orientation distribution functions (ODF) stage (one file for each super-voxel size requested via CLI):
 
-    * **ODF** (*path/to/save_dir/odf/odf_mrtrixview_\*cfg_sfx\, type: float32, format: NIfTI)
+    * **ODF** (*path/to/save_dir/odf/odf_mrtrixview_\*cfg_sfx\**, type: float32, format: NIfTI)
 
     * **ODF background** (*path/to/save_dir/odf/bg_mrtrixview_\*cfg_sfx\**, type: uint8, format: NIfTI)
 

foa3d/__main__.py

@@ -1,7 +1,7 @@
 from foa3d.input import get_cli_parser, load_microscopy_image
-from foa3d.pipeline import parallel_odf_over_scales, parallel_frangi_over_slices
+from foa3d.pipeline import parallel_frangi_over_slices, parallel_odf_over_scales
 from foa3d.printing import print_pipeline_heading
-from foa3d.utils import delete_tmp_folder
+from foa3d.utils import delete_tmp_data
 
 
 def foa3d(cli_args):
@@ -12,15 +12,14 @@ def foa3d(cli_args):
     # parallel 3D Frangi-based fiber orientation analysis on batches of basic image slices
     out_img = parallel_frangi_over_slices(cli_args, save_dirs, in_img)
 
-    # generate 3D fiber ODF maps over the spatial scales of interest using concurrent workers
-    parallel_odf_over_scales(cli_args, save_dirs, out_img['vec'], out_img['iso'], out_img['px_sz'], in_img['name'])
+    # generate 3D fiber ODF maps at the spatial scales of interest using concurrent workers
+    parallel_odf_over_scales(cli_args, save_dirs, out_img, in_img['name'])
 
     # delete temporary folder
-    delete_tmp_folder(save_dirs['tmp'], (in_img, out_img))
+    delete_tmp_data(save_dirs['tmp'], (in_img, out_img))
 
 
 def main():
-    # start Foa3D by terminal
     print_pipeline_heading()
     foa3d(cli_args=get_cli_parser())