17.2.5.3. cis.collocation package¶

17.2.5.3.1. cis.collocation.col module¶

Top level collocation objects

class cis.collocation.col.Collocate(sample_points, missing_data_for_missing_sample=False, collocator_factory=<cis.collocation.col.CollocatorFactory object>)¶

Bases: object

Perform a general collocation

collocate(data, col_name=None, col_params=None, kern=None, kern_params=None)¶

Perform the collocation.

Return CommonData:
Parameters:	data (CommonData) – Data to collocate col_name (str) – Name of the collocator col_params (dict) – Parameters dictionary for the collocation and constraint kern (str) – The kernel to use kern_params (dict) – The kernel parameters to use
	The collocated data
Raises CoordinateNotFoundError:
	If the collocator was unable to compare the sample and data points

class cis.collocation.col.CollocatorFactory¶

Bases: object

Class for creating Collocator, Constraint and Kernel instances

get_collocator_instances_for_method(method_name, kernel_name, collocator_params, kernel_params, sample_gridded, data_gridded)¶: Get instances of the correct classes for collocation :param method_name: Collocation method name (e.g. ‘lin’, ‘nn’) :param kernel_name: Kernel class name :param collocator_params: Collocation parameters :param kernel_params: Kernel parameters :param sample_gridded: Is the sample data gridded? :param data_gridded: Is the collocation data gridded? :return: Collocator, Constrain and Kernel instances

get_default_collocator_name(method_name, sample_gridded, data_gridded)¶

17.2.5.3.2. cis.collocation.col_framework module¶

class cis.collocation.col_framework.AbstractDataOnlyKernel¶

Bases: cis.collocation.col_framework.Kernel

A Kernel that can work on data only, e.g. mean only requires the data values to calculate the mean, not the sampling point.

get_value(point, data)¶

This method is redundant in the AbstractDataOnlyKernel and only serves as an interface to AbstractDataOnlyKernel(), removing the unnecessary point and checking for one or more data points.

Parameters:	point – A single HyperPoint data – A set of data points to reduce to a single value
Returns:	For return_size=1 a single value (number) otherwise a list of returns values, which represents some operation on the points provided

get_value_for_data_only(values)¶

This method should return a single value (if Kernel.return_size is 1) or a list of n values (if Kernel.return_size is n) based on some calculation on the the values (a numpy array).

Note that this method will be called for every sample point in which data can be placed and so could become a bottleneck for calculations, it is advisable to make it as quick as is practical. If this method is unable to provide a value (for example if no data points were given) a ValueError should be thrown. This method will not be called if there are no values to be used for calculations.

Raises ValueError:
Parameters:	values – A numpy array of values (can not be none or empty)
Returns:	A single data item if return_size is 1 or a list of items containing `Kernel.return_size` items
	If there are any problems creating a value

class cis.collocation.col_framework.CellConstraint¶

Bases: cis.collocation.col_framework.Constraint

Superclass of constraints acting on cells surrounding sample points.

The point argument in constrain_points is a HyperPoint in which the coordinate values are of type iris.coords.Cell.

get_iterator(missing_data_for_missing_sample, coord_map, coords, data_points, shape, points, output_data)¶

class cis.collocation.col_framework.Collocator(fill_value=None, var_name='', var_long_name='', var_units='', missing_data_for_missing_sample=False)¶

Bases: object

Class which provides a method for performing collocation. This just defines the interface which the subclasses must implement.

collocate(points, data, constraint, kernel)¶

The method is responsible for setting up and running the collocation. It should take a set of data and map that onto the given (sample) points using the constraint and kernel provided.

Parameters:	points – A set of sample points onto which we will collocate some other ‘data’ data – Some other data to be collocated onto the ‘points’ constraint – A `Constraint` instance which provides a `Constraint.constrain_points()` method, and optionally an `Constraint.get_iterator()` method kernel – A `Kernel` instance which provides a `Kernel.get_value()` method
Returns:	One or more `CommonData` (or subclasses of) objects whose coordinates lie on the points defined above.

class cis.collocation.col_framework.Constraint¶

Bases: object

Class which provides a method for constraining a set of points. A single HyperPoint is given as a reference but the data points to be reduced ultimately may be of any type. This just defines the interface which the subclasses must implement.

constrain_points(point, data)¶

This method should return a subset of the data given a single reference point. It is expected that the data returned should be of the same type as that given - but this isn’t mandatory. It is possible that this function will return zero points (no data), the collocation class is responsible for providing a fill_value.

Parameters:	point (HyperPoint) – A single HyperPoint data – A set of data points to be reduced
Returns:	A reduced set of data points

get_iterator(missing_data_for_missing_sample, coord_map, coords, data_points, shape, points, output_data)¶

Iterator to iterate through the points needed to be calculated. The default iterator, iterates through all the sample points calling Constraint.constrain_points() for each one.

Parameters:

missing_data_for_missing_sample – If true anywhere there is missing data on the sample then final point is missing; otherwise just use the sample
coord_map – Coordinate map - list of tuples of indexes of hyperpoint coord, data coords and output coords
coords – The coordinates to map the data onto
data_points – The (non-masked) data points
shape – Shape of the final data values
points – The original points object, these are the points to collocate
output_data – Output data set

Returns:

Iterator which iterates through (sample indices, hyper point and constrained points) to be placed in these points

class cis.collocation.col_framework.IndexedConstraint¶

Bases: cis.collocation.col_framework.Constraint

Superclass of constraints that expect points to be referenced by index.

get_iterator(missing_data_for_missing_sample, coord_map, coords, data_points, shape, points, output_data)¶

class cis.collocation.col_framework.Kernel¶

Bases: object

Class which provides a method for taking a number of points and returning one value. For example a nearest neighbour algorithm or sort algorithm or mean. This just defines the interface which the subclasses must implement.

get_value(point, data)¶

This method should return a single value (if Kernel.return_size is 1) or a list of n values (if Kernel.return_size is n) based on some calculation on the data given a single point.

The data is deliberately left unspecified in the interface as it may be any type of data, however it is expected that each implementation will only work with a specific type of data (gridded, ungridded etc.) Note that this method will be called for every sample point and so could become a bottleneck for calculations, it is advisable to make it as quick as is practical. If this method is unable to provide a value (for example if no data points were given) a ValueError should be thrown.

Raises ValueError:
Parameters:	point – A single HyperPoint data – A set of data points to reduce to a single value
Returns:	For return_size=1 a single value (number) otherwise a list of return values, which represents some operation on the points provided
	When the method is unable to return a value

get_variable_details(var_name, var_long_name, var_standard_name, var_units)¶

Returns the details of all variables to be created from the outputs of a kernel.

Parameters:	var_name (str) – Base variable name var_long_name (str) – Base variable long name var_standard_name (str) – Base variable standard_name var_units (str) – Base variable units
Returns:	Tuple of tuples, each containing (variable name, variable long name, variable units)

return_size = 1¶: The number of values the Kernel.get_value() should be expected to return (i.e. the length of the return list).

class cis.collocation.col_framework.PointConstraint¶

Bases: cis.collocation.col_framework.Constraint

Superclass of constraints acting on sample points.

The point argument in constrain_points is a HyperPoint.

cis.collocation.col_framework.get_collocator(method=None)¶: Top level routine for finding the correct Collocator object. :param method: The collocate method to find - this should be a string which matches the name of one of the subclasses of Collocator :return: One of Collocator’s subclasses

cis.collocation.col_framework.get_constraint(method=None)¶: Top level routine for finding the correct Constraint object. This doesn’t instantiate the constraint class as it may need variables passed to the constructor :param method: The constraint method to find - this should be a string which matches the name of one of the subclasses of Constraint :return: One of Constraint’s subclasses

cis.collocation.col_framework.get_kernel(method=None)¶: Top level routine for finding the correct Kernel object. :param method: The kernel method to find - this should be a string which matches the name of one of the subclasses of Kernel :return: One of Kernel’s subclasses

17.2.5.3.3. cis.collocation.col_implementations module¶

class cis.collocation.col_implementations.BinnedCubeCellOnlyConstraint¶

Bases: cis.collocation.col_framework.Constraint

Constraint for constraining HyperPoints to be within an iris.coords.Cell. With an iterator which only travels over those cells with a value in.

Uses the index_data method to bin all the points.

constrain_points(sample_point, data)¶

get_iterator(missing_data_for_missing_sample, coord_map, coords, data_points, shape, points, output_data)¶

get_iterator_for_data_only(missing_data_for_missing_sample, coord_map, coords, data_points, shape, points, values)¶

The method returns an iterator over the output indices and a numpy array slice of the data values. This may not be called by all collocators who may choose to iterate over all sample points instead.

Parameters:

missing_data_for_missing_sample – If true anywhere there is missing data on the sample then final point is missing; otherwise just use the sample
coord_map – Not needed for the data only kernel
coords – Not needed for the data only kernel
data_points – The (non-masked) data points
shape – Not needed
points – The original points object, these are the points to collocate
values – Not needed

Returns:

Iterator which iterates through (sample indices and data slice) to be placed in these points

class cis.collocation.col_implementations.BinningCubeCellConstraint¶

Bases: cis.collocation.col_framework.IndexedConstraint

Constraint for constraining HyperPoints to be within an iris.coords.Cell.

Uses the index_data method to bin all the points

constrain_points(sample_point, data)¶

Returns HyperPoints lying within a cell.

This implementation returns the points that have been stored in the appropriate bin by the index_data method. :param sample_point: HyperPoint of indices of cells defining sample region :param data: list of HyperPoints to check :return: HyperPointList of points found within cell

class cis.collocation.col_implementations.CubeCellConstraint¶

Bases: cis.collocation.col_framework.CellConstraint

Constraint for constraining HyperPoints to be within an iris.coords.Cell.

constrain_points(sample_point, data)¶: Returns HyperPoints lying within a cell. :param sample_point: HyperPoint of cells defining sample region :param data: list of HyperPoints to check :return: HyperPointList of points found within cell

class cis.collocation.col_implementations.DummyCollocator(fill_value=None, var_name='', var_long_name='', var_units='', missing_data_for_missing_sample=False)¶

Bases: cis.collocation.col_framework.Collocator

collocate(points, data, constraint, kernel)¶

This collocator does no collocation at all - it just returns the original data values. This might be useful if the input data for one variable is already known to be on the same grid as points. This routine could check the coordinates are the same but currently does no such check.

Parameters:	points – A list of HyperPoints data – An UngriddedData object or Cube constraint – Unused kernel – Unused
Returns:	A single LazyData object

class cis.collocation.col_implementations.DummyConstraint¶

Bases: cis.collocation.col_framework.Constraint

constrain_points(point, data)¶

class cis.collocation.col_implementations.GeneralGriddedCollocator(fill_value=None, var_name='', var_long_name='', var_units='', missing_data_for_missing_sample=False)¶

Bases: cis.collocation.col_framework.Collocator

Performs collocation of data on to the points of a cube (ie onto a gridded dataset).

collocate(points, data, constraint, kernel)¶

Parameters:	points – cube defining the sample points data – CommonData object providing data to be collocated (or list of Data) constraint – instance of a Constraint subclass, which takes a data object and returns a subset of that data based on it’s internal parameters kernel – instance of a Kernel subclass which takes a number of points and returns a single value
Returns:	GriddedDataList of collocated data

class cis.collocation.col_implementations.GeneralUngriddedCollocator(fill_value=None, var_name='', var_long_name='', var_units='', missing_data_for_missing_sample=False)¶

Bases: cis.collocation.col_framework.Collocator

Collocator for locating onto ungridded sample points

collocate(points, data, constraint, kernel)¶

This collocator takes a list of HyperPoints and a data object (currently either Ungridded data or a Cube) and returns one new LazyData object with the values as determined by the constraint and kernel objects. The metadata for the output LazyData object is copied from the input data object.

Parameters:

points – UngriddedData or UngriddedCoordinates defining the sample points
data – An UngriddedData object or Cube, or any other object containing metadata that the constraint object can read. May also be a list of objects, in which case a list will be returned
constraint – An instance of a Constraint subclass which takes a data object and returns a subset of that data based on it’s internal parameters
kernel – An instance of a Kernel subclass which takes a number of points and returns a single value

Returns:

A single LazyData object

class cis.collocation.col_implementations.GriddedCollocator(var_name='', var_long_name='', var_units='', missing_data_for_missing_sample=False)¶

Bases: cis.collocation.col_framework.Collocator

collocate(points, data, constraint, kernel)¶: This collocator takes two Iris cubes, and collocates from the data cube onto the grid of the ‘points’ cube. The collocator then returns another Iris cube. :param points: An Iris cube with the sampling grid to collocate onto. :param data: The Iris cube with the data to be collocated. :param constraint: None allowed yet, as this is unlikely to be required for gridded-gridded. :param kernel: The kernel to use, current options are gridded_gridded_nn and gridded_gridded_li. :return: An Iris cube with the collocated data.

class cis.collocation.col_implementations.SepConstraint(h_sep=None, a_sep=None, p_sep=None, t_sep=None)¶

Bases: cis.collocation.col_framework.PointConstraint

alt_constraint(point, ref_point)¶

constrain_points(ref_point, data)¶

horizontal_constraint(point, ref_point)¶

pressure_constraint(point, ref_point)¶

time_constraint(point, ref_point)¶

class cis.collocation.col_implementations.SepConstraintKdtree(h_sep=None, a_sep=None, p_sep=None, t_sep=None)¶

Bases: cis.collocation.col_framework.PointConstraint

A separation constraint that uses a k-D tree to optimise spatial constraining. If no horizontal separation parameter is supplied, this reduces to an exhaustive search using the other parameter(s).

alt_constraint(point, ref_point)¶

constrain_points(ref_point, data)¶

horizontal_constraint(point, ref_point)¶

pressure_constraint(point, ref_point)¶

time_constraint(point, ref_point)¶

class cis.collocation.col_implementations.gridded_gridded_li¶

Bases: cis.collocation.col_framework.Kernel

get_value(point, data)¶: Not needed for gridded/gridded collocation.

class cis.collocation.col_implementations.gridded_gridded_nn¶

Bases: cis.collocation.col_framework.Kernel

get_value(point, data)¶: Not needed for gridded/gridded collocation.

class cis.collocation.col_implementations.li(extrapolate=False, nn_vertical=False)¶

Bases: cis.collocation.col_framework.Kernel

Linear Interpolation Kernel

get_value(point, data)¶: Co-location routine using iris’ linear interpolation algorithm. This only makes sense for gridded data.

cis.collocation.col_implementations.make_coord_map(points, data)¶: Create a map for how coordinates from the sample points map to the standard hyperpoint coordinates. Ignoring coordinates which are not present in the data :param points: sample points :param data: data to map :return: list of tuples, each tuple is index of coordinate to use tuple is (hyper point coord index, sample point coord index, output coord index)

class cis.collocation.col_implementations.max¶

Bases: cis.collocation.col_framework.AbstractDataOnlyKernel

Calculate the maximum value

get_value_for_data_only(values)¶: Return the maximum value

class cis.collocation.col_implementations.mean¶

Bases: cis.collocation.col_framework.AbstractDataOnlyKernel

Calculate mean of data points

get_value_for_data_only(values)¶: return the mean

class cis.collocation.col_implementations.min¶

Bases: cis.collocation.col_framework.AbstractDataOnlyKernel

Calculate the minimum value

get_value_for_data_only(values)¶: Return the minimum value

class cis.collocation.col_implementations.moments(mean_name='', stddev_name='', nopoints_name='')¶

Bases: cis.collocation.col_framework.AbstractDataOnlyKernel

get_value_for_data_only(values)¶: Returns the mean, standard deviation and number of values

get_variable_details(var_name, var_long_name, var_standard_name, var_units)¶: Sets name and units for mean, standard deviation and number of points variables, based on those of the base variable or overridden by those specified as kernel parameters. :param var_name: base variable name :param var_long_name: base variable long name :param var_standard_name: base variable standard name :param var_units: base variable units :return: tuple of tuples each containing (variable name, variable long name, variable units)

return_size = 3¶

class cis.collocation.col_implementations.nn_a¶

Bases: cis.collocation.col_implementations.nn_altitude

Nearest neighbour altitude kernel - alias for nn_altitude.

class cis.collocation.col_implementations.nn_altitude¶

Bases: cis.collocation.col_framework.Kernel

get_value(point, data)¶

Collocation using nearest neighbours in altitude, where both points and: data are a list of HyperPoints. The default point is the first point.

class cis.collocation.col_implementations.nn_gridded¶

Bases: cis.collocation.col_framework.Kernel

get_value(point, data)¶: Co-location routine using nearest neighbour algorithm optimized for gridded data. This calls out to iris to do the work.

class cis.collocation.col_implementations.nn_h¶

Bases: cis.collocation.col_implementations.nn_horizontal

Nearest neighbour horizontal kernel - alias for nn_horizontal.

class cis.collocation.col_implementations.nn_horizontal¶

Bases: cis.collocation.col_framework.Kernel

get_value(point, data)¶

Collocation using nearest neighbours along the face of the earth where both points and: data are a list of HyperPoints. The default point is the first point.

class cis.collocation.col_implementations.nn_horizontal_kdtree¶

Bases: cis.collocation.col_framework.Kernel