# 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.

``` python
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:

``` python
{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'}

``` python
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.

``` python
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:

``` python
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:

``` python
[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](datasets.md#us-states)).

## Scoping to a dataset

Coverage varies between datasets, so [load()](../api/loaders.md#starsim_data.loaders.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:

``` python
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')"

``` python
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()](../api/locations.md#starsim_data.locations.list_all_locations) gives every location the package knows about.

``` python
len(ssd.list_all_locations())
```

    187

## Inspecting the table

``` python
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'}

``` python
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.

> **Warning: Namibia'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.
>
> ``` python
> ssd.resolve('NA'), ssd.location_info('Namibia').iso3
> ```
>
>     ('Namibia', 'NAM')

## Administrative levels

[parse_level()](../api/locations.md#starsim_data.locations.parse_level) accepts the common ways of writing an administrative level and returns a number:

``` python
[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](datasources.md) publishes.

``` python
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:

``` python
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:

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

``` python
[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()](../api/loaders.md#starsim_data.loaders.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](spatial.md).
