چگونه با خوشه‌بندی در Python کار کنیم

Aspose.PDF FOSS برای Python یک ابزار کوچک و عمومی خوشه‌بندی تجمعی سلسله‌مراتبی را باندل می‌کند — مستقل از هر عملیات تک PDF — برای گروه‌بندی اشیای مرتبط DataPoint به نمونه‌های Cluster و محاسبه مرکز خوشه. شما تعیین می‌کنید هر نقطه داده چه چیزی را نشان می‌دهد و مختصات آن را خودتان فراهم می‌کنید؛ این ابزار به‌صورت خودکار آن‌ها را پر نمی‌کند. کتابخانه با فرمان زیر نصب می‌شود.

راهنمای گام به گام

گام ۱: نصب بسته

نصب بسته 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.")

مرحله ۲: وارد کردن کلاس‌های مورد نیاز

سه کلاس که ابزار خوشه‌بندی را تشکیل می‌دهند را وارد کنید:

from aspose_pdf import Cluster, ClusterCollection, DataPoint

مرحله ۳: ایجاد نقاط داده

یک 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 وابسته نمی‌کند — مختصات صفحه، معیارهای قلم، یا هر بردار ویژگی عددی دیگر همگی به‌طور مساوی کار می‌کنند.

مرحله ۴: گروه‌بندی نقاط داده در یک خوشه

لیست کامل اعضا را به سازندهٔ 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(). قبل از فراخوانی 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() است. این موارد رفتارهای تکرار، جستجو یا ترکیب را فراتر از آنچه در لیستی که از آن ساخته‌اید، اضافه نمی‌کند.