# locations

[locations](../api/locations.md#starsim_data.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.

``` python
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](#starsim_data.locations.list_all_locations) | Return every canonical location name known to the package, sorted. |
| [location_info](#starsim_data.locations.location_info) | Return the metadata row for a location, as a `sciris.objdict`. |
| [parse_level](#starsim_data.locations.parse_level) | Parse an administrative level into an integer. |
| [resolve](#starsim_data.locations.resolve) | Resolve a location string to its canonical key. |

### list_all_locations

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

``` python
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](../api/registry.md#starsim_data.registry.Dataset.level), `iso_code`, `iso3`, |
|  |  | `official_name`, `aliases`, `primary_contact_source`, `contact_sources`, |
|  |  | `population_source`. |

#### Example

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

### parse_level

``` python
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](../api/shapes.md#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](../api/registry.md#starsim_data.registry.Dataset.level) cannot be parsed or is out of range. |

#### Example

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

### resolve

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