Update docs

TorchIO-project · Mar 2, 2020 · 6ae22d9 · 6ae22d9
1 parent 02832a2
commit 6ae22d9
Show file tree

Hide file tree

Showing 10 changed files with 127 additions and 82 deletions.
diff --git a/docs/source/data/image.rst b/docs/source/data/image.rst
@@ -1,6 +1,33 @@
 Images dataset
 ==============
 
+The :class:`ImagesDataset` class is one of the most important in TorchIO.
+It inherits directly from :class:`torch.utils.data.Dataset`.
+Here is a usage example:
+
+>>> import torchio
+>>> from torchio import ImagesDataset, Image, Subject
+>>> from torchio.transforms import Rescale, RandomAffine
+>>> from torchvision.transforms import Compose
+>>> subject_a = Subject([
+...     Image('t1', '~/Dropbox/MRI/t1.nrrd', torchio.INTENSITY),
+...     Image('label', '~/Dropbox/MRI/t1_seg.nii.gz', torchio.LABEL),
+>>> ])
+>>> subject_b = Subject(
+...     Image('t1', '/tmp/colin27_t1_tal_lin.nii.gz', torchio.INTENSITY),
+...     Image('t2', '/tmp/colin27_t2_tal_lin.nii', torchio.INTENSITY),
+...     Image('label', '/tmp/colin27_seg1.nii.gz', torchio.LABEL),
+... )
+>>> subjects_list = [subject_a, subject_b]
+>>> transforms = [
+...     Rescale((0, 1)),
+...     RandomAffine(),
+... ]
+>>> transform = Compose(transforms)
+>>> subjects_dataset = ImagesDataset(subjects_list, transform=transform)
+>>> subject_sample = subjects_dataset[0]
+
+
 .. currentmodule:: torchio.data.images
 
 :class:`ImagesDataset`

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -66,6 +66,6 @@ You can preview and run most features in TorchIO in this
    :maxdepth: 2
    :caption: API
 
-   datasets.rst
    data/data.rst
    transforms/transforms.rst
+   datasets.rst
diff --git a/docs/source/transforms/augmentation.rst b/docs/source/transforms/augmentation.rst
@@ -14,88 +14,79 @@ Augmentation
 .. currentmodule:: torchio.transforms
 
 
+
+Spatial
+-------
+
+:class:`RandomFlip`
+~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: RandomFlip
+    :show-inheritance:
+
+
+:class:`RandomAffine`
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: RandomAffine
+    :show-inheritance:
+
+
+:class:`RandomElasticDeformation`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: RandomElasticDeformation
+    :show-inheritance:
+
+
+
 Intensity
 ---------
 
 :class:`RandomMotion`
 ~~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: RandomMotion
-    :members:
     :show-inheritance:
 
 
 :class:`RandomGhosting`
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: RandomGhosting
-    :members:
     :show-inheritance:
 
 
 :class:`RandomSpike`
 ~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: RandomSpike
-    :members:
     :show-inheritance:
 
 
 :class:`RandomBiasField`
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: RandomBiasField
-    :members:
     :show-inheritance:
 
 
 :class:`RandomBlur`
 ~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: RandomBlur
-    :members:
     :show-inheritance:
 
 
 :class:`RandomNoise`
 ~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: RandomNoise
-    :members:
     :show-inheritance:
 
 
 :class:`RandomSwap`
 ~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: RandomSwap
-    :members:
-    :show-inheritance:
-
-
-
-Spatial
--------
-
-:class:`RandomElasticDeformation`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. autoclass:: RandomElasticDeformation
-    :members:
-    :show-inheritance:
-
-
-:class:`RandomAffine`
-~~~~~~~~~~~~~~~~~~~~~
-
-.. autoclass:: RandomAffine
-    :members:
-    :show-inheritance:
-
-
-:class:`RandomFlip`
-~~~~~~~~~~~~~~~~~~~
-
-.. autoclass:: RandomFlip
-    :members:
     :show-inheritance:
diff --git a/docs/source/transforms/others.rst b/docs/source/transforms/others.rst
@@ -8,5 +8,4 @@ Others
 ~~~~~~~~~~~~~~~
 
 .. autoclass:: Lambda
-    :members:
     :show-inheritance:
diff --git a/docs/source/transforms/preprocessing.rst b/docs/source/transforms/preprocessing.rst
@@ -10,7 +10,6 @@ Intensity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: NormalizationTransform
-    :members:
     :show-inheritance:
 
 
@@ -20,15 +19,13 @@ Intensity
 ~~~~~~~~~~~~~~~~
 
 .. autoclass:: Rescale
-    :members:
     :show-inheritance:
 
 
 :class:`ZNormalization`
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: ZNormalization
-    :members:
     :show-inheritance:
 
 
@@ -39,37 +36,32 @@ Spatial
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: CenterCropOrPad
-    :members:
     :show-inheritance:
 
 
 :class:`Crop`
 ~~~~~~~~~~~~~
 
 .. autoclass:: Crop
-    :members:
     :show-inheritance:
 
 
 :class:`Pad`
 ~~~~~~~~~~~~
 
 .. autoclass:: Pad
-    :members:
     :show-inheritance:
 
 
 :class:`Resample`
 ~~~~~~~~~~~~~~~~~
 
-.. autoclass:: Pad
-    :members:
+.. autoclass:: Resample
     :show-inheritance:
 
 
 :class:`ToCanonical`
 ~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: Pad
-    :members:
+.. autoclass:: ToCanonical
     :show-inheritance:
diff --git a/torchio/data/images.py b/torchio/data/images.py
@@ -135,22 +135,6 @@ class ImagesDataset(Dataset):
         check_nans: If ``True``, issues a warning if NaNs are found
             in the image
 
-    Example::
-
-        >>> import torchio
-        >>> from torchio import ImagesDataset, Image, Subject
-        >>> subject_a = Subject([
-        ...     Image('t1', '~/Dropbox/MRI/t1.nrrd', torchio.INTENSITY),
-        ...     Image('label', '~/Dropbox/MRI/t1_seg.nii.gz', torchio.LABEL),
-        >>> ])
-        >>> subject_b = Subject(
-        ...     Image('t1', '/tmp/colin27_t1_tal_lin.nii.gz', torchio.INTENSITY),
-        ...     Image('t2', '/tmp/colin27_t2_tal_lin.nii', torchio.INTENSITY),
-        ...     Image('label', '/tmp/colin27_seg1.nii.gz', torchio.LABEL),
-        ... )
-        >>> subjects_list = [subject_a, subject_b]
-        >>> subjects_dataset = ImagesDataset(subjects_list)
-        >>> subject_sample = subjects_dataset[0]
     """
     def __init__(
             self,

diff --git a/torchio/torchio.py b/torchio/torchio.py
@@ -18,6 +18,8 @@
     'TypeData',
     'TypeTuple',
     'TypeCallable',
+    'TypeRangeInt',
+    'TypeRangeFloat',
 ]
 
 INTENSITY = 'intensity'
@@ -35,4 +37,6 @@
 TypeNumber = Union[int, float]
 TypeData = Union[torch.Tensor, np.ndarray]
 TypeTuple = Union[int, Tuple[int, int, int]]
+TypeRangeInt = Union[int, Tuple[int, int]]
+TypeRangeFloat = Union[float, Tuple[float, float]]
 TypeCallable = Callable[[torch.Tensor], torch.Tensor]
diff --git a/torchio/transforms/augmentation/intensity/random_bias_field.py b/torchio/transforms/augmentation/intensity/random_bias_field.py
@@ -1,16 +1,3 @@
-"""
-The bias field is modelled as a linear combination of
-polynomial basis functions, as in
-
-    K. Van Leemput et al., 1999
-    Automated model-based tissue classification of MR images of the brain
-
-
-It was included in NiftyNet by Carole Sudre and used in:
-
-    C. Sudre et al., 2017
-    Longitudinal segmentation of age-related white matter hyperintensities
-"""
 
 from typing import Union, Tuple, Optional
 import numpy as np
@@ -21,9 +8,30 @@
 
 
 class RandomBiasField(RandomTransform):
+    r"""Random MRI bias field artifact.
+
+    The bias field is modelled as a linear combination of
+    polynomial basis functions, as in K. Van Leemput et al., 1999,
+    *Automated model-based tissue classification of MR images of the brain*.
+
+    It was added to NiftyNet by Carole Sudre and used in
+    C. Sudre et al., 2017, *Longitudinal segmentation of age-related
+    white matter hyperintensities*.
+
+    Args:
+        coefficients: Tuple of two floats :math:`(a, b)` to specify the
+            artifact magnitude of each coefficient.
+            If only one number :math:`n` is specified, all the coefficients
+            will be equal to :math:`n`.
+        order: Order of the basis polynomial functions.
+        proportion_to_augment:
+        seed:
+        verbose:
+
+    """
     def __init__(
             self,
-            coefficients: Union[float, Tuple[float]] = 0.5,
+            coefficients: Union[float, Tuple[float, float]] = 0.5,
             order: int = 3,
             proportion_to_augment: float = 1,
             seed: Optional[int] = None,

diff --git a/torchio/transforms/augmentation/random_transform.py b/torchio/transforms/augmentation/random_transform.py
@@ -8,7 +8,7 @@
 import torch
 import numpy as np
 from .. import Transform, Interpolation
-from ... import TypeNumber
+from ... import TypeNumber, TypeRangeFloat
 
 
 class RandomTransform(Transform):
@@ -73,13 +73,13 @@ def parse_range(
 
     def parse_degrees(
             self,
-            degrees: Union[float, Tuple[float]],
+            degrees: TypeRangeFloat,
             ) -> Tuple[float, float]:
         return self.parse_range(degrees, 'degrees')
 
     def parse_translation(
             self,
-            translation: Union[float, Tuple[float]],
+            translation: TypeRangeFloat,
             ) -> Tuple[float, float]:
         return self.parse_range(translation, 'translation')
 

diff --git a/torchio/transforms/augmentation/spatial/random_affine.py b/torchio/transforms/augmentation/spatial/random_affine.py
@@ -3,16 +3,56 @@
 import numpy as np
 import SimpleITK as sitk
 from ....utils import is_image_dict, check_consistent_shape
-from ....torchio import LABEL, DATA, AFFINE
+from ....torchio import LABEL, DATA, AFFINE, TypeRangeFloat
 from .. import Interpolation
 from .. import RandomTransform
 
 
 class RandomAffine(RandomTransform):
+    r"""Random affine transformation.
+
+    Args:
+        scales: Tuple :math:`(a, b)` defining the scaling
+            magnitude. The scaling values along each dimension are
+            :math:`(s_1, s_2, s_3)`, where :math:`s_i \sim \mathcal{U}(a, b)`.
+        degrees: Tuple :math:`(a, b)` defining the rotation range in degrees.
+            The rotation angles around each axis are
+            :math:`(\theta_1, \theta_2, \theta_3)`,
+            where :math:`\theta_i \sim \mathcal{U}(a, b)`.
+            If only one value :math:`d` is provided,
+            :math:`\theta_i \sim \mathcal{U}(-d, d)`.
+        isotropic: If ``True``, the scaling factor along all dimensions is the
+            same, i.e. :math:`s_1 = s_2 = s_3`.
+        image_interpolation: Interpolation type to use for resampling.
+            The available interpolation strategies are enumerated in
+            :class:`torchio.transforms.interpolation.Interpolation`.
+            For more information, visit
+            `ITK <https://itk.org/Doxygen/html/group__ImageInterpolators.html>`_
+            and `Simple ITK <https://simpleitk-prototype.readthedocs.io/en/latest/user_guide/transforms/plot_interpolation.html>`_
+            docs on image interpolation.
+        seed:
+        verbose:
+
+    .. note:: The image minimum is used as default value to fill missing values
+        during resampling.
+        This behavior might become customizable in the future.
+
+    Example:
+        >>> from torchio.transforms import RandomAffine, Interpolation
+        >>> sample = images_dataset[0]  # instance of torchio.ImagesDataset
+        >>> transform = RandomAffine(
+        ...     scales=(0.9, 1.2),
+        ...     degrees=(10),
+        ...     isotropic=False,
+        ...     image_interpolation=Interpolation.BSPLINE,
+        ... )
+        >>> transformed = transform(sample)
+
+    """
     def __init__(
             self,
             scales: Tuple[float, float] = (0.9, 1.1),
-            degrees: float = 10,
+            degrees: TypeRangeFloat = 10,
             isotropic: bool = False,
             image_interpolation: Interpolation = Interpolation.LINEAR,
             seed: Optional[int] = None,