9.7. "statistics" --- Funções estatísticas
******************************************

Novo na versão 3.4.

**Código Fonte:** Lib/statistics.py

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

Este módulo fornece funções para calcular estatísticas de dados
numéricos (com valor "Real")

Nota:

  A não ser que marcado explicitamente o contrário, essas funções
  suportam valores dos tipos "int", "float", "decimal.Decimal" e
  "fractions.Fraction". O uso com outros tipos (independente de serem
  numéricos ou não) ainda não é suportado. O mesmo vale para tipos
  mistos, cujo comportamento dependerá da implementação. Se os seus
  dados de entrada possuem diversos tipos, talvez você consiga usar da
  função "map()" para garantir resultados consistentes. Por exemplo
  "map(float, input_data)" converterá os elementos de "input_data"
  para float.


9.7.1. Médias e medidas de valor central
========================================

Essas funções calculam a média ou o valor típico de uma população ou
amostra.

+-------------------------+-----------------------------------------------+
| "mean()"                | Média aritmética dos dados.                   |
+-------------------------+-----------------------------------------------+
| "harmonic_mean()"       | Média harmônica dos dados.                    |
+-------------------------+-----------------------------------------------+
| "median()"              | Mediana (valor do meio) dos dados.            |
+-------------------------+-----------------------------------------------+
| "median_low()"          | Mediana inferior dos dados.                   |
+-------------------------+-----------------------------------------------+
| "median_high()"         | Mediana superior dos dados.                   |
+-------------------------+-----------------------------------------------+
| "median_grouped()"      | Mediana, ou o 50º percentil dos dados         |
|                         | agrupados.                                    |
+-------------------------+-----------------------------------------------+
| "mode()"                | Moda (valor mais comum) de dados discretos.   |
+-------------------------+-----------------------------------------------+


9.7.2. Medidas de espalhamento
==============================

Essas funções calculam o quanto a população ou amostra tendem a
desviar dos valores típicos ou médios.

+-------------------------+-----------------------------------------------+
| "pstdev()"              | Desvio padrão de dados populacionais.         |
+-------------------------+-----------------------------------------------+
| "pvariance()"           | Variância de dados populacionais.             |
+-------------------------+-----------------------------------------------+
| "stdev()"               | Desvio padrão de dados amostrais.             |
+-------------------------+-----------------------------------------------+
| "variance()"            | Variância de dados amostrais.                 |
+-------------------------+-----------------------------------------------+


9.7.3. Detalhes da função
=========================

Nota: as funções não exigem que os dados estejam ordenados. No
entanto, para conveniência do leitor, a maioria dos exemplos mostrará
sequências ordenadas.

statistics.mean(data)

   Retorna a média aritmética de *data*, que pode ser uma sequência ou
   um iterador

   A média aritmética é a soma dos dados dividida pela quantidade. É
   comumente chamada apenas de "média", apesar de ser uma das diversas
   médias matemáticas. Ela representa uma medida da localização
   central dos dados

   Se *data* for vazio, uma exceção do tipo "StatisticsError" será
   lançada.

   Alguns exemplos de uso:

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

   Nota:

     A média é bastante afetada por valores discrepantes e não é uma
     estimativa muito robusta da localização central. Ou seja, a média
     não é necessariamente um ponto que ocorre nos dados. Para medidas
     mais robustas, apesar de menos eficientes, da localização
     central, veja "median()" e "mode()". Nesse caso "eficiência" se
     refere à eficiência estatística ao invés de computacional.A média
     de uma amostra nos dá uma estimativa não enviesada da média
     populacional verdadeira. Isso significa que obtendo a média de
     todas as amostras, "mean(amostra)" converge para a média da
     população como um todo. Se *data*  representa a população inteira
     ao invés de uma amostra, então "mean(data)" é equivalente a
     calcular a média verdadeira da população, comumente denotada por
     μ.

statistics.harmonic_mean(data)

   Retorna a média harmônica de *data*, que deve ser uma sequência ou
   um iterador de números reais.

   A média harmônica, as vezes chamada de média subcontrária é a
   recíproca da média aritmética, calculada por "mean()", dos
   recíprocos dos dados. Por exemplo, a média harmônica dos valores
   *a*, *b* e *c* será equivalente a "3/(1/a + 1/b + 1/c)".

   A média harmônica, como toda média, é uma medida da localização
   central dos dados. Ela costuma ser apropriada quanto estamos
   tirando média de quantidades que representam taxas ou razões, como
   velocidade. Por exemplo:

   Suponha que um investidor compre um valor igual de ações em cada
   uma de três companhias diferentes com uma razão P/L (preço/lucro)
   de 2,5, 3 e 10. Qual é a razão P/L média da carteira de
   investimentos desse investidor?

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

   Usando a média aritmética, teríamos um valor de aproximadamente
   5.167, que é muito alto.

   "StatisticsError" é levantado se *data* for vazio ou se qualquer
   elemento for menor que zero.

   Novo na versão 3.6.

statistics.median(data)

   Retorna a mediana (o valor do meio) de dados numéricos, usando o
   método comum de "média entre os dois do meio". Se *data* for vazio,
   "StatisticsError" é levantado. *data* pode ser uma sequência ou um
   iterador.

   A mediana é uma medida robusta da localização central e é menos
   afetada pela presença de valores muito discrepantes nos seus dados.
   Quando o número de elementos nos dados for ímpar, o valor que fica
   no meio da sequência é retornado:

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

   Quando o número de elementos for par, a mediana é calculada tomando
   a média entre os dois valores no meio:

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

   Isso serve quando seus dados forem discretos e você não se importa
   que a média possa não ser um valor que de fato ocorre nos seus
   dados.

   Caso os seus dados sejam ordinais (ou seja, suportam operações de
   ordenação) mas não são numéricos (não suportam adição), você deve
   usar "median_low()" ou "median_high()" no lugar.

   Ver também: "median_low()", "median_high()", "median_grouped()"

statistics.median_low(data)

   Retorna a mediana inferior de dados numéricos. Se *data* for vazio,
   "StatisticsError" é levantado. *data* pode ser uma sequência ou um
   iterador.

   A mediana inferior sempre é um membro do conjunto de dados. Quando
   o número de elementos for ímpar, o valor intermediário é retornado.
   Se houver um número par de elementos, o menor entre os dois valores
   centrais é retornado.

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

   Use "median_low()" quando seus dados são discretos e você prefere
   que a mediana seja um valor que de fato existe nos seus dados ao
   invés de um valor interpolado.

statistics.median_high(data)

   Retorna a mediana superior de dados numéricos. Se *data* for vazio,
   "StatisticsError" é levantado. *data* pode ser uma sequência ou um
   iterador.

   A mediana superior sempre é um membro do conjunto de dados. Quando
   o número de elementos for ímpar, o valor intermediário é retornado.
   Se houver um número par de elementos, o maior entre os dois valores
   centrais é retornado.

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

   Use "median_high()" quando seus dados são discretos e você prefere
   que a mediana seja um valor que de fato existe nos seus dados ao
   invés de um valor interpolado.

statistics.median_grouped(data, interval=1)

   Retorna a media de dados contínuos agrupados, calculada como o 50º
   percentil, usando de interpolação. Se *data* for vazio,
   "StatisticsError" é levantado. *data* pode ser uma sequência ou um
   iterador.

      >>> median_grouped([52, 52, 53, 54])
      52.5

   No exemplo a seguir, os dados estão arredondados de forma que cada
   valor representa o ponto intermediário de classes de dados. Isto é,
   1 é o meio da classe 0.5--1.5, 2 é o meio de 1.5--2.5, 3 é o meio
   de 2.5--3.5, etc. Com os dados oferecidos, o valor do meio cai em
   algum ponto na classe 3.5--4.5 e interpolação é usada para
   estimá-lo:

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

   O argumento opcional *interval* representa a classe de intervalo e
   tem como valor padrão 1. Mudar a classe de intervalo irá mudar a
   interpolação:

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

   Essa função não checa se os pontos de dados estão separados por uma
   distância que seja ao menos igual à *interval*

   **CPython implementation detail:** Em algumas circunstâncias
   "median_grouped()" pode forçar os pontos de dados a serem floats.
   Esse comportamento provavelmente irá mudar no futuro.

   Ver também:

     * "Statistics for the Behavioral Sciences", Frederick J Gravetter
       and Larry B Wallnau (8th Edition).

     * Calculating the median.

     * A função SSMEDIAN
       <https://help.gnome.org/users/gnumeric/stable/gnumeric.html
       #gnumeric-function-SSMEDIAN>`_ na planilha Gnome Gnumeric,
       incluindo essa discussão <https://mail.gnome.org/archives
       /gnumeric-list/2011-April/msg00018.html>`_.

statistics.mode(data)

   Retorna o valor mais comum em dados discretos ou nominais. A moda -
   quando ela existe - é o valor mais típico e é uma medida robusta da
   localização central

   Se *data* for vazio ou se não tem exatamente um valor mais comum,
   "StatisticsError" é levantado.

   "mode" assume que os dados são discretos e retorna um único valor.
   Esse é o tratamento padrão do conceito de moda normalmente ensinado
   nas escolas:

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

   A moda é única no sentido que é a única medida estatística que
   também se aplica a dados nominais (não numéricos):

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

statistics.pstdev(data, mu=None)

   Retorna o desvio padrão da população. Ou seja, a raíz quadrada da
   variância da população. Veja os argumentos e outros detalhes em
   "pvariance()".

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

statistics.pvariance(data, mu=None)

   Retorna a variância populacional de *data*, que deve ser um
   iterável não vazio de números reais. A variância, o segundo Momento
   Estatístico sobre a média é uma medida da variabilidade
   (espalhamento ou dispersão) dos dados. Uma variância grande indica
   que os dados são espalhados; uma variância menor indica que os
   dados estão agrupado em volta da média.

   Se o segundo argumento opcional *mu* for dado, ele deve representar
   a média de *data*. Se ele não estiver presente ou for "None", a
   média será automaticamente calculada.

   Use essa função para calcular a variância de toda a população. Para
   estimar a variância de uma amostra, a função "variance()" costuma
   ser uma escolha melhor.

   Causa "StatisticsError" se *data* for vazio.

   Exemplos:

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

   Se você já calculou a média dos seus dados, você pode passar o
   valor no segundo argumento opcional *mu* para evitar recálculos:

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

   Essa função não tentar verificar que você passou a média verdadeira
   em *mu*. Se você passar um valor arbitrário para *mu*, poderá ter
   resultados inválidos ou impossíveis.

   Decimais e frações são suportadas:

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

   Nota:

     Quando os dados de entrada representarem toda a população, ele
     retorna a variância populacional σ². Se em vez disso, amostras
     forem usadas, então a variância amostral enviesada s², também
     conhecida como variância com N graus de liberdade é retornada.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)

   Retorna o desvio padrão amostral (a raiz quadrada da variância da
   amostra). Veja "variance()" para argumentos e outros detalhes.

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

statistics.variance(data, xbar=None)

   Retorna a variância amostral de *data*, que deve ser um iterável
   com pelo menos dois números reais. Variância, ou o segundo momento
   estatístico sobre a média, é uma medida de variabilidade
   (espalhamento ou dispersão) dos dados. Uma variância grande indica
   que os dados são espalhados, uma variância menor indica que os
   dados estão agrupados em volta da média.

   Se o segundo argumento opcional *xbar* for dado, ele deve
   representar a média de *data*. Se ele não estiver presente ou for
   "None" (valor padrão), a média é automaticamente calculada.

   Use essa função quando seus dados representarem uma amostra da
   população. Para calcular a variância de toda população veja
   "pvariance()".

   Levanta a exceção "StatisticsError" se *data* tiver menos do que
   dois valores.

   Exemplos:

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

   Se você já calculou a média dos seus dados, você pode passar o
   valor no segundo argumento opcional *xbar* para evitar recálculos:

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

   Essa função não verifica se você passou a média verdadeira como
   *xbar*. Usando valores arbitrários para *xbar* pode levar a
   resultados inválidos ou impossíveis.

   Valores decimais e fracionários são suportados.

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

   Nota:

     Essa é a variância amostral s² com a correção de Bessel, também
     conhecida como variância com N-1 graus de liberdade. Desde que os
     pontos de dados sejam representativos (por exemplo, independentes
     e distribuídos de forma idêntica), o resultado deve ser uma
     estimativa não enviesada da verdadeira variação populacional.Caso
     você de alguma forma saiba a verdadeira média populacional μ você
     deveria passar para a função "pvariance()" como o parâmetro *mu*
     para pegar a variância da amostra.


9.7.4. Exceções
===============

Uma única exceção é definida:

exception statistics.StatisticsError

   Subclasse de "ValueError" para exceções relacionadas a
   estatísticas.
