import starsim_data as ssd
[ssd.resolve(name) for name in ['Kenya', 'kenya', 'KE', 'KEN', 'Republic of Kenya']]['Kenya', 'Kenya', 'Kenya', 'Kenya', 'Kenya']
Each location has one standard name in this package, such as Kenya, United_States or Cote_dIvoire, but people write country names in many other ways. This page covers which names are recognized and what happens when one isn’t.
import starsim_data as ssd
[ssd.resolve(name) for name in ['Kenya', 'kenya', 'KE', 'KEN', 'Republic of Kenya']]['Kenya', 'Kenya', 'Kenya', 'Kenya', 'Kenya']
These forms are all recognized:
| Form | Example | Resolves to |
|---|---|---|
| Standard name | United_States |
United_States |
| Free-text name | united states |
United_States |
| ISO 3166-1 alpha-2 | US |
United_States |
| ISO 3166-1 alpha-3 | USA |
United_States |
| Official name | United States of America |
United_States |
| Common abbreviation | DRC, UK, UAE |
the corresponding country |
| Former name | Zaire, Burma |
the current country |
| French, Spanish or Portuguese name | Allemagne, Alemania |
Germany |
Accents, case, punctuation and spacing are ignored, so these are all treated as the same name:
A name has to match one in the table exactly (after ignoring accents, case and punctuation). Close matches are only used to suggest names in the error message; the package never guesses which country you meant.
--------------------------------------------------------------------------- KeyError Traceback (most recent call last) Cell In[4], line 1 ----> 1 ssd.load('Keyna', which='deaths') File ~/work/starsim_data/starsim_data/starsim_data/loaders.py:290, in load(location, which, kind, revision, level) 288 if ds.tier > 0: # `load` never touches the network; say so rather than quietly downloading 289 raise ValueError(f'{which!r} is not bundled; use {ds.function}({location!r}, which={which!r}) to download it') --> 290 return _read(which, location, kind=kind, revision=revision, level=level) File ~/work/starsim_data/starsim_data/starsim_data/loaders.py:311, in _read(which, location, kind, revision, level, path) 309 with f: 310 spec = ssd.registry._spec(group) --> 311 key = ssd.resolve(location, valid=group.keys(), dataset=which) 312 opts = dict(kind=kind, level=level) 313 shape = ssd.registry.get_layout(spec['layout']) File ~/work/starsim_data/starsim_data/starsim_data/locations.py:191, in resolve(location, valid, dataset) 189 return direct[key] 190 if canonical is None: --> 191 raise KeyError(f'location {location!r} not found{_did_you_mean(location, valid)}') 193 # The location is known, but not in this dataset: say so, and where else to find it 194 what = f'{location!r}' KeyError: "location 'Keyna' not found (did you mean: Kenya, China, Ghana?)"
Guessing would go wrong both ways. Abbreviations like USA look nothing like United_States, so they have to be listed in the table rather than guessed. And a name that is no country at all still has close matches:
['Albania', 'Algeria', 'Argentina']
That is helpful in an error message, but would be wrong as an answer.
A subnational unit is named by its country and its own name, separated by a colon, as in the node table’s dot_name. The country part is recognized as above; the unit’s name has to match exactly, ignoring case, accents and punctuation:
['United_States:Massachusetts',
'United_States:Massachusetts',
'United_States:New_York']
When no dataset is given, the units are those of the node table, and a misspelled unit gets suggestions from its own country. Only a few datasets have subnational units so far: mistry2021_us and population_us, for the US states (see Datasets).
Coverage varies between datasets, so load() checks the name against the locations in the dataset you asked for. A country that exists but is missing from that dataset gives a different error from a name that isn’t a country at all:
--------------------------------------------------------------------------- KeyError Traceback (most recent call last) Cell In[7], line 1 ----> 1 ssd.load('Japan', which='prem2021') File ~/work/starsim_data/starsim_data/starsim_data/loaders.py:290, in load(location, which, kind, revision, level) 288 if ds.tier > 0: # `load` never touches the network; say so rather than quietly downloading 289 raise ValueError(f'{which!r} is not bundled; use {ds.function}({location!r}, which={which!r}) to download it') --> 290 return _read(which, location, kind=kind, revision=revision, level=level) File ~/work/starsim_data/starsim_data/starsim_data/loaders.py:311, in _read(which, location, kind, revision, level, path) 309 with f: 310 spec = ssd.registry._spec(group) --> 311 key = ssd.resolve(location, valid=group.keys(), dataset=which) 312 opts = dict(kind=kind, level=level) 313 shape = ssd.registry.get_layout(spec['layout']) File ~/work/starsim_data/starsim_data/starsim_data/locations.py:203, in resolve(location, valid, dataset) 201 hint = f'; see list_locations({dataset!r})' 202 errormsg = f'location {what} is not available{where} ({len(valid)} locations{hint}){_elsewhere(canonical, dataset)}' --> 203 raise KeyError(errormsg) KeyError: "location 'Japan' is not available in 'prem2021' (177 locations; see list_locations('prem2021')); it is in load('Japan') or fetch('Japan', which='mistry2021') or fetch('Japan', which='prem2017')"
list_locations(which) gives the locations in one dataset, and list_all_locations() gives every location the package knows about.
info = ssd.location_info('DRC')
{k: info[k] for k in ['location', 'iso_code', 'iso3', 'official_name']}{'location': 'Democratic_Republic_of_the_Congo',
'iso_code': 'CD',
'iso3': 'COD',
'official_name': 'Congo, The Democratic Republic of the'}
The table itself is starsim_data/data/locations.csv, with official names and aliases taken from the pycountry package. Any alias that could mean two different locations is left out, so a name that matches always means just one.
parse_level() accepts the common ways of writing an administrative level and returns a number:
Level 0 is the country, level 1 its first subdivisions (provinces, states), and so on. The highest is 5, the finest level any of the boundary sources in Data sources publishes.
--------------------------------------------------------------------------- ValueError Traceback (most recent call last) Cell In[14], line 1 ----> 1 ssd.parse_level('admin9') File ~/work/starsim_data/starsim_data/starsim_data/locations.py:280, in parse_level(level) 278 number = int(text) 279 if not (0 <= number <= MAX_LEVEL): --> 280 raise ValueError(f'administrative level {number} out of range (0 to {MAX_LEVEL})') 281 return number ValueError: administrative level 9 out of range (0 to 5)
True and False are rejected, rather than quietly read as levels 1 and 0:
--------------------------------------------------------------------------- ValueError Traceback (most recent call last) Cell In[15], line 1 ----> 1 ssd.parse_level(True) File ~/work/starsim_data/starsim_data/starsim_data/locations.py:267, in parse_level(level) 244 """Parse an administrative level into an integer. 245 246 Accepts `'admin1'`, `'ADM2'`, `'3'` or a bare `int`. Level 0 is the country; (...) 264 ``` 265 """ 266 if isinstance(level, bool): # bool is an int subclass; not a level --> 267 raise ValueError(f'invalid administrative level {level!r}') 268 if isinstance(level, int): 269 number = level ValueError: invalid administrative level True
Subnational units in the node table are named by their dot_name, the country and unit names joined by a colon, cleaned up the same way but keeping capitals:
['France:Ile_de_France',
'France:Centre_Val_de_Loire',
'France:Bourgogne_Franche_Comte',
'France:Normandie']
['New_York', 'Ile_de_France', 'KwaZulu_Natal']
The part before the colon is always a name load() accepts, so you can split a dot_name and look up its country directly. To join to other data, though, use pcode rather than dot_name; see Spatial data.