"statistics" --- 数理統計関数
*****************************

バージョン 3.4 で追加.

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

======================================================================

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

注釈:

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


平均及び中心位置の測度
======================

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

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


分散の測度
==========

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

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


関数の詳細
==========

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

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

     * 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* に渡して標本の分散
     を計算することが出来ます。


例外
====

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

exception statistics.StatisticsError

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