hdx.location.adminlevel

Classes

AdminLevel — AdminLevel class which takes in p-codes and then maps names to those p-codes with fuzzy matching if necessary.

class AdminLevel(admin_config: dict | None = None, admin_level: int = 1, admin_level_overrides: dict | None = None, retriever: Retrieve | None = None)

AdminLevel class which takes in p-codes and then maps names to those p-codes with fuzzy matching if necessary.

The dictionary admin_config, which defaults to an empty dictionary, can have the following optional keys: countries_fuzzy_try are countries (iso3 codes) for which to try fuzzy matching. Default is all countries. admin_name_mappings is a dictionary of mappings from name to p-code (for where fuzzy matching fails) admin_name_replacements is a dictionary of textual replacements to try when fuzzy matching admin_fuzzy_dont is a list of names for which fuzzy matching should not be tried

The admin_level_overrides parameter allows manually overriding the returned admin level for given countries. It is a dictionary with iso3s as keys and admin level numbers as values.

The retriever parameter accepts an object of type Retrieve (or inherited classes). It is used to allow either that admin data from urls is saved to files or to enable already saved files to be used instead of downloading from urls.

Parameters

admin_config : dict | None — Configuration dictionary. Defaults to {}.
admin_level : int — Admin level. Defaults to 1.
admin_level_overrides : dict | None — Countries at other admin levels.
retriever : Retrieve | None — Retriever object to use for loading/saving files.

Methods

looks_like_pcode — Check if a string looks like a p-code using regex matching of format. Checks for 2 or 3 letter country iso code at start and then numbers.
set_default_admin_url — Set default admin URL from which to retrieve admin data
setup_from_iterable — Setup p-codes from an Iterable such as an Iterator or Sequence
setup_from_url — Setup p-codes from a URL. Defaults to global p-codes dataset on HDX.
load_pcode_formats_from_iterable — Load p-code formats from an Iterable such as an Iterator or Sequence
load_pcode_formats — Load p-code formats from a URL. Defaults to global p-codes dataset on HDX.
set_parent_admins — Set parent admins
set_parent_admins_from_adminlevels — Set parent admins from AdminLevel objects
get_pcode_list — Get list of all pcodes
get_admin_level — Get admin level for country
get_pcode_length — Get pcode length for country
init_matches_errors — Initialise storage of fuzzy matches, ignored and errors for logging purposes
convert_admin_pcode_length — Standardise pcode length by country and match to an internal pcode. Requires that p-code formats be loaded (eg. using load_pcode_formats)
convert_admin1_pcode_length — Standardise pcode length by country and match to an internal pcode. Only works for admin1 pcodes.
get_admin_name_replacements — Get relevant admin name replacements from admin name replacements which is a dictionary of mappings from string to string replacement. These can be global or they can be restricted by country or parent (if the AdminLevel object has been set up with parents). Keys take the form "STRING_TO_REPLACE", "AFG|STRING_TO_REPLACE" or "AF01|STRING_TO_REPLACE".
get_admin_fuzzy_dont — Get relevant admin names that should not be fuzzy matched from admin fuzzy dont which is a list of strings. These can be global or they can be restricted by country or parent. Keys take the form "DONT_MATCH", "AFG|DONT_MATCH", or "AF01|DONT_MATCH".
fuzzy_pcode — Fuzzy match name to pcode
get_name_mapped_pcode — Get pcode from admin name mappings which is a dictionary of mappings from name to pcode. These can be global or they can be restricted by country or parent (if the AdminLevel object has been set up with parents). Keys take the form "MAPPING", "AFG|MAPPING" or "AF01|MAPPING".
get_pcode — Get pcode for a given name
output_matches — Output log of matches
output_ignored — Output log of ignored
output_errors — Output log of errors
output_admin_name_mappings — Output log of name mappings
output_admin_name_replacements — Output log of name replacements

classmethod AdminLevel.looks_like_pcode(string: str) → bool

Check if a string looks like a p-code using regex matching of format. Checks for 2 or 3 letter country iso code at start and then numbers.

Parameters

string : str — String to check

Returns

bool — Whether string looks like a p-code

classmethod AdminLevel.set_default_admin_url(admin_url: str | None = None) → None

Set default admin URL from which to retrieve admin data

Parameters

admin_url : str | None — Admin URL from which to retrieve admin data. Defaults to internal value.

Returns

None — None

method AdminLevel.setup_from_iterable(iterable: Iterable[dict], countryiso3s: Sequence[str] | None = None) → None

Setup p-codes from an Iterable such as an Iterator or Sequence

Parameters

iterable : Iterable[dict] — Iterable such as an Iterator or Sequence
countryiso3s : Sequence[str] | None — Countries to read. Defaults to None (all).

Returns

None — None

method AdminLevel.setup_from_url(admin_url: Path | str | None = None, countryiso3s: Sequence[str] | None = None) → None

Setup p-codes from a URL. Defaults to global p-codes dataset on HDX.

Parameters

admin_url : Path | str | None — URL from which to load data. Defaults to global p-codes dataset.
countryiso3s : Sequence[str] | None — Countries to read. Defaults to None (all).

Returns

None — None

Raises

ValueError

method AdminLevel.load_pcode_formats_from_iterable(iterable: Iterable) → None

Load p-code formats from an Iterable such as an Iterator or Sequence

Parameters

iterable : Iterable — Iterable such as an Iterator or Sequence

Returns

None — None

method AdminLevel.load_pcode_formats(formats_url: Path | str | None = None) → None

Load p-code formats from a URL. Defaults to global p-codes dataset on HDX.

Parameters

formats_url : Path | str | None — URL from which to load data. Defaults to global p-codes dataset.

Returns

None — None

Raises

ValueError

method AdminLevel.set_parent_admins(parent_admins: list[list]) → None

Set parent admins

Parameters

parent_admins : list[list] — List of P-codes per parent admin

Returns

None — None

method AdminLevel.set_parent_admins_from_adminlevels(adminlevels: list['AdminLevel']) → None

Set parent admins from AdminLevel objects

Parameters

adminlevels : list['AdminLevel'] — List of parent AdminLevel objects

Returns

None — None

method AdminLevel.get_pcode_list() → list[str]

Get list of all pcodes

Returns

list[str] — List of pcodes

method AdminLevel.get_admin_level(countryiso3: str) → int

Get admin level for country

Parameters

countryiso3 : str — ISO3 country code

Returns

int — Admin level

method AdminLevel.get_pcode_length(countryiso3: str) → int | None

Get pcode length for country

Parameters

countryiso3 : str — ISO3 country code

Returns

int | None — Country's pcode length or None

method AdminLevel.init_matches_errors() → None

Initialise storage of fuzzy matches, ignored and errors for logging purposes

Returns

None — None

method AdminLevel.convert_admin_pcode_length(countryiso3: str, pcode: str, **kwargs: Any) → str | None

Standardise pcode length by country and match to an internal pcode. Requires that p-code formats be loaded (eg. using load_pcode_formats)

Parameters

countryiso3 : str — ISO3 country code
pcode : str — P code to match
**kwargs : Any — See below
parent : str — Parent admin code
logname : str — Log using this identifying name. Defaults to not logging.

Returns

str | None — Matched P code or None if no match

method AdminLevel.convert_admin1_pcode_length(countryiso3: str, pcode: str, logname: str | None = None) → str | None

Standardise pcode length by country and match to an internal pcode. Only works for admin1 pcodes.

Parameters

countryiso3 : str — ISO3 country code
pcode : str — P code for admin one to match
logname : str | None — Identifying name to use when logging. Defaults to None (don't log).

Returns

str | None — Matched P code or None if no match

method AdminLevel.get_admin_name_replacements(countryiso3: str, parent: str | None) → dict[str, str]

Get relevant admin name replacements from admin name replacements which is a dictionary of mappings from string to string replacement. These can be global or they can be restricted by country or parent (if the AdminLevel object has been set up with parents). Keys take the form "STRING_TO_REPLACE", "AFG|STRING_TO_REPLACE" or "AF01|STRING_TO_REPLACE".

Parameters

countryiso3 : str — ISO3 country code
parent : str | None — Parent admin code

Returns

dict[str, str] — Relevant admin name replacements

method AdminLevel.get_admin_fuzzy_dont(countryiso3: str, parent: str | None) → list[str]

Get relevant admin names that should not be fuzzy matched from admin fuzzy dont which is a list of strings. These can be global or they can be restricted by country or parent. Keys take the form "DONT_MATCH", "AFG|DONT_MATCH", or "AF01|DONT_MATCH".

Parameters

countryiso3 : str — ISO3 country code
parent : str | None — Parent admin code

Returns

list[str] — Relevant admin names that should not be fuzzy matched

method AdminLevel.fuzzy_pcode(countryiso3: str, name: str, normalised_name: str, **kwargs: Any) → str | None

Fuzzy match name to pcode

Parameters

countryiso3 : str — ISO3 country code
name : str — Name to match
normalised_name : str — Normalised name
**kwargs : Any — See below
parent : str — Parent admin code
logname : str — Log using this identifying name. Defaults to not logging.

Returns

str | None — Matched P code or None if no match

method AdminLevel.get_name_mapped_pcode(countryiso3: str, name: str, parent: str | None) → str | None

Get pcode from admin name mappings which is a dictionary of mappings from name to pcode. These can be global or they can be restricted by country or parent (if the AdminLevel object has been set up with parents). Keys take the form "MAPPING", "AFG|MAPPING" or "AF01|MAPPING".

Parameters

countryiso3 : str — ISO3 country code
name : str — Name to match
parent : str | None — Parent admin code

Returns

str | None — P code match from admin name mappings or None if no match

method AdminLevel.get_pcode(countryiso3: str, name: str, fuzzy_match: bool = True, fuzzy_length: int = 4, **kwargs: Any) → tuple[str | None, bool]

Get pcode for a given name

Parameters

countryiso3 : str — ISO3 country code
name : str — Name to match
fuzzy_match : bool — Whether to try fuzzy matching. Defaults to True.
fuzzy_length : int — Minimum length for fuzzy matching. Defaults to 4.
**kwargs : Any — See below
parent : str — Parent admin code
logname : str — Log using this identifying name. Defaults to not logging.

Returns

tuple[str | None, bool] — (Matched P code or None if no match, True if exact match or False if not)

method AdminLevel.output_matches() → list[str]

Output log of matches

Returns

list[str] — List of matches

method AdminLevel.output_ignored() → list[str]

Output log of ignored

Returns

list[str] — List of ignored

method AdminLevel.output_errors() → list[str]

Output log of errors

Returns

list[str] — List of errors

method AdminLevel.output_admin_name_mappings() → list[str]

Output log of name mappings

Returns

list[str] — List of mappings

method AdminLevel.output_admin_name_replacements() → list[str]

Output log of name replacements

Returns

list[str] — List of name replacements