dataset package

Submodules

dataset.dataset module

Module for the dataset classes and functions for the cardiac MRI images + reports.

class dataset.dataset.RemoveBlackLevelLiftByMin

Bases: Transform

Removes black level lift from input. Use before normalising.

transform(inpt: Any, params: dict[str, Any])

Method to override for custom transforms.

See How to write your own v2 transforms

class dataset.dataset.RemoveBlackLevelLiftByHistogram

Bases: Transform

Removes static black level lift using a histogram. Use before normalising.

transform(inpt: Any, params: dict[str, Any])

Method to override for custom transforms.

See How to write your own v2 transforms

class dataset.dataset.NormaliseImageFramesByHistogram

Bases: Transform

Normalise the image histogram per frame.

Ideally, this will remove flicker from the image frames (or may just introduce flicker itself, if this doesn’t work.)

Note: Run this before doing any dtype conversion or ImageNet normalisation. Expects a numpy array or Tensor.

transform(inpt: Any, params: dict[str, Any])

Method to override for custom transforms.

See How to write your own v2 transforms

class dataset.dataset.TemporalDenoiseTransform(temporal_window_size: int = 3, template_window_size: int = 7, filter_strength: float = 3, search_window_size: int = 21, *args, **kwargs)

Bases: Transform

Temporal denoiser.

transform(inpt: Any, params: dict[str, Any])

Method to override for custom transforms.

See How to write your own v2 transforms

class dataset.dataset.DefaultTransformsMixin

Bases: object

Mixin class for getting default transforms.

classmethod get_default_transforms(loading_mode: LoadingMode, augment: bool = False, image_size: int | Tuple[int, int] = (224, 224), histogram_equalize: bool = False) → tuple[Compose, Compose, Compose]

Get default transformations for the dataset.

The default implementation resizes the images to (224, 224), casts them to float32, normalises them, and sets them to greyscale if the loading mode is not RGB.

Parameters:

  • loading_mode – The loading mode for the images.

  • augment – Whether to augment the images and masks together.

  • image_size – Output image resolution.

  • histogram_equalize – Whether to normalise the image using histogram

  • equalisation.

Returns:

The image, mask, combined, and final resize transformations

class dataset.dataset.DefaultDatasetProtocol(*args, **kwargs)

Bases: Protocol

Mixin class for default attributes in Dataset implementations.

img_dir: str
train_idxs: list[int]
valid_idxs: list[int]
batch_size: int
class dataset.dataset.LGEDataset(img_dir: str, mask_dir: str, idxs_dir: str, transform_img: Compose, transform_mask: Compose, transform_together: Compose | None = None, batch_size: int = 8, mode: Literal['train', 'val', 'test'] = 'train', classification_mode: ClassificationMode = ClassificationMode.MULTICLASS_MODE, loading_mode: LoadingMode = LoadingMode.RGB, combine_train_val: bool = False, image_size: int | Tuple[int, int] = (224, 224))

Bases: Dataset[tuple[Tensor, Tensor, str]], DefaultTransformsMixin

LGE dataset for the cardiac LGE MRI images.

class dataset.dataset.CineDataset(img_dir: str, mask_dir: str, idxs_dir: str, transform_img: Compose, transform_mask: Compose, transform_together: Compose | None = None, frames: int = 30, select_frame_method: Literal['consecutive', 'specific'] = 'consecutive', batch_size: int = 4, mode: Literal['train', 'val', 'test'] = 'train', classification_mode: ClassificationMode = ClassificationMode.MULTICLASS_MODE, loading_mode: LoadingMode = LoadingMode.RGB, combine_train_val: bool = False, image_size: int | Tuple[int, int] = (224, 224))

Bases: Dataset[tuple[Tensor, Tensor, str]], DefaultTransformsMixin

Cine cardiac magnetic resonance imagery dataset.

class dataset.dataset.TwoPlusOneDataset(img_dir: str, mask_dir: str, idxs_dir: str, frames: int, select_frame_method: Literal['consecutive', 'specific'], transform_img: Compose, transform_mask: Compose, transform_together: Compose | None = None, batch_size: int = 2, mode: Literal['train', 'val', 'test'] = 'train', classification_mode: ClassificationMode = ClassificationMode.MULTICLASS_MODE, loading_mode: LoadingMode = LoadingMode.RGB, combine_train_val: bool = False, image_size: int | Tuple[int, int] = (224, 224))

Bases: CineDataset, DefaultTransformsMixin

Cine CMR dataset.

class dataset.dataset.ResidualTwoPlusOneDataset(img_dir: str, mask_dir: str, idxs_dir: str, frames: int, select_frame_method: Literal['consecutive', 'specific'], transform_img: Compose, transform_mask: Compose, transform_resize: Compose | Resize | None = None, transform_together: Compose | None = None, transform_residual: Compose | None = None, batch_size: int = 2, mode: Literal['train', 'val', 'test'] = 'train', classification_mode: ClassificationMode = ClassificationMode.MULTICLASS_MODE, loading_mode: LoadingMode = LoadingMode.RGB, combine_train_val: bool = False, residual_mode: ResidualMode = ResidualMode.SUBTRACT_NEXT_FRAME, image_size: int | Tuple[int, int] = (224, 224))

Bases: Dataset[tuple[Tensor, Tensor, Tensor, str]], DefaultTransformsMixin

Two stream dataset with cine images and residual frames.

classmethod get_default_transforms(loading_mode: LoadingMode, residual_mode: ResidualMode, augment: bool = False, image_size: int | Tuple[int, int] = (224, 224), histogram_equalize: bool = False) → tuple[Compose, Compose, Compose, Compose | None]

Get default transformations for the dataset.

The default implementation resizes the images to (224, 224), casts them to float32, normalises them, and sets them to greyscale if the loading mode is not RGB.

Parameters:

  • loading_mode – The loading mode for the images.

  • augment – Whether to augment the images and masks together.

  • image_size – Output image resolution.

  • histogram_equalize – Whether to normalise the image using histogram

  • equalisation.

Returns:

The image, mask, combined, and final resize transformations

class dataset.dataset.FourStreamDataset(lge_dir: str, cine_dir: str, mask_dir: str, txt_dir: str, idxs_dir: str, frames: int, select_frame_method: Literal['consecutive', 'specific'], transform_lge: Compose, transform_cine: Compose, transform_mask: Compose, transform_resize: Compose | None = None, transform_residual: Compose | None = None, transform_together: Compose | None = None, batch_size: int = 8, mode: Literal['train', 'val', 'test'] = 'train', classification_mode: ClassificationMode = ClassificationMode.BINARY_CLASS_3_MODE, loading_mode: LoadingMode = LoadingMode.GREYSCALE, combine_train_val: bool = False, residual_mode: ResidualMode = ResidualMode.SUBTRACT_NEXT_FRAME, image_size: int | Tuple[int, int] = (224, 224), tokenizer: str = 'microsoft/BiomedVLP-CXR-BERT-general', _use_dummy_reports: bool = False)

Bases: Dataset[tuple[Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, str]], DefaultTransformsMixin

LGE + Cine Sequence + Cine residuals + Textual reports dataset.

classmethod get_default_transforms(loading_mode: LoadingMode, residual_mode: ResidualMode, augment: bool = False, image_size: int | Tuple[int, int] = (224, 224)) → tuple[Compose, Compose, Compose, Compose, Compose | None]

Get default transformations for the dataset.

The default implementation resizes the images to (224, 224), casts them to float32, normalises them, and sets them to greyscale if the loading mode is not RGB.

Parameters:

  • loading_mode – The loading mode for the images.

  • augment – Whether to augment the images and masks together.

  • image_size – Output image resolution.

  • histogram_equalize – Whether to normalise the image using histogram

  • equalisation.

Returns:

The image, mask, combined, and final resize transformations

class dataset.dataset.ThreeStreamDataset(lge_dir: str, cine_dir: str, mask_dir: str, txt_dir: str, idxs_dir: str, frames: int, select_frame_method: Literal['consecutive', 'specific'], transform_lge: Compose, transform_cine: Compose, transform_mask: Compose, transform_resize: Compose | None = None, transform_residual: Compose | None = None, transform_together: Compose | None = None, batch_size: int = 8, mode: Literal['train', 'val', 'test'] = 'train', classification_mode: ClassificationMode = ClassificationMode.BINARY_CLASS_3_MODE, loading_mode: LoadingMode = LoadingMode.GREYSCALE, combine_train_val: bool = False, residual_mode: ResidualMode = ResidualMode.SUBTRACT_NEXT_FRAME, image_size: int | Tuple[int, int] = (224, 224), tokenizer: str = 'microsoft/BiomedVLP-CXR-BERT-general', _use_dummy_reports: bool = False)

Bases: Dataset[tuple[Tensor, Tensor, Tensor, Tensor, Tensor, str]], DefaultTransformsMixin

LGE + Cine residuals + Text dataset.

classmethod get_default_transforms(loading_mode: LoadingMode, residual_mode: ResidualMode, augment: bool = False, image_size: int | Tuple[int, int] = (224, 224)) → tuple[Compose, Compose, Compose, Compose, Compose | None]

Get default transformations for the dataset.

The default implementation resizes the images to (224, 224), casts them to float32, normalises them, and sets them to greyscale if the loading mode is not RGB.

Parameters:

  • loading_mode – The loading mode for the images.

  • augment – Whether to augment the images and masks together.

  • image_size – Output image resolution.

  • histogram_equalize – Whether to normalise the image using histogram

  • equalisation.

Returns:

The image, mask, combined, and final resize transformations

dataset.dataset.concatenate_imgs(frames: int, select_frame_method: Literal['consecutive', 'specific'], imgs: Tensor) → Tensor

Concatenate the images.

This is performed based on the number of frames and the method of selecting frames.

Parameters:

  • frames – The number of frames to concatenate.

  • select_frame_method – The method of selecting frames.

  • imgs – The tensor of images to select.

Returns:

The concatenated images.

Raises:

  • ValueError – If the number of frames is not within [5, 10, 15, 20, 30].

  • ValueError – If the method of selecting frames is not valid.

dataset.dataset.load_train_indices(dataset: DefaultDatasetProtocol, train_idxs_path: str, valid_idxs_path: str) → tuple[list[int], list[int]]

Load the training and validation indices for the dataset.

If the path to the indices are invalid, it then generates the indices in a possibly deterministic way. This method also sets the dataset.train_idxs and dataset.valid_idxs properties.

Parameters:

  • dataset – The dataset to load indices for.

  • train_idxs_path – Path to training indices pickle file.

  • valid_idxs_path – Path to validation indices pickle file.

Returns:

Training and Validation indices

Raises:

  • RuntimeError – If there are duplicates in the training and validation

  • indices. –

  • RuntimeError – If patients have images in both the training and testing.

  • AssertionError – If the training and validation indices are not disjoint.

Example

lge_dataset = LGEDataset() load_train_indices(lge_dataset, train_idxs_path, valid_idxs_path)

dataset.dataset.seed_worker(worker_id)

Set the seed for the worker based on the initial seed.

Parameters:

worker_id – The worker ID (not used).

dataset.dataset.get_trainval_data_subsets(train_dataset: DefaultDatasetProtocol, valid_dataset: DefaultDatasetProtocol | None = None) → tuple[Subset, Subset]

Get the subsets of the data as train/val splits from a superset.

Parameters:

  • train_dataset – The original train dataset.

  • valid_dataset – The original valid dataset.

Returns:

Training and validation subsets.

Raises:

AssertionError – Train and valid datasets are not the same.

dataset.dataset.get_trainval_dataloaders(dataset: DefaultDatasetProtocol) → tuple[DataLoader, DataLoader]

Get the dataloaders of the data as train/val splits from a superset.

The dataloaders are created using the SubsetRandomSampler to ensure that the training and validation sets are disjoint. The dataloaders are also set to have a fixed seed for reproducibility.

Parameters:

dataset – The original dataset.

Returns:

Training and validation dataloaders.

dataset.dataset.get_class_weights(train_set: Subset) → ndarray[tuple[int, ...], dtype[float32]]

Get the class weights based on the occurrence of the classes in the training set.

Parameters:

train_set – The training set.

Returns:

The class weights.

Raises:

  • AssertionError – If the subset’s dataset object has no classification_mode

  • attribute. –

  • AssertionError – If the classification mode is not multilabel.

dataset.optical_flow module

Optical flow calculation methods for video data.

dataset.optical_flow.dense_optical_flow(video: Sequence[Mat | ndarray]) → list[Mat | ndarray]

Compute dense optical flow on the CPU (slow).

Parameters:

video – Video frames to calculate optical flow with. Must be greyscale.

Returns:

Optical flow.

Raises:

AssertionError – Video is not greyscale.

dataset.optical_flow.cuda_optical_flow(video: Sequence[Mat | ndarray], threshold: float | None = None) → tuple[list[Mat | ndarray], list[Mat | ndarray] | None]

Compute dense optical flow with hardware acceleration on NVIDIA cards.

This method computes optical flow between all frames i with i + 1 for up to sequence length n-1, then computes for frame n and frame 0.

Parameters:

  • video – Video frames to calculate optical flow with. Must be greyscale.

  • threshold – Threshold to apply to the cost buffer. If set, the cost buffer will be returned as well.

Returns:

Optical flow, and cost buffer (if threshold is set)

Raises:

Module contents

Dataset classes.

class dataset.LGEDataset(img_dir: str, mask_dir: str, idxs_dir: str, transform_img: Compose, transform_mask: Compose, transform_together: Compose | None = None, batch_size: int = 8, mode: Literal['train', 'val', 'test'] = 'train', classification_mode: ClassificationMode = ClassificationMode.MULTICLASS_MODE, loading_mode: LoadingMode = LoadingMode.RGB, combine_train_val: bool = False, image_size: int | Tuple[int, int] = (224, 224))

Bases: Dataset[tuple[Tensor, Tensor, str]], DefaultTransformsMixin

LGE dataset for the cardiac LGE MRI images.

class dataset.CineDataset(img_dir: str, mask_dir: str, idxs_dir: str, transform_img: Compose, transform_mask: Compose, transform_together: Compose | None = None, frames: int = 30, select_frame_method: Literal['consecutive', 'specific'] = 'consecutive', batch_size: int = 4, mode: Literal['train', 'val', 'test'] = 'train', classification_mode: ClassificationMode = ClassificationMode.MULTICLASS_MODE, loading_mode: LoadingMode = LoadingMode.RGB, combine_train_val: bool = False, image_size: int | Tuple[int, int] = (224, 224))

Bases: Dataset[tuple[Tensor, Tensor, str]], DefaultTransformsMixin

Cine cardiac magnetic resonance imagery dataset.

class dataset.TwoPlusOneDataset(img_dir: str, mask_dir: str, idxs_dir: str, frames: int, select_frame_method: Literal['consecutive', 'specific'], transform_img: Compose, transform_mask: Compose, transform_together: Compose | None = None, batch_size: int = 2, mode: Literal['train', 'val', 'test'] = 'train', classification_mode: ClassificationMode = ClassificationMode.MULTICLASS_MODE, loading_mode: LoadingMode = LoadingMode.RGB, combine_train_val: bool = False, image_size: int | Tuple[int, int] = (224, 224))

Bases: CineDataset, DefaultTransformsMixin

Cine CMR dataset.

class dataset.ResidualTwoPlusOneDataset(img_dir: str, mask_dir: str, idxs_dir: str, frames: int, select_frame_method: Literal['consecutive', 'specific'], transform_img: Compose, transform_mask: Compose, transform_resize: Compose | Resize | None = None, transform_together: Compose | None = None, transform_residual: Compose | None = None, batch_size: int = 2, mode: Literal['train', 'val', 'test'] = 'train', classification_mode: ClassificationMode = ClassificationMode.MULTICLASS_MODE, loading_mode: LoadingMode = LoadingMode.RGB, combine_train_val: bool = False, residual_mode: ResidualMode = ResidualMode.SUBTRACT_NEXT_FRAME, image_size: int | Tuple[int, int] = (224, 224))

Bases: Dataset[tuple[Tensor, Tensor, Tensor, str]], DefaultTransformsMixin

Two stream dataset with cine images and residual frames.

classmethod get_default_transforms(loading_mode: LoadingMode, residual_mode: ResidualMode, augment: bool = False, image_size: int | Tuple[int, int] = (224, 224), histogram_equalize: bool = False) → tuple[Compose, Compose, Compose, Compose | None]

Get default transformations for the dataset.

The default implementation resizes the images to (224, 224), casts them to float32, normalises them, and sets them to greyscale if the loading mode is not RGB.

Parameters:

  • loading_mode – The loading mode for the images.

  • augment – Whether to augment the images and masks together.

  • image_size – Output image resolution.

  • histogram_equalize – Whether to normalise the image using histogram

  • equalisation.

Returns:

The image, mask, combined, and final resize transformations

class dataset.ThreeStreamDataset(lge_dir: str, cine_dir: str, mask_dir: str, txt_dir: str, idxs_dir: str, frames: int, select_frame_method: Literal['consecutive', 'specific'], transform_lge: Compose, transform_cine: Compose, transform_mask: Compose, transform_resize: Compose | None = None, transform_residual: Compose | None = None, transform_together: Compose | None = None, batch_size: int = 8, mode: Literal['train', 'val', 'test'] = 'train', classification_mode: ClassificationMode = ClassificationMode.BINARY_CLASS_3_MODE, loading_mode: LoadingMode = LoadingMode.GREYSCALE, combine_train_val: bool = False, residual_mode: ResidualMode = ResidualMode.SUBTRACT_NEXT_FRAME, image_size: int | Tuple[int, int] = (224, 224), tokenizer: str = 'microsoft/BiomedVLP-CXR-BERT-general', _use_dummy_reports: bool = False)

Bases: Dataset[tuple[Tensor, Tensor, Tensor, Tensor, Tensor, str]], DefaultTransformsMixin

LGE + Cine residuals + Text dataset.

classmethod get_default_transforms(loading_mode: LoadingMode, residual_mode: ResidualMode, augment: bool = False, image_size: int | Tuple[int, int] = (224, 224)) → tuple[Compose, Compose, Compose, Compose, Compose | None]

Get default transformations for the dataset.

The default implementation resizes the images to (224, 224), casts them to float32, normalises them, and sets them to greyscale if the loading mode is not RGB.

Parameters:

  • loading_mode – The loading mode for the images.

  • augment – Whether to augment the images and masks together.

  • image_size – Output image resolution.

  • histogram_equalize – Whether to normalise the image using histogram

  • equalisation.

Returns:

The image, mask, combined, and final resize transformations

class dataset.FourStreamDataset(lge_dir: str, cine_dir: str, mask_dir: str, txt_dir: str, idxs_dir: str, frames: int, select_frame_method: Literal['consecutive', 'specific'], transform_lge: Compose, transform_cine: Compose, transform_mask: Compose, transform_resize: Compose | None = None, transform_residual: Compose | None = None, transform_together: Compose | None = None, batch_size: int = 8, mode: Literal['train', 'val', 'test'] = 'train', classification_mode: ClassificationMode = ClassificationMode.BINARY_CLASS_3_MODE, loading_mode: LoadingMode = LoadingMode.GREYSCALE, combine_train_val: bool = False, residual_mode: ResidualMode = ResidualMode.SUBTRACT_NEXT_FRAME, image_size: int | Tuple[int, int] = (224, 224), tokenizer: str = 'microsoft/BiomedVLP-CXR-BERT-general', _use_dummy_reports: bool = False)

Bases: Dataset[tuple[Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, str]], DefaultTransformsMixin

LGE + Cine Sequence + Cine residuals + Textual reports dataset.

classmethod get_default_transforms(loading_mode: LoadingMode, residual_mode: ResidualMode, augment: bool = False, image_size: int | Tuple[int, int] = (224, 224)) → tuple[Compose, Compose, Compose, Compose, Compose | None]

Get default transformations for the dataset.

The default implementation resizes the images to (224, 224), casts them to float32, normalises them, and sets them to greyscale if the loading mode is not RGB.

Parameters:

  • loading_mode – The loading mode for the images.

  • augment – Whether to augment the images and masks together.

  • image_size – Output image resolution.

  • histogram_equalize – Whether to normalise the image using histogram

  • equalisation.

Returns:

The image, mask, combined, and final resize transformations

dataset.get_trainval_data_subsets(train_dataset: DefaultDatasetProtocol, valid_dataset: DefaultDatasetProtocol | None = None) → tuple[Subset, Subset]

Get the subsets of the data as train/val splits from a superset.

Parameters:

  • train_dataset – The original train dataset.

  • valid_dataset – The original valid dataset.

Returns:

Training and validation subsets.

Raises:

AssertionError – Train and valid datasets are not the same.