# 9.7. `statistics` - 数学统计函数

版本3.4中的新功能。

源代码： Lib / statistics.py

此模块提供用于计算数字（`Real`值）数据的数学统计的功能。

注意

除非另有说明，否则这些函数支持`int`，`float`，`decimal.Decimal`和`fractions.Fraction`。目前不支持其他类型的行为（无论是否在数字塔中）。混合类型也是未定义的和实现依赖的。如果您的输入数据由混合类型组成，您可以使用`map()`确保一致的结果，例如 `map（float， input_data）`。

## 9.7.1.中心位置的平均值和度量

这些函数从总体或样本计算平均值或典型值。

`mean()` | 数据的算术平均值（“平均”）。
`median()` | 数据的中位数（中间值）。
`median_low()` | 数据的中位数低。
`median_high()` | 数据的中位数高。
`median_grouped()` | 分组数据的中位数或第50个百分位数。
`mode()` | 离散数据的模式（最常见值）。

## 9.7.2.扩展度量

这些函数计算总体或样本趋向于偏离典型值或平均值多少的量度。

`pstdev()` | 数据的总体标准偏差。
`pvariance()` | 数据的人口方差。
`stdev()` | 数据的样本标准偏差。
`variance()` | 数据的样本方差。

## 9.7.3。函数详细信息

注意：这些函数不需要对它们提供的数据进行排序。然而，为了阅读方便，大多数实施例显示排序的序列。

`statistics.``mean`(data)

  返回数据的样本算术平均值，实数值的序列或迭代器。

  算术平均值是数据的总和除以数据点的数量。它通常被称为“平均值”，虽然它只是许多不同数学平均值中的一个。它是数据的中心位置的度量。

  如果数据为空，则会出现`StatisticsError`。

  一些使用示例：

      >>> mean([1, 2, 3, 4, 4])
      2.8
      >>> mean([-1.0, 2.5, 3.25, 5.75])
      2.625

      >>> from fractions import Fraction as F
      >>> mean([F(3, 7), F(1, 21), F(5, 3), F(1, 3)])
      Fraction(13, 21)

      >>> from decimal import Decimal as D
      >>> mean([D("0.5"), D("0.75"), D("0.625"), D("0.375")])
      Decimal('0.5625')

  注意

  平均值受异常值强烈影响，并且不是中心位置的鲁棒估计器：平均值不一定是数据点的典型示例。对于更稳健，虽然效率较低，中心位置的测量，参见`median()`和`mode()`。（在这种情况下，“有效”是指统计效率而不是计算效率。）

  样本平均值给出真实总体平均值的无偏估计，这意味着，在所有可能样本上取平均值，`mean(sample)`收敛于整个群体的真实平均值。如果数据代表整个群体而不是样本，则`mean(data)`等效于计算真实群体平均值μ。

`statistics.``median`(data)

  使用常用的“中间两个平均值”方法返回数值数据的中值（中间值）。如果data为空，则会出现`StatisticsError`。

  中位数是中心位置的可靠度量，并且受到数据中异常值的存在的影响较小。当数据点的数量为奇数时，返回中间数据点：

      >>> median([1, 3, 5])
      3

  当数据点的数量为偶数时，通过取两个中间值的平均值来内插中值：

      >>> median([1, 3, 5, 7])
      4.0

  这适合于您的数据是离散的，并且您不介意中值可能不是实际的数据点。

  也可以看看

  `median_low()`，`median_high()`，`median_grouped()`

`statistics.``median_low`(data)

  返回数值数据的低中位数。如果data为空，则会出现`StatisticsError`。

  低中值总是数据集的成员。当数据点的数量为奇数时，返回中间值。当为偶数时，返回两个中间值中较小的值。

      >>> median_low([1, 3, 5])
      3
      >>> median_low([1, 3, 5, 7])
      3

  当数据为离散数据时，使用低中值，并且您更喜欢中值为实际数据点，而不是内插。

`statistics.``median_high`(data)

  返回数据的高中位数。如果data为空，则会出现`StatisticsError`。

  高中位数始终是数据集的成员。当数据点的数量为奇数时，返回中间值。当为偶数时，返回两个中间值中的较大者。

      >>> median_high([1, 3, 5])
      3
      >>> median_high([1, 3, 5, 7])
      5

  在数据离散时使用高中位数，并且您更喜欢中位数为实际数据点而不是内插。

`statistics.``median_grouped`(data, interval=1)

  使用内插法返回分组连续数据的中值，计算为第50个百分位数。如果data为空，则会出现`StatisticsError`。

      >>> median_grouped([52, 52, 53, 54])
      52.5

  在下面的示例中，数据被四舍五入，使得每个值表示数据类的中点，例如。1是0.5-1.5等级的中点，2是1.5-2.5的中点，3是2.5-3.5的中点等。使用给定的数据，中间值落在类3.5-4.5中的某处，并且使用插值来估计它：

      >>> median_grouped([1, 2, 2, 3, 4, 4, 4, 4, 4, 5])
      3.7

  可选参数interval表示类间隔，默认为1。自然改变类间隔将改变插值：

      >>> median_grouped([1, 3, 3, 5, 7], interval=1)
      3.25
      >>> median_grouped([1, 3, 3, 5, 7], interval=2)
      3.5

  此函数不检查数据点是否至少interval。

  CPython实现细节：在某些情况下，`median_grouped()`可能会将数据点强制为浮点数。这种行为在未来可能会改变。

  也可以看看

  - “行为科学统计”，Frederick J Gravetter和Larry B Wallnau（第8版）。
  - 计算中位数。
  - Gnome Gnumeric电子表格中的SSMEDIAN函数，包括此讨论。

`statistics.``mode`(data)

  从离散或标称数据返回最常用的数据点。模式（当它存在时）是最典型的值，并且是中心位置的鲁棒测量。

  如果data为空，或者如果没有一个最常见的值，则会引发`StatisticsError`。

  `mode`假定离散数据，并返回单个值。这是学校通常教授的模式的标准处理：

      >>> mode([1, 1, 2, 3, 3, 3, 3, 4])
      3

  该模式是唯一的，因为它是唯一也适用于标称（非数字）数据的统计量：

      >>> mode(["red", "blue", "blue", "red", "green", "red", "red"])
      'red'

`statistics.``pstdev`(data, mu=None)

  返回总体标准差（总体方差的平方根）。有关参数和其他详细信息，请参见`pvariance()`。

      >>> pstdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
      0.986893273527251

`statistics.``pvariance`(data, mu=None)

  返回数据的总体方差，实数值的非空迭代。方差或关于均值的二阶矩是数据的可变性（扩展或分散）的度量。大的方差表示数据被展开；小方差表示它在均值附近聚集。

  如果给出了可选的第二个参数mu，它应该是数据的平均值。如果缺少或`None`（默认值），将自动计算平均值。

  使用此函数计算整个总体的方差。为了从样本估计方差，`variance()`函数通常是更好的选择。

  引发`StatisticsError`如果数据为空。

  例子：

      >>> data = [0.0, 0.25, 0.25, 1.25, 1.5, 1.75, 2.75, 3.25]
      >>> pvariance(data)
      1.25

  如果您已经计算了数据的平均值，则可以将其作为可选的第二个参数mu传递，以避免重新计算：

      >>> mu = mean(data)
      >>> pvariance(data, mu)
      1.25

  此函数不会尝试验证您已通过mu的实际平均值。使用mu的任意值可能导致无效或不可能的结果。

  支持小数和分数：

      >>> from decimal import Decimal as D
      >>> pvariance([D("27.5"), D("30.25"), D("30.25"), D("34.5"), D("41.75")])
      Decimal('24.815')

      >>> from fractions import Fraction as F
      >>> pvariance([F(1, 4), F(5, 4), F(1, 2)])
      Fraction(13, 72)

  注意

  当调用整个人口时，这给出了人口方差σ²。当对样本调用时，这是偏置样本方差s²，也称为具有N个自由度的方差。

  如果你以某种方式知道真实总体平均值μ，你可以使用这个函数来计算样本的方差，给出已知总体平均值作为第二个参数。如果数据点是代表性的（例如，独立和相同分布），结果将是人口方差的无偏估计。

`statistics.``stdev`(data, xbar=None)

  返回样本标准偏差（样本方差的平方根）。有关参数和其他详细信息，请参见`variance()`。

      >>> stdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
      1.0810874155219827

`statistics.``variance`(data, xbar=None)

  返回数据的样本方差，这是至少两个实数值的迭代。方差或关于均值的二阶矩是数据的可变性（扩展或分散）的度量。大的方差表示数据被展开；小方差表示它在均值附近聚集。

  如果给出了可选的第二个参数xbar，它应该是数据的平均值。如果缺少或`None`（默认值），将自动计算平均值。

  当您的数据是来自总体的样本时使用此函数。要计算整个群体的方差，请参见`pvariance()`。

  引发`StatisticsError`如果数据具有少于两个值。

  例子：

      >>> data = [2.75, 1.75, 1.25, 0.25, 0.5, 1.25, 3.5]
      >>> variance(data)
      1.3720238095238095

  如果您已计算数据的均值，则可以将其作为可选的第二个参数xbar传递，以避免重新计算：

      >>> m = mean(data)
      >>> variance(data, m)
      1.3720238095238095

  此函数不会尝试验证您是否已经通过了xbar的实际平均值。使用xbar的任意值可能导致无效或不可能的结果。

  支持小数和分数值：

      >>> from decimal import Decimal as D
      >>> variance([D("27.5"), D("30.25"), D("30.25"), D("34.5"), D("41.75")])
      Decimal('31.01875')

      >>> from fractions import Fraction as F
      >>> variance([F(1, 6), F(1, 2), F(5, 3)])
      Fraction(67, 108)

  注意

  这是样本方差s²与贝塞尔校正，也称为具有N-1自由度的方差。只要数据点是代表性的。独立和相同分布），结果应该是真实总体方差的无偏估计。

  如果您以某种方式知道实际的群体平均值μ，您应该将其作为mu参数传递给`pvariance()`函数以获取样本的方差。

## 9.7.4.异常

定义了一个异常：

exception `statistics.``StatisticsError`

  与统计相关的异常的`ValueError`子类。