GADM tools

cycles.gadm

read_gadm(path, country, level_str, *, conus=True)

Read a GADM layer and normalize its index.

Parameters:
  • path (str | Path) –

    Directory containing GADM shapefiles.

  • country (str) –

    Country code used in GADM file names.

  • level_str (str) –

    Administrative level name (country, state, county).

  • conus (bool, default: True ) –

    For USA state/county layers, exclude Alaska and Hawaii.
Returns:
  • GeoDataFrame –

    GeoDataFrame indexed by GID.

state_abbreviation(*, state=None, gid=None, fips=None)

Look up state abbreviation by name, GID, or FIPS code.

Parameters:
  • state (str | None, default: None ) –

    Full state name.

  • gid (str | None, default: None ) –

    State GID string.

  • fips (int | None, default: None ) –

    Numeric state FIPS code.
Returns:
  • str –

    Two-letter state abbreviation.
Raises:
  • KeyError –

    If no matching state record is found.

state_fips(*, state=None, abbreviation=None, gid=None)

Look up state FIPS code by name, abbreviation, or GID.

Parameters:
  • state (str | None, default: None ) –

    Full state name.

  • abbreviation (str | None, default: None ) –

    Two-letter state abbreviation.

  • gid (str | None, default: None ) –

    State GID string.
Returns:
  • int –

    Numeric state FIPS code.
Raises:
  • KeyError –

    If no matching state record is found.

state_gid(*, state=None, abbreviation=None, fips=None)

Look up state GID by name, abbreviation, or FIPS code.

Parameters:
  • state (str | None, default: None ) –

    Full state name.

  • abbreviation (str | None, default: None ) –

    Two-letter state abbreviation.

  • fips (int | None, default: None ) –

    Numeric state FIPS code.
Returns:
  • str –

    State GID string.
Raises:
  • KeyError –

    If no matching state record is found.

state_name(*, abbreviation=None, gid=None, fips=None)

Look up state name by abbreviation, GID, or FIPS code.

Parameters:
  • abbreviation (str | None, default: None ) –

    Two-letter state abbreviation.

  • gid (str | None, default: None ) –

    State GID string.

  • fips (int | None, default: None ) –

    Numeric state FIPS code.
Returns:
  • str –

    Full state name.
Raises:
  • KeyError –

    If no matching state record is found.

county_fips(*, gid)

Look up county FIPS code by county GID.

Parameters:
  • gid (str) –

    County GID string.
Returns:
  • int –

    Numeric county FIPS code.
Raises:
  • KeyError –

    If no matching county record is found.

county_gid(*, fips)

Look up county GID by county FIPS code.

Parameters:
  • fips (int) –

    Numeric county FIPS code.
Returns:
  • str –

    County GID string.
Raises:
  • KeyError –

    If no matching county record is found.

county_name(*, gid=None, fips=None)

Look up county display name by GID or FIPS code.

Parameters:
  • gid (str | None, default: None ) –

    County GID string.

  • fips (int | None, default: None ) –

    Numeric county FIPS code.
Returns:
  • str –

    County display name formatted as "County, State".
Raises:
  • KeyError –

    If no matching county record is found.