Agrupación de puntos de datos

Agrupamiento de Puntos de Datos

DataPoint, Cluster y ClusterCollection son un pequeño conjunto de herramientas de propósito general para clustering jerárquico-aglomerativo incluido con Aspose.PDF FOSS para Python. Son primitivas genéricas de agrupación de datos — un punto con coordenadas y etiqueta, un grupo de elementos y una colección de grupos — en lugar de una característica de documento específica de PDF; nada en este módulo lee o escribe contenido PDF por sí mismo. Úsalas cuando tu propio código necesite agrupar valores numéricos (por ejemplo, medidas que ya hayas extraído de un documento) en clústeres y resumir un clúster con su centroide.

Representación de un Punto de Datos

DataPoint combina un name identificador con una lista value de coordenadas numéricas. Ambos se exponen como DataPoint.name y DataPoint.value después de la construcción.

Construcción y Copia de Clústeres

Cluster envuelve una lista opcional de elementos en un único grupo. Cluster.count informa cuántos elementos contiene actualmente el clúster, Cluster.contains() verifica si un elemento dado es miembro, y Cluster.clone() devuelve una copia independiente respaldada por su propia lista de elementos. Cluster.empty() devuelve una instancia vacía de clúster compartida, singleton, en lugar de asignar una nueva en cada llamada.

Agrupación de Clústeres en una Colección

ClusterCollection envuelve una lista opcional de instancias de Cluster en una única colección, proporcionándote un objeto para pasar cuando una función necesita aceptar o devolver más de un cluster a la vez.

Calculando el centroide de un cluster

DataPoint.get_centroid() promedia las coordenadas de cada punto de datos en un Cluster, posición por posición, y devuelve un nuevo DataPoint que representa el centroide. Cada punto del cluster debe tener el mismo número de dimensiones en DataPoint.value para que el promedio sea significativo.

Consejos y mejores prácticas

Mantén todas las listas de DataPoint.value con la misma longitud dentro de un cluster — DataPoint.get_centroid() promedia las coordenadas posición por posición, por lo que dimensiones desajustadas generan un centroide engañoso.
Utiliza Cluster.empty() para un cluster vacío compartido y único en lugar de crear un nuevo cluster vacío cuando solo necesitas un valor marcador.
Invoca Cluster.clone() antes de modificar un cluster del que aún necesitas el original en otro sitio — clonar copia la lista de elementos en vez de crear un alias.
Recurre a ClusterCollection cuando una función necesita aceptar o devolver más de un Cluster como un único valor.
Estas clases son utilidades genéricas, no una característica de análisis de PDF — combínalas con tu propia lógica para producir los valores DataPoint a partir de los datos del documento.

Problemas comunes

Problema	Causa	Solución
`DataPoint.get_centroid()` produce un centroide con un número inesperado de valores	Los puntos de datos en el clúster tienen listas `DataPoint.value` de diferentes longitudes	Asegúrese de que cada `DataPoint` añadido a un `Cluster` tenga la misma dimensionalidad
`Cluster.contains()` devuelve `False` para un valor que espera que esté presente	La membresía se verifica directamente contra los objetos de elemento almacenados, por lo que dos instancias `DataPoint` construidas por separado con el mismo nombre y valor no se consideran automáticamente iguales en búsquedas basadas en identidad	Reutiliza la misma instancia de `DataPoint`, o compara por `DataPoint.name` y `DataPoint.value` antes de asumir pertenencia
Mutar un clúster clonado también modifica el original	Se omitió `Cluster.clone()` y la misma referencia de `Cluster` se compartió en vez de copiarse	Llama a `Cluster.clone()` primero siempre que el llamador necesite una copia independiente

FAQ

¿Cuál es la diferencia entre `Cluster` y `ClusterCollection`?

Cluster contiene una lista de elementos — típicamente instancias de DataPoint — que pertenecen a un grupo. ClusterCollection contiene una lista de objetos Cluster: agrupa conglomerados juntos, no puntos de datos individuales.

¿Modifica `DataPoint.get_centroid()` el clúster que se le proporciona?

No. Lee los elementos que ya están en el Cluster suministrado y devuelve un nuevo DataPoint para el centroide; el clúster origen y sus elementos permanecen sin cambios.

¿Esta funcionalidad de clustering es específica del contenido PDF?

No. DataPoint, Cluster y ClusterCollection son primitivas genéricas de agrupamiento numérico que se envían dentro del paquete aspose_pdf. No leen páginas, texto ni ninguna otra estructura PDF por sí mismas — operan únicamente con los valores con los que los construyes.

¿Por qué `Cluster.empty()` devuelve la misma instancia cada vez?

Cluster.empty() devuelve un singleton compartido para que las llamadas repetidas de “no cluster” no asignen un nuevo objeto en cada llamada.

API Reference Resumen

Clase/Método	Descripción
`DataPoint`	Un punto nombrado que contiene una lista de coordenadas numéricas
`DataPoint.name`	El nombre identificador del punto
`DataPoint.value`	La lista de coordenadas numéricas del punto
`DataPoint.get_centroid()`	Devuelve un nuevo `DataPoint` promediando las coordenadas de cada punto en un clúster
`Cluster`	Un grupo de elementos, típicamente instancias de `DataPoint`
`Cluster.empty()`	Devuelve el singleton de clúster vacío compartido
`Cluster.contains()`	Comprueba si un elemento está en el clúster
`Cluster.clone()`	Devuelve una copia independiente del clúster
`Cluster.count`	El número de elementos actualmente en el clúster
`ClusterCollection`	Envuelve una lista de instancias de `Cluster` en una única colección

Ver también

Aspose.PDF for Python — Enterprise Documentation