cf.Field.weights

Field.weights(weights='auto', scale=False, components=False, methods=False, **kwargs)[source]

Return weights for the data array values.

By default weights components are created for all axes of the field by one or more of the following methods, in order of preference,

  1. Volume cell measures
  2. Area cell measures
  3. Area calculated from (grid) latitude and (grid) longitude dimension coordinates with bounds
  4. Cell sizes of dimension coordinates with bounds
  5. Equal weights

and the outer product of these weights components is returned in a field which is broadcastable to the orginal field (see the components parameter).

The methods used by the default behaviour may differ between fields, depending on which metadata they contain (see the methods parameter), so it is possible to force weights to be created with particular methods (see the weights parameter).

New in version 1.0.

See also

cell_area, collapse

Examples 1: 
>>> g = f.weights()
Parameters:
weights, kwargs: 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
    'auto' This the default. Weights are created for non-overlapping 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.
    None Equal weights for all axes.

  • Type 2: weights may be one, or a sequence, of:

    weights Description
    'area' Cell area weights from the field’s area cell measure construct or, if one doesn’t exist, from (grid) latitude and (grid) longitude dimension coordinates. Set the methods parameter to find out how the weights were actually created.
    'volume' Cell volume weights from the field’s volume cell measure construct.
    items Weights from the cell sizes of the dimension coordinate objects that would be selected by this call of the field’s dims method: f.dims(items, **kwargs). See cf.Field.dims for details.
    cf.Field Take weights from the data array of another field, which must be broadcastable to this field.

    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.

    Example:

    To create to 2-dimensional weights based on cell areas: f.weights('area'). To create to 3-dimensional weights based on cell areas and linear height: f.weights(['area', 'Z']).

scale: bool, optional

If True then scale the returned weights so that they are less than or equal to 1.

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’s data array with corresponding values of weights in cf.Data objects. The axes of weights match the axes of the field’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.
Returns:
out: cf.Field or dict

The weights field or, if components is True, orthogonal weights in a dictionary.
Examples 2: 
>>> f
<CF Field: air_temperature(time(1800), latitude(145), longitude(192)) K>
>>> f.weights()
<CF Field: long_name:weight(time(1800), latitude(145), longitude(192)) 86400 s.rad>
>>> f.weights('auto', scale=True)
<CF Field: long_name:weight(time(1800), latitude(145), longitude(192)) 1>
>>> f.weights('auto', components=True)
{(0,): <CF Data: [1.0, ..., 1.0] d>,
 (1,): <CF Data: [5.94949998503e-05, ..., 5.94949998503e-05]>,
 (2,): <CF Data: [0.0327249234749, ..., 0.0327249234749] radians>}
>>> f.weights('auto', components=True, scale=True)
{(0,): <CF Data: [1.0, ..., 1.0]>,
 (1,): <CF Data: [0.00272710399807, ..., 0.00272710399807]>,
 (2,): <CF Data: [1.0, ..., 1.0]>}
>>> f.weights('auto', methods=True)
{(0,): 'linear time',
 (1,): 'linear sine latitude',
 (2,): 'linear longitude'}