תהליך לעדכון מזהי OCD

מבוא

מזהי נתונים אזרחיים פתוחים (Open Civic Data Identifies) הם פורמט משותף של מזהים שמגדירים אזורים גיאוגרפיים פוליטיים. כדי ליצור פיד CDF, צריך לספק את המזהים האלה כחלק מישות של GpUnit. מטרת המסמך הזה היא לספק הנחיות ושיטות מומלצות להוספת מזהי OCD למאגר Opencivicdata של GitHub.

איך מעדכנים מזהי OCD במאגר הנתונים Open Civic Data של GitHub

דרישות מוקדמות

  1. איך תורמים לפרויקט קוד פתוח

לפני שמתחילים:

  1. מכינים את תחנת העבודה:

    מפצלים ומשכפלים את החבילה ממאגר מזהי OCD.

  2. מכירים את המאגר:

    במאגר מזהי OCD, כל מדינה נתמכת מיוצגת באמצעות ספרייה וקובץ CSV עם שם זהה: country-<2 אותיות של קוד מדינה> (לדוגמה: identifiers/country-de ו-identifiers/country-de.csv לגרמניה).

    בתוך הספרייה של המדינה שרוצים לשנות אפשר למצוא את קובצי ה-CSV (Example) שכוללים חלקים מקובץ ה-CSV ברמה העליונה, ספציפי למדינה. אלה הקבצים שאתם צריכים לשנות.

  3. איך יוצרים מזהי OCD חדשים:

    מבנה ומקורות נתונים

    כדי להכיר את המבנה של מזהה ה-OCD, מומלץ לעיין במסמך הפתוח בנושא נתונים אזרחיים. באופן כללי, מזהה תקין של OCD הוא בפורמט הבא: ocd-division/country:<country_code>(/<type>:<type_id>)

    מתן עדיפות לשמות מזהים לפי תקן ISO או לפי תקנים אחרים, כמו FIPS ו-NUTS, אם אין להם תקן ISO.

    מדיניות כללית

    אלה כללי המדיניות:

    היררכיה

    היררכיית מזהי OCD חייבת להכתיב את רמת הניהול ששולטת בגבולות של מזהי ה-OCD, ולא בהכרח את קשרי הבלימה של מזהי ה-OCD.

    • לדוגמה: בארצות הברית, מחוזות קונגרס משמשים בבחירות לבית הנבחרים הלאומי, אבל הגבולות שלהם נקבעים על ידי ארצות הברית. לכן, מחוזות הקונגרס מבלים את המדינות הבאות: ocd-division/country:us/state:pa/cd:2
    • דוגמה: מוריסוויל היא רשות מקומית בפנסילבניה והיא נמצאת במחוז ווסטמורלנד. עם זאת, הערים מנוהלות על ידי המדינה, כך שמזהה ה-OCD תלוי במדינה: ocd-division/country:us/state:pa/place:murrysville במקרים שבהם נדרשת הבהרה, אפשר להשתמש בהיררכיה נוספת.
    • לדוגמה: יש 16 מקומות בפנסילבניה בשם 'עיריית פרנקלין'. בדרך כלל לכל אחד מהם יהיה מזהה OCD ocd-division/country:us/state:pa/place:franklin, אבל זה יהיה לא ברור. במקום זאת, אנחנו יכולים להוסיף את המדינה למזהה ה-OCD כך שכל אחד מהם יקבל מזהה OCD ייחודי. לדוגמה: ocd-division/country:us/state:pa/county:adams/place:franklin
    תיאור

    • סוגי מזהי OCD הם בדרך כלל ספציפיים למדינות.

    • מזהי OCD מסוימים נפוצים במאגר, למשל country, region ו-place.

    • עם זאת, ההנחיה הכללית היא לציין את הסוגים באופן ספציפי יותר, שנראה הגיוני בהקשר של אותה מדינה.

      • לדוגמה: ב-Admin Area 1 בארה"ב, נעשה שימוש בסוגים state, district ו-territory.
      • דוגמה: עבור אזור ניהול 1 ב-CA, נעשה שימוש מהסוגים province ו-territory.
      • דוגמה: עבור אזור ניהול 1 ב-PT, נעשה שימוש בסוגים region ו-autonomous_region.
    מזהה
    • באופן כללי, אנחנו רוצים להשתמש באותו מזהה OCD למחוז בכל שינוי מחוזות. כשבוחרים type_id לשימוש עבור קבוצה חדשה של מזהי OCD, יש לבחור את המזהה היציב ביותר. אלה כמה מהשאלות שצריך לשאול כדי להחליט באיזה מזהה להשתמש:
    • מה הסבירות שהמזהה של מחוז נתון ישתנה כתוצאה משינוי המחוזות?
    • אם אותו בעל תפקיד בכיר מכהן במחוז X לפני ואחרי שהגבולות שלו השתנו משינוי המחוזות, האם תקופת ההסכם תיושם כ'רצופה'?
    • האם מחוזות בעלי גבולות או שמות זהים במחוזות שונים מיוצגים על ידי אותו מזהה?
      • לדוגמה: בארה"ב משתמשים במספרים של מחוזות קונגרס בארה"ב עבור מחוזות מגורים בארה"ב, מפני שלמרות שהגבולות שלהם משתנים על ידי שינוי המחוזות, הזהות שלהם מצורפת באופן הדוק למספר הזה. כמו כן, צריך להתייחס לאדם כאל מכהן בתפקידו במושב ה-N למשך X שנים, גם אם מספר השנים הזה חוצה גבולות של מחוזות מחדש.
      • דוגמה: בקנדה אנחנו רוצים להשתמש בשמות מחוזות כדי לייצג מחוזות בחירות פדרליים. הסיבה לכך היא שקיימים קודי בחירות פדרליים, אך המזהה אינו יציב מפני שמחוזות זהים שמשנים את המחוז מיוצגים במזהים שונים. (למשל במחוז 47012 לפני 2012, שינוי המחוז כבר לא זהה למחוז אחרי 2012).
    שינוי בהגדרת המחוזות

    בדרך כלל, כשמעדכנים מזהי OCD עקב שינוי בהגדרת המחוזות, צריך להשתמש בקבוצה של מזהי ה-OCD הקיימים, ולא ליצור קבוצה חדשה.

    • אם הזהות של מחוז (מזהה מספרי, שם וכו') לא משתנה אחרי השינוי של המחוזות, צריך להשתמש באותו מזהה OCD.
    • כדי ליצור מחוזות חדשים אחרי שינוי המחוזות, צריך ליצור מזהי OCD חדשים.
    • במחוזות שכבר לא קיימים, מעדכנים בשדה ValidThrough את התאריך שבו נכנס לתוקף השינוי בהגדרת המחוזות.
    • אם המזהה של המחוז מבוסס על השם שלו, והשם של המחוז משתנה אחרי השינוי, צריך ליצור מזהה חדש על סמך השם החדש של המחוז ולהוסיף כינוי שבו id = oldId ו-sameAs = newId. הפעולה הזו הופכת את newId לקנוני כשימוש במפות oldId ל-newId.
    • במקרים שבהם יש התנגשות בין מזהי OCD היסטוריים, למשל מזהה חדש שזהה למזהה שבוטל, צריך לצרף את השנה ה-ValidFrom למזהה החדש. מידע נוסף על המדיניות הזו בנושא שמות זמין במאמר יצירת קבצים חדשים למזהי OCD-ID קיימים, שבוטלו ושויכו לשמות אחרים.

עדכון העותק המקומי

צריך לבצע את העדכון בספרייה הספציפית של המדינה: ocd-repository/identifiers/country-<2 אותיות של קוד מדינה>. אם לא קיים קוד מדינה, יוצרים אותו.

  • אם קובץ ה-CSV עם מזהי ה-OCD כבר קיים, והם מייצגים גבולות בחירות ישנים, צריך לעדכן את הקובץ הזה כך שיכלול את אזורי הבוחרים החדשים. כדי לעשות את זה, צריך להוסיף עמודת ValidFrom ועמודה ValidTo שמכילות את התאריך בפורמט YYYY-MM-DD.
    • ValidFrom צריך להיות תאריך הבחירות למחוזות בחירה חדשים. אפשר להשאיר את השדה ריק עבור מחוזות שכבר קיימים.
    • ValidTo למחוזות בחירה מיושנים חייב להיות יום לפני הבחירות.

עדכון כינויים

אפשר להשתמש בכינוי כדי לסמן מזהי OCD כייצוג של אותה גיאוגרפיה פוליטית.

  • לדוגמה, אם המקום הוא גם עיר וגם מחוז, זה יכול להיות הגיוני.

העקרונות הכלליים שאנחנו מנסים ליישם:

  • אם שני חלקים של גיאוגרפיה פוליטית זהים, אין צורך ליצור כינוי ביניהם. לדוגמה: הקונגרס האמריקני הגדול פועל במשותף עם מדינות, אבל הוא מקרי עקב מספר האוכלוסין הנוכחי בארה"ב.

הוספת כינוי גם יכולה להיות הגיונית במקרים שבהם יידרשו שינויים משמעותיים בחוקים או בתיקונים חוקתיים כדי לפצל את המחוזות.

  • לדוגמה, הסנאט של מדינת וושינגטון ומחוזות בתי המדינה מוגדרים כאותו חוקה.

אם צריך, מוסיפים קובץ CSV בשם aliases.csv שבו מוסיפים את מזהי ה-OCD הישנים ואת הכינויים שלהם. מזהים קנוניים יכולים להשתמש בסוגי חלוקות שיש להם משמעות מקומית ויכולים להיות להם כינויים עם ייצוגים מוכרים יותר (לדוגמה, כינוי קנוני: ocd-division/country:de/land: 'ocd-division/country:de/state). למידע נוסף, עיינו בבעיה מס' 170.

כדי לעדכן את הקובץ domains.csv:

  • יש להקפיד על סדר העמודות בקובץ החלופי: id,sameAs,sameAsNote
תיאור התיאור
id לעמודה הזו חייבות להיות הכינויים למזהי ה-OCD.
sameAs לעמודה הזו חייבים להיות מזהי ה-OCD בפועל, שעבורם אנחנו מוסיפים את הכינויים.
sameAsNote הערה שבה מוסבר איך ולמה יש כמה מזהים של חלוקה זו.

לדוגמה: identifiers/country-in/aliases.csv

מריצים את הסקריפט - compile.py

מריצים את סקריפט python במיקום opencivicdata/ocd-division-id/scripts:

  • צריך לציין את קוד המדינה בן 2 האותיות כארגומנט לסקריפט, כדי שהוא ידע איזו מדינה צריך לעדכן.
  • דוגמה: python3 חיבורי/החברות בו - (לעדכון מזהי OCD של מחוזות בחירה בהודו).
  • Python 2.x לא מקבל תמיכה. צריכים להשתמש ב-Python 3 ואילך. כאן אפשר להוריד את הגרסה העדכנית של Python 3.

הסקריפט לוקח נתונים מקובצי ה-CSV שעודכנו בשלב הקודם (ocd-division-id/identifiers/country-in/*.csv), מאמת את הערכים בקבצים, בודק אם יש שגיאות בנתונים (שימוש בתווים מיוחדים וכו') או בכפילויות בנתונים, וכותב את מזהי ה-OCD החדשים בקובץ ה-CSV של המדינה ברמה העליונה.

הסקריפט יוצר הודעות שגיאה ואזהרה אם מתעוררות בעיות כלשהן בקובצי ה-CSV המעודכנים. צריך לפתור את הבעיות ולהריץ את הסקריפט שוב.

הוספת קובץ Readme

כשמוסיפים מדינה חדשה או רמת כיסוי חדשה (לדוגמה, כשבעבר היה לנו רק מזהה OCD למדינה, אבל עכשיו אנחנו מוסיפים את המחוזות המנהליים ברמה הראשונה), מוסיפים או מעדכנים קובץ README.md. הקובץ חייב לכלול מתווה קצר של המיקום הפוליטי, כולל:

  • הסוגים שבהם נשתמש והתפקידים שלהם (כמו "districts הם האזור המנהלי ברמה הראשונה במדינה הזו");
  • היחסים בין הסוגים (למשל "מחוזות מחוקקים מוקצים על בסיס כל מחוז ולא חוצים גבולות של מחוזות");
  • מקרים חריגים בולטים (כמו "יש מחוז מחוקקים אחד שחל על כל האזרחים בחוץ"), וכן
  • קישורים לדפי ויקיפדיה שימושיים שיעזרו לספק הקשר למבקר או למשתמש.

יצירה של בקשת משיכה

כדי ליצור בקשת משיכה, יש לפעול לפי ההנחיות הבאות:

  • כשהתהליך יסתיים ללא שגיאות, מומלץ לבדוק את קובץ ה-CSV החדש של המדינה ברמה העליונה <2 letter_country code>.csv כדי לוודא שעכשיו הוא כולל את הקבוצה המעודכנת/החדשה של מזהי OCD.
  • צריך ליצור בקשת משיכה ולהוסיף בודקים. בקשת המשיכה הזו חייבת לכלול שינויים שבוצעו בכל קובצי ה-CSV הבאים.
  • קובצי ה-CSV בספרייה הספציפית למדינה. דוגמה
  • מדינה ברמה העליונה-<קובץ csv. קוד מדינה בן 2 אותיות>. דוגמה
  • כששניים מהגורמים המעורבים במדינה בודקים ומאושרים את בקשת השליפה, היא ממוזגת על ידי אחד מהבעלים או שותפי העריכה של החבילה.