Usage#

Get admininstrative items#

The PyGAUL lib can be used to extract information from the FAO GAUL dataset as ee.FeatureCollection.

Note

ee.FeatureCollection can easily be converted to GeoDataFrame but if interacting with Earthengine is not the chore of your usage, have a look to pygadm. It will provide accès to smaller administrative boundaries and return directly a gdf.

Important

PyGAUL is not managing the connection to Google Earth Engine API. The user is responsible to set up the Initialization as he see fit. This is a feature to allow users with exotic GEE connection (e.g. service accounts) to continue use the lib without any modification.

Countries#

Using the Items class, you can access an administrative area using either its name or its GAUL identification code.

For example to extract the France geometry you can use the following code:

import pygaul
from geemap import Map
import ee

ee.Initialize()

fc = pygaul.Items(name="France")

# display it in a map
m = Map(zoom=5, center=[46.21, 2.21])
m.addLayer(fc, {"color": "red"}, "")
m

If you know the code of the area you try to use, you can use the GADM code instead of the name.

import pygaul
from geemap import Map
import ee

ee.Initialize()

fc = pygaul.Items(admin="85")

# display it in a map
m = Map(zoom=5, center=[46.21, 2.21])
m.addLayer(fc, {"color": "red"}, "")
m

Smaller admin levels#

One is not bind to only request a country, any level can be accessed using both names and/or GADM code.

import pygaul
from geemap import Map
import ee

ee.Initialize()

fc = pygaul.Items(name="Corse-du-Sud")

# display it in a map
m = Map(zoom=8, center=[41.86, 8.97])
m.addLayer(fc, {"color": "red"}, "")
m

Warning

The names of countries are all unique but not the smaller administrative layers. If you request a small area using name, make sure it’s the one you are looking for before running your workflow. follow usage:Duplication issue for more information.

Content of an admin layer#

Using the content_level option, one can require smaller administrative layer than the one setup in the name. For example when you request France, by setting up the content_level option to 2, the geodataframe will include all the department geometries.

import pygaul
from geemap import Map
import ee

ee.Initialize()

fc = pygaul.Items(admin="85", content_level=2)

# display it in a map
m = Map(zoom=5, center=[46.21, 2.21])
m.addLayer(fc, {"color": "red"}, "")
m

Request multiple areas at once#

To perform regional analysis that aggregate multiple boundaries, you can now request them at once using a list of name or a list of admin. In this example we request both germany and France at once:

import pygaul
from geemap import Map
import ee

ee.Initialize()

fc = pygaul.Items(name=["France", "Germany"], content_level=1)

# display it in a map
m = Map(zoom=5, center=[48.83, 5.17])
m.addLayer(fc, {"color": "red"}, "")
m

Continents#

It’s possible to request all countries from one single continent using one of the following names:

North America
South America
Antartica
Europe
Asia
Oceania
Africa

import pygaul
from geemap import Map
import ee

ee.Initialize()

fc = pygaul.Items(name="europe")

# display it in a map
m = Map(zoom=4, center = [49.38237278700955, 31.464843750000004])
m.addLayer(fc, {"color": "red"}, "")
m

Find administrative names#

To get the available name and GAUL code in a administrative layer you can use the Names class with the same parameters. Use then these names in a Items request to get the geometry.

For example to get the names and codes of all the departments in France you can run:

import pygaul

pygaul.Names(admin="85", content_level=2)

	ADM2_NAME	ADM2_CODE
0	Dordogne	16240
1	Gironde	16241
2	Landes	16242
3	Lot-et-Garonne	16243
4	Pyrenees-Atlantique	16244
...	...	...
91	Ain	16326
92	Haute-Savoie	16329
93	Loire	16331
94	Rhone	16332
95	Savoie	16333

96 rows × 2 columns

Note

If needed, one can get the names of the upper administrative layers by setting the complete parameter to True.

import pygaul

pygaul.Names(admin="1270", content_level=2, complete=True)

	ADM0_CODE	ADM0_NAME	ADM1_CODE	ADM1_NAME	ADM2_CODE	ADM2_NAME	ISO 3166-1 alpha-3
0	85	France	1270	Rhone-Alpes	16327	Ardeche	FRA
1	85	France	1270	Rhone-Alpes	16328	Drome	FRA
2	85	France	1270	Rhone-Alpes	16330	Isere	FRA
3	85	France	1270	Rhone-Alpes	16326	Ain	FRA
4	85	France	1270	Rhone-Alpes	16329	Haute-Savoie	FRA
5	85	France	1270	Rhone-Alpes	16331	Loire	FRA
6	85	France	1270	Rhone-Alpes	16332	Rhone	FRA
7	85	France	1270	Rhone-Alpes	16333	Savoie	FRA

Note

You can also get the list of all the country names by omitting admin and name parameters. If a level is not provided the table will only show country names but other parameters remain availables.

pygaul.Names()

Suggestion#

If you make an error when writing the name of your input, the error message will suggest 5 potential candidates in the existing names of the GADM dataset:

import pygaul
import ee

ee.Initialize()

fc = pygaul.Items(name="Franc")

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[9], line 6
      2 import ee
      4 ee.Initialize()
----> 6 fc = pygaul.Items(name="Franc")

File ~/checkouts/readthedocs.org/user_builds/pygaul/envs/latest/lib/python3.10/site-packages/ee/computedobject.py:29, in ComputedObjectMetaclass.__call__(cls, *args, **kwargs)
     27   return args[0]
     28 else:
---> 29   return type.__call__(cls, *args, **kwargs)

File ~/checkouts/readthedocs.org/user_builds/pygaul/envs/latest/lib/python3.10/site-packages/pygaul/__init__.py:171, in Items.__init__(self, name, admin, content_level)
    167     names = [""]
    169 # use itertools, normally one of them is empty so it will raise an error
    170 # if not the case as admin and name will be set together
--> 171 fc_list = [self._items(n, a, content_level) for n, a in product(names, admins)]
    173 # concat all the data
    174 feature_collection = fc_list[0]

File ~/checkouts/readthedocs.org/user_builds/pygaul/envs/latest/lib/python3.10/site-packages/pygaul/__init__.py:171, in <listcomp>(.0)
    167     names = [""]
    169 # use itertools, normally one of them is empty so it will raise an error
    170 # if not the case as admin and name will be set together
--> 171 fc_list = [self._items(n, a, content_level) for n, a in product(names, admins)]
    173 # concat all the data
    174 feature_collection = fc_list[0]

File ~/checkouts/readthedocs.org/user_builds/pygaul/envs/latest/lib/python3.10/site-packages/pygaul/__init__.py:196, in Items._items(self, name, admin, content_level)
    184 """
    185 Return the requested administrative boundaries from a single name or administrative code.
    186 
   (...)
    193     The FeatureCollection of the requested area with all the GAUL attributes.
    194 """
    195 # call to Names without level to raise an error if the requested level won't work
--> 196 df = Names(name, admin)
    197 if len(df) > 1:
    198     raise ValueError(
    199         f'The requested name ("{name}") is not unique ({len(df)} results). '
    200         f"To retrieve it, please use the `admin` parameter instead. "
    201         f"If you don't know the GAUL code, use the following code, "
    202         f'it will return the GAUL codes as well:\n`Names(name="{name}")`'
    203     )

File ~/checkouts/readthedocs.org/user_builds/pygaul/envs/latest/lib/python3.10/site-packages/pygaul/__init__.py:84, in Names.__init__(self, name, admin, content_level, complete)
     82     else:
     83         close_ids = [i.upper() for i in close_ids]
---> 84     raise ValueError(
     85         f'The requested "{id}" is not part of FAO GAUL 2015. The closest '
     86         f'matches are: {", ".join(close_ids)}.'
     87     )
     89 # Get the code of the associated country of the identifed area and the associated level
     90 line = is_in[~((~is_in).all(axis=1))].idxmax(1)

ValueError: The requested "Franc" is not part of FAO GAUL 2015. The closest matches are: France, Franca, Ranco, Rancul, Ranchi.