clinicadl.data.structures.DataPoint¶

class clinicadl.data.structures.DataPoint(image: ScalarImage | Path | str, participant_id: str, session_id: str, **kwargs: Any) → None[source]¶

Data structure that gathers an image and any other relevant information associated to the image.

It inherits from torchio.Subject, which inherits itself from Python’s dict.

A DataPoint can contain any type of values, but you are encouraged to store your images in torchio.ScalarImage and your masks in torchio.LabelMap.

A DataPoint has the following attributes:

image: the image, in a torchio.ScalarImage;
participant_id: the id of the participant, in a str;
session_id: the id of the session, in a str.

You can easily access these elements using the attribute notation:

>>> import torchio as tio
>>> import torch
>>> import numpy as np
>>> datapoint = DataPoint(
        image=tio.ScalarImage(tensor=torch.randn(1, 10, 10, 10), affine=np.eye(4)),
        participant_id="sub-001",
        session_id="ses-M000",
    )
>>> datapoint.session_id
'ses-M000'

To add, modify, or delete any other field, you can use the standard dictionary syntax:

>>> datapoint["age"] = 55
>>> datapoint["age"]
55

To add an image or a mask to the DataPoint, prefer add_image() and add_mask().

To get all the images in your DataPoint, you can use get_images_dict().

If all the images and masks of your DataPoint have the same shape, voxel spacing or affine matrix, you can easily access them via the attributes shape (or spatial_shape to remove the channel dimension), spacing and affine respectively.

Finally, you may also be interested in plot() to plot images inside your DataPoint.

As DataPoint is a subclass of torchio.Subject, you can also used all the other methods it inherits from.

Parameters:

image (Union[torchio.ScalarImage, PathType]) – The image, as a torchio.ScalarImage or a path to a NIfTI file.
participant_id (str) – The participant id.
session_id (str) – The session id.
kwargs (Any) – Any other information to store in the DataPoint.

property shape¶

Returns the shape of the images in the DataPoint.

Consistency of shapes across images in the DataPoint is checked first.

Examples

>>> from clinicadl.data.structures.examples import Colin27DataPoint
>>> datapoint = Colin27DataPoint()
>>> datapoint.shape
(1, 181, 217, 181)

property spatial_shape¶

Returns the spatial shape of the images in the DataPoint.

Consistency of spatial shapes across images in the DataPoint is checked first.

Examples

>>> from clinicadl.data.structures.examples import Colin27DataPoint
>>> datapoint = Colin27DataPoint()
>>> datapoint.spatial_shape
(181, 217, 181)

property spacing¶

Returns the voxel spacing of the images in the DataPoint.

Consistency of voxel spacings across images in the DataPoint is checked first (1e-3 relative tolerance).

Examples

>>> from clinicadl.data.structures.examples import Colin27DataPoint
>>> datapoint = Colin27DataPoint()
>>> datapoint.spacing
(1.0, 1.0, 1.0)

property affine¶

Returns affine matrix of the images in the DataPoint.

Consistency of matrices across images in the DataPoint is checked first (1e-3 relative tolerance).

Examples

>>> from clinicadl.data.structures.examples import Colin27DataPoint
>>> datapoint = Colin27DataPoint()
>>> datapoint.affine
array([[   1.,    0.,    0.,  -90.],
       [   0.,    1.,    0., -126.],
       [   0.,    0.,    1.,  -72.],
       [   0.,    0.,    0.,    1.]])

get_images_dict(intensity_only: bool = True, include: Sequence[str] | None = None, exclude: Sequence[str] | None = None) → dict[str, Image][source]¶

To get all the images in a DataPoint, and their names.

Parameters:

intensity_only (bool, default=True) – To get only the images (torchio.ScalarImage) and not the masks (torchio.LabelMap).
include (Optional[Sequence[str]], default=None) – Names of the images to include. If None, will return all the images specified by intensity_only and not in exclude.
exclude (Optional[Sequence[str]], default=None) – Names of the images to exclude.

Returns:

dict[str, torchio.Image] – The images and their names.

Examples

>>> from clinicadl.data.structures.examples import Colin27DataPoint
>>> datapoint = Colin27DataPoint()
>>> datapoint.get_images_dict()
{'image': ScalarImage(shape: (1, 181, 217, 181); spacing: (1.00, 1.00, 1.00); orientation: RAS+; path: ...)}

See also

get_masks_dict()

get_masks_dict(include: Sequence[str] | None = None, exclude: Sequence[str] | None = None) → dict[str, LabelMap][source]¶

To get all the masks in a DataPoint, and their names.

Parameters:

include (Optional[Sequence[str]], default=None) – Names of the masks to include. If None, will return all the masks not in exclude.
exclude (Optional[Sequence[str]], default=None) – Names of the masks to exclude.

Returns:

dict[str, torchio.LabelMap] – The masks and their names.

Examples

>>> from clinicadl.data.structures.examples import Colin27DataPoint
>>> datapoint = Colin27DataPoint()
>>> datapoint.get_masks_dict()
{'head': LabelMap(shape: (1, 181, 217, 181); spacing: (1.00, 1.00, 1.00); orientation: RAS+; path: ...)}

See also

get_images_dict()

get_non_images_dict(include: Sequence[str] | None = None, exclude: Sequence[str] | None = None) → dict[str, Any][source]¶

To get all the values in the DataPoint that are not images or masks.

Parameters:

include (Optional[Sequence[str]], default=None) – Keys to include. If None, will return all the keys not in exclude.
exclude (Optional[Sequence[str]], default=None) – Keys to exclude.

Returns:

dict[str, Any] – The non-image values and their keys.

Examples

>>> from clinicadl.data.structures.examples import Colin27DataPoint
>>> datapoint = Colin27DataPoint()
>>> datapoint.get_non_images_dict()
{'participant_id': 'sub-colin', 'session_id': 'ses-M000'}

See also

get_images_dict()

get_image_tensor(image_name: str) → Tensor[source]¶

Returns a copy of the tensor associated to an image that is a torchio.Image.

Parameters:: image_name (str) – The name of the image in the DataPoint.
Returns:: torch.Tensor – The tensor image.

get_keys(include: Sequence[str] | None = None, exclude: Sequence[str] | None = None) → list[str][source]¶

To get the list of all the keys in a DataPoint.

Parameters:

include (Optional[Sequence[str]], default=None) – Keys to include. If None, will return all the keys not in exclude.
exclude (Optional[Sequence[str]], default=None) – Names of the keys to exclude.

Returns:

list[str] – The keys.

Examples

>>> from clinicadl.data.structures.examples import Colin27DataPoint
>>> datapoint = Colin27DataPoint()
>>> datapoint.get_keys()
['image', 'head', 'participant_id', 'session_id']
>>> datapoint.get_keys(exclude=["image"])
['head', 'participant_id', 'session_id']
>>> datapoint.get_keys(include=["image"])
['image']

add_image(image: ScalarImage | Path | str | Tensor, image_name: str) → None[source]¶

To add an image to the DataPoint.

Parameters:

image (Union[tio.ScalarImage, PathType, torch.Tensor]) – The image to add, as a torchio.ScalarImage, a path to the NIfTI file containing the image, or a 4D torch.Tensor (including one channel dimension). If a Tensor is passed, the same affine matrix as self.image will be used.
image_name (str) – The name that the image will take in the DataPoint.

Examples

>>> from clinicadl.data.structures.examples import Colin27DataPoint
>>> datapoint = Colin27DataPoint()
>>> datapoint
Colin27DataPoint(Keys: ('head', 'image', 'participant_id', 'session_id'); images: 2)
>>> datapoint.add_image(datapoint.image, "image_duplicate")
>>> datapoint
Colin27DataPoint(Keys: ('head', 'image', 'participant_id', 'session_id', 'image_duplicate'); images: 3)
>>> datapoint["image_duplicate"]
ScalarImage(shape: (1, 181, 217, 181); spacing: (1.00, 1.00, 1.00); orientation: RAS+; path: ...)

See also

add_mask()

add_mask(mask: ScalarImage | Path | str | Tensor, mask_name: str) → None[source]¶

To add a mask to the DataPoint.

Parameters:

mask (Union[tio.ScalarImage, PathType, torch.Tensor]) – The mask to add, as a torchio.LabelMap, a path to the NIfTI file containing the image, or a 4D torch.Tensor (including one channel dimension). If a Tensor is passed, the same affine matrix as self.image` will be used.
mask_name (str) – The name that the mask will take in the DataPoint.

Examples

>>> from clinicadl.data.structures.examples import Colin27DataPoint
>>> datapoint = Colin27DataPoint()
>>> datapoint
Colin27DataPoint(Keys: ('head', 'image', 'participant_id', 'session_id'); images: 2)
>>> datapoint.add_mask(datapoint["head"], "head_duplicate")
>>> datapoint
Colin27DataPoint(Keys: ('head', 'image', 'participant_id', 'session_id', 'head_duplicate'); images: 3)
>>> datapoint["head_duplicate"]
LabelMap(shape: (1, 181, 217, 181); spacing: (1.00, 1.00, 1.00); orientation: RAS+; path: ...)

See also

add_image()

plot(**kwargs) → None[source]¶

Plots images using matplotlib.

See torchio.Subject.plot() for more details.

remove_image(image_name: str) → None[source]¶: Removes an image from the DataPoint.