Processo para atualizar os IDs de OCD

Introdução

Os identificadores de dados cívicos abertos (IDs do OCD) são um formato de identificador comum que define regiões geográficas políticas. Para criar um feed de CDF, forneça esses identificadores como parte de uma entidade GpUnit. O objetivo deste documento é apresentar orientações e práticas recomendadas para adicionar IDs de OCD ao repositório opencivicdata do GitHub.

Aviso :o repositório de IDs de OCD é público. Não mencione explicitamente os próximos lançamentos ou projetos em RP nem descrições ou comentários de problemas. Isso acontece mesmo se os países abrangidos forem óbvios para o conjunto de países para os quais estamos gerando PRs ou para o fato de que uma eleição bem divulgada está acontecendo em um determinado país.

Como atualizar os IDs de OCD no repositório Open Civic Data do GitHub

Pré-requisitos

1. Entender como contribuir para um projeto de código aberto

Antes de começar:

1. Prepare a estação de trabalho:

   Bifurque e clone o pacote do repositório de ID do OCD.

2. Conheça o repositório:

   No repositório de IDs do OCD, cada país aceito é representado por um diretório e um arquivo CSV que compartilha o mesmo nome: country-<código do país de duas letras> (por exemplo: identifiers/country-de e identifiers/country-de.csv para a Alemanha).

   Observação :os arquivos CSV não podem ser atualizados diretamente usando uma edição manual. Em vez disso, siga as instruções abaixo.

   Dentro do diretório do país que você quer modificar, é possível encontrar os arquivos CSV (exemplo) que incluem partes do arquivo CSV de nível superior específico do país. Esses são os arquivos que você precisa modificar.

3. Como criar novos IDs de OCD:

   Estrutura e fontes

   Consulte o documento aberto de dados cívicos para se familiarizar com a estrutura do ID do OCD. Em geral, um ID de OCD válido tem o seguinte formato: ocd-division/country:<country_code>(/<type>:<type_id>)

   A nomenclatura de identificadores vai dar preferência a identificadores padrão da ISO ou de outros padrões, como FIPS e NUTS, se o ISO não estiver disponível.

   Políticas gerais

   Veja a seguir as políticas gerais:

   Hierarquia

   A hierarquia de IDs de OCD precisa ser determinada pelo nível administrativo que controla os limites dos IDs de OCD, não necessariamente a relação de contenção deles.

   • Exemplo:nos Estados Unidos, os distritos congressionais são usados nas eleições para a Câmara dos Deputados nacional, mas os limites são determinados pelos Estados. Portanto, os distritos congressionais não dependem dos estados: ocd-division/country:us/state:pa/cd:2
   • Exemplo:Murrysville é uma municipalidade da Pensilvânia e fica no condado de Westmoreland. No entanto, as cidades são administradas pelo estado. Por isso, o ID de OCD fica suspenso quando necessário: ocd-division/country:us/state:pa/place:murrysville A hierarquia extra pode ser usada nos casos em que a desambiguação é necessária.
   • Exemplo:há 16 lugares na Pensilvânia chamados "FranklinTownship". Normalmente, cada um deles teria o ID de OCD ocd-division/country:us/state:pa/place:franklin, mas isso seria ambíguo. Em vez disso, podemos adicionar o condado ao ID de OCD para que cada um receba o próprio ID de OCD exclusivo. Por exemplo: ocd-division/country:us/state:pa/county:adams/place:franklin

   Tipo

   • Os tipos de ID OCD normalmente são específicos de cada país.

   • Alguns IDs de OCD são comuns em todo o repositório, como country, region e place.

   • No entanto, a orientação geral é especificar os tipos de uma forma mais específica que faria sentido no contexto desse país.

     • Exemplo: para a Área administrativa 1 nos EUA, os tipos state, district e territory são usados.
     • Exemplo: para a Área administrativa 1 na CA, os tipos province e territory são usados.
     • Exemplo:para a Área administrativa 1 em PT, os tipos region e autonomous_region são usados.

   ID

   • Em geral, queremos usar o mesmo ID de OCD para um distrito em todo o redistritamento. Ao escolher um type_id a ser usado para um novo conjunto de IDs de OCD, escolha um que seja mais estável. Algumas perguntas a serem feitas ao determinar qual identificador usar são:
   • Qual é a probabilidade de o identificador de um determinado distrito mudar devido ao redistritamento?
   • Se o mesmo funcionário ocupar o distrito X antes e depois das fronteiras terem mudado de redistritamento, eu representaria o período dele como contínuo?
   • Os distritos com fronteiras ou nomes idênticos são representados pelo mesmo identificador?
     • Exemplo:nos EUA, os números de distritos congressionais são usados para distritos domésticos dos EUA porque, mesmo que os limites mudem com o redistritamento, a identidade está fortemente ligada ao número, e você seria que alguém ocupa um cargo na Nante cadeira por X anos, mesmo quando esse número ultrapassa os limites do redistritamento.
     • Exemplo:no Canadá, queremos usar nomes de distritos para representar os distritos eleitorais federais porque, embora existam códigos eleitorais federais, esse identificador não é estável porque distritos idênticos em todo o redistritamento são representados com IDs diferentes. Por exemplo, o redistritamento do distrito 47012 antes de 2012 não será o mesmo depois.

   Redefinição

   Geralmente, ao atualizar os IDs de OCD devido ao redistritamento, use o conjunto de IDs de OCD atuais em vez de criar um novo conjunto.

   • Se a identidade de um distrito (código numérico, nome etc.) não mudar após a redefinição, use o mesmo ID de OCD.
   • Para a criação de novos distritos após o redistritamento, crie novos IDs de OCD.
   • Para os distritos que não existem mais, atualize o campo ValidThrough com a data em que a redistritação entrou em vigor.
   • Se o ID de um distrito for baseado no nome dele e o distrito for renomeado após a redistritação, crie um novo ID com base no novo nome do distrito e adicione um alias onde id = oldId e sameAs = newId. Isso canoniza o newId conforme o uso de oldId é mapeado para newId.
   • Se houver uma colisão entre IDs históricos de TOCD, por exemplo, quando um novo ID for idêntico a um abolido, anexe o ano de ValidFrom ao novo ID. Para saber mais sobre essa política de nomenclatura, consulte Criar novos arquivos para IDs de OCD atuais, abolidos e renomeados.

Atualizar sua cópia local

Qualquer atualização precisa ser feita no diretório específico do país: ocd-repository/identifiers/country-<2 letter country code>. Se não existir, crie uma.

• Se o arquivo CSV com os IDs de TOC já existir e representar os limites eleitorais antigos, você vai precisar atualizar o arquivo para incluir os novos grupos eleitorais. Para fazer isso, adicione uma coluna ValidFrom e uma ValidTo que contenha a data no formato AAAA-MM-DD.
  • ValidFrom precisa ser a data da eleição para os novos públicos-alvo e pode ser deixado em branco para os já existentes.
  • ValidTo para eleitores desatualizados precisa ser um dia antes da eleição.

Atualizar aliases

A atribuição de alias pode ser usada para marcar IDs do OCD como representação da mesma região política.

• Por exemplo, se um lugar é uma cidade e um condado, isso pode fazer sentido.

Os princípios gerais que estamos tentando promover:

• Se duas áreas geográficas políticas forem conjuntas, elas não precisarão ter alias umas com as outras. Exemplo: um grande Congresso dos EUA é consenso com os estados, mas isso acontece por acaso devido aos números atuais da população dos EUA.

A atribuição de aliases também pode fazer sentido quando mudanças significativas nas leis ou emendas constitucionais seriam necessárias para dividir os distritos.

• Por exemplo, o senado do estado de Washington e os distritos da câmara estadual são definidos como os mesmos por lei constitucional.

Se precisar, adicione um arquivo CSV aliases.csv em que adicionamos os IDs de OCD antigos e os aliases deles. Os IDs canônicos podem usar tipos de divisão que têm um significado local e podem ter aliases com representações mais conhecidas (como canônico: alias ocd-division/country:de/land: `ocd-division/country:de/state). Consulte o problema 170 para ver mais informações.

Para atualizar o arquivo aliases.csv:

• Respeite a ordem das colunas no arquivo aliases.csv: id,sameAs,sameAsNote

Tipo	Descrição
id	Essa coluna precisa ter os aliases dos IDs de OCD.
sameAs	Essa coluna precisa ter os IDs de OCD reais para os quais adicionamos os aliases.
sameAsNote	Uma observação que descreve como ou por que a divisão tem vários identificadores.

Exemplo:identifiers/country-in/aliases.csv

Execute o script: compile.py

Execute o script Python no local opencivicdata/ocd-division-ids/scripts:

• Você precisa especificar o código do país de duas letras como argumento para o script para que ele saiba quais identificadores do país precisam ser atualizados.
• Exemplo: scripts python3/compile.py in (para atualizar códigos de OCD de eleitores na Índia).
• O Python 2.x não recebe suporte. É preciso usar o Python 3 ou versões mais recentes. Faça o download da versão mais recente do Python 3 aqui.

O script coleta dados dos arquivos CSV atualizados na etapa anterior (ocd-division-ids/identifiers/country-in/*.csv), valida os valores nos arquivos, verifica se há erros de dados (uso de caracteres especiais etc.) ou duplicação de dados e grava os novos códigos de OCD no arquivo CSV do país de nível superior.

O script gera mensagens de erro e aviso caso surja algum problema nos arquivos CSV atualizados. Resolva os problemas e execute o script novamente.

Observação: o script não detecta erros como vários espaços no nome ou nome do distrito eleitoral escrito incorretamente, já que o uso de espaços e letras é válido de acordo com os padrões.

Adicionar um arquivo leia-me

Ao adicionar um novo país ou um novo nível de cobertura (por exemplo, antes tínhamos apenas um ID de OCD para o país, mas agora estamos adicionando os distritos administrativos de primeiro nível), adicione ou atualize um arquivo README.md. Esse arquivo precisa conter uma descrição rápida da geografia política, incluindo:

• Os tipos que vamos usar e os papéis deles (como "districts são a área político-administrativa de primeiro nível deste país");
• as relações entre os tipos (como "os distritos legislativos são atribuídos por distrito e não ultrapassam os limites do distrito");
• Exceções notáveis (como "há um distrito legislativo para cobrir todos os cidadãos estrangeiros"); e
• Links para páginas úteis da Wikipédia que ajudam a dar contexto a um revisor ou usuário.

Criar uma solicitação de envio

Para criar uma solicitação de envio, siga estas orientações:

• Quando o processo for concluído sem erros, verifique o arquivo .csv recém-gravado de nível superior de nível superior do país <2 letras do código do país> para conferir se ele inclui o conjunto atualizado/novo de IDs de OCD.
• Crie uma solicitação de envio e adicione revisores. Essa solicitação de envio precisa incluir modificações feitas em todos os arquivos CSV a seguir.
• Os arquivos CSV no diretório específico do país. Exemplo
• O arquivo .csv de nível superior país-<código do país de duas letras>. Exemplo
• Quando a solicitação de envio é analisada e aprovada por dois dos revisores do país, ela é mesclada por um dos proprietários/colaboradores do pacote.