"statistics" — Fonctions mathématiques pour les statistiques
************************************************************

Nouveau dans la version 3.4.

**Code source :** Lib/statistics.py

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

Ce module fournit des fonctions pour le calcul de valeurs statistiques
sur des données numériques (valeurs réelles de la classe "Real").

Ce module n'est pas pensé comme substitut à des bibliothèques tierces
telles que NumPy, SciPy ou des suites logicielles propriétaires
complètes à destination des statisticiens professionnels comme
Minitab, SAS ou Matlab. Ce module se situe au niveau des calculatrices
scientifiques graphiques.

À moins que cela ne soit précisé différemment, ces fonctions gèrent
les objets "int", "float", "Decimal" et "Fraction". Leur bon
comportement avec d'autres types (numériques ou non) n'est pas
garanti. Le comportement de ces fonctions sur des collections mixtes
de différents types est indéfini et dépend de l'implémentation. Si vos
données comportement un mélange de plusieurs types, vous pouvez
utiliser "map()" pour vous assurer que le résultat est cohérent, par
exemple : "map(float, input_data)".

Some datasets use "NaN" (not a number) values to represent missing
data. Since NaNs have unusual comparison semantics, they cause
surprising or undefined behaviors in the statistics functions that
sort data or that count occurrences.  The functions affected are
"median()", "median_low()", "median_high()", "median_grouped()",
"mode()", "multimode()", and "quantiles()".  The "NaN" values should
be stripped before calling these functions:

   >>> from statistics import median
   >>> from math import isnan
   >>> from itertools import filterfalse

   >>> data = [20.7, float('NaN'),19.2, 18.3, float('NaN'), 14.4]
   >>> sorted(data)  # This has surprising behavior
   [20.7, nan, 14.4, 18.3, 19.2, nan]
   >>> median(data)  # This result is unexpected
   16.35

   >>> sum(map(isnan, data))    # Number of missing values
   2
   >>> clean = list(filterfalse(isnan, data))  # Strip NaN values
   >>> clean
   [20.7, 19.2, 18.3, 14.4]
   >>> sorted(clean)  # Sorting now works as expected
   [14.4, 18.3, 19.2, 20.7]
   >>> median(clean)       # This result is now well defined
   18.75


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.                               |
+-------------------------+-----------------------------------------------------------------+
| "fmean()"               | Moyenne arithmétique rapide en calcul à virgule flottante.      |
+-------------------------+-----------------------------------------------------------------+
| "geometric_mean()"      | Moyenne géométrique 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 principal (la valeur la plus représentée) de données       |
|                         | discrètes ou nominales.                                         |
+-------------------------+-----------------------------------------------------------------+
| "multimode()"           | List of modes (most common values) of discrete or nominal data. |
+-------------------------+-----------------------------------------------------------------+
| "quantiles()"           | Divise les données en intervalles de même probabilité.          |
+-------------------------+-----------------------------------------------------------------+


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


Statistics for relations between two inputs
===========================================

These functions calculate statistics regarding relations between two
inputs.

+---------------------------+-------------------------------------------------------+
| "covariance()"            | Sample covariance for two variables.                  |
+---------------------------+-------------------------------------------------------+
| "correlation()"           | Pearson's correlation coefficient for two variables.  |
+---------------------------+-------------------------------------------------------+
| "linear_regression()"     | Slope and intercept for simple linear regression.     |
+---------------------------+-------------------------------------------------------+


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)

   Renvoie la moyenne arithmétique de l'échantillon *data* qui peut
   être une séquence ou un itérable.

   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 necessarily
     a typical example of the data points. For a more robust, although
     less efficient, measure of central tendency, see "median()".La
     moyenne de l'échantillon est une estimation non biaisée de la
     moyenne de la véritable population. Ainsi, en calculant la
     moyenne sur tous les échantillons possibles, "mean(sample)"
     converge vers la moyenne réelle de la population entière. Si
     *data* est une population entière plutôt qu'un échantillon, alors
     "mean(data)" équivaut à calculer la véritable moyenne μ.

statistics.fmean(data)

   Convertit *data* en nombres à virgule flottante et calcule la
   moyenne arithmétique.

   Cette fonction est plus rapide que "mean()" et renvoie toujours un
   "float". *data* peut être une séquence ou un itérable. Si les
   données d'entrée sont vides, la fonction lève une erreur
   "StatisticsError".

      >>> fmean([3.5, 4.0, 5.25])
      4.25

   Nouveau dans la version 3.8.

statistics.geometric_mean(data)

   Convertit *data* en nombres à virgule flottante et calcule la
   moyenne géométrique.

   La moyenne géométrique mesure la tendance centrale ou la valeur
   typique de *data* en utilisant le produit des valeurs (par
   opposition à la moyenne arithmétique qui utilise la somme).

   Lève une erreur "StatisticsError" si les données sont vides, si
   elles contiennent un zéro ou une valeur négative. *data* peut être
   une séquence ou un itérable.

   Aucune mesure particulière n'est prise pour garantir que le
   résultat est parfaitement exact (cela peut toutefois changer dans
   une version future).

      >>> round(geometric_mean([54, 24, 36]), 1)
      36.0

   Nouveau dans la version 3.8.

statistics.harmonic_mean(data, weights=None)

   Return the harmonic mean of *data*, a sequence or iterable of real-
   valued numbers.  If *weights* is omitted or *None*, then equal
   weighting is assumed.

   The harmonic 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)".  If one of the values is zero, the result will be zero.

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

   Supposons qu'une voiture parcoure 10 km à 40 km/h puis 10 km à 60
   km/h. Quelle a été sa vitesse moyenne ?

      >>> harmonic_mean([40, 60])
      48.0

   Suppose a car travels 40 km/hr for 5 km, and when traffic clears,
   speeds-up to 60 km/hr for the remaining 30 km of the journey. What
   is the average speed?

      >>> harmonic_mean([40, 60], weights=[5, 30])
      56.0

   "StatisticsError" is raised if *data* is empty, any element is less
   than zero, or if the weighted sum isn't positive.

   L'algorithme actuellement implémenté s'arrête prématurément lors de
   la rencontre d'un zéro dans le parcours de l'entrée. Cela signifie
   que la validité des valeurs suivantes n'est pas testée (ce
   comportement est susceptible de changer dans une version future).

   Nouveau dans la version 3.6.

   Modifié dans la version 3.10: Added support for *weights*.

statistics.median(data)

   Renvoie la médiane (la valeur centrale) de données numériques en
   utilisant la méthode classique « moyenne des deux du milieu ». Lève
   une erreur "StatisticsError" si *data* est vide. *data* peut être
   une séquence ou un itérable.

   La médiane est une mesure robuste de la tendance centrale et est
   moins sensible à la présence de valeurs aberrantes que la moyenne.
   Lorsque le nombre d'observations est impair, la valeur du milieu
   est renvoyée :

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

   Si les données sont ordinales (elles peuvent être ordonnées) mais
   pas numériques (elles ne peuvent être additionnées), utilisez
   "median_low()" ou "median_high()" à la place.

statistics.median_low(data)

   Renvoie la médiane basse de données numériques. Lève une erreur
   "StatisticsError" si *data* est vide. *data* peut être une séquence
   ou un itérable.

   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)

   Renvoie la médiane haute des données. Lève une erreur
   "StatisticsError" si *data* est vide. *data* peut être une séquence
   ou un itérable.

   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)

   Renvoie la médiane de données réelles groupées, calculée comme le
   50^e percentile (avec interpolation). Lève une erreur
   "StatisticsError" si *data* est vide. *data* peut être une séquence
   ou un itérable.

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

   **Particularité de l'implémentation CPython :** 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)

   Renvoie la valeur la plus représentée dans la collection *data*
   (discrète ou nominale). Ce mode, lorsqu'il existe, est la valeur la
   plus représentative des données et est une mesure de la tendance
   centrale.

   S'il existe plusieurs modes avec la même fréquence, cette fonction
   renvoie le premier qui a été rencontré dans *data*. Utilisez
   "min(multimode(data))" ou "max(multimode(data))" si vous désirez le
   plus petit mode ou le plus grand mode. Lève une erreur
   "StatisticsError" si *data* est vide.

   "mode" suppose que les données sont discrètes et renvoie une seule
   valeur. Il s'agit de la définition usuelle du mode telle
   qu'enseignée dans à l'école :

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

   Le mode a la particularité d'être la seule statistique de ce module
   à pouvoir être calculée sur des données nominales (non numériques)
   :

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

   Modifié dans la version 3.8: Gère désormais des jeux de données
   avec plusieurs modes en renvoyant le premier mode rencontré.
   Précédemment, une erreur "StatisticsError" était levée si plusieurs
   modes étaient trouvés.

statistics.multimode(data)

   Renvoie une liste des valeurs les plus fréquentes en suivant leur
   ordre d'apparition dans *data*. Renvoie plusieurs résultats s'il y
   a plusieurs modes ou une liste vide si *data* est vide :

      >>> multimode('aabbbbccddddeeffffgg')
      ['b', 'd', 'f']
      >>> multimode('')
      []

   Nouveau dans la version 3.8.

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)

   Renvoie la variance de la population *data*, une séquence non-vide
   ou un itérable de 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 une large dispersion des
   valeurs ; une faible variance indique que les valeurs sont
   resserrées autour de la moyenne.

   Si le second argument optionnel *mu* est n'est pas spécifié ou est
   "None" (par défaut), il est remplacé automatiquement par la moyenne
   arithmétique. Cet argument correspond en général à la moyenne de
   *data*. En le spécifiant autrement, cela permet de calculer le
   moment de second ordre autour d'un point qui n'est pas la moyenne.

   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

   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é.Si
     vous connaissez d'avance la vraie moyenne de la population μ,
     vous pouvez utiliser cette fonction pour calculer la variance de
     l'échantillon sachant la moyenne de la population en la passante
     comme second argument. En supposant que les observations sont
     issues d'un tirage aléatoire uniforme dans la population, le
     résultat sera une estimation non biaisée de la variance de la
     population.

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.

statistics.quantiles(data, *, n=4, method='exclusive')

   Divise *data* en *n* intervalles réels de même probabilité. Renvoie
   une liste de "n - 1" valeurs délimitant les intervalles (les
   quantiles).

   Utilisez "n = 4" pour obtenir les quartiles (le défaut), "n = 10"
   pour obtenir les déciles et "n = 100" pour obtenir les centiles (ce
   qui produit 99 valeurs qui séparent *data* en 100 groupes de même
   taille). Lève une erreur "StatisticsError" si *n* est strictement
   inférieur à 1.

   *data* peut être n'importe quel itérable contenant les valeurs de
   l'échantillon. Pour que les résultats aient un sens, le nombre
   d'observations dans l'échantillon *data* doit être plus grand que
   *n*. Lève une erreur "StatisticsError" s'il n'y a pas au moins deux
   observations.

   Les quantiles sont linéairement interpolées à partir des deux
   valeurs les plus proches dans l'échantillon. Par exemple, si un
   quantile se situe à un tiers de la distance entre les deux valeurs
   de l'échantillon "100" et "112", le quantile vaudra "104".

   L'argument *method* indique la méthode à utiliser pour calculer les
   quantiles et peut être modifié pour spécifier s'il faut inclure ou
   exclure les valeurs basses et hautes de *data* de la population.

   La valeur par défaut pour *method* est ""exclusive"" et est
   applicable pour des données échantillonnées dans une population
   dont une des valeurs extrêmes peut être plus grande (respectivement
   plus petite) que le maximum (respectivement le minimum) des valeurs
   de l'échantillon. La proportion de la population se situant en-
   dessous du i^e de *m* valeurs ordonnées est calculée par la formule
   "i / (m + 1)". Par exemple, en supposant 9 valeurs dans
   l'échantillon, cette méthode les ordonne et leur associe les
   quantiles suivants : 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%.

   En utilisant ""inclusive"" comme valeur du paramètre *method*, on
   suppose que *data* correspond soit à une population entière, soit
   que les valeurs extrêmes de la population sont représentées dans
   l'échantillon. Le minimum de *data* est alors considéré comme 0^e
   centile et le maximum comme 100^e centile. La proportion de la
   population se situant sous la i^e valeur de *m* valeurs ordonnées
   est calculée par la formule "(i - 1)/(m - 1)". En supposant que
   l'on a 11 valeurs dans l'échantillon, cette méthode les ordonne et
   leur associe les quantiles suivants : 0%, 10%, 20%, 30%, 40%, 50%,
   60%, 70%, 80%, 90%, 100%.

      # Decile cut points for empirically sampled data
      >>> data = [105, 129, 87, 86, 111, 111, 89, 81, 108, 92, 110,
      ...         100, 75, 105, 103, 109, 76, 119, 99, 91, 103, 129,
      ...         106, 101, 84, 111, 74, 87, 86, 103, 103, 106, 86,
      ...         111, 75, 87, 102, 121, 111, 88, 89, 101, 106, 95,
      ...         103, 107, 101, 81, 109, 104]
      >>> [round(q, 1) for q in quantiles(data, n=10)]
      [81.0, 86.2, 89.0, 99.4, 102.5, 103.6, 106.0, 109.8, 111.0]

   Nouveau dans la version 3.8.

statistics.covariance(x, y, /)

   Return the sample covariance of two inputs *x* and *y*. Covariance
   is a measure of the joint variability of two inputs.

   Both inputs must be of the same length (no less than two),
   otherwise "StatisticsError" is raised.

   Exemples :

      >>> x = [1, 2, 3, 4, 5, 6, 7, 8, 9]
      >>> y = [1, 2, 3, 1, 2, 3, 1, 2, 3]
      >>> covariance(x, y)
      0.75
      >>> z = [9, 8, 7, 6, 5, 4, 3, 2, 1]
      >>> covariance(x, z)
      -7.5
      >>> covariance(z, x)
      -7.5

   Nouveau dans la version 3.10.

statistics.correlation(x, y, /)

   Return the Pearson's correlation coefficient for two inputs.
   Pearson's correlation coefficient *r* takes values between -1 and
   +1. It measures the strength and direction of the linear
   relationship, where +1 means very strong, positive linear
   relationship, -1 very strong, negative linear relationship, and 0
   no linear relationship.

   Both inputs must be of the same length (no less than two), and need
   not to be constant, otherwise "StatisticsError" is raised.

   Exemples :

      >>> x = [1, 2, 3, 4, 5, 6, 7, 8, 9]
      >>> y = [9, 8, 7, 6, 5, 4, 3, 2, 1]
      >>> correlation(x, x)
      1.0
      >>> correlation(x, y)
      -1.0

   Nouveau dans la version 3.10.

statistics.linear_regression(x, y, /)

   Return the slope and intercept of simple linear regression
   parameters estimated using ordinary least squares. Simple linear
   regression describes the relationship between an independent
   variable *x* and a dependent variable *y* in terms of this linear
   function:

      *y = slope * x + intercept + noise*

   where "slope" and "intercept" are the regression parameters that
   are estimated, and "noise" represents the variability of the data
   that was not explained by the linear regression (it is equal to the
   difference between predicted and actual values of the dependent
   variable).

   Both inputs must be of the same length (no less than two), and the
   independent variable *x* cannot be constant; otherwise a
   "StatisticsError" is raised.

   For example, we can use the release dates of the Monty Python films
   to predict the cumulative number of Monty Python films that would
   have been produced by 2019 assuming that they had kept the pace.

      >>> year = [1971, 1975, 1979, 1982, 1983]
      >>> films_total = [1, 2, 3, 4, 5]
      >>> slope, intercept = linear_regression(year, films_total)
      >>> round(slope * 2019 + intercept)
      16

   Nouveau dans la version 3.10.


Exceptions
==========

Une seule exception est définie :

exception statistics.StatisticsError

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


Objets "NormalDist"
===================

"NormalDist" est un outil permettant de créer et manipuler des lois
normales de variables aléatoires. Cette classe gère la moyenne et l
'écart-type d'un ensemble d'observations comme une seule entité.

Les lois normales apparaissent dans de très nombreuses applications
des statistiques. Leur ubiquité découle du théorème central limite.

class statistics.NormalDist(mu=0.0, sigma=1.0)

   Renvoie un nouvel objet *NormalDist* où *mu* représente la moyenne
   arithmétique et *sigma* l'écart-type.

   Lève une erreur "StatisticsError" si *sigma* est négatif.

   mean

      Attribut en lecture seule correspondant à la moyenne
      arithmétique d'une loi normale.

   median

      Attribut en lecture seule correspondant à la médiane d'une loi
      normale.

   mode

      Attribut en lecture seule correspondant au mode d'une loi
      normale.

   stdev

      Attribut en lecture seule correspondant à l'écart-type d'une loi
      normale.

   variance

      Attribut en lecture seule correspondant à la variance d'une loi
      normale. La variance est égale au carré de l'écart-type.

   classmethod from_samples(data)

      Crée une instance de loi normale de paramètres *mu* et *sigma*
      estimés à partir de *data* en utilisant "fmean()" et "stdev()".

      *data* peut être n'importe quel *iterable* de valeurs pouvant
      être converties en "float". Lève une erreur "StatisticsError" si
      *data* ne contient pas au moins deux éléments car il faut au
      moins un point pour estimer la moyenne et deux points pour
      estimer la variance.

   samples(n, *, seed=None)

      Génère *n* valeurs aléatoires suivant une loi normale de moyenne
      et écart-type connus. Renvoie une "list" de "float".

      Si *seed* est spécifié, sa valeur est utilisée pour initialiser
      une nouvelle instance du générateur de nombres aléatoires. Cela
      permet de produire des résultats reproductibles même dans un
      contexte de parallélisme par fils d'exécution.

   pdf(x)

      Calcule la vraisemblance qu'une variable aléatoire *X* soit
      proche de la valeur *x* à partir de la fonction de densité.
      Mathématiquement, cela correspond à la limite de la fraction
      "P(x <= X < x + dx) / dx" lorsque "dx" tend vers zéro.

      The relative likelihood is computed as the probability of a
      sample occurring in a narrow range divided by the width of the
      range (hence the word "density").  Since the likelihood is
      relative to other points, its value can be greater than "1.0".

   cdf(x)

      Calcule la probabilité qu'une variable aléatoire *X* soit
      inférieure ou égale à *x* à partir de la fonction de
      répartition. Mathématiquement, cela correspond à "P(X <= x)".

   inv_cdf(p)

      Compute the inverse cumulative distribution function, also known
      as the quantile function or the percent-point function.
      Mathematically, it is written "x : P(X <= x) = p".

      Détermine la valeur *x* de la variable aléatoire *X* telle que
      la probabilité que la variable soit inférieure ou égale à cette
      valeur *x* est égale à *p*.

   overlap(other)

      Mesure le recouvrement entre deux lois normales. Renvoie une
      valeur réelle entre 0 et 1 indiquant l'aire du recouvrement de
      deux densités de probabilité.

   quantiles(n=4)

      Divise la loi normale entre *n* intervalles réels équiprobables.
      Renvoie une liste de "(n - 1)" quantiles séparant les
      intervalles.

      Utilisez "n = 4" pour obtenir les quartiles (le défaut), "n =
      10" pour obtenir les déciles et "n = 100" pour obtenir les
      centiles (ce qui produit 99 valeurs qui séparent *data* en 100
      groupes de même taille).

   zscore(x)

      Compute the Standard Score describing *x* in terms of the number
      of standard deviations above or below the mean of the normal
      distribution: "(x - mean) / stdev".

      Nouveau dans la version 3.9.

   Les instances de la classe "NormalDist" gèrent l'addition, la
   soustraction, la multiplication et la division par une constante.
   Ces opérations peuvent être utilisées pour la translation ou la
   mise à l'échelle, par exemple :

      >>> temperature_february = NormalDist(5, 2.5)             # Celsius
      >>> temperature_february * (9/5) + 32                     # Fahrenheit
      NormalDist(mu=41.0, sigma=4.5)

   Diviser une constante par une instance de "NormalDist" n'est pas
   pris en charge car le résultat ne serait pas une loi normale.

   Étant donné que les lois normales sont issues des propriétés
   additives de variables indépendantes, il est possible d'ajouter ou
   de soustraite deux variables normales indépendantes représentées
   par des instances de "NormalDist". Par exemple :

      >>> birth_weights = NormalDist.from_samples([2.5, 3.1, 2.1, 2.4, 2.7, 3.5])
      >>> drug_effects = NormalDist(0.4, 0.15)
      >>> combined = birth_weights + drug_effects
      >>> round(combined.mean, 1)
      3.1
      >>> round(combined.stdev, 1)
      0.5

   Nouveau dans la version 3.8.


Exemples d'utilisation de "NormalDist"
--------------------------------------

"NormalDist" permet de résoudre aisément des problèmes probabilistes
classiques.

Par exemple, sachant que les scores aux examens SAT suivent une loi
normale de moyenne 1060 et d'écart-type 195, déterminer le pourcentage
d'étudiants dont les scores se situent entre 1100 et 1200, arrondi à
l'entier le plus proche :

   >>> sat = NormalDist(1060, 195)
   >>> fraction = sat.cdf(1200 + 0.5) - sat.cdf(1100 - 0.5)
   >>> round(fraction * 100.0, 1)
   18.4

Déterminer les quartiles et les déciles des scores SAT :

   >>> list(map(round, sat.quantiles()))
   [928, 1060, 1192]
   >>> list(map(round, sat.quantiles(n=10)))
   [810, 896, 958, 1011, 1060, 1109, 1162, 1224, 1310]

"NormalDist" peut générer des observations pour une simulation
utilisant la méthode de Monte-Carlo afin d'estimer la distribution
d'un modèle difficile à résoudre analytiquement :

   >>> def model(x, y, z):
   ...     return (3*x + 7*x*y - 5*y) / (11 * z)
   ...
   >>> n = 100_000
   >>> X = NormalDist(10, 2.5).samples(n, seed=3652260728)
   >>> Y = NormalDist(15, 1.75).samples(n, seed=4582495471)
   >>> Z = NormalDist(50, 1.25).samples(n, seed=6582483453)
   >>> quantiles(map(model, X, Y, Z))       
   [1.4591308524824727, 1.8035946855390597, 2.175091447274739]

Normal distributions can be used to approximate Binomial distributions
when the sample size is large and when the probability of a successful
trial is near 50%.

Par exemple, 750 personnes assistent à une conférence sur le logiciel
libre. Il y a deux salles pouvant chacune accueillir 500 personnes.
Dans la première salle a lieu une présentation sur Python, dans
l'autre une présentation à propos de Ruby. Lors des conférences
passées, 65% des personnes ont préféré écouter les présentations sur
Python. En supposant que les préférences de la population n'ont pas
changé, quelle est la probabilité que la salle Python reste en-dessous
de sa capacité d'accueil ?

   >>> n = 750             # Sample size
   >>> p = 0.65            # Preference for Python
   >>> q = 1.0 - p         # Preference for Ruby
   >>> k = 500             # Room capacity

   >>> # Approximation using the cumulative normal distribution
   >>> from math import sqrt
   >>> round(NormalDist(mu=n*p, sigma=sqrt(n*p*q)).cdf(k + 0.5), 4)
   0.8402

   >>> # Solution using the cumulative binomial distribution
   >>> from math import comb, fsum
   >>> round(fsum(comb(n, r) * p**r * q**(n-r) for r in range(k+1)), 4)
   0.8402

   >>> # Approximation using a simulation
   >>> from random import seed, choices
   >>> seed(8675309)
   >>> def trial():
   ...     return choices(('Python', 'Ruby'), (p, q), k=n).count('Python')
   >>> mean(trial() <= k for i in range(10_000))
   0.8398

Les lois normales interviennent souvent en apprentissage automatique.

Wikipedia has a nice example of a Naive Bayesian Classifier. The
challenge is to predict a person's gender from measurements of
normally distributed features including height, weight, and foot size.

Nous avons à notre disposition un jeu de données d'apprentissage
contenant les mesures de huit personnes. On suppose que ces mesures
suivent une loi normale. Nous pouvons donc synthétiser les données à
l'aide de "NormalDist" :

   >>> height_male = NormalDist.from_samples([6, 5.92, 5.58, 5.92])
   >>> height_female = NormalDist.from_samples([5, 5.5, 5.42, 5.75])
   >>> weight_male = NormalDist.from_samples([180, 190, 170, 165])
   >>> weight_female = NormalDist.from_samples([100, 150, 130, 150])
   >>> foot_size_male = NormalDist.from_samples([12, 11, 12, 10])
   >>> foot_size_female = NormalDist.from_samples([6, 8, 7, 9])

Ensuite, nous rencontrons un nouvel individu dont nous connaissons les
proportions mais pas le sexe :

   >>> ht = 6.0        # height
   >>> wt = 130        # weight
   >>> fs = 8          # foot size

En partant d'une probabilité a priori de 50% d'être un homme ou une
femme, nous calculons la probabilité a posteriori comme le produit de
la probabilité antérieure et de la vraisemblance des différentes
mesures étant donné le sexe :

   >>> prior_male = 0.5
   >>> prior_female = 0.5
   >>> posterior_male = (prior_male * height_male.pdf(ht) *
   ...                   weight_male.pdf(wt) * foot_size_male.pdf(fs))

   >>> posterior_female = (prior_female * height_female.pdf(ht) *
   ...                     weight_female.pdf(wt) * foot_size_female.pdf(fs))

La prédiction finale est celle qui a la plus grande probabilité a
posteriori. Cette approche est appelée maximum a posteriori ou MAP :

   >>> 'male' if posterior_male > posterior_female else 'female'
   'female'
