Proceso para actualizar los ID de OCD

Introducción

Los identificadores de datos cívicos abiertos (IDs de OCD) son un formato de identificador común que definen geografías políticas. Para crear un feed de CDF, debes proporcionar estos identificadores como parte de una entidad GpUnit. El objetivo de este documento es brindar orientación y prácticas recomendadas para agregar los IDs de TOC al repositorio de GitHub de opencivicdata.

Advertencia: El repositorio de ID de OCD es público. No menciones de forma explícita ningún lanzamiento o proyecto próximo en el área de RR.PP., ni en las descripciones de problemas o los comentarios. Esto ocurre incluso si los países que cubren son evidentes en el conjunto de países para los que generamos informes de prensa, o el hecho de que haya una elección muy publicitada en un país determinado.

Cómo actualizar los IDs de TOC en el repositorio de GitHub de datos abiertos de Civic

Requisitos previos

1. Comprende cómo contribuir a un proyecto de código abierto

Antes de comenzar:

1. Prepara tu estación de trabajo:

   Bifurca y clona el paquete desde el repositorio del ID de OCD.

2. Familiarízate con el repo:

   En el repositorio del ID de OCD, cada país admitido se representa con un directorio y un archivo CSV que comparte el mismo nombre: country-<2 letter country code> (por ejemplo, identifiers/country-de y identifiers/country-de.csv para Alemania).

   Nota: Los archivos CSV no se deben actualizar directamente mediante una edición manual. En su lugar, usa las siguientes instrucciones.

   Dentro del directorio del país que deseas modificar, puedes encontrar los archivos CSV (ejemplo) que incluyen partes del archivo CSV de nivel superior específico para el país. Estos son los archivos que debes modificar.

3. Cómo crear nuevos IDs de TOC:

   Estructura y fuentes

   Consulta el documento abierto de datos cívicos para familiarizarte con la estructura del ID de OCD. En general, un ID de OCD válido tiene el siguiente formato: ocd-division/country:<country_code>(/<type>:<type_id>)

   La denominación de identificadores prefiere los identificadores estándar de ISO o de otros estándares, como FIPS y NUTS, si ISO no está disponible.

   Políticas generales

   Las siguientes son políticas generales:

   Jerarquía

   La jerarquía de los ID de TOC debe dictarse por el nivel administrativo que controla los límites de los IDs de TOC, no necesariamente por la relación de contención de los IDs de TOC.

   • Ejemplo: En Estados Unidos, los distritos electorales se usan en las elecciones de la Cámara de Representantes nacional, pero los Estados Unidos determinan sus límites. Por lo tanto, los distritos congresionales cuelgan de los estados: ocd-division/country:us/state:pa/cd:2.
   • Ejemplo: Murrysville es una municipalidad de Pensilvania y se encuentra dentro del condado de Westmoreland. Sin embargo, el estado es la administración de los pueblos, por lo que el ID de TOC se mantiene en pertenencia al estado: ocd-division/country:us/state:pa/place:murrysville Es posible que se use una jerarquía adicional en los casos en que sea necesario desambiguar.
   • Ejemplo: Hay 16 lugares en Pensilvania llamados “Municipio de Franclin”. Por lo general, cada uno tendría el ID de TOC ocd-division/country:us/state:pa/place:franklin, pero sería ambiguo. Entonces, en su lugar, podemos agregar el condado al ID de TOC para que cada uno obtenga su propio ID de TOC único. Ej.: ocd-division/country:us/state:pa/county:adams/place:franklin

   Tipo

   • Los tipos de ID de TOC suelen ser específicos de cada país.

   • Algunos IDs de TOC son comunes en todo el repositorio, como country, region y place.

   • Sin embargo, la orientación general consiste en especificar los tipos de una manera más específica que tenga sentido en el contexto de ese país.

     • Ejemplo: Para el Área administrativa 1 en EE.UU., se usan los tipos state, district y territory.
     • Ejemplo: Para el Área administrativa 1 en CA, se usan los tipos province y territory.
     • Ejemplo: Para el Área administrativa 1 en PT, se usan los tipos region y autonomous_region.

   ID

   • En general, queremos usar el mismo ID de OCD en un distrito en toda la reestructuración. Cuando elijas un type_id para usar en un conjunto nuevo de IDs de TOC, elige uno que sea más estable. Estas son algunas preguntas que debes hacerte para determinar qué identificador usar:
   • ¿Qué tan probable es que cambie el identificador de un distrito determinado debido a la reestructuración distrital?
   • Si el mismo funcionario mantiene el distrito X antes y después de que sus límites hayan cambiado de reestructuración distrital, ¿puedo representar su mandato como continuo?
   • ¿Los distritos con límites o nombres idénticos en distintas reestructuraciones están representados por el mismo identificador?
     • Ejemplo: En EE.UU., los números de distritos electorales se usan para los distritos residenciales en EE.UU. porque, aunque sus límites cambian con el reestructuración, la identidad está muy apegada al número y te refieres a alguien que ocupará el cargo en la tercera ubicación durante X años, incluso si esa cantidad de años cruza los límites de la reestructuración distrital.
     • Ejemplo: En Canadá, queremos usar nombres de distritos para representar los distritos electorales federales porque, si bien existen códigos electorales federales, este identificador no es estable porque los distritos idénticos en las reestructuraciones distritales están representados con diferentes IDs. (por ejemplo, el distrito 47012 antes de 2012 no es el mismo distrito después).

   Rediseñar

   Por lo general, cuando se actualizan los ID de TOC debido a la reestructuración distrital, se debe usar el conjunto de IDs de TOC que existe en lugar de crear un conjunto nuevo.

   • Si la identidad de un distrito (ID numérico, nombre, etc.) no cambia después de la reestructuración, usa el mismo ID de TOC.
   • Para la creación de distritos nuevos después de la reestructuración distrital, crea nuevos ID de TOC.
   • Para los distritos que ya no existen, actualiza el campo ValidThrough con la fecha en que entró en vigencia la reestructuración de distritos.
   • Si el ID de un distrito se basa en su nombre, y se cambia el nombre del distrito después de la reestructuración, crea un ID nuevo basado en el nombre del distrito nuevo y agrega un alias donde id = oldId y sameAs = newId. Esto canonicaliza el newId como uso de oldId, que se asigna a newId.
   • En caso de que haya una colisión entre los IDs históricos de TOC, por ejemplo, si un ID nuevo es idéntico a un ID abolido, agrega el año ValidFrom al nuevo ID. Para obtener más información sobre esta política de nombres, consulta Cómo crear archivos nuevos para los ID de TOC actuales, abolidos y renombrados.

Actualiza tu copia local

Cualquier actualización debe realizarse en el directorio específico del país: ocd-repository/identifiers/country-<2 letter country code>. Si no existe uno, créalo.

• Si el archivo CSV con los IDs de TOC ya existe y representan los límites electorales anteriores, debes actualizar este archivo para incluir los distritos nuevos. Para ello, agrega una columna ValidFrom y una ValidTo que contengan la fecha en formato AAAA-MM-DD.
  • ValidFrom debe ser la fecha de la elección para los distritos nuevos. Puede dejarse en blanco para los distritos que ya existen.
  • ValidTo para los distritos desactualizados debe ser el día anterior a la elección.

Actualizar alias

La asignación de alias se puede usar para marcar los IDs de TOC como una representación de la misma geografía política.

• Por ejemplo, si un lugar es un pueblo y un condado, esto podría tener sentido.

Estos son los principios generales que intentamos aplicar:

• Si dos partes de la geografía política son coincidentes, no necesariamente deben tener un alias entre sí. P. ej.: El congreso general de EE.UU. coincide con los estados, pero esto es casualidad debido a las cifras actuales de la población de ese país.

La asignación de alias también puede tener sentido cuando se requieran cambios significativos en las leyes o enmiendas constitucionales para dividir los distritos.

• Por ejemplo, los distritos del Senado y la Casa del Estado de Washington están configurados de ser los mismos por la ley constitucional.

Si lo necesitas, agrega un archivo CSV aliases.csv en el que agreguemos los IDs de TOC antiguos y sus alias. Los IDs canónicos pueden usar tipos de divisiones que tienen un significado local y pueden tener alias con representaciones más conocidas (como canónicos: ocd-division/country:de/land alias: `ocd-division/country:de/state). Consulta el error 170 para obtener más información.

Para actualizar un archivo alias.csv:

• Respeta el orden de las columnas en el archivo alias.csv: id,sameAs,sameAsNote

Tipo	Descripción
id	Esta columna debe tener los alias de los ID de OCD.
sameAs	Esta columna debe tener los ID de TOC reales para los que agregamos los alias.
sameAsNote	Una nota que describe cómo o por qué la división tiene varios identificadores.

Ejemplo: identifiers/country-in/aliases.csv

Ejecuta la secuencia de comandos: compile.py

Ejecuta la secuencia de comandos de Python en la ubicación opencivicdata/ocd-division-ids/scripts:

• Debes especificar el código de país de 2 letras como argumento de la secuencia de comandos para que sepa qué identificadores de país necesitan una actualización.
• Ejemplo: python3 scripts/compile.py in (para actualizar los ID de TOC de los distritos de la India).
• Python 2.x no recibe asistencia. Debes usar Python 3 o versiones posteriores. Puedes descargar la versión más reciente de Python 3 aquí.

La secuencia de comandos toma datos de los archivos CSV actualizados en el paso anterior (ocd-division-ids/identifiers/country-in/*.csv), valida los valores de los archivos, comprueba si hay errores de datos (uso de caracteres especiales, etc.) o duplicación de datos, y escribe los nuevos IDs de OCD en el archivo CSV de país de nivel superior.

La secuencia de comandos arroja mensajes de error y advertencia si surgen problemas en los archivos CSV actualizados. Resuelve los problemas y vuelve a ejecutar la secuencia de comandos.

Nota: La secuencia de comandos no detecta errores como varios espacios en el nombre o el nombre de la distrito electoral escrito incorrectamente, ya que el uso de espacios y letras es válido según los estándares.

Cómo agregar un archivo Léame

Cuando agregas un nuevo país o un nuevo nivel de cobertura (por ejemplo, antes solo teníamos un ID de OCD para el país, pero ahora agregamos los distritos administrativos de primer nivel), agrega o actualiza un archivo README.md. Este archivo debe contener un esquema rápido de la geografía política, incluido lo siguiente:

• Los tipos que usaremos y sus roles (como "districts es el área administrativa de primer nivel de este país")
• Las relaciones entre los tipos (como "los distritos legislativos se asignan por distrito y no cruzan los límites de los distritos")
• Cualquier excepción notable (como "hay un distrito legislativo que abarca a todos los ciudadanos extranjeros")
• Vínculos a cualquier página útil de Wikipedia que ayude a proporcionar contexto para un revisor o un usuario.

Crea una solicitud de extracción

Para crear una solicitud de extracción, usa la siguiente guía:

• Una vez que se complete este proceso sin errores, revisa el archivo .csv de nivel superior <2letter country code> de nivel superior recién escrito para asegurarte de que incluya el conjunto actualizado/nuevo de IDs de TOC.
• Crea una solicitud de extracción y agrega revisores. Esta solicitud de extracción debe incluir las modificaciones realizadas en todos los archivos CSV siguientes.
• Los archivos CSV del directorio específico del país. Ejemplo
• El archivo .csv de nivel superior país <código de país de 2 letras>. Ejemplo
• Cuando la solicitud de extracción revisa y aprueba dos de los confirmadores del país, uno de los propietarios o colaboradores del paquete la combina.