Merge pull request #343 from jhlegarreta/doc/improve-dmri-data-doc

DOC: Improve the dMRI module documentation

Author: jhlegarreta

src/nifreeze/data/dmri/__init__.py

@@ -29,12 +29,12 @@
 
 **Gradient Table Representation**.
 The :class:`~nifreeze.data.dmri.base.DWI` class represents diffusion MRI data must
-be provided a gradient table, which is a :class:`numpy.ndarray` of shape (N, 4), where N
-is the number of diffusion-weighted volumes.
+be provided a gradient table, which is a :class:`numpy.ndarray` of shape ``(N, 4)``, where
+``N`` is the number of diffusion-weighted volumes.
 The first three columns represent the gradient directions (b-vectors), and the fourth column
 represents the b-values in s/mm².
 *NiFreeze* expects that the gradient directions are normalized to unit length for non-zero
-b-values, and that the b=0 volumes have a gradient direction of (0, 0, 0).
+b-values, and that the :math:`b=0` volumes have a gradient direction of :math:`(0, 0, 0)`.
 When non-unit b-vectors are detected, the corresponding b-value is automatically adjusted to
 reflect the actual diffusion weighting.
 If the input gradient table does not conform to these expectations, it will be automatically
@@ -47,14 +47,15 @@
 The :class:`~nifreeze.data.dmri.base.DWI` class requires a ``dataobj`` that can be an array-like
 object.
 The final step of the initialization process examines the data object and the gradient table,
-and removes b=0 volumes from the data **AND** the gradient table.
+and removes :math:`b=0` volumes from the data **AND** the gradient table.
 If no ``bzero`` parameter is provided, a reference low-b volume is computed as the median of all
-the low-b volumes (b < 50 s/mm²) and inserted in the ``DWI.bzero`` attribute.
+the low-b volumes (``b <`` :data:`~nifreeze.data.dmri.utils.DEFAULT_LOWB_THRESHOLD` s/mm²) and
+inserted in the :attr:`~nifreeze.data.dmri.base.DWI.bzero` attribute.
 Therefore, ***NiFreeze* WILL NOT be able to reconstruct the original data organization**.
 This design choice simplifies the internal representation and processing of diffusion MRI data.
-If you want to calculate a b=0 reference map in a more sophisticated way (e.g., after realignment
-of all the low-b volumes), you should handle this separately and feed your own reference through
-the ``bzero`` parameter.
+If you want to calculate a :math:`b=0` reference map in a more sophisticated way (e.g., after
+realignment of all the low-b volumes), you should handle this separately and feed your own
+reference through the ``bzero`` parameter.
 
 """
 

src/nifreeze/data/dmri/base.py

@@ -61,7 +61,7 @@ def validate_gradients(
 
     Parameters
     ----------
-    inst : :obj:`~nifreeze.data.dmri.DWI`
+    inst : :obj:`~nifreeze.data.dmri.base.DWI`
         The instance being validated (unused; present for validator signature).
     attr : :obj:`~attrs.Attribute`
         The attribute being validated; attr.name is used in the error message.
@@ -190,7 +190,7 @@ def from_filename(cls, filename: Path | str) -> Self:
 
         Returns
         -------
-        :obj:`~nifreeze.data.dmri.DWI`
+        :obj:`~nifreeze.data.dmri.base.DWI`
             The constructed dataset with data loaded from the file.
 
         """

src/nifreeze/data/dmri/io.py

@@ -66,7 +66,7 @@ def from_nii(
         stored in the returned dataset.
     gradients_file : :obj:`os.pathlike`, optional
         A text file containing the gradients table, shape (N, C) where the last column
-        stores the b-values. If provided following the column-major convention(C, N),
+        stores the b-values. If provided following the column-major convention (C, N),
         it will be transposed automatically. If provided, it supersedes any .bvec / .bval
         combination.
     bvec_file : :obj:`os.pathlike`, optional
@@ -79,7 +79,7 @@ def from_nii(
 
     Returns
     -------
-    dwi : :obj:`~nifreeze.data.dmri.DWI`
+    dwi : :obj:`~nifreeze.data.dmri.base.DWI`
         A DWI object containing the loaded data, gradient table, and optional
         b-zero volume, and brainmask.
 
@@ -147,6 +147,9 @@ def to_nifti(
 
     Parameters
     ----------
+    dwi : :obj:`~nifreeze.data.dmri.base.DWI`
+        A DWI object containing the diffusion data to be written, including the
+        gradient table, and optional b-zero volume.
     filename : :obj:`os.pathlike`, optional
         The output NIfTI file path.
     write_hmxfms : :obj:`bool`, optional
@@ -163,6 +166,10 @@ def to_nifti(
     bvecs_dec_places : :obj:`int`, optional
         Decimal places to use when serializing b-vectors.
 
+    Returns
+    -------
+    nii : :obj:`~nibabel.Nifti1Image`
+        The main DWI data object.
     """
 
     no_bzero = dwi.bzero is None or not insert_b0

src/nifreeze/model/dmri.py

@@ -69,7 +69,7 @@ def __init__(self, dataset: DWI, max_b: float | int | None = None, **kwargs):
 
         Parameters
         ----------
-        dataset : :obj:`~nifreeze.data.dmri.DWI`
+        dataset : :obj:`~nifreeze.data.dmri.base.DWI`
             Reference to a DWI object.
 
         """
@@ -249,7 +249,7 @@ def __init__(
 
         Parameters
         ----------
-        dataset : :obj:`~nifreeze.data.dmri.DWI`
+        dataset : :obj:`~nifreeze.data.dmri.base.DWI`
             Reference to a DWI object.
         stat : :obj:`str`, optional
             Whether the summary statistic to apply is ``"mean"`` or ``"median"``.