# Pandas

[Pandas](https://github.com/pandas-dev/pandas), yaygın olarak kullanılan bir Python veri analiz araç setidir. Uzaktaki verileri okumak ve yazmak için [fsspec](https://filesystem-spec.readthedocs.io) kullandığı için, Hub üzerindeki verileri okumak ve yazmak için Hugging Face yollarını ([`hf://`](/docs/huggingface_hub/guides/hf_file_system#integrations)) kullanabilirsiniz.

## Bir DataFrame yükleyin

Verileri yerel dosyalardan veya Hugging Face Datasets gibi uzak depolama alanlarından yükleyebilirsiniz. Pandas, CSV, JSON ve Parquet dahil olmak üzere birçok formatı destekler:

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

Hugging Face'ten bir dosya yüklemek için yolun `hf://` ile başlaması gerekir. Örneğin, [stanfordnlp/imdb](https://huggingface.co/datasets/stanfordnlp/imdb) veri seti deposunun yolu `hf://datasets/stanfordnlp/imdb`'dir. Hugging Face'teki veri seti birden çok Parquet dosyası içerir. Parquet dosya biçimi, veri çerçevelerini okumayı ve yazmayı verimli hale getirmek ve veri analiz dilleri arasında veri paylaşımını kolaylaştırmak üzere tasarlanmıştır. `plain_text/train-00000-of-00001.parquet` dosyasını yüklemenin yolu aşağıdaki gibidir:

```python
>>> 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
```

Hugging Face yolları ve bunların nasıl uygulandığına dair daha fazla bilgi için lütfen [HfFileSystem hakkında istemci kütüphanesinin belgelerine](/docs/huggingface_hub/guides/hf_file_system) başvurun.

> [!TIP]
> Aynı `hf://` yolları [Storage Buckets](./storage-buckets) ile de çalışır:
> ```python
> >>> df = pd.read_parquet("hf://buckets/username/my-bucket/data.parquet")
> >>> df.to_parquet("hf://buckets/username/my-bucket/output.parquet")
> ```

## Bir DataFrame kaydet

Bir pandas DataFrame'ini `to_csv/to_json/to_parquet` kullanarak yerel bir dosyaya veya doğrudan Hugging Face'e kaydedebilirsiniz.

Hugging Face üzerinde DataFrame'i kaydetmek için önce [Hugging Face hesabınızla oturum açmanız](/docs/huggingface_hub/quick-start#login) gerekir, örneğin şunu kullanarak:

```
hf auth login
```

Ardından [bir veri seti deposu oluşturabilirsiniz](/docs/huggingface_hub/quick-start#create-a-repository), örneğin şunu kullanarak:

```python
from huggingface_hub import HfApi

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

Son olarak, Pandas'ta [Hugging Face yollarını](/docs/huggingface_hub/guides/hf_file_system#integrations) kullanabilirsiniz:

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

Hugging Face'taki Parquet dosyalarının, depolama verimliliğini artırmak, indirme ve yükleme işlemlerini hızlandırmak ve verimli veri seti akışını ve düzenlemeyi mümkün kılmak üzere optimize edildiğini unutmayın:

* [Parquet İçerik Tanımlı Parçalama](https://huggingface.co/blog/parquet-cdc), Hugging Face'in depolama altyapısı olan [Xet](https://huggingface.co/docs/hub/en/xet/index) için Parquet'i optimize eder. Parça tabanlı kopya azaltma sayesinde yüklemeleri ve indirmeleri hızlandırır ve verimli dosya düzenlemeye olanak tanır
* Page index, akış sırasında filtreleri hızlandırır ve [Dataset Viewer](https://huggingface.co/docs/dataset-viewer) gibi durumlarda verimli rastgele erişim sağlar.

Pandas, optimize edilmiş Parquet dosyaları yazmak için ek bir argüman gerektirir:

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

* Parquet İçerik Tanımlı Parçalama'yı etkinleştirmek için `use_content_defined_chunking=True` kullanın; bu, [ayıklama](https://huggingface.co/blog/parquet-cdc) ve [düzenleme](./datasets-editing) için gereklidir (`pyarrow>=21.0` gerektirir)
* Parquet metaverisinde sayfa dizini içermek için `write_page_index=True`, [akış ve rastgele erişim](./datasets-streaming) için

> [!TIP]
> İçerik tanımlı parçalama (CDC), Parquet yazıcısının veri sayfalarını, kopya verilerin aynı şekilde parçalanıp sıkıştırılmasını sağlayacak biçimde parçalamasını sağlar. CDC olmadan sayfalar keyfi olarak parçalanır ve bu nedenle kopya veriler, sıkıştırma nedeniyle tespit edilemez. CDC sayesinde, kopya veriler yalnızca bir kez yüklendiği veya indirildiği için Hugging Face'e Parquet yükleme ve indirme işlemleri daha hızlıdır.

Xet hakkında daha fazla bilgiyi [burada](https://huggingface.co/join/xet) bulabilirsiniz.

## Parquet için Xet çakışma giderme özelliğinden yararlanın

Optimize edilmiş Parquet dosyaları, yinelenen verilerin kaldırılmasını (deduplication) mümkün kılan Content Defined Chunking ile yazılır. Bu, Hugging Face üzerinde zaten var olan veri parçacıklarının yeniden yüklenmesine gerek kalmadığı için yükleme işlemlerini hızlandırır ve çok fazla I/O tasarrufu sağlar.

Örneğin, bu kod `df` içeriğini yükler ve ardından `edited_df` için yalnızca değişen parçaları yüklediğinden yükleme daha hızlıdır:

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

Parçalar ~64kB boyutundadır ve Parquet verileri sütun sütun kaydettiğinden, pratikte bir Optimize Edilmiş Parquet dosyası düzenlendiğinde şunlar gerçekleşir:

* yeni bir sütun ekleyin -> yalnızca yeni sütunun parçaları yüklenir
* satır ekleme/düzenleme/silme -> her sütun için bir parça yüklenir

Bunun yanı sıra, Parquet altbilgisindeki metadata içeren parçalar da yüklenir.

## Görüntüler Kullanın

Bir klasör yükleyebilirsiniz; bu klasör, görsellerin adlarını veya yollarını içeren bir alanı barındıran bir meta veri dosyası içerir ve şu şekilde yapılandırılmıştır:

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

Görsel yollarını şu şekilde döngüye alabilirsiniz:

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

Veri seti [desteklenen bir yapıda](https://huggingface.co/docs/hub/en/datasets-image#additional-columns) (`file_name` alanına sahip bir `metadata.csv` veya `.jsonl` dosyası) olduğundan, bu veri setini Hugging Face'e kaydedebilir ve Hugging Face'teki Dataset Viewer hem metadata'yı hem de görüntüleri gösterebilir.

```python
from huggingface_hub import HfApi
api = HfApi()

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

### Görüntü yöntemleri ve Parquet

[pandas-image-methods](https://github.com/lhoestq/pandas-image-methods) kullanarak bir görüntü sütununda `PIL.Image` yöntemlerini etkinleştirebilirsiniz. Ayrıca görüntüleri ve meta verileri içeren tek bir Parquet dosyası olarak veri setini kaydetmeyi de sağlar:

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

Tüm `PIL.Image` yöntemleri kullanılabilir, örneğin

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

## Sesleri Kullanın

İçinde seslerin adlarını veya yollarını içeren bir alan bulunan bir metadata dosyası içeren bir klasörü şu şekilde yapılandırılmış olarak yükleyebilirsiniz:

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

Ses dosyası yollarını şu şekilde döngüye alabilirsiniz:

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

Veri seti [desteklenen bir yapıda](https://huggingface.co/docs/hub/en/datasets-audio#additional-columns) (`file_name` alanına sahip bir `metadata.csv` veya `.jsonl` dosyası) olduğundan, Hugging Face'e kaydedebilirsiniz ve Hub Veri Seti Görüntüleyici hem meta verileri hem de sesleri gösterir.

```python
from huggingface_hub import HfApi
api = HfApi()

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

### Ses yöntemleri ve Parquet

[pandas-audio-methods](https://github.com/lhoestq/pandas-audio-methods) kullanarak bir ses sütununda `soundfile` yöntemlerini etkinleştirebilirsiniz. Ayrıca, hem sesleri hem de meta verileri içeren tek bir Parquet dosyası olarak veri setini kaydetmeyi de mümkün kılar:

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

Bu, `librosa` ile örneğin yeniden örneklemeye (resampling) yönelik kullanımını kolaylaştırır:

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

## Transformers Kullanın

`transformers` pipeline'lerini pandas DataFrames üzerinde sınıflandırma, metin ve görsel üretimi gibi işlemler için kullanabilirsiniz. Bu bölümde, ilerleme çubukları için `tqdm` ile birkaç örnek gösterilmektedir.

> [!TIP]
> Pipelines, girdi olarak bir `tqdm` nesnesi kabul etmez ancak bunun yerine `x for x in tqdm(...)` biçiminde bir python jeneratörü kullanabilirsiniz.

### Metin Sınıflandırma

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

### Metin Üretimi

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