Quy trình cập nhật mã OCD

Giới thiệu

Giá trị nhận dạng dữ liệu dân sự mở (mã nhận dạng OCD) là một định dạng giá trị nhận dạng phổ biến xác định các khu vực địa lý chính trị. Để tạo nguồn cấp dữ liệu CDF, bạn cần cung cấp các giá trị nhận dạng này như một phần của thực thể GpUnit. Tài liệu này nhằm cung cấp hướng dẫn và các phương pháp hay nhất để thêm mã OCD vào kho lưu trữ GitHub về OCD.

Cách cập nhật mã OCD trong kho lưu trữ Open Civic Data GitHub

Điều kiện tiên quyết

  1. Tìm hiểu cách đóng góp cho dự án nguồn mở

Trước khi bắt đầu, bạn cần:

  1. Chuẩn bị máy trạm:

    Phát triển nhánh và sao chép gói từ kho lưu trữ mã nhận dạng OCD.

  2. Làm quen với kho lưu trữ:

    Trong kho lưu trữ mã nhận dạng OCD, mỗi quốc gia được hỗ trợ được biểu thị bằng một thư mục và tệp CSV có cùng tên: mã quốc gia <2 chữ cái> (Ví dụ: identifiers/country-de và identifiers/country-de.csv đối với Đức).

    Trong thư mục của quốc gia mà bạn muốn sửa đổi, bạn có thể tìm thấy các tệp CSV (Ví dụ) bao gồm các phần của tệp CSV cấp cao nhất dành riêng cho từng quốc gia. Đây là những tệp bạn cần sửa đổi.

  3. Cách tạo mã OCD mới:

    Cấu trúc và nguồn

    Hãy xem tài liệu mở về dữ liệu dân sự để làm quen với cấu trúc mã OCD. Nhìn chung, mã nhận dạng OCD hợp lệ sẽ có định dạng sau: ocd-division/country:<country_code>(/<type>:<type_id>)

    Việc đặt tên giá trị nhận dạng ưu tiên giá trị nhận dạng chuẩn theo ISO hoặc các tiêu chuẩn khác, chẳng hạn như FIPS và NUTS, nếu không có ISO.

    Chính sách chung

    Sau đây là các chính sách chung:

    Hệ phân cấp

    Hệ phân cấp mã OCD phải chỉ định theo cấp quản trị giúp kiểm soát ranh giới của mã OCD, chứ không nhất thiết là mối quan hệ ngăn chặn của mã OCD.

    • Ví dụ: Ở Hoa Kỳ, các địa hạt quốc hội được dùng trong các cuộc bầu cử cho Hạ viện quốc gia, nhưng ranh giới của các địa hạt đó là do Hoa Kỳ xác định. Vì vậy, các hạt bầu cử treo liên quan đến các tiểu bang: ocd-division/country:us/state:pa/cd:2
    • Ví dụ: Murrysville là một đô thị ở Pennsylvania và nằm trong Hạt Westmoreland. Tuy nhiên, các thị trấn do Nhà nước quản lý, vì vậy, mã OCD bị bỏ qua cho tiểu bang: ocd-division/country:us/state:pa/place:murrysville Có thể dùng thêm thứ bậc phân cấp trong trường hợp cần phân định.
    • Ví dụ: Có 16 địa điểm ở Pennsylvania có tên là "Thành phố Franklin". Thông thường, mỗi mã này sẽ có mã OCD ocd-division/country:us/state:pa/place:franklin, nhưng mã này không rõ ràng. Thay vào đó, chúng ta có thể thêm hạt vào mã OCD để mỗi hạt sẽ nhận được mã OCD riêng. Ví dụ: ocd-division/country:us/state:pa/county:adams/place:franklin
    Loại

    • Các loại mã nhận dạng OCD thường dành riêng cho từng quốc gia.

    • Một số mã nhận dạng OCD phổ biến trên toàn bộ kho lưu trữ như country, region và place.

    • Tuy nhiên, hướng dẫn chung là sai sót khi chỉ định các loại theo cách cụ thể hơn và phù hợp với bối cảnh của quốc gia đó.

      • Ví dụ: Đối với Khu vực quản trị 1 ở Hoa Kỳ, các loại state, district, và territory sẽ được sử dụng.
      • Ví dụ: Đối với Khu vực quản trị 1 trong CA, hệ thống sử dụng các kiểu province và territory.
      • Ví dụ: Đối với Khu vực quản trị 1 ở PT, hệ thống sử dụng các loại region và autonomous_region.
    Mã nhận dạng
    • Nhìn chung, chúng tôi muốn sử dụng cùng một mã OCD cho một học khu trong quá trình tái phân khu. Khi chọn type_id để sử dụng cho một nhóm mã OCD mới, hãy chọn một mã ổn định nhất. Một số câu hỏi cần đặt ra khi xác định giá trị nhận dạng để sử dụng là:
    • Giá trị nhận dạng của một quận nhất định có khả năng thay đổi do việc xác lập lại địa hạt không?
    • Nếu cùng một chính trị gia giữ quận X trước và sau khi ranh giới của khu vực đó thay đổi từ việc xác lập lại quận, thì tôi có thể hiện nhiệm kỳ của họ là liên tục không?
    • Các quận có ranh giới hoặc tên giống nhau trên phạm vi phân khu có được đại diện bằng cùng một mã nhận dạng không?
      • Ví dụ: Ở Hoa Kỳ, số khu vực quốc hội được sử dụng cho các quận hạt ở Hoa Kỳ vì mặc dù ranh giới của các khu vực đó thay đổi khi phân chia lại khu vực, danh tính đó gắn liền với số đó và bạn sẽ đề cập đến người nào đó là giữ chức vụ tại ghế N trong X năm ngay cả khi khoảng năm đó vượt qua ranh giới tái phân khu.
      • Ví dụ: Ở Canada, chúng tôi muốn sử dụng tên quận để đại diện cho các khu bầu cử liên bang vì mặc dù có mã bầu cử liên bang, nhưng giá trị nhận dạng này không ổn định vì các quận giống nhau trong khu vực bầu cử lại được thể hiện bằng mã khác nhau. (chẳng hạn như quận 47012 trước năm 2012 việc thiết lập lại phân khu vực không phải là cùng một quận sau đó).
    Xác lập địa hạt

    Nhìn chung, khi cập nhật mã OCD do phân chia lại khu vực, hãy sử dụng bộ mã OCD hiện có thay vì tạo một bộ mới.

    • Nếu danh tính của một học khu (mã nhận dạng bằng số, tên, v.v.) không thay đổi sau khi xác định lại khu vực, hãy sử dụng cùng một mã OCD.
    • Để tạo các khu vực mới sau khi phân chia khu vực, hãy tạo các mã nhận dạng OCD mới.
    • Đối với các quận không còn tồn tại, hãy cập nhật trường ValidThrough bằng ngày phân chia lại có hiệu lực.
    • Nếu mã nhận dạng của một quận dựa trên tên và quận đó được đổi tên sau khi phân chia lại khu vực, hãy tạo một mã nhận dạng mới dựa trên tên mới của quận, đồng thời thêm một bí danh có id = oldId và sameAs = newId. Việc này chuẩn hoá newId dưới dạng mức sử dụng của mục ánh xạ oldId đến newId.
    • Trong trường hợp có xung đột giữa các mã OCD trước đây, chẳng hạn như mã nhận dạng mới giống với mã nhận dạng đã bị xoá, hãy thêm năm ValidFrom vào mã mới. Để biết thêm về chính sách đặt tên này, hãy xem phần Tạo tệp mới cho các mã OCD-ID hiện tại, đã bị xoá bỏ và được đổi tên.

Cập nhật bản sao cục bộ

Bạn cần cập nhật mọi thông tin trong thư mục dành riêng cho quốc gia: ocd-repository/identifiers/country-<2 letter country code>. Hãy tạo bản cập nhật nếu chưa có.

  • Nếu tệp CSV chứa mã OCD đã tồn tại và tệp này đại diện cho các khu vực bầu cử cũ, bạn cần cập nhật tệp này để thêm các khu vực bầu cử mới. Để thực hiện việc này, hãy thêm ValidFrom và cột ValidTo chứa ngày ở định dạng YYYY-MM-DD.
    • ValidFrom phải là ngày bầu cử cho các khu vực bầu cử mới. Có thể để trống cho các khu vực bầu cử đã tồn tại.
    • ValidTo cho các khu vực bầu cử đã lỗi thời phải diễn ra một ngày trước ngày bầu cử.

Cập nhật email đại diện

Bạn có thể sử dụng phương pháp đặt bí danh để đánh dấu mã OCD là nội dung đại diện cho cùng một phần địa lý chính trị.

  • Ví dụ: nếu một địa điểm vừa là thị trấn và hạt, thì điều này có thể hợp lý.

Nguyên tắc chung mà chúng tôi cố gắng thúc đẩy:

  • Nếu hai phần về địa lý chính trị có tính kết hợp thống nhất, thì chúng không nhất thiết phải đặt bí danh với nhau. Ví dụ: Quốc hội Hoa Kỳ có quy mô lớn đồng thời với các tiểu bang, nhưng điều này là do tình huống số lượng dân số hiện tại của Hoa Kỳ.

Hiện tượng chồng phổ cũng có thể hợp lý khi cần phải có những thay đổi đáng kể về luật/sửa đổi hiến pháp để chia tách các khu vực.

  • Ví dụ: Thượng viện và các địa hạt tại Hạ viện tiểu bang Washington được đặt giống nhau theo luật hiến pháp.

Nếu cần, hãy thêm tệp CSV aliases.csv, trong đó chúng tôi thêm cả mã OCD cũ và tên đại diện của các mã đó. Mã nhận dạng chính tắc có thể sử dụng những loại phép chia có ý nghĩa cục bộ và có thể có bí danh với các cách biểu diễn quen thuộc hơn (chẳng hạn như bí danh: ocd-division/country:de/land bí danh: `ocd-division/country:de/state). Hãy xem vấn đề #170 để biết thêm thông tin.

Cách cập nhật tệp sellers.csv:

  • Tuân theo thứ tự của các cột trong tệp alias.csv: id,sameAs,sameAsNote
Loại Nội dung mô tả
id Cột này phải có bí danh cho mã OCD.
sameAs Cột này phải có mã OCD thực mà chúng tôi thêm bí danh.
sameAsNote Ghi chú mô tả cách thức hoặc lý do phép chia có nhiều giá trị nhận dạng.

Ví dụ: identifiers/country-in/aliases.csv

Chạy tập lệnh – compile.py

Chạy tập lệnh python tại vị trí open Civicdata/ocd-division-ids/scripts:

  • Bạn phải chỉ định mã quốc gia gồm 2 chữ cái làm đối số cho tập lệnh để tập lệnh biết được mã nhận dạng của quốc gia nào cần cập nhật.
  • Ví dụ: python3 Scripts/compile.py in (để cập nhật mã OCD của các khu vực bầu cử ở Ấn Độ).
  • Python 2.x không được hỗ trợ. Phải sử dụng phiên bản Python 3 trở lên. Bạn có thể tải phiên bản mới nhất của Python 3 tại đây.

Tập lệnh sẽ lấy dữ liệu từ các tệp CSV được cập nhật ở bước trước (ocd-division-ids/identifiers/country-in/*.csv), xác thực giá trị trong tệp, kiểm tra xem có lỗi dữ liệu nào không (sử dụng các ký tự đặc biệt, v.v.) hoặc trùng lặp dữ liệu và ghi mã OCD mới vào tệp CSV quốc gia cấp cao nhất.

Tập lệnh sẽ gửi ra thông báo lỗi và cảnh báo nếu có bất kỳ vấn đề nào phát sinh trong các tệp CSV cập nhật. Hãy giải quyết vấn đề rồi chạy lại tập lệnh.

Thêm tệp readme

Khi bạn thêm một quốc gia mới hoặc một phạm vi phủ sóng mới (ví dụ: trước đây chúng tôi chỉ có mã OCD cho quốc gia đó nhưng giờ đã thêm các khu hành chính cấp 1), hãy thêm hoặc cập nhật tệp README.md. Tệp này phải chứa bản tóm tắt ngắn gọn về địa lý chính trị, bao gồm:

  • Các loại mà chúng tôi sẽ sử dụng và vai trò của chúng (chẳng hạn như "districts là khu vực hành chính cấp 1 tại quốc gia này");
  • Mối quan hệ giữa các loại (chẳng hạn như "các khu vực lập pháp được chỉ định trên cơ sở từng quận và không vượt qua ranh giới của quận");
  • Mọi ngoại lệ đáng chú ý (chẳng hạn như "có một khu vực lập pháp bao gồm tất cả công dân ở nước ngoài"); và
  • Liên kết đến bất kỳ trang Wikipedia hữu ích nào để giúp cung cấp ngữ cảnh cho người đánh giá hoặc người dùng.

Tạo một yêu cầu lấy dữ liệu

Để tạo một yêu cầu lấy dữ liệu, hãy sử dụng hướng dẫn sau:

  • Khi quá trình này hoàn tất mà không gặp lỗi, hãy kiểm tra tệp .csv cấp cao nhất mới viết bằng mã quốc gia <2 chữ cái> để đảm bảo tệp này hiện đã có bộ mã OCD được cập nhật/mới.
  • Tạo yêu cầu thu thập dữ liệu và thêm người đánh giá. Yêu cầu lấy dữ liệu này phải bao gồm các thao tác sửa đổi trong tất cả các tệp CSV sau đây.
  • Các tệp CSV trong thư mục dành riêng cho quốc gia. Ví dụ
  • Tệp .csv quốc gia có <2 chữ cái> cấp cao nhất. Ví dụ
  • Khi yêu cầu lấy dữ liệu được hai trong số các uỷ ban của quốc gia đó xem xét và phê duyệt, yêu cầu đó sẽ được một trong những chủ sở hữu/cộng tác viên của gói hợp nhất.