ppgrns-estatistica 0.3.0

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
  • 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.
• 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, 'remax')
ef.mediana(dados, ['remin', 'remax'])
ef.moda(dados, 'remax')

# 3. Ver dispersão
ef.desviopadrao(dados, 'remax')
ef.coeficientevariacao(dados, ['remin', 'remax'])

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

# 5. Gerar gráficos
ef.boxplot(dados, 'remin', 'remax', titulo="Análise de Remuneração")
ef.histograma(dados, 'remax', numerocolunas=10)

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, 'remax')
ef.mediana(dados, ['remin', 'remax'])
ef.moda(dados)                            # moda de todas as colunas numéricas

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

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

ef.limiteinferior(dados, 'remax')         # Q1 − 1.5·IQR
ef.limitesuperior(dados, 'remax')         # 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, 'remax')
ef.variancia(dados, 'remax')                   # amostral (ddof=1) por padrão
ef.variancia(dados, 'remax', amostral=False)   # populacional (ddof=0)
ef.desviopadrao(dados, 'remax')
ef.coeficientevariacao(dados, ['remin', 'remax'])

ef.iqr(dados, 'remax')

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

As funções assimetria e curtose imprimem uma interpretação didática do resultado:

--- Assimetria (Skewness) ---
remin: 1.2340 -> Forte (Positiva/Direita)
   └─ A distribuição é altamente inclinada.

Inferência estatística

# Intervalo de confiança para a média
ef.intervaloconfianca(dados, 'remax', 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, 'remax', margem=100, 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:

--- Intervalo de Confiança — remax ---
  Tamanho amostral (n)            :         30
  Média amostral (x̄)             :    97.1778
  Desvio padrão amostral (s)      :    13.5001
  Nível de confiança              :      95.0%
  Distribuição utilizada          : t de Student
  Graus de liberdade (ν)          :         29
  Valor crítico t(0.025; 29)      :     2.0452
  Erro Padrão                     :     2.4648
  Margem de Erro (ME)             :     5.0410

  IC 95% = [ 92.1368  ;  102.2188 ]
  → Com 95% de confiança, a média populacional de 'remax'
    está entre 92.137 e 102.219.

Gráficos

Boxplot

ef.boxplot(
    dados, 'remin', 'remax',
    titulo="Análise de Remuneração",
    cores=['lightblue', 'lightgreen'],
    metodos=['exc', 'inc'],
    salvar='meu_boxplot',       # salva como meu_boxplot.png
)

Os boxplots usam Q1, mediana, Q3 e limites calculados pelo próprio pacote (e não pela convenção interna do matplotlib), garantindo coerência com os resultados mostrados pelas funções quartil, limiteinferior e limitesuperior.

Histograma

ef.histograma(
    dados, 'remax',
    numerocolunas=10,           # quantidade de classes (bins)
    cor='steelblue',
    titulo="Distribuição de Remuneração",
    salvar='distribuicao',
)

Se numerocolunas não for informado, a biblioteca escolhe automaticamente (regra de Sturges/Freedman-Diaconis). A rotação dos rótulos do eixo X também é ajustada dinamicamente conforme o número de classes.

Interativo (Jupyter / Colab)

ef.icinterativo(dados, 'remax')

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 que o aluno veja como o IC "encolhe" conforme n aumenta — e como a distribuição muda de t para Z quando n > 30.

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.

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:

m = ef.media(dados, 'remax', mostrar=False)
print(m['remax'])

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

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. Posição do k-ésimo percentil: k·(n+1)/100.
• 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 (e consequentemente os limites de outliers).

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. Nessa situação, a teoria estatística manda usar a distribuição t de Student, independentemente de n.

Se você realmente conhece σ (por exemplo, porque é um dado histórico validado), 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 rodados pelo terminal, 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.