harmmean

Harmonic mean

Syntax

m = harmmean(X)

m = harmmean(X,'all')

m = harmmean(X,dim)

m = harmmean(X,vecdim)

m = harmmean(___,nanflag)

Description

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.

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

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

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.

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

Compare Harmonic and Arithmetic Mean

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.

Harmonic Mean of All Values

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

Harmonic Mean Along Specified Dimensions

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').

Harmonic Mean Excluding NaN

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

Harmonic Mean

The harmonic mean of a sample X is

$$m=\frac{n}{{\displaystyle \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.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The harmmean function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• These input arguments are not supported: 'all', vecdim, and nanflag.

• The dim input argument must be a compile-time constant.

• If you do not specify the dim input argument, the working (or operating) dimension can be different in the generated code. As a result, run-time errors can occur. For more details, see Automatic dimension restriction (MATLAB Coder).

For more information on code generation, see Introduction to Code Generation and General Code Generation Workflow.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

This function fully supports GPU arrays. For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2024a: Specify gpuArray inputs

harmmean fully supports gpuArray inputs.