pygaul#

Easy access to administrative boundary defined by FAO GAUL 2015 from Python scripts.

This lib provides access to FAO GAUL 2015 datasets from a Python script. it is the best boundary dataset available for GEE at this point. We provide access to The current version (2015) administrative areas till level 2.

Submodules#

Attributes#

__author__

__email__

__gaul_asset__

__gaul_data__

__version__

Classes#

AdmItems

Object to handle administrative boundaries using the name or the administrative code.

AdmNames

Object to handle names of administrative layer using the name or the administrative code.

Items

Object to handle administrative boundaries using the name or the administrative code.

Names

Object to handle names of administrative layer using the name or the administrative code.

Functions#

_df()

Get the parquet database.

get_items([name, admin, content_level])

Return the requested administrative boundaries using the name or the administrative code.

get_names([name, admin, content_level, complete])

Return the list of names available in a administrative layer using the name or the administrative code.

Package Contents#

class pygaul.AdmItems(name='', admin='', content_level=-1)[source]#

Bases: Items

Object to handle administrative boundaries using the name or the administrative code.

Return an ee.FeatureCollection representing an administrative region. The region can be requested either by its “name” or its “admin”, the lib will identify the area level on the fly. The user can also request for a specific level for the GeoDataFrame features e.g. get all admin level 1 of a country. If nothing is set we will infer the level of the item and if the level is higher than the found item, it will be ignored. If Nothing is found the method will return an error.

Parameters:

  • name (Union[str, List[str]]) – The name of an administrative area. Cannot be set along with admin. it can be a list or a single name.

  • admin (Union[str, List[str]]) – The id of an administrative area in the GADM nomenclature. Cannot be set along with name. It can be a list or a single admin code.

  • content_level (int) – The level to use in the final dataset. Default to -1 (use level from the area).

class pygaul.AdmNames(name='', admin='', content_level=-1, complete=False)[source]#

Bases: Names

Object to handle names of administrative layer using the name or the administrative code.

Compute a pandas DataFrame of the names as FAO GAUL codes of and administrative region. The region can be requested either by its “name” or its “admin”, the lib will identify the corresponding level on the fly. The user can also request for a specific level for its content e.g. get all admin level 1 of a country. If nothing is set we will infer the level of the item and if the level is higher than the found item, it will be ignored. If Nothing is found the method will raise an error.

Parameters:

  • name (str) – The name of a administrative area. Cannot be set along with admin.

  • admin (str) – The id of an administrative area in the FAO GAUL nomenclature. Cannot be set along with name.

  • content_level (int) – The level to use in the final dataset. Default to -1 (use level of the selected area).

  • complete (bool) – If True, the method will return all the names of the higher administrative areas. Default to False.

class pygaul.Items(name='', admin='', content_level=-1)[source]#

Bases: ee.FeatureCollection

Object to handle administrative boundaries using the name or the administrative code.

Return an ee.FeatureCollection representing an administrative region. The region can be requested either by its “name” or its “admin”, the lib will identify the area level on the fly. The user can also request for a specific level for the GeoDataFrame features e.g. get all admin level 1 of a country. If nothing is set we will infer the level of the item and if the level is higher than the found item, it will be ignored. If Nothing is found the method will return an error.

Parameters:

  • name (Union[str, List[str]]) – The name of an administrative area. Cannot be set along with admin. it can be a list or a single name.

  • admin (Union[str, List[str]]) – The id of an administrative area in the GADM nomenclature. Cannot be set along with name. It can be a list or a single admin code.

  • content_level (int) – The level to use in the final dataset. Default to -1 (use level from the area).

_items(name='', admin='', content_level=-1)[source]#

Return the requested administrative boundaries from a single name or administrative code.

Parameters:

  • name (str) – The name of an administrative area. Cannot be set along with admin.

  • admin (str) – The id of an administrative area in the FAO GAUL nomenclature. Cannot be set along with name.

  • content_level (int) – The level to use in the final dataset. Default to -1 (use level from the area).

Returns:

The FeatureCollection of the requested area with all the GAUL attributes.

Return type:

ee.FeatureCollection

class pygaul.Names(name='', admin='', content_level=-1, complete=False)[source]#

Bases: pandas.DataFrame

Object to handle names of administrative layer using the name or the administrative code.

Compute a pandas DataFrame of the names as FAO GAUL codes of and administrative region. The region can be requested either by its “name” or its “admin”, the lib will identify the corresponding level on the fly. The user can also request for a specific level for its content e.g. get all admin level 1 of a country. If nothing is set we will infer the level of the item and if the level is higher than the found item, it will be ignored. If Nothing is found the method will raise an error.

Parameters:

  • name (str) – The name of a administrative area. Cannot be set along with admin.

  • admin (str) – The id of an administrative area in the FAO GAUL nomenclature. Cannot be set along with name.

  • content_level (int) – The level to use in the final dataset. Default to -1 (use level of the selected area).

  • complete (bool) – If True, the method will return all the names of the higher administrative areas. Default to False.

pygaul._df()[source]#

Get the parquet database.

Return type:

pandas.DataFrame

pygaul.get_items(name='', admin='', content_level=-1)[source]#

Return the requested administrative boundaries using the name or the administrative code.

Parameters:

  • name (Union[str, List[str]])

  • admin (Union[str, List[str]])

  • content_level (int)

Return type:

ee.FeatureCollection

pygaul.get_names(name='', admin='', content_level=-1, complete=False)[source]#

Return the list of names available in a administrative layer using the name or the administrative code.

Parameters:

  • name (str)

  • admin (str)

  • content_level (int)

  • complete (bool)

Return type:

pandas.DataFrame

pygaul.__author__ = 'Pierrick Rambaud'[source]#
pygaul.__email__ = 'pierrick.rambaud49@gmail.com'[source]#
pygaul.__gaul_asset__ = 'projects/sat-io/open-datasets/FAO/GAUL/GAUL_2024_L{}'[source]#
pygaul.__gaul_data__[source]#
pygaul.__version__ = '0.4.2'[source]#