9.7. statistics — Fonctions mathématiques pour les statistiques

Nouveau dans la version 3.4.

Code source : Lib/statistics.py

---

This module provides functions for calculating mathematical statistics of numeric (Real-valued) data.

Note

Unless explicitly noted otherwise, these functions support int, float, decimal.Decimal and fractions.Fraction. Behaviour with other types (whether in the numeric tower or not) is currently unsupported. Mixed types are also undefined and implementation-dependent. If your input data consists of mixed types, you may be able to use map() to ensure a consistent result, e.g. map(float, input_data).

9.7.1. Moyennes et mesures de la tendance centrale

Ces fonctions calculent une moyenne ou une valeur typique à partir d’une population ou d’un échantillon.

mean()	Moyenne arithmétique des données.
harmonic_mean()	Moyenne harmonique des données.
median()	Médiane (valeur centrale) des données.
median_low()	Médiane basse des données.
median_high()	Médiane haute des données.
median_grouped()	Médiane de données groupées, calculée comme le 50e percentile.
mode()	Mode (most common value) of discrete data.

9.7.2. Mesures de la dispersion

Ces fonctions mesurent la tendance de la population ou d’un échantillon à dévier des valeurs typiques ou des valeurs moyennes.

pstdev()	Écart-type de la population.
pvariance()	Variance de la population.
stdev()	Écart-type d’un échantillon.
variance()	Variance d’un échantillon.

9.7.3. Détails des fonctions

Note : les fonctions ne requièrent pas que les données soient ordonnées. Toutefois, pour en faciliter la lecture, les exemples utiliseront des séquences croissantes.

statistics.mean(data)

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

La moyenne arithmétique est la somme des valeurs divisée par le nombre d’observations. Il s’agit de la valeur couramment désignée comme la « moyenne » bien qu’il existe de multiples façons de définir mathématiquement la moyenne. C’est une mesure de la tendance centrale des données.

Une erreur StatisticsError est levée si data est vide.

Exemples d’utilisation :

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

Note

The mean is strongly affected by outliers and is not a robust estimator for central location: the mean is not necessarily a typical example of the data points. For more robust, although less efficient, measures of central location, see median() and mode(). (In this case, « efficient » refers to statistical efficiency rather than computational efficiency.)

The sample mean gives an unbiased estimate of the true population mean, which means that, taken on average over all the possible samples, mean(sample) converges on the true mean of the entire population. If data represents the entire population rather than a sample, then mean(data) is equivalent to calculating the true population mean μ.

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:

Supposons qu’un investisseur achète autant de parts dans trois compagnies chacune de ratio cours sur bénéfices (P/E) 2,5, 3 et 10. Quel est le ratio cours sur bénéfices moyen du portefeuille de l’investisseur ?

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

Une erreur StatisticsError est levée si data est vide ou si l’un de ses éléments est inférieur à zéro.

Nouveau dans la version 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.

The median is a robust measure of central location, and is less affected by the presence of outliers in your data. When the number of data points is odd, the middle data point is returned:

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

Lorsque le nombre d’observations est pair, la médiane est interpolée en calculant la moyenne des deux valeurs du milieu :

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

Cette approche est adaptée à des données discrètes à condition que vous acceptiez que la médiane ne fasse pas nécessairement partie des observations.

If your data is ordinal (supports order operations) but not numeric (doesn’t support addition), you should use median_low() or median_high() instead.

Voir aussi

median_low(), median_high(), median_grouped()

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.

La médiane basse est toujours une valeur représentée dans les données. Lorsque le nombre d’observations est impair, la valeur du milieu est renvoyée. Sinon, la plus petite des deux valeurs du milieu est renvoyée.

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

Utilisez la médiane basse lorsque vos données sont discrètes et que vous préférez que la médiane soit une valeur représentée dans vos observations plutôt que le résultat d’une interpolation.

statistics.median_high(data)

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

La médiane haute est toujours une valeur représentée dans les données. Lorsque le nombre d’observations est impair, la valeur du milieu est renvoyée. Sinon, la plus grande des deux valeurs du milieu est renvoyée.

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

Utilisez la médiane haute lorsque vos données sont discrètes et que vous préférez que la médiane soit une valeur représentée dans vos observations plutôt que le résultat d’une interpolation.

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

Dans l’exemple ci-dessous, les valeurs sont arrondies de sorte que chaque valeur représente le milieu d’un groupe. Par exemple 1 est le milieu du groupe 0,5 - 1, 2 est le milieu du groupe 1,5 - 2,5, 3 est le milieu de 2,5 - 3,5, etc. Compte-tenu des valeurs ci-dessous, la valeur centrale se situe quelque part dans le groupe 3,5 - 4,5 et est estimée par interpolation :

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

L’argument optionnel interval représente la largeur de l’intervalle des groupes (par défaut, 1). Changer l’intervalle des groupes change bien sûr l’interpolation :

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

Cette fonction ne vérifie pas que les valeurs sont bien séparées d’au moins une fois interval.

CPython implementation detail: Sous certaines conditions, median_grouped() peut convertir les valeurs en nombres à virgule flottante. Ce comportement est susceptible de changer dans le futur.

Voir aussi

• Statistics for the Behavioral Sciences, Frederick J Gravetter et Larry B Wallnau (8^e édition, ouvrage en anglais).

• Calculating the median.

• La fonction SSMEDIAN du tableur Gnome Gnumeric ainsi que cette discussion.

statistics.mode(data)

Return the most common data point from discrete or nominal data. The mode (when it exists) is the most typical value, and is a robust measure of central location.

If data is empty, or if there is not exactly one most common value, StatisticsError is raised.

mode assumes discrete data, and returns a single value. This is the standard treatment of the mode as commonly taught in schools:

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

The mode is unique in that it is the only statistic which also applies to nominal (non-numeric) data:

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

statistics.pstdev(data, mu=None)

Renvoie l’écart-type de la population (racine carrée de la variance de la population). Voir pvariance() pour les arguments et d’autres précisions.

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

statistics.pvariance(data, mu=None)

Return the population variance of data, a non-empty iterable of real-valued numbers. Variance, or second moment about the mean, is a measure of the variability (spread or dispersion) of data. A large variance indicates that the data is spread out; a small variance indicates it is clustered closely around the mean.

If the optional second argument mu is given, it should be the mean of data. If it is missing or None (the default), the mean is automatically calculated.

Utilisez cette fonction pour calculer la variance sur une population complète. Pour estimer la variance à partir d’un échantillon, utilisez plutôt variance() à la place.

Lève une erreur StatisticsError si data est vide.

Exemples :

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

Si vous connaissez la moyenne de vos données, il est possible de la passer comme argument optionnel mu lors de l’appel de fonction pour éviter de la calculer une nouvelle fois :

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

This function does not attempt to verify that you have passed the actual mean as mu. Using arbitrary values for mu may lead to invalid or impossible results.

La fonction gère les nombres décimaux et les fractions :

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

Note

Cette fonction renvoie la variance de la population σ² lorsqu’elle est appliquée sur la population entière. Si elle est appliquée seulement sur un échantillon, le résultat est alors la variance de l’échantillon s² ou variance à N degrés de liberté.

If you somehow know the true population mean μ, you may use this function to calculate the variance of a sample, giving the known population mean as the second argument. Provided the data points are representative (e.g. independent and identically distributed), the result will be an unbiased estimate of the population variance.

statistics.stdev(data, xbar=None)

Renvoie l’écart-type de l’échantillon (racine carrée de la variance de l’échantillon). Voir variance() pour les arguments et plus de détails.

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

statistics.variance(data, xbar=None)

Renvoie la variance de l’échantillon data, un itérable d’au moins deux valeurs réelles. La variance, ou moment de second ordre, est une mesure de la variabilité (ou dispersion) des données. Une variance élevée indique que les données sont très dispersées ; une variance faible indique que les valeurs sont resserrées autour de la moyenne.

Si le second argument optionnel xbar est spécifié, celui-ci doit correspondre à la moyenne de data. S’il n’est pas spécifié ou None (par défaut), la moyenne est automatiquement calculée.

Utilisez cette fonction lorsque vos données forment un échantillon d’une population plus grande. Pour calculer la variance d’une population complète, utilisez pvariance().

Lève une erreur StatisticsError si data contient moins de deux éléments.

Exemples :

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

Si vous connaissez la moyenne de vos données, il est possible de la passer comme argument optionnel xbar lors de l’appel de fonction pour éviter de la calculer une nouvelle fois :

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

Cette fonction ne vérifie pas que la valeur passée dans l’argument xbar correspond bien à la moyenne. Utiliser des valeurs arbitraires pour xbar produit des résultats impossibles ou incorrects.

La fonction gère les nombres décimaux et les fractions :

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

Note

Cela correspond à la variance s² de l’échantillon avec correction de Bessel (ou variance à N-1 degrés de liberté). En supposant que les observations sont représentatives de la population (c’est-à-dire indépendantes et identiquement distribuées), alors le résultat est une estimation non biaisée de la variance.

Si vous connaissez d’avance la vraie moyenne μ de la population, vous devriez la passer à pvariance() comme paramètre mu pour obtenir la variance de l’échantillon.

9.7.4. Exceptions

Une seule exception est définie :

exception statistics.StatisticsError

Sous-classe de ValueError pour les exceptions liées aux statistiques.