Pandas

Pandas est un kit d’analyse de données Python très utilisé. Comme il utilise fsspec pour lire et écrire des données distantes, vous pouvez utiliser les chemins Hugging Face (hf://) pour lire et écrire des données sur le Hub.

Charger un DataFrame

Vous pouvez charger des données depuis des fichiers locaux ou depuis un stockage distant comme Hugging Face Datasets. Pandas prend en charge de nombreux formats, notamment CSV, JSON et Parquet :

>>> import pandas as pd
>>> df = pd.read_csv("path/to/data.csv")

Pour charger un fichier depuis Hugging Face, le chemin doit commencer par hf://. Par exemple, le chemin vers le dépôt de données stanfordnlp/imdb est hf://datasets/stanfordnlp/imdb. Le jeu de données sur Hugging Face contient plusieurs fichiers Parquet. Le format de fichier Parquet est conçu pour rendre la lecture et l'écriture de data frames efficaces, et pour faciliter le partage de données entre les langages d'analyse de données. Voici comment charger le fichier plain_text/train-00000-of-00001.parquet :

>>> import pandas as pd
>>> df = pd.read_parquet("hf://datasets/stanfordnlp/imdb/plain_text/train-00000-of-00001.parquet")
>>> df
                                                    text  label
0      I rented I AM CURIOUS-YELLOW from my video sto...      0
1      "I Am Curious: Yellow" is a risible and preten...      0
2      If only to avoid making this type of film in t...      0
3      This film was probably inspired by Godard's Ma...      0
4      Oh, brother...after hearing about this ridicul...      0
...                                                  ...    ...
24995  A hit at the time but now better categorised a...      1
24996  I love this movie like no other. Another time ...      1
24997  This film and it's sequel Barry Mckenzie holds...      1
24998  'The Adventures Of Barry McKenzie' started lif...      1
24999  The story centers around Barry McKenzie who mu...      1

Pour plus d’informations sur les chemins Hugging Face et leur implémentation, veuillez consulter la documentation de la bibliothèque client sur HfFileSystem.

Les mêmes chemins hf:// fonctionnent également avec les Storage Buckets :

Copié

>>> df = pd.read_parquet("hf://buckets/username/my-bucket/data.parquet")
>>> df.to_parquet("hf://buckets/username/my-bucket/output.parquet")

Enregistrer un DataFrame

Vous pouvez enregistrer un DataFrame pandas à l'aide de to_csv/to_json/to_parquet dans un fichier local ou directement sur Hugging Face.

Pour enregistrer le DataFrame sur Hugging Face, vous devez d'abord vous connecter à votre compte Hugging Face, par exemple en utilisant :

hf auth login

Ensuite, vous pouvez Créer un dépôt de jeu de données, par exemple en utilisant :

from huggingface_hub import HfApi

HfApi().create_repo(repo_id="username/my_dataset", repo_type="dataset")

Enfin, vous pouvez utiliser des chemins Hugging Face dans Pandas :

import pandas as pd

df.to_parquet("hf://datasets/username/my_dataset/imdb.parquet")

# or write in separate files if the dataset has train/validation/test splits
df_train.to_parquet("hf://datasets/username/my_dataset/train.parquet")
df_valid.to_parquet("hf://datasets/username/my_dataset/validation.parquet")
df_test .to_parquet("hf://datasets/username/my_dataset/test.parquet")

Notez que les fichiers Parquet sur Hugging Face sont optimisés pour améliorer l’efficacité du stockage, accélérer les téléchargements et les téléversements, et permettre un streaming et une édition efficaces des jeux de données :

• Parquet Content Defined Chunking optimise Parquet pour Xet, le backend de stockage de Hugging Face. Il accélère les téléversements et les téléchargements grâce à la déduplication par chunks et permet une édition efficace des fichiers
• L'index de page accélère les filtres lors du streaming et permet un accès aléatoire efficace, par exemple dans le Dataset Viewer

Pandas nécessite un argument supplémentaire pour écrire des fichiers Parquet optimisés :

import pandas as pd

df.to_parquet(
    "hf://datasets/username/my_dataset/imdb.parquet",
    # Optimize for Xet
    use_content_defined_chunking=True,
    write_page_index=True,
)

• use_content_defined_chunking=True pour activer le Parquet Content Defined Chunking, pour la déduplication et l'édition (nécessite pyarrow>=21.0)
• write_page_index=True pour inclure un index de pages dans les métadonnées Parquet, pour le streaming et l'accès aléatoire

Le découpage par contenu défini (CDC) permet à l’écriture Parquet de découper les pages de données de manière à ce que les données en double soient découpées et compressées de façon identique. Sans CDC, les pages sont découpées arbitrairement et les données en double sont donc impossibles à détecter en raison de la compression. Grâce au CDC, les téléversements et téléchargements Parquet depuis Hugging Face sont plus rapides, car les données en double ne sont téléversées ou téléchargées qu’une seule fois.

Retrouvez plus d'informations sur Xet ici.

Exploiter la déduplication Xet pour Parquet

Les fichiers Parquet optimisés sont écrits avec le Content Defined Chunking, ce qui permet la déduplication. Cela accélère les téléversements, car les blocs de données qui existent déjà sur Hugging Face n’ont pas besoin d’être téléversés à nouveau, ce qui économise beaucoup d’I/O.

Par exemple, ce code téléverse le contenu de df, puis pour edited_df, le téléversement est plus rapide car il ne téléverse que les blocs modifiés :

import pandas as pd

df.to_parquet(
    "hf://datasets/username/my_dataset/imdb.parquet",
    # Optimize for Xet
    use_content_defined_chunking=True,
    write_page_index=True,
)

edited_df = ...  # e.g. with added/modified/removed rows or columns

edited_df.to_parquet(
    "hf://datasets/username/my_dataset/imdb.parquet",
    # Optimize for Xet
    use_content_defined_chunking=True,
    write_page_index=True,
)

Les blocs font environ 64 Ko et Parquet enregistre les données colonne par colonne, donc en pratique, voici ce qui se produit lors de l'édition d'un fichier Parquet optimisé :

• ajouter une nouvelle colonne -> seuls les fragments de la nouvelle colonne sont téléversés
• ajouter/modifier/supprimer une ligne -> un chunk par colonne est téléversé

En plus de cela, les blocs du pied de page Parquet contenant les métadonnées sont également téléversés.

Utiliser des images

Vous pouvez charger un dossier avec un fichier de métadonnées contenant un champ pour les noms ou les chemins des images, structuré de la manière suivante :

Example 1:            Example 2:
folder/               folder/
├── metadata.csv      ├── metadata.csv
├── img000.png        └── images
├── img001.png            ├── img000.png
...                       ...
└── imgNNN.png            └── imgNNN.png

Vous pouvez itérer sur les chemins des images de cette manière :

import pandas as pd

folder_path = "path/to/folder/"
df = pd.read_csv(folder_path + "metadata.csv")
for image_path in (folder_path + df["file_name"]):
    ...

Puisque le jeu de données est dans une structure prise en charge (un fichier metadata.csv ou .jsonl avec un champ file_name), vous pouvez enregistrer ce jeu de données sur Hugging Face et le Dataset Viewer affiche à la fois les métadonnées et les images sur Hugging Face.

from huggingface_hub import HfApi
api = HfApi()

api.upload_folder(
    folder_path=folder_path,
    repo_id="username/my_image_dataset",
    repo_type="dataset",
)

Méthodes d’images et Parquet

En utilisant pandas-image-methods, vous activez les méthodes PIL.Image sur une colonne d’images. Cela permet également d’enregistrer le jeu de données sous forme d’un seul fichier Parquet contenant à la fois les images et les métadonnées :

import pandas as pd
from pandas_image_methods import PILMethods

pd.api.extensions.register_series_accessor("pil")(PILMethods)

df["image"] = (folder_path + df["file_name"]).pil.open()
df.to_parquet("data.parquet")

Toutes les méthodes de PIL.Image sont disponibles, par exemple

df["image"] = df["image"].pil.rotate(90)

Utiliser des Audios

Vous pouvez charger un dossier avec un fichier de métadonnées contenant un champ pour les noms ou les chemins des audios, structuré de la manière suivante :

Example 1:            Example 2:
folder/               folder/
├── metadata.csv      ├── metadata.csv
├── rec000.wav        └── audios
├── rec001.wav            ├── rec000.wav
...                       ...
└── recNNN.wav            └── recNNN.wav

Vous pouvez itérer sur les chemins des audios de cette manière :

import pandas as pd

folder_path = "path/to/folder/"
df = pd.read_csv(folder_path + "metadata.csv")
for audio_path in (folder_path + df["file_name"]):
    ...

Puisque le jeu de données est dans une structure prise en charge (un fichier metadata.csv ou .jsonl avec un champ file_name), vous pouvez l’enregistrer sur Hugging Face, et le visualiseur de jeux de données du Hub affiche à la fois les métadonnées et l’audio.

from huggingface_hub import HfApi
api = HfApi()

api.upload_folder(
    folder_path=folder_path,
    repo_id="username/my_audio_dataset",
    repo_type="dataset",
)

Méthodes audio et Parquet

En utilisant pandas-audio-methods, vous activez les méthodes soundfile sur une colonne audio. Cela permet également d’enregistrer le jeu de données sous forme d’un seul fichier Parquet contenant à la fois les audios et les métadonnées :

import pandas as pd
from pandas_audio_methods import SFMethods

pd.api.extensions.register_series_accessor("sf")(SFMethods)

df["audio"] = (folder_path + df["file_name"]).sf.open()
df.to_parquet("data.parquet")

Cela facilite son utilisation avec librosa, par exemple pour le rééchantillonnage :

df["audio"] = [librosa.load(audio, sr=16_000) for audio in df["audio"]]
df["audio"] = df["audio"].sf.write()

Utiliser Transformers

Vous pouvez utiliser les pipelines de transformers sur des DataFrames pandas pour classifier, générer du texte, des images, etc. Cette section présente quelques exemples avec tqdm pour les barres de progression.

Les pipelines n’acceptent pas un objet tqdm en entrée, mais vous pouvez utiliser à la place un générateur Python, sous la forme x for x in tqdm(...)

Classification de texte

from transformers import pipeline
from tqdm import tqdm

pipe = pipeline("text-classification", model="clapAI/modernBERT-base-multilingual-sentiment")

# Compute labels
df["label"] = [y["label"] for y in pipe(x for x in tqdm(df["text"]))]
# Compute labels and scores
df[["label", "score"]] = [(y["label"], y["score"]) for y in pipe(x for x in tqdm(df["text"]))]

Génération de texte

from transformers import pipeline
from tqdm import tqdm

pipe = pipeline("text-generation", model="Qwen/Qwen2.5-1.5B-Instruct")

# Generate chat response
prompt = "What is the main topic of this sentence ? REPLY IN LESS THAN 3 WORDS. Sentence: '{}'"
df["output"] = [y["generated_text"][1]["content"] for y in pipe([{"role": "user", "content": prompt.format(x)}] for x in tqdm(df["text"]))]