Процесс обновления идентификаторов OCD

Введение

Открытые гражданские идентификаторы данных (OCD ID) — это общий формат идентификаторов, определяющий политическую географию. Чтобы создать канал CDF, вам необходимо предоставить эти идентификаторы как часть сущности GpUnit. Целью этого документа является предоставление рекомендаций и лучших практик по добавлению идентификаторов OCD в репозиторий opencivicdata Github .

Предупреждение. Репозиторий идентификаторов OCD является общедоступным. Не упоминайте явным образом какие-либо предстоящие запуски или проекты в PR, описаниях проблем или комментариях. Это верно, даже если страны, которые это охватывает, очевидны из набора стран, для которых мы генерируем ОР, или из того факта, что в данной стране проходят широко освещаемые выборы.

Как обновить идентификаторы OCD в репозитории Open Civic Data GitHub

Предварительные условия

1. Поймите, как внести свой вклад в проект с открытым исходным кодом.

Прежде чем ты начнешь:

1. Подготовьте рабочее место:

   Форкните и клонируйте пакет из репозитория OCD ID .

2. Ознакомьтесь с репо:

   В репозитории идентификаторов OCD каждая поддерживаемая страна представлена ​​каталогом и CSV-файлом с одинаковым именем: страна-<двухбуквенный код страны> (пример: identifiers/country-de и identifiers/country-de.csv для Германии). ).

   Примечание. Файлы CSV не должны обновляться напрямую путем редактирования вручную. Вместо этого используйте инструкцию ниже.

   В каталоге страны, которую вы хотите изменить, вы можете найти файлы CSV ( Пример ), которые включают части CSV-файла верхнего уровня для конкретной страны. Это файлы, которые вам нужно изменить.

3. Как создать новые идентификаторы OCD:

   Структура и источники

   Взгляните на документ с открытыми гражданскими данными , чтобы ознакомиться со структурой идентификатора OCD. Как правило, действительный идентификатор OCD имеет следующий формат: ocd-division/country:<country_code>(/<type>:<type_id>)

   При именовании идентификаторов предпочтение отдается стандартным идентификаторам ISO или другим стандартам, таким как FIPS и NUTS, если ISO недоступен.

   Общая политика

   Ниже приведены общие правила:

   Иерархия

   Иерархия идентификаторов OCD должна диктоваться административным уровнем, который контролирует границы идентификаторов OCD, а не обязательно отношениями сдерживания идентификаторов OCD.

   • Пример: В Соединенных Штатах избирательные округа Конгресса используются на выборах в национальную Палату представителей, но их границы определяются штатами. Таким образом, избирательные округа Конгресса отделяются от штатов: ocd-division/country:us/state:pa/cd:2
   • Пример: Маррисвилл — муниципалитет в Пенсильвании, входящий в состав округа Уэстморленд. Однако города находятся в ведении штата, поэтому идентификатор OCD не привязан к штату: ocd-division/country:us/state:pa/place:murrysville Дополнительная иерархия может использоваться в случаях, когда необходимо устранение неоднозначности.
   • Пример. В Пенсильвании 16 мест под названием «Тауншип Франклин». Обычно каждый из них имеет идентификатор OCD ocd-division/country:us/state:pa/place:franklin , но это было бы неоднозначно. Вместо этого мы можем добавить округ к идентификатору OCD, чтобы каждый округ получил свой уникальный идентификатор OCD. Пример: ocd-division/country:us/state:pa/county:adams/place:franklin

   Тип

   • Типы идентификаторов OCD обычно зависят от страны.

   • Некоторые идентификаторы OCD являются общими для всего репозитория, например country , region и place .

   • Однако общее руководство состоит в том, чтобы допустить ошибку в определении типов более конкретным способом, который имел бы смысл в контексте этой страны.

     • Пример. Для административной области 1 в США используются типы state , district и territory .
     • Пример. Для административной области 1 в Калифорнии используются типы province » и territory .
     • Пример: для административной области 1 в PT используются типы region и autonomous_region .

   ИДЕНТИФИКАТОР

   • В общем, мы хотим использовать один и тот же идентификатор OCD для округа при перераспределении округов. При выборе type_id для использования в новом наборе идентификаторов OCD выберите наиболее стабильный. При определении того, какой идентификатор использовать, следует задать следующие вопросы:
   • Насколько вероятно изменение идентификатора данного округа в результате перераспределения округов?
   • Если одно и то же должностное лицо управляет округом X до и после изменения его границ в результате перераспределения округов, буду ли я представлять их срок как непрерывный?
   • Представлены ли районы с идентичными границами или названиями в рамках перераспределения округов одним и тем же идентификатором?
     • Пример: В США номера округов Конгресса используются для избирательных округов США, потому что, хотя их границы меняются при перераспределении избирательных округов, идентичность сильно привязана к номеру, и вы будете называть кого-то занимающим должность N-го места в течение X лет, даже если такое количество лет пересекает границы перераспределения округов.
     • Пример. В Канаде мы хотим использовать названия округов для обозначения федеральных избирательных округов, поскольку, несмотря на существование федеральных избирательных кодексов , этот идентификатор не является стабильным, поскольку идентичные округа при перераспределении округов представлены с разными идентификаторами. (например, округ 47012 до 2012 года, после которого перераспределение округов не будет тем же самым).

   Перераспределение округов

   Обычно при обновлении идентификаторов OCD из-за перераспределения используйте существующий набор идентификаторов OCD, а не создайте новый набор.

   • Если идентификатор округа (цифровой идентификатор, имя и т. д.) не меняется после изменения округа, используйте тот же идентификатор OCD.
   • Для создания новых округов после перераспределения создайте новые идентификаторы OCD.
   • Для округов, которые больше не существуют, обновите поле ValidThrough , указав дату вступления перераспределения в силу.
   • Если идентификатор округа основан на его названии и после перераспределения округ переименовывается, создайте новый идентификатор на основе нового названия округа и добавьте псевдоним, где id = oldId и sameAs = newId . Это канонизирует newId , поскольку использование oldId сопоставляется с newId .
   • В случае конфликта между историческими идентификаторами OCD, например, новый идентификатор идентичен отмененному идентификатору, добавьте год ValidFrom к новому идентификатору. Дополнительные сведения об этой политике именования см. в разделе Создание новых файлов для текущих, упраздненных и переименованных OCD-ID .

Обновите локальную копию

Любое обновление необходимо выполнять в каталоге конкретной страны: ocd-repository /identifiers/country-<2-буквенный код страны>. Если такового не существует, создайте его.

• Если CSV-файл идентификаторов OCD уже существует и они представляют старые избирательные границы, вам необходимо обновить этот файл, включив в него новые округа. Для этого добавьте столбцы ValidFrom и ValidTo , содержащие дату в формате ГГГГ-ММ-ДД.
  • ValidFrom должен быть датой выборов для новых округов. его можно оставить пустым для уже существующих избирательных округов.
  • ValidTo для устаревших округов должен быть за день до выборов.

Обновить псевдонимы

Псевдонимы можно использовать для маркировки идентификаторов OCD как представления одной и той же части политической географии.

• Например, если место одновременно является городом и округом, это может иметь смысл.

Общие принципы, которые мы пытаемся продвигать:

• Если две части политической географии совпадают, они не обязательно должны быть псевдонимами друг друга. Пример: Конгресс США в целом совпадает со штатами, но это случайно из-за текущей численности населения США.

Псевдонимы также могут иметь смысл в тех случаях, когда для разделения округов потребуются значительные изменения в законах/конституционные поправки.

• Например, в соответствии с конституционным законом сенат штата Вашингтон и избирательные округа штата должны быть одинаковыми.

Если нужно, добавьте CSV-файл aliases.csv , в который мы добавляем как старые идентификаторы OCD, так и их псевдонимы. Канонические идентификаторы могут использовать типы делений, которые имеют локальное значение и могут иметь псевдонимы с более привычными представлениями (например, канонический: ocd-division/country:de/land alias: `ocd-division/country:de/state). Дополнительную информацию см. в выпуске № 170 .

Чтобы обновить файл aliases.csv:

• Соблюдайте порядок столбцов в файле aliases.csv: id , sameAs , sameAsNote

Тип	Описание
идентификатор	В этом столбце должны быть псевдонимы идентификаторов OCD.
такой же как	В этом столбце должны быть указаны фактические идентификаторы OCD, для которых мы добавляем псевдонимы.
то жеКакПримечание	Примечание, описывающее, как и почему подразделение имеет несколько идентификаторов.

Пример: идентификаторы/country-in/aliases.csv

Запустите скрипт — compile.py

Запустите скрипт Python по адресу opencivicdata/ocd-division-ids/scripts :

• Вам необходимо указать двухбуквенный код страны в качестве аргумента сценария, чтобы он знал, идентификаторы какой страны нуждаются в обновлении.
• Пример: скрипты python3/compile.py (для обновления идентификаторов OCD избирательных округов в Индии).
• Python 2.x не получает поддержки. Приходится использовать Python 3 или более поздние версии. Скачать последнюю версию Python 3 можно здесь .

Скрипт берет данные из CSV-файлов, обновленных на предыдущем шаге (ocd-division-ids/identifiers/country-in/*.csv), проверяет значения в файлах, проверяет наличие ошибок в данных (использование специальных символов и т. д.). ) или дублирование данных и записывает новые идентификаторы OCD в CSV-файл страны верхнего уровня.

Сценарий выдает сообщения об ошибках и предупреждения, если в обновленных файлах CSV возникают какие-либо проблемы. Устраните проблемы и снова запустите сценарий.

Примечание. Скрипт не обнаруживает такие ошибки, как наличие нескольких пробелов в имени или неправильное написание названия округа, поскольку использование пробелов и букв допустимо в соответствии со стандартами .

Добавьте файл readme

Когда вы добавляете новую страну или новый уровень покрытия (например, раньше у нас был только идентификатор OCD для страны, а теперь добавляем административные округа первого уровня), добавьте или обновите файл README.md. Этот файл должен содержать краткое описание политической географии, в том числе:

• Типы, которые мы будем использовать, и их роли (например, « districts являются административной единицей первого уровня в этой стране»);
• Отношения между типами (например, «законодательные округа назначаются отдельно для каждого округа и не пересекают границы округа»);
• Любые заметные исключения (например, «есть один законодательный округ, охватывающий всех иностранных граждан»); и
• Ссылки на любые полезные страницы Википедии, помогающие предоставить контекст рецензенту или пользователю.

Создать запрос на включение

Чтобы создать запрос на включение, используйте следующие рекомендации:

• Как только этот процесс завершится без ошибок, проверьте вновь записанный файл страны верхнего уровня <двухбуквенный код страны>.csv, чтобы убедиться, что он теперь включает обновленный/новый набор идентификаторов OCD.
• Создайте запрос на включение. и добавьте рецензентов. Этот запрос на включение должен включать изменения, внесенные во все следующие файлы CSV.
• Файлы CSV в каталоге конкретной страны. Пример
• Файл страны верхнего уровня <двухбуквенный код страны>.csv. Пример
• Когда запрос на включение рассматривается и утверждается двумя коммиттерами в стране , он объединяется одним из владельцев/соавторов пакета.