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 2resolve
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. |