# Utiliser avec NumPy

Ce document est une introduction rapide à l'utilisation de `datasets` avec NumPy, avec un accent particulier sur la façon d'extraire des objets `numpy.ndarray` de nos jeux de données et de les utiliser pour entraîner des modèles basés sur NumPy, tels que les modèles `scikit-learn`.

## Format du jeu de données

Par défaut, les jeux de données renvoient des objets Python classiques : des entiers, des flottants, des chaînes de caractères, des listes, etc.

Pour obtenir des tableaux NumPy à la place, vous pouvez définir le format du jeu de données sur `numpy` :

```py
>>> from datasets import Dataset
>>> data = [[1, 2], [3, 4]]
>>> ds = Dataset.from_dict({"data": data})
>>> ds = ds.with_format("numpy")
>>> ds[0]
{'data': array([1, 2])}
>>> ds[:2]
{'data': array([
    [1, 2],
    [3, 4]])}
```

> [!TIP]
> Un objet [Dataset](/docs/datasets/main/fr/package_reference/main_classes#datasets.Dataset) est un conteneur pour un tableau Arrow, qui permet des lectures rapides depuis les tableaux du jeu de données vers des tableaux NumPy.

Notez que la procédure exacte s'applique également aux objets `DatasetDict`, de sorte que lorsque le format d'un `DatasetDict` est défini sur `numpy`, tous les `Dataset` qu'il contient seront formatés en `numpy` :

```py
>>> from datasets import DatasetDict
>>> data = {"train": {"data": [[1, 2], [3, 4]]}, "test": {"data": [[5, 6], [7, 8]]}}
>>> dds = DatasetDict.from_dict(data)
>>> dds = dds.with_format("numpy")
>>> dds["train"][:2]
{'data': array([
    [1, 2],
    [3, 4]])}
```

### Tableaux N-dimensionnels

Si votre jeu de données est constitué de tableaux N-dimensionnels, vous constaterez qu’ils sont considérés par défaut comme le même tableau si la forme est fixe :

```py
>>> from datasets import Dataset
>>> data = [[[1, 2],[3, 4]], [[5, 6],[7, 8]]]  # fixed shape
>>> ds = Dataset.from_dict({"data": data})
>>> ds = ds.with_format("numpy")
>>> ds[0]
{'data': array([[1, 2],
        [3, 4]])}
```

```py
>>> from datasets import Dataset
>>> data = [[[1, 2],[3]], [[4, 5, 6],[7, 8]]]  # varying shape
>>> ds = Dataset.from_dict({"data": data})
>>> ds = ds.with_format("numpy")
>>> ds[0]
{'data': array([array([1, 2]), array([3])], dtype=object)}
```

Cependant, cette logique nécessite souvent des comparaisons de formes et des copies de données lentes. Pour l’éviter, vous devez utiliser explicitement le type de fonctionnalité `Array` et spécifier la forme de vos tenseurs :

```py
>>> from datasets import Dataset, Features, Array2D
>>> data = [[[1, 2],[3, 4]],[[5, 6],[7, 8]]]
>>> features = Features({"data": Array2D(shape=(2, 2), dtype='int32')})
>>> ds = Dataset.from_dict({"data": data}, features=features)
>>> ds = ds.with_format("numpy")
>>> ds[0]
{'data': array([[1, 2],
        [3, 4]])}
>>> ds[:2]
{'data': array([[[1, 2],
         [3, 4]],
 
        [[5, 6],
         [7, 8]]])}
```

### Autres types de fonctionnalités

Les données [ClassLabel](/docs/datasets/main/fr/package_reference/main_classes#datasets.ClassLabel) sont correctement converties en tableaux :

```py
>>> from datasets import Dataset, Features, ClassLabel
>>> labels = [0, 0, 1]
>>> features = Features({"label": ClassLabel(names=["negative", "positive"])})
>>> ds = Dataset.from_dict({"label": labels}, features=features)
>>> ds = ds.with_format("numpy")
>>> ds[:3]
{'label': array([0, 0, 1])}
```

Les objets de type chaîne et binaire ne sont pas modifiés, car NumPy ne prend en charge que les nombres.

Les types de fonctionnalités [Image](/docs/datasets/main/fr/package_reference/main_classes#datasets.Image) et [Audio](/docs/datasets/main/fr/package_reference/main_classes#datasets.Audio) sont également pris en charge.

> [!TIP]
> Pour utiliser le type de fonctionnalité [Image](/docs/datasets/main/fr/package_reference/main_classes#datasets.Image), vous devez installer l'extra `vision` via `pip install datasets[vision]`.

```py
>>> from datasets import Dataset, Features, Image
>>> images = ["path/to/image.png"] * 10
>>> features = Features({"image": Image()})
>>> ds = Dataset.from_dict({"image": images}, features=features)
>>> ds = ds.with_format("numpy")
>>> ds[0]["image"].shape
(512, 512, 3)
>>> ds[0]
{'image': array([[[ 255, 255, 255],
              [ 255, 255, 255],
              ...,
              [ 255, 255, 255],
              [ 255, 255, 255]]], dtype=uint8)}
>>> ds[:2]["image"].shape
(2, 512, 512, 3)
>>> ds[:2]
{'image': array([[[[ 255, 255, 255],
              [ 255, 255, 255],
              ...,
              [ 255, 255, 255],
              [ 255, 255, 255]]]], dtype=uint8)}
```

> [!TIP]
> Pour utiliser le type de fonctionnalité [Audio](/docs/datasets/main/fr/package_reference/main_classes#datasets.Audio), vous devez installer l'extra `audio` via `pip install datasets[audio]`.

```py
>>> from datasets import Dataset, Features, Audio
>>> audio = ["path/to/audio.wav"] * 10
>>> features = Features({"audio": Audio()})
>>> ds = Dataset.from_dict({"audio": audio}, features=features)
>>> ds = ds.with_format("numpy")
>>> ds[0]["audio"]["array"]
array([-0.059021  , -0.03894043, -0.00735474, ...,  0.0133667 ,
              0.01809692,  0.00268555], dtype=float32)
>>> ds[0]["audio"]["sampling_rate"]
array(44100, weak_type=True)
```

## Chargement des données

NumPy ne dispose d'aucune fonctionnalité intégrée de chargement de données. Vous devez donc soit matérialiser les tableaux NumPy comme `X, y` pour les utiliser dans `scikit-learn`, soit utiliser une bibliothèque telle que [PyTorch](https://pytorch.org/) pour charger vos données à l'aide d'un `DataLoader`.

### Utilisation de `with_format('numpy')`

La façon la plus simple d’extraire des tableaux NumPy d’un jeu de données est d’utiliser la méthode `with_format('numpy')`. Supposons que nous voulons entraîner un réseau de neurones sur le [jeu de données MNIST](http://yann.lecun.com/exdb/mnist/) disponible sur le HuggingFace Hub à l’adresse https://huggingface.co/datasets/mnist.

```py
>>> from datasets import load_dataset
>>> ds = load_dataset("ylecun/mnist")
>>> ds = ds.with_format("numpy")
>>> ds["train"][0]
{'image': array([[  0,   0,   0, ...],
                       [  0,   0,   0, ...],
                       ...,
                       [  0,   0,   0, ...],
                       [  0,   0,   0, ...]], dtype=uint8),
 'label': array(5)}
```

Une fois le format défini, nous pouvons alimenter le modèle basé sur NumPy avec le jeu de données par lots à l'aide de la méthode `Dataset.iter()` :

```py
>>> for epoch in range(epochs):
...     for batch in ds["train"].iter(batch_size=32):
...         x, y = batch["image"], batch["label"]
...         ...
```