Proces aktualizowania identyfikatorów OCD

Wstęp

Identyfikatory OCD (Open Civic Data Identifier – OCD) to popularny format identyfikatorów określający położenie geograficzne polityczne. Aby utworzyć kanał CDF, musisz podać te identyfikatory w ramach encji GpUnit. Ten dokument zawiera wskazówki i sprawdzone metody dotyczące dodawania identyfikatorów OCD do repozytorium opencivicdata Github.

Jak aktualizować identyfikatory OCD w repozytorium Open Civic Data na GitHubie

Wymagania wstępne

  1. Dowiedz się, jak brać udział w projekcie open source

Zanim zaczniesz:

  1. Przygotuj stację roboczą:

    Utwórz rozwidlenia i skopiuj pakiet z repozytorium identyfikatora OCD.

  2. Zapoznaj się z repozytorium:

    W repozytorium z identyfikatorami OCD każdy obsługiwany kraj jest reprezentowany przez katalog oraz plik CSV o tej samej nazwie: kraj-<2-literowy kod kraju> (np. identifiers/country-de i identifiers/country-de.csv w przypadku Niemiec).

    W katalogu kraju, który chcesz zmienić, znajdź pliki CSV (przykład) zawierające części pliku CSV najwyższego poziomu dla danego kraju. Są to pliki, które musisz zmodyfikować.

  3. Jak tworzyć nowe identyfikatory OCD:

    Struktura i źródła

    Zapoznaj się z otwartym dokumentem dotyczącym danych obywatelskich, aby poznać strukturę identyfikatora OCD. Ogólnie prawidłowy identyfikator OCD ma taki format: ocd-division/country:<country_code>(/<type>:<type_id>)

    Jeśli standard ISO jest niedostępny, w przypadku nazewnictwa identyfikatorów preferowane są standardowe identyfikatory z ISO lub inne standardy, takie jak FIPS i NUTS.

    Zasady ogólne

    Oto ogólne zasady:

    Hierarchia

    Hierarchia identyfikatorów OCD musi dyktować poziom administracyjny, który kontroluje granice identyfikatorów OCD, a niekoniecznie relacji izolacji identyfikatorów OCD.

    • Przykład: w Stanach Zjednoczonych okręgi wyborcze używane są w wyborach do Narodowej Izby Reprezentantów, ale ich granice są określane przez Stany Zjednoczone. Zatem okręgi kongresowe są kojarzone z stanami: ocd-division/country:us/state:pa/cd:2
    • Przykład: Murrysville to gmina w Pensylwanii i znajduje się w hrabstwie Westmoreland. Miasta są jednak administrowane przez stan, więc identyfikator OCD nie jest powiązany ze stanem: ocd-division/country:us/state:pa/place:murrysville W sytuacjach, gdy potrzebne jest ujednoznacznienie, może być stosowana dodatkowa hierarchia.
    • Przykład: w Pensylwanii jest 16 miejsc o nazwie „Franklin”. Normalnie każdy z nich miałby identyfikator OCD ocd-division/country:us/state:pa/place:franklin, ale byłby to niejednoznaczny. Zamiast tego możemy dodać hrabstwo do identyfikatora OCD, aby każdy miał unikalny identyfikator. Np. ocd-division/country:us/state:pa/county:adams/place:franklin
    Typ

    • Typy identyfikatorów OCD są zwykle specyficzne dla poszczególnych krajów.

    • Niektóre identyfikatory OCD są wspólne w całym repozytorium, np. country, region i place.

    • Ogólna wskazówka to jednak błędnie sprecyzować typy treści w konkretny sposób, który miałby sens w kontekście danego kraju.

      • Przykład: w przypadku obszaru administracyjnego 1 w Stanach Zjednoczonych używane są typy state, district i territory.
      • Przykład: w przypadku obszaru administracyjnego 1 w CA używane są typy province i territory.
      • Przykład: w przypadku obszaru administracyjnego 1 w regionie PT używane są typy region i autonomous_region.
    Identyfikator
    • Ogólnie chcemy używać tego samego identyfikatora OCD dla danego okręgu w przypadku zmiany okręgów. Wybierając type_id do użycia z nowym zestawem identyfikatorów OCD, wybierz najbardziej stabilny. Oto niektóre pytania, jakie należy sobie zadać przy wyborze identyfikatora:
    • Jakie jest prawdopodobieństwo, że identyfikator danego okręgu zmieni się z powodu zmiany granic?
    • Czy jeśli ten sam urzędnik sprawujący urząd X przed zmianą granic regionu i po zmianie jego granic X uległ zmianie, czy mogę przedstawić jego stan jako ciągły?
    • Czy okręgi z identycznymi granicami lub nazwami objętymi zmianą granic są reprezentowane przez ten sam identyfikator?
      • Przykład: w Stanach Zjednoczonych numery okręgów kongresowych są używane w przypadku okręgów wyborczych w Stanach Zjednoczonych, ponieważ mimo wprowadzenia ograniczeń określających ich granice, tożsamość jest silnie powiązana z liczbą i osoba będzie uznawana za osobę sprawującą urząd N-tego okręgu przez X lat, nawet jeśli ta liczba lat przekracza granice granic okręgów.
      • Przykład: w Kanadzie nazw okręgów wyborczych używamy do reprezentowania federalnych okręgów wyborczych, ponieważ chociaż istnieją federalne kody wyborcze, identyfikator ten nie jest stabilny, ponieważ identyczne okręgi wyborcze w ramach zmiany okręgów są reprezentowane za pomocą różnych identyfikatorów. (np. okręg 47012 przed zmianą granic regionu w 2012 r. to nie to samo co okręg).
    Zwiększenie okręgów

    Ogólnie rzecz biorąc, gdy aktualizujesz identyfikatory OCD ze względu na zmianę ograniczeń, zamiast tworzyć nowy zbiór, użyj istniejącego zbioru identyfikatorów OCD.

    • Jeśli tożsamość okręgu (identyfikator numeryczny, nazwa itp.) nie ulegnie zmianie po zmianie granic okręgów, użyj tego samego identyfikatora OCD.
    • Aby utworzyć nowe okręgi po zmianie granic okręgów, utwórz nowe identyfikatory OCD.
    • W przypadku okręgów, które już nie istnieją, zaktualizuj pole ValidThrough, podając datę wejścia w życie zmiany granic.
    • Jeśli identyfikator okręgu pochodzi z jego nazwy, a po zmianie okręgów nazwa została zmieniona, utwórz nowy identyfikator na podstawie nowej nazwy okręgu i dodaj alias w miejscu id = oldId i sameAs = newId. Spowoduje to przypisanie parametru newId do postaci kanonicznej jako użycie map oldId na newId.
    • W przypadku kolizji między historycznymi identyfikatorami OCD, np. gdy nowy identyfikator jest taki sam jak ze zniesionym identyfikatorem, do nowego identyfikatora dołącz rok ValidFrom. Więcej informacji o tych zasadach dotyczących nazewnictwa znajdziesz w artykule na temat tworzenia nowych plików dla obecnych, zniesionych i zmienionych identyfikatorów OCD-ID.

Aktualizowanie kopii lokalnej

Każda aktualizacja musi być przeprowadzona w katalogu dla danego kraju: ocd-repository/identifiers/country-<2-literowy kod kraju>. Jeśli taki kod nie istnieje, utwórz go.

  • Jeśli plik CSV z identyfikatorami OCD już istnieje i reprezentują one stare granice wyborcze, musisz go zaktualizować, aby zawierał nowe okręgi wyborcze. W tym celu dodaj kolumny ValidFrom i ValidTo z datą w formacie RRRR-MM-DD.
    • W przypadku nowych okręgów wyborczych należy podać datę ValidFrom. W przypadku istniejących okręgów wyborczych tę datę można pozostawić pustą.
    • ValidTo w przypadku nieaktualnych okręgów wyborczych musi przypadać na dzień przed wyborami.

Aktualizowanie aliasów

Za pomocą aliasów można oznaczać identyfikatory OCD jako reprezentujących ten sam fragment geografii politycznej.

  • Takie rozwiązanie może mieć sens na przykład w sytuacji, gdy dane miejsce jest zarówno miastem, jak i powiatem.

Ogólne zasady, którymi staramy się dążyć:

  • Jeśli dwa rodzaje geografii politycznej są zbieżne, nie należy ich utożsamiać z aliasami. Np. duży ruch kongresowy USA jest pokrywany ze stanami, ale to przypadek, ze względu na obecną liczbę ludności amerykańskiej.

Pseudonim może też mieć sens w przypadkach, gdy do podziału okręgów konieczne byłyby znaczne zmiany w przepisach lub konstytucjach.

  • Na przykład okręgi wyborcze do senatu w stanie Waszyngton i okręgów stanowych według prawa konstytucyjnego są określone tak samo.

W razie potrzeby dodaj plik CSV aliases.csv, w którym dodajemy zarówno stare identyfikatory OCD, jak i ich aliasy. Identyfikatory kanoniczne mogą używać typów podziałów mających znaczenie lokalne i mieć aliasy z bardziej znanymi reprezentacjami (np. kanoniczny: ocd-division/country:de/land alias: `ocd-division/country:de/state). Więcej informacji znajdziesz w numerze nr 170.

Aby zaktualizować plik aliasy.csv:

  • Przestrzegaj kolejności kolumn w pliku aliasy.csv: id,sameAs,sameAsNote
Typ Opis
id Ta kolumna musi mieć aliasy identyfikatorów OCD.
sameAs Ta kolumna musi zawierać rzeczywiste identyfikatory OCD, do których dodajesz aliasy.
sameAsNote Informacja wyjaśniająca, w jaki sposób i dlaczego podział ma kilka identyfikatorów.

Przykład: identifiers/country-in/aliases.csv

Uruchomienie skryptu – compile.py.

Uruchom skrypt Pythona w lokalizacji opencivicdata/ocd-division-ids/scripts:

  • Musisz podać 2-literowy kod kraju jako argument w skrypcie, aby wiedział, które identyfikatory kraju wymagają aktualizacji.
  • Przykład: skrypty python3/kompilowane w pliku (do aktualizowania identyfikatorów OCD stanów w Indiach).
  • Obsługa języka Python 2.x nie jest obsługiwana. Musisz użyć Pythona w wersji 3 lub nowszej. Najnowszą wersję Pythona 3 możesz pobrać stąd.

Skrypt pobiera dane z plików CSV zaktualizowanych w poprzednim kroku (ocd-division-ids/identifiers/country-in/*.csv), sprawdza wartości w plikach, sprawdza, czy nie ma w nich błędów (np. użycie znaków specjalnych) lub nie powielonych danych, i zapisuje nowe identyfikatory OCD w pliku CSV kraju najwyższego poziomu.

Skrypt generuje komunikaty o błędach i ostrzeżenia, jeśli pojawią się problemy w zaktualizowanych plikach CSV. Rozwiąż problemy i uruchom skrypt ponownie.

Dodaj plik Readme

Gdy dodasz nowy kraj lub nowy poziom zasięgu (np. wcześniej mieliśmy tylko identyfikator OCD dla tego kraju, a teraz dodajemy okręgi administracyjne pierwszego poziomu), dodaj lub zaktualizuj plik README.md. Plik musi zawierać krótki zarys geografii politycznej, w tym:

  • Typy, których użyjemy, i ich role (np. „districts to region administracyjny pierwszego poziomu w tym kraju”);
  • Relacje między typami (np. „okręgi prawne są przypisywane na poziomie rejonu i nie przekraczają jego granic”);
  • wszelkie istotne wyjątki (np. „istnieje jeden okręg ustawodawczy, który obejmuje wszystkich obywateli zagranicznych”) oraz
  • Linki do przydatnych stron w Wikipedii, które mogą zapewnić kontekst dla recenzentów lub użytkowników.

Tworzenie żądania pull

Aby utworzyć żądanie pull, skorzystaj z tych wskazówek:

  • Gdy proces zostanie ukończony bez błędów, sprawdź nowo zapisany plik CSV najwyższego poziomu z <2-literowym kodem kraju>, aby upewnić się, że zawiera on zaktualizowany/nowy zestaw identyfikatorów OCD.
  • Utwórz żądanie pull i dodaj weryfikatorów. To żądanie pull musi zawierać zmiany wprowadzone we wszystkich poniższych plikach CSV.
  • Pliki CSV w katalogu dla poszczególnych krajów. Przykład
  • Plik CSV najwyższego poziomu zawierający <2-literowy kod kraju>. Przykład
  • Po sprawdzeniu i zatwierdzeniu wniosku przez 2 komisarzy w danym kraju prośba zostaje scalona przez jednego z właścicieli lub współpracowników pakietu.