Prozess zum Aktualisieren der OCD-IDs

Einführung

Open Civic Data Identifiers (OCD-IDs) sind ein gängiges Format zur Definition politischer Regionen. Zum Erstellen eines CDF-Feeds müssen Sie diese IDs als Teil einer GpUnit-Entität angeben. In diesem Dokument finden Sie Anleitungen und Best Practices zum Hinzufügen von OCD-IDs zum GitHub-Repository „opencivicdata“.

OCD-IDs im Open Civic Data GitHub-Repository aktualisieren

Voraussetzungen

  1. Beiträge zu Open-Source-Projekten

Ein paar wichtige Hinweise vorab:

  1. Bereiten Sie Ihre Workstation vor:

    Verzweigen und klonen Sie das Paket aus dem OCD-ID-Repository.

  2. Machen Sie sich mit dem Repository vertraut:

    Im OCD-ID-Repository wird jedes unterstützte Land durch ein Verzeichnis und eine CSV-Datei mit demselben Namen dargestellt: country-<Ländercode mit 2 Buchstaben> (Beispiel: identifiers/country-de und identifiers/country-de.csv für Deutschland).

    Im Verzeichnis des Landes, das Sie ändern möchten, finden Sie die CSV-Dateien (Beispiel), die Teile der länderspezifischen CSV-Datei der obersten Ebene enthalten. Dies sind die Dateien, die Sie ändern müssen.

  3. So erstellen Sie neue OCD-IDs:

    Struktur und Quellen

    Sehen Sie sich das Dokument zu OpenCivics-Daten an, um sich mit der Struktur der OCD-IDs vertraut zu machen. Im Allgemeinen hat eine gültige OCD-ID das folgende Format: ocd-division/country:<country_code>(/<type>:<type_id>)

    Bei der Benennung von Kennungen werden Standardkennzeichnungen aus ISO oder anderen Standards wie FIPS und NUTS bevorzugt, wenn ISO nicht verfügbar ist.

    Allgemeine Richtlinien

    Im Folgenden finden Sie allgemeine Richtlinien:

    Hierarchie

    Die Hierarchie der OCD-IDs muss durch die Verwaltungsebene vorgegeben werden, über die die Grenzen der OCD-IDs gesteuert werden, nicht unbedingt die Begrenzungsbeziehung der OCD-IDs.

    • Beispiel:In den USA werden Wahlbezirke bei Wahlen des nationalen Repräsentantenhauses genutzt, ihre Grenzen werden jedoch von den USA bestimmt. Die Kongresswahlbezirke hängen also von den Bundesstaaten ab: ocd-division/country:us/state:pa/cd:2
    • Beispiel:Murrysville ist eine Gemeinde in Pennsylvania, die im Westmoreland County liegt. Da die Städte jedoch vom Bundesstaat verwaltet werden, hängt die OCD-ID vom Bundesstaat ab: ocd-division/country:us/state:pa/place:murrysville In Fällen, in denen eine Unterscheidung erforderlich ist, kann eine zusätzliche Hierarchie verwendet werden.
    • Beispiel: In Pennsylvania gibt es 16 Orte mit dem Namen "Franklin Township". Normalerweise haben beide die OCD-ID ocd-division/country:us/state:pa/place:franklin, aber das wäre mehrdeutig. Stattdessen können wir der OCD-ID den Landkreis hinzufügen, sodass jeder seine eigene eindeutige OCD-ID erhält. Beispiel: ocd-division/country:us/state:pa/county:adams/place:franklin
    Typ

    • OCD-IDs sind in der Regel länderspezifisch.

    • Einige OCD-IDs sind im gesamten Repository identisch, z. B. country, region und place.

    • Generell sollten Sie jedoch die Typen auf eine spezifischere Weise angeben, die im Kontext des jeweiligen Landes sinnvoll wäre.

      • Beispiel:Für Verwaltungsgebiet 1 in den USA werden die Typen state, district und territory verwendet.
      • Beispiel: Für Verwaltungsgebiet 1 in CA werden die Typen province und territory verwendet.
      • Beispiel:Für Verwaltungsgebiet 1 in PT werden die Typen region und autonomous_region verwendet.
    ID
    • Im Allgemeinen möchten wir für einen Bezirk bei der Wahlwiederholung dieselbe OCD-ID verwenden. Wenn Sie eine type_id für einen neuen Satz von OCD-IDs auswählen, wählen Sie diejenige aus, die am stabilsten ist. Folgende Fragen sollten Sie sich stellen, wenn Sie die zu verwendende ID ermitteln:
    • Wie wahrscheinlich ist es, dass sich die Kennzeichnung für einen bestimmten Bezirk aufgrund einer Wahlwiederholung ändert?
    • Wenn derselbe Amtsträger den Distrikt X vor und nach der Änderung der Grenzen der Wahlbezirke innehat, würde ich dann seine Amtszeit als kontinuierlich darstellen?
    • Werden Bezirke mit identischen Grenzen oder Namen über mehrere Grenzen hinweg durch dieselbe Kennzeichnung dargestellt?
      • Beispiel:In den USA werden die Nummern der Kongresswahlbezirke für US-Hausbezirke verwendet. Obwohl sich ihre Grenzen mit der Einschränkung ändern, hängt die Identität stark an der Nummer ab. Sie würden eine Person, die X Jahre lang Amt für den Sitz des N-ten Sitzes innehat, auch dann nennen, wenn diese Anzahl von Jahren Grenzen überschreitet.
      • Beispiel:In Kanada sollen Wahlbezirke verwendet werden, um Wahlbezirke darzustellen, da zwar Bundeswahlkreise vorhanden sind, diese Kennung jedoch nicht stabil ist, da identische Bezirke innerhalb der Wahlbezirke durch unterschiedliche IDs dargestellt werden. (So ist z. B. der Bezirk 47012, der vor 2012 geändert wurde, nicht mehr derselbe.)
    Neudefinition

    Wenn Sie OCD-IDs aufgrund von Einschränkungen aktualisieren, sollten Sie im Allgemeinen die vorhandenen OCD-IDs verwenden, anstatt einen neuen zu erstellen.

    • Wenn sich die Identität eines Bezirks (numerische ID, Name usw.) nach der neuen Beschränkung nicht ändert, verwenden Sie dieselbe OCD-ID.
    • Wenn Sie nach der Wahl der Grenzen neue Bezirke erstellen möchten, müssen Sie neue OCD-IDs erstellen.
    • Aktualisieren Sie für nicht mehr vorhandene Bezirke das Feld ValidThrough mit dem Datum, an dem die Änderung der Grenzen in Kraft getreten ist.
    • Wenn die ID eines Bezirks auf seinem Namen basiert und der Bezirk nach der Wahlwiederholung umbenannt wird, erstellen Sie basierend auf dem neuen Bezirksnamen eine neue ID und fügen Sie einen Alias mit id = oldId und sameAs = newId hinzu. Dadurch wird die newId kanonisiert, da die Verwendung von oldId der newId zugeordnet wird.
    • Falls es einen Konflikt zwischen alten OCD-IDs gibt, z. B. wenn eine neue ID mit einer abgeschafften ID identisch ist, hängen Sie das Jahr ValidFrom an die neue ID an. Weitere Informationen zu dieser Benennungsrichtlinie finden Sie unter Neue Dateien für aktuelle, abgeschaffte und umbenannte OCD-IDs erstellen.

Lokale Kopie aktualisieren

Jede Aktualisierung muss im landesspezifischen Verzeichnis ocd-repository/identifiers/country-<Ländercode mit 2 Buchstaben> erfolgen. Wenn kein länderspezifisches Verzeichnis vorhanden ist, erstellen Sie es.

  • Wenn die CSV-Datei mit den OCD-IDs bereits vorhanden ist und alte Wahlgrenzen darstellt, müssen Sie diese Datei aktualisieren, um die neuen Wahlkreise aufzunehmen. Fügen Sie dazu eine ValidFrom- und eine ValidTo-Spalte hinzu, die das Datum im Format JJJJ-MM-TT enthält.
    • ValidFrom sollte das Wahldatum für neue Wahlkreise sein. Für bereits bestehende Wählerschaften kann das Feld leer gelassen werden.
    • ValidTo für veraltete Wahlkreise muss der Tag vor der Wahl sein.

Aliasse aktualisieren

Aliasing kann verwendet werden, um OCD-IDs als Darstellung derselben politischen Geografie zu kennzeichnen.

  • Wenn ein Ort beispielsweise eine Stadt und ein Landkreis ist, könnte dies Sinn ergeben.

Die allgemeinen Prinzipien, die wir verbreiten möchten:

  • Wenn zwei politische Geografien koterminiert sind, sollten sie nicht unbedingt aufeinander abgestimmt sein. Ein Beispiel: Der große US-Kongress ist mit den Bundesstaaten zusammen, aber dies liegt an der aktuellen Bevölkerungszahl in den USA.

Aliasing kann auch sinnvoll sein, wenn wesentliche Änderungen in Bezug auf Gesetze oder verfassungsmäßige Änderungen erforderlich sind, um Bezirke aufzuteilen.

  • Zum Beispiel sind der Senat und die Wahlbezirke von Washington durch das Verfassungsrecht identisch.

Fügen Sie bei Bedarf die CSV-Datei aliases.csv hinzu, in die wir sowohl die alten OCD-IDs als auch ihre Aliasse einfügen. Kanonische IDs können Divisionstypen mit lokaler Bedeutung verwenden und Aliasse mit vertrauteren Darstellungen haben (z. B. kanonisch: ocd-division/country:de/land Alias: `ocd-division/country:de/state). Weitere Informationen finden Sie unter Problem 170.

So aktualisieren Sie die Datei „alias.csv“:

  • Spalten in der Datei „alias.csv“ berücksichtigen: id,sameAs,sameAsNote
Typ Beschreibung
id Diese Spalte muss die Aliasse für die OCD-IDs enthalten.
sameAs Diese Spalte muss die tatsächlichen OCD-IDs enthalten, für die wir die Aliasse hinzufügen.
sameAsNote Eine Notiz, in der beschrieben wird, wie oder warum die Abteilung mehrere Kennungen hat.

Beispiel:identifiers/country-in/aliases.csv

Führen Sie das Skript compile.py aus.

Führen Sie das Python-Skript unter opencivicdata/ocd-division-ids/scripts aus:

  • Sie müssen den aus zwei Buchstaben bestehenden Ländercode als Argument für das Skript angeben, damit es weiß, welche Länderkennungen aktualisiert werden müssen.
  • Beispiel: python3scripts/compile.py in (zum Aktualisieren der OCD-IDs von Wahlkreisen in Indien).
  • Python 2.x wird nicht unterstützt. Sie müssen Python 3 oder höher verwenden. Die neueste Version von Python 3 können Sie hier herunterladen.

Das Skript entnimmt Daten aus den CSV-Dateien, die im vorherigen Schritt aktualisiert wurden (ocd-division-ids/identifiers/country-in/*.csv), validiert die Werte in den Dateien, prüft auf Datenfehler (Verwendung von Sonderzeichen usw.) oder Datenduplikate und schreibt die neuen OCD-IDs in die Länder-CSV-Datei der obersten Ebene.

Das Skript gibt Fehler- und Warnmeldungen aus, wenn Probleme in den aktualisierten CSV-Dateien auftreten. Beheben Sie die Probleme und führen Sie das Skript noch einmal aus.

Readme-Datei hinzufügen

Wenn Sie ein neues Land oder eine neue Abdeckung hinzufügen (z. B. hatten wir bisher nur eine OCD-ID für das Land, jetzt fügen wir aber die ersten Verwaltungsbezirke hinzu), fügen Sie eine README.md-Datei hinzu oder aktualisieren Sie sie. Diese Datei muss eine kurze Darstellung der politischen Region enthalten, darunter:

  • Die zu verwendenden Typen und ihre Rollen (z. B. „districts sind die oberste Verwaltungsebene in diesem Land“)
  • Die Beziehungen zwischen den Typen (z. B. „Legislativenwahlen werden auf Bezirksbasis zugewiesen und überschreiten nicht die Bezirksgrenzen“).
  • allen wichtigen Ausnahmen (z. B. „Es gibt einen Gesetzgebungsbezirk, der alle Staatsbürger im Ausland abdecken“); und
  • Links zu nützlichen Wikipedia-Seiten, um für Rezensenten oder Nutzer Kontext bereitzustellen

Pull-Anfrage erstellen

Gehen Sie wie folgt vor, um eine Pull-Anfrage zu erstellen:

  • Sobald dieser Vorgang ohne Fehler abgeschlossen ist, prüfen Sie die neu geschriebene Top-Level-Ländercode mit <2 Buchstaben-Ländercode>.csv-Datei, um sicherzustellen, dass sie jetzt den aktualisierten/neuen Satz von OCD-IDs enthält.
  • Pull-Anfrage erstellen und Prüfer hinzufügen Diese Pull-Anfrage muss Änderungen an allen folgenden CSV-Dateien enthalten.
  • Die CSV-Dateien im länderspezifischen Verzeichnis. Beispiel
  • Die CSV-Datei mit dem Ländercode der obersten Ebene mit <zwei Buchstaben des Ländercodes>. Beispiel
  • Wenn die Pull-Anfrage von zwei Committern des Landes geprüft und genehmigt wird, wird sie von einem der Inhaber/Mitbearbeiter des Pakets zusammengeführt.