Skip to main content

Locations

🧠5% 🤖95%

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']

What is recognized

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:

{name: ssd.locations.normalize(name) for name in
 ["Côte d'Ivoire", "cote divoire", "Cote_dIvoire", "  COTE D'IVOIRE  "]}
{"Côte d'Ivoire": 'cote_divoire',
 'cote divoire': 'cote_divoire',
 'Cote_dIvoire': 'cote_divoire',
 "  COTE D'IVOIRE  ": 'cote_divoire'}
len(set(ssd.resolve(n) for n in ["Côte d'Ivoire", 'cote divoire', 'Ivory Coast', 'CIV']))
1

Resolution is exact; approximate matching only advises

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.

ssd.load('Keyna', which='deaths')
---------------------------------------------------------------------------
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:

import sciris as sc
sc.suggest('Atlantis', ssd.list_all_locations(), n=3, die=False)
['Albania', 'Algeria', 'Argentina']

That is helpful in an error message, but would be wrong as an answer.

Subnational units

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:

[ssd.resolve(name) for name in ['United States:Massachusetts', 'USA:massachusetts', 'us:new york']]
['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).

Scoping to a dataset

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:

ssd.load('Japan', which='prem2021')
---------------------------------------------------------------------------
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')"
len(ssd.list_locations('prem2021')), len(ssd.list_locations('mistry2021'))
(177, 36)

list_locations(which) gives the locations in one dataset, and list_all_locations() gives every location the package knows about.

len(ssd.list_all_locations())
187

Inspecting the table

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'}
ssd.location_info('Germany').aliases[:8]
['Allemagne', 'Alemania', 'Alemanha']

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.

WarningNamibia’s country code

Namibia’s two-letter ISO code is NA, which pandas.read_csv reads as a missing value by default. This package handles it, but if you read country tables with pandas yourself, pass keep_default_na=False to avoid losing Namibia.

ssd.resolve('NA'), ssd.location_info('Namibia').iso3
('Namibia', 'NAM')

Administrative levels

parse_level() accepts the common ways of writing an administrative level and returns a number:

[ssd.parse_level(x) for x in ['admin1', 'ADM2', '3', 4, 'level0']]
[1, 2, 3, 4, 0]

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.

ssd.parse_level('admin9')
---------------------------------------------------------------------------
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:

ssd.parse_level(True)
---------------------------------------------------------------------------
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

Naming below the country level

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:

ssd.load_nodes('France', level=1).dot_name.head(4).tolist()
['France:Ile_de_France',
 'France:Centre_Val_de_Loire',
 'France:Bourgogne_Franche_Comte',
 'France:Normandie']
[ssd.node_name(x) for x in ['New York', 'Île-de-France', 'KwaZulu-Natal']]
['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.