Documentation

# harmmean

## Syntax

``m = harmmean(X)``
``m = harmmean(X,'all')``
``m = harmmean(X,dim)``
``m = harmmean(X,vecdim)``
``m = harmmean(___,nanflag)``

## Description

example

````m = harmmean(X)` calculates the harmonic mean of a sample. For vectors, `harmmean(X)` is the harmonic mean of the elements in `X`. For matrices, `harmmean(X)` is a row vector containing the harmonic means of each column. For N-dimensional arrays, `harmmean` operates along the first nonsingleton dimension of `X`.```

example

````m = harmmean(X,'all')` returns the harmonic mean of all elements of `X`.```

example

````m = harmmean(X,dim)` takes the harmonic mean along the operating dimension `dim` of `X`.```

example

````m = harmmean(X,vecdim)` returns the harmonic mean over the dimensions specified in the vector `vecdim`. Each element of `vecdim` represents a dimension of the input array `X`. The output `m` has length 1 in the specified operating dimensions. The other dimension lengths are the same for `X` and `m`. For example, if `X` is a 2-by-3-by-4 array, then ```harmmean(X,[1 2])``` returns a 1-by-1-by-4 array. Each element of the output array is the harmonic mean of the elements on the corresponding page of `X`.```

example

````m = harmmean(___,nanflag)` specifies whether to exclude `NaN` values from the calculation, using any of the input argument combinations in previous syntaxes. By default, `harmmean` includes `NaN` values in the calculation (`nanflag` has the value `'includenan'`). To exclude `NaN` values, set the value of `nanflag` to `'omitnan'`.```

## Examples

collapse all

Set the random seed for reproducibility of the results.

`rng('default')`

Create a matrix of exponential random numbers with 5 rows and 4 columns.

`X = exprnd(1,5,4)`
```X = 5×4 0.2049 2.3275 1.8476 1.9527 0.0989 1.2783 0.0298 0.8633 2.0637 0.6035 0.0438 0.0880 0.0906 0.0434 0.7228 0.2329 0.4583 0.0357 0.2228 0.0414 ```

Compute the harmonic and arithmetic means of the columns of `X`.

`harmonic = harmmean(X)`
```harmonic = 1×4 0.1743 0.0928 0.0797 0.1205 ```
`arithmetic = mean(X)`
```arithmetic = 1×4 0.5833 0.8577 0.5734 0.6357 ```

The arithmetic mean is greater than the harmonic mean for all the columns of `X`.

Find the harmonic mean of all the values in an array.

Create a 3-by-5-by-2 array `X`.

`X = reshape(1:30,[3 5 2])`
```X = X(:,:,1) = 1 4 7 10 13 2 5 8 11 14 3 6 9 12 15 X(:,:,2) = 16 19 22 25 28 17 20 23 26 29 18 21 24 27 30 ```

Find the harmonic mean of the elements of `X`.

`m = harmmean(X,'all')`
```m = 7.5094 ```

Find the harmonic mean along different operating dimensions and vectors of dimensions for a multidimensional array.

Create a 3-by-5-by-2 array `X`.

`X = reshape(1:30,[3 5 2])`
```X = X(:,:,1) = 1 4 7 10 13 2 5 8 11 14 3 6 9 12 15 X(:,:,2) = 16 19 22 25 28 17 20 23 26 29 18 21 24 27 30 ```

Find the harmonic mean of `X` along the default dimension.

`hmean1 = harmmean(X)`
```hmean1 = hmean1(:,:,1) = 1.6364 4.8649 7.9162 10.9392 13.9523 hmean1(:,:,2) = 16.9607 19.9666 22.9710 25.9743 28.9770 ```

By default, `harmmean` operates along the first dimension of `X` whose size does not equal 1. In this case, this dimension is the first dimension of `X`. Therefore, `hmean1` is a 1-by-5-by-2 array.

Find the harmonic mean of `X` along the second dimension.

`hmean2 = harmmean(X,2)`
```hmean2 = hmean2(:,:,1) = 3.1852 5.0641 6.5693 hmean2(:,:,2) = 21.1595 22.1979 23.2329 ```

`hmean2` is a 3-by-1-by-2 array.

Find the harmonic mean of `X` along the third dimension.

`hmean3 = harmmean(X,3)`
```hmean3 = 3×5 1.8824 6.6087 10.6207 14.2857 17.7561 3.5789 8.0000 11.8710 15.4595 18.8837 5.1429 9.3333 13.0909 16.6154 20.0000 ```

`hmean3` is a 3-by-5 array.

Find the harmonic mean of each page of `X` by specifying the first and second dimensions using the `vecdim` input argument.

`mpage = harmmean(X,[1 2])`
```mpage = mpage(:,:,1) = 4.5205 mpage(:,:,2) = 22.1645 ```

For example, `mpage(1,1,2)` is the harmonic mean of the elements in `X(:,:,2)`.

Find the harmonic mean of the elements in each `X(i,:,:)` slice by specifying the second and third dimensions.

`mrow = harmmean(X,[2 3])`
```mrow = 3×1 5.5369 8.2469 10.2425 ```

For example, `mrow(3)` is the harmonic mean of the elements in `X(3,:,:)` and is equivalent to specifying `harmmean(X(3,:,:),'all')`.

Create a vector and compute its `harmmean`, excluding `NaN` values.

```x = 1:10; x(3) = nan; % Replace the third element of x with a NaN value n = harmmean(x,'omitnan')```
```n = 3.4674 ```

If you do not specify `'omitnan'`, then `harmmean(x)` returns `NaN`.

collapse all

### Harmonic Mean

The harmonic mean of a sample `X` is

`$m=\frac{n}{\sum _{i=1}^{n}\frac{1}{{x}_{i}}}$`

where n is the number of values in `X`.

## Tips

• When `harmmean` computes the harmonic mean of an array containing `0`, the returned value is `0`.