Hur man arbetar med klustring i Python

Aspose.PDF FOSS för Python paketar ett litet, allmänt hierarkiskt agglomerativt klustringsverktyg — oberoende av någon enskild PDF-operation — för att gruppera relaterade DataPoint-objekt i Cluster-instanser och beräkna ett klusters centroid. Du bestämmer vad varje datapunkt representerar och tillhandahåller dess koordinater själv; verktyget fyller inte i dem automatiskt. Biblioteket installeras med kommandot nedan.

Steg-för-steg-guide

Steg 1: Installera paketet

Installera Aspose.PDF FOSS-paketet:

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

Verifiera installationen genom att importera Cluster och skriva ut ett bekräftelsemeddelande:

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

Steg 2: Importera erforderliga klasser

Importera de tre klasserna som utgör klustringsverktyget:

from aspose_pdf import Cluster, ClusterCollection, DataPoint

Steg 3: Skapa datapunkter

En DataPoint parar ihop en name sträng med en value lista av flyttal — koordinaterna eller funktionsvektorn som du anser är meningsfulla för din egen grupperinglogik:

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 binder inte value till något särskilt PDF-koncept — sidkoordinater, teckensnittsmått eller någon annan numerisk funktionsvektor fungerar lika bra.

Steg 4: Gruppera datapunkter i ett kluster

Skicka hela medlemslistan till Cluster-konstruktorn. Det finns ingen metod för att lägga till objekt i en Cluster efter att den har skapats, så bestäm medlemskapet först:

from aspose_pdf import Cluster

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

contains() matchar genom likhet — DataPoint definierar likhet på name och value tillsammans, så en annan DataPoint-instans med samma namn och värde rapporteras också som innehållen.

Steg 5: Beräkna klustrets centroid

DataPoint.get_centroid(cluster) är en statisk metod som beräknar medelvärdet för varje dimension av varje DataPoint.value i klustret och returnerar resultatet som ett nytt DataPoint med namnet "centroid":

from aspose_pdf import DataPoint

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

Varje DataPoint.value-lista i klustret måste ha samma längd — get_centroid beräknar medelvärdet position för position och validerar inte att längderna matchar. Att anropa den på Cluster.empty(), eller vilket kluster som helst med count == 0, kastar ValueError.

Steg 6: Klona ett kluster eller återanvänd den delade tomma instansen

clone() returnerar ett oberoende Cluster som innehåller samma objekt; Cluster.empty() returnerar alltid samma cachade empty-cluster-instans istället för att allokera en ny:

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

Steg 7: Gruppera flera kluster i en ClusterCollection

ClusterCollection samlar flera Cluster-objekt bakom en enda len()-medveten behållare:

from aspose_pdf import Cluster, ClusterCollection

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

ClusterCollection exponerar inte en metod för att hämta tillbaka sina kluster — behåll en referens till listan du skickar in i konstruktorn om du behöver iterera över klustren senare.

Vanliga problem och lösningar

Det finns ingen metod för att lägga till ett objekt i ett befintligt Cluster

Cluster accepterar endast sin medlemslista vid konstruktionstid (Cluster(items)). Bygg den kompletta listan av DataPoint-objekt först, skapa sedan Cluster — det finns ingen add() eller append() att anropa efteråt.

DataPoint.get_centroid() raises ValueError

Detta händer när den överförda klustern är tom (count == 0), inklusive Cluster.empty(). Kontrollera cluster.count innan du anropar get_centroid, eller hantera undantaget om en tom kluster är en giltig indata i ditt arbetsflöde.

Centroidvärden ser felaktiga ut

get_centroid summerar varje DataPoint.value position för position och delar med antalet punkter — den kontrollerar inte att varje value-lista i klustern har samma längd. Att blanda DataPoint-objekt med olika dimensionalitet ger ett felaktigt genomsnitt tyst istället för att kasta ett fel.

Expecting Cluster.empty() för att skapa ett nytt tomt kluster varje gång

Cluster.empty() är en singleton-åtkomst – varje anrop returnerar samma cachade instans. Använd Cluster() (utan argument) istället om du behöver ett separat, oberoende tomt kluster.

Förväntar att biblioteket grupperar punkter automatiskt

DataPoint, Cluster och ClusterCollection är datastrukturer för att representera punkter, kluster och en centroidberäkning – modulen innehåller ingen länk- eller avståndsfunktion som avgör vilka punkter som hör ihop. Din egen kod bestämmer klustertillhörighet innan du konstruerar ett Cluster.

Vanliga frågor

Grupperar den här modulen automatiskt datapunkter efter avstånd?

Nej. Cluster, DataPoint och ClusterCollection är byggstenar för att representera redan bestämda grupperingar och beräkna en centroid – det finns inget inbyggt agglomerations- eller avståndsbaserat tilldelningssteg.

Vad är skillnaden mellan `Cluster()` och `Cluster.empty()`?

Cluster(items=None) skapar en ny instans varje gång den anropas. Cluster.empty() är en classmethod som returnerar samma cachade, delade empty-cluster-instans vid varje anrop.

Kan jag lägga till objekt i en `Cluster` efter att den har skapats?

Nej. Cluster exponerar endast contains(), clone() och count-egenskapen utöver konstruktionen — medlemskapet är fast när konstruktorn har körts.

Fungerar `get_centroid()` med ett godtyckligt antal dimensioner?

Ja, så länge varje DataPoint.value list i klustret har samma längd. get_centroid beräknar medelvärdet för varje dimension oberoende och returnerar resultatet som en ny DataPoint.

Vad lägger `ClusterCollection` till utöver en vanlig Python lista med kluster?

Främst en typad behållare med len()-stöd. Den lägger inte till iteration, uppslagning eller sammanslagningsbeteende utöver det du redan har i listan du konstruerade den från.