Map one country or selected countries#
Choose country names/codes, make a finer regional grid and clip its mapped values to real country contours. The helpers work with the repository’s soiling/snow, KGPV, degradation and other rectilinear latitude/longitude maps. The offline country gallery demonstrates Austria plus Slovenia, followed by Slovenia alone, using real 2023 inputs sampled at 0.5°.
For a categorical inventory, the worldwide connector coverage example uses the same country loader and the boundary-only plotting helper below. It shows implemented sources and real station-catalogue locations; its country colors describe source context rather than electrical service areas.
Acquire the country shapefile#
The new source adapter downloads Natural Earth Admin 0 country boundaries, retains their shapefile companions and records version/checksum provenance. Natural Earth is public domain and uses de facto boundaries by default. Country codes follow the source’s administrative units, which need not equal sovereign states or every ISO territory. Other boundary datasets can be loaded locally when a different delineation is required.
from pathlib import Path
from energy_data_retrieval.transport import HTTPClient
from energy_data_retrieval.sources.natural_earth import (
NATURAL_EARTH_HOSTS,
NaturalEarthClient,
)
with HTTPClient(allowed_hosts=NATURAL_EARTH_HOSTS) as http:
download = NaturalEarthClient(http).download_countries(
Path("artifacts/boundaries"), scale="10m"
)
print(download.shapefile, download.manifest)
Scale option |
Nominal map scale |
Typical use |
|---|---|---|
|
1:10 million |
Detailed country views; default |
|
1:50 million |
Broader regional views |
|
1:110 million |
Small worldwide maps |
10m does not mean 10-metre accuracy. The official download URL can change
with releases. To require the same archive, pass a saved expected_sha256.
The adapter verifies cached downloads, bounds expanded size and reads only the
expected flat archive members. Keep .shp, .shx, .dbf, .prj and .cpg
together. Source archives and generated shapefiles belong under artifacts/;
the offline gallery keeps small attributed GeoJSON fixtures.
Select countries and create a grid#
from energy_methods.country_boundaries import load_country_boundaries
from energy_methods.country_mapping import country_grid
spain = load_country_boundaries(download.shapefile, "Spain")
iberia = load_country_boundaries(download.shapefile, ["ESP", "PRT"])
grid = country_grid(iberia, resolution=0.25)
Names and codes match exactly, ignoring case and surrounding spaces. Natural
Earth’s ADM0_A3/ADMIN are the default identifier/name fields; ISO A2/A3,
their _EH variants, NAME and NAME_LONG are aliases when present. Duplicate
selectors collapse to one country; unknown or ambiguous selectors raise an
error. For another source use code_field and name_field explicitly.
All polygon parts, islands and holes remain in the selection. For Spain this includes the Canaries and Balearics; a default Spain/Portugal extent also includes their source-defined offshore parts. To focus on mainland Iberia, make the spatial restriction explicit:
grid = country_grid(
iberia,
resolution=0.25,
bounds=(-10, 35.5, 4.5, 44.5), # west, south, east, north
)
Grid edges align to -180° longitude and -90° latitude. Spacing is in degrees
and must divide 180 (for example 1, 0.5, 0.25, 0.1). Allocation is capped at
250,000 cells by default. grid.country_mask marks cells intersecting selected
polygons, including partial coastal/border cells; their centres can be outside
the country. This is an acquisition mask, not a land-fraction estimate.
Draw categorical country boundaries#
Use plot_country_boundaries for a country inventory or categorical background.
It draws the actual polygon parts and holes directly, with one Matplotlib patch
per selected country, and does not require a numeric weather grid. For example,
run this from the repository root with the offline worldwide fixture:
from pathlib import Path
import matplotlib.pyplot as plt
from energy_methods.country_boundaries import load_country_boundaries
from energy_methods.country_mapping import plot_country_boundaries
boundaries = Path("examples/connectors/data/generation_coverage_world.geojson")
iberia = load_country_boundaries(boundaries, ["ESP", "PRT"])
fig, ax = plt.subplots(figsize=(7, 5))
patches = plot_country_boundaries(
iberia,
ax=ax,
colors={"ESP": "#2f7d88"},
facecolor="#e6ecef",
edgecolor="#ffffff",
linewidth=0.4,
zorder=1,
)
ax.set(
xlim=(-12, 5),
ylim=(35, 45),
xlabel="Longitude",
ylabel="Latitude",
title="Selected countries: mainland view; Spain highlighted",
)
ax.set_aspect("equal", adjustable="box")
plt.show()
colors uses exact codes from selection.codes; omitted codes receive
facecolor, and unknown keys raise an error. This differs from the loader’s
name/ISO alias matching. The caller sets axis bounds, labels and the meaning of
each color. The explicit mainland extent above leaves the source islands in
the geometry while cropping the displayed view. Geographic axes are not an
equal-area projection, and country colors alone establish no measurement or
service coverage.
The worldwide fixture preserves Natural Earth 5.1.1’s original vertices at
1:110 million scale for 176 features. Antarctica is explicitly excluded because
its unsplit world-spanning ring violates the current antimeridian rule. Source
version, public-domain terms, archive checksum, derived checksum and the
exclusion are recorded in generation_coverage_provenance.json. Regenerate
it explicitly with scripts/prepare_connector_coverage.py; gallery builds
read the checked-in GeoJSON without a download.
Mask, plot and export existing results#
The following assumes risk is a two-dimensional xarray.DataArray on regular
lat/lon axes. Continuous fields may use NaN; integer class maps should pass
their missing-data code explicitly, such as nodata=0.
import matplotlib.pyplot as plt
from energy_methods.country_boundaries import write_country_boundaries
from energy_methods.country_mapping import (
clip_country_grid,
plot_country_map,
write_country_geojson,
)
selected = clip_country_grid(risk, iberia, nodata=0)
fig, ax = plt.subplots()
mesh = plot_country_map(selected, iberia, ax=ax, nodata=0)
fig.colorbar(mesh, ax=ax)
write_country_boundaries(iberia, Path("artifacts/iberia.shp"))
write_country_geojson(selected, iberia, Path("artifacts/risk.geojson"), nodata=0)
Function |
Behavior |
|---|---|
|
Reads |
|
Builds a bounded grid and polygon-intersection mask |
|
Boolean mask using cell |
|
Masks raster values and trims only outer empty rows/columns |
|
Draws categorical country polygons, preserving holes and islands; exact code colors |
|
Draws flat-shaded values clipped to the contours, with country borders |
|
Exports selected contours as |
|
Exports actual country-cell polygon intersections |
Raster masking retains each partial cell’s numerical value. Plotting and
GeoJSON export clip its visible/geometric footprint to the polygon. They do
not smooth or interpolate class IDs. NaN/class-0 cells remain missing, including
inside the country. GeoJSON export omits missing and line-only intersections.
clip_country_grid also accepts additional year/month dimensions; select a
two-dimensional layer before plotting/exporting.
Coordinates normalize to EPSG:4326 longitude/latitude. Shapefiles need a .prj
or explicit crs; projected inputs are transformed with x/y axis order fixed.
RFC 7946 GeoJSON defaults to WGS84. Invalid geometry fails rather than being
silently repaired. Already split antimeridian polygons are supported, but their
default longitude extent may span the world; use separate bounded views for
islands on opposite sides. Unsplit rings crossing the antimeridian are rejected.
The plots use geographic axes, not a metric or equal-area projection. Do not estimate country areas by summing whole intersecting cells; use geodesic or equal-area calculations on the clipped polygons. Small islands can be drawn from the vector boundaries even when source weather remains coarse.
Retrieve finer soiling/snow inputs#
First inspect the acquisition plan; this downloads boundaries if needed but makes no weather requests:
uv run python scripts/prepare_weather_risk_example.py \
--countries AUT SVN --resolution 0.5 --plan-only
Prepare the actual inputs and selected shapefiles:
uv run python scripts/prepare_weather_risk_example.py \
--countries AUT SVN --resolution 0.5 --year 2023 \
--output artifacts/country-risk --export-shp
Use --boundaries path/to/countries.shp to reuse a local dataset, or
--boundary-scale 50m to choose a less detailed Natural Earth source.
--bounds WEST SOUTH EAST NORTH restricts the acquisition area. Names with
spaces need shell quotes. The default limit is 500 weather sites; exceed it
only by explicitly setting --maximum-sites, subject to provider access terms.
Public requests use bounded workers, pacing and caching. Use
--use-environment-proxy when the configured HTTPS proxy is required.
Country outputs use country_risk_* filenames and do not overwrite the
worldwide weather_risk_* fixtures. The documented example has 83 sampled
cells intersecting Austria/Slovenia on a 0.5° grid; its source manifest gives
all requested and selected coordinates, full-year counts, checksums and dates.
One of the 83 snow samples is unavailable and remains missing. Very large
modelled snow-depth sums in some Alpine cells warrant source-quality review;
the repository retains them visibly instead of silently clipping the inputs.
Copy examples/analysis/plot_country_risk.py alongside the country output files and run
it there for the Austria/Slovenia example. For other countries, change the
selectors and displayed extents in the example, or use the generic functions
above.
Finer boundaries, finer sampling and finer source data are different. NASA POWER AOD550 has 1° source support. The country workflow queries each needed 1° cell centre once and explicitly reuses it at finer target points. ERA5-Land snow uses nearest native model cells. A 0.25° grid does not magically create 0.25° aerosol information. Retrieve suitable higher-resolution weather where available; do not upsample the 15° global fixture and describe it as new information. Scientific equations and limitations remain those in the soiling/snow guide.
Made with Natural Earth. The bibliography also records Shapely, PyProj and PyShp; NASA POWER/CERES and Open-Meteo/Copernicus ERA5-Land remain the weather sources.