# dask.array.ma.average

### dask.array.ma.average(a, axis=None, weights=None, returned=False, keepdims=False)

Return the weighted average of array over the given axis.

This docstring was copied from numpy.ma.average.

Some inconsistencies with the Dask version may exist.

* **Parameters:**
  **a**
  : Data to be averaged.
    Masked entries are not taken into account in the computation.

  **axis**
  : Axis or axes along which to average a.  The default,
    axis=None, will average over all of the elements of the input array.
    If axis is a tuple of ints, averaging is performed on all of the axes
    specified in the tuple instead of a single axis or all the axes as
    before.

  **weights**
  : An array of weights associated with the values in a. Each value in
    a contributes to the average according to its associated weight.
    The array of weights must be the same shape as a if no axis is
    specified, otherwise the weights must have dimensions and shape
    consistent with a along the specified axis.
    If weights=None, then all data in a are assumed to have a
    weight equal to one.
    The calculation is:
    ```default
    avg = sum(a * weights) / sum(weights)
    ```
    <br/>
    where the sum is over all included elements.
    The only constraint on the values of weights is that sum(weights)
    must not be 0.

  **returned**
  : Flag indicating whether a tuple `(result, sum of weights)`
    should be returned as output (True), or just the result (False).
    Default is False.

  **keepdims**
  : If this is set to True, the axes which are reduced are left
    in the result as dimensions with size one. With this option,
    the result will broadcast correctly against the original a.
    *Note:* keepdims will not work with instances of numpy.matrix
    or other classes whose methods do not support keepdims.
    <br/>
    #### Versionadded
    Added in version 1.23.0.
* **Returns:**
  **average, [sum_of_weights]**
  : The average along the specified axis. When returned is True,
    return a tuple with the average as the first element and the sum
    of the weights as the second element. The return type is np.float64
    if a is of integer type and floats smaller than float64, or the
    input data-type, otherwise. If returned, sum_of_weights is always
    float64.
* **Raises:**
  ZeroDivisionError
  : When all weights along axis are zero. See numpy.ma.average for a
    version robust to this type of error.

  TypeError
  : When weights does not have the same shape as a, and axis=None.

  ValueError
  : When weights does not have dimensions and shape consistent with a
    along specified axis.

### Examples

```pycon
>>> import numpy as np
>>> a = np.ma.array([1., 2., 3., 4.], mask=[False, False, True, True])
>>> np.ma.average(a, weights=[3, 1, 0, 0])
1.25
```

```pycon
>>> x = np.ma.arange(6.).reshape(3, 2)
>>> x
masked_array(
  data=[[0., 1.],
        [2., 3.],
        [4., 5.]],
  mask=False,
  fill_value=1e+20)
>>> data = np.arange(8).reshape((2, 2, 2))
>>> data
array([[[0, 1],
        [2, 3]],
       [[4, 5],
        [6, 7]]])
>>> np.ma.average(data, axis=(0, 1), weights=[[1./4, 3./4], [1., 1./2]])
masked_array(data=[3.4, 4.4],
         mask=[False, False],
   fill_value=1e+20)
>>> np.ma.average(data, axis=0, weights=[[1./4, 3./4], [1., 1./2]])
Traceback (most recent call last):
    ...
ValueError: Shape of weights must be consistent
with shape of a along specified axis.
```

```pycon
>>> avg, sumweights = np.ma.average(x, axis=0, weights=[1, 2, 3],
...                                 returned=True)
>>> avg
masked_array(data=[2.6666666666666665, 3.6666666666666665],
             mask=[False, False],
       fill_value=1e+20)
```

With `keepdims=True`, the following result has shape (3, 1).

```pycon
>>> np.ma.average(x, axis=1, keepdims=True)
masked_array(
  data=[[0.5],
        [2.5],
        [4.5]],
  mask=False,
  fill_value=1e+20)
```

<!-- !! processed by numpydoc !! -->
