Static plots

This section provides the API reference for static plotting functions in mapflow.

PlotModel

class mapflow.PlotModel(x, y, crs=4326, borders=None)

A class for plotting 2D data with geographic borders. Useful for multiple plots of the same geographic domain, as it pre-computes geographic borders.

Parameters:

  • x (np.ndarray) – Array of x-coordinates (e.g., longitudes).

  • y (np.ndarray) – Array of y-coordinates (e.g., latitudes).

  • crs (int | str | CRS, optional) – Coordinate Reference System. Defaults to 4326 (WGS84).

  • borders (gpd.GeoDataFrame | gpd.GeoSeries | None) – Custom borders to use. If None, defaults to world borders from a packaged GeoPackage.

import xarray as xr
from mapflow import PlotModel

ds = xr.tutorial.open_dataset("era5-2mt-2019-03-uk.grib")
da = ds["t2m"].isel(time=0)

p = PlotModel(x=da.longitude, y=da.latitude)
p(da)
__call__(data, figsize=None, qmin=0.01, qmax=99.9, vmin=None, vmax=None, log=False, diff=False, cmap='turbo', norm=None, shading='nearest', shrink=0.5, label=None, title=None, show=True)

Plots a 2D data array using imshow or pcolormesh.

This method handles the actual plotting of a single frame. It applies normalization, colormaps, adds a colorbar, overlays borders, sets the aspect ratio, title, and optionally displays the plot.

Parameters:

  • data (np.ndarray) – 2D array of data to plot.

  • figsize (tuple[float, float], optional) – Figure size (width, height) in inches. Defaults to None (matplotlib’s default).

  • qmin (float, optional) – Minimum quantile for color normalization if vmin is not set. Defaults to 0.01.

  • qmax (float, optional) – Maximum quantile for color normalization if vmax is not set. Defaults to 99.9.

  • vmin (float, optional) – Minimum value for color normalization. Overrides qmin. Defaults to None.

  • vmax (float, optional) – Maximum value for color normalization. Overrides qmax. Defaults to None.

  • log (bool, optional) – Whether to use a logarithmic color scale. Defaults to False.

  • diff (bool, optional) – Whether to use a divergent colormap. Defaults to False.

  • cmap (str, optional) – Colormap to use. Defaults to “turbo”.

  • norm (matplotlib.colors.Normalize, optional) – Custom normalization object. Overrides vmin, vmax, qmin, qmax, log. Defaults to None.

  • shading (str, optional) – Shading method for pcolormesh. Defaults to “nearest”.

  • shrink (float, optional) – Factor by which to shrink the colorbar. Defaults to 0.5.

  • label (str, optional) – Label for the colorbar. Defaults to None.

  • title (str, optional) – Title for the plot. Defaults to None.

  • show (bool, optional) – Whether to display the plot using plt.show(). Defaults to True.

plot_da

mapflow.plot_da(da: DataArray, x_name=None, y_name=None, crs=None, borders=None, diff=False, subsample=None, **kwargs)

Convenience function for quick plotting of an xarray DataArray using PlotModel.

This is a simplified wrapper around the PlotModel class that handles: - Automatic coordinate detection - CRS processing - Data sorting and longitude wrapping (for geographic CRS) - Single-call plotting

For better performance when making multiple plots of the same geographic domain, consider using PlotModel directly, which pre-computes geographic borders and can be reused for multiple plots.

Parameters:

  • da (xr.DataArray) – xarray DataArray with 2D data to plot. Must have appropriate coordinates.

  • x_name (str, optional) – Name of the x-coordinate dimension. If None, will attempt to guess from [“x”, “lon”, “longitude”].

  • y_name (str, optional) – Name of the y-coordinate dimension. If None, will attempt to guess from [“y”, “lat”, “latitude”].

  • crs (int | str | CRS, optional) – Coordinate Reference System. Can be an EPSG code, a PROJ string, or a pyproj.CRS object. If the DataArray has a ‘crs’ attribute, that will be used by default. Defaults to 4326 (WGS84).

  • borders (gpd.GeoDataFrame | gpd.GeoSeries | None) – Custom borders to use. If None, defaults to world borders from a packaged GeoPackage.

  • diff (bool, optional) – Whether to use a divergent colormap. Defaults to False.

  • subsample (int, optional) – If provided, subsamples the data by this factor for plotting. Useful for large datasets to speed up plotting. Defaults to None.

  • **kwargs – Additional arguments passed to PlotModel.__call__, including: - figsize (tuple, optional): Figure size (width, height) in inches. - qmin/qmax (float, optional): Quantile ranges for color scaling (0-100). - vmin/vmax (float, optional): Explicit value ranges for color scaling. - log (bool, optional): Whether to use a logarithmic color scale. - cmap (str, optional): Colormap name. - norm (matplotlib.colors.Normalize, optional): Custom normalization object. - shading (str, optional): Color shading method. - shrink (float, optional): Colorbar shrink factor. - label (str, optional): Colorbar label. - title (str, optional): Plot title. - show (bool, optional): Whether to display the plot.

Example

import xarray as xr
from mapflow import plot_da

ds = xr.tutorial.open_dataset("era5-2mt-2019-03-uk.grib")
plot_da(da=ds['t2m'].isel(time=0))

See also

PlotModel: The underlying plotting class used by this function.

plot_da_quiver

mapflow.plot_da_quiver(u, v, x_name=None, y_name=None, crs=None, subsample: int = 1, show=True, arrows_kwgs: dict[str, Any] | None = None, **kwargs)

Plots a quiver plot from two xarray DataArrays.

The magnitude of the vector field is represented by a color mesh, and the direction is shown with quiver arrows.

Parameters:

  • u (xr.DataArray) – DataArray for the U-component of the vector field.

  • v (xr.DataArray) – DataArray for the V-component of the vector field.

  • x_name (str, optional) – Name of the x-coordinate dimension. If None, will attempt to guess from [“x”, “lon”, “longitude”].

  • y_name (str, optional) – Name of the y-coordinate dimension. If None, will attempt to guess from [“y”, “lat”, “latitude”].

  • crs (int | str | CRS, optional) – Coordinate Reference System. Can be an EPSG code, a PROJ string, or a pyproj.CRS object. If the DataArray has a ‘crs’ attribute, that will be used. Defaults to 4326 (WGS84).

  • subsample (int, optional) – The subsampling factor for the quiver arrows. For example, a value of 10 will plot one arrow for every 10 grid points. Defaults to 1.

  • show (bool, optional) – Whether to display the plot. Defaults to True.

  • arrows_kwgs (dict, optional) – Additional keyword arguments passed to matplotlib.pyplot.quiver. Defaults to None.

  • **kwargs – Additional arguments passed to PlotModel.__call__, including: - figsize (tuple, optional): Figure size (width, height) in inches. - qmin/qmax (float, optional): Quantile ranges for color scaling. - vmin/vmax (float, optional): Explicit value ranges for color scaling. - log (bool, optional): Whether to use a logarithmic color scale. - cmap (str, optional): Colormap name. - norm (matplotlib.colors.Normalize, optional): Custom normalization object. - shading (str, optional): Color shading method. - shrink (float, optional): Colorbar shrink factor. - label (str, optional): Colorbar label. - title (str, optional): Plot title.

Example

import xarray as xr
from mapflow import plot_da_quiver

ds = xr.tutorial.load_dataset("air_temperature_gradient").isel(time=0)
plot_da_quiver(u=ds["dTdx"], v=ds["dTdy"], subsample=4)

See also

PlotModel: The underlying plotting class used by this function.