Jak pracovat s clusteringem v Python

Aspose.PDF FOSS pro Python obsahuje malý, obecný hierarchický aglomerativní nástroj pro shlukování — nezávislý na jakékoli konkrétní operaci s PDF — pro seskupování souvisejících objektů DataPoint do instancí Cluster a výpočet centroidu shluku. Vy určujete, co každý datový bod představuje, a zadáváte jeho souřadnice sami; nástroj je nevyplňuje automaticky. Knihovna se nainstaluje pomocí níže uvedeného příkazu.

Průvodce krok za krokem

Krok 1: Nainstalujte balíček

Nainstalujte balíček 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 .

Ověřte instalaci importováním Cluster a vytištěním potvrzovací zprávy:

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

Krok 2: Naimportujte požadované třídy

Importujte tři třídy, které tvoří nástroj pro shlukování:

from aspose_pdf import Cluster, ClusterCollection, DataPoint

Krok 3: Vytvořte datové body

Objekt DataPoint spojuje řetězec name s value seznamem desetinných čísel — souřadnice nebo vektor vlastností, které považujete za smysluplné pro vlastní logiku seskupování:

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 nespojuje value s žádným konkrétním konceptem PDF — souřadnice stránky, metriku písma nebo jakýkoli jiný číselný vektor vlastností fungují stejně dobře.

Krok 4: Seskupte datové body do shluku

Předávejte úplný seznam členství konstruktoru Cluster. Po vytvoření neexistuje metoda pro přidání položek do Cluster, proto určete členství nejprve:

from aspose_pdf import Cluster

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

contains() porovnává podle rovnosti — DataPoint definuje rovnost na základě name a value dohromady, takže jiná instance DataPoint se stejným názvem a hodnotou je také hlášena jako obsažená.

Krok 5: Vypočítejte centroid klastru

DataPoint.get_centroid(cluster) je statická metoda, která zprůměruje každou dimenzi každého DataPoint.value v klastru a vrátí výsledek jako nový DataPoint pojmenovaný "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ždý seznam DataPoint.value v klastru musí mít stejnou délku — get_centroid průměruje pozice po jednotlivých prvcích a neověřuje, zda se délky shodují. Volání na Cluster.empty() nebo na libovolný klastr s count == 0 vyvolá ValueError.

Krok 6: Klonovat klastr nebo znovu použít sdílenou prázdnou instanci

clone() vrací nezávislý Cluster obsahující stejné položky; Cluster.empty() vždy vrací stejnou kešovanou prázdnou instanci klastru místo alokace nové:

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: Seskupit více klastrů do ClusterCollection

ClusterCollection seskupuje několik objektů Cluster za jedním kontejnerem, který je len()-schopný:

from aspose_pdf import Cluster, ClusterCollection

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

ClusterCollection neexponuje metodu pro získání svých klastrů zpět — uchovejte si odkaz na seznam, který předáte konstruktoru, pokud potřebujete později iterovat klastery.

Běžné problémy a opravy

Neexistuje žádná metoda, jak přidat položku k existujícímu Cluster

Cluster přijímá svůj seznam členství pouze při konstrukci (Cluster(items)). Nejprve vytvořte kompletní seznam objektů DataPoint, pak vytvořte Cluster — neexistuje žádná add() ani append(), kterou by bylo možné zavolat později.

DataPoint.get_centroid() raises ValueError

K tomu dochází, když je předaný klastr prázdný (count == 0), včetně Cluster.empty(). Zkontrolujte cluster.count před voláním get_centroid, nebo ošetřete výjimku, pokud je prázdný klastr platným vstupem ve vašem workflow.

Hodnoty centroidu vypadají špatně

get_centroid sčítá každou DataPoint.value pozici po pozici a dělí počtem bodů — nekontroluje, že každý seznam value v klastru má stejnou délku. Míchání objektů DataPoint s neodpovídající dimenzionalitou způsobí nesprávný průměr tiše, místo aby vyvolalo výjimku.

Expecting Cluster.empty() vytvořit čerstvý prázdný cluster pokaždé

Cluster.empty() je přístupový objekt singleton — každé volání vrací stejnou uloženou instanci. Použijte Cluster() (bez argumentů) místo toho, pokud potřebujete odlišný, nezávislý prázdný shluk.

Očekává se, že knihovna automaticky seskupí body

DataPoint, Cluster a ClusterCollection jsou datové struktury pro reprezentaci bodů, shluků a výpočtu středu — modul neobsahuje spojovací nebo vzdálenostní funkci, která rozhoduje, které body patří k sobě. Váš vlastní kód určuje příslušnost ke shluku před vytvořením Cluster.

Často kladené otázky

Rozděluje tento modul automaticky datové body podle vzdálenosti?

Ne. Cluster, DataPoint a ClusterCollection jsou stavební bloky pro reprezentaci již rozhodnutých seskupení a výpočet středu — neexistuje žádný vestavěný krok agregace nebo přiřazení založený na vzdálenosti.

Jaký je rozdíl mezi `Cluster()` a `Cluster.empty()`?

Cluster(items=None) vytváří novou instanci při každém volání. Cluster.empty() je classmethod, která vrací stejnou kešovanou, sdílenou empty-cluster instanci při každém volání.

Mohu po vytvoření přidávat položky do `Cluster`?

Ne. Cluster zpřístupňuje pouze contains(), clone() a vlastnost count nad rámec konstrukce — členství je pevně dané, jakmile se spustí konstruktor.

Funguje `get_centroid()` s libovolným počtem dimenzí?

Ano, pokud má každý seznam DataPoint.value v clusteru stejnou délku. get_centroid průměruje každou dimenzi nezávisle a vrací výsledek jako nový DataPoint.

Co `ClusterCollection` přidává nad rámec obyčejného Python seznamu clusterů?

Především typovaný kontejner s podporou len(). Nepřidává iteraci, vyhledávání ani chování slučování nad rámec toho, co již máte v seznamu, ze kterého byl vytvořen.