admin#

Administration

Worldwide administrative referencing and mapping

  • Manage global admin files

  • Manage globally unique identifiers (admin_ids)

Functions#

get_admin1_iso()

Get dataframe with country ISO alpha codes and names

admin1_id_index_from_admin1_id_a3(gdf)

Give dataframe gdf an admin1_id index from admin1_id_a3

get_admin2_iso()

Get dataframe with state/province ISO3116-2 codes and names

admin2_id_index_from_admin2_gadm(admin2)

Give dataframe admin an admin2_id index based on GADM data

admin3_id_index_from_local(admin3_local, admin2_recipe_id)

Index a country's local admin-3 source against the global spine.

fold_to_ascii(text)

Transliterate text to its closest ASCII representation.

clean_geographic_name(name, *[, na_tokens, prefixes, ...])

Clean an administrative-unit name into structured components.

generate_admin_ids(df[, new_admin_id_col, ...])

Generate unique two-letter admin unit codes within parent units.

update_admin_spine(level, admin_recipe_id, test[, silent])

Update the openplaces admin spine with admin recipe info

Module Contents#

openplaces.io.admin.get_admin1_iso()#

Get dataframe with country ISO alpha codes and names

openplaces.io.admin.admin1_id_index_from_admin1_id_a3(gdf)#

Give dataframe gdf an admin1_id index from admin1_id_a3

Single-use function to create linkage between GADM and ISO

openplaces.io.admin.get_admin2_iso()#

Get dataframe with state/province ISO3116-2 codes and names

openplaces.io.admin.admin2_id_index_from_admin2_gadm(admin2)#

Give dataframe admin an admin2_id index based on GADM data

openplaces.io.admin.admin3_id_index_from_local(admin3_local, admin2_recipe_id)#

Index a country’s local admin-3 source against the global spine.

Joins the local admin-3 units to the global (GADM-derived) admin-3 layer by parent admin-2 and cleaned name, applies the country’s name corrections and explicit ID overrides (CSV assets stored beside its admin recipe), and returns the frame indexed by admin3_id.

Wired from a recipe via create_index.function with args: {admin2_recipe_id} (index_function: cannot pass args). The explicit recipe reference also declares the admin-2 data dependency to the flow DAG (recipe-ID keys are edge sources).

Parameters:

  • admin3_local (GeoDataFrame) – Local admin-3 source with at least name and admin2_id_admin1 (and usually name_long and admin3_id_admin1).

  • admin2_recipe_id (str) – Recipe ID of the admin-2 ingest of the same source (e.g. 'US_admin-census-2021_admin2'). Its country and admin entity also locate the crosswalk assets stored beside the recipe.

openplaces.io.admin.fold_to_ascii(text)#

Transliterate text to its closest ASCII representation.

Strips diacritics via NFKD normalization, maps non-decomposing letters (e.g. Đ, Ø, ß) to ASCII equivalents, converts non-ASCII decimal digits (e.g. Arabic-Indic) to ASCII digits, and drops anything else non-ASCII.

Parameters:

text (str) – Input text.

Returns:

ASCII-only version of the input.

Return type:

str

openplaces.io.admin.clean_geographic_name(name, *, na_tokens=ADMIN_NA_TOKENS, prefixes=ADMIN_NAME_PREFIXES, generic_words=ADMIN_GENERIC_WORDS)#

Clean an administrative-unit name into structured components.

Language-agnostic: the vocabulary lists default to the broadened English/Spanish sets in openplaces.core.constants but can be overridden (e.g. per recipe) to support other languages without editing this function.

Parameters:

  • name (str) – Raw administrative-unit name.

  • na_tokens (Iterable[str], optional) – Lower-cased tokens treated as “no name”.

  • prefixes (Iterable[str], optional) – Leading articles/honorifics stripped from the name.

  • generic_words (Iterable[str], optional) – Generic administrative words detected alongside a number.

Returns:

(clean_text, digits, letter_suffix, generic_word).

Return type:

tuple

openplaces.io.admin.generate_admin_ids(df, new_admin_id_col='admin4_id', parent_admin_id_col='admin3_id', name_col='name', id_separator=STRING_SEPARATOR_WITHIN_IDS, name_cleaning=None, verbose=False)#

Generate unique two-letter admin unit codes within parent units.

Generate unique admin ID codes for administrative units

Level-agnostic design: works for any parent-child relationship: admin2->admin3 (state->county), admin3->admin4 (county->town)

Strategy#

Each name is first cleaned into structured components: a text portion, digit portion, letter suffix, and detected generic word. IDs are then assigned through a waterfall of prioritized strategies. Each row moves to the next strategy only if it remains unassigned:

  1. Pure numeric — If the name reduces to only digits with no text (e.g., “N.A. (12)”) use the number directly.

  2. Generic word + number — If a recognized generic word (ward, zone, barangay, district, etc.) is detected alongside a number, prefix the number with the generic word’s initial(s). A letter suffix is appended if present (e.g., “Ward 3B” → “W3B”).

  3. Name + number for duplicates — If the same base name appears multiple times under the same parent and a digit is present, disambiguate by combining the name’s initial(s) with the number (and any letter suffix).

  4. Initials from multi-word names — For names with two or more words, take the first letter of the first two words (e.g., “North East” → “NE”).

  5. First two letters — Take the first two characters of the cleaned name, assigned only where unique within the parent.

  6. Any two letters — Try all pairwise letter combinations from the cleaned name until a unique code is found.

  7. Letter + number combinations — Combine any letter from the name with any digit from the name; fall back to “X” + digit if no letters exist.

  8. Swapping — If a desired two-letter code is taken by another row, check whether that row can be reassigned to an alternative code, freeing up the preferred code for the current row.

  9. Three-letter codes — Try the first three letters, then all three-letter combinations from the name.

  10. Sequential fallback — Assign codes like X01, X02, … (with a

    letter disambiguator if needed) to any rows that all prior strategies failed to place.

After assignment, all IDs are verified to be non-null and globally unique; an exception is raised if either condition is violated.

param df:

Input dataframe with administrative unit data

type df:

pd.DataFrame

param new_admin_id_col:

Name for the new administrative ID column (default ‘admin4_id’)

type new_admin_id_col:

str

param parent_admin_id_col:

Column name containing parent admin ID (e.g., ‘admin3_id’)

type parent_admin_id_col:

str

param name_col:

Column name containing subdivision name

type name_col:

str

param id_separator:

Separator to use in IDs (default STRING_SEPARATOR_WITHIN_IDS)

type id_separator:

str

param name_cleaning:

Overrides forwarded to clean_geographic_name() (e.g. {'prefixes': [...], 'generic_words': [...]}) to support a specific language. Defaults to the broadened English/Spanish vocabulary.

type name_cleaning:

dict, optional

param verbose:

If True, prints statistics and other outputs

type verbose:

bool

returns:

DataFrame indexed by new_admin_id_col with diagnostics column

rtype:

pd.DataFrame

raises ValueError:

If unable to generate unique IDs for all rows

openplaces.io.admin.update_admin_spine(level, admin_recipe_id, test, silent=False)#

Update the openplaces admin spine with admin recipe info

Parameters:

  • level (int) – Administrative level of the spine to update

  • admin_recipe (str) – ID of admin recipe to update the spine with (This function assumes the recipe is already ingested.)

  • test (bool) – If True, writes to ‘{file}_test.csv’ instead of the original

  • silent (bool) – If True, silences printouts when new admin IDs are added.