ppgrns-estatistica 0.1.14

Biblioteca de suporte estatístico para o PPGRNS - UTFPR

ppgrns_estatistica

Biblioteca Python de apoio estatístico em português, desenvolvida para alunos do Programa de Pós-Graduação em Recursos Naturais e Sustentabilidade (PPGRNS — UTFPR).

Foi pensada para quem não tem experiência com programação: as funções têm nomes em português, aceitam planilhas reais (com vírgula decimal, espaços e caracteres invisíveis que vêm do Excel), imprimem resultados diretamente no terminal e ainda retornam os valores caso você queira usá-los em cálculos posteriores.

---

📑 Sumário

• Funcionalidades principais
• Instalação
• Uso básico
• Guia por módulo
  • Carregamento de dados
  • Medidas de posição
  • Medidas de dispersão e forma
  • Inferência estatística
  • Testes de hipótese (teste t)
  • Normalidade, ANOVA e Tukey
  • Gráficos
  • Interativo (Jupyter / Colab)
• Referência completa de funções
• Perguntas frequentes (FAQ)
• Autoria e licença

---

🚀 Funcionalidades principais

• Carregamento inteligente de arquivos .xlsx e .ods, detectando automaticamente se você está no Google Colab (abre botão de upload) ou no PC (abre janela de seleção).
• Limpeza automática na leitura: remove caracteres invisíveis (\u200b), converte vírgula decimal em ponto e padroniza nomes de colunas em minúsculas, tudo sem você precisar pensar nisso.
• Medidas de posição: média, mediana, moda, quartis, percentis e limites para detecção de outliers.
• Medidas de dispersão e forma: amplitude, variância, desvio padrão, coeficiente de variação, IQR, assimetria e curtose — essas duas últimas com classificação didática automática impressa no terminal.
• Inferência estatística: intervalos de confiança para a média (t de Student ou Z) e cálculo de tamanho amostral mínimo.
• Testes de hipótese: teste t para uma amostra, duas amostras independentes e amostras pareadas.
• ANOVA e comparação de médias: teste de normalidade de Shapiro-Wilk, ANOVA para DIC e DBC, e teste de Tukey com letras de agrupamento.
• Gráficos personalizáveis: boxplots e histogramas, com opção de salvar como .png.
• Explorador interativo de intervalos de confiança (Jupyter / Colab), com sliders para o aluno visualizar como n e o nível de confiança afetam o IC.

---

📦 Instalação

No computador local

pip install ppgrns_estatistica

No Google Colab

!pip install ppgrns_estatistica

Com suporte a gráficos interativos (opcional)

pip install "ppgrns_estatistica[interativo]"

As dependências principais (pandas, numpy, scipy, matplotlib, openpyxl, odfpy) são instaladas automaticamente.

---

🛠 Uso básico

import ppgrns_estatistica as ef

# 1. Carregar os dados (abre upload no Colab ou janela no PC)
dados = ef.carregardados()

# 2. Ver medidas de posição
ef.media(dados, 'od')
ef.mediana(dados, ['riqueza', 'biomassa'])

# 3. Ver dispersão
ef.desviopadrao(dados, 'od')
ef.coeficientevariacao(dados, 'od')

# 4. Testar normalidade
ef.shapiro(dados, 'od')

# 5. Construir um intervalo de confiança
ef.intervaloconfianca(dados, 'od', confianca=0.95)

# 6. Teste t
ef.testet_uma(dados, 'od', mu0=6.0)
ef.testet_duas(dados, 'riqueza', grupo='habitat')
ef.testet_pareado(dados, 'nitrogenio_antes', 'nitrogenio_depois')

# 7. ANOVA e Tukey
ef.anova(dados, 'nitrogenio', 'uso')
ef.tukey(dados, 'nitrogenio', 'uso')

# 8. Gráficos
ef.boxplot(dados, 'riqueza', titulo="Riqueza por Habitat")
ef.histograma(dados, 'od', numerocolunas=8)

Todas as funções aceitam as mesmas formas de chamada: ef.funcao(df, 'col'), ef.funcao(df, 'c1', 'c2') ou ef.funcao(df, ['c1', 'c2']).

---

📚 Guia por módulo

Carregamento de dados

dados = ef.carregardados()

A função detecta o ambiente automaticamente. No Colab abre a interface de upload; no PC abre a janela do sistema operacional. Suporta .xlsx e .ods.

Ao carregar, a biblioteca já faz a limpeza: nomes de colunas ficam em minúsculas sem acentos invisíveis, e valores numéricos que vieram como texto (comum quando a planilha usa vírgula decimal) são convertidos automaticamente.

Também está disponível um conversor utilitário de CSV para XLSX:

ef.csv_para_xlsx('dados.csv', 'dados.xlsx')
ef.csv_para_xlsx('dados_br.csv', 'dados.xlsx', sep=';', encoding='latin1')

Medidas de posição

ef.media(dados, 'od')
ef.mediana(dados, ['riqueza', 'biomassa'])
ef.moda(dados)                              # moda de todas as colunas numéricas

ef.quartil(dados, 'od', quartil=1)          # Q1
ef.quartil(dados, 'od', quartil=3, metodo='inc')   # Q3 método inclusivo

ef.percentil(dados, 'od', percentil=90)

ef.limiteinferior(dados, 'od')              # Q1 − 1.5·IQR
ef.limitesuperior(dados, 'od')              # Q3 + 1.5·IQR

A função moda identifica automaticamente se a distribuição é unimodal, bimodal, trimodal, multimodal ou amodal, informando também a frequência do valor mais comum.

Os quartis, percentis e limites aceitam dois métodos:

• 'exc' (padrão) — método exclusivo, equivalente ao PERCENTIL.EXC do Excel (Weibull).
• 'inc' — método inclusivo, equivalente ao PERCENTIL.INC do Excel (interpolação linear).

Medidas de dispersão e forma

ef.amplitude(dados, 'od')
ef.variancia(dados, 'od')                    # amostral (ddof=1) por padrão
ef.variancia(dados, 'od', amostral=False)    # populacional (ddof=0)
ef.desviopadrao(dados, 'od')
ef.coeficientevariacao(dados, ['od', 'riqueza'])

ef.iqr(dados, 'od')

ef.assimetria(dados, 'od')    # classifica: Simétrica / Moderada / Forte
ef.curtose(dados, 'od')       # classifica: Meso / Lepto / Platicúrtica

Inferência estatística

# Intervalo de confiança para a média
ef.intervaloconfianca(dados, 'od', confianca=0.95)

# Com sigma populacional conhecido (usa Z em vez de t)
ef.intervaloconfianca(dados, 'ph', sigma=0.3, confianca=0.99)

# Tamanho amostral mínimo para uma margem de erro desejada
ef.tamanhominimo(dados, 'od', margem=0.3, confianca=0.95)

Por padrão, o IC usa a distribuição t de Student (σ populacional desconhecido). Se você passar sigma, a função usa a Normal (Z). Em qualquer caso, o relatório completo é impresso no terminal.

Testes de hipótese (teste t)

Uma amostra vs. valor de referência

Compara a média de um grupo com um valor fixo conhecido (padrão legal, valor histórico, meta):

ef.testet_uma(dados, 'od', mu0=6.0)
ef.testet_uma(dados, 'ph', mu0=7.0, alpha=0.01)

Duas amostras independentes

Compara as médias de dois grupos coletados de forma independente. Aceita duas formas:

# Forma 1 — duas colunas separadas
ef.testet_duas(dados, 'riqueza_mata', 'riqueza_pastagem')

# Forma 2 — coluna resposta + coluna de grupo (exatamente 2 níveis)
ef.testet_duas(dados, 'riqueza', grupo='habitat')

# Variâncias diferentes (teste de Welch)
ef.testet_duas(dados, 'biomassa', grupo='uso', variancia_igual=False)

Amostras pareadas

Compara duas medições feitas na mesma unidade experimental (antes/depois, dois momentos no mesmo ponto):

ef.testet_pareado(dados, 'nitrogenio_antes', 'nitrogenio_depois')
ef.testet_pareado(dados, 'sp_antes', 'sp_depois', alpha=0.01)

Os dados para o teste pareado devem estar em duas colunas separadas, uma para cada momento. Se estiverem em formato longo, use pivot_table antes de chamar a função.

Todas as funções de teste t imprimem a estatística $t$, os graus de liberdade, o $p$-valor e a conclusão em linguagem clara.

Normalidade, ANOVA e Tukey

Teste de Shapiro-Wilk

Verifica o pressuposto de normalidade antes de aplicar o teste t ou a ANOVA:

ef.shapiro(dados, 'od')
ef.shapiro(dados, 'riqueza_mata', 'riqueza_pastagem')
ef.shapiro(dados, ['nitrogenio', 'fosforo'], alpha=0.01)

A função imprime a estatística $W$, o $p$-valor e a conclusão:

• p > alpha → normalidade não rejeitada, pode prosseguir.
• p ≤ alpha → dados não normais, considerar transformação ou teste não-paramétrico.

Para $n > 50$, o Teorema do Limite Central já garante aproximação Normal para as médias. O $p$-valor é calculado pela versão de Royston (1992).

ANOVA

Compara as médias de três ou mais grupos simultaneamente, controlando o erro tipo I:

# DIC — Delineamento Inteiramente Casualizado
ef.anova(dados, 'nitrogenio', 'uso')

# DBC — Delineamento em Blocos ao Acaso
ef.anova(dados, 'biomassa', 'qualidade', bloco='rio')

# Com nível de significância diferente
ef.anova(dados, 'riqueza', 'habitat', alpha=0.01)

A função imprime a tabela ANOVA completa com SQ, GL, QM, F, F crítico e p-valor para cada fonte de variação. Para o DBC, testa também a significância dos blocos e informa se o uso do DBC foi acertado.

Tukey HSD

Identifica quais pares de tratamentos diferem significativamente após uma ANOVA significativa:

ef.tukey(dados, 'nitrogenio', 'uso')
ef.tukey(dados, 'biomassa', 'qualidade', bloco='rio')

Imprime a DMS (Diferença Mínima Significativa), a tabela de comparações par a par e as letras de agrupamento (grupos que compartilham a mesma letra não diferem entre si).

Gráficos

Boxplot

ef.boxplot(
    dados, 'riqueza_mata', 'riqueza_pastagem',
    titulo="Riqueza por Habitat",
    cores=['lightblue', 'lightgreen'],
    metodos=['exc', 'inc'],
    salvar='boxplot_riqueza',       # salva como boxplot_riqueza.png
)

Os boxplots usam Q1, mediana, Q3 e limites calculados pelo próprio pacote, garantindo coerência com os resultados das funções quartil, limiteinferior e limitesuperior.

Histograma

ef.histograma(
    dados, 'od',
    numerocolunas=8,
    cor='steelblue',
    titulo="Distribuição do Oxigênio Dissolvido",
    salvar='histograma_od',
)

Interativo (Jupyter / Colab)

ef.icinterativo(dados, 'od')

Exibe um painel com sliders para o tamanho amostral (n) e um dropdown de confiança (90%, 95%, 99%). O gráfico é recalculado em tempo real, permitindo visualizar como o IC "encolhe" conforme n aumenta.

Requer ipywidgets (instale com pip install "ppgrns_estatistica[interativo]").

---

📋 Referência completa de funções

Carregamento

Função	Descrição
carregardados()	Abre o seletor de arquivos e retorna um DataFrame limpo.
csv_para_xlsx(caminho_csv, caminho_xlsx, sep=',', encoding='utf-8')	Converte um CSV em XLSX.

Posição

Função	Principais parâmetros
media(dados, *colunas, mostrar=True)	—
mediana(dados, *colunas, mostrar=True)	—
moda(dados, *colunas, mostrar=True)	Retorna dict com modas, frequencia e tipo.
quartil(dados, *colunas, quartil=1, metodo='exc', mostrar=True)	quartil: 1, 2 ou 3.
percentil(dados, *colunas, percentil=50, metodo='exc', mostrar=True)	percentil: 0–100.
limiteinferior(dados, *colunas, metodo='exc', mostrar=True)	Q1 − 1.5·IQR
limitesuperior(dados, *colunas, metodo='exc', mostrar=True)	Q3 + 1.5·IQR

Dispersão e forma

Função	Principais parâmetros
amplitude(dados, *colunas, mostrar=True)	Máximo − mínimo.
variancia(dados, *colunas, amostral=True, mostrar=True)	amostral=False para populacional.
desviopadrao(dados, *colunas, amostral=True, mostrar=True)	idem acima.
coeficientevariacao(dados, *colunas, mostrar=True)	(s / x̄) · 100.
iqr(dados, *colunas, metodo='exc', mostrar=True)	Q3 − Q1.
assimetria(dados, *colunas, mostrar=True)	Classifica automaticamente.
curtose(dados, *colunas, mostrar=True)	Classifica automaticamente.

Inferência

Função	Principais parâmetros
intervaloconfianca(dados, *colunas, confianca=0.95, sigma=None, mostrar=True)	sigma=None → t de Student; com valor → Z.
tamanhominimo(dados, *colunas, margem, confianca=0.95, sigma=None, mostrar=True)	margem é obrigatório.

Teste t

Função	Principais parâmetros
testet_uma(dados, coluna, mu0, alpha=0.05, mostrar=True)	mu0: valor de referência.
testet_duas(dados, coluna1, coluna2=None, grupo=None, alpha=0.05, variancia_igual=True, mostrar=True)	Aceita duas colunas ou coluna + grupo.
testet_pareado(dados, coluna_antes, coluna_depois, alpha=0.05, mostrar=True)	Dados em duas colunas separadas.

Normalidade, ANOVA e Tukey

Função	Principais parâmetros
shapiro(dados, *colunas, alpha=0.05, mostrar=True)	Retorna dict com W, p_valor e normal.
anova(dados, resposta, fator, bloco=None, alpha=0.05, mostrar=True)	bloco=None → DIC; com valor → DBC.
tukey(dados, resposta, fator, bloco=None, alpha=0.05, mostrar=True)	Retorna DMS, comparacoes e grupos.

Gráficos

Função	Principais parâmetros
boxplot(dados, *colunas, larguras, cores, metodos, titulo, horizontal, vertical, qualidade, tamanhohorizontal, tamanhovertical, salvar)	Listas (larguras, cores, metodos) devem ter tamanho igual ao número de colunas.
histograma(dados, *colunas, numerocolunas, cor, titulo, vertical, qualidade, tamanhohorizontal, tamanhovertical, salvar)	Plota a primeira coluna informada.
icinterativo(dados=None, coluna=None)	Requer Jupyter/Colab e ipywidgets.

---

❓ Perguntas frequentes (FAQ)

Minha planilha usa vírgula decimal (ex: 3,14). Preciso converter antes?

Não. A função carregardados() já faz essa conversão automaticamente. Valores que estavam como texto ("3,14") viram números (3.14) durante a leitura.

Posso passar várias colunas de uma vez?

Sim. Todas as funções aceitam três formatos equivalentes:

ef.media(dados, 'col1')
ef.media(dados, 'col1', 'col2')
ef.media(dados, ['col1', 'col2'])

Se você não passar nenhuma coluna, a função aplica o cálculo a todas as colunas numéricas do DataFrame.

Como salvar o resultado em uma variável em vez de só imprimir?

Use mostrar=False para suprimir a impressão, e atribua o retorno a uma variável:

r = ef.anova(dados, 'nitrogenio', 'uso', mostrar=False)
print(r['tratamento']['F'])

As funções retornam pd.Series (posição, dispersão) ou dict aninhado (inferência, testes, ANOVA).

Qual é a diferença entre `metodo='exc'` e `metodo='inc'`?

São dois métodos de interpolação de quantis:

• exc (exclusivo, Weibull): equivale ao PERCENTIL.EXC do Excel e ao padrão de várias referências estatísticas.
• inc (inclusivo, linear): equivale ao PERCENTIL.INC do Excel, ao numpy.percentile padrão e ao pandas.quantile padrão.

Em amostras grandes, a diferença é pequena. Em amostras pequenas, pode afetar valores de Q1 e Q3.

Qual a diferença entre `testet_duas` com duas colunas e com grupo?

As duas formas produzem o mesmo teste — a diferença é apenas na estrutura dos dados:

• Duas colunas: cada grupo está em uma coluna separada. Ex: ef.testet_duas(dados, 'riqueza_mata', 'riqueza_pastagem').
• Coluna + grupo: todos os valores estão em uma coluna e outra coluna indica o grupo. Ex: ef.testet_duas(dados, 'riqueza', grupo='habitat'). A coluna de grupo deve ter exatamente 2 níveis.

Preciso rodar o Shapiro-Wilk antes de toda ANOVA?

Sim, é recomendado. O Shapiro-Wilk testa o pressuposto de normalidade, que é exigido tanto pelo teste t quanto pela ANOVA. Use ef.shapiro em cada grupo antes de ef.anova. Se a normalidade for rejeitada, considere transformação dos dados ou use Kruskal-Wallis como alternativa não-paramétrica.

Quando usar DIC e quando usar DBC?

• DIC (bloco=None): quando as unidades experimentais são homogêneas entre si e não há fonte de variação conhecida que precise ser controlada.
• DBC (bloco='nome_da_coluna'): quando existe uma fonte de variação conhecida (ex: diferentes rios, tipos de solo, encostas) que pode mascarar o efeito do tratamento. O DBC remove essa variação do resíduo, tornando o teste mais sensível.

Por que `intervaloconfianca` usa t de Student por padrão, e não Z?

Porque quase sempre o desvio padrão populacional (σ) é desconhecido na prática — só conhecemos o desvio amostral s. Se você realmente conhece σ, passe sigma=valor para a função e ela usará a Normal (Z).

A função `icinterativo` não funciona no meu script Python normal.

É esperado: icinterativo só funciona em ambientes com ipywidgets ativo, ou seja, em Jupyter Notebook, JupyterLab ou Google Colab. Em scripts .py, use intervaloconfianca() em vez disso.

O que significa "moda: Amodal"?

Significa que nenhum valor se repetiu na coluna — todos são únicos. Nesse caso, não faz sentido falar em moda, e a biblioteca reporta explicitamente a situação em vez de retornar um valor enganoso.

Posso usar essa biblioteca fora do PPGRNS?

Claro! A biblioteca foi desenhada pensando no PPGRNS, mas as funções são genéricas e funcionam com qualquer conjunto de dados tabulares.

---

👤 Autoria e licença

Desenvolvido por Evandro A. Nakajima para o Programa de Pós-Graduação em Recursos Naturais e Sustentabilidade (PPGRNS — UTFPR).

Sugestões, correções e contribuições são bem-vindas.