# 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 :

```py
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`.

> [!TIP]
> 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](https://huggingface.co/docs/hub/datasets-gated) 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`.

```py
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.

```py
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 :

```py
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` :

```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. La structure de votre jeu de données peut donc 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()](/docs/datasets/v5.2.0/fr/package_reference/main_classes#datasets.Dataset.set_transform) pour appliquer la transformation à la volée aux lots du jeu de données :

```py
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 :
```python
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](https://nipy.org/nibabel/index.html) et en particulier [ce tutoriel nibabel](https://nipy.org/nibabel/coordinate_systems.html) ---

