regionmask

library0.13.0pypypi✓ verified 86d ago

regionmask is a Python library for creating masks of geographic regions for arbitrary grids, supporting both raster and vector data. It works with geopandas, xarray, shapely, and cartopy. Version 0.13.0, released regularly, requires Python >=3.10.

analytics

pip install regionmask

github ↗homepage ↗

INSTALL

IMPORT

SIG · REGIONMASK

regionmask

analyticspythonv0.13.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

regionmask

✓ import regionmask

✗ from regionmask import ...

Use import regionmask, then access classes via regionmask.ClassName

Regions

✓ from regionmask import Regions

defined_regions

✓ from regionmask import defined_regions

mask_3D

✓ from regionmask import mask_3D

mask

✓ from regionmask import mask

Creates a mask for predefined natural earth regions on a longitude/latitude grid.

import regionmask import numpy as np import xarray as xr # Create a simple longitude/latitude grid lon = np.arange(-180, 180, 10) lat = np.arange(-90, 90, 10) # Use predefined land regions (e.g., country boundaries) regions = regionmask.defined_regions.natural_earth_v5_0_0.countries_110 # Create a 2D mask (boolean array) mask_2d = regions.mask(lon, lat) # Create a 3D mask (one boolean layer per region, useful for xarray) lon_2d, lat_2d = np.meshgrid(lon, lat) mask_3d = regions.mask_3D(lon_2d, lat_2d) print('Mask shape:', mask_3d.shape) # (number of regions, lat, lon) print('Region names:', list(regions.names))

Debug

Known issues

breakingIn version 0.11.0, the API changed: mask and mask_3D now return xr.DataArray instead of np.ndarray by default. Wrap with .values to get a numpy array.

fix

Use mask_array.values to get a numpy array, or set as_numpy=True (deprecated in later versions).

affects: >=0.11.0

deprecatedThe as_numpy parameter in mask() and mask_3D() is deprecated since 0.12.0. Instead, use the return type directly (DataArray) or call .values.

fix

Use mask_3d.values if you need a numpy array; avoid passing as_numpy=True.

affects: >=0.12.0

gotchaWhen using mask_3D, the returned DataArray has dimensions (region, lat, lon). Make sure your input lat/lon arrays are 2D (meshgrid) for correct alignment; otherwise, regionmask may broadcast unexpectedly.

fix

Use np.meshgrid(lon, lat) to create 2D arrays before calling mask_3D.

affects: all

gotchaPredefined regions (e.g., defined_regions.natural_earth) download shapefiles on first use. If the download fails, regionmask will raise an OSError. Ensure internet access or cache the data.

fix

Check network connectivity or manually download and place files in the cache directory (~/.regionmask/).

affects: all

deprecatedThe regionmask.Regions constructor from a list of shapely geometries without specifying names may default to numeric indices in future versions; always provide names explicitly.

fix

When creating custom Regions, pass a list of names: regionmask.Regions(geometries, names=['Region1', ...]).

affects: >=0.13.0

Errors

Common errors & fixes

ImportError: cannot import name 'defined_regions' from 'regionmask'

In older versions (< 0.8.0), defined_regions was not available; or you might have a different package version.

fix

Update regionmask: pip install --upgrade regionmask. Then use: from regionmask import defined_regions.

KeyError: 'COUNTRY' when using defined_regions.natural_earth_v5_0_0.countries_110

The region group might have a different attribute name (e.g., countries_110 vs countries_50).

fix

List available regions: print(dir(regionmask.defined_regions.natural_earth_v5_0_0)). Use the correct attribute.

ValueError: The input lat and lon arrays must be 1-dimensional

mask_3D expects 2D arrays, but you passed 1D arrays inadvertently.

fix

Create 2D arrays using np.meshgrid(lon, lat) and pass those to mask_3D.

OSError: [Errno 22] Invalid argument when saving a mask to NetCDF

The mask DataArray may have non-standard dtypes (e.g., integer or float) and NetCDF cannot handle them.

fix

Convert mask to an integer or float dtype: mask.astype(int).to_netcdf('mask.nc').

Upgrade

Version history

0.13.0latest on PyPI · released Dec 3, 2024

Audit

Dependencies

geopandasrequiredRequired for working with shapefiles and vector regions

xarrayrequiredRequired for masking gridded data (e.g., NetCDF)

shapelyrequiredRequired for geometry operations

numpyrequiredRequired for array operations

matplotliboptionalRequired for plotting

cartopyoptionalRequired for map projections and plotting

poochoptionalUsed for downloading predefined region files

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/regionmask/regionmask ↗

homepagehttps://github.com/regionmask/regionmask ↗