abydos.stats._mean.aghmean() - Code Metrics - chrislit/abydos - Measure and Improve Code Quality continuously with Scrutinizer

abydos.stats._mean.aghmean() B
last analyzed 2020-12-31 20:10 UTC

↳ Parent: abydos.stats._mean

Complexity

Conditions

Size

Total Lines	45
Code Lines	13

Duplication

Lines	0
Ratio	0 %

Code Coverage

Tests	12
CRAP Score	6

Importance

Changes

Metric	Value
eloc	13
dl	0
loc	45
ccs	12
cts	12
cp	1
rs	8.6666
c	0
b	0
f	0
cc	6
nop	2
crap	6

# Copyright 2014-2020 by Christopher C. Little.
# This file is part of Abydos.
#
# Abydos is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Abydos is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Abydos. If not, see <http://www.gnu.org/licenses/>.

r"""abydos.stats._mean.

The stats._mean module defines functions for calculating means and other
measures of central tendencies.
"""

import math
from collections import Counter
from typing import Callable, Sequence

from ..util._prod import _prod

__all__ = [
    'amean',
    'gmean',
    'hmean',
    'agmean',
    'ghmean',
    'aghmean',
    'cmean',
    'imean',
    'lmean',
    'qmean',
    'heronian_mean',
    'hoelder_mean',
    'lehmer_mean',
    'seiffert_mean',
    'median',
    'midrange',
    'mode',
    'std',
    'var',
]


def amean(nums: Sequence[float]) -> float:
    r"""Return arithmetic mean.

    The arithmetic mean is defined as

        .. math::

            \frac{\sum{nums}}{|nums|}

    Cf. https://en.wikipedia.org/wiki/Arithmetic_mean

    Parameters
    ----------
    nums : list
        A series of numbers

    Returns
    -------
    float
        The arithmetric mean of nums

    Examples
    --------
    >>> amean([1, 2, 3, 4])
    2.5
    >>> amean([1, 2])
    1.5
    >>> amean([0, 5, 1000])
    335.0

    .. versionadded:: 0.1.0

    """
    return sum(nums) / len(nums)


def gmean(nums: Sequence[float]) -> float:
    r"""Return geometric mean.

    The geometric mean is defined as

        .. math::

            \sqrt[|nums|]{\prod\limits_{i} nums_{i}}

    Cf. https://en.wikipedia.org/wiki/Geometric_mean

    Parameters
    ----------
    nums : list
        A series of numbers

    Returns
    -------
    float
        The geometric mean of nums

    Examples
    --------
    >>> gmean([1, 2, 3, 4])
    2.213363839400643
    >>> gmean([1, 2])
    1.4142135623730951
    >>> gmean([0, 5, 1000])
    0.0

    .. versionadded:: 0.1.0

    """
    return _prod(nums) ** (1 / len(nums))


def hmean(nums: Sequence[float]) -> float:
    r"""Return harmonic mean.

    The harmonic mean is defined as

        .. math::

            \frac{|nums|}{\sum\limits_{i}\frac{1}{nums_i}}

    Following the behavior of Wolfram|Alpha:
    - If one of the values in nums is 0, return 0.
    - If more than one value in nums is 0, return NaN.

    Cf. https://en.wikipedia.org/wiki/Harmonic_mean

    Parameters
    ----------
    nums : list
        A series of numbers

    Returns
    -------
    float
        The harmonic mean of nums

    Raises
    ------
    ValueError
        hmean requires at least one value

    Examples
    --------
    >>> hmean([1, 2, 3, 4])
    1.9200000000000004
    >>> hmean([1, 2])
    1.3333333333333333
    >>> hmean([0, 5, 1000])
    0

    .. versionadded:: 0.1.0

    """
    if len(nums) < 1:
        raise ValueError('hmean requires at least one value')
    elif len(nums) == 1:
        return nums[0]
    else:
        for i in range(1, len(nums)):
            if nums[0] != nums[i]:
                break
        else:
            return nums[0]

    if 0 in nums:
        if nums.count(0) > 1:
            return float('nan')
        return 0
    return len(nums) / sum(1.0 / float(i) for i in nums)  # type: ignore


def qmean(nums: Sequence[float]) -> float:
    r"""Return quadratic mean.

    The quadratic mean is defined as

        .. math::

            \sqrt{\sum\limits_{i} \frac{num_i^2}{|nums|}}

    Cf. https://en.wikipedia.org/wiki/Quadratic_mean

    Parameters
    ----------
    nums : list
        A series of numbers

    Returns
    -------
    float
        The quadratic mean of nums

    Examples
    --------
    >>> qmean([1, 2, 3, 4])
    2.7386127875258306
    >>> qmean([1, 2])
    1.5811388300841898
    >>> qmean([0, 5, 1000])
    577.3574860228857

    .. versionadded:: 0.1.0

    """
    return (sum(i ** 2 for i in nums) / len(nums)) ** 0.5


def cmean(nums: Sequence[float]) -> float:
    r"""Return contraharmonic mean.

    The contraharmonic mean is

        .. math::

            \frac{\sum\limits_i x_i^2}{\sum\limits_i x_i}

    Cf. https://en.wikipedia.org/wiki/Contraharmonic_mean

    Parameters
    ----------
    nums : list
        A series of numbers

    Returns
    -------
    float
        The contraharmonic mean of nums

    Examples
    --------
    >>> cmean([1, 2, 3, 4])
    3.0
    >>> cmean([1, 2])
    1.6666666666666667
    >>> cmean([0, 5, 1000])
    995.0497512437811

    .. versionadded:: 0.1.0

    """
    return sum(x ** 2 for x in nums) / sum(nums)


def lmean(nums: Sequence[float]) -> float:
    r"""Return logarithmic mean.

    The logarithmic mean of an arbitrarily long series is defined by
    http://www.survo.fi/papers/logmean.pdf
    as


        .. math::

            L(x_1, x_2, ..., x_n) =
            (n-1)! \sum\limits_{i=1}^n \frac{x_i}
            {\prod\limits_{\substack{j = 1\\j \ne i}}^n
            ln \frac{x_i}{x_j}}

    Cf. https://en.wikipedia.org/wiki/Logarithmic_mean

    Parameters
    ----------
    nums : list
        A series of numbers

    Returns
    -------
    float
        The logarithmic mean of nums

    Raises
    ------
    ValueError
        No two values in the nums list may be equal

    Examples
    --------
    >>> lmean([1, 2, 3, 4])
    2.2724242417489258
    >>> lmean([1, 2])
    1.4426950408889634

    .. versionadded:: 0.1.0

    """
    if len(nums) == 2:
        if nums[0] == nums[1]:
            return float(nums[0])
        if 0 in nums:
            return 0.0
        return (nums[1] - nums[0]) / (math.log(nums[1] / nums[0]))

    else:
        if len(nums) != len(set(nums)):
            raise ValueError('No two values in the nums list may be equal')
        rolling_sum = 0.0
        for i in range(len(nums)):
            rolling_prod = 1.0
            for j in range(len(nums)):
                if i != j:
                    rolling_prod *= math.log(nums[i] / nums[j])
            rolling_sum += nums[i] / rolling_prod
        return math.factorial(len(nums) - 1) * rolling_sum


def imean(nums: Sequence[float]) -> float:
    r"""Return identric (exponential) mean.

    The identric mean of two numbers x and y is:
    x if x = y
    otherwise

        .. math::

            \frac{1}{e} \sqrt[x-y]{\frac{x^x}{y^y}}

    Cf. https://en.wikipedia.org/wiki/Identric_mean

    Parameters
    ----------
    nums : list
        A series of numbers

    Returns
    -------
    float
        The identric mean of nums

    Raises
    ------
    ValueError
        imean supports no more than two values

    Examples
    --------
    >>> imean([1, 2])
    1.4715177646857693
    >>> imean([1, 0])
    nan
    >>> imean([2, 4])
    2.9430355293715387

    .. versionadded:: 0.1.0

    """
    if len(nums) == 1:
        return nums[0]
    if len(nums) > 2:
        raise ValueError('imean supports no more than two values')
    if nums[0] <= 0 or nums[1] <= 0:
        return float('NaN')
    elif nums[0] == nums[1]:
        return nums[0]
    nums = sorted(nums, reverse=True)
    return (1 / math.e) * (nums[0] ** nums[0] / nums[1] ** nums[1]) ** (
        1 / (nums[0] - nums[1])
    )


def seiffert_mean(nums: Sequence[float]) -> float:
    r"""Return Seiffert's mean.

    Seiffert's mean of two numbers x and y is

        .. math::

            \frac{x - y}{4 \cdot arctan \sqrt{\frac{x}{y}} - \pi}

    It is defined in :cite:`Seiffert:1993`.

    Parameters
    ----------
    nums : list
        A series of numbers

    Returns
    -------
    float
        Sieffert's mean of nums

    Raises
    ------
    ValueError
        seiffert_mean supports no more than two values

    Examples
    --------
    >>> seiffert_mean([1, 2])
    1.4712939827611637
    >>> seiffert_mean([1, 0])
    0.3183098861837907
    >>> seiffert_mean([2, 4])
    2.9425879655223275
    >>> seiffert_mean([2, 1000])
    336.84053300118825

    .. versionadded:: 0.1.0

    """
    if len(nums) == 1:
        return nums[0]
    if len(nums) > 2:
        raise ValueError('seiffert_mean supports no more than two values')
    if nums[0] + nums[1] == 0 or nums[0] - nums[1] == 0:
        return float('NaN')
    return (nums[0] - nums[1]) / (
        2 * math.asin((nums[0] - nums[1]) / (nums[0] + nums[1]))
    )


def lehmer_mean(nums: Sequence[float], exp: float = 2.0) -> float:
    r"""Return Lehmer mean.

    The Lehmer mean is

        .. math::

            \frac{\sum\limits_i{x_i^p}}{\sum\limits_i{x_i^(p-1)}}

    Cf. https://en.wikipedia.org/wiki/Lehmer_mean

    Parameters
    ----------
    nums : list
        A series of numbers
    exp : numeric
        The exponent of the Lehmer mean

    Returns
    -------
    float
        The Lehmer mean of nums for the given exponent

    Examples
    --------
    >>> lehmer_mean([1, 2, 3, 4])
    3.0
    >>> lehmer_mean([1, 2])
    1.6666666666666667
    >>> lehmer_mean([0, 5, 1000])
    995.0497512437811

    .. versionadded:: 0.1.0

    """
    return sum(x ** exp for x in nums) / sum(x ** (exp - 1) for x in nums)


def heronian_mean(nums: Sequence[float]) -> float:
    r"""Return Heronian mean.

    The Heronian mean is:

        .. math::

            \frac{\sum\limits_{i, j}\sqrt{{x_i \cdot x_j}}}
            {|nums| \cdot \frac{|nums| + 1}{2}}

    for :math:`j \ge i`

    Cf. https://en.wikipedia.org/wiki/Heronian_mean

    Parameters
    ----------
    nums : list
        A series of numbers

    Returns
    -------
    float
        The Heronian mean of nums

    Examples
    --------
    >>> heronian_mean([1, 2, 3, 4])
    2.3888282852609093
    >>> heronian_mean([1, 2])
    1.4714045207910316
    >>> heronian_mean([0, 5, 1000])
    179.28511301977582

    .. versionadded:: 0.1.0

    """
    mag = len(nums)
    rolling_sum = 0.0
    for i in range(mag):
        for j in range(i, mag):
            if nums[i] == nums[j]:
                rolling_sum += nums[i]
            else:
                rolling_sum += (nums[i] * nums[j]) ** 0.5
    return rolling_sum * 2 / (mag * (mag + 1))


def hoelder_mean(nums: Sequence[float], exp: float = 2.0) -> float:
    r"""Return Hölder (power/generalized) mean.

    The Hölder mean is defined as:

        .. math::

            \sqrt[p]{\frac{1}{|nums|} \cdot \sum\limits_i{x_i^p}}

    for :math:`p \ne 0`, and the geometric mean for :math:`p = 0`

    Cf. https://en.wikipedia.org/wiki/Generalized_mean

    Parameters
    ----------
    nums : list
        A series of numbers
    exp : numeric
        The exponent of the Hölder mean

    Returns
    -------
    float
        The Hölder mean of nums for the given exponent

    Examples
    --------
    >>> hoelder_mean([1, 2, 3, 4])
    2.7386127875258306
    >>> hoelder_mean([1, 2])
    1.5811388300841898
    >>> hoelder_mean([0, 5, 1000])
    577.3574860228857

    .. versionadded:: 0.1.0

    """
    if exp == 0:
        return gmean(nums)
    return ((1 / len(nums)) * sum(i ** exp for i in nums)) ** (1 / exp)


def agmean(nums: Sequence[float], prec: int = 12) -> float:
    """Return arithmetic-geometric mean.

    Iterates between arithmetic & geometric means until they converge to
    a single value (rounded to 10 digits).

    Cf. https://en.wikipedia.org/wiki/Arithmetic-geometric_mean

    Parameters
    ----------
    nums : list
        A series of numbers
    prec : int
        Digits of precision when testing convergeance

    Returns
    -------
    float
        The arithmetic-geometric mean of nums

    Examples
    --------
    >>> agmean([1, 2, 3, 4])
    2.3545004777751077
    >>> agmean([1, 2])
    1.4567910310469068
    >>> agmean([0, 5, 1000])
    2.9753977059954195e-13

    .. versionadded:: 0.1.0

    """
    m_a = amean(nums)
    m_g = gmean(nums)
    if math.isnan(m_a) or math.isnan(m_g):
        return float('nan')
    while round(m_a, prec) != round(m_g, prec):
        m_a, m_g = (m_a + m_g) / 2, (m_a * m_g) ** (1 / 2)
    return m_a


def ghmean(nums: Sequence[float], prec: int = 12) -> float:
    """Return geometric-harmonic mean.

    Iterates between geometric & harmonic means until they converge to
    a single value (rounded to 10 digits).

    Cf. https://en.wikipedia.org/wiki/Geometric-harmonic_mean

    Parameters
    ----------
    nums : list
        A series of numbers
    prec : int
        Digits of precision when testing convergeance

    Returns
    -------
    float
        The geometric-harmonic mean of nums

    Examples
    --------
    >>> ghmean([1, 2, 3, 4])
    2.058868154613003
    >>> ghmean([1, 2])
    1.3728805006183502
    >>> ghmean([0, 5, 1000])
    0.0

    >>> ghmean([0, 0])
    0.0
    >>> ghmean([0, 0, 5])
    nan

    .. versionadded:: 0.1.0

    """
    m_g = gmean(nums)
    m_h = hmean(nums)
    if math.isnan(m_g) or math.isnan(m_h):
        return float('nan')
    while round(m_h, prec) != round(m_g, prec):
        m_g, m_h = (m_g * m_h) ** (1 / 2), (2 * m_g * m_h) / (m_g + m_h)
    return m_g


def aghmean(nums: Sequence[float], prec: int = 12) -> float:
    """Return arithmetic-geometric-harmonic mean.

    Iterates over arithmetic, geometric, & harmonic means until they
    converge to a single value (rounded to 10 digits), following the
    method described in :cite:`Raissouli:2009`.

    Parameters
    ----------
    nums : list
        A series of numbers
    prec : int
        Digits of precision when testing convergeance

    Returns
    -------
    float
        The arithmetic-geometric-harmonic mean of nums

    Examples
    --------
    >>> aghmean([1, 2, 3, 4])
    2.198327159900212
    >>> aghmean([1, 2])
    1.4142135623731884
    >>> aghmean([0, 5, 1000])
    335.0

    .. versionadded:: 0.1.0

    """
    m_a = amean(nums)
    m_g = gmean(nums)
    m_h = hmean(nums)
    if math.isnan(m_a) or math.isnan(m_g) or math.isnan(m_h):
        return float('nan')
    while round(m_a, prec) != round(m_g, prec) and round(m_g, prec) != round(
        m_h, prec
    ):
        m_a, m_g, m_h = (
            (m_a + m_g + m_h) / 3,
            (m_a * m_g * m_h) ** (1 / 3),
            3 / (1 / m_a + 1 / m_g + 1 / m_h),
        )
    return m_a


def midrange(nums: Sequence[float]) -> float:
    """Return midrange.

    The midrange is the arithmetic mean of the maximum & minimum of a series.

    Cf. https://en.wikipedia.org/wiki/Midrange

    Parameters
    ----------
    nums : list
        A series of numbers

    Returns
    -------
    float
        The midrange of nums

    Examples
    --------
    >>> midrange([1, 2, 3])
    2.0
    >>> midrange([1, 2, 2, 3])
    2.0
    >>> midrange([1, 2, 1000, 3])
    500.5

    .. versionadded:: 0.1.0

    """
    return 0.5 * (max(nums) + min(nums))


def median(nums: Sequence[float]) -> float:
    """Return median.

    With numbers sorted by value, the median is the middle value (if there is
    an odd number of values) or the arithmetic mean of the two middle values
    (if there is an even number of values).

    Cf. https://en.wikipedia.org/wiki/Median

    Parameters
    ----------
    nums : list
        A series of numbers

    Returns
    -------
    int or float
        The median of nums

    Examples
    --------
    >>> median([1, 2, 3])
    2
    >>> median([1, 2, 3, 4])
    2.5
    >>> median([1, 2, 2, 4])
    2

    .. versionadded:: 0.1.0

    """
    nums = sorted(nums)
    mag = len(nums)
    if mag % 2:
        mag = int((mag - 1) / 2)
        return nums[mag]
    mag = int(mag / 2)
    med = (nums[mag - 1] + nums[mag]) / 2
    return med if not med.is_integer() else int(med)


def mode(nums: Sequence[float]) -> float:
    """Return the mode.

    The mode of a series is the most common element of that series

    Cf. https://en.wikipedia.org/wiki/Mode_(statistics)

    Parameters
    ----------
    nums : list
        A series of numbers

    Returns
    -------
    int or float
        The mode of nums

    Example
    -------
    >>> mode([1, 2, 2, 3])
    2

    .. versionadded:: 0.1.0

    """
    return Counter(nums).most_common(1)[0][0]


def var(
    nums: Sequence[float],
    mean_func: Callable[[Sequence[float]], float] = amean,
    ddof: int = 0,
) -> float:
    r"""Calculate the variance.

    The variance (:math:`\sigma^2`) of a series of numbers (:math:`x_i`) with
    mean :math:`\mu` and population :math:`N` is:

        .. math::

            \sigma^2 = \frac{1}{N}\sum_{i=1}^{N}(x_i-\mu)^2

    Cf. https://en.wikipedia.org/wiki/Variance

    Parameters
    ----------
    nums : list
        A series of numbers
    mean_func : function
        A mean function (amean by default)
    ddof : int
        The degrees of freedom (0 by default)

    Returns
    -------
    float
        The variance of the values in the series

    Examples
    --------
    >>> var([1, 1, 1, 1])
    0.0
    >>> var([1, 2, 3, 4])
    1.25
    >>> round(var([1, 2, 3, 4], ddof=1), 12)
    1.666666666667

    .. versionadded:: 0.3.0

    """
    x_bar = mean_func(nums)
    return sum((x - x_bar) ** 2 for x in nums) / (len(nums) - ddof)


def std(
    nums: Sequence[float],
    mean_func: Callable[[Sequence[float]], float] = amean,
    ddof: int = 0,
) -> float:
    """Return the standard deviation.

    The standard deviation of a series of values is the square root of the
    variance.

    Cf. https://en.wikipedia.org/wiki/Standard_deviation

    Parameters
    ----------
    nums : list
        A series of numbers
    mean_func : function
        A mean function (amean by default)
    ddof : int
        The degrees of freedom (0 by default)

    Returns
    -------
    float
        The standard deviation of the values in the series

    Examples
    --------
    >>> std([1, 1, 1, 1])
    0.0
    >>> round(std([1, 2, 3, 4]), 12)
    1.11803398875
    >>> round(std([1, 2, 3, 4], ddof=1), 12)
    1.290994448736

    .. versionadded:: 0.3.0

    """
    return var(nums, mean_func, ddof) ** 0.5


if __name__ == '__main__':
    import doctest

    doctest.testmod()


1		# Copyright 2014-2020 by Christopher C. Little.
2		# This file is part of Abydos.
3		#
4		# Abydos is free software: you can redistribute it and/or modify
5		# it under the terms of the GNU General Public License as published by
6		# the Free Software Foundation, either version 3 of the License, or
7		# (at your option) any later version.
8		#
9		# Abydos is distributed in the hope that it will be useful,
10		# but WITHOUT ANY WARRANTY; without even the implied warranty of
11		# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12		# GNU General Public License for more details.
13		#
14		# You should have received a copy of the GNU General Public License
15		# along with Abydos. If not, see <http://www.gnu.org/licenses/>.
16
17		r"""abydos.stats._mean.
18
19	1	The stats._mean module defines functions for calculating means and other
20		measures of central tendencies.
21		"""
22
23		import math
24		from collections import Counter
25	1	from typing import Callable, Sequence
26
27		from ..util._prod import _prod
28
29		__all__ = [
30		'amean',
31		'gmean',
32	1	'hmean',
33	1	'agmean',
34		'ghmean',
35	1	'aghmean',
36		'cmean',
37	1	'imean',
38		'lmean',
39	1	'qmean',
40		'heronian_mean',
41		'hoelder_mean',
42		'lehmer_mean',
43		'seiffert_mean',
44		'median',
45		'midrange',
46		'mode',
47		'std',
48		'var',
49		]
50
51
52		def amean(nums: Sequence[float]) -> float:
53		r"""Return arithmetic mean.
54
55		The arithmetic mean is defined as
56
57		.. math::
58
59		\frac{\sum{nums}}{\|nums\|}
60
61		Cf. https://en.wikipedia.org/wiki/Arithmetic_mean
62	1
63		Parameters
64		----------
65		nums : list
66		A series of numbers
67
68		Returns
69		-------
70		float
71		The arithmetric mean of nums
72
73		Examples
74		--------
75		>>> amean([1, 2, 3, 4])
76		2.5
77		>>> amean([1, 2])
78		1.5
79		>>> amean([0, 5, 1000])
80		335.0
81
82		.. versionadded:: 0.1.0
83
84		"""
85		return sum(nums) / len(nums)
86
87
88		def gmean(nums: Sequence[float]) -> float:
89		r"""Return geometric mean.
90
91		The geometric mean is defined as
92
93		.. math::
94
95	1	\sqrt[\|nums\|]{\prod\limits_{i} nums_{i}}
96
97		Cf. https://en.wikipedia.org/wiki/Geometric_mean
98	1
99		Parameters
100		----------
101		nums : list
102		A series of numbers
103
104		Returns
105		-------
106		float
107		The geometric mean of nums
108
109		Examples
110		--------
111		>>> gmean([1, 2, 3, 4])
112		2.213363839400643
113		>>> gmean([1, 2])
114		1.4142135623730951
115		>>> gmean([0, 5, 1000])
116		0.0
117
118		.. versionadded:: 0.1.0
119
120		"""
121		return _prod(nums) ** (1 / len(nums))
122
123
124		def hmean(nums: Sequence[float]) -> float:
125		r"""Return harmonic mean.
126
127		The harmonic mean is defined as
128
129		.. math::
130
131	1	\frac{\|nums\|}{\sum\limits_{i}\frac{1}{nums_i}}
132
133		Following the behavior of Wolfram\|Alpha:
134	1	- If one of the values in nums is 0, return 0.
135		- If more than one value in nums is 0, return NaN.
136
137		Cf. https://en.wikipedia.org/wiki/Harmonic_mean
138
139		Parameters
140		----------
141		nums : list
142		A series of numbers
143
144		Returns
145		-------
146		float
147		The harmonic mean of nums
148
149		Raises
150		------
151		ValueError
152		hmean requires at least one value
153
154		Examples
155		--------
156		>>> hmean([1, 2, 3, 4])
157		1.9200000000000004
158		>>> hmean([1, 2])
159		1.3333333333333333
160		>>> hmean([0, 5, 1000])
161		0
162
163		.. versionadded:: 0.1.0
164
165		"""
166		if len(nums) < 1:
167		raise ValueError('hmean requires at least one value')
168		elif len(nums) == 1:
169		return nums[0]
170		else:
171		for i in range(1, len(nums)):
172		if nums[0] != nums[i]:
173		break
174		else:
175		return nums[0]
176	1
177	1	if 0 in nums:
178	1	if nums.count(0) > 1:
179	1	return float('nan')
180		return 0
181	1	return len(nums) / sum(1.0 / float(i) for i in nums) # type: ignore
182	1
183	1
184		def qmean(nums: Sequence[float]) -> float:
185	1	r"""Return quadratic mean.
186
187	1	The quadratic mean is defined as
188	1
189	1	.. math::
190	1
191	1	\sqrt{\sum\limits_{i} \frac{num_i^2}{\|nums\|}}
192
193		Cf. https://en.wikipedia.org/wiki/Quadratic_mean
194	1
195		Parameters
196		----------
197		nums : list
198		A series of numbers
199
200		Returns
201		-------
202		float
203		The quadratic mean of nums
204
205		Examples
206		--------
207		>>> qmean([1, 2, 3, 4])
208		2.7386127875258306
209		>>> qmean([1, 2])
210		1.5811388300841898
211		>>> qmean([0, 5, 1000])
212		577.3574860228857
213
214		.. versionadded:: 0.1.0
215
216		"""
217		return (sum(i 2 for i in nums) / len(nums)) 0.5
218
219
220		def cmean(nums: Sequence[float]) -> float:
221		r"""Return contraharmonic mean.
222
223		The contraharmonic mean is
224
225		.. math::
226
227	1	\frac{\sum\limits_i x_i^2}{\sum\limits_i x_i}
228
229		Cf. https://en.wikipedia.org/wiki/Contraharmonic_mean
230	1
231		Parameters
232		----------
233		nums : list
234		A series of numbers
235
236		Returns
237		-------
238		float
239		The contraharmonic mean of nums
240
241		Examples
242		--------
243		>>> cmean([1, 2, 3, 4])
244		3.0
245		>>> cmean([1, 2])
246		1.6666666666666667
247		>>> cmean([0, 5, 1000])
248		995.0497512437811
249
250		.. versionadded:: 0.1.0
251
252		"""
253		return sum(x ** 2 for x in nums) / sum(nums)
254
255
256		def lmean(nums: Sequence[float]) -> float:
257		r"""Return logarithmic mean.
258
259		The logarithmic mean of an arbitrarily long series is defined by
260		http://www.survo.fi/papers/logmean.pdf
261		as
262
263	1
264		.. math::
265
266	1	L(x_1, x_2, ..., x_n) =
267		(n-1)! \sum\limits_{i=1}^n \frac{x_i}
268		{\prod\limits_{\substack{j = 1\\j \ne i}}^n
269		ln \frac{x_i}{x_j}}
270
271		Cf. https://en.wikipedia.org/wiki/Logarithmic_mean
272
273		Parameters
274		----------
275		nums : list
276		A series of numbers
277
278		Returns
279		-------
280		float
281		The logarithmic mean of nums
282
283		Raises
284		------
285		ValueError
286		No two values in the nums list may be equal
287
288		Examples
289		--------
290		>>> lmean([1, 2, 3, 4])
291		2.2724242417489258
292		>>> lmean([1, 2])
293		1.4426950408889634
294
295		.. versionadded:: 0.1.0
296
297		"""
298		if len(nums) == 2:
299		if nums[0] == nums[1]:
300		return float(nums[0])
301		if 0 in nums:
302		return 0.0
303		return (nums[1] - nums[0]) / (math.log(nums[1] / nums[0]))
304
305		else:
306		if len(nums) != len(set(nums)):
307		raise ValueError('No two values in the nums list may be equal')
308	1	rolling_sum = 0.0
309	1	for i in range(len(nums)):
310	1	rolling_prod = 1.0
311	1	for j in range(len(nums)):
312	1	if i != j:
313	1	rolling_prod *= math.log(nums[i] / nums[j])
314		rolling_sum += nums[i] / rolling_prod
315		return math.factorial(len(nums) - 1) * rolling_sum
316	1
317	1
318	1	def imean(nums: Sequence[float]) -> float:
319	1	r"""Return identric (exponential) mean.
320	1
321	1	The identric mean of two numbers x and y is:
322	1	x if x = y
323	1	otherwise
324	1
325	1	.. math::
326
327		\frac{1}{e} \sqrt[x-y]{\frac{x^x}{y^y}}
328	1
329		Cf. https://en.wikipedia.org/wiki/Identric_mean
330
331		Parameters
332		----------
333		nums : list
334		A series of numbers
335
336		Returns
337		-------
338		float
339		The identric mean of nums
340
341		Raises
342		------
343		ValueError
344		imean supports no more than two values
345
346		Examples
347		--------
348		>>> imean([1, 2])
349		1.4715177646857693
350		>>> imean([1, 0])
351		nan
352		>>> imean([2, 4])
353		2.9430355293715387
354
355		.. versionadded:: 0.1.0
356
357		"""
358		if len(nums) == 1:
359		return nums[0]
360		if len(nums) > 2:
361		raise ValueError('imean supports no more than two values')
362		if nums[0] <= 0 or nums[1] <= 0:
363		return float('NaN')
364		elif nums[0] == nums[1]:
365		return nums[0]
366		nums = sorted(nums, reverse=True)
367		return (1 / math.e) * (nums[0] nums[0] / nums[1] nums[1]) ** (
368	1	1 / (nums[0] - nums[1])
369	1	)
370	1
371	1
372	1	def seiffert_mean(nums: Sequence[float]) -> float:
373	1	r"""Return Seiffert's mean.
374	1
375	1	Seiffert's mean of two numbers x and y is
376	1
377	1	.. math::
378
379		\frac{x - y}{4 \cdot arctan \sqrt{\frac{x}{y}} - \pi}
380
381		It is defined in :cite:`Seiffert:1993`.
382	1
383		Parameters
384		----------
385		nums : list
386		A series of numbers
387
388		Returns
389		-------
390		float
391		Sieffert's mean of nums
392
393		Raises
394		------
395		ValueError
396		seiffert_mean supports no more than two values
397
398		Examples
399		--------
400		>>> seiffert_mean([1, 2])
401		1.4712939827611637
402		>>> seiffert_mean([1, 0])
403		0.3183098861837907
404		>>> seiffert_mean([2, 4])
405		2.9425879655223275
406		>>> seiffert_mean([2, 1000])
407		336.84053300118825
408
409		.. versionadded:: 0.1.0
410
411		"""
412		if len(nums) == 1:
413		return nums[0]
414		if len(nums) > 2:
415		raise ValueError('seiffert_mean supports no more than two values')
416		if nums[0] + nums[1] == 0 or nums[0] - nums[1] == 0:
417		return float('NaN')
418		return (nums[0] - nums[1]) / (
419		2 * math.asin((nums[0] - nums[1]) / (nums[0] + nums[1]))
420		)
421
422	1
423	1	def lehmer_mean(nums: Sequence[float], exp: float = 2.0) -> float:
424	1	r"""Return Lehmer mean.
425	1
426	1	The Lehmer mean is
427	1
428	1	.. math::
429
430		\frac{\sum\limits_i{x_i^p}}{\sum\limits_i{x_i^(p-1)}}
431
432		Cf. https://en.wikipedia.org/wiki/Lehmer_mean
433	1
434		Parameters
435		----------
436		nums : list
437		A series of numbers
438		exp : numeric
439		The exponent of the Lehmer mean
440
441		Returns
442		-------
443		float
444		The Lehmer mean of nums for the given exponent
445
446		Examples
447		--------
448		>>> lehmer_mean([1, 2, 3, 4])
449		3.0
450		>>> lehmer_mean([1, 2])
451		1.6666666666666667
452		>>> lehmer_mean([0, 5, 1000])
453		995.0497512437811
454
455		.. versionadded:: 0.1.0
456
457		"""
458		return sum(x exp for x in nums) / sum(x (exp - 1) for x in nums)
459
460
461		def heronian_mean(nums: Sequence[float]) -> float:
462		r"""Return Heronian mean.
463
464		The Heronian mean is:
465
466		.. math::
467
468	1	\frac{\sum\limits_{i, j}\sqrt{{x_i \cdot x_j}}}
469		{\|nums\| \cdot \frac{\|nums\| + 1}{2}}
470
471	1	for :math:`j \ge i`
472
473		Cf. https://en.wikipedia.org/wiki/Heronian_mean
474
475		Parameters
476		----------
477		nums : list
478		A series of numbers
479
480		Returns
481		-------
482		float
483		The Heronian mean of nums
484
485		Examples
486		--------
487		>>> heronian_mean([1, 2, 3, 4])
488		2.3888282852609093
489		>>> heronian_mean([1, 2])
490		1.4714045207910316
491		>>> heronian_mean([0, 5, 1000])
492		179.28511301977582
493
494		.. versionadded:: 0.1.0
495
496		"""
497		mag = len(nums)
498		rolling_sum = 0.0
499		for i in range(mag):
500		for j in range(i, mag):
501		if nums[i] == nums[j]:
502		rolling_sum += nums[i]
503		else:
504		rolling_sum += (nums[i] * nums[j]) ** 0.5
505		return rolling_sum * 2 / (mag * (mag + 1))
506
507	1
508	1	def hoelder_mean(nums: Sequence[float], exp: float = 2.0) -> float:
509	1	r"""Return Hölder (power/generalized) mean.
510	1
511	1	The Hölder mean is defined as:
512	1
513		.. math::
514	1
515	1	\sqrt[p]{\frac{1}{\|nums\|} \cdot \sum\limits_i{x_i^p}}
516
517		for :math:`p \ne 0`, and the geometric mean for :math:`p = 0`
518	1
519		Cf. https://en.wikipedia.org/wiki/Generalized_mean
520
521		Parameters
522		----------
523		nums : list
524		A series of numbers
525		exp : numeric
526		The exponent of the Hölder mean
527
528		Returns
529		-------
530		float
531		The Hölder mean of nums for the given exponent
532
533		Examples
534		--------
535		>>> hoelder_mean([1, 2, 3, 4])
536		2.7386127875258306
537		>>> hoelder_mean([1, 2])
538		1.5811388300841898
539		>>> hoelder_mean([0, 5, 1000])
540		577.3574860228857
541
542		.. versionadded:: 0.1.0
543
544		"""
545		if exp == 0:
546		return gmean(nums)
547		return ((1 / len(nums)) * sum(i exp for i in nums)) (1 / exp)
548
549
550		def agmean(nums: Sequence[float], prec: int = 12) -> float:
551		"""Return arithmetic-geometric mean.
552
553		Iterates between arithmetic & geometric means until they converge to
554		a single value (rounded to 10 digits).
555	1
556	1	Cf. https://en.wikipedia.org/wiki/Arithmetic-geometric_mean
557	1
558		Parameters
559		----------
560	1	nums : list
561		A series of numbers
562		prec : int
563		Digits of precision when testing convergeance
564
565		Returns
566		-------
567		float
568		The arithmetic-geometric mean of nums
569
570		Examples
571		--------
572		>>> agmean([1, 2, 3, 4])
573		2.3545004777751077
574		>>> agmean([1, 2])
575		1.4567910310469068
576		>>> agmean([0, 5, 1000])
577		2.9753977059954195e-13
578
579		.. versionadded:: 0.1.0
580
581		"""
582		m_a = amean(nums)
583		m_g = gmean(nums)
584		if math.isnan(m_a) or math.isnan(m_g):
585		return float('nan')
586		while round(m_a, prec) != round(m_g, prec):
587		m_a, m_g = (m_a + m_g) / 2, (m_a * m_g) ** (1 / 2)
588		return m_a
589
590
591		def ghmean(nums: Sequence[float], prec: int = 12) -> float:
592	1	"""Return geometric-harmonic mean.
593	1
594	1	Iterates between geometric & harmonic means until they converge to
595	1	a single value (rounded to 10 digits).
596	1
597	1	Cf. https://en.wikipedia.org/wiki/Geometric-harmonic_mean
598	1
599		Parameters
600		----------
601	1	nums : list
602		A series of numbers
603		prec : int
604		Digits of precision when testing convergeance
605
606		Returns
607		-------
608		float
609		The geometric-harmonic mean of nums
610
611		Examples
612		--------
613		>>> ghmean([1, 2, 3, 4])
614		2.058868154613003
615		>>> ghmean([1, 2])
616		1.3728805006183502
617		>>> ghmean([0, 5, 1000])
618		0.0
619
620		>>> ghmean([0, 0])
621		0.0
622		>>> ghmean([0, 0, 5])
623		nan
624
625		.. versionadded:: 0.1.0
626
627		"""
628		m_g = gmean(nums)
629		m_h = hmean(nums)
630		if math.isnan(m_g) or math.isnan(m_h):
631		return float('nan')
632		while round(m_h, prec) != round(m_g, prec):
633		m_g, m_h = (m_g * m_h) ** (1 / 2), (2 * m_g * m_h) / (m_g + m_h)
634		return m_g
635
636
637		def aghmean(nums: Sequence[float], prec: int = 12) -> float:
638	1	"""Return arithmetic-geometric-harmonic mean.
639	1
640	1	Iterates over arithmetic, geometric, & harmonic means until they
641	1	converge to a single value (rounded to 10 digits), following the
642	1	method described in :cite:`Raissouli:2009`.
643	1
644	1	Parameters
645		----------
646		nums : list
647	1	A series of numbers
648		prec : int
649		Digits of precision when testing convergeance
650
651		Returns
652		-------
653		float
654		The arithmetic-geometric-harmonic mean of nums
655
656		Examples
657		--------
658		>>> aghmean([1, 2, 3, 4])
659		2.198327159900212
660		>>> aghmean([1, 2])
661		1.4142135623731884
662		>>> aghmean([0, 5, 1000])
663		335.0
664
665		.. versionadded:: 0.1.0
666
667		"""
668		m_a = amean(nums)
669		m_g = gmean(nums)
670		m_h = hmean(nums)
671		if math.isnan(m_a) or math.isnan(m_g) or math.isnan(m_h):
672		return float('nan')
673		while round(m_a, prec) != round(m_g, prec) and round(m_g, prec) != round(
674		m_h, prec
675		):
676		m_a, m_g, m_h = (
677		(m_a + m_g + m_h) / 3,
678	1	(m_a * m_g * m_h) ** (1 / 3),
679	1	3 / (1 / m_a + 1 / m_g + 1 / m_h),
680	1	)
681	1	return m_a
682	1
683	1
684		def midrange(nums: Sequence[float]) -> float:
685		"""Return midrange.
686	1
687		The midrange is the arithmetic mean of the maximum & minimum of a series.
688
689		Cf. https://en.wikipedia.org/wiki/Midrange
690
691	1	Parameters
692		----------
693		nums : list
694	1	A series of numbers
695
696		Returns
697		-------
698		float
699		The midrange of nums
700
701		Examples
702		--------
703		>>> midrange([1, 2, 3])
704		2.0
705		>>> midrange([1, 2, 2, 3])
706		2.0
707		>>> midrange([1, 2, 1000, 3])
708		500.5
709
710		.. versionadded:: 0.1.0
711
712		"""
713		return 0.5 * (max(nums) + min(nums))
714
715
716		def median(nums: Sequence[float]) -> float:
717		"""Return median.
718
719		With numbers sorted by value, the median is the middle value (if there is
720		an odd number of values) or the arithmetic mean of the two middle values
721		(if there is an even number of values).
722
723	1	Cf. https://en.wikipedia.org/wiki/Median
724
725		Parameters
726	1	----------
727		nums : list
728		A series of numbers
729
730		Returns
731		-------
732		int or float
733		The median of nums
734
735		Examples
736		--------
737		>>> median([1, 2, 3])
738		2
739		>>> median([1, 2, 3, 4])
740		2.5
741		>>> median([1, 2, 2, 4])
742		2
743
744		.. versionadded:: 0.1.0
745
746		"""
747		nums = sorted(nums)
748		mag = len(nums)
749		if mag % 2:
750		mag = int((mag - 1) / 2)
751		return nums[mag]
752		mag = int(mag / 2)
753		med = (nums[mag - 1] + nums[mag]) / 2
754		return med if not med.is_integer() else int(med)
755
756
757	1	def mode(nums: Sequence[float]) -> float:
758	1	"""Return the mode.
759	1
760	1	The mode of a series is the most common element of that series
761	1
762	1	Cf. https://en.wikipedia.org/wiki/Mode_(statistics)
763	1
764	1	Parameters
765		----------
766		nums : list
767	1	A series of numbers
768
769		Returns
770		-------
771		int or float
772		The mode of nums
773
774		Example
775		-------
776		>>> mode([1, 2, 2, 3])
777		2
778
779		.. versionadded:: 0.1.0
780
781		"""
782		return Counter(nums).most_common(1)[0][0]
783
784
785		def var(
786		nums: Sequence[float],
787		mean_func: Callable[[Sequence[float]], float] = amean,
788		ddof: int = 0,
789		) -> float:
790		r"""Calculate the variance.
791
792	1	The variance (:math:`\sigma^2`) of a series of numbers (:math:`x_i`) with
793		mean :math:`\mu` and population :math:`N` is:
794
795	1	.. math::
796
797		\sigma^2 = \frac{1}{N}\sum_{i=1}^{N}(x_i-\mu)^2
798
799		Cf. https://en.wikipedia.org/wiki/Variance
800
801		Parameters
802		----------
803		nums : list
804		A series of numbers
805		mean_func : function
806		A mean function (amean by default)
807		ddof : int
808		The degrees of freedom (0 by default)
809
810		Returns
811		-------
812		float
813		The variance of the values in the series
814
815		Examples
816		--------
817		>>> var([1, 1, 1, 1])
818		0.0
819		>>> var([1, 2, 3, 4])
820		1.25
821		>>> round(var([1, 2, 3, 4], ddof=1), 12)
822		1.666666666667
823
824		.. versionadded:: 0.3.0
825
826		"""
827		x_bar = mean_func(nums)
828		return sum((x - x_bar) ** 2 for x in nums) / (len(nums) - ddof)
829
830
831		def std(
832		nums: Sequence[float],
833	1	mean_func: Callable[[Sequence[float]], float] = amean,
834	1	ddof: int = 0,
835		) -> float:
836		"""Return the standard deviation.
837	1
838		The standard deviation of a series of values is the square root of the
839		variance.
840
841		Cf. https://en.wikipedia.org/wiki/Standard_deviation
842
843		Parameters
844		----------
845		nums : list
846		A series of numbers
847		mean_func : function
848		A mean function (amean by default)
849		ddof : int
850		The degrees of freedom (0 by default)
851
852		Returns
853		-------
854		float
855		The standard deviation of the values in the series
856
857		Examples
858		--------
859		>>> std([1, 1, 1, 1])
860		0.0
861		>>> round(std([1, 2, 3, 4]), 12)
862		1.11803398875
863		>>> round(std([1, 2, 3, 4], ddof=1), 12)
864		1.290994448736
865
866		.. versionadded:: 0.3.0
867
868		"""
869		return var(nums, mean_func, ddof) ** 0.5
870
871	1
872		if __name__ == '__main__':
873		import doctest
874
875		doctest.testmod()
876

chrislit / abydos

abydos.stats._mean.aghmean() B last analyzed 2020-12-31 20:10 UTC

Complexity

Size

Duplication

Code Coverage

Importance

Duplication Side-by-Side

Filter issues like

abydos.stats._mean.aghmean() B
last analyzed 2020-12-31 20:10 UTC