pyvoa.geo

Geographical normalisation and country geometries.

GeoManager translates between the naming normalisations of countries, built on the pycountry module. GeoInfo adds statistical fields about countries to a pandas DataFrame. GeoRegion returns the list of countries of a given region. GeoCountry manages the subregions, regions and geometries of a single country.

Project : pyvoa Authors : Tristan Beau, Julien Browaeys, Olivier Dadoun Copyright ©pyvoa_org License : see the joint LICENSE file https://pyvoa.org/

class pyvoa.geo.GeoManager(standard=_list_standard[0])

Bases: object

GeoManager class for managing geographical data and standardization.

This class provides functionality to manage geographical regions, convert country names to standardized formats, and handle various output types. It supports multiple standards for country names and integrates with different databases for name translation.

Variables:

• _list_standard (list) – List of supported standard names for countries.

• _list_db (list) – List of supported database names for country name translation.

• _list_output (list) – List of supported output types.

• _standard (str) – Currently used normalization standard.

__init__(standard=_list_standard[0])

Initialize a GeoManager instance.

This constructor initializes a GeoManager object, setting the standard to a specified value or a default from the _list_standard. It also creates a GeoRegion instance for managing geographical data.

Parameters:

standard (optional) – The standard to be set for the GeoManager. Defaults to the first element of _list_standard.

Raises:

• Any relevant exceptions that may arise during initialization or –

• setting the standard. –

get_GeoRegion()

Return the geographical region associated with the instance.

Returns:

The geographical region (_gr) of the instance.

Return type:

GeoRegion

get_region_list()

Retrieve a list of regions.

This method calls the underlying service to obtain a list of regions.

Returns:

A list containing the regions.

Return type:

list

get_list_standard()

Return the standard list.

This method retrieves the supported list of standard name of countries.

Returns:

The standard list. First one is default for the class.

Return type:

list

get_list_output()

Return the list output.

This method retrieves the value of the private attribute _list_output.

Returns:

The current value of _list_output. The first element is the the default one

Return type:

list

get_list_db()

Return the list database.

This method retrieves the internal list database stored in the instance.

Returns:

The list database.

Return type:

list

get_standard()

Return the standard country names are converted to.

Returns:

One of ‘iso2’, ‘iso3’, ‘name’ and ‘num’, as set at construction or by set_standard(). The default is ‘iso2’.

Return type:

str

set_standard(standard)

Set the working standard type within the GeoManager class.

This method ensures that the specified standard meets the requirements defined by the get_list_standard() method. If the provided standard is not a string or is not in the list of valid standards, appropriate exceptions are raised.

Parameters:

standard (str) – The standard type to be set for the GeoManager.

Raises:

• PyvoaError – If the standard argument is not a string.

• PyvoaError – If the standard is not managed or recognized.

Returns:

The current standard after setting it.

Return type:

str

to_standard(w, **kwargs)

Convert input location names to standardized forms based on specified parameters.

Parameters:

• w (str or list of str) – The location names to be standardized. Can be a single string or a list of strings.

• **kwargs – Additional keyword arguments. - output (str): The format of the output. Options include ‘list’, ‘dict’, or ‘pandas’. Defaults to the first item from the list of available outputs. - db (str): The database to use for translation. Defaults to the first item from the list of available databases. - interpret_region (bool): If True, interprets region names and expands them to their corresponding countries. Defaults to False.

Raises:

• PyvoaError – If an incorrect output type or incompatible arguments are provided.

• PyvoaError – If an unknown database is specified.

• PyvoaError – If the input types are incorrect.

• PyvoaError – If no country matches the provided key.

• PyvoaError – If an unexpected error occurs during processing.

Returns:

list or dict or pandas.DataFrame

Return type:

The standardized location names in the specified output format.

first_db_translation(w, db)

Generate translations for country names based on the specified database.

Parameters:

• w (list) – A list of country names to be translated.

• db (str) – The database to use for translations. Supported values are: - ‘jhu’: Johns Hopkins University database. - ‘worldometers’: Worldometers database. - ‘owid’: Our World in Data database.

Returns:

A list of translated country names corresponding to the input list. If a country name does not have a translation in the specified database, the original name is returned.

Return type:

list

class pyvoa.geo.GeoInfo(gm=0)

Bases: object

GeoInfo class for managing geographical information.

This class provides methods to retrieve and manipulate geographical data, including country demographics, geographical boundaries, and additional fields related to countries.

Variables:

• _list_field (dict) – A dictionary mapping field names to their respective data sources.

• _data_geometry (pd.DataFrame) – DataFrame containing geographical data.

• _data_population (pd.DataFrame) – DataFrame containing population data.

• _data_flag (pd.DataFrame) – DataFrame containing flag data.

__init__(gm=0)

Initialise a GeoInfo instance.

This constructor initializes the GeoInfo object. If a GeoManager instance is provided, it is used; otherwise, a new GeoManager is created. The group data is then retrieved from the GeoManager and stored in the instance.

Parameters:

gm (GeoManager, optional) – An instance of GeoManager. Defaults to 0, which triggers the creation of a new GeoManager.

Variables:

• _gm (GeoManager) – The GeoManager instance used by this GeoInfo.

• _grp (pandas.DataFrame) – The group data retrieved from the GeoManager.

get_GeoManager()

Return the GeoManager instance.

This method retrieves the GeoManager object associated with the current instance.

Returns:

The GeoManager instance.

Return type:

GeoManager

get_list_field()

Return a sorted list of the keys from the _list_field dictionary.

This method retrieves the keys from the _list_field attribute, which is expected to be a dictionary, and returns them as a sorted list.

Returns:

A sorted list of keys from the _list_field dictionary.

Return type:

list

get_source(field=None)

Retrieve the source information for a specified field.

Parameters:

field (str, optional) – The name of the field for which to retrieve the source information. If None, the method returns the entire list of fields.

Returns:

The source information for the specified field, or the entire list of fields if no field is specified.

Return type:

str

Raises:

PyvoaError – If the specified field is not a supported field of GeoInfo.

Examples

source_info = get_source(‘example_field’) all_fields = get_source()

add_field(**kwargs)

Add specified fields to a pandas DataFrame based on geographical data.

This method allows the user to add various fields to a given pandas DataFrame, including country-related information such as continent codes, population, area, and more. The function validates input parameters and ensures that the specified fields are supported and do not conflict with existing DataFrame columns unless the overload option is set to True.

Parameters:

**kwargs – Keyword arguments that can include: - field (list or str): The field(s) to add to the DataFrame. Must be valid fields supported by the class. - input (pd.DataFrame): The input pandas DataFrame to which fields will be added. Must be a valid DataFrame. - geofield (str): The name of the column in the DataFrame that contains geographical identifiers (e.g., country codes). - overload (bool): If True, allows overwriting existing fields in the DataFrame. Defaults to False.

Raises:

• PyvoaError – If the input DataFrame is not valid or if overload is not a boolean.

• PyvoaError – If no field is provided, if any specified fields are invalid, or if the geofield is not a valid column in the DataFrame.

• PyvoaError – If the worldometers database field names have changed and cannot be matched.

Returns:

The modified DataFrame with the specified fields added.

Return type:

pd.DataFrame

Notes

The ‘geometry’ field comes from the 2008 TM_WORLD_BORDERS file, which predates the dissolution of the Netherlands Antilles: Curaçao, Sint Maarten and the Caribbean Netherlands (CUW, SXM, BES) are given an empty geometry, so that their data join and are counted, though not drawn.

class pyvoa.geo.GeoRegion

Bases: object

Class representing geographical regions and their associated countries.

This class provides functionality to manage and retrieve information about various geographical regions, including their member countries. It initializes with data sourced from various online references and allows users to query regions, check if a name corresponds to a region, and retrieve lists of countries belonging to specific regions.

Variables:

• _source_dict (dict) – A dictionary containing URLs for various geographical data sources.

• _region_dict (dict) – A dictionary mapping region codes to region names.

• _p_gs (DataFrame) – A pandas DataFrame containing geographical data including country codes and region associations.

__init__()

Initialize a GeoRegion instance.

This constructor fetches and processes geographical region data from various sources, including the United Nations M49 standard and several Wikipedia pages. It populates internal dictionaries and lists with region names, codes, and other relevant information.

Variables:

• _region_dict (dict) – A dictionary mapping region codes to region names.

• _cw (list) – A list of countries that are members of the Commonwealth of Nations.

• _celac (list) – A list of countries that are members of the Community of Latin American and Caribbean States.

• _cedeao (list) – A list of countries that are members of the Economic Community of West African States.

• _sadc (list) – A list of countries that are members of the Southern African Development Community.

• _amu (list) – A list of countries that are members of the Arab Maghreb Union.

• _ceeac (list) – A list of countries that are members of the Economic Community of Central African States.

• _eac (list) – A list of countries that are members of the East African Community.

• _censad (list) – A list of countries that are members of the Community of Sahel–Saharan States.

• _comesa (list) – A list of countries that are members of the Common Market for Eastern and Southern Africa.

• _p_gs (DataFrame) – A DataFrame containing country information including ISO codes, capitals, and region codes.

• Logs – Verbose logging of the initialization process is performed, including the calling stack.

get_source()

Return the source dictionary.

This method retrieves the internal source dictionary associated with the instance.

Returns:

The source dictionary.

Return type:

dict

get_region_list()

Return a list of regions.

This method retrieves all the values from the internal region dictionary and returns them as a list.

Returns:

A list containing the regions.

Return type:

list

is_region(region)

Check if the provided region is valid.

Parameters:

region (str) – The region to be checked.

Raises:

PyvoaError – If the provided region is not of type str.

Returns:

True if the region is valid, False otherwise.

Return type:

bool

get_countries_from_region(region)

Retrieve a list of country codes from a specified region.

This method checks if the provided region is valid and returns a sorted list of country codes (ISO 3166-1 alpha-3) associated with that region. If the region is not recognized, a PyvoaError is raised.

Parameters:

region (str) – The name of the region for which to retrieve country codes. Valid regions include ‘European Union’, ‘G7’, ‘G8’, ‘G20’, ‘Oecd’, ‘G77’, ‘Commonwealth’, ‘Celac’, ‘Cedeao’, ‘Sadc’, ‘Amu’, ‘Ceeac’, ‘Eac’, ‘Censad’, ‘Comesa’, and ‘Brics’.

Raises:

PyvoaError – If the provided region is unknown.

Returns:

• list – A sorted list of country codes corresponding to the specified region.

• Examples (...)

get_pandas()

Return the pandas object.

This method retrieves the pandas object stored in the instance.

Returns:

The pandas object associated with the instance.

Return type:

pandas.DataFrame

class pyvoa.geo.GeoCountry(country=None)

Bases: object

A class to handle geographical data for various countries.

This class provides functionalities to manage and manipulate geographical data for different countries, including retrieving country-specific information, handling geometries, and accessing subregions and regions.

Variables:

• _country_info_dict (dict) – A dictionary mapping country ISO3 codes to their respective data source URLs.

• _source_dict (dict) – A dictionary mapping country ISO3 codes to their respective data sources and additional information.

__init__(country=None)

Initialize the class with country-specific data.

Parameters:

country (str, optional) – The country code for which to initialize data. If None, no country data is loaded. Supported country codes include: ‘FRA’ for France, ‘USA’ for the United States, ‘ITA’ for Italy, ‘IND’ for India, ‘DEU’ for Germany, ‘ESP’ for Spain, ‘GBR’ for the United Kingdom, ‘BEL’ for Belgium, ‘PRT’ for Portugal, ‘MYS’ for Malaysia, ‘CHL’ for Chile, ‘EUR’ for Europe, ‘GRC’ for Greece, ‘JPN’ for Japan and ‘COD’ for the Democratic Republic of the Congo.

Raises:

PyvoaError – If the provided country code is not supported.

Variables:

• _country_data (GeoDataFrame) – A GeoDataFrame containing geographical and demographic data for the specified country.

• _country_data_region (str) – The region data for the country.

• _country_data_subregion (str) – The subregion data for the country.

• _municipality_region (str) – The municipality region data.

• _is_dense_geometry (bool) – Flag indicating if the geometry is dense.

• _is_exploded_geometry (bool) – Flag indicating if the geometry is exploded.

• _is_main_geometry (bool) – Flag indicating if the geometry is the main one.

• _list_translation (dict) – A dictionary mapping subregion codes to translation coordinates.

• _list_scale (dict) – A dictionary mapping subregion codes to scale factors.

• _list_center (dict) – A dictionary mapping subregion codes to center coordinates.

set_dense_geometry()

Draw the subregions and regions of the current country densely.

The overseas parts of a country are translated and scaled to sit beside the mainland instead of at their true coordinates, so that the whole country fits one readable map. Only France and the USA have such a geometry.

Raises:

PyvoaError – If the main or the exploded geometry has already been chosen, or if the current country has no dense geometry.

Notes

The three geometries – dense, exploded, main – exclude one another, and the choice cannot be undone: build a new GeoCountry to start over.

set_exploded_geometry()

Draw the current country densely, and blow up its crowded part.

Adds to set_dense_geometry() a second displacement, of the subregions too small and too tightly packed to be readable at the scale of the country – the Paris region, for France, which is the only country this applies to.

Raises:

PyvoaError – If the main or the dense geometry has already been chosen.

Notes

The three geometries – dense, exploded, main – exclude one another, and the choice cannot be undone: build a new GeoCountry to start over.

set_main_geometry()

Draw the mainland of the current country only.

Drops the overseas subregions from the geography rather than moving them, which set_dense_geometry() does. Only France and the USA have such a geometry.

Raises:

PyvoaError – If the dense or the exploded geometry has already been chosen, or if the current country has no main geometry of its own.

Notes

The three geometries – dense, exploded, main – exclude one another, and the choice cannot be undone: build a new GeoCountry to start over.

is_dense_geometry()

Determine if the geometry is dense.

Returns:

True if the geometry is dense, False otherwise.

Return type:

bool

is_exploded_geometry()

Determine if the geometry is exploded.

Returns:

True if the geometry is exploded, False otherwise.

Return type:

bool

is_main_geometry()

Determine if the current geometry is the main geometry.

Returns:

True if the current geometry is the main geometry, False otherwise.

Return type:

bool

get_source()

Retrieve the source data based on the country.

If a country is set, it returns the corresponding source from the source dictionary. If no country is set, it returns the entire source dictionary.

Returns:

The source data corresponding to the country, or the entire source dictionary if no country is set.

Return type:

dict

get_country()

Return the country associated with the instance.

This method retrieves the value of the private attribute _country.

Returns:

The country associated with the instance.

Return type:

str

get_list_countries()

Return a sorted list of country names.

This method retrieves the keys from the internal dictionary that contains country information and returns them as a sorted list.

Returns:

A sorted list of country names.

Return type:

list

is_init()

Determine if the object is initialized based on the country attribute.

Returns:

True if the country is not None, indicating the object is initialized; False otherwise.

Return type:

bool

test_is_init()

Test if the object is initialized.

This method checks whether the object has been properly initialized. If the object is initialized, it returns True. Otherwise, it raises a PyvoaError indicating that the country is not set.

Raises:

PyvoaError – If the object is not initialized with a non-empty country string.

Returns:

True if the object is initialized, otherwise an exception is raised.

Return type:

bool

get_region_list()

Retrieve a list of regions along with their geometries.

This method filters the properties of the object to include only those that contain ‘_region’ in their names, and appends the ‘geometry’ property to the list. It then returns the corresponding data for these properties.

Returns:

• DataFrame – A DataFrame containing the filtered list of regions and their

• geometries.

is_region(r)

Check if a given region exists in the region list.

Parameters:

r (str) – The region to check, which will be standardized before comparison.

Returns:

• str or bool (The name of the region if it exists in the region list,)

• otherwise returns False.

get_subregion_list()

Retrieve a list of subregion data along with their geometries.

This method filters the properties of the object to find those that contain the substring ‘_subregion’ and appends the ‘geometry’ property to the list. It then returns a DataFrame containing only the selected columns.

Returns:

A DataFrame containing the subregion properties and their corresponding geometries.

Return type:

DataFrame

is_subregion(r)

Determine if a given region is a subregion of the current object.

Parameters:

r (str) – The region code or name to check against the subregions.

Returns:

str or bool

Return type:

The name of the subregion if found, otherwise False.

Notes

This function first converts the input region to a standardized string format. It then checks if the standardized input matches any of the names in the subregion list. If a match is found, it returns the corresponding name. If no match is found, it checks if the input region code corresponds to a single subregion and returns its name if so.

get_subregions_from_region(**kwargs)

Retrieve subregions based on the specified region name or code.

This method allows you to obtain subregions from a specified region by providing either the region’s name or code. The output can be customized to return either the code or name of the subregion.

Parameters:

**kwargs – Keyword arguments that can include: - name (str): The name of the region. Must be provided as a string. - code (str): The code of the region. Must be provided as a string. - output (str): Specifies the output format. Should be either ‘code’ or ‘name’. Defaults to ‘code’.

Raises:

• PyvoaError – If both name and code are provided, or if neither is provided.

• PyvoaError – If the provided name or code is not a string.

• PyvoaError – If the specified region does not exist for the country.

Returns:

The subregion corresponding to the specified region, in the format specified by the output argument.

Return type:

str

get_subregions_from_list_of_region_names(lnames, output='code')

Retrieve subregions for a list of region names.

Parameters:

• lnames (list) – A list of region names for which to retrieve subregions.

• output (str, optional) – The format of the output. Defaults to ‘code’.

Raises:

PyvoaError – If the provided argument is not a list.

Returns:

A list of subregions corresponding to the provided region names.

Return type:

list

get_regions_from_subregion(code, output='code')

Retrieve regions associated with a specified subregion code.

This method checks if the provided subregion code exists and returns a list of regions that are linked to that subregion. The output can be either the region codes or the region names based on the specified output parameter.

Parameters:

• code (str) – The subregion code for which to retrieve associated regions.

• output (str, optional) – The format of the output. Can be ‘code’ for region codes or ‘name’ for region names. Defaults to ‘code’.

Raises:

• PyvoaError – If the output option is not ‘code’ or ‘name’.

• PyvoaError – If the specified subregion code does not exist for the current country.

Returns:

A list of unique regions associated with the specified subregion code, either as codes or names based on the output parameter.

Return type:

list

get_regions_from_list_of_subregion_codes(lcodes, output='code')

Return a list of regions corresponding to a given list of subregion codes.

This function takes a list of subregion codes and retrieves the associated regions. The output parameter, which defaults to ‘code’, is passed to the get_regions_from_subregion function to determine the format of the returned regions.

Parameters:

• lcodes (list) – A list of subregion codes.

• output (str, optional) – The format for the output from get_regions_from_subregion. Defaults to ‘code’.

Raises:

PyvoaError – If the provided argument is not a list.

Returns:

A list of unique regions corresponding to the provided subregion codes.

Return type:

list

get_regions_from_macroregion(**kwargs)

Retrieve regions from a specified macroregion based on either the region’s name or code.

This method allows the user to obtain a list of regions that belong to a specified macroregion. The user must provide either the name or the code of the region, and can specify the desired output format (either ‘code’ or ‘name’).

Parameters:

**kwargs – Keyword arguments that can include: - ‘name’ (str): The name of the region. - ‘code’ (str): The code of the region. - ‘output’ (str): The desired output format, either ‘code’ or ‘name’. Defaults to ‘code’.

Raises:

• PyvoaError – If both ‘name’ and ‘code’ are provided, or if neither is provided.

• PyvoaError – If ‘output’ is not set to either ‘code’ or ‘name’.

Returns:

A list of regions associated with the specified macroregion, including the input region.

Return type:

list

get_list_properties()

Return the properties the current country geography carries.

Returns:

The column names of the country data, sorted, or None if no country has been selected. They are the fields add_field() can add.

Return type:

list of str or None

from_subregion_codes_to_names(codes)

Convert a list of codes to their corresponding names.

This method takes a list of codes and returns a list of names that correspond to those codes based on the country data. It checks if the object is initialized before performing the conversion.

Parameters:

codes (list) – A list of codes to be converted to names.

Returns:

A list of names corresponding to the provided codes, in the same order, if exist, otherwise PyvoaError

Return type:

list

from_subregion_names_to_codes(names)

Convert a list of names to their corresponding codes.

This method takes a list of names and returns a list of codes that correspond to those names based on the country data. It checks if the object is initialized before performing the conversion.

Parameters:

names (list) – A list of names to be converted to codes.

Returns:

A list of codes corresponding to the provided names, in the same order, if they exist, otherwise PyvoaError.

Return type:

list

from_region_names_to_codes(names)

Convert a list of region names to their corresponding codes.

This method takes a list of region names and returns a list of codes that correspond to those names based on the country data. It checks if the object is initialized before performing the conversion.

Parameters:

names (list) – A list of region names to be converted to codes.

Returns:

A list of codes corresponding to the provided names, in the same order, if they exist, otherwise PyvoaError.

Return type:

list

from_region_codes_to_names(codes)

Convert a list of region codes to their corresponding names.

This method takes a list of region codes and returns a list of names that correspond to those codes based on the country data. It checks if the object is initialized before performing the conversion.

Parameters:

codes (list) – A list of region codes to be converted to names.

Returns:

A list of names corresponding to the provided codes, in the same order, if they exist, otherwise PyvoaError.

Return type:

list

get_data(region_version=False)

Retrieve country data based on the specified region version.

This method checks if the class is initialized and retrieves either region-level or subregion-level data from the internal country data. If region_version is set to True, it processes the data to include region-specific information, handling special cases for certain countries. If region_version is False, it returns subregion-level data.

Parameters:

region_version (bool) – If True, retrieves region-level data; if False, retrieves subregion-level data. Default is False.

Returns:

A DataFrame containing either region-level or subregion-level country data, depending on the value of region_version.

Return type:

pd.DataFrame

Raises:

ValueError – If the class is not initialized or if the data cannot be processed correctly.

add_field(**kwargs)

Add a field to a pandas DataFrame by merging it with additional data based on specified parameters.

Parameters:

**kwargs – Keyword arguments that include: - input (pd.DataFrame): The input pandas DataFrame to which the field will be added. - field (list or str): The field(s) to be added. Can be a single string or a list of strings. - input_key (str): The column name in the input DataFrame to join on. Defaults to ‘where’. - geofield (str): The column name in the additional data to join on. Defaults to ‘code_subregion’. - region_merging (bool, optional): Indicates whether to merge based on region. Defaults to None, which infers from geofield. - overload (bool): If True, allows overwriting existing columns in the input DataFrame. Defaults to False.

Raises:

• PyvoaError – If the input DataFrame, input_key, geofield, or overload parameters are of incorrect type.

• PyvoaError – If the input_key or geofield is not a valid column name in the respective DataFrames, or if the field(s) to be added are not available.

Returns:

A new DataFrame that results from merging the input DataFrame with the additional data based on the specified keys.

Return type:

pd.DataFrame

pyvoa.geo.pack_polygons_grid_by_area(gdf, gap=0.0, x=0.0, y=0.0, n_cols=None, ascending=False)

Place polygons from a GeoDataFrame / GeoSeries into a grid, sorted by area.

Parameters:

• gdf (GeoDataFrame or GeoSeries) – Contains Shapely polygons.

• gap (float) – Minimum spacing (in coordinate units) between the bounding boxes of polygons, horizontally and vertically.

• x (float) – Additionnal translation in x (default 0.)

• y (float) – Additionnal translation in y (default 0.)

• n_cols (int or None) – Number of columns in the grid. If None, compute approx. sqrt(n) for a roughly square grid.

• ascending (bool) – If False (default): largest polygons first. If True : smallest polygons first.

Returns:

• Same type as input (GeoDataFrame or GeoSeries),

• with translated geometries and reindexed by area.