Procedura per l'aggiornamento degli ID OCD

Introduzione

Gli ID OCD (Open Civic Data Identifier) sono un formato di identificatore comune che definisce le aree geografiche politiche. Per creare un feed CDF, devi fornire questi identificatori come parte di un'entità GpUnit. Questo documento ha lo scopo di fornire indicazioni e best practice per aggiungere ID OCD al repository GitHub Opencivicdata.

Avviso: il repository di ID OCD è pubblico. Non menzionare esplicitamente lanci o progetti imminenti nelle PR oppure nelle descrizioni o nei commenti dei problemi. Ciò è vero anche se i paesi inclusi in questo articolo sono evidenti dall'insieme di paesi per i quali stiamo generando PR o se in un determinato paese si stanno svolgendo elezioni ben pubblicizzate.

Come aggiornare gli ID OCD nel repository GitHub di Open Civic Data

Prerequisiti

1. Comprendere come contribuire a un progetto open source

Prima di iniziare:

1. Prepara la workstation:

   Crea un fork e clona il pacchetto dal repository ID ODC.

2. Familiarizza con il repository:

   Nel repository ID OCD, ogni paese supportato è rappresentato con una directory e un file CSV che ha lo stesso nome: paese-<codice paese di 2 lettere> (ad esempio: identifiers/country-de e identifiers/country-de.csv per la Germania).

   Nota: i file CSV non devono essere aggiornati direttamente utilizzando una modifica manuale. Utilizza invece le istruzioni riportate di seguito.

   Nella directory del paese da modificare puoi trovare i file CSV (Esempio) che includono parti del file CSV specifico per il paese di primo livello. Questi sono i file che devi modificare.

3. Come creare nuovi ID OCD:

   Struttura e origini

   Dai un'occhiata al documento aperto sui dati relativi all'educazione civica per acquisire familiarità con la struttura degli ID OCD. In generale, un ID OCD valido ha il seguente formato: ocd-division/country:<country_code>(/<type>:<type_id>)

   La denominazione degli identificatori preferisce gli identificatori standard di ISO o altri standard, come FIPS e NUTS, se ISO non è disponibile.

   Norme generali

   Di seguito sono riportate le norme generali:

   Gerarchia

   La gerarchia degli ID OCD deve determinare il livello amministrativo che controlla i limiti degli ID OCD, non necessariamente la relazione di contenimento degli ID OCD.

   • Esempio: negli Stati Uniti, i distretti congressuali vengono utilizzati nelle elezioni per la Camera dei rappresentanti nazionale, ma i loro confini sono determinati dagli Stati Uniti. I distretti congressuali si dividono con gli stati: ocd-division/country:us/state:pa/cd:2
   • Esempio: Murrysville è un comune della Pennsylvania che fa parte della contea di Westmoreland. Tuttavia, le città sono amministrate dallo stato, pertanto l'ID OCD non è associato allo stato: ocd-division/country:us/state:pa/place:murrysville La gerarchia extra può essere utilizzata nei casi in cui è necessaria una disambiguazione.
   • Esempio: ci sono 16 luoghi in Pennsylvania chiamati "Franklin Township". In genere, ognuno ha l'ID OCD ocd-division/country:us/state:pa/place:franklin, ma è ambiguo. Possiamo quindi aggiungere la contea all'ID OCD in modo che ciascuna abbia il proprio ID OCD univoco. Esempio: ocd-division/country:us/state:pa/county:adams/place:franklin

   Tipo

   • I tipi di ID OCD sono in genere specifici dei paesi.

   • Alcuni ID OCD sono comuni in tutto il repository, ad esempio country, region e place.

   • Tuttavia, le linee guida generali consigliano di specificare i tipi di dati in un modo più specifico che abbia senso nel contesto del paese.

     • Esempio: per l'area di amministrazione 1 negli Stati Uniti vengono utilizzati i tipi state, district e territory.
     • Esempio: per l'area di amministrazione 1 in CA, vengono utilizzati i tipi province e territory.
     • Esempio: per l'area amministratore 1 in PT, vengono utilizzati i tipi region e autonomous_region.

   ID

   • In generale, vogliamo utilizzare lo stesso ID OCD per un distretto nella ridefinizione dei distretti. Quando scegli un type_id da utilizzare per un nuovo insieme di ID OCD, scegli quello più stabile. Ecco alcune domande da porsi durante la determinazione dell'identificatore da utilizzare:
   • Quanto è probabile che l'identificatore di un determinato distretto cambi a causa della ridefinizione dei distretti?
   • Se lo stesso funzionario occupa il distretto X prima e dopo che i confini sono passati dalla ridefinizione dei distretti, rappresenterebbe il suo mandato come continuo?
   • I distretti con confini o nomi identici nell'ambito della ridefinizione dei distretti sono rappresentati dallo stesso identificatore?
     • Esempio: negli Stati Uniti, i numeri dei distretti congressuali vengono utilizzati per i distretti condominiali statunitensi perché, anche se i loro confini cambiano con la ridefinizione dei distretti, l'identità è strettamente legata al numero e fai riferimento a qualcuno come ricoprendo la carica per l'ennesimo seggio per X anni, anche quando questo numero di anni oltrepassa i confini della ridefinizione dei distretti.
     • Esempio: in Canada, vogliamo utilizzare i nomi dei distretti per rappresentare i distretti elettorali federali perché, sebbene esistano codici elettorali federali, questo identificatore non è stabile perché i distretti identici nella ridefinizione dei distretti sono rappresentati con ID diversi. (ad esempio, la ridefinizione dei distretti del distretto 47012 prima del 2012 non è più lo stesso dopo).

   Ridefinizione dei distretti

   In genere, quando aggiorni gli ID OCD a causa della ridefinizione dei distretti, utilizza l'insieme di ID OCD esistenti anziché crearne uno nuovo.

   • Se l'identità di un distretto (ID numerico, nome e così via) non cambia dopo la ridefinizione dei distretti, utilizza lo stesso ID OCD.
   • Per la creazione di nuovi distretti dopo la ridefinizione dei distretti, crea nuovi ID OCD.
   • Per i distretti che non esistono più, aggiorna il campo ValidThrough con la data di entrata in vigore della ridefinizione dei distretti.
   • Se l'ID di un distretto è basato sul nome e quest'ultimo viene rinominato dopo la ridefinizione dei distretti, crea un nuovo ID in base al nome del nuovo distretto e aggiungi un alias dove id = oldId e sameAs = newId. In questo modo, newId viene canonico come utilizzo di oldId mappato a newId.
   • Nel caso in cui si verifichi un conflitto tra gli ID OCD storici, ad esempio se un nuovo ID è identico a un ID eliminato, aggiungi l'anno ValidFrom al nuovo ID. Per ulteriori informazioni su questo criterio di denominazione, vedi Creare nuovi file per gli ID OCD attuali, aboliti e rinominati.

Aggiorna la tua copia locale

Qualsiasi aggiornamento deve essere eseguito nella directory specifica del paese: ocd-repository/identifiers/country-<codice paese di 2 lettere>. Se non ne esiste una, creala.

• Se il file CSV degli ID OCD esiste già e rappresenta i vecchi confini elettorali, devi aggiornare questo file in modo da includere i nuovi collegi elettorali. Per farlo, aggiungi una colonna ValidFrom e una ValidTo contenenti la data nel formato AAAA-MM-GG.
  • ValidFrom deve essere la data delle elezioni per i nuovi collegi elettorali. Può essere lasciato vuoto per i collegi elettorali già esistenti.
  • ValidTo per i collegi elettorali obsoleti deve essere il giorno prima delle elezioni.

Aggiorna alias

Gli alias possono essere utilizzati per contrassegnare gli ID OCD come rappresentazione della stessa area geografica.

• Ad esempio, se un luogo è sia una città che una contea, questo potrebbe avere senso.

I principi generali che cerchiamo di spingere:

• Se due parti della geografia politica sono paralleli, non devono essere necessariamente alias tra loro. Ad esempio, il Congresso degli Stati Uniti in generale è cotermino con gli stati, ma questo è un caso a causa dell'attuale numero di persone degli Stati Uniti.

L'aliasing può avere senso anche nel caso in cui siano necessari cambiamenti significativi nelle leggi/emendamenti costituzionali per la divisione dei distretti.

• Ad esempio, il Senato dello stato di Washington e i distretti delle case statali sono stabiliti in base alla legge costituzionale.

Se necessario, aggiungi un file CSV aliases.csv in cui vengono aggiunti i vecchi ID OCD e i relativi alias. Gli ID canonici possono utilizzare tipi di divisione che hanno un significato locale e possono avere alias con rappresentazioni più familiari (ad esempio canonico: ocd-division/country:de/land alias: "ocd-division/country:de/state). Per ulteriori informazioni, vedi il problema n. 170.

Per aggiornare il file alias.csv:

• Rispetta l'ordine delle colonne nel file alias.csv: id,sameAs,sameAsNote

Tipo	Descrizione
id	Questa colonna deve contenere gli alias degli ID OCD.
sameAs	Questa colonna deve contenere gli ID OCD effettivi per i quali vengono aggiunti gli alias.
sameAsNote	Una nota che descrive come o perché la divisione ha più identificatori.

Esempio: identifiers/country-in/aliases.csv

Esegui lo script - compile.py

Esegui lo script Python nella posizione opencivicdata/ocd-division-ids/scripts:

• Devi specificare il codice paese di due lettere come argomento dello script in modo che sappia quali identificatori del paese richiedono un aggiornamento.
• Esempio: python3 scripts/compile.py in (per l'aggiornamento degli ID OCD dei circoli in India).
• Python 2.x non riceve assistenza. Devi utilizzare Python 3 o versioni successive. Puoi scaricare la versione più recente di Python 3 qui.

Lo script recupera i dati dai file CSV aggiornati nel passaggio precedente (ocd-division-ids/identifiers/country-in/*.csv), convalida i valori nei file, verifica la presenza di eventuali errori nei dati (uso di caratteri speciali e così via) o la duplicazione dei dati e scrive i nuovi ID OCD nel file CSV del paese di primo livello.

Lo script genera messaggi di errore e di avviso se si verificano problemi nei file CSV aggiornati. Risolvi i problemi ed esegui di nuovo lo script.

Nota: lo script non rileva errori come la presenza di più spazi nel nome o il nome della circoscrizione scritto in modo errato, in quanto l'uso di spazi e lettere è valido secondo gli standard.

Aggiungi un file README

Quando aggiungi un nuovo paese o un nuovo livello di copertura (ad esempio, in precedenza avevamo solo un ID OCD per il paese, ma ora stiamo aggiungendo i distretti amministrativi di primo livello), aggiungi o aggiorna un file README.md. Questo file deve contenere un breve riepilogo della geografia politica, tra cui:

• I tipi che utilizzeremo e i relativi ruoli (ad esempio "districts è l'area amministrativa di primo livello in questo paese");
• Le relazioni tra i tipi (ad esempio "i distretti legislativi sono assegnati per distretto e non superano i confini");
• Eventuali eccezioni degne di nota (come "esiste un distretto legislativo che copra tutti i cittadini stranieri"); e
• Link a eventuali pagine di Wikipedia utili per fornire contesto a un revisore o a un utente.

Crea una richiesta di pull

Per creare una richiesta di pull, segui queste indicazioni:

• Al termine della procedura senza errori, controlla il file .csv di primo livello appena scritto con <codice paese di 2 lettere> per assicurarti che ora includa il nuovo set aggiornato/nuovo di ID OCD.
• Creare una richiesta di pull e aggiungere revisori. Questa richiesta di pull deve includere le modifiche apportate in tutti i seguenti file CSV.
• I file CSV nella directory specifica del paese. Esempio
• Il file .csv del paese di primo livello -<codice paese di 2 lettere>. Esempio
• Quando la richiesta di pull viene esaminata e approvata da due dei responsabili del paese, viene unita da uno dei proprietari/collaboratori del pacchetto.