Cara Bekerja dengan Clustering di Python

Aspose.PDF FOSS untuk Python menyertakan utilitas clustering hierarkis aglomeratif kecil yang bersifat umum — independen dari operasi PDF tunggal — untuk mengelompokkan objek DataPoint yang terkait menjadi instance Cluster dan menghitung centroid klaster. Anda menentukan apa yang direpresentasikan setiap titik data dan menyediakan koordinatnya sendiri; utilitas ini tidak mengisinya secara otomatis. Perpustakaan diinstal dengan perintah di bawah.

Panduan Langkah demi Langkah

Langkah 1: Instal Paket

Instal paket FOSS Aspose.PDF:

git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .

Verifikasi instalasi dengan mengimpor Cluster dan mencetak pesan konfirmasi:

from aspose_pdf import Cluster
print("aspose-pdf-foss-for-python is ready.")

Langkah 2: Impor Kelas yang Diperlukan

Impor tiga kelas yang membentuk utilitas clustering:

from aspose_pdf import Cluster, ClusterCollection, DataPoint

Langkah 3: Buat Titik Data

Sebuah DataPoint menggabungkan string name dengan daftar value float — koordinat atau vektor fitur yang Anda anggap bermakna untuk logika pengelompokan Anda sendiri:

from aspose_pdf import DataPoint

point_a = DataPoint("item-1", [12.0, 45.0])
point_b = DataPoint("item-2", [13.5, 44.0])
point_c = DataPoint("item-3", [98.0, 5.0])

print(point_a.name, point_a.value)

DataPoint tidak mengaitkan value dengan konsep PDF tertentu — koordinat halaman, metrik font, atau vektor fitur numerik lainnya semuanya bekerja dengan baik.

Langkah 4: Kelompokkan Titik Data menjadi Klaster

Berikan daftar keanggotaan lengkap ke konstruktor Cluster. Tidak ada metode untuk menambahkan item ke Cluster setelah dibuat, jadi tentukan keanggotaan terlebih dahulu:

from aspose_pdf import Cluster

nearby = Cluster([point_a, point_b])
print(nearby.count)              # 2
print(nearby.contains(point_a))  # True

contains() cocok berdasarkan kesamaan — DataPoint mendefinisikan kesamaan pada name dan value secara bersamaan, sehingga instance DataPoint yang berbeda dengan nama dan nilai yang sama juga dilaporkan sebagai terkandung.

Langkah 5: Hitung Sentroid Klaster

DataPoint.get_centroid(cluster) adalah metode statis yang merata-rata setiap dimensi dari setiap DataPoint.value dalam klaster dan mengembalikan hasilnya sebagai DataPoint baru yang bernama "centroid":

from aspose_pdf import DataPoint

centroid = DataPoint.get_centroid(nearby)
print(centroid.name)   # "centroid"
print(centroid.value)  # per-dimension average across the cluster

Setiap daftar DataPoint.value dalam klaster harus memiliki panjang yang sama — get_centroid merata-rata posisi per posisi dan tidak memvalidasi bahwa panjangnya cocok. Memanggilnya pada Cluster.empty(), atau klaster apa pun dengan count == 0, menimbulkan ValueError.

Langkah 6: Gandakan Klaster atau Gunakan Kembali Instansi Kosong Bersama

clone() mengembalikan Cluster independen yang memegang item yang sama; Cluster.empty() selalu mengembalikan instansi klaster-kosong yang sama yang di-cache alih-alih membuat yang baru:

from aspose_pdf import Cluster

backup = nearby.clone()
print(backup is nearby)          # False -- independent copy
print(backup.contains(point_a))  # True -- same items

placeholder = Cluster.empty()
print(placeholder.count)         # 0

Langkah 7: Kelompokkan Beberapa Klaster ke dalam ClusterCollection

ClusterCollection menggabungkan beberapa objek Cluster di belakang satu kontainer yang mendukung len():

from aspose_pdf import Cluster, ClusterCollection

outliers = Cluster([point_c])
collection = ClusterCollection([nearby, outliers])
print(len(collection))  # 2

ClusterCollection tidak menyediakan metode untuk mengambil kembali klasternya — simpan referensi ke daftar yang Anda berikan ke konstruktor jika Anda perlu mengiterasi klaster tersebut nanti.

Masalah Umum dan Solusi

Tidak ada metode untuk menambahkan item ke yang sudah ada Cluster

Cluster hanya menerima daftar keanggotaannya pada saat konstruksi (Cluster(items)). Bangun daftar lengkap objek DataPoint terlebih dahulu, kemudian buat Cluster — tidak ada add() atau append() yang dapat dipanggil setelahnya.

DataPoint.get_centroid() raises ValueError

Ini terjadi ketika klaster yang diberikan kosong (count == 0), termasuk Cluster.empty(). Periksa cluster.count sebelum memanggil get_centroid, atau tangani pengecualian jika klaster kosong merupakan input yang valid dalam alur kerja Anda.

Nilai centroid tampak salah

get_centroid menjumlahkan setiap posisi DataPoint.value satu per satu dan membagi dengan jumlah titik — tidak memeriksa bahwa setiap daftar value dalam klaster memiliki panjang yang sama. Mencampur objek DataPoint dengan dimensi yang tidak cocok menghasilkan rata-rata yang salah secara diam-diam alih-alih menimbulkan kesalahan.

Expecting Cluster.empty() untuk membuat klaster kosong baru setiap kali

Cluster.empty() adalah accessor singleton — setiap panggilan mengembalikan instance yang sama yang di-cache. Gunakan Cluster() (tanpa argumen) sebagai gantinya jika Anda memerlukan klaster kosong yang terpisah dan independen.

Mengharapkan perpustakaan mengelompokkan titik secara otomatis

DataPoint, Cluster, dan ClusterCollection adalah struktur data untuk merepresentasikan titik, klaster, dan perhitungan centroid — modul tidak menyertakan fungsi penghubung atau jarak yang menentukan titik mana yang bersama. Kode Anda sendiri menentukan keanggotaan klaster sebelum membangun Cluster.

Pertanyaan yang Sering Diajukan

Apakah modul ini secara otomatis mengelompokkan data poin berdasarkan jarak?

Tidak. Cluster, DataPoint, dan ClusterCollection adalah blok bangunan untuk merepresentasikan pengelompokan yang sudah diputuskan dan menghitung centroid — tidak ada langkah aglomerasi atau penugasan berbasis jarak yang built-in.

Apa perbedaan antara `Cluster()` dan `Cluster.empty()`?

Cluster(items=None) membuat sebuah instance baru setiap kali dipanggil. Cluster.empty() adalah classmethod yang mengembalikan instance cluster kosong yang sama, di-cache dan dibagikan, pada setiap pemanggilan.

Bisakah saya menambahkan item ke `Cluster` setelah membuatnya?

Tidak. Cluster hanya mengekspos contains(), clone(), dan properti count selain konstruksi — keanggotaan tetap tetap setelah konstruktor dijalankan.

Apakah `get_centroid()` berfungsi dengan jumlah dimensi berapa pun?

Ya, selama setiap daftar DataPoint.value dalam cluster memiliki panjang yang sama. get_centroid menghitung rata-rata setiap dimensi secara independen dan mengembalikan hasilnya sebagai DataPoint baru.

Apa yang ditambahkan `ClusterCollection` selain daftar Python sederhana dari cluster?

Terutama sebuah kontainer berjenis dengan dukungan len(). Ia tidak menambahkan perilaku iterasi, pencarian, atau penggabungan di luar apa yang sudah Anda miliki dalam daftar yang Anda gunakan untuk membuatnya.