The datain module.

This module implements functions to various input tasks for monc_utils.

New at 0.4

1. Provides input of UM idealised fields with functionality of monc_utils.io.datain

   • Using get_um_field() to read a UM field using its stash code.

   • Using get_um_data() to read a UM field using a name similar to MONC.

     Currently only a small mapping from name to STASH code is provided.

   • Using get_um_data_on_grid() the result is interpolated to the required grid and the name appended _on_grid, with grid the requested grid.

   • Nesting is allowed, e.g. 'dbydy(dbydx(th_L))'.

Detailed Module Contents

The entire module is documented below.

Created on Mon Aug 2 11:01:11 2021.

@author: Peter Clark

monc_utils.io_um.datain.set_um_datain_options(opts)

monc_utils.io_um.datain.set_um_stashmap(stash_map_update)

monc_utils.io_um.datain.clean_dims(field, keep_dims=None)

monc_utils.io_um.datain.get_coord(field, dimname)

monc_utils.io_um.datain.coords_to_latlon(field: DataArray, offsets: Optional[dict] = None)

Identify coordinates in Lat/Long (or rotated Lat/Long) grid, create dimension coordinates x_p, x_u, y_p, y_v, z_p or z_w and modify original (now non-dimension) coordinates to indicate u, v, w, or p grid. In the horizontal add coordinate values in terms of grid index, taking account of staggering (so x_u starts at -0.5).

The optional input offsets is intended for data cut out of a larger grid (e.g. the inner part of a variable resolution grid) and provides an offset in each direction added to the grid index.

The code looks for coordinates containing ‘longitude’,’latitude’ and ‘model_level’. It uses the field.name and internal lookup table var_properties to detrmine the grid.

Parameters:

• field (xr.DataArray) – DataArray to be modified.

• offsets (dict, optional) – Numeric offsets added to grid index. The default is None. Keys are ‘x’, ‘y’, ‘z’]

Returns:

field – DESCRIPTION.

Return type:

TYPE

monc_utils.io_um.datain.coords_to_cartesian(field)

monc_utils.io_um.datain.get_um_field(ds, stash: Optional[str] = None, name: Optional[str] = None)

Read DataArray corresponding to stash_code from xarray dataset, Changing coordinates to more MONC-like.

Parameters:

• ds (xarray Dataset) – Input (at least 2D) data.

• name (str) – Actual variable name

• stash (str) – Of form ‘m01snnimmm’ with nn = section and mmm item.

Returns:

field – Required data.

Return type:

xarray.core.dataarray.DataArray

monc_utils.io_um.datain.get_derived_um_vars(source_dataset, var_name: str, derived_vars: dict, options: Optional[dict] = None)

Get data from source_dataset and compute required variable.

Parameters:

• source_dataset (xarray.Dataset) – Input (at least 2D) data.

• var_name (str) – Name of variable to retrieve.

• derived_vars (dict) – Maps var_name to function name and argument list.

• options (dict (optional - default=None)) – Options. Options possibly used are ‘dx’ and ‘dy’.

Returns:

vard – Required data.

Return type:

xarray.core.dataarray.DataArray

monc_utils.io_um.datain.get_um_data(source_dataset, var_name: str, options: Optional[dict] = None, allow_none: bool = False)

Extract data or derived data field from source NetCDF dataset.

If var_name is in source_dataset it is retrieved; if one of the primary variables with a key in var_properties the grid is corrected. Otherwise, it is assumed to be on a ‘theta’ point.

Currently written for UM data, enforcing C-grid. Returned coords are ‘x_p’, ‘x_u’, ‘y_p’, ‘y_v’, ‘z_w’, ‘z_p’.

Alternative names of variables can be supplied in options[‘aliases’] as a list of strings. If var_name is not found in source_dataset the first alias present in source_dataset is retrieved and renamed to var_name.

Currently supported derived data are specified if the thermodynamics module.

The special var_name ‘thref’ retrieves the reference theta profile.

Parameters:

• source_dataset (xarray Dataset) – Input (at least 2D) data.

• var_name (str) – Name of variable to retrieve.

• options (dict (optional - default=None)) – Options possibly used are ‘dx’ and ‘dy’.

• allow_none (bool (optional - default=False)) – If True, return None if not found.

Returns:

vard – Output data field.

Return type:

xarray.core.dataarray.DataArray

@author: Peter Clark

monc_utils.io_um.datain.get_um_and_transform(source_dataset, var_name, options=None, grid='p')

Extract data from dataset and transform to alternative grid.

See get_data for derived variables.

Parameters:

• source_dataset (xarray Dataset) – Input (at least 2D) data.

• var_name (str) – Name of variable to retrieve.

• options (dict (optional - default=None)) – Options. Options possibly used are ‘dx’ and ‘dy’.

• grid (str, optional) – Destination grid ‘u’, ‘v’, ‘w’ or ‘p’. Default is ‘p’.

Returns:

var – Output data field.

Return type:

xarray.core.dataarray.DataArray

@author: Peter Clark

monc_utils.io_um.datain.get_um_data_on_grid(source_dataset, var_name, derived_dataset=None, options=None, rename_time=False, grid='p')

Find data from source_dataset remapped to destination grid.

Uses data from derived_dataset if present, otherwise uses get_and_transform to input from source_dataset and remap grid. In this case, if options[‘save_all’]==’yes’, save the remapped data to derived_dataset.

See get_data for derived variables.

Parameters:

• source_dataset (xarray Dataset) – Input (at least 2D) data.

• var_name (str) – Name of variable to retrieve.

• derived_dataset (dict, optional) – ‘ds’ points to xarray Dataset, ‘file’ to output file path.

• options (dict, (optional - default=None)) – Options. Options possibly used are ‘dx’ and ‘dy’.

• grid (str, optional) – Destination grid ‘u’, ‘v’, ‘w’ or ‘p’. Default is ‘p’.

• Returns –

  var: xarray.core.dataarray.DataArray

  Output data field.

• @author (Peter Clark) –

monc_utils.io_um.datain.get_mean(vard)

monc_utils.io_um.datain.get_um_coords(field)

monc_utils.io_um.datain.get_um_grid_desc(cg)

Created on Mon Aug 2 11:21:15 2021

@author: Peter Clark