cf.Data.mean

Data.mean(axes=None, squeeze=False, mtol=1, weights=None, i=False)

Collapse axes with their weighted mean.

The weighted mean, \(\mu\), for array elements \(x_i\) and corresponding weights elements \(w_i\) is

\[\mu=\frac{\sum w_i x_i}{\sum w_i}\]

Missing data array elements and their corresponding weights are omitted from the calculation.

Parameters:

axes : (sequence of) int, optional

The axes to be collapsed. By default flattened input is used. Each axis is identified by its integer position. No axes are collapsed if axes is an empty sequence.

squeeze : bool, optional

If True then collapsed axes are removed. By default the axes which are collapsed are left in the result as axes with size 1, meaning that the result is guaranteed to broadcast correctly against the original array.

weights : data-like or dict, optional

Weights associated with values of the array. By default all non-missing elements of the array are assumed to have a weight equal to one. If weights is a data-like object then it must have either the same shape as the array or, if that is not the case, the same shape as the axes being collapsed. If weights is a dictionary then each key is axes of the array (an int or tuple of ints) with a corresponding data-like value of weights for those axes. In this case, the implied weights array is the outer product of the dictionary’s values.

Example: If weights={1: w, (2, 0): x} then w must contain 1-dimensionsal weights for axis 1 and x must contain 2-dimensionsal weights for axes 2 and 0. This is equivalent, for example, to weights={(1, 2, 0), y}, where y is the outer product of w and x. If axes=[1, 2, 0] then weights={(1, 2, 0), y} is equivalent to weights=y. If axes=None and the array is 3-dimensionsal then weights={(1, 2, 0), y} is equivalent to weights=y.transpose([2, 0, 1]).

mtol : number, optional

For each element in the output data array, the fraction of contributing input array elements which is allowed to contain missing data. Where this fraction exceeds mtol, missing data is returned. The default is 1, meaning a missing datum in the output array only occurs when its contributing input array elements are all missing data. A value of 0 means that a missing datum in the output array occurs whenever any of its contributing input array elements are missing data. Any intermediate value is permitted.

i : bool, optional

If True then update the data array in place. By default a new data array is created.

Returns:

out : cf.Data

The collapsed array.

See also

max, min, mid_range, range, sum, sd, var

Examples:

>>> d = cf.Data([[1, 2, 4], [1, 4, 9]], 'm')
>>> print d.array
[[1 2 4]
 [1 4 9]]

>>> d.mean()
<CF Data: 3.5 m>
>>> d.mean(squeeze=True)
<CF Data: [[3.5]] m>
>>> d.mean(axes=[0, 1])
<CF Data: 3.5 m>
>>> d.mean(axes=[1, 0])
<CF Data: 3.5 m>
>>> print d.mean(axes=0).array
[ 1.   3.   6.5]
>>> print d.mean(axes=1).array
[ 2.33333333  4.66666667]
>>> d.mean(axes=1, squeeze=True)
[[ 2.33333333]
 [ 4.66666667]]

>>> y = cf.Data([1, 3])
>>> x = cf.Data([1, 2, 1])
>>> w = cf.expand_dims(y, 1) * x
>>> print w.array
[[1 2 1]
 [3 6 3]]

>>> d.mean(weights=w)
<CF Data: 3.9375 m>
>>> d.mean(weights={(0, 1): w})
<CF Data: 3.9375 m>
>>> d.mean(axes=[0, 1], weights={(0, 1): w})
<CF Data: 3.9375 m>
>>> d.mean(axes=[1, 0], weights={(0, 1): w})
<CF Data: 3.9375 m>
>>> d.mean(axes=(0, 1), weights={1: x, 0: y})
<CF Data: 3.9375 m>

>>> d.mean(axes=1, weights=w)
<CF Data: [2.25, 4.5] m>
>>> d.mean(axes=1, weights=x)
<CF Data: [2.25, 4.5] m>
>>> d.mean(axes=1, weights={1: x})
<CF Data: [2.25, 4.5] m>
>>> d.mean(axes=1, weights={(0, 1): w})
<CF Data: [2.25, 4.5] m>
>>> d.mean(axes=1, weights={0: y, (1,): x})
<CF Data: [2.25, 4.5] m>

>>> d.mean(axes=1)
<CF Data: [2.33333333333, 4.66666666667] m>
>>> d.mean(axes=1, weights={0: y})
<CF Data: [2.33333333333, 4.66666666667] m>

>>> e = cf.Data(numpy.arange(24).reshape(3, 2, 4))
>>> print e.array
[[[ 0  1  2  3]
  [ 4  5  6  7]]
 [[ 8  9 10 11]
  [12 13 14 15]]
 [[16 17 18 19]
  [20 21 22 23]]]

>>> e.mean(axes=[0, 2])
<CF Data: [9.5, 13.5] >
>>> f = e.mean(axes=[0, 2], squeeze=True)
>>> f
<CF Data: [[[9.5, 13.5]]] >
>>> f.shape
(1, 2, 1)
>>> print e.mean(axes=[0, 1]).array
[ 10.  11.  12.  13.]
>>> print e.mean(axes=[0, 1], weights={(1, 0): w}).array
[ 11.  12.  13.  14.]

>>> e[0, 0] = cf.masked
>>> e[-1, -1] = cf.masked
>>> e[..., 2] = cf.masked
>>> print e.array
[[[-- -- -- --]
  [4 5 -- 7]]
 [[8 9 -- 11]
  [12 13 -- 15]]
 [[16 17 -- 19]
  [-- -- -- --]]]

>>> e.mean()
<CF Data: 11.3333333333 >
>>> print e.mean(axes=[0, 1]).array
[10.0 11.0 -- 13.0]
>>> print e.mean(axes=[0, 1], weights={(1, 0): w}).array
[9.666666666666666 10.666666666666666 -- 12.666666666666666]