Metadata-Version: 2.4
Name: ppgrns_estatistica
Version: 0.1.5
Summary: Biblioteca de suporte estatístico para o PPGRNS - UTFPR
Author: Evandro A. Nakajima
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: openpyxl
Requires-Dist: odfpy
Provides-Extra: interativo
Requires-Dist: ipywidgets; extra == "interativo"
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ppgrns_estatistica

[![PyPI version](https://img.shields.io/pypi/v/ppgrns_estatistica.svg)](https://pypi.org/project/ppgrns_estatistica/)
[![Python versions](https://img.shields.io/pypi/pyversions/ppgrns_estatistica.svg)](https://pypi.org/project/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](#-funcionalidades-principais)
- [Instalação](#-instalação)
- [Uso básico](#-uso-básico)
- [Guia por módulo](#-guia-por-módulo)
  - [Carregamento de dados](#carregamento-de-dados)
  - [Medidas de posição](#medidas-de-posição)
  - [Medidas de dispersão e forma](#medidas-de-dispersão-e-forma)
  - [Inferência estatística](#inferência-estatística)
  - [Gráficos](#gráficos)
  - [Interativo (Jupyter / Colab)](#interativo-jupyter--colab)
- [Referência completa de funções](#-referência-completa-de-funções)
- [Perguntas frequentes (FAQ)](#-perguntas-frequentes-faq)
- [Autoria e licença](#-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

```bash
pip install ppgrns_estatistica
```

### No Google Colab

```python
!pip install ppgrns_estatistica
```

### Com suporte a gráficos interativos (opcional)

```bash
pip install "ppgrns_estatistica[interativo]"
```

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

---

## 🛠 Uso básico

```python
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

```python
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:

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

### Medidas de posição

```python
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

```python
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

```python
# 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**

```python
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**

```python
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)

```python
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)

<details>
<summary><strong>Minha planilha usa vírgula decimal (ex: 3,14). Preciso converter antes?</strong></summary>

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.
</details>

<details>
<summary><strong>Posso passar várias colunas de uma vez?</strong></summary>

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

```python
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.
</details>

<details>
<summary><strong>Como salvar o resultado em uma variável em vez de só imprimir?</strong></summary>

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

```python
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).
</details>

<details>
<summary><strong>Qual é a diferença entre `metodo='exc'` e `metodo='inc'`?</strong></summary>

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).
</details>

<details>
<summary><strong>Por que `intervaloconfianca` usa t de Student por padrão, e não Z?</strong></summary>

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).
</details>

<details>
<summary><strong>A função `icinterativo` não funciona no meu script Python normal.</strong></summary>

É 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.
</details>

<details>
<summary><strong>O que significa "moda: Amodal"?</strong></summary>

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.
</details>

<details>
<summary><strong>Posso usar essa biblioteca fora do PPGRNS?</strong></summary>

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

---

## 👤 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.
