energy_methods.country_mapping#
Country grids, polygon masks, clipped plots and clipped cell exports.
- energy_methods.country_mapping.country_grid(selection, *, resolution=0.5, bounds=None, maximum_cells=250000)[source]#
Build a regular lon/lat grid and an intersecting-cell country mask.
Resolution is degrees, not new source information. Cell edges align to -180/-90. The spacing must divide 180 degrees; e.g. 1, .5, .25 or .1. All country parts determine default bounds. Explicit bounds select an area of interest (useful for overseas territories/insets). At least two centres per axis support cell edges and export. Allocation is bounded in advance.
- Parameters:
selection (CountrySelection)
resolution (float)
bounds (Bounds | None)
maximum_cells (int)
- Return type:
Dataset
- energy_methods.country_mapping.country_mask(data, selection, *, mode='intersects', maximum_cells=250000)[source]#
Boolean mask on normalized lat/lon coordinates; no interpolation.
‘center’ includes centres on country boundaries, excludes interior holes. ‘intersects’ includes cells touching any polygon; this supports retrieval for partial coastal cells. It is not a fractional-area mask. Both modes keep islands. Antimeridian-split countries work on a conventional -180..180 grid; default extents can therefore span the world. Use separate views to zoom.
- Parameters:
data (DataArray)
selection (CountrySelection)
mode (Literal['center', 'intersects'])
maximum_cells (int)
- Return type:
DataArray
- energy_methods.country_mapping.clip_country_grid(data, selection, *, nodata=nan, mode='intersects', crop=True)[source]#
Mask outside countries and optionally trim outer empty rows/columns.
Partial cells retain their original numerical value; the plotting/export functions clip their polygon footprint. Existing NaN/nodata values stay missing. For integer class maps pass nodata=0 to preserve integer dtype. Supports additional dimensions such as year/month; never resamples classes.
- Parameters:
data (DataArray)
selection (CountrySelection)
nodata (float)
mode (Literal['center', 'intersects'])
crop (bool)
- Return type:
DataArray
- energy_methods.country_mapping.plot_country_boundaries(selection, *, ax, colors=None, facecolor='#e6ecef', edgecolor='#ffffff', linewidth=0.4, zorder=1)[source]#
Draw categorical country polygons without inventing a numeric grid.
colorsmaps exact selected country codes to face colors; other countries receivefacecolor. Holes and disconnected islands are preserved. Unknown codes fail instead of silently missing a requested highlight. The caller controls the longitude/latitude view bounds, labels and interpretation of the colors; these polygons are administrative context, not service areas. Returns one Matplotlib patch per country for further styling or export.- Parameters:
selection (CountrySelection)
ax (Axes)
colors (Mapping[str, str] | None)
facecolor (str)
edgecolor (str)
linewidth (float)
zorder (float)
- Return type:
tuple[PathPatch, …]
- energy_methods.country_mapping.plot_country_map(data, selection, *, ax, bounds=None, cmap='viridis', norm=None, vmin=None, vmax=None, nodata=None)[source]#
Draw unsmoothed values clipped to exact country contours and draw borders.
Returns a QuadMesh for fig.colorbar. Geographic axes are longitude/latitude, not a metric/equal-area projection. Gray denotes missing data within the supplied boundaries; white/background is outside. Use explicit bounds for mainland/island views. Boundary detail does not change source resolution.
- Parameters:
data (DataArray)
selection (CountrySelection)
ax (Axes)
bounds (Bounds | None)
cmap (str | Colormap)
norm (Normalize | None)
vmin (float | None)
vmax (float | None)
nodata (float | None)
- Return type:
QuadMesh
- energy_methods.country_mapping.write_country_geojson(data, selection, path, *, nodata=None, labels=None, maximum_features=100000)[source]#
Export cell-country polygon intersections, retaining each cell’s value.
Empty/line-only intersections and missing values are omitted. Holes/islands remain in the output. Polygon clipping is planar lon/lat and adds no data resolution. Use geodesic/equal-area calculations for fractional-area totals.
- Parameters:
data (DataArray)
selection (CountrySelection)
path (Path)
nodata (float | None)
labels (dict[int, str] | None)
maximum_features (int)
- Return type:
Path