Créer un jeu de données NIfTI

Cette page montre comment créer et partager un jeu de données d'images médicales au format NIfTI (.nii / .nii.gz) à l'aide de la bibliothèque datasets.

Vous pouvez partager un jeu de données avec votre équipe ou avec n’importe qui dans la communauté en créant un dépôt de jeu de données sur le Hugging Face Hub :

from datasets import load_dataset

dataset = load_dataset("<username>/my_nifti_dataset")

Il existe deux façons courantes de créer un jeu de données NIfTI :

• Créer un jeu de données à partir de fichiers NIfTI locaux en Python et le téléverser avec Dataset.push_to_hub.
• Utilisez une convention basée sur des dossiers (un fichier par exemple) et un petit utilitaire pour le convertir en Dataset.

Vous pouvez contrôler l'accès à votre jeu de données en exigeant que les utilisateurs partagent d'abord leurs coordonnées. Consultez le guide Gated datasets pour plus d'informations.

Fichiers locaux

Si vous disposez déjà d'une liste de chemins d'accès vers des fichiers NIfTI, le flux de travail le plus simple consiste à créer un Dataset à partir de cette liste et à convertir la colonne en fonctionnalité Nifti.

from datasets import Dataset
from datasets import Nifti

# simple example: create a dataset from file paths
files = ["/path/to/scan_001.nii.gz", "/path/to/scan_002.nii.gz"]
ds = Dataset.from_dict({"nifti": files}).cast_column("nifti", Nifti())

# access a decoded nibabel image (if decode=True)
# ds[0]["nifti"] will be a nibabel.Nifti1Image object when decode=True
# or a dict {'bytes': None, 'path': '...'} when decode=False

La fonctionnalité Nifti prend en charge un paramètre decode. Lorsque decode=True (par défaut), elle charge le fichier NIfTI dans un objet nibabel.nifti1.Nifti1Image. Vous pouvez accéder aux données de l'image sous forme de tableau numpy avec img.get_fdata(). Lorsque decode=False, elle renvoie un dictionnaire contenant le chemin du fichier et les octets.

from datasets import Dataset, Nifti

ds = Dataset.from_dict({"nifti": ["/path/to/scan.nii.gz"]}).cast_column("nifti", Nifti(decode=True))
img = ds[0]["nifti"]  # instance of: nibabel.nifti1.Nifti1Image
arr = img.get_fdata()

Après avoir préparé le jeu de données, vous pouvez le pousser sur le Hub :

ds.push_to_hub("<username>/my_nifti_dataset")

Cela créera un dépôt de jeu de données contenant votre jeu de données NIfTI avec un dossier data/ de fragments parquet.

Conventions de dossiers et métadonnées

Si vous organisez votre jeu de données dans des dossiers, vous pouvez créer automatiquement des splits (train/test/validation) en suivant une structure comme :

dataset/train/scan_0001.nii
dataset/train/scan_0002.nii
dataset/validation/scan_1001.nii
dataset/test/scan_2001.nii

Si vous disposez d’étiquettes ou d’autres métadonnées, fournissez un metadata.csv, metadata.jsonl ou metadata.parquet dans le dossier afin que les fichiers puissent être liés aux lignes de métadonnées. Les métadonnées doivent contenir un champ file_name (ou *_file_name) avec le chemin relatif vers le fichier NIfTI situé à côté du fichier de métadonnées.

Exemple de metadata.csv :

file_name,patient_id,age,diagnosis
scan_0001.nii.gz,P001,45,healthy
scan_0002.nii.gz,P002,59,disease_x

La fonctionnalité Nifti fonctionne également avec des jeux de données compressés — chaque archive zip peut contenir des fichiers NIfTI et un fichier de métadonnées. C’est pratique lors de l’envoi de grands jeux de données sous forme d’archives. Cela signifie que la structure de votre jeu de données pourrait ressembler à ceci (fichiers compressés et non compressés mélangés) :

dataset/train/scan_0001.nii.gz
dataset/train/scan_0002.nii
dataset/validation/scan_1001.nii.gz
dataset/test/scan_2001.nii

Conversion en tenseurs PyTorch

Utilisez la fonction set_transform() pour appliquer la transformation à la volée aux lots du jeu de données :

import torch 
import nibabel
import numpy as np

def transform_to_pytorch(example):
    example["nifti_torch"] = [torch.tensor(ex.get_fdata()) for ex in example["nifti"]]
    return example

ds.set_transform(transform_to_pytorch)

L’accès aux éléments (par exemple ds[0]) renvoie désormais des tenseurs torch dans la clé "nifti_torch".

Utilisation de NifTI1Image

NifTI est un format de stockage des résultats d'examens cérébraux en 3 (voire 4) dimensions. Cela inclut 3 dimensions spatiales (x, y, z) et, le cas échéant, une dimension temporelle (t). De plus, les positions fournies ici ne sont que relatives au scanner ; les dimensions (4, 5, 6) sont donc utilisées pour les convertir en coordonnées du monde réel.

Vous pouvez par exemple visualiser des fichiers nifti en utilisant matplotlib de la manière suivante :

import matplotlib.pyplot as plt
from datasets import load_dataset

def show_slices(slices):
   """ Function to display row of image slices """
   fig, axes = plt.subplots(1, len(slices))
   for i, slice in enumerate(slices):
       axes[i].imshow(slice.T, cmap="gray", origin="lower")

nifti_ds = load_dataset("<username>/my_nifti_dataset")
for epi_img in nifti_ds:
    nifti_img = epi_img["nifti"].get_fdata()
    show_slices([nifti_img[:, :, 16], nifti_img[26, :, :], nifti_img[:, 30, :]])
    plt.show()

Pour aller plus loin, nous vous renvoyons vers la documentation de nibabel et en particulier ce tutoriel nibabel