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.
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
Return CommonData: 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 (ifKernel.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.
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
itemsRaises ValueError: 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 aConstraint.constrain_points()
method, and optionally anConstraint.get_iterator()
method  kernel – A
Kernel
instance which provides aKernel.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 (nonmasked) 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 (ifKernel.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.
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
Raises ValueError: 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 (nonmasked) 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 griddedgridded. :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 kD 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)¶ Colocation 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)¶ Colocation 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

get_value
(point, data)¶ Collocation using nearest neighbours along the face of the earth using a kD tree index.


class
cis.collocation.col_implementations.
nn_p
¶ Bases:
cis.collocation.col_implementations.nn_pressure
Nearest neighbour pressure kernel  alias for nn_pressure.

class
cis.collocation.col_implementations.
nn_pressure
¶ Bases:
cis.collocation.col_framework.Kernel

get_value
(point, data)¶  Collocation using nearest neighbours in pressure, where both points and
 data are a list of HyperPoints. The default point is the first point.


class
cis.collocation.col_implementations.
nn_t
¶ Bases:
cis.collocation.col_implementations.nn_time
Nearest neighbour time kernel  alias for nn_time.

class
cis.collocation.col_implementations.
nn_time
¶ Bases:
cis.collocation.col_framework.Kernel

get_value
(point, data)¶  Collocation using nearest neighbours in time, where both points and
 data are a list of HyperPoints. The default point is the first point.


class
cis.collocation.col_implementations.
stddev
¶ Bases:
cis.collocation.col_framework.AbstractDataOnlyKernel
Calculate the standard deviation

get_value_for_data_only
(values)¶ Return the standard deviation points
