Boundaries#
easysnowdata.boundaries#
Boundaries: countries, states, counties, admin units, mountain ranges, glaciers.
Products#
adminCountries and states/provinces (Natural Earth), US states and counties (US Census), and any administrative level of any country (geoBoundaries).
natural_earthAny Natural Earth vector layer by name: lakes, rivers, coastline, glaciated areas, populated places.
mountainsGMBA Mountain Inventory v2 mountain ranges.
glaciersRandolph Glacier Inventory outlines, version 7.0 or 6.0.
Every loader returns a geopandas.GeoDataFrame in EPSG:4326 of the
features that intersect the AOI (whole features, not cut at its edge), and any
of them is itself an AOI for the other loaders.
import easysnowdata as esd
aoi = (-121.94, 46.72, -121.54, 46.99)
esd.boundaries.admin.countries() # the world, 1:110m
esd.boundaries.admin.states(aoi) # Washington (Census)
esd.boundaries.admin.counties(aoi) # Pierce, Lewis …
esd.boundaries.admin.admin(country="NOR", level=2) # Norwegian kommuner
esd.boundaries.natural_earth.load(aoi, layer="lakes")
esd.boundaries.mountains.load(aoi) # Mount Rainier Massif …
esd.boundaries.glaciers.load(aoi) # RGI 7.0
esd.boundaries.glaciers.load(aoi, version="6.0", source="oggm-mirror")
easysnowdata.boundaries.admin#
Countries, states and provinces, US counties, and admin levels anywhere.
import easysnowdata as esd
aoi = (-123.0, 46.0, -120.5, 48.0)
world_gdf = esd.boundaries.admin.countries() # Natural Earth, 1:110m
wa_gdf = esd.boundaries.admin.states(aoi) # US AOI → Census
bc_gdf = esd.boundaries.admin.states(country="CAN", name="British Columbia")
counties_gdf = esd.boundaries.admin.counties(aoi, state="WA") # Census
kommuner_gdf = esd.boundaries.admin.admin(country="NOR", level=2) # geoBoundaries
Four products, one question each: which country, which state or province,
which county, which administrative unit at a given level. Every function
returns a geopandas.GeoDataFrame in EPSG:4326 of the units that
intersect the AOI (whole units, not cut at its edge; None means the
world), with provenance in .attrs. The first columns are the same
everywhere: name, iso3 (the country, ISO 3166-1 alpha-3) and
admin_level (0 country, 1 state/province, 2 county…), followed by the
source’s own attributes.
Sources. Natural Earth (public domain) for countries and for states and
provinces worldwide; the US Census Bureau’s cartographic boundary files
(public domain, yearly) for US states and counties; geoBoundaries (gbOpen,
CC BY 4.0 for most countries — each unit carries its own boundaryLicense)
for any administrative level of any country. Each archive is fetched once
into the easysnowdata cache.
Natural Earth’s point of view. Its countries follow one de facto view of
disputed borders; Natural Earth also publishes per-country point-of-view
variants, which easysnowdata.boundaries.natural_earth.load() reaches
(layer="admin_0_countries_ind", "admin_0_countries_usa" …).
Natural Earth’s ISO codes. ISO_A3 is -99 for France, Norway and a
few others; iso3 is taken from ADM0_A3, which is always set.
A boundary is an AOI: esd.hydro.basins.huc(wa_gdf, level=4).
Country boundaries intersecting aoi (the world when |
|
First-level subdivisions (states, provinces, regions) intersecting aoi. |
|
US counties (and county equivalents) intersecting aoi. |
|
Administrative units at level (0-5) from geoBoundaries. |
|
The Natural Earth zip for layer ( |
|
The Census cartographic boundary zip for layer ( |
easysnowdata.boundaries.glaciers#
Randolph Glacier Inventory (RGI) glacier outlines, version 7.0 or 6.0.
import easysnowdata as esd
aoi = (-121.94, 46.72, -121.54, 46.99)
glaciers_gdf = esd.boundaries.glaciers.load(aoi) # RGI 7.0, NSIDC
complexes_gdf = esd.boundaries.glaciers.load(aoi, product="complexes")
rgi6_gdf = esd.boundaries.glaciers.load(aoi, version="6.0") # NSIDC
rgi6_gdf = esd.boundaries.glaciers.load(aoi, version="6.0", source="oggm-mirror")
regions_gdf = esd.boundaries.glaciers.regions() # the 19 first-order regions
The RGI is the global inventory of glacier outlines outside the ice sheets. Version 7.0 (RGI 7.0 Consortium 2023) is a new inventory with outlines targeted at the year 2000, a glacier product and a glacier-complex product (contiguous ice as one polygon). Version 6.0 (RGI Consortium 2017) is the inventory most published work up to 2023 used, including the OGGM and many mass-balance datasets; keep it for comparison with that literature.
Both are distributed per first-order region, one zipped shapefile each. The
loader reads the region outlines, picks the regions the AOI touches, fetches
each regional archive once into the easysnowdata cache (3-190 MB), and reads
the AOI from it. region= bypasses the lookup; a whole-world read needs
region= (every region is roughly a gigabyte).
Sources. "nsidc" (default) is the archive of record for both
versions and needs an Earthdata Login — as a username and password
(EARTHDATA_USERNAME/EARTHDATA_PASSWORD or a ~/.netrc entry): NSIDC’s
on-premises archive does not accept a bearer EARTHDATA_TOKEN on its own.
"oggm-mirror" is OGGM’s credential-free mirror of the original GLIMS
release files for 6.0 only.
The first columns are the same for both versions: rgi_id, name,
area_km2 and o1region, followed by the version’s own attributes (for
7.0 glims_id, src_date, zmin_m … term_type; for 6.0 RGIId,
GLIMSId, BgnDate, Zmin … TermType). RGI 7.0 stores a constant
Z coordinate, which is dropped.
easysnowdata.boundaries.mountains#
GMBA Mountain Inventory v2: named mountain-range polygons worldwide.
import easysnowdata as esd
aoi = (-121.94, 46.72, -121.54, 46.99)
ranges_gdf = esd.boundaries.mountains.load(aoi) # smallest units
major_gdf = esd.boundaries.mountains.load(aoi, subset="300") # major systems
cascades_gdf = esd.boundaries.mountains.load(aoi, subset="all", level=4)
broad_gdf = esd.boundaries.mountains.load(aoi, extent="broad")
The Global Mountain Biodiversity Assessment inventory (Snethlage et al. 2022) delineates 8,327 mountain ranges as a hierarchy up to ten levels deep (North America > American Cordillera > Pacific Coast Ranges > Cascade Range > South Washington Cascades > …). It comes in three subsets:
"basic"(default)6,717 non-overlapping polygons, the smallest unit wherever there is one (around Rainier: the Mount Rainier Massif and its foothills).
"300"291 non-overlapping major systems (the Cascade Range).
"all"every range at every level, overlapping;
level=picks one level.
and two extents: "standard" follows the GMBA v2 mountain definition,
"broad" extends each polygon well into the surrounding terrain (meant to be
intersected with another mountain definition, such as the Wrzesien mask).
Each variant is one zipped shapefile on EarthEnv (22-186 MB), fetched once into the easysnowdata cache.
easysnowdata.boundaries.natural_earth#
Any Natural Earth vector layer: lakes, rivers, coastline, glaciated areas, places.
import easysnowdata as esd
aoi = (-123.0, 46.0, -120.5, 48.0)
lakes_gdf = esd.boundaries.natural_earth.load(aoi) # layer="lakes"
rivers_gdf = esd.boundaries.natural_earth.load(aoi, layer="rivers_lake_centerlines")
ice_gdf = esd.boundaries.natural_earth.load(aoi, layer="glaciated_areas")
places_gdf = esd.boundaries.natural_earth.load(aoi, layer="populated_places_simple")
coast_gdf = esd.boundaries.natural_earth.load(layer="coastline", scale="110m")
Natural Earth publishes some 130 public-domain cartographic layers at three
scales (1:10m, 1:50m, 1:110m), each a zipped shapefile named
ne_<scale>_<layer>.zip under a cultural or physical folder. This
module reads any of them by name; LAYERS lists the common ones and
the category is looked up there (pass category= for anything else). The
countries and states in admin come from the
same archive, with normalized columns on top. The point-of-view editions of
the countries layer (layer="admin_0_countries_ind", _usa, _chn …,
1:10m) draw disputed borders as that country does.
These are map layers, generalized for display at their scale: use them for
outlines and labels, not for measurements. For glacier outlines to analyse,
use glaciers (RGI); for rivers and lakes as
hydrography, HydroRIVERS and HydroLAKES are the analysis-grade route.