HMEAN

Overview

The HMEAN function calculates the harmonic mean of a dataset, which is a type of average particularly useful when dealing with rates, ratios, and other quantities that are defined relative to a unit of measure. Unlike the arithmetic mean, the harmonic mean gives greater weight to smaller values, making it ideal for averaging speeds, rates of return, or price-to-earnings ratios.

The harmonic mean is defined as the reciprocal of the arithmetic mean of the reciprocals of the observations. For a set of n positive values a_1, a_2, \ldots, a_n, it is computed as:

H = \frac{n}{\sum_{i=1}^{n} \frac{1}{a_i}}

This implementation uses the scipy.stats.hmean function from the SciPy library. For more details on the underlying algorithm, see the SciPy GitHub repository.

A key requirement of the harmonic mean is that all input values must be strictly positive. This function automatically flattens two-dimensional input and filters out non-numeric values before calculation. If no valid positive numbers remain after filtering, an error message is returned.

Common applications of the harmonic mean include:

• Averaging rates: When calculating average speed over a fixed distance traveled at different speeds, the harmonic mean provides the correct result.
• Finance: Computing the average P/E ratio of a portfolio or the average cost in dollar-cost averaging strategies.
• Physics and engineering: Calculating equivalent resistance for resistors in parallel circuits.

For additional mathematical background, see the Wikipedia article on harmonic mean.

This example function is provided as-is without any representation of accuracy.

Excel Usage

=HMEAN(data)

• data (list[list], required): 2D array of positive numeric values. Non-numeric values are ignored.

Returns (float): Harmonic mean of the input data, or error message (str) if input is invalid.

Examples

Example 1: Harmonic mean of 2x2 matrix

Inputs:

data
1	2
3	4

Excel formula:

=HMEAN({1,2;3,4})

Expected output:

1.92

Example 2: Single column with multiple rows

Inputs:

data
2
4
8
16

Excel formula:

=HMEAN({2;4;8;16})

Expected output:

4.2667

Example 3: Non-numeric values are ignored

Inputs:

data
5	6
text	7

Excel formula:

=HMEAN({5,6;"text",7})

Expected output:

5.8879

Example 4: Harmonic mean of 3x2 matrix

Inputs:

data
10	20	30
40	50	60

Excel formula:

=HMEAN({10,20,30;40,50,60})

Expected output:

24.4898

Python Code

from scipy.stats import hmean as scipy_hmean

def hmean(data):
    """
    Calculates the harmonic mean of the input data, flattening the input and ignoring non-numeric values.

    See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.hmean.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        data (list[list]): 2D array of positive numeric values. Non-numeric values are ignored.

    Returns:
        float: Harmonic mean of the input data, or error message (str) if input is invalid.
    """
    def to2d(x):
        return [[x]] if not isinstance(x, list) else x

    data = to2d(data)

    if not isinstance(data, list) or not all(isinstance(row, list) for row in data):
        return "Error: Invalid input: data must be a 2D list."

    flat = []
    for row in data:
        for item in row:
            try:
                val = float(item)
                if val > 0:
                    flat.append(val)
            except (TypeError, ValueError):
                continue

    if not flat:
        return "Error: Input must contain at least one positive number."

    result = scipy_hmean(flat)
    return float(result)

Online Calculator