O módulo statistics ganhou recursos modernos para análise de distribuições, e statistics.kde é um dos mais interessantes para quem precisa estimar uma curva de densidade a partir de uma amostra sem depender imediatamente de bibliotecas externas. Em vez de resumir os dados apenas com média, mediana ou desvio padrão, a estimativa de densidade por kernel mostra onde os valores se concentram, quais regiões têm pouca observação e se a distribuição parece ter um ou vários picos.
Este guia explica como usar statistics.kde no Python, como escolher a largura de banda, quais kernels estão disponíveis, como avaliar a função resultante e em quais situações a técnica é útil. A ideia é construir uma visão prática, mas também cuidadosa, porque uma curva suave pode parecer convincente mesmo quando foi calculada com parâmetros inadequados.
O que é estimativa de densidade por kernel
Uma estimativa de densidade por kernel, frequentemente abreviada como KDE, transforma uma coleção de observações em uma função contínua. Cada ponto da amostra recebe uma pequena curva ao redor de sua posição. A soma normalizada dessas curvas forma a estimativa final. O resultado lembra um histograma suavizado, mas sem depender de intervalos rígidos.
Imagine tempos de resposta medidos em milissegundos. Um histograma exige que você escolha faixas, como 0–50, 50–100 e 100–150. Pequenas mudanças nessas divisões podem alterar bastante a aparência. Com KDE, a decisão principal passa a ser a largura de banda, que controla quanto cada observação influencia os valores próximos.
Primeiro exemplo com statistics.kde
A função recebe uma sequência de números e um parâmetro h, que representa a largura de banda. Ela devolve outra função. Essa função pode ser chamada com qualquer ponto numérico para obter a densidade estimada.
from statistics import kde
amostra = [1.2, 1.5, 1.7, 2.0, 2.1, 2.2, 3.8, 4.0, 4.2]
densidade = kde(amostra, h=0.35)
for x in [1.0, 1.5, 2.0, 2.5, 3.0, 4.0]:
print(x, densidade(x))
Os valores retornados não são probabilidades isoladas. Eles representam densidade. Por isso, podem ultrapassar 1 em determinadas escalas. A probabilidade é obtida pela área sob a curva em um intervalo, não pelo valor em um único ponto.
Como interpretar a curva
Se você avaliar a função em muitos pontos ordenados, poderá desenhar uma curva. Regiões com valores altos indicam maior concentração relativa de observações. Regiões baixas indicam lacunas ou menor frequência. Na amostra anterior, é provável que apareça um grupo entre 1 e 2,2 e outro em torno de 4.
Essa capacidade de revelar múltiplos grupos é uma das vantagens do KDE. A média poderia sugerir um valor central próximo de 2,5, embora poucos dados realmente estejam ali. A densidade preserva melhor a estrutura da amostra.
A largura de banda é o parâmetro principal
O argumento h controla a suavização. Um valor muito pequeno produz uma curva cheia de picos, frequentemente acompanhando ruídos e pontos individuais. Um valor muito grande pode esconder estruturas importantes e fundir grupos diferentes.
from statistics import kde
valores = [10, 10.5, 11, 11.2, 14, 14.3, 15]
estreita = kde(valores, h=0.2)
equilibrada = kde(valores, h=0.8)
larga = kde(valores, h=2.0)
Não existe uma largura perfeita para todos os dados. A escolha depende da escala, do tamanho da amostra e da pergunta. Quando o objetivo é explorar, compare várias larguras. Quando o resultado será usado em decisão automatizada, valide o parâmetro com dados de teste e conhecimento do domínio.
Kernels disponíveis
O parâmetro kernel permite escolher a forma usada ao redor de cada observação. Entre as opções documentadas estão kernels como normal, logistic, sigmoid, rectangular, triangular, parabolic e outros. O kernel normal costuma ser uma escolha inicial intuitiva, mas kernels com suporte limitado podem ser úteis quando você deseja que observações distantes não contribuam.
normal = kde(amostra, h=0.35, kernel="normal")
triangular = kde(amostra, h=0.35, kernel="triangular")
Na prática, a largura de banda geralmente influencia mais o formato do que a escolha entre kernels razoáveis. Ainda assim, o kernel deve ser documentado para tornar a análise reproduzível.
Gerando pontos para visualização
O módulo retorna a função de densidade, mas não desenha o gráfico. Você pode criar uma grade de pontos e usar sua ferramenta de visualização preferida.
from statistics import kde
amostra = [1.2, 1.5, 1.7, 2.0, 2.1, 2.2, 3.8, 4.0, 4.2]
f = kde(amostra, h=0.35)
inicio = min(amostra) - 1
fim = max(amostra) + 1
passos = 200
xs = [inicio + i * (fim - inicio) / (passos - 1) for i in range(passos)]
ys = [f(x) for x in xs]
Os vetores xs e ys podem ser enviados ao Matplotlib, a uma API, a uma planilha ou a um componente web. Para uma introdução ao tratamento de sequências, veja também o artigo sobre itertools.pairwise no Python. Para somas progressivas e curvas acumuladas, consulte itertools.accumulate no Python.
Validação de dados antes do cálculo
Uma análise confiável começa antes do KDE. Remova ou trate valores ausentes, confirme unidades e investigue extremos. Misturar segundos e milissegundos, por exemplo, cria uma distribuição enganosa. Também é importante decidir se outliers são erros, eventos legítimos ou uma população diferente.
import math
from statistics import kde
brutos = [1.2, None, 1.5, float("nan"), 2.0, 2.1]
limpos = [x for x in brutos if isinstance(x, (int, float)) and math.isfinite(x)]
if len(limpos) < 2:
raise ValueError("Amostra insuficiente")
f = kde(limpos, h=0.3)
Para organizar validações e modelos mais robustos, o conteúdo sobre dataclasses.KW_ONLY no Python mostra como criar APIs explícitas. Já SimpleNamespace no Python ajuda a entender objetos leves para resultados exploratórios.
Comparando KDE e histograma
O histograma é excelente para contagens e comunicação direta. Ele mostra quantas observações caíram em cada faixa. KDE é melhor para visualizar uma forma contínua e comparar distribuições. Em muitos relatórios, usar ambos é mais informativo do que escolher apenas um.
Não trate o KDE como substituto absoluto do histograma. Uma curva muito suave pode ocultar que a amostra é pequena. Sempre informe o tamanho da amostra, a largura de banda e, quando possível, os pontos originais ou um histograma de apoio.
Amostras pequenas e limites
Com poucos pontos, a curva depende fortemente de cada observação. A estimativa continua calculável, mas sua interpretação deve ser prudente. KDE descreve a amostra; não prova que a população real possui exatamente aquele formato.
Outro limite é a fronteira. Quando os dados só podem ser positivos, como duração ou peso, kernels simétricos podem espalhar densidade abaixo de zero. Isso não significa que o Python criou valores observados negativos, mas mostra que a técnica padrão pode precisar de transformação ou correção de fronteira.
Uso em detecção de anomalias
Uma aplicação comum é marcar regiões de baixa densidade. Você calcula a densidade dos novos valores e compara com um limite definido a partir de dados históricos. Porém, isso exige cuidado: baixa densidade não significa automaticamente erro. Pode ser um evento raro e legítimo.
from statistics import kde
historico = [100, 102, 98, 101, 99, 103, 97, 100]
f = kde(historico, h=2.0)
novo = 118
score = f(novo)
if score < 0.001:
print("Valor incomum; revisar")
O limite deve ser calibrado com exemplos conhecidos. Em produção, registre o score, a versão dos dados e o parâmetro h. Isso facilita auditoria e evita decisões opacas.
Reprodutibilidade e testes
Como a função é determinística para a mesma amostra e configuração, você pode escrever testes simples. Verifique que a densidade é não negativa, que pontos próximos a grupos importantes têm valor maior que regiões distantes e que alterações de largura produzem o comportamento esperado.
def test_kde_destaca_regiao_da_amostra():
from statistics import kde
f = kde([0.0, 0.1, 0.2, 0.3], h=0.2)
assert f(0.15) > f(3.0)
assert f(0.15) >= 0
Não teste números de ponto flutuante com igualdade rígida sem necessidade. Prefira relações, tolerâncias e propriedades do resultado.
Quando usar bibliotecas externas
statistics.kde é excelente para scripts, ensino, protótipos e aplicações que desejam permanecer na biblioteca padrão. Projetos científicos maiores podem precisar de seleção automática de banda, KDE multidimensional, pesos por observação, integração numérica sofisticada ou gráficos prontos. Nesses casos, SciPy, NumPy, pandas, statsmodels e scikit-learn continuam relevantes.
A documentação oficial do Python descreve a API e os kernels disponíveis em statistics — Mathematical statistics functions. Para fundamentos estatísticos e interpretação, o material do NIST Engineering Statistics Handbook é uma referência confiável.
Boas práticas
Registre a versão do Python, porque o recurso depende de versões modernas. Normalize unidades, trate valores inválidos e preserve a amostra original. Compare mais de uma largura de banda, especialmente durante exploração. Não esconda o tamanho da amostra. Evite apresentar densidade como probabilidade pontual. Use limites de anomalia apenas depois de validação.
Também vale separar a etapa de preparação da etapa de avaliação. Uma função pode limpar os dados e outra construir a densidade. Essa divisão torna testes e manutenção mais simples. Para estruturar recursos e etapas de forma segura, veja contextlib.ExitStack no Python.
Conclusão
statistics.kde coloca uma ferramenta poderosa de análise de distribuição dentro da biblioteca padrão. Ela permite transformar amostras numéricas em funções contínuas, explorar concentrações, comparar grupos e criar scores simples. O principal desafio não é chamar a função, mas escolher e justificar a largura de banda, validar os dados e comunicar as limitações.
Comece com uma amostra pequena, avalie a função em uma grade e compare larguras diferentes. Depois, adicione testes, documentação e monitoramento. Assim, o KDE deixa de ser apenas uma curva bonita e passa a ser uma ferramenta estatística útil e responsável.
