cf.Field.weights¶

Field.
weights
(weights=True, scale=None, measure=False, components=False, methods=False, radius='earth', data=False, great_circle=False, axes=None, cell_measures=True, coordinates=True, **kwargs)[source]¶ Return weights for the data array values.
The weights are those used during a statistical collapse of the data. For example when computing an area weight average.
Weights for any combination of axes may be returned.
Weights are either derived from the field construct’s metadata (such as coordinate cell sizes) or provided explicitly in the form of other
Field
constructs. In any case, the outer product of these weights components is returned in a field which is broadcastable to the original field (see the components parameter for returning the components individually).By default null, equal weights are returned.
New in version 1.0.
See also
 Parameters
 weights: optional
Specify the weights to be created. There are three distinct methods:
Type 1 will create weights for all axes of size greater than 1, raising an exception if this is not possible (this is the default).;
Type 2 will always succeed in creating weights for all axes of the field, even if some of those weights are null.
Type 3 allows particular types of weights to be defined for particular axes, and an exception will be raised if it is not possible to create the weights.
Type 1 and Type 2 come at the expense of not always being able to control exactly how the weights are created (although which methods were used can be inspected with use of the methods parameter).
Type 1: weights may be:
weights
Description
This is the default. Weights are created for all axes (or a subset of them, see the axes parameter). Set the methods parameter to find out how the weights were actually created.
The weights components are created for axes of the field by one or more of the following methods, in order of preference,
If the cell_measures parameter is True:
Volume cell measures (see the note on the measure parameter)
Area cell measures
If the coordinates parameter is True:
Area calculated from X and Y dimension coordinate constructs with bounds
Area calculated from 1d auxiliary coordinate constructs for geometries or a UGRID mesh topology.
Length calculated from 1d auxiliary coordinate constructs for geometries or a UGRID mesh topology.
Cell sizes of dimension coordinate constructs with bounds
Equal weights
and the outer product of these weights components is returned in a field constructs which is broadcastable to the original field construct (see the components parameter).
Type 2: weights may be one of:
weights
Description
Equal weights for all axes.
Equal weights for all axes.
Explicit weights in a
Data
object that must be broadcastable to the field construct’s data, unless the axes parameter is also set.Explicit weights in a dictionary of the form that is returned from a call to the
weights
method withcomponent=True
Type 3: weights may be one, or a sequence, of:
weights
Description
'area'
Cell area weights. The weights components are created for axes of the field by the following methods, in order of preference,
If the cell_measures parameter is True:
Area cell measures.
If the coordinates parameter is True:
X and Y dimension coordinate constructs with bounds.
X and Y 1d auxiliary coordinate constructs for polygon cells defined by geometries or a UGRID mesh topology.
Set the methods parameter to find out how the weights were actually created.
'volume'
Cell volume weights from the field construct’s volume cell measure construct (see the note on the measure parameter). Requires the cell_measures parameter to be True.
Weights from the cell sizes of the dimension coordinate construct with this identity.
Explicit weights from the data of another field construct, which must be broadcastable to this field construct.
If weights is a sequence of any combination of the above then the returned field contains the outer product of the weights defined by each element of the sequence. The ordering of the sequence is irrelevant.
 Parameter example:
To create to 2dimensional weights based on cell areas:
f.weights('area')
. To create to 3dimensional weights based on cell areas and linear height:f.weights(['area', 'Z'])
.
 scale: number, optional
If set to a positive number then scale the weights so that they are less than or equal to that number. If weights components have been requested (see the components parameter) then each component is scaled independently of the others.
 Parameter example:
To scale all weights so that they lie between 0 and 1:
scale=1
.
 measure:
bool
, optional Create weights that are cell measures, i.e. which describe actual cell sizes (e.g. cell areas) with appropriate units (e.g. metres squared).
Cell measures can be created for any combination of axes. For example, cell measures for a time axis are the time span for each cell with canonical units of seconds; cell measures for the combination of four axes representing time and three dimensional space could have canonical units of metres cubed seconds.
Note
Specifying cell volume weights via
weights=['X', 'Y', 'Z']
orweights=['area', 'Z']
(or other equivalents) will produce an incorrect result if the vertical dimension coordinates do not define the actual height or depth thickness of every cell in the domain. In this case,weights='volume'
should be used instead, which requires the field construct to have a “volume” cell measure construct.If
weights=True
then care also needs to be taken, as a “volume” cell measure construct will be used if present, otherwise the cell volumes will be calculated using the size of the vertical coordinate cells. radius: optional
Specify the radius of the latitudelongitude plane defined in spherical polar coordinates. The radius is that which would be returned by this call of the field construct’s
radius
method:f.radius(default=radius)
. The radius is defined by the datum of a coordinate reference construct, and if and only if no such radius is found then the default value given by the radius parameter is used instead. A value of'earth'
is equivalent to a default value of 6371229 metres. components:
bool
, optional If True then a dictionary of orthogonal weights components is returned instead of a field. Each key is a tuple of integers representing axis positions in the field construct’s data, with corresponding values of weights in
Data
objects. The axes of weights match the axes of the field construct’s data array in the order given by their dictionary keys. methods:
bool
, optional If True, then return a dictionary describing methods used to create the weights.
 data:
bool
, optional If True then return the weights in a
Data
instance that is broadcastable to the original data.New in version 3.1.0.
 great_circle:
bool
, optional If True then allow, if required, the derivation of i) area weights from polygon cells by assuming that each cell part is a spherical polygon composed of great circle segments; and ii) the derivation of linelength weights line cells by assuming that each line part is composed of great circle segments. Only applies to geometry and UGRID cells.
New in version 3.2.0.
 axes: (sequence of)
int
orstr
, optional Modify the behaviour when weights is
True
or aData
instance. Ignored for any other value the weights parameter.If weights is
True
then weights are created only for the specified axes (as opposed to all axes). I.e.weight=True, axes=axes
is identical toweights=axes
.If weights is a
Data
instance then the specified axes identify each dimension of the given weights. If the weights do not broadcast to the field construct’s data then setting the axes parameter is required so that the broadcasting can be inferred, otherwise setting the axes is not required. Parameter example:
axes='T'
 Parameter example:
axes=['longitude']
 Parameter example:
axes=[3, 1]
New in version 3.3.0.
 cell_measures:
bool
, optional If True, the default, then area and volume cell measure constructs are considered for weights creation when weights is
True
,'area'
, or'volume'
. If False then cell measure constructs are ignored for these weights.New in version 3.16.1.
 coordinates:
bool
, optional If True, the default, then coordinate constructs are considered for weights creation for weights of
True
or'area'
. If False then coordinate constructs are ignored for these weights.New in version 3.16.1.
kwargs: deprecated at version 3.0.0.
 Returns
Examples
>>> f <CF Field: air_temperature(time(12), latitude(145), longitude(192)) K> >>> f.weights() <CF Field: long_name:weight(time(12), latitude(145), longitude(192)) 86400 s.rad> >>> f.weights(scale=1.0) <CF Field: long_name:weight(time(12), latitude(145), longitude(192)) 1> >>> f.weights(components=True) {(0,): <CF Data(12): [30.0, ..., 31.0] d>, (1,): <CF Data(145): [5.94949998503e05, ..., 5.94949998503e05]>, (2,): <CF Data(192): [0.0327249234749, ..., 0.0327249234749] radians>} >>> f.weights(components=True, scale=1.0) {(0,): <CF Data(12): [0.967741935483871, ..., 1.0] 1>, (1,): <CF Data(145): [0.00272710399807, ..., 0.00272710399807]>, (2,): <CF Data(192): [1.0, ..., 1.0]>} >>> f.weights(components=True, scale=2.0) {(0,): <CF Data(12): [1.935483870967742, ..., 2.0] 1>, (1,): <CF Data(145): [0.00545420799614, ..., 0.00545420799614]>, (2,): <CF Data(192): [2.0, ..., 2.0]>} >>> f.weights(methods=True) {(0,): 'linear time', (1,): 'linear sine latitude', (2,): 'linear longitude'}