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.

More About

collapse all

Harmonic Mean

The harmonic mean of a sample X is

m=ni=1n1xi

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.

Extended Capabilities

Introduced before R2006a