Кластеризация точек данных

DataPoint, Cluster и ClusterCollection — небольшой, универсальный набор инструментов для иерархической агломеративной кластеризации, поставляемый вместе с Aspose.PDF FOSS для Python. Это общие primitives для группировки данных — точка с координатами и меткой, группа элементов и коллекция групп — а не функция, специфичная для PDF-документов; модуль не читает и не записывает PDF-контент. Используйте их, когда ваш собственный код должен группировать числовые значения (например, измерения, уже извлечённые из документа) в кластеры и суммировать кластер с помощью его центроида.

Представление точки данных

DataPoint связывает идентифицирующий name со value списком числовых координат. Оба доступны как DataPoint.name и DataPoint.value после создания.

Создание и копирование кластеров

Cluster оборачивает необязательный список элементов в одну группу. Cluster.count сообщает, сколько элементов сейчас содержит кластер, Cluster.contains() проверяет, является ли данный элемент членом, а Cluster.clone() возвращает независимую копию с собственным списком элементов. Cluster.empty() возвращает общую, единственную пустую кластерную сущность вместо создания новой при каждом вызове.

Группировка кластеров в коллекции

ClusterCollection оборачивает необязательный список экземпляров Cluster в одну коллекцию, предоставляя вам один объект для передачи, когда функции необходимо принять или вернуть более одного кластера одновременно.

Вычисление центроида кластера

DataPoint.get_centroid() вычисляет среднее значение координат каждой точки данных в Cluster позиция за позицией и возвращает новый DataPoint, представляющий центроид. Каждая точка в кластере должна иметь одинаковое количество измерений в DataPoint.value, чтобы среднее имело смысл.

Советы и лучшие практики

Держите каждый список DataPoint.value одинаковой длины внутри кластера — DataPoint.get_centroid() вычисляет среднее координат позиция за позицией, поэтому несовпадающие размеры приводят к вводящему в заблуждение центроиду.
Используйте Cluster.empty() для общего, единственного пустого кластера вместо создания нового пустого кластера, когда вам нужен лишь заполнитель.
Вызовите Cluster.clone() перед изменением кластера, оригинал которого вам ещё нужен в другом месте — клонирование копирует список элементов, а не создаёт алиас.
Обращайтесь к ClusterCollection, когда функции необходимо принять или вернуть более одного Cluster в виде единого значения.
Эти классы являются универсальными утилитами, а не функцией парсинга PDF — используйте их вместе со своей логикой для получения значений DataPoint из данных документа.

Распространённые проблемы

Проблема	Причина	Исправление
`DataPoint.get_centroid()` создает центр масс с неожиданным количеством значений	Точки данных в кластере имеют списки `DataPoint.value` разной длины	Убедитесь, что каждый `DataPoint`, добавляемый в `Cluster`, имеет одинаковую размерность
`Cluster.contains()` возвращает `False` для значения, которое вы ожидаете присутствовать	Членство проверяется непосредственно по хранящимся объектам элементов, поэтому два отдельно сконструированных экземпляра `DataPoint` с одинаковым именем и значением автоматически не считаются равными при поиске по идентичности	Повторно используйте тот же экземпляр `DataPoint`, либо сравнивайте по `DataPoint.name` и `DataPoint.value`, прежде чем предполагать членство
Изменение клонированного кластера также изменяет оригинал	`Cluster.clone()` был пропущен, и тот же объект `Cluster` был использован совместно вместо копирования	Сначала вызовите `Cluster.clone()`, когда вызывающему коду нужна независимая копия

FAQ

В чём разница между `Cluster` и `ClusterCollection`?

Cluster содержит список элементов — обычно экземпляры DataPoint — которые принадлежат одной группе. ClusterCollection содержит список объектов Cluster: он объединяет кластеры, а не отдельные точки данных.

Изменяет ли `DataPoint.get_centroid()` переданный ему кластер?

Нет. Он читает элементы, уже находящиеся в переданном Cluster, и возвращает новый DataPoint для центроида; исходный кластер и его элементы остаются без изменений.

Является ли эта функция кластеризации специфической для PDF-контента?

No. DataPoint, Cluster и ClusterCollection являются общими примитивами числовой кластеризации, поставляемыми в пакете aspose_pdf. Они не читают страницы, текст или любую другую структуру PDF сами по себе — они работают исключительно с переданными им значениями.

Почему `Cluster.empty()` возвращает один и тот же экземпляр каждый раз?

Cluster.empty() возвращает общий singleton, чтобы повторные вызовы для “no cluster” не создавали новый объект каждый раз.

API Reference Сводка

Класс/Метод	Описание:
`DataPoint`	Именованная точка, содержащая список числовых координат
`DataPoint.name`	Идентифицирующее имя точки
`DataPoint.value`	Список числовых координат точки
`DataPoint.get_centroid()`	Возвращает новый `DataPoint`, усредняющий координаты каждой точки в кластере
`Cluster`	Группа элементов, обычно экземпляры `DataPoint`
`Cluster.empty()`	Возвращает общий singleton пустого кластера
`Cluster.contains()`	Проверяет, находится ли элемент в кластере
`Cluster.clone()`	Возвращает независимую копию кластера
`Cluster.count`	Текущее количество элементов в кластере
`ClusterCollection`	Объединяет список экземпляров `Cluster` в одну коллекцию

См. также:

Aspose.PDF for Python — Enterprise Documentation

Кластеризация точек данных