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.

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.

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.

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

Exceções

Uma única exceção é definida:

exception statistics.StatisticsError

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