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.

colors maps exact selected country codes to face colors; other countries receive facecolor. 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