Skip to main content

locations

locations

Resolve user-supplied location names to canonical dataset keys.

Datasets are keyed by a canonical name (Kenya, United_States, Cote_dIvoire), but people write locations every other way: ISO codes (KE, USA), abbreviations (UK, DRC), official names, accented spellings, other languages. This module maps all of them onto the canonical key.

Matching is exact, against a table generated at build time into data/locations.csv (see scripts/build_locations.py). Fuzzy matching is used only to suggest alternatives once an exact match has failed – never to resolve one. That division matters: fuzzy matching cannot reach abbreviations at all (sc.suggest('USA', ...) returns nothing, the edit distance is too large), and it will cheerfully offer candidates for input that corresponds to no location whatsoever. It makes a good error message and a bad lookup.

import starsim_data as ssd
ssd.resolve('USA')            # 'United_States'
ssd.resolve('cote divoire')   # 'Cote_dIvoire'
ssd.resolve('DRC')            # 'Democratic_Republic_of_the_Congo'
ssd.location_info('KE').iso3  # 'KEN'

A subnational unit is named by its country and its name, separated by a colon, as in the node table’s dot_name: 'United States:Massachusetts' and 'USA:massachusetts' both resolve to 'United_States:Massachusetts'. The country part is resolved as above; the unit’s name has to match exactly, up to case, accents and punctuation.

Functions

Name Description
list_all_locations Return every canonical location name known to the package, sorted.
location_info Return the metadata row for a location, as a sciris.objdict.
parse_level Parse an administrative level into an integer.
resolve Resolve a location string to its canonical key.

list_all_locations

locations.list_all_locations()

Return every canonical location name known to the package, sorted.

This is the full location table; use list_locations(which) for the subset actually present in a given dataset.

location_info

locations.location_info(location)

Return the metadata row for a location, as a sciris.objdict.

Parameters

Name Type Description Default
location str location name, ISO-2/ISO-3 code, or alias. required

Returns

Name Type Description
sciris.objdict: with keys location, level, iso_code, iso3,
official_name, aliases, primary_contact_source, contact_sources,
population_source.

Example

import starsim_data as ssd
ssd.location_info('USA').iso3 # Returns 'USA'

parse_level

locations.parse_level(level)

Parse an administrative level into an integer.

Accepts 'admin1', 'ADM2', '3' or a bare int. Level 0 is the country; higher levels are progressively finer subdivisions (1 = state/province, 2 = district/county). The upper bound is 5, the finest level any of the boundary sources in starsim_data.shapes publishes.

Parameters

Name Type Description Default
level str / int the level to parse. required

Returns

Name Type Description
int the level number, 0 to 5.

Raises

Type Description
ValueError if level cannot be parsed or is out of range.

Example

import starsim_data as ssd
ssd.parse_level('ADM2') # Returns 2

resolve

locations.resolve(location, valid=None, dataset=None)

Resolve a location string to its canonical key.

Parameters

Name Type Description Default
location str location name, ISO-2/ISO-3 code, official name, or alias; case-, accent- and punctuation-insensitive. A subnational unit is '<country>:<unit>', e.g. 'United States:Massachusetts'. required
valid collection if given, the resolved key must be one of these (used to scope resolution to the locations actually present in a dataset). None
dataset str name of the dataset valid came from, for error messages only. None

Returns

Name Type Description
str the canonical location key, e.g. 'United_States' or
'United_States:Massachusetts'.

Raises

Type Description
KeyError if the location is unknown, or is known but absent from valid. The message lists close matches where there are any.