Jak pracować z klasteryzacją w Python

Aspose.PDF FOSS dla Python zawiera małe, ogólnego przeznaczenia narzędzie do hierarchicznego aglomeracyjnego klasteryzowania — niezależne od jakiejkolwiek pojedynczej operacji PDF — służące do grupowania powiązanych obiektów DataPoint w instancje Cluster oraz obliczania środka masy klastra. Decydujesz, co reprezentuje każdy punkt danych i podajesz jego współrzędne samodzielnie; narzędzie nie wypełnia ich automatycznie. Biblioteka jest instalowana poleceniem poniżej.

Przewodnik krok po kroku

Krok 1: Zainstaluj pakiet

Zainstaluj pakiet Aspose.PDF FOSS:

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

Zweryfikuj instalację, importując Cluster i wyświetlając komunikat potwierdzający:

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

Krok 2: Importuj wymagane klasy

Zaimportuj trzy klasy, które tworzą narzędzie do grupowania:

from aspose_pdf import Cluster, ClusterCollection, DataPoint

Krok 3: Utwórz punkty danych

Obiekt DataPoint łączy ciąg name z listą value liczb zmiennoprzecinkowych — współrzędne lub wektor cech, które uznasz za istotne dla własnej logiki grupowania:

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 nie wiąże value z żadnym konkretnym pojęciem PDF — współrzędne strony, metryki czcionki lub dowolny inny wektor cech numerycznych działają równie dobrze.

Krok 4: Grupuj punkty danych w klaster

Przekaż pełną listę członków do konstruktora Cluster. Nie ma metody dodawania elementów do Cluster po jego utworzeniu, więc najpierw zdecyduj o członkostwie:

from aspose_pdf import Cluster

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

contains() dopasowuje na podstawie równości — DataPoint definiuje równość na podstawie name i value razem, więc inna instancja DataPoint o tej samej nazwie i wartości także jest zgłaszana jako zawarta.

Krok 5: Oblicz centroid klastra

DataPoint.get_centroid(cluster) jest metodą statyczną, która uśrednia każdy wymiar każdego DataPoint.value w klastrze i zwraca wynik jako nowy DataPoint o nazwie "centroid":

from aspose_pdf import DataPoint

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

Każda lista DataPoint.value w klastrze musi mieć tę samą długość — get_centroid uśrednia pozycję po pozycji i nie sprawdza, czy długości się zgadzają. Wywołanie jej na Cluster.empty() lub na dowolnym klastrze z count == 0 rzuca ValueError.

Krok 6: Klonuj klaster lub użyj współdzielonej pustej instancji

clone() zwraca niezależny Cluster zawierający te same elementy; Cluster.empty() zawsze zwraca tę samą buforowaną instancję empty-cluster zamiast alokować nową:

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

Krok 7: Grupuj wiele klastrów w ClusterCollection

ClusterCollection grupuje kilka obiektów Cluster w jednym kontenerze świadomym len():

from aspose_pdf import Cluster, ClusterCollection

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

ClusterCollection nie udostępnia metody do pobrania swoich klastrów — zachowaj referencję do listy przekazanej do konstruktora, jeśli potrzebujesz później iterować po klastrach.

Typowe problemy i rozwiązania

Nie ma metody, aby dodać element do istniejącego Cluster

Cluster akceptuje listę członków tylko podczas tworzenia (Cluster(items)). Najpierw zbuduj pełną listę obiektów DataPoint, a potem utwórz Cluster — nie ma add() ani append(), które można wywołać później.

DataPoint.get_centroid() raises ValueError

Dzieje się to, gdy przekazany klaster jest pusty (count == 0), łącznie z Cluster.empty(). Sprawdź cluster.count przed wywołaniem get_centroid, lub obsłuż wyjątek, jeśli pusty klaster jest dopuszczalnym wejściem w Twoim przepływie pracy.

Wartości centroidu wyglądają nieprawidłowo

get_centroid sumuje każdą pozycję DataPoint.value po kolei i dzieli przez liczbę punktów — nie sprawdza, czy każda lista value w klastrze ma tę samą długość. Mieszanie obiektów DataPoint o niepasującej wymiarowości powoduje niepoprawną średnią, cicho, zamiast zgłosić błąd.

Expecting Cluster.empty() aby za każdym razem utworzyć nowy pusty klaster

Cluster.empty() jest dostępem singleton — każde wywołanie zwraca tę samą buforowaną instancję. Użyj Cluster() (bez argumentów), jeśli potrzebujesz odrębnego, niezależnego pustego klastra.

Oczekując, że biblioteka automatycznie grupuje punkty

DataPoint, Cluster i ClusterCollection to struktury danych służące do reprezentacji punktów, klastrów i obliczania środka ciężkości — moduł nie zawiera funkcji łączenia ani odległości, które decydują, które punkty należą do siebie. To Twój własny kod określa przynależność do klastra przed utworzeniem Cluster.

Najczęściej zadawane pytania

Czy ten moduł automatycznie grupuje punkty danych według odległości?

Nie. Cluster, DataPoint i ClusterCollection są elementami budulcowymi do reprezentacji już ustalonych grupowań i obliczania środka ciężkości — nie ma wbudowanego etapu aglomeracji ani przypisywania opartego na odległości.

Jaka jest różnica między `Cluster()` a `Cluster.empty()`?

Cluster(items=None) tworzy nową instancję za każdym razem, gdy jest wywoływany. Cluster.empty() jest metodą klasy, która zwraca tę samą buforowaną, współdzieloną pustą instancję klastra przy każdym wywołaniu.

Czy mogę dodać elementy do `Cluster` po jego utworzeniu?

Nie. Cluster udostępnia tylko contains(), clone() oraz właściwość count poza konstrukcją — członkostwo jest ustalone po uruchomieniu konstruktora.

Czy `get_centroid()` działa z dowolną liczbą wymiarów?

Tak, pod warunkiem że każda lista DataPoint.value w klastrze ma tę samą długość. get_centroid uśrednia każdy wymiar niezależnie i zwraca wynik jako nowy DataPoint.

Co `ClusterCollection` dodaje poza zwykłą listą Python klastrów?

Głównie typowany kontener z obsługą len(). Nie dodaje iteracji, wyszukiwania ani zachowań scalania poza tym, co już masz w liście, z której go utworzyłeś.