improver.spotdata.build_spotdata_cube module

Functions to create spotdata cubes.

build_spotdata_cube(data, name, units, altitude, latitude, longitude, wmo_id, unique_site_id=None, unique_site_id_key=None, scalar_coords=None, auxiliary_coords=None, neighbour_methods=None, grid_attributes=None, additional_dims=None, additional_dims_aux=None)

Function to build a spotdata cube with expected dimension and auxiliary coordinate structure.

It can be used to create spot data cubes. In this case the data is the spot data values at each site, and the coordinates that describe each site.

It can also be used to create cubes which describe the grid points that are used to extract each site from a gridded field, for different selection method. The selection methods are specified by the neighbour_methods coordinate. The grid_attribute coordinate encapsulates information required to extract data, for example the x/y indices that identify the grid point neighbour.

Examples

For a cube containing diagnostic values:

air_temperature / (K)             (index: 5)
    Dimension coordinates:
         time                            -
         index                           x
    Auxiliary coordinates:
         forecast_period                 -
         altitude                        x
         latitude                        x
         longitude                       x
         utc_offset                      x
         wmo_site                        x
    Scalar coordinates:
         forecast_reference_time: 2018-07-13 09:00:00
         height: 1.5 m

Or for a cube identifying grid point neighbours:

ukvx_grid_neighbour / (1)           (spot_index: 100; neighbour_selection_method: 3; grid_attribute: 3)
    Dimension coordinates:
         spot_index                           x                                -                  -
         neighbour_selection_method           -                                x                  -
         grid_attribute                       -                                -                  x
    Auxiliary coordinates:
         altitude                             x                                -                  -
         latitude                             x                                -                  -
         longitude                            x                                -                  -
         wmo_ids                              x                                -                  -
         neighbour_selection_method_name      -                                x                  -
         grid_attribute_key                   -                                -                  x

where the neighbour_selection dimension coordinate is necessarily numeric, but the string names of the methods can be found in the associated neighbour_selection_method_name auxiliary coordinate, e.g.:

AuxCoord(array(['nearest', 'nearest_land', 'nearest_land_minimumdz', 'bilinear'], dtype='<U22'),
   standard_name=None, units=Unit('1'), long_name='neighbour_selection_method_name')

The grid attribute coordinate contains the information necessary for extracting and adjusting diagnostic data from a gridded field. The names of the elements of this coordinate can be found in the grid_attribute_key auxiliary coordinate, e.g.:

AuxCoord(array(['x_index', 'y_index', 'vertical_displacement'], dtype='<U22'),
   standard_name=None, units=Unit('1'), long_name='grid_attribute_key')

Parameters:

• data (ndarray) – Float spot data or array of data points from several sites. The spot index should be the last dimension if the array is multi-dimensional (see optional additional dimensions below).

• name (str) – Cube name (eg ‘air_temperature’)

• units (str) – Cube units (eg ‘K’)

• altitude (ndarray) – Float or 1d array of site altitudes in metres

• latitude (ndarray) – Float or 1d array of site latitudes in degrees

• longitude (ndarray) – Float or 1d array of site longitudes in degrees

• wmo_id (Union[str, List[str]]) – String or list of 5-digit WMO site identifiers.

• unique_site_id (Union[List[str], ndarray, None]) – Optional list of 8-digit unique site identifiers. If provided, this is expected to be a complete list with a unique identifier for every site.

• unique_site_id_key (Optional[str]) – String to name the unique_site_id coordinate. Required if unique_site_id is in use.

• scalar_coords (Optional[List[Coord]]) – Optional list of iris.coords.Coord instances

• auxiliary_coords (Optional[List[Coord]]) – Optional list of iris.coords.Coord instances which are non-scalar.

• neighbour_methods (Optional[List[str]]) – Optional list of neighbour method names, e.g. ‘nearest’

• grid_attributes (Optional[List[str]]) – Optional list of grid attribute names, e.g. x-index, y-index

• additional_dims (Optional[List[Coord]]) – Optional list of additional dimensions to preceed the spot data dimension.

• additional_dims_aux (Optional[List[List[AuxCoord]]]) – Optional list of auxiliary coordinates associated with each dimension in additional_dims

Return type:

Cube

Returns:

A cube containing the extracted spot data with spot data being the final dimension.