harmmean

Harmonic mean

collapse all in page

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.

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

example

Examples

collapse all

Compare Harmonic and Arithmetic Mean

Open Live Script

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

Open Live Script

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

Open Live Script

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`

Open Live Script

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 = \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.

Extended Capabilities

expand all

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 Incompatibility with MATLAB for Default Dimension Selection (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

expand all

R2024a: Specify `gpuArray` inputs

harmmean fully supports gpuArray inputs.

harmmean

Syntax

Description

Examples

Compare Harmonic and Arithmetic Mean

Harmonic Mean of All Values

Harmonic Mean Along Specified Dimensions

Harmonic Mean Excluding NaN

More About

Harmonic Mean

Tips

Extended Capabilities

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

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

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

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

Version History

R2024a: Specify gpuArray inputs

See Also

Harmonic Mean Excluding `NaN`

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

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

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

R2024a: Specify `gpuArray` inputs