O módulo statistics calcula medidas descritivas sem dependências externas. A escolha da medida importa: uma única latência muito alta pode deslocar a média e representar mal o comportamento típico.

from statistics import fmean, median, quantiles

latencias_ms = [91, 105, 110, 118, 140, 420]

media = fmean(latencias_ms)
mediana = median(latencias_ms)
q1, q2, q3 = quantiles(latencias_ms, n=4)

print(media, mediana, q3)

fmean() retorna média em ponto flutuante, median() encontra o centro e quantiles() divide os dados. O terceiro quartil ajuda a observar a parte superior sem resumir tudo pelo máximo. Antes de calcular, trate valores ausentes e confirme a unidade.

Boas práticas

Diferencie população e amostra: pvariance() e pstdev() usam a população completa, enquanto variance() e stdev() estimam a partir de uma amostra. Não publique apenas uma média; informe tamanho do conjunto, período, dispersão e critérios de exclusão. Para dinheiro, avalie Decimal e regras de arredondamento do domínio.

Para análise tabular, avance para o guia de pandas. Se os dados forem arrays grandes, consulte NumPy em Python.

A documentação oficial do módulo statistics, consultada em 22 de julho de 2026, detalha a API e suas garantias.

Prepare os dados antes de resumir

Uma medida correta sobre dados ruins continua enganosa. Confirme unidade, período, origem e significado de cada observação. Remova valores ausentes por uma regra explícita. Valores NaN produzem resultados surpreendentes em funções que dependem de ordenação, portanto filtre-os antes.

from math import isnan
from statistics import fmean, median

brutos = [12.4, float("nan"), 13.1, 19.8]
validos = [valor for valor in brutos if not isnan(valor)]
print(fmean(validos), median(validos))

Não misture segundos com milissegundos nem observações de populações diferentes. Registre quantos valores foram descartados e por quê. Remover um outlier apenas porque ele muda a média oculta informação; investigue se é erro de medição ou evento real.

Média, mediana e moda

mean() preserva tipos numéricos compatíveis. fmean() converte o resultado para ponto flutuante e costuma ser rápida. A média usa toda a informação, mas é sensível a extremos. A mediana descreve o centro por posição e representa melhor muitos dados assimétricos, como renda e latência. Mostrar ambas pode revelar uma cauda que uma única medida esconderia.

mode() retorna uma moda, enquanto multimode() retorna todos os valores com maior frequência. Em medições contínuas, quase todos os números podem aparecer uma vez e a moda perde utilidade. Para categorias, a contagem absoluta também deve acompanhar a porcentagem.

População, amostra e dispersão

Dois conjuntos com a mesma média podem ter riscos muito diferentes. pvariance() e pstdev() descrevem a população completa observada. variance() e stdev() aplicam a correção usada para estimar a partir de uma amostra. A escolha depende do desenho da coleta, não do resultado que parece mais favorável.

from statistics import fmean, stdev

amostra = [18.2, 17.9, 18.5, 19.1, 17.7]
resumo = {
    "n": len(amostra),
    "media": fmean(amostra),
    "desvio_padrao": stdev(amostra),
}
print(resumo)

A variância fica na unidade ao quadrado; o desvio padrão volta à unidade original. Informe também n, pois uma dispersão calculada com poucas observações é instável.

Quantis e convenções

quantiles(dados, n=4) produz três cortes para quartis. Com n=100, produz 99 cortes internos associados a percentis. O argumento method define a interpolação. Os métodos exclusive e inclusive partem de convenções diferentes; documente a escolha ao comparar resultados com planilhas ou outras bibliotecas.

P95 de latência significa que aproximadamente 95% das observações ficam até aquele corte, não que toda requisição terá esse tempo. Percentis extremos calculados sobre uma amostra pequena sugerem precisão que os dados não sustentam. Informe janela, quantidade e método junto ao valor.

Tipos numéricos e precisão

Não misture Decimal e float sem uma política. Para dinheiro, Decimal preserva a representação decimal, mas arredondamento e regras contábeis continuam sendo decisões do domínio.

from decimal import Decimal
from statistics import mean

precos = [Decimal("19.90"), Decimal("20.10"), Decimal("20.00")]
media = mean(precos).quantize(Decimal("0.01"))
print(media)

Fraction também funciona em várias operações quando um resultado racional exato é útil. Mantenha o conjunto numericamente homogêneo e teste a função escolhida.

Relações entre variáveis

covariance() mede como duas variáveis mudam juntas. correlation() normaliza a associação em uma escala próxima de -1 a 1. Correlação não prova causalidade: outliers, tendência temporal ou uma terceira variável podem criar uma relação aparente.

linear_regression() ajusta uma reta simples e retorna inclinação e intercepto. Visualize os pontos e examine resíduos antes de interpretar. Uma reta pode resumir muito mal uma relação curva. Essas funções atendem exploração pequena, mas não substituem desenho experimental, intervalos de confiança ou modelos especializados.

Erros e casos extremos

Várias funções lançam StatisticsError quando recebem entrada vazia ou insuficiente. Valide na fronteira e escolha uma resposta coerente.

from statistics import StatisticsError, median

def mediana_ou_nulo(valores):
    try:
        return median(valores)
    except StatisticsError:
        return None

Decida se None, exceção ou ausência do campo representa melhor o caso. Retornar zero costuma ser incorreto, pois parece uma observação real. Iteradores também podem ser consumidos; materialize-os quando precisar calcular mais de uma medida sobre os mesmos dados.

Testes e comunicação

Teste conjuntos pares e ímpares, valores repetidos, negativos, extremos, um único item e entrada vazia. Use math.isclose() para resultados de ponto flutuante em vez de igualdade exata frágil. Nos testes de quantis, declare o método.

Ao publicar uma análise, inclua fonte, período, unidade, tamanho, exclusões e uma medida de dispersão. Um histograma ou boxplot pode revelar assimetria e grupos escondidos pelo resumo. Preserve dados brutos ou um processo reproduzível para auditoria.

Quando escolher outra ferramenta

statistics é excelente para iteráveis pequenos e scripts sem dependências. NumPy atende arrays grandes e vetorização; pandas adiciona rótulos, agrupamento e tratamento tabular; bibliotecas científicas oferecem inferência e modelos avançados. Troque por uma necessidade concreta, não porque uma média simples exija uma pilha maior.

O checklist final é curto: defina população ou amostra, limpe dados de forma documentada, escolha medidas compatíveis com a distribuição, informe quantidade e dispersão, registre o método de quantis e nunca transforme associação em causalidade.