创建 NIfTI 数据集

此页面展示了如何使用 datasets 库创建并共享 NIfTI 格式（.nii / .nii.gz）的医学图像数据集。

您可以在 Hugging Face Hub 上创建数据集仓库，与您的团队或社区中的任何人共享数据集：

from datasets import load_dataset

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

创建 NIfTI 数据集有两种常见方式：

在 Python 中从本地 NIfTI 文件创建数据集，并使用 Dataset.push_to_hub 将其上传。
使用基于文件夹的约定（每个示例一个文件），并使用一个小型辅助函数将其转换为 Dataset。

您可以通过要求用户先共享其联系信息来控制对数据集的访问权限。有关更多信息，请参阅 Gated datasets 指南。

本地文件

如果您已经有一个 NIfTI 文件路径列表，最简单的工作流是从该列表创建一个 Dataset，并将该列转换为 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

Nifti 功能支持 decode 参数。当 decode=True（默认值）时，它会将 NIfTI 文件加载为 nibabel.nifti1.Nifti1Image 对象。您可以通过 img.get_fdata() 以 numpy 数组的形式访问图像数据。当 decode=False 时，它会返回一个包含文件路径和字节的字典。

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()

准备数据集后，您可以将其推送到 Hub：

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

这将创建一个数据集仓库，其中包含您的 NIfTI 数据集以及一个包含 parquet 分片的 data/ 文件夹。

文件夹约定和元数据

如果你按文件夹组织数据集，可以按照类似以下结构自动创建数据划分（训练/测试/验证）：

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

如果您有标签或其他元数据，请在文件夹中提供 metadata.csv、metadata.jsonl 或 metadata.parquet，以便将文件与元数据行关联。元数据必须包含一个 file_name（或 *_file_name）字段，其值为位于元数据文件旁边的 NIfTI 文件的相对路径。

metadata.csv 示例：

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

Nifti 功能也支持压缩数据集——每个压缩包可以包含 NIfTI 文件和元数据文件。这在以归档形式上传大型数据集时非常有用。这意味着您的数据集结构可能如下所示（混合了压缩文件和未压缩文件）：

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

转换为 PyTorch 张量

使用 set_transform() 函数对数据集的批次即时应用转换：

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)

现在访问元素（例如 ds[0]）将在 "nifti_torch" 键中返回 torch 张量。

NifTI1Image 的用法

NifTI 是一种用于存储 3 维（甚至 4 维）脑部扫描结果的格式。这包括 3 个空间维度（x,y,z）以及可选的时间维度（t）。此外，此处给出的位置仅相对于扫描仪，因此使用维度（4, 5, 6）将其转换到真实世界坐标中。

例如，您可以利用 matplotlib 可视化 nifti 文件，方法如下：

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()

如需进一步阅读，请参阅 nibabel 文档，尤其是此 nibabel 教程

Update on GitHub

Datasets

创建 NIfTI 数据集

本地文件

文件夹约定和元数据

转换为 PyTorch 张量

NifTI1Image 的用法

如需进一步阅读，请参阅 nibabel 文档，尤其是此 nibabel 教程