Processus de mise à jour des ID de TOC

Introduction

Les identifiants de données municipales ouvertes (OCD) sont un format d'identifiant courant qui définit les zones géographiques politiques. Pour créer un flux CDF, vous devez fournir ces identifiants dans une entité GpUnit. L'objectif de ce document est de fournir des conseils et des bonnes pratiques pour ajouter des ID OCD au dépôt GitHub Opencivicdata.

Avertissement :Le dépôt d'ID OCD est public. Ne mentionnez pas explicitement les lancements ou projets à venir dans les relations publiques, la description des problèmes ou les commentaires. Ce principe s'applique même si les pays concernés sont évidents dans l'ensemble des pays pour lesquels nous générons des relations publiques, ou qu'une élection bien annoncée a lieu dans un pays donné.

Mettre à jour les ID OCD dans le dépôt GitHub Open Civic Data

Conditions préalables

1. Savoir comment contribuer à un projet Open Source

Avant de commencer

1. Préparez votre station de travail:

   Dupliquez et clonez le package à partir du dépôt d'ID OCC.

2. Familiarisez-vous avec le dépôt:

   Dans le dépôt d'ID OCD, chaque pays accepté est représenté par un répertoire et un fichier CSV portant le même nom : country-<code pays à deux lettres> (par exemple, identifiers/country-de et identifiers/country-de.csv pour l'Allemagne).

   Remarque :Les fichiers CSV ne doivent pas être mis à jour directement par modification manuelle. Suivez plutôt les instructions ci-dessous.

   Dans le répertoire du pays que vous souhaitez modifier, vous trouverez les fichiers CSV (exemple) qui incluent des parties du fichier CSV de premier niveau spécifique au pays. Voici les fichiers à modifier.

3. Pour créer des ID OCD, procédez comme suit:

   Structure et sources

   Consultez le document ouvert sur les données civiques pour vous familiariser avec la structure de l'ID de l'OCD. En général, les ID OCD valides utilisent le format suivant : ocd-division/country:<country_code>(/<type>:<type_id>)

   Si l'option ISO n'est pas disponible, le nommage des identifiants privilégie les identifiants standards ISO ou d'autres normes, telles que FIPS et NUTS.

   Règles générales

   Voici les règles générales:

   Hiérarchie

   La hiérarchie des identifiants OCD doit être dictée par le niveau administratif qui contrôle les limites des ID OCD, et pas nécessairement par leur relation de confinement.

   • Exemple:Aux États-Unis, les circonscriptions électorales sont utilisées lors des élections de la Chambre des représentants nationales, mais leurs frontières sont déterminées par les États. Les districts congressionnels sont donc liés aux États: ocd-division/country:us/state:pa/cd:2
   • Exemple:Murrysville est une municipalité de Pennsylvanie située dans le comté de Westmoreland. Cependant, comme les villes sont administrées par l'État, l'ID OCD se trouve hors de l'État : ocd-division/country:us/state:pa/place:murrysville Une hiérarchie supplémentaire peut être utilisée dans les cas où une distinction est nécessaire.
   • Exemple:En Pennsylvanie, il y a 16 lieux nommés "Township" de Franklin. En général, chacune d'elles aurait l'ID de TOC ocd-division/country:us/state:pa/place:franklin, mais ce serait ambigu. Nous pouvons donc ajouter le comté à l'ID OCD afin que chacun obtienne son propre ID OCD. Ex. : ocd-division/country:us/state:pa/county:adams/place:franklin

   Type

   • Les ID de TOC sont généralement spécifiques aux pays.

   • Certains ID de TOC sont communs dans le dépôt, tels que country, region et place.

   • Toutefois, il est généralement recommandé de privilégier les types de spécification d'une manière plus spécifique et pertinente dans le contexte du pays en question.

     • Exemple:Pour la zone administrative 1 aux États-Unis, les types state, district et territory sont utilisés.
     • Exemple:Pour la zone administrative 1 en Californie, les types province et territory sont utilisés.
     • Exemple:Pour la zone administrative 1 du Pacifique, les types region et autonomous_region sont utilisés.

   ID

   • En règle générale, nous voulons utiliser le même identifiant pour tous les redécoupagements d'un district. Lorsque vous choisissez une type_id à utiliser pour un nouvel ensemble d'ID de TOC, choisissez celui qui est le plus stable. Voici quelques questions à vous poser pour déterminer quel identifiant utiliser:
   • Quelle est la probabilité que l'identifiant d'un district donné change en raison d'un redécoupage ?
   • Si c'est le même représentant qui détient le district X avant et après le redécoupage de ses limites, est-ce que je le considère comme un mandat continu ?
   • Les districts dont les limites ou les noms sont identiques sont-ils représentés par le même identifiant ?
     • Exemple:Aux États-Unis, le numéro de district congressionnel est utilisé pour les circonscriptions électorales des États-Unis, car même si leurs limites changent avec le redécoupage, l'identité est étroitement liée à ce numéro, et vous pouvez désigner une personne comme occupant le poste du Nième siège pendant X ans, même si ce nombre d'années dépasse les limites du redécoupage.
     • Exemple:Au Canada, nous souhaitons utiliser des noms de district pour représenter les circonscriptions électorales fédérales. En effet, bien que les codes électoraux fédéraux existent, cet identifiant n'est pas stable, car les circonscriptions identiques dans les différents redécoupages sont représentées par des ID différents. (par exemple, le redécoupage du district 47012 avant 2012 ne correspond pas au même district après).

   Redécoupage des circonscriptions

   En règle générale, lorsque vous mettez à jour les ID de TOC en raison d'un redécoupage, utilisez l'ensemble des ID de TOC existants plutôt que d'en créer un.

   • Si l'identité d'un district (identifiant numérique, nom, etc.) ne change pas après le redécoupage, utilisez le même identifiant OCD.
   • Pour créer des districts après un redécoupage, créez des identifiants OCD.
   • Pour les districts qui n'existent plus, mettez à jour le champ ValidThrough avec la date à laquelle le redécoupage est entré en vigueur.
   • Si l'ID d'un district est basé sur son nom et qu'il est renommé après le redécoupage, créez un ID basé sur le nouveau nom du district et ajoutez un alias où id = oldId et sameAs = newId. Ainsi, le newId est canonique, car l'utilisation de oldId est mappée à newId.
   • En cas de conflit entre des ID de l'historique OCD (par exemple, si un nouvel ID est identique à un ID supprimé), ajoutez l'année ValidFrom au nouvel ID. Pour en savoir plus sur cette règle de dénomination, consultez Créer des fichiers pour les OCD-ID actuels, supprimés et renommés.

Mettre à jour votre copie locale

Toute mise à jour doit être effectuée dans le répertoire spécifique au pays : ocd-repository/identifiers/country-<code pays à deux lettres>. S'il n'en existe pas, créez-le.

• Si le fichier CSV contenant les identifiants de l'OCDE existe déjà et qu'ils représentent d'anciennes circonscriptions électorales, vous devez le mettre à jour pour y inclure les nouvelles circonscriptions. Pour ce faire, ajoutez une ValidFrom et une colonne ValidTo contenant la date au format AAAA-MM-JJ.
  • ValidFrom doit correspondre à la date des élections pour les nouvelles circonscriptions. Il peut être laissé vide pour les circonscriptions existantes.
  • Pour les circonscriptions obsolètes, le ValidTo doit être la veille de l'élection.

Mettre à jour les alias

La création d'alias permet de marquer les ID de TOC comme une représentation de la même zone géographique politique.

• Par exemple, si un lieu est à la fois une ville et un comté, cela peut avoir du sens.

Voici les principes généraux que nous essayons d'appliquer:

• Si deux éléments de géographie politique sont coïncidents, ils ne doivent pas nécessairement être associés l'un à l'autre. Par exemple, les groupes congressionnels américains au sens large coïncident avec les États, mais cela est dû au hasard en raison de la population américaine actuelle.

La création d'alias peut également être pertinente lorsque des modifications importantes des lois ou des modifications constitutionnelles devraient être nécessaires pour diviser les districts.

• Par exemple, les districts du sénat et des chambres d'État de Washington sont définis comme étant les mêmes par le droit constitutionnel.

Si nécessaire, ajoutez un fichier CSV aliases.csv dans lequel nous ajoutons les anciens ID de TOC et leurs alias. Les ID canoniques peuvent utiliser des types de division ayant une signification locale et avoir des alias avec des représentations plus familières (par exemple, l'alias canonique ocd-division/country:de/land : `ocd-division/country:de/state). Pour en savoir plus, consultez le problème n° 170.

Pour mettre à jour le fichier alias.csv:

• Respectez l'ordre des colonnes dans le fichier alias.csv: id,sameAs,sameAsNote.

Type	Description
id	Cette colonne doit contenir les alias des ID OCD.
sameAs	Cette colonne doit contenir les ID OCD pour lesquels nous ajoutons les alias.
sameAsNote	Note expliquant comment ou pourquoi la division possède plusieurs identifiants.

Exemple:identifiers/country-in/aliases.csv

Exécutez le script compile.py.

Exécutez le script Python à l'emplacement opencivicdata/ocd-division-ids/scripts:

• Vous devez spécifier le code pays à deux lettres comme argument du script pour qu'il sache quels identifiants de pays doivent être mis à jour.
• Exemple: scripts python3/compile.py dans (pour mettre à jour les ID de TOC des constantes en Inde).
• Python 2.x n'est pas pris en charge. Vous devez utiliser Python 3 ou une version ultérieure. Vous pouvez télécharger la dernière version de Python 3 ici.

Le script récupère les données des fichiers CSV mis à jour à l'étape précédente (ocd-division-ids/identifiers/country-in/*.csv), valide les valeurs des fichiers, recherche les erreurs de données (utilisation de caractères spéciaux, etc.) ou les doublons, et écrit les nouveaux ID OCD dans le fichier CSV du pays de premier niveau.

Le script génère des messages d'erreur et d'avertissement en cas de problème dans les fichiers CSV mis à jour. Résolvez les problèmes et exécutez à nouveau le script.

Remarque :Le script ne détecte pas les erreurs telles que les espaces multiples dans le nom ou le nom de circonscription mal orthographié, car l'utilisation d'espaces et de lettres est valide conformément aux normes.

Ajouter un fichier Lisez-moi

Lorsque vous ajoutez un nouveau pays ou un nouveau niveau de couverture (par exemple, nous n'avions qu'un ID de TOC pour le pays, mais nous ajoutons maintenant les districts administratifs de premier niveau), ajoutez ou mettez à jour un fichier README.md. Ce fichier doit contenir un aperçu rapide de la géographie politique, y compris:

• Les types que nous utiliserons et leurs rôles (par exemple, "districts est la région administrative de premier niveau dans ce pays")
• Relations entre les types (par exemple, "les districts législatifs sont attribués au niveau de chaque circonscription et ne traversent pas les limites des districts") ;
• toutes les exceptions notables (par exemple, "il existe une circonscription unique pour tous les citoyens étrangers") ; et
• Liens vers des pages Wikipédia utiles pour fournir du contexte à un réviseur ou à un utilisateur.

Créer une demande d'extraction

Pour créer une demande d'extraction, suivez les instructions ci-dessous:

• Une fois ce processus terminé sans erreur, vérifiez le fichier .csv de premier niveau pays-<code pays à deux lettres>.csv pour vous assurer qu'il inclut désormais le nouvel ensemble d'ID OCD mis à jour.
• Créez une demande d'extraction et ajoutez des examinateurs. Cette demande d'extraction doit inclure les modifications effectuées dans tous les fichiers CSV suivants.
• Les fichiers CSV du répertoire spécifique au pays Exemple
• Fichier .csv de premier niveau country-<code pays à deux lettres>. Exemple
• Lorsque la demande d'extraction est examinée et approuvée par deux des commits du pays, elle est fusionnée par l'un des propriétaires/collaborateurs du package.