Pandas

Pandas adalah toolkit analisis data Python yang banyak digunakan. Karena menggunakan fsspec untuk membaca dan menulis data jarak jauh, Anda dapat menggunakan jalur Hugging Face (hf://) untuk membaca dan menulis data di Hub.

Muat DataFrame

Anda dapat memuat data dari file lokal atau dari penyimpanan jarak jauh seperti Hugging Face Datasets. Pandas mendukung banyak format termasuk CSV, JSON, dan Parquet:

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

Untuk memuat file dari Hugging Face, path harus diawali dengan hf://. Sebagai contoh, path ke repositori dataset stanfordnlp/imdb adalah hf://datasets/stanfordnlp/imdb. Dataset di Hugging Face berisi beberapa file Parquet. Format file Parquet dirancang untuk membuat pembacaan dan penulisan data frame menjadi efisien, serta memudahkan berbagi data di antara bahasa analisis data. Berikut cara memuat file 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

Untuk informasi lebih lanjut tentang jalur Hugging Face dan cara implementasinya, silakan merujuk ke dokumentasi pustaka klien tentang HfFileSystem.

Path hf:// yang sama juga berfungsi dengan Storage Buckets:

Disalin

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

Simpan DataFrame

Anda dapat menyimpan pandas DataFrame menggunakan to_csv/to_json/to_parquet ke file lokal atau langsung ke Hugging Face.

Untuk menyimpan DataFrame di Hugging Face, Anda perlu Masuk dengan akun Hugging Face Anda terlebih dahulu, misalnya menggunakan:

hf auth login

Lalu Anda dapat Membuat repositori dataset, misalnya menggunakan:

from huggingface_hub import HfApi

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

Terakhir, Anda dapat menggunakan jalur Hugging Face di 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")

Perhatikan bahwa file Parquet di Hugging Face dioptimalkan untuk meningkatkan efisiensi penyimpanan, mempercepat unduhan dan unggahan, serta memungkinkan streaming dan pengeditan dataset yang efisien:

• Parquet Content Defined Chunking mengoptimalkan Parquet untuk Xet, backend penyimpanan Hugging Face. Hal ini mempercepat unggahan dan unduhan berkat deduplikasi berbasis chunk serta memungkinkan pengeditan file yang efisien
• Indeks halaman mempercepat filter saat streaming dan memungkinkan akses acak yang efisien, misalnya di Dataset Viewer

Pandas memerlukan argumen tambahan untuk menulis file Parquet yang dioptimalkan:

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 untuk mengaktifkan Parquet Content Defined Chunking, untuk deduplikasi dan pengeditan (memerlukan pyarrow>=21.0)
• write_page_index=True untuk menyertakan indeks halaman dalam metadata Parquet, untuk streaming dan akses acak

Chunking yang didefinisikan konten (CDC) membuat penulisan Parquet membagi halaman data sedemikian rupa sehingga data duplikat di-chunk dan dikompresi secara identik. Tanpa CDC, halaman di-chunk secara sewenang-wenang sehingga data duplikat tidak mungkin terdeteksi karena kompresi. Berkat CDC, unggahan dan unduhan Parquet dari Hugging Face menjadi lebih cepat, karena data duplikat hanya diunggah atau diunduh sekali.

Temukan informasi lebih lanjut tentang Xet di sini.

Manfaatkan deduplikasi Xet untuk Parquet

File Parquet yang dioptimalkan ditulis dengan Content Defined Chunking, yang memungkinkan deduplikasi. Hal ini mempercepat unggahan karena potongan data yang sudah ada di Hugging Face tidak perlu diunggah ulang, dan ini menghemat banyak I/O.

Sebagai contoh, kode ini mengunggah konten dari df dan kemudian untuk edited_df pengunggahan lebih cepat karena hanya mengunggah chunk yang berubah:

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

Chunk berukuran ~64kB dan Parquet menyimpan data per kolom, sehingga dalam praktiknya inilah yang terjadi saat mengedit file Optimized Parquet:

• menambahkan kolom baru -> hanya chunk dari kolom baru yang diunggah
• menambahkan/mengedit/menghapus baris -> satu chunk per kolom diunggah

Selain itu, potongan-potongan footer Parquet yang berisi metadata juga diunggah.

Gunakan Gambar

Anda dapat memuat folder dengan file metadata yang berisi field untuk nama atau path ke gambar, yang terstruktur seperti ini:

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

Anda dapat mengiterasi jalur gambar seperti ini:

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"]):
    ...

Karena dataset berada dalam struktur yang didukung (berupa file metadata.csv atau .jsonl dengan field file_name), Anda dapat menyimpan dataset ini ke Hugging Face dan Dataset Viewer akan menampilkan metadata serta gambar di 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",
)

Metode gambar dan Parquet

Dengan pandas-image-methods, Anda mengaktifkan metode PIL.Image pada kolom gambar. Ini juga memungkinkan penyimpanan dataset sebagai satu file Parquet tunggal yang berisi gambar dan metadata:

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

Semua metode PIL.Image tersedia, misalnya

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

Gunakan Audios

Anda dapat memuat folder dengan file metadata yang berisi field untuk nama atau path ke audio, yang terstruktur seperti ini:

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

Anda dapat mengiterasi jalur audio seperti ini:

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"]):
    ...

Karena dataset berada dalam struktur yang didukung (berupa file metadata.csv atau .jsonl dengan field file_name), Anda dapat menyimpannya ke Hugging Face, dan Hub Dataset Viewer akan menampilkan metadata sekaligus audio.

from huggingface_hub import HfApi
api = HfApi()

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

Metode audio dan Parquet

Dengan pandas-audio-methods, Anda mengaktifkan metode soundfile pada kolom audio. Hal ini juga memungkinkan penyimpanan dataset sebagai satu file Parquet tunggal yang berisi audio dan metadata:

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

Hal ini memudahkan penggunaannya dengan librosa, misalnya untuk resampling:

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

Gunakan Transformers

Anda dapat menggunakan pipeline transformers pada DataFrame pandas untuk mengklasifikasikan, menghasilkan teks, gambar, dan sebagainya. Bagian ini menunjukkan beberapa contoh dengan tqdm untuk bilah kemajuan.

Pipelines tidak menerima objek tqdm sebagai input, tetapi Anda dapat menggunakan generator python sebagai gantinya, dalam bentuk x for x in tqdm(...)

Klasifikasi Teks

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"]))]

Generasi Teks

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"]))]