כיצד לעבוד עם Clustering ב-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 של מספרים צפים — הקואורדינטות או וקטור המאפיינים שאתה מחליט שהם משמעותיים עבור הלוגיקה של הקיבוץ שלך:

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 שמחזירה את אותה מופע של empty-cluster ריק המשותף במטמון בכל קריאה.

האם אפשר להוסיף פריטים ל-`Cluster` לאחר יצירתו?

לא. Cluster חושף רק את contains(), clone(), ואת המאפיין count מעבר לבנייה — החברות קבועה כאשר הקונסטרקטור מתבצע.

האם `get_centroid()` עובד עם כל מספר של ממדים?

כן, כל עוד כל רשימת DataPoint.value באשכול בעלת אותו אורך. get_centroid ממוצעת כל ממד באופן עצמאי ומחזירה את התוצאה כ-DataPoint חדש.

מה מוסיף `ClusterCollection` מעבר לרשימת Python רגילה של אשכולות?

בעיקר מכולה טיפוסית עם תמיכת len(). היא לא מוסיפה iteration, lookup, או merging behavior מעבר למה שכבר יש ברשימה שממנה נוצרה.