PYGADM - ITEM

Easy access to administrative boundaries from the GADM database.

URL: https://github.com/12rambau/pygadm

Example

This wrapper can be used in the following way:

rule download:
    output:
        # GADM data file
        path="results/mexico.parquet",
    params:
        # administration iso-3 code
        admin="MEX",
        # layer to get (0: country, 1: regions, 2: subregions)
        content_level=1
    threads: 1
    log:
        "logs/pygadm/item.log"
    wrapper:
        "v5.9.0/geo/pygadm/item"

Note that input, output and log file paths can be chosen freely.

When running with

snakemake --use-conda

the software dependencies will be automatically deployed into an isolated environment before execution.

Notes

Important: either name or admin must be specified. Read the documentation https://pygadm.readthedocs.io/ to learn more about valid requests.

Software dependencies

• pygadm=0.5.3

Params

• name: Optional. Name of the item in the GADM database (e.g., “France” or [“France”, “Spain”]).

• admin: Optional. Admin code in the GADM database, usually a country ISO alpha-3 code (e.g., “FRA” or [“FRA”, “ESP”])

• content_level: Optional. level of administrative layer to get (e.g., 0, 1, 2). Defaults to the country layer (0).

Authors

• Ivan Ruiz Manuel

Code

__author__ = "Ivan Ruiz Manuel"
__copyright__ = "Copyright 2025, Ivan Ruiz Manuel"
__email__ = "i.ruizmanuel@tudelft.nl"
__license__ = "MIT"

from pathlib import Path
from pygadm import Items

log = snakemake.log_fmt_shell(stdout=True, stderr=True)

# Request data
request = {}
for param in ["name", "admin", "content_level"]:
    value = snakemake.params.get(param, None)
    if value:
        request[param] = value
geo_dataframe = Items(**request)

# GADM uses a WGS84 datum.
geo_dataframe = geo_dataframe.set_crs(4326)

# GeoPandas specifies separate methods for saving files.
# Attempt to grab it using the file extension.
path = snakemake.output.path
save_method = f"to_{Path(path).suffix[1:]}"
if save_method in dir(geo_dataframe):
    getattr(geo_dataframe, save_method)(path)
else:
    geo_dataframe.to_file(path)