Basic usage

Let us look at an example

Imagine you ran an Elmer/Ice simulation over Greenland, and you want to make a map of the surface elevation at the end of the simulation (variable orog in file output.nc). Without geomodeloutputs, you might write a script like this:

import xarray as xr
import matplotlib.pyplot as plt

ds = xr.open_dataset("output.nc")
meshname = "greenland"
tri = Triangulation(ds["x"][-1,:], ds["y"][-1,:], ds[meshname + "_face_nodes"])
plt.tripcolor(tri, ds["orog"][-1,:])
plt.savefig("orog.png")
ds.close()

In order to plot Elmer/Ice output data, which are given on an unstructured mesh, you first have to create a Triangulation object from three of the output’s variables: x, y, and a third variable whose name depends on the name that was given to the mesh when Elmer/Ice was run. To plot Elmer/Ice output data, you therefore have to:

  • remember how to correctly create the Triangulation instance.

  • know the name of the mesh, which you will probably have to hard-code in your script. Your script will therefore not be usable with outputs of other Elmer/Ice simulations, if they have a different mesh name.

Using geomodeloutputs, you might write a script like this instead:

import xarray as xr
import geomodeloutputs
import matplotlib.pyplot as plt

ds = xr.open_dataset("output.nc").elmerice
plt.tripcolor(ds.triangulation, ds["orog"][-1,:])
plt.savefig("orog.png")
ds.close()

In this example, you can see that:

  • the NetCDF file is opened, accessed, and closed in exactly the same way as in the previous example, except that we add the name of the model after calling xr.open_dataset to unlock the Elmer/Ice functionality.

  • the details of the calculation of the Triangulation instance are now hidden.

  • you do not need to know the name of the mesh (it is automatically detected by geomodeloutputs). Your script will therefore be usable “as is” with other Elmer/Ice output files.

In fact, if you need to know it, geomodeloutputs can give you the name of the mesh:

>>> print(ds.meshname)

"greenland"

The examples above show the philosophy of geomodeloutputs:

  • do not change the functionality of xarray.

  • hide uninteresting technical details and automate their calculation.

  • make manipulating outputs from known models (Elmer/Ice, MAR, LMDz, WRF, …) more convenient.

The general philosophy of geomodeloutputs

The general philosophy of geomodeloutputs is to add functionality to NetCDF files opened as xarray.Dataset instances, without changing how xarray works.

The functionality added by geomodeloutputs can be accessed through new attributes of Dataset instances. There is one such new attribute for each model supported by geomodeloutputs. Think of these attributes as drawers: one drawer for each model. These drawers are actually called “accessors” in xarray jargon.

For example, the added functionality for Elmer/Ice outputs can be accessed via ds.elmerice.*, and the added functionality for LMDz outputs can be accessed via ds.lmdz.*.

Each accessor also features the usual xarray interface. For example, ds.lmdz["snow"] is equivalent to ds["snow"].

The wizard

Sometimes one wants to write code that is model-agnostic (ie. code that works transparently with outputs of different models). For that, geomodeloutputs provides the wizard accessor that works for all relevant models. For example, ds.wizard.units_nice correspond to ds.elmerice.units_nice for Elmer/Ice outputs and to ds.lmdz.units_nice for LMDz outputs.