# 9.7. `statistics` --- 数理統計関数

バージョン 3.4 で追加.

ソースコード: Lib/statistics.py

このモジュールは、数値 (`Real` 型) データを数学的に統計計算するための関数を提供します。

注釈

特に明記しない限り、これらの関数は `int`, `float`, `decimal.Decimal` そして `fractions.Fraction` をサポートします。他の型 (算術型及びそれ以外) は現在サポートされていません。混合型 (mixed type) も未定義で実装依存です。入力データが混合型を含んでいる場合、`map()` を使用すると正しい結果が得られるでしょう。 e.g. `map(float, input_data)`。

## 9.7.1. 平均及び中心位置の測度

これらの関数は母集団または標本の平均値や標準値を計算します。

`mean()` | データの算術平均。
`harmonic_mean()` | データの調和平均。
`median()` | データの中央値。
`median_low()` | データの low median。
`median_high()` | データの high median。
`median_grouped()` | grouped data の中央値、すなわち50パーセンタイル。
`mode()` | 離散データの最頻値。

## 9.7.2. 分散の測度

これらの関数は母集団または標本が標準値や平均値からどれくらい離れているかについて計算します。

`pstdev()` | データの母標準偏差。
`pvariance()` | データの母分散。
`stdev()` | データの標本標準偏差。
`variance()` | データの標本標準分散。

## 9.7.3. 関数の詳細

註釈: 関数の引数となるデータをソートしておく必要はありません。例の多くがソートされているのは見やすさのためです。

`statistics.``mean`(data)

  シーケンス型またはイテレータになり得る data の標本算術平均を返します。

  算術平均はデータの総和をデータ数で除したものです。単に「平均」と呼ばれることも多いですが、数学における平均の一種に過ぎません。データの中心位置の測度の一つです。

  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)` は真の母平均に収束します (訳注: 大数の法則)。data が標本ではなく母集団全体の場合、`mean(data)` は真の母平均 μ を計算することと等価です。

`statistics.``harmonic_mean`(data)

  実数値のシーケンス型またはイテレータの data の調和平均を返します。

  調和平均（harmonic mean, subcontrary mean）は、データの逆数の算術平均の逆数です。例えば、3つの値 a, b, c の調和平均は``3/(1/a + 1/b + 1/c)`` になります。

  調和平均は平均の一種で、データの中心位置の測度です。速度のような率(rates)や比(ratios)の量を平均するときにしばしば適切です。例えば、

  投資家がP / E（価格/収益）の比率が2.5,3,10という3つの会社のそれぞれに等しい価値の株式を購入したとします。投資家のポートフォリオの平均P / Eの比率はいくつでしょうか？

      >>> harmonic_mean([2.5, 3, 10])  # For an equal investment portfolio.
      3.6

  算術平均を使うと平均は約5.167になり、高すぎる値になります。

  もし data が空の場合、またはいずれの要素が0より小さい場合、 `StatisticsError` は例外を送出します。

  バージョン 3.6 で追加.

`statistics.``median`(data)

  一般的な「中央2つの平均をとる」方法を使用して、数値データの中央値（中間値）を返します。もし data が空の場合、例外 `StatisticsError` が送出されます。data はシーケンス型またはイテレータにもなれます。

  中央値は外れ値の影響を受けにくいため、中心位置のロバストな測度です。データ数が奇数の場合は中央の値を返します:

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

  データ数が偶数の場合は、中央値は中央に最も近い2値の算術平均で補間されます:

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

  データが離散的で、中央値がデータ点にない値でも構わない場合に適しています。

  もしあなたのデータが（注文操作をサポートする）序数で、（追加操作をサポートしない）数値でないならば、代わりに `median_low()` または `median_high()` を使うべきです。

  参考

  `median_low()`, `median_high()`, `median_grouped()`

`statistics.``median_low`(data)

  数値データの小さい方の中央値（low median）を返します。もし data が空の場合、:exc:`StatisticsError`が送出されます。data はシーケンス型またはイテレータにもなれます。

  low median は必ずデータに含まれています。データ数が奇数の場合は中央の値を返し、偶数の場合は中央の2値の小さい方を返します。

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

  データが離散的で、中央値が補間値よりもデータ点にある値の方が良い場合に用いてください。

`statistics.``median_high`(data)

  データの大きい方の中央値(high median)を返します。もし data が空の場合、`StatisticsError` が送出されます。 data はシーケンス型やイテレータにもなれます。

  high median は必ずデータに含まれています。データ数が奇数の場合は中央の値を返し、偶数の場合は中央の2値の大きい方を返します。

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

  データが離散的で、中央値が補間値よりもデータ点にある値の方が良い場合に用いてください。

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

  補間を使用して、50番目のパーセンタイルとして計算されたグループ化された連続データの中央値を返します。もし data が空の場合、`StatisticsError` が送出されます。data はシーケンス型やイテレータにもなれます。

      >>> 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 implementation detail: 環境によっては `median_grouped()` はデータ点を強制的に浮動小数点に変換します。この挙動はいずれ変更されるでしょう。

  参考

  - "Statistics for the Behavioral Sciences", Frederick J Gravetter and Larry B Wallnau (8th Edition).

  - Calculating the median.

  - The SSMEDIAN function in the Gnome Gnumeric spreadsheet, including this discussion.

`statistics.``mode`(data)

  離散データや名目データ data の最頻値を返します。最頻値は (存在するときは) 最も標準的な値で、中心位置のロバストな測度です。

  data が空の場合や最頻値が1つでない場合 `StatisticsError` を送出します。

  `mode` は離散データであることを想定していて、1つの値を返します。これは学校で教わるような最頻値の標準的な取扱いです:

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

  data の母分散を返します。data は実数の空でない iterable です。分散、すなわち2次の中心化モーメントはデータの散らばり具合の測度です。分散が大きいデータはばらつきが大きく、分散が小さいデータは平均値のまわりに固まっています。

  第2引数 mu に値を渡す場合は data の平均値でなくてはなりません。mu が与えられない場合や `None` の場合 (デフォルト)、平均値は自動的に計算されます。

  母集団全体から分散を計算する場合に用いてください。標本から分散を推定する場合は `variance()` を使いましょう。

  data が空の場合 `StatisticsError` を送出します。

  例:

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

  既にデータの平均値を計算している場合、それを第2引数 mu に渡して再計算を避けることが出来ます:

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

  この関数は引数として渡した mu が実際の平均値かどうかチェックしません。任意の値を mu に渡すと無効な結果やありえない結果が返ることがあります。

  Decimal と Fraction がサポートされています:

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

  注釈

  母集団全体で呼んだ場合は母分散 σ² を返します。代わりに標本で呼んだ場合は biased variance s²、すなわち自由度 N の分散を返します。

  何らかの方法で真の母平均 μ を知っている場合、それを第2引数に渡して標本の分散を計算することが出来ます。与えられたデータ点が代表的 (たとえば独立で均等に分布) な場合、戻り値は母分散の不偏推定量になります。

`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)

  data の標本分散を返します。data は少なくとも2つの実数の iterable です。分散、すなわち2次の中心化モーメントはデータの散らばり具合の測度です。分散が大きいデータはばらつきが大きく、分散が小さいデータは平均値のまわりに固まっています。

  第2引数 xbar に値を渡す場合は data の平均値でなくてはなりません。xbar が与えられない場合や `None` の場合 (デフォルト)、平均値は自動的に計算されます。

  データが母集団の標本であるときに用いてください。母集団全体から分散を計算するには `pvariance()` を参照してください。

  data の値が2より少ない場合 `StatisticsError` を送出します。

  例:

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

  既にデータの平均値を計算している場合、それを第2引数 xbar に渡して再計算を避けることが出来ます:

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

  この関数は引数として渡した xbar が実際の平均値かどうかチェックしません。任意の値を xbar に渡すと無効な結果やありえない結果が返ることがあります。

  Decimal と Fraction がサポートされています:

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

  注釈

  Bessel 補正済みの標本分散 s²、すなわち自由度 N-1 の分散です。与えられたデータ点が代表的 (たとえば独立で均等に分布) な場合、戻り値は母分散の不偏推定量になります。

  何らかの方法で真の母平均 μ を知っている場合、それを `pvariance()` の引数 mu に渡して標本の分散を計算することが出来ます。

## 9.7.4. 例外

例外が1つ定義されています:

exception `statistics.``StatisticsError`

  統計関係の例外。`ValueError` の派生クラス。