Utility functions

open_dataset(filepath, **kwargs)

Open dataset.

This function acts as xarray.open_dataset, except that it can handle files that use “months since…” time units but a calendar that is not a 360-day calendar.

Parameters:

  • filepath (str) – The location of the file on disk.

  • **kwargs – These are passed “as is” to xarray.open_dataset.

Returns:

xarray.Dataset – The opened dataset.

open_mfdataset(filepath, **kwargs)

Open multiple-file dataset.

This function acts as xarray.open_mfdataset, except that it can handle files that use “months since…” time units but a calendar that is not a 360-day calendar.

Parameters:

  • filepath (str) – The location of the file(s) on disk. It can be any pattern accepted by xarray.open_mfdataset.

  • **kwargs – These are passed “as is” to xarray.open_dataset, with one exception: named argument “preprocess” is not allowed here.

Returns:

xarray.Dataset – The opened dataset.

Raises:

ValueError – If “preprocess” is present as a named argument.

Shared functionality

Some functionality is implemented for all models. For example, the method units_nice is common to all models, so you can use, ds.lmdz.units_nice, ds.elmerice.units_nice, and of course ds.wizard.units_nice.

ds.units_nice(varname)

Return units of given variable, in a predictible format.

Predictable format:

  • uses single spaces to separate the dimensions in the units

  • uses negative exponents instead of division symbols

  • always orders dimensions in this order: mass, length, time

  • never uses parentheses

Parameters:

varname (str) – The name of the variable in the NetCDF file.

Returns:

str – The formatted units (or None for dimensionless variables).

property ds.crs_pyproj

The CRS (pyproj) corresponding to dataset.

property ds.crs_cartopy

The CRS (cartopy) corresponding to dataset.

property ds.varnames_lonlat

The names of the longitude and latitude variables.

Shared functionality (ugrid)

This section describes functionality that is implemented for all model outputs that are based on unstructured grids.

property ds.varnames_lonlat_bounds

The names of the lon/lat bound variables.

This property only makes sense for unstructured grids. For these grids, the bound variables are arrays of shape (n_cells, n_vertices) that contain the coordinates of the vertices of each cell.

ds.plot_ugridded_colors(colors, box=None, ax=None, **kwargs)

Plot given colors as colored polygons on unstructured grid.

Parameters:

  • colors (sequence of colors) – The face colors of the polygons. There must be exactly as many colors as there are cells in the grid.

  • box (sequence of four numbers) – The longitude and latitude limits of the interesting part of the data, in the format (lon_min, lon_max, lat_min, lat_max). Grid cells outse of this range will not be plotted.

  • ax (Matplotlib axes object) – The Matplotlib axis object onto which to draw the data (default is current axis).

  • **kwarg – These are passed “as is” to Matplotlib’s Polygon.

ds.plot_ugridded_values(values, cmap='viridis', vmin=None, vmax=None, **kwargs)

Plot given values as colored polygons on unstructured grid.

Parameters:

  • values (numpy.array) – The values to be plotted. There must be exactly as many values as there are grids in the cell.

  • cmap (Matplotlib color map, or just its name) – The colormap to use.

  • vmin (numeric) – The minimum value to show on the color scale.

  • vmax (numeric) – The maximum value to show on the color scale.

  • **kwargs – These are passed “as is” to self.plot_ugridded_colors.