torchio 0.20.1__py3-none-any.whl

torchio/__init__.py

@@ -0,0 +1,48 @@
+"""Top-level package for torchio."""
+
+__author__ = """Fernando Perez-Garcia"""
+__email__ = 'fepegar@gmail.com'
+__version__ = '0.20.1'
+
+
+from . import datasets
+from . import reference
+from . import utils
+from .constants import *  # noqa: F401, F403
+from .data import GridAggregator
+from .data import GridSampler
+from .data import Image
+from .data import LabelMap
+from .data import LabelSampler
+from .data import Queue
+from .data import ScalarImage
+from .data import Subject
+from .data import SubjectsDataset
+from .data import SubjectsLoader
+from .data import UniformSampler
+from .data import WeightedSampler
+from .data import inference
+from .data import io
+from .data import sampler
+from .transforms import *  # noqa: F401, F403
+
+__all__ = [
+    'utils',
+    'io',
+    'sampler',
+    'inference',
+    'SubjectsDataset',
+    'SubjectsLoader',
+    'Image',
+    'ScalarImage',
+    'LabelMap',
+    'Queue',
+    'Subject',
+    'datasets',
+    'reference',
+    'WeightedSampler',
+    'UniformSampler',
+    'LabelSampler',
+    'GridSampler',
+    'GridAggregator',
+]

torchio/cli/apply_transform.py

@@ -0,0 +1,116 @@
+# pylint: disable=import-outside-toplevel
+
+from pathlib import Path
+
+import typer
+from rich.progress import Progress
+from rich.progress import SpinnerColumn
+from rich.progress import TextColumn
+
+app = typer.Typer()
+
+
+@app.command()
+def main(
+    input_path: Path = typer.Argument(  # noqa: B008
+        ...,
+        exists=True,
+        file_okay=True,
+        dir_okay=True,
+        readable=True,
+    ),
+    transform_name: str = typer.Argument(...),  # noqa: B008
+    output_path: Path = typer.Argument(  # noqa: B008
+        ...,
+        file_okay=True,
+        dir_okay=False,
+        writable=True,
+    ),
+    kwargs: str = typer.Option(  # noqa: B008
+        None,
+        '--kwargs',
+        '-k',
+        help='String of kwargs, e.g. "degrees=(-5,15) num_transforms=3".',
+    ),
+    imclass: str = typer.Option(  # noqa: B008
+        'ScalarImage',
+        '--imclass',
+        '-c',
+        help=(
+            'Name of the subclass of torchio.Image'
+            ' that will be used to instantiate the image.'
+        ),
+    ),
+    seed: int = typer.Option(  # noqa: B008
+        None,
+        '--seed',
+        '-s',
+        help='Seed for PyTorch random number generator.',
+    ),
+    verbose: bool = typer.Option(  # noqa: B008
+        False,
+        help='Print random transform parameters.',
+    ),
+    show_progress: bool = typer.Option(  # noqa: B008
+        True,
+        '--show-progress/--hide-progress',
+        '-p/-P',
+        help='Show animations indicating progress.',
+    ),
+):
+    """Apply transform to an image.
+
+    Example:
+    $ tiotr input.nrrd RandomMotion output.nii "degrees=(-5,15) num_transforms=3" -v
+    """
+    # Imports are placed here so that the tool loads faster if not being run
+    import torch
+
+    import torchio.transforms as transforms
+    from torchio.utils import apply_transform_to_file
+
+    try:
+        transform_class = getattr(transforms, transform_name)
+    except AttributeError as error:
+        message = f'Transform "{transform_name}" not found in torchio'
+        raise ValueError(message) from error
+
+    params_dict = get_params_dict_from_kwargs(kwargs)
+    transform = transform_class(**params_dict)
+    if seed is not None:
+        torch.manual_seed(seed)
+    with Progress(
+        SpinnerColumn(),
+        TextColumn('[progress.description]{task.description}'),
+        transient=True,
+        disable=not show_progress,
+    ) as progress:
+        progress.add_task('Applying transform', total=1)
+        apply_transform_to_file(
+            input_path,
+            transform,
+            output_path,
+            verbose=verbose,
+            class_=imclass,
+        )
+
+
+def get_params_dict_from_kwargs(kwargs):
+    from torchio.utils import guess_type
+
+    params_dict = {}
+    if kwargs is not None:
+        for substring in kwargs.split():
+            try:
+                key, value_string = substring.split('=')
+            except ValueError as error:
+                message = f'Arguments string "{kwargs}" not valid'
+                raise ValueError(message) from error
+
+            value = guess_type(value_string)
+            params_dict[key] = value
+    return params_dict
+
+
+if __name__ == '__main__':
+    app()

torchio/cli/print_info.py

@@ -0,0 +1,56 @@
+# pylint: disable=import-outside-toplevel
+from pathlib import Path
+
+import typer
+
+app = typer.Typer()
+
+
+@app.command()
+def main(
+    input_path: Path = typer.Argument(  # noqa: B008
+        ...,
+        exists=True,
+        file_okay=True,
+        dir_okay=True,
+        readable=True,
+    ),
+    plot: bool = typer.Option(  # noqa: B008
+        False,
+        '--plot/--no-plot',
+        '-p/-P',
+        help='Plot the image using Matplotlib or Pillow.',
+    ),
+    show: bool = typer.Option(  # noqa: B008
+        False,
+        '--show/--no-show',
+        '-s/-S',
+        help='Show the image using specialized visualisation software.',
+    ),
+    label: bool = typer.Option(  # noqa: B008
+        False,
+        '--label/--scalar',
+        '-l/-s',
+        help='Use torchio.LabelMap to instantiate the image.',
+    ),
+):
+    """Print information about an image and, optionally, show it.
+
+    Example:
+    $ tiohd input.nii.gz
+    """
+    # Imports are placed here so that the tool loads faster if not being run
+    import torchio as tio
+
+    class_ = tio.LabelMap if label else tio.ScalarImage
+    image = class_(input_path)
+    image.load()
+    print(image)  # noqa: T201
+    if plot:
+        image.plot()
+    if show:
+        image.show()
+
+
+if __name__ == '__main__':
+    app()

torchio/constants.py

@@ -0,0 +1,36 @@
+import torch
+
+# Image types
+INTENSITY = 'intensity'
+LABEL = 'label'
+SAMPLING_MAP = 'sampling_map'
+
+# Keys for dataset samples
+PATH = 'path'
+TYPE = 'type'
+STEM = 'stem'
+DATA = 'data'
+AFFINE = 'affine'
+TENSOR = 'tensor'
+
+# For aggregator
+IMAGE = 'image'
+LOCATION = 'location'
+
+# For special collate function
+HISTORY = 'history'
+
+# In PyTorch convention
+CHANNELS_DIMENSION = 1
+
+# Code repository
+REPO_URL = 'https://github.com/fepegar/torchio/'
+
+# Data repository
+DATA_REPO = 'https://github.com/fepegar/torchio-data/raw/main/data/'
+
+# Floating point error
+MIN_FLOAT_32 = torch.finfo(torch.float32).eps
+
+# For the queue
+NUM_SAMPLES = 'num_samples'

torchio/data/__init__.py

@@ -0,0 +1,29 @@
+from .dataset import SubjectsDataset
+from .image import Image
+from .image import LabelMap
+from .image import ScalarImage
+from .inference import GridAggregator
+from .loader import SubjectsLoader
+from .queue import Queue
+from .sampler import GridSampler
+from .sampler import LabelSampler
+from .sampler import PatchSampler
+from .sampler import UniformSampler
+from .sampler import WeightedSampler
+from .subject import Subject
+
+__all__ = [
+    'Queue',
+    'Subject',
+    'SubjectsDataset',
+    'SubjectsLoader',
+    'Image',
+    'ScalarImage',
+    'LabelMap',
+    'GridSampler',
+    'GridAggregator',
+    'PatchSampler',
+    'LabelSampler',
+    'WeightedSampler',
+    'UniformSampler',
+]

torchio/data/dataset.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import copy
+from typing import Callable
+from typing import Iterable
+from typing import List
+from typing import Optional
+from typing import Sequence
+
+from torch.utils.data import Dataset
+
+from ..utils import get_subjects_from_batch
+from .subject import Subject
+
+
+class SubjectsDataset(Dataset):
+    """Base TorchIO dataset.
+
+    Reader of 3D medical images that directly inherits from the PyTorch
+    :class:`~torch.utils.data.Dataset`. It can be used with a
+    :class:`~tio.SubjectsLoader` for efficient loading and
+    augmentation. It receives a list of instances of :class:`~torchio.Subject`
+    and an optional transform applied to the volumes after loading.
+
+    Args:
+        subjects: List of instances of :class:`~torchio.Subject`.
+        transform: An instance of :class:`~torchio.transforms.Transform`
+            that will be applied to each subject.
+        load_getitem: Load all subject images before returning it in
+            :meth:`__getitem__`. Set it to ``False`` if some of the images will
+            not be needed during training.
+
+    Example:
+        >>> import torchio as tio
+        >>> subject_a = tio.Subject(
+        ...     t1=tio.ScalarImage('t1.nrrd',),
+        ...     t2=tio.ScalarImage('t2.mha',),
+        ...     label=tio.LabelMap('t1_seg.nii.gz'),
+        ...     age=31,
+        ...     name='Fernando Perez',
+        ... )
+        >>> subject_b = tio.Subject(
+        ...     t1=tio.ScalarImage('colin27_t1_tal_lin.minc',),
+        ...     t2=tio.ScalarImage('colin27_t2_tal_lin_dicom',),
+        ...     label=tio.LabelMap('colin27_seg1.nii.gz'),
+        ...     age=56,
+        ...     name='Colin Holmes',
+        ... )
+        >>> subjects_list = [subject_a, subject_b]
+        >>> transforms = [
+        ...     tio.RescaleIntensity(out_min_max=(0, 1)),
+        ...     tio.RandomAffine(),
+        ... ]
+        >>> transform = tio.Compose(transforms)
+        >>> subjects_dataset = tio.SubjectsDataset(subjects_list, transform=transform)
+        >>> subject = subjects_dataset[0]
+
+    .. _NiBabel: https://nipy.org/nibabel/#nibabel
+    .. _SimpleITK: https://itk.org/Wiki/ITK/FAQ#What_3D_file_formats_can_ITK_import_and_export.3F
+    .. _DICOM: https://www.dicomstandard.org/
+    .. _affine matrix: https://nipy.org/nibabel/coordinate_systems.html
+
+    .. tip:: To quickly iterate over the subjects without loading the images,
+        use :meth:`dry_iter()`.
+    """
+
+    def __init__(
+        self,
+        subjects: Sequence[Subject],
+        transform: Optional[Callable] = None,
+        load_getitem: bool = True,
+    ):
+        self._parse_subjects_list(subjects)
+        self._subjects = subjects
+        self._transform: Optional[Callable]
+        self.set_transform(transform)
+        self.load_getitem = load_getitem
+
+    def __len__(self):
+        return len(self._subjects)
+
+    def __getitem__(self, index: int) -> Subject:
+        try:
+            index = int(index)
+        except (RuntimeError, TypeError) as err:
+            message = (
+                f'Index "{index}" must be int or compatible dtype,'
+                f' but an object of type "{type(index)}" was passed'
+            )
+            raise ValueError(message) from err
+
+        subject = self._subjects[index]
+        subject = copy.deepcopy(subject)  # cheap since images not loaded yet
+        if self.load_getitem:
+            subject.load()
+
+        # Apply transform (this is usually the bottleneck)
+        if self._transform is not None:
+            subject = self._transform(subject)
+        return subject
+
+    @classmethod
+    def from_batch(cls, batch: dict) -> SubjectsDataset:
+        """Instantiate a dataset from a batch generated by a data loader.
+
+        Args:
+            batch: Dictionary generated by a data loader, containing data that
+                can be converted to instances of :class:`~.torchio.Subject`.
+        """
+        subjects: List[Subject] = get_subjects_from_batch(batch)
+        return cls(subjects)
+
+    def dry_iter(self):
+        """Return the internal list of subjects.
+
+        This can be used to iterate over the subjects without loading the data
+        and applying any transforms::
+
+        >>> names = [subject.name for subject in dataset.dry_iter()]
+        """
+        return self._subjects
+
+    def set_transform(self, transform: Optional[Callable]) -> None:
+        """Set the :attr:`transform` attribute.
+
+        Args:
+            transform: Callable object, typically an subclass of
+                :class:`torchio.transforms.Transform`.
+        """
+        if transform is not None and not callable(transform):
+            message = (
+                'The transform must be a callable object,'
+                f' but it has type {type(transform)}'
+            )
+            raise ValueError(message)
+        self._transform = transform
+
+    @staticmethod
+    def _parse_subjects_list(subjects_list: Iterable[Subject]) -> None:
+        # Check that it's an iterable
+        try:
+            iter(subjects_list)
+        except TypeError as e:
+            message = f'Subject list must be an iterable, not {type(subjects_list)}'
+            raise TypeError(message) from e
+
+        # Check that it's not empty
+        if not subjects_list:
+            raise ValueError('Subjects list is empty')
+
+        # Check each element
+        for subject in subjects_list:
+            if not isinstance(subject, Subject):
+                message = (
+                    'Subjects list must contain instances of torchio.Subject,'
+                    f' not "{type(subject)}"'
+                )
+                raise TypeError(message)