torch_em.data.datasets.medical.instance22

  1"""The INSTANCE dataset contains annotations for intracranial hemorrhage segmentation in
  2non-contrast head CT (NCCT) scans.
  3
  4It comprises the training set of the INSTANCE2022 challenge (https://instance.grand-challenge.org):
  5100 NCCT volumes with a voxel-wise annotation of the intracranial hemorrhage, refined by 10 radiologists.
  6The 30 validation volumes are distributed without annotations and are therefore not included here.
  7
  8NOTE: The label legend is as follows:
  9- background: 0, intracranial hemorrhage: 1
 10
 11NOTE: The organizers announced on 2026/09/11 that they have made the dataset open to the public, and state
 12that the download link can be found in the dataset part of the challenge page. That page,
 13https://instance.grand-challenge.org/Dataset/, still returns HTTP 403 to users who are not signed in to
 14grand-challenge.org, so the data cannot be downloaded automatically. There is no mirror of this data
 15elsewhere. Please follow these steps:
 16- Register at https://instance.grand-challenge.org/ and join the challenge. If the dataset page is still
 17  not accessible to you, write to INSTANCE2022@outlook.com and, if you are participating in the challenge,
 18  send the signed data agreement
 19  (https://github.com/PerceptionComputingLab/INSTANCE2022/blob/main/Agreements/instance2022_agreements.pdf).
 20- Follow the download link on https://instance.grand-challenge.org/Dataset/ and extract the archive into
 21  '<path>', such that '<path>/train_2/data/001.nii.gz' and '<path>/train_2/label/001.nii.gz' exist
 22  (a folder named 'train' instead of 'train_2' is also accepted).
 23  The case ids are the zero-padded numbers 001 - 100.
 24
 25The dataset is located at https://instance.grand-challenge.org/Dataset/. The annotations are released
 26under a CC BY-NC-ND license and https://instance.grand-challenge.org/Participation/ states that any other
 27use of the data, including redistribution, is not allowed, so please make sure that you are allowed to use
 28the data for your purpose.
 29
 30This dataset is from the publication https://doi.org/10.48550/arXiv.2301.03281.
 31Please cite it if you use this dataset in your research.
 32"""
 33
 34import os
 35from glob import glob
 36from natsort import natsorted
 37from typing import Union, Tuple, List
 38
 39from torch.utils.data import Dataset, DataLoader
 40
 41import torch_em
 42
 43from .. import util
 44
 45
 46LABEL_IDS = {"background": 0, "hemorrhage": 1}
 47
 48
 49def get_instance22_data(path: Union[os.PathLike, str], download: bool = False) -> str:
 50    """Obtain the INSTANCE dataset.
 51
 52    Args:
 53        path: Filepath to a folder where the data is downloaded for further processing.
 54        download: Whether to download the data if it is not present.
 55
 56    Returns:
 57        Filepath where the data is stored.
 58    """
 59    # The archive is either extracted directly into 'path' or into a folder named after the archive.
 60    # NOTE: The official archive is called 'train_2.zip' and extracts to a folder 'train_2', while the dataset
 61    # description calls it 'train', so both spellings are accepted. The folder is identified by its subfolders.
 62    candidates = natsorted(glob(os.path.join(path, "**", "train*"), recursive=True))
 63    for candidate in candidates:
 64        if os.path.isdir(os.path.join(candidate, "data")) and os.path.isdir(os.path.join(candidate, "label")):
 65            return candidate
 66
 67    msg = f"It's expected to place the extracted INSTANCE2022 training data at '{path}'. "
 68    msg += "'torch_em' cannot download this dataset, as it is only accessible to users who are signed in to "
 69    msg += "grand-challenge.org. See 'torch_em.data.datasets.medical.instance22' for the manual download "
 70    msg += "instructions."
 71    if download:
 72        raise NotImplementedError(msg)
 73    else:
 74        raise FileNotFoundError(msg)
 75
 76
 77def get_instance22_paths(path: Union[os.PathLike, str], download: bool = False) -> Tuple[List[str], List[str]]:
 78    """Get paths to the INSTANCE data.
 79
 80    Args:
 81        path: Filepath to a folder where the data is downloaded for further processing.
 82        download: Whether to download the data if it is not present.
 83
 84    Returns:
 85        List of filepaths for the image data.
 86        List of filepaths for the label data.
 87    """
 88    data_dir = get_instance22_data(path, download)
 89
 90    # NOTE: The label paths are built from the data directory instead of replacing 'data' in the image paths,
 91    # because the path to the dataset itself may contain a folder called 'data'.
 92    raw_paths = natsorted(glob(os.path.join(data_dir, "data", "*.nii.gz")))
 93    label_paths = [os.path.join(data_dir, "label", os.path.basename(p)) for p in raw_paths]
 94    assert len(raw_paths) > 0 and all(os.path.exists(p) for p in label_paths)
 95
 96    return raw_paths, label_paths
 97
 98
 99def get_instance22_dataset(
100    path: Union[os.PathLike, str],
101    patch_shape: Tuple[int, ...],
102    resize_inputs: bool = False,
103    download: bool = False,
104    **kwargs
105) -> Dataset:
106    """Get the INSTANCE dataset for intracranial hemorrhage segmentation.
107
108    Args:
109        path: Filepath to a folder where the data is downloaded for further processing.
110        patch_shape: The patch shape to use for training.
111        resize_inputs: Whether to resize inputs to the desired patch shape.
112        download: Whether to download the data if it is not present.
113        kwargs: Additional keyword arguments for `torch_em.default_segmentation_dataset`.
114
115    Returns:
116        The segmentation dataset.
117    """
118    raw_paths, label_paths = get_instance22_paths(path, download)
119
120    if resize_inputs:
121        resize_kwargs = {"patch_shape": patch_shape, "is_rgb": False}
122        kwargs, patch_shape = util.update_kwargs_for_resize_trafo(
123            kwargs=kwargs, patch_shape=patch_shape, resize_inputs=resize_inputs, resize_kwargs=resize_kwargs
124        )
125
126    return torch_em.default_segmentation_dataset(
127        raw_paths=raw_paths,
128        raw_key="data",
129        label_paths=label_paths,
130        label_key="data",
131        patch_shape=patch_shape,
132        is_seg_dataset=True,
133        **kwargs
134    )
135
136
137def get_instance22_loader(
138    path: Union[os.PathLike, str],
139    batch_size: int,
140    patch_shape: Tuple[int, ...],
141    resize_inputs: bool = False,
142    download: bool = False,
143    **kwargs
144) -> DataLoader:
145    """Get the INSTANCE dataloader for intracranial hemorrhage segmentation.
146
147    Args:
148        path: Filepath to a folder where the data is downloaded for further processing.
149        batch_size: The batch size for training.
150        patch_shape: The patch shape to use for training.
151        resize_inputs: Whether to resize inputs to the desired patch shape.
152        download: Whether to download the data if it is not present.
153        kwargs: Additional keyword arguments for `torch_em.default_segmentation_dataset` or for the PyTorch DataLoader.
154
155    Returns:
156        The DataLoader.
157    """
158    ds_kwargs, loader_kwargs = util.split_kwargs(torch_em.default_segmentation_dataset, **kwargs)
159    dataset = get_instance22_dataset(path, patch_shape, resize_inputs, download, **ds_kwargs)
160    return torch_em.get_data_loader(dataset, batch_size, **loader_kwargs)