Python에서 클러스터링을 사용하는 방법

Aspose.PDF FOSS for 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 부동소수점 리스트와 짝지어 줍니다 — 좌표 또는 특징 벡터로, 사용자가 직접 정의하는 그룹화 로직에 의미가 있는 것으로 결정합니다:

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()는 동일성(equality)으로 매치됩니다 — DataPoint은 name와 value을 함께 사용하여 동일성을 정의하므로, 이름과 값이 같은 다른 DataPoint 인스턴스도 포함된 것으로 보고됩니다.

Step 5: 클러스터 중심점 계산

DataPoint.get_centroid(cluster)는 클러스터 내 모든 DataPoint.value의 각 차원을 평균내는 정적 메서드이며, 결과를 "centroid"라는 이름의 새로운 DataPoint로 반환합니다:

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가 발생합니다.

Step 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

Step 7: 여러 클러스터를 ClusterCollection로 그룹화

ClusterCollection은 단일 len() 인식 컨테이너 뒤에 여러 Cluster 객체를 번들링합니다:

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()도 포함됩니다. get_centroid을 호출하기 전에 cluster.count를 확인하거나, 빈 클러스터가 워크플로에서 유효한 입력인 경우 예외를 처리하십시오.

중심값이 잘못된 것처럼 보입니다

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()은 클래스 메서드로, 매 호출 시 동일한 캐시된 공유 빈 클러스터 인스턴스를 반환합니다.

생성한 후에 `Cluster`에 항목을 추가할 수 있나요?

아니요. Cluster는 생성 이후에 contains(), clone(), 그리고 count 속성만 노출합니다 — 멤버십은 생성자가 실행된 후 고정됩니다.

`get_centroid()`는 차원의 수에 관계없이 작동합니까?

예, 클러스터 내의 모든 DataPoint.value 리스트가 동일한 길이를 갖는 한 가능합니다. get_centroid은 각 차원을 독립적으로 평균내어 결과를 새로운 DataPoint로 반환합니다.

`ClusterCollection`는 일반적인 Python 클러스터 리스트에 비해 무엇을 추가하나요?

주로 len() 지원이 포함된 타입 지정 컨테이너입니다. 이것은 당신이 만든 리스트에 이미 있는 것 외에 반복, 조회, 병합 동작을 추가하지 않습니다.