Come Lavorare con il Clustering in Python

Aspose.PDF FOSS per Python include un piccolo utility di clustering gerarchico agglomerativo di uso generale — indipendente da qualsiasi operazione PDF singola — per raggruppare oggetti DataPoint correlati in istanze Cluster e calcolare il centroide di un cluster. Decidi tu cosa rappresenta ciascun punto dati e fornisci le sue coordinate; l’utilità non le popola automaticamente. La libreria si installa con il comando riportato di seguito.

Guida passo-passo

Passo 1: Installa il pacchetto

Installa il pacchetto 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 .

Verifica l’installazione importando Cluster e stampando un messaggio di conferma:

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

Passo 2: Importa le classi richieste

Importa le tre classi che costituiscono l’utilità di clustering:

from aspose_pdf import Cluster, ClusterCollection, DataPoint

Passo 3: Crea i punti dati

Un DataPoint associa una stringa name a una lista value di float — le coordinate o il vettore di caratteristiche che decidi siano significativi per la tua logica di raggruppamento:

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 non lega value a nessun concetto PDF specifico — le coordinate di pagina, le metriche dei font o qualsiasi altro vettore di caratteristiche numeriche funzionano tutti ugualmente bene.

Passo 4: Raggruppa i punti dati in un cluster

Passa l’elenco completo dei membri al costruttore Cluster. Non esiste un metodo per aggiungere elementi a un Cluster dopo che è stato creato, quindi decidi la composizione dei membri prima:

from aspose_pdf import Cluster

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

contains() corrisponde per uguaglianza — DataPoint definisce l’uguaglianza su name e value insieme, quindi una diversa istanza DataPoint con lo stesso nome e valore viene anch’essa segnalata come contenuta.

Passo 5: Calcola il centroide del cluster

DataPoint.get_centroid(cluster) è un metodo statico che media ogni dimensione di tutti i DataPoint.value nel cluster e restituisce il risultato come un nuovo DataPoint chiamato "centroid":

from aspose_pdf import DataPoint

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

Ogni lista DataPoint.value nel cluster deve avere la stessa lunghezza — get_centroid media posizione per posizione e non verifica che le lunghezze corrispondano. Chiamarla su Cluster.empty(), o su qualsiasi cluster con count == 0, solleva ValueError.

Passo 6: Clona un cluster o riutilizza l’istanza vuota condivisa

clone() restituisce un Cluster indipendente che contiene gli stessi elementi; Cluster.empty() restituisce sempre la stessa istanza di cluster vuoto memorizzata nella cache anziché allocarne una nuova:

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

Passo 7: Raggruppa più cluster in un ClusterCollection

ClusterCollection raggruppa diversi oggetti Cluster dietro un unico contenitore consapevole di len():

from aspose_pdf import Cluster, ClusterCollection

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

ClusterCollection non espone un metodo per recuperare i suoi cluster — conserva un riferimento alla lista che passi al costruttore se hai bisogno di iterare i cluster in seguito.

Problemi comuni e soluzioni

Non esiste alcun metodo per aggiungere un elemento a un esistente Cluster

Cluster accetta la sua lista di membri solo al momento della costruzione (Cluster(items)). Costruisci prima l’elenco completo di oggetti DataPoint, poi costruisci il Cluster — non esiste alcun add() o append() da chiamare successivamente.

DataPoint.get_centroid() raises ValueError

Questo accade quando il cluster passato è vuoto (count == 0), inclusi Cluster.empty(). Controlla cluster.count prima di chiamare get_centroid, oppure gestisci l’eccezione se un cluster vuoto è un input valido nel tuo flusso di lavoro.

I valori del centroide sembrano errati

get_centroid somma ogni posizione di DataPoint.value una per una e divide per il numero di punti — non verifica che ogni lista di value nel cluster abbia la stessa lunghezza. Mescolare oggetti DataPoint con dimensionalità non corrispondente produce una media errata in modo silenzioso invece di sollevare un’eccezione.

Expecting Cluster.empty() per creare un nuovo cluster vuoto ogni volta

Cluster.empty() è un accessor singleton — ogni chiamata restituisce la stessa istanza nella cache. Usa Cluster() (senza argomenti) invece se ti serve un cluster vuoto distinto e indipendente.

Ci si aspetta che la libreria raggruppi i punti automaticamente

DataPoint, Cluster e ClusterCollection sono strutture dati per rappresentare punti, cluster e un calcolo del centroide — il modulo non include una funzione di collegamento o di distanza che decida quali punti appartengono insieme. Il tuo codice determina l’appartenenza ai cluster prima di costruire un Cluster.

Domande Frequenti

Questo modulo raggruppa automaticamente i punti dati per distanza?

No. Cluster, DataPoint e ClusterCollection sono blocchi costitutivi per rappresentare raggruppamenti già decisi e calcolare un centroide — non esiste alcuna fase di aggregazione o di assegnazione basata sulla distanza incorporata.

Qual è la differenza tra `Cluster()` e `Cluster.empty()`?

Cluster(items=None) crea una nuova istanza ogni volta che viene chiamato. Cluster.empty() è un metodo di classe che restituisce la stessa istanza di cluster vuoto memorizzata nella cache e condivisa a ogni chiamata.

Posso aggiungere elementi a un `Cluster` dopo averlo creato?

No. Cluster espone solo contains(), clone() e la proprietà count oltre alla costruzione — l’appartenenza è fissata una volta che il costruttore viene eseguito.

Il `get_centroid()` funziona con qualsiasi numero di dimensioni?

Sì, purché ogni lista DataPoint.value nel cluster abbia la stessa lunghezza. get_centroid calcola la media di ogni dimensione in modo indipendente e restituisce il risultato come un nuovo DataPoint.

Cosa aggiunge `ClusterCollection` oltre a una semplice lista di cluster Python?

Principalmente un contenitore tipizzato con supporto len(). Non aggiunge iterazione, ricerca o comportamento di fusione oltre a ciò che hai già nella lista da cui lo hai costruito.