cf.Field.weights¶

Field.
weights
(weights='auto', scale=None, measure=False, components=False, methods=False, radius='earth', **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 a 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 orginal field (see the components parameter for returning the components individually).By default null, equal weights are returned.
New in version 1.0.
Parameters:  weights: optional
Specify the weights to be created. There are two distinct methods: type 1 will always succeed in creating weights for all axes of the field, at the expense of not always being able to control exactly how the weights are created (see the methods parameter); type 2 allows particular types of weights to be defined for particular axes, and an exception will be raised if it is not possible to the create weights.
 Type 1: weights may be one of:
weights Description None
Equal weights for all axes. This the default. 'auto'
Weights are created for nonoverlapping subsets of the axes by the methods enumerated in the above notes. Set the methods parameter to find out how the weights were actually created.
In this case weights components are created for all axes of the field by one or more of the following methods, in order of preference,
 Volume cell measures
 Area cell measures
 Area calculated from (grid) latitude and (grid) longitude dimension coordinate constructs with bounds
 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 orginal field construct (see the components parameter).
Data
Explicit weights in a Data
object that must be broadcastable to the field construct’s data.Field
Explicit weights from the data of another field construct, which must be broadcastable to this field construct’s data. dict
Explicit weights in dictionary of the form that is returned from a call to the weights
method withcomponent=True
 Type 2: weights may be one, or a sequence, of:
weights Description 'area'
Cell area weights from the field construct’s area cell measure construct or, if one doesn’t exist, from (grid) latitude and (grid) longitude dimension coordinate constructs. 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. str
Weights from the cell sizes of the dimension coordinate construct with this identity. Field
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. radius: optional
Specify the radius used for calculating the areas of cells 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(radius)
. See thecf.Field.radius
for details.By default radius is
'earth'
which means that if and only if the radius can not found from the datums of any coordinate reference constucts, then the default radius taken as 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 axes 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.
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('auto', scale=1.0) <CF Field: long_name:weight(time(12), latitude(145), longitude(192)) 1> >>> f.weights('auto', 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('auto', 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('auto', 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('auto', methods=True) {(0,): 'linear time', (1,): 'linear sine latitude', (2,): 'linear longitude'}