Як працювати з кластеризацією у Python

Aspose.PDF FOSS для Python постачає невелику універсальну утиліту ієрархічної агломеративної кластеризації — незалежну від будь-якої окремої PDF-операції — для групування пов’язаних об’єктів DataPoint у екземпляри Cluster та обчислення центроїда кластера. Ви вирішуєте, що представляє кожна точка даних, і самостійно надаєте її координати; утиліта не заповнює їх автоматично. Бібліотеку встановлюють за допомогою команди нижче.

Покроковий посібник

Крок 1: Встановити пакет

Встановіть пакет 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 .

Перевірте встановлення, імпортуючи Cluster і виводячи повідомлення підтвердження:

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

Крок 2: Імпортувати необхідні класи

Імпортуйте три класи, які становлять утиліту кластеризації:

from aspose_pdf import Cluster, ClusterCollection, DataPoint

Крок 3: Створити точки даних

Об’єкт DataPoint поєднує рядок name зі списком value типу float — координати або вектор ознак, які ви вважаєте значущими для вашої власної логіки групування:

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 не прив’язує value до жодної конкретної концепції PDF — координати сторінки, метрики шрифту або будь-який інший числовий вектор ознак працюють однаково добре.

Крок 4: Групувати точки даних у кластер

Передайте повний список членства у конструктор Cluster. Після створення Cluster немає методу додавання елементів, тому спочатку визначте членство:

from aspose_pdf import Cluster

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

contains() порівнює за рівністю — DataPoint визначає рівність за name та value разом, тому інший екземпляр DataPoint з тим самим ім’ям і значенням також вважається міститися.

Крок 5: Обчислити центр кластера

DataPoint.get_centroid(cluster) — це статичний метод, який усереднює кожен вимір кожного DataPoint.value у кластері та повертає результат як новий DataPoint з назвою "centroid":

from aspose_pdf import DataPoint

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

Кожен список DataPoint.value у кластері повинен мати однакову довжину — get_centroid усереднює позицію за позицією і не перевіряє, чи збігаються довжини. Виклик його на Cluster.empty() або на будь-якому кластері з count == 0 піднімає ValueError.

Крок 6: Клонувати кластер або повторно використати спільний порожній екземпляр

clone() повертає незалежний Cluster, що містить ті ж елементи; Cluster.empty() завжди повертає той самий кешований порожній екземпляр кластера замість створення нового:

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

Крок 7: Групувати кілька кластерів у ClusterCollection

ClusterCollection об’єднує кілька об’єктів Cluster за одним єдиним контейнером, що підтримує len():

from aspose_pdf import Cluster, ClusterCollection

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

ClusterCollection не надає метод для отримання своїх кластерів назад — збережіть посилання на список, який ви передаєте у конструктор, якщо потрібно потім ітерувати кластери.

Поширені проблеми та виправлення

Немає способу додати елемент до існуючого Cluster

Cluster приймає список членства лише під час створення (Cluster(items)). Спочатку сформуйте повний список об’єктів DataPoint, а потім створіть Cluster — після цього немає add() або append(), які можна викликати.

DataPoint.get_centroid() raises ValueError

Це трапляється, коли переданий кластер порожній (count == 0), включаючи Cluster.empty(). Перевірте cluster.count перед викликом get_centroid, або обробіть виключення, якщо порожній кластер є допустимим вхідним параметром у вашому робочому процесі.

Значення центроїдів виглядають неправильними

get_centroid підсумовує кожну позицію DataPoint.value по порядку і ділить на кількість точок — він не перевіряє, чи має кожен список value у кластері однакову довжину. Поєднання об’єктів DataPoint з різною розмірністю створює неправильне середнє без повідомлення про помилку, а не викликає виключення.

Expecting Cluster.empty() створити новий порожній кластер щоразу

Cluster.empty() — це одноелементний доступник — кожний виклик повертає той самий кешований екземпляр. Якщо потрібен окремий, незалежний порожній кластер, використайте Cluster() (без аргументів) замість цього.

Очікується, що бібліотека автоматично групуватиме точки

DataPoint, Cluster і ClusterCollection — це структури даних для представлення точок, кластерів та обчислення центроїда — модуль не містить функції зв’язку або відстані, яка визначає, які точки належать разом. Ваш власний код визначає належність до кластера перед створенням Cluster.

Поширені питання

Чи автоматично цей модуль групує точки даних за відстанню?

Ні. Cluster, DataPoint і ClusterCollection — це будівельні блоки для представлення вже визначених групувань та обчислення центроїда — вбудованого кроку агрегації або призначення на основі відстані немає.

У чому різниця між `Cluster()` і `Cluster.empty()`?

Cluster(items=None) створює новий екземпляр щоразу, коли його викликають. Cluster.empty() — це classmethod, який повертає той самий кешований, спільний порожній кластерний екземпляр при кожному виклику.

Чи можу я додавати елементи до `Cluster` після його створення?

Ні. Cluster надає доступ лише до contains(), clone() та властивості count поза конструктором — склад членів фіксується після виконання конструктора.

Чи працює `get_centroid()` з будь-якою кількістю вимірів?

Так, за умови, що кожен список DataPoint.value у кластері має однакову довжину. get_centroid усереднює кожен вимір окремо і повертає результат у вигляді нового DataPoint.

Що `ClusterCollection` додає понад простий список кластерів типу Python?

В основному це типізований контейнер з підтримкою len(). Він не додає ітерацію, пошук чи поведінку об’єднання понад те, що вже є у списку, з якого ви його сконструювали.