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


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 50^e percentile.                           |
+-------------------------+-----------------------------------------------+
| "mode()"                | Mode (most common value) of discrete data.    |
+-------------------------+-----------------------------------------------+


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


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

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


Exceptions
==========

Une seule exception est définie :

exception statistics.StatisticsError

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