API Reference

Full information about MARUtils’ functionality is provided on this page.

Input/Output

Read MAR outputs into xarray.

marutils.io.open_dataset(filenames, concat_dim='time', transform_func=None, chunks={'time': 366}, projection='stere', base_proj4='+k=1 +datum=WGS84 +units=m', errors='raise', **kwargs)

Load single or multiple MAR NC files into a xr.Dataset.

If multiple files are specified then they will be concatenated on the time axis.

The following changes are applied to the dimensions to improve usability and script portability between different MAR model runs: * ‘X{n}_{n}’ –> x * ‘Y{n}_{n}’ –> y * ‘TIME’ –> ‘time’ * x & y km –> metres

You might also use indexing operations like .sel to subset datasets:

mymar = open_dataset('MAR*.nc', dim='time', transform_func=lambda ds: ds.AL.sel(x=slice(.., ..)))

Functionality based on http://xray.readthedocs.io/en/v0.7.1/io.html#combining-multiple-files See also http://xray.readthedocs.io/en/v0.7.1/dask.html

Parameters

files (str) – filesystem path to open, optionally with wildcard expression (*)
dim (str or None) – name of dimension on which concatenate (only if multiple files specified)
transform_func (function) – a function to use to reduce/aggregate data
chunks (dict or None) – A dictionary specifying how to chunk the Dataset. Use dimension names time, y, x.
projection (str) – The proj.4 name of the projection of the MAR file/grid.
base_proj4 (str) – The basic proj.4 parameters needed to georeference the file.
errors – ‘raise’ or ‘ignore’. If ‘raise’, errors encountered while trying

to rename dataset dimensions to standards will be raised, otherwise they will be ignored. :type errors: str

Returns: concatenated dataset
Return type: xr.Dataset

Georeferencing

Recall that MAR output files opened by marutils.io.open_dataset() are automatically given the .rio accessor (see https://corteva.github.io/rioxarray/stable/).

MAR georeferencing helpers.

marutils.georef.create_crs(xds, projection='stere', base_proj4='+k=1 +datum=WGS84 +units=m'): Create a Coordinate Reference System object for the dataset.

marutils.georef.create_proj4(xds, proj, base)

Return proj4 string for dataset.

Create proj4 string using combination of values determined from dataset and those which must be known in advance (projection).

Parameters

xds (xr.Dataset) – xarray representation of MAR dataset opened using mar_raster
proj (str) – Proj.4 projection
base (str) – base Proj.4 string for MAR

Returns

Proj.4 string object

Return type

str

marutils.georef.get_mpl_extent(xds)

Return an extent tuple in the format required by matplotlib.

Parameters: xds (xr.Dataset) – a MAR XDataset opened through MAR.open().
Returns: (xmin,xmax,ymin,ymax)
Return type: tuple

X-hourly data helpers

Functions for working with X-hourly variables.

marutils.xhourly.xhourly_to_time(xda)

Squeeze X-hourly dimension out of a variable, yielding hourly time dimension.

Used for DataArrays with coordinates (y, x, ATMXH, time).

Example:

import marutils
from marutils import xhourly
mar = marutils.open_dataset('MAR.data.nc')
hourly_tt = xhourly.xhourly_to_time(mar.TTH)

Parameters: xda (xr.DataArray) – a DataArray of MAR data containing ATMXH coordinate
Returns: DataArray with ATMXH dimension removed and hours on the time dimension.
Return type: xr.DataArray

Masking

Functions for returning standardised masks, e.g. of ice areas.

marutils.masking.gris_mask(xds)

Return a Greenland Ice Sheet mask.

This method returns a mask of the GrIS processed according to Xavier Fettweis’ method (as per email XF–>AT 5 April 2018)

Ferret method:

yes? LET msk_tmp1            = if ( lat[d=1]  GE 75   AND lon[d=1] LE -75 ) then  0           else 1
yes? LET msk_tmp2a           = if ( lat[d=1]  GE 79.5 AND lon[d=1] LE -67 ) then  0           else msk_tmp1
yes? LET msk_tmp2            = if ( lat[d=1]  GE 81.2 AND lon[d=1] LE -63 ) then  0           else msk_tmp2a
yes? let km3 = 15*15/(1000*1000)
yes? LET msk2 = IF ( msk[d=1]  ge 50 ) then (1*msk_tmp2)*msk/100 else 0
yes? let RUsum=RU*msk2*km3
yes? list RUsum[k=1,x=@sum,y=@sum,l=@sum] 

Parameters: xds – filename of MARdataset, or an opened xarray representation
Returns: MAR mask with XF GrIS-specific post-processing applied. Fractional values from 0 to 1.
Return type: xr.DataArray