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

バージョン 3.4 で追加.

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

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

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

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

 `mean()` データの算術平均。 `harmonic_mean()` Harmonic mean of data. `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)

Return the sample arithmetic mean of data which can be a sequence or iterator.

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

`statistics.``harmonic_mean`(data)

Return the harmonic mean of data, a sequence or iterator of real-valued numbers.

The harmonic mean, sometimes called the subcontrary mean, is the reciprocal of the arithmetic `mean()` of the reciprocals of the data. For example, the harmonic mean of three values a, b and c will be equivalent to `3/(1/a + 1/b + 1/c)`.

The harmonic mean is a type of average, a measure of the central location of the data. It is often appropriate when averaging quantities which are rates or ratios, for example speeds. For example:

Suppose an investor purchases an equal value of shares in each of three companies, with P/E (price/earning) ratios of 2.5, 3 and 10. What is the average P/E ratio for the investor's portfolio?

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

Using the arithmetic mean would give an average of about 5.167, which is too high.

`StatisticsError` is raised if data is empty, or any element is less than zero.

バージョン 3.6 で追加.

`statistics.``median`(data)

Return the median (middle value) of numeric data, using the common "mean of middle two" method. If data is empty, `StatisticsError` is raised. data can be a sequence or iterator.

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

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

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

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

`statistics.``median_low`(data)

Return the low median of numeric data. If data is empty, `StatisticsError` is raised. data can be a sequence or iterator.

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

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

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

`statistics.``median_high`(data)

Return the high median of data. If data is empty, `StatisticsError` is raised. data can be a sequence or iterator.

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

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

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

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

Return the median of grouped continuous data, calculated as the 50th percentile, using interpolation. If data is empty, `StatisticsError` is raised. data can be a sequence or iterator.

```>>> median_grouped([52, 52, 53, 54])
52.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 が空の場合や最頻値が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)

```>>> pstdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
0.986893273527251
```
`statistics.``pvariance`(data, mu=None)

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

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

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

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

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

```>>> 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次の中心化モーメントはデータの散らばり具合の測度です。分散が大きいデータはばらつきが大きく、分散が小さいデータは平均値のまわりに固まっています。

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

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

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

```>>> 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 の分散です。与えられたデータ点が代表的 (たとえば独立で均等に分布) な場合、戻り値は母分散の不偏推定量になります。

## 9.7.4. 例外¶

exception `statistics.``StatisticsError`