exploradata 0.1.0__tar.gz

exploradata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anna Elisa Petersen Gatelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

exploradata-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: exploradata
+Version: 0.1.0
+Summary: Ferramentas simples e composáveis para exploração de DataFrames (EDA)
+Author-email: Anna Gatelli <anna.gatelli@bateleur.com.br>
+License: MIT
+Project-URL: Homepage, https://github.com/anna-gatelli/exploradata
+Keywords: eda,pandas,data-exploration,data-quality
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: numpy>=1.23
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# exploradata
+
+Ferramentas simples e composáveis para exploração de DataFrames pandas (EDA).
+
+Todas as funções **retornam DataFrames** — dá para filtrar, ordenar, exportar e encadear. Quando você só quer olhar, use `verbose=True` ou a função `profile()`.
+
+## Instalação
+
+```bash
+pip install git+https://github.com/anna-gatelli/exploradata.git
+```
+
+Ou, para desenvolvimento local:
+
+```bash
+git clone https://github.com/anna-gatelli/exploradata.git
+cd exploradata
+pip install -e ".[dev]"
+```
+
+## Uso rápido
+
+```python
+import pandas as pd
+import exploradata as xd
+
+df = pd.read_csv("dados.csv")
+
+# Relatório completo de uma vez
+report = xd.profile(df)
+
+# Ou função por função:
+xd.unique_values(df, "cidade")   # únicos com frequência e %
+xd.summary(df)                   # df.info() melhorado
+xd.missing(df)                   # nulos ranqueados
+xd.outliers(df)                  # outliers por IQR (ou method="zscore")
+xd.peek(df)                      # head + amostra aleatória + tail
+```
+
+## Funções
+
+### Visão geral
+| Função | O que faz |
+|---|---|
+| `summary(df)` | Tipo, nulos, únicos, cardinalidade e memória por coluna |
+| `peek(df, n=5)` | head + amostra aleatória + tail em um só DataFrame |
+| `detect_types(df)` | Detecta números, datas e booleanos "disfarçados" em colunas de texto |
+
+### Qualidade
+| Função | O que faz |
+|---|---|
+| `missing(df)` | Nulos por coluna (contagem e %), ranqueados |
+| `duplicates(df, subset=None)` | Linhas duplicadas, completas ou por chave |
+| `outliers(df, method="iqr")` | Outliers por IQR ou z-score nas numéricas |
+| `text_issues(df)` | Espaços extras e variações de capitalização que inflam os únicos |
+
+### Por coluna
+| Função | O que faz |
+|---|---|
+| `unique_values(df, coluna, top=20)` | Valores únicos com frequência e % (sem coluna: todas) |
+| `cardinality(df)` | % de únicos + classificação (id, categoria, constante...) |
+| `describe_numeric(df)` | Estatísticas + percentis + skewness + kurtosis |
+| `describe_categorical(df)` | Moda, frequências e top valores |
+
+### Relações
+| Função | O que faz |
+|---|---|
+| `correlation(df, method="pearson")` | Matriz de correlação (pearson/spearman/kendall) |
+| `high_correlations(df, threshold=0.9)` | Pares de colunas possivelmente redundantes |
+| `constant_columns(df)` | Colunas constantes ou quase constantes |
+
+### Consolidado
+| Função | O que faz |
+|---|---|
+| `profile(df)` | Roda tudo e imprime relatório organizado; retorna dict de DataFrames |
+| `compare(df_a, df_b)` | Compara schema e distribuições — útil pra validar cargas |
+
+## Exemplo de saída
+
+```python
+>>> xd.unique_values(df, "cidade")
+  valor  frequencia    pct
+0    SP          38  38.00
+1    RJ          25  25.00
+2    BH          20  20.00
+3    sp          10  10.00
+4   " SP"         7   7.00
+```
+
+Repare que `text_issues(df)` avisaria que "SP", "sp" e " SP" provavelmente são o mesmo valor.
+
+## Rodando os testes
+
+```bash
+pytest
+```
+
+## Licença
+
+MIT

exploradata-0.1.0/README.md

@@ -0,0 +1,100 @@
+# exploradata
+
+Ferramentas simples e composáveis para exploração de DataFrames pandas (EDA).
+
+Todas as funções **retornam DataFrames** — dá para filtrar, ordenar, exportar e encadear. Quando você só quer olhar, use `verbose=True` ou a função `profile()`.
+
+## Instalação
+
+```bash
+pip install git+https://github.com/anna-gatelli/exploradata.git
+```
+
+Ou, para desenvolvimento local:
+
+```bash
+git clone https://github.com/anna-gatelli/exploradata.git
+cd exploradata
+pip install -e ".[dev]"
+```
+
+## Uso rápido
+
+```python
+import pandas as pd
+import exploradata as xd
+
+df = pd.read_csv("dados.csv")
+
+# Relatório completo de uma vez
+report = xd.profile(df)
+
+# Ou função por função:
+xd.unique_values(df, "cidade")   # únicos com frequência e %
+xd.summary(df)                   # df.info() melhorado
+xd.missing(df)                   # nulos ranqueados
+xd.outliers(df)                  # outliers por IQR (ou method="zscore")
+xd.peek(df)                      # head + amostra aleatória + tail
+```
+
+## Funções
+
+### Visão geral
+| Função | O que faz |
+|---|---|
+| `summary(df)` | Tipo, nulos, únicos, cardinalidade e memória por coluna |
+| `peek(df, n=5)` | head + amostra aleatória + tail em um só DataFrame |
+| `detect_types(df)` | Detecta números, datas e booleanos "disfarçados" em colunas de texto |
+
+### Qualidade
+| Função | O que faz |
+|---|---|
+| `missing(df)` | Nulos por coluna (contagem e %), ranqueados |
+| `duplicates(df, subset=None)` | Linhas duplicadas, completas ou por chave |
+| `outliers(df, method="iqr")` | Outliers por IQR ou z-score nas numéricas |
+| `text_issues(df)` | Espaços extras e variações de capitalização que inflam os únicos |
+
+### Por coluna
+| Função | O que faz |
+|---|---|
+| `unique_values(df, coluna, top=20)` | Valores únicos com frequência e % (sem coluna: todas) |
+| `cardinality(df)` | % de únicos + classificação (id, categoria, constante...) |
+| `describe_numeric(df)` | Estatísticas + percentis + skewness + kurtosis |
+| `describe_categorical(df)` | Moda, frequências e top valores |
+
+### Relações
+| Função | O que faz |
+|---|---|
+| `correlation(df, method="pearson")` | Matriz de correlação (pearson/spearman/kendall) |
+| `high_correlations(df, threshold=0.9)` | Pares de colunas possivelmente redundantes |
+| `constant_columns(df)` | Colunas constantes ou quase constantes |
+
+### Consolidado
+| Função | O que faz |
+|---|---|
+| `profile(df)` | Roda tudo e imprime relatório organizado; retorna dict de DataFrames |
+| `compare(df_a, df_b)` | Compara schema e distribuições — útil pra validar cargas |
+
+## Exemplo de saída
+
+```python
+>>> xd.unique_values(df, "cidade")
+  valor  frequencia    pct
+0    SP          38  38.00
+1    RJ          25  25.00
+2    BH          20  20.00
+3    sp          10  10.00
+4   " SP"         7   7.00
+```
+
+Repare que `text_issues(df)` avisaria que "SP", "sp" e " SP" provavelmente são o mesmo valor.
+
+## Rodando os testes
+
+```bash
+pytest
+```
+
+## Licença
+
+MIT

exploradata-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "exploradata"
+version = "0.1.0"
+description = "Ferramentas simples e composáveis para exploração de DataFrames (EDA)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Anna Gatelli", email = "anna.gatelli@bateleur.com.br" }]
+keywords = ["eda", "pandas", "data-exploration", "data-quality"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "pandas>=1.5",
+    "numpy>=1.23",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/anna-gatelli/exploradata"
+
+[tool.setuptools.packages.find]
+where = ["src"]

exploradata-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

exploradata-0.1.0/src/exploradata/__init__.py

@@ -0,0 +1,25 @@
+"""exploradata — ferramentas simples e composáveis para exploração de DataFrames.
+
+Uso rápido:
+    import exploradata as xd
+
+    xd.profile(df)                      # relatório completo
+    xd.unique_values(df, "cidade")      # únicos de uma coluna
+    xd.missing(df)                      # nulos ranqueados
+"""
+
+from .overview import summary, peek, detect_types
+from .quality import missing, duplicates, outliers, text_issues
+from .columns import unique_values, cardinality, describe_numeric, describe_categorical
+from .relations import correlation, high_correlations, constant_columns
+from .report import profile, compare
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "summary", "peek", "detect_types",
+    "missing", "duplicates", "outliers", "text_issues",
+    "unique_values", "cardinality", "describe_numeric", "describe_categorical",
+    "correlation", "high_correlations", "constant_columns",
+    "profile", "compare",
+]

exploradata-0.1.0/src/exploradata/columns.py

@@ -0,0 +1,119 @@
+"""Análise por coluna: valores únicos, estatísticas e distribuição."""
+
+from __future__ import annotations
+
+import pandas as pd
+import numpy as np
+
+
+def unique_values(
+    df: pd.DataFrame,
+    column: str | None = None,
+    top: int = 20,
+    verbose: bool = False,
+) -> pd.DataFrame | dict[str, pd.DataFrame]:
+    """Valores únicos com frequência e percentual.
+
+    Se `column` for informada, retorna um DataFrame com os `top` valores
+    mais frequentes daquela coluna. Caso contrário, retorna um dict
+    {coluna: DataFrame} para todas as colunas.
+
+    Parameters
+    ----------
+    top : int
+        Quantos valores mais frequentes retornar (use None para todos).
+    verbose : bool
+        Se True, imprime os resultados formatados.
+    """
+    def _one(col: str) -> pd.DataFrame:
+        vc = df[col].value_counts(dropna=False)
+        out = pd.DataFrame({
+            "valor": vc.index,
+            "frequencia": vc.values,
+            "pct": (vc.values / len(df) * 100).round(2) if len(df) else 0.0,
+        })
+        if top is not None:
+            out = out.head(top)
+        return out.reset_index(drop=True)
+
+    if column is not None:
+        if column not in df.columns:
+            raise KeyError(f"Coluna '{column}' não existe no DataFrame")
+        result = _one(column)
+        if verbose:
+            n_uniq = df[column].nunique(dropna=True)
+            print(f"\n=== {column} ({n_uniq} valores únicos) ===")
+            print(result.to_string(index=False))
+        return result
+
+    results = {col: _one(col) for col in df.columns}
+    if verbose:
+        for col, res in results.items():
+            n_uniq = df[col].nunique(dropna=True)
+            print(f"\n=== {col} ({n_uniq} valores únicos) ===")
+            print(res.to_string(index=False))
+    return results
+
+
+def cardinality(df: pd.DataFrame) -> pd.DataFrame:
+    """Cardinalidade por coluna, com classificação heurística.
+
+    Ajuda a identificar IDs (cardinalidade ~100%), categorias (baixa)
+    e colunas constantes.
+    """
+    n = len(df)
+    rows = []
+    for col in df.columns:
+        uniq = df[col].nunique(dropna=True)
+        pct = round(uniq / n * 100, 2) if n else 0.0
+        if uniq <= 1:
+            kind = "constante"
+        elif pct >= 99:
+            kind = "provavel_id"
+        elif pct >= 50:
+            kind = "alta_cardinalidade"
+        elif uniq <= 20:
+            kind = "categoria"
+        else:
+            kind = "intermediaria"
+        rows.append({
+            "coluna": col, "unicos": uniq,
+            "cardinalidade_pct": pct, "classificacao": kind,
+        })
+    return pd.DataFrame(rows).sort_values(
+        "cardinalidade_pct", ascending=False
+    ).reset_index(drop=True)
+
+
+def describe_numeric(df: pd.DataFrame) -> pd.DataFrame:
+    """Estatísticas descritivas das colunas numéricas, incluindo skew e kurtosis."""
+    num = df.select_dtypes(include=np.number)
+    if num.empty:
+        return pd.DataFrame()
+
+    desc = num.describe(percentiles=[0.01, 0.05, 0.25, 0.5, 0.75, 0.95, 0.99]).T
+    desc["skewness"] = num.skew()
+    desc["kurtosis"] = num.kurtosis()
+    desc["nulos"] = num.isna().sum()
+    return desc.round(4).reset_index(names="coluna")
+
+
+def describe_categorical(df: pd.DataFrame, top: int = 3) -> pd.DataFrame:
+    """Estatísticas das colunas categóricas/texto: moda e valores mais frequentes."""
+    cat = df.select_dtypes(include=["object", "string", "category"])
+    rows = []
+    for col in cat.columns:
+        s = df[col].dropna()
+        vc = s.value_counts()
+        top_vals = "; ".join(
+            f"{v} ({c})" for v, c in vc.head(top).items()
+        )
+        rows.append({
+            "coluna": col,
+            "unicos": s.nunique(),
+            "moda": vc.index[0] if len(vc) else None,
+            "freq_moda": int(vc.iloc[0]) if len(vc) else 0,
+            f"top_{top}": top_vals,
+            "nulos": int(df[col].isna().sum()),
+        })
+    return pd.DataFrame(rows)

exploradata-0.1.0/src/exploradata/overview.py

@@ -0,0 +1,124 @@
+"""Visão geral do dataset: resumo, amostragem e detecção de tipos reais."""
+
+from __future__ import annotations
+
+import pandas as pd
+import numpy as np
+
+
+def summary(df: pd.DataFrame, verbose: bool = False) -> pd.DataFrame:
+    """Resumo geral do DataFrame: um df.info() melhorado.
+
+    Retorna um DataFrame com uma linha por coluna contendo tipo, nulos,
+    únicos, cardinalidade e uso de memória.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+    verbose : bool
+        Se True, imprime também um cabeçalho com shape e memória total.
+    """
+    n_rows = len(df)
+    info = pd.DataFrame({
+        "coluna": df.columns,
+        "dtype": [str(t) for t in df.dtypes],
+        "nulos": df.isna().sum().values,
+        "pct_nulos": (df.isna().mean() * 100).round(2).values,
+        "unicos": df.nunique(dropna=True).values,
+    })
+    info["cardinalidade_pct"] = (
+        (info["unicos"] / n_rows * 100).round(2) if n_rows else 0.0
+    )
+    info["memoria_kb"] = (
+        df.memory_usage(deep=True, index=False).values / 1024
+    ).round(1)
+
+    if verbose:
+        total_mb = df.memory_usage(deep=True).sum() / 1024**2
+        print(f"Shape: {df.shape[0]} linhas x {df.shape[1]} colunas")
+        print(f"Memória total: {total_mb:.2f} MB")
+        print(f"Linhas duplicadas: {df.duplicated().sum()}")
+        print(info.to_string(index=False))
+
+    return info
+
+
+def peek(df: pd.DataFrame, n: int = 5, random_state: int | None = None) -> pd.DataFrame:
+    """Amostragem inteligente: head + amostra aleatória + tail em um só DataFrame.
+
+    Adiciona uma coluna '_origem' indicando de onde cada linha veio.
+    """
+    n = min(n, len(df))
+    if len(df) == 0:
+        return df.copy()
+
+    head = df.head(n).copy()
+    head["_origem"] = "head"
+    tail = df.tail(n).copy()
+    tail["_origem"] = "tail"
+
+    middle_idx = df.index.difference(head.index).difference(tail.index)
+    sample_n = min(n, len(middle_idx))
+    if sample_n > 0:
+        sample = df.loc[middle_idx].sample(sample_n, random_state=random_state).copy()
+        sample["_origem"] = "amostra"
+    else:
+        sample = df.iloc[0:0].copy()
+        sample["_origem"] = pd.Series(dtype=str)
+
+    return pd.concat([head, sample, tail])
+
+
+def detect_types(df: pd.DataFrame, sample_size: int = 1000) -> pd.DataFrame:
+    """Detecta o tipo 'real' de colunas object: números, datas ou booleanos disfarçados.
+
+    Retorna apenas as colunas com sugestão de conversão.
+    """
+    suggestions = []
+    bool_sets = [
+        {"0", "1"}, {"true", "false"}, {"sim", "nao", "não"},
+        {"yes", "no"}, {"s", "n"}, {"t", "f"},
+    ]
+
+    for col in df.columns:
+        s = df[col].dropna()
+        if len(s) == 0:
+            continue
+        if len(s) > sample_size:
+            s = s.sample(sample_size, random_state=0)
+
+        current = str(df[col].dtype)
+        suggestion = None
+
+        # 0/1 numéricos que parecem booleanos
+        if pd.api.types.is_numeric_dtype(s):
+            vals = set(pd.unique(s))
+            if vals.issubset({0, 1}) and len(vals) == 2:
+                suggestion = "bool (0/1)"
+        elif current in ("object", "string", "str"):
+            as_str = s.astype(str).str.strip().str.lower()
+            uniq = set(as_str.unique())
+
+            if any(uniq.issubset(b) for b in bool_sets):
+                suggestion = "bool"
+            else:
+                numeric = pd.to_numeric(
+                    s.astype(str).str.replace(",", ".", regex=False),
+                    errors="coerce",
+                )
+                if numeric.notna().mean() > 0.95:
+                    suggestion = "numérico"
+                else:
+                    with np.errstate(all="ignore"):
+                        dates = pd.to_datetime(s, errors="coerce", format="mixed")
+                    if dates.notna().mean() > 0.95:
+                        suggestion = "datetime"
+
+        if suggestion:
+            suggestions.append({
+                "coluna": col,
+                "dtype_atual": current,
+                "tipo_sugerido": suggestion,
+            })
+
+    return pd.DataFrame(suggestions, columns=["coluna", "dtype_atual", "tipo_sugerido"])

exploradata-0.1.0/src/exploradata/quality.py

@@ -0,0 +1,120 @@
+"""Qualidade dos dados: nulos, duplicatas, outliers e inconsistências de texto."""
+
+from __future__ import annotations
+
+import pandas as pd
+import numpy as np
+
+
+def missing(df: pd.DataFrame, sort: bool = True) -> pd.DataFrame:
+    """Contagem e percentual de valores nulos por coluna, ranqueados."""
+    out = pd.DataFrame({
+        "coluna": df.columns,
+        "nulos": df.isna().sum().values,
+        "pct_nulos": (df.isna().mean() * 100).round(2).values,
+    })
+    if sort:
+        out = out.sort_values("nulos", ascending=False).reset_index(drop=True)
+    return out
+
+
+def duplicates(df: pd.DataFrame, subset: list[str] | None = None) -> pd.DataFrame:
+    """Linhas duplicadas — completas ou por subconjunto de colunas (ex.: chaves).
+
+    Retorna todas as ocorrências dos grupos duplicados (keep=False),
+    ordenadas para facilitar a comparação lado a lado.
+    """
+    mask = df.duplicated(subset=subset, keep=False)
+    dups = df[mask]
+    if len(dups) and subset:
+        dups = dups.sort_values(subset)
+    elif len(dups):
+        dups = dups.sort_values(list(df.columns))
+    return dups
+
+
+def outliers(
+    df: pd.DataFrame,
+    method: str = "iqr",
+    threshold: float | None = None,
+) -> pd.DataFrame:
+    """Detecta outliers nas colunas numéricas.
+
+    Parameters
+    ----------
+    method : 'iqr' ou 'zscore'
+    threshold : fator do IQR (padrão 1.5) ou limite de z-score (padrão 3.0)
+    """
+    num = df.select_dtypes(include=np.number)
+    rows = []
+
+    for col in num.columns:
+        s = num[col].dropna()
+        if len(s) < 4:
+            continue
+
+        if method == "iqr":
+            k = 1.5 if threshold is None else threshold
+            q1, q3 = s.quantile(0.25), s.quantile(0.75)
+            iqr = q3 - q1
+            low, high = q1 - k * iqr, q3 + k * iqr
+        elif method == "zscore":
+            k = 3.0 if threshold is None else threshold
+            std = s.std()
+            if std == 0 or np.isnan(std):
+                continue
+            mean = s.mean()
+            low, high = mean - k * std, mean + k * std
+        else:
+            raise ValueError("method deve ser 'iqr' ou 'zscore'")
+
+        mask = (s < low) | (s > high)
+        n_out = int(mask.sum())
+        rows.append({
+            "coluna": col,
+            "n_outliers": n_out,
+            "pct_outliers": round(n_out / len(s) * 100, 2),
+            "limite_inferior": round(float(low), 4),
+            "limite_superior": round(float(high), 4),
+            "min": round(float(s.min()), 4),
+            "max": round(float(s.max()), 4),
+        })
+
+    cols = ["coluna", "n_outliers", "pct_outliers", "limite_inferior",
+            "limite_superior", "min", "max"]
+    return pd.DataFrame(rows, columns=cols).sort_values(
+        "n_outliers", ascending=False
+    ).reset_index(drop=True)
+
+
+def text_issues(df: pd.DataFrame) -> pd.DataFrame:
+    """Inconsistências em colunas de texto que inflam a contagem de únicos.
+
+    Detecta espaços extras nas pontas e variações de capitalização
+    ('SP' vs 'sp' vs ' SP').
+    """
+    rows = []
+    text_cols = df.select_dtypes(include=["object", "string"]).columns
+
+    for col in text_cols:
+        s = df[col].dropna().astype(str)
+        if len(s) == 0:
+            continue
+
+        n_whitespace = int((s != s.str.strip()).sum())
+        uniq_raw = s.nunique()
+        uniq_norm = s.str.strip().str.lower().nunique()
+        n_case_variants = uniq_raw - uniq_norm
+
+        if n_whitespace or n_case_variants:
+            rows.append({
+                "coluna": col,
+                "valores_com_espacos": n_whitespace,
+                "unicos_brutos": uniq_raw,
+                "unicos_normalizados": uniq_norm,
+                "variantes_redundantes": n_case_variants,
+            })
+
+    cols = ["coluna", "valores_com_espacos", "unicos_brutos",
+            "unicos_normalizados", "variantes_redundantes"]
+    return pd.DataFrame(rows, columns=cols)

exploradata-0.1.0/src/exploradata/relations.py

@@ -0,0 +1,87 @@
+"""Relações entre colunas: correlação, redundância e colunas constantes."""
+
+from __future__ import annotations
+
+import pandas as pd
+import numpy as np
+
+
+def correlation(df: pd.DataFrame, method: str = "pearson") -> pd.DataFrame:
+    """Matriz de correlação das colunas numéricas.
+
+    Parameters
+    ----------
+    method : 'pearson', 'spearman' ou 'kendall'
+    """
+    num = df.select_dtypes(include=np.number)
+    if num.shape[1] < 2:
+        return pd.DataFrame()
+    return num.corr(method=method).round(4)
+
+
+def high_correlations(
+    df: pd.DataFrame,
+    threshold: float = 0.9,
+    method: str = "pearson",
+) -> pd.DataFrame:
+    """Pares de colunas com |correlação| acima do threshold — candidatas a redundância."""
+    corr = correlation(df, method=method)
+    if corr.empty:
+        return pd.DataFrame(columns=["coluna_a", "coluna_b", "correlacao"])
+
+    pairs = []
+    cols = corr.columns
+    for i in range(len(cols)):
+        for j in range(i + 1, len(cols)):
+            val = corr.iloc[i, j]
+            if pd.notna(val) and abs(val) >= threshold:
+                pairs.append({
+                    "coluna_a": cols[i],
+                    "coluna_b": cols[j],
+                    "correlacao": round(float(val), 4),
+                })
+
+    out = pd.DataFrame(pairs, columns=["coluna_a", "coluna_b", "correlacao"])
+    if len(out):
+        out = out.reindex(
+            out["correlacao"].abs().sort_values(ascending=False).index
+        ).reset_index(drop=True)
+    return out
+
+
+def constant_columns(df: pd.DataFrame, threshold: float = 0.99) -> pd.DataFrame:
+    """Colunas constantes ou quase constantes (candidatas a exclusão).
+
+    Parameters
+    ----------
+    threshold : float
+        Fração mínima do valor dominante para marcar como quase constante.
+    """
+    rows = []
+    n = len(df)
+    if n == 0:
+        return pd.DataFrame(
+            columns=["coluna", "valor_dominante", "pct_dominante", "status"]
+        )
+
+    for col in df.columns:
+        vc = df[col].value_counts(dropna=False)
+        if len(vc) == 0:
+            continue
+        dominant_pct = vc.iloc[0] / n
+        if len(vc) == 1:
+            status = "constante"
+        elif dominant_pct >= threshold:
+            status = "quase_constante"
+        else:
+            continue
+        rows.append({
+            "coluna": col,
+            "valor_dominante": vc.index[0],
+            "pct_dominante": round(dominant_pct * 100, 2),
+            "status": status,
+        })
+
+    return pd.DataFrame(
+        rows, columns=["coluna", "valor_dominante", "pct_dominante", "status"]
+    )

exploradata-0.1.0/src/exploradata/report.py

@@ -0,0 +1,134 @@
+"""Relatório consolidado e comparação entre DataFrames."""
+
+from __future__ import annotations
+
+import pandas as pd
+import numpy as np
+
+from .overview import summary, detect_types
+from .quality import missing, outliers, text_issues
+from .columns import cardinality, describe_numeric, describe_categorical
+from .relations import high_correlations, constant_columns
+
+
+def profile(df: pd.DataFrame, verbose: bool = True) -> dict[str, pd.DataFrame]:
+    """Roda todas as análises e retorna um dicionário de DataFrames.
+
+    Chaves: summary, missing, cardinality, numeric, categorical,
+    outliers, text_issues, high_correlations, constant_columns,
+    type_suggestions.
+
+    Se verbose=True, imprime um relatório organizado.
+    """
+    report = {
+        "summary": summary(df),
+        "missing": missing(df),
+        "cardinality": cardinality(df),
+        "numeric": describe_numeric(df),
+        "categorical": describe_categorical(df),
+        "outliers": outliers(df),
+        "text_issues": text_issues(df),
+        "high_correlations": high_correlations(df),
+        "constant_columns": constant_columns(df),
+        "type_suggestions": detect_types(df),
+    }
+
+    if verbose:
+        _print_report(df, report)
+
+    return report
+
+
+def _print_report(df: pd.DataFrame, report: dict[str, pd.DataFrame]) -> None:
+    sep = "=" * 70
+    print(sep)
+    print("RELATÓRIO DE EXPLORAÇÃO")
+    print(sep)
+    print(f"Shape: {df.shape[0]} linhas x {df.shape[1]} colunas")
+    print(f"Memória: {df.memory_usage(deep=True).sum() / 1024**2:.2f} MB")
+    print(f"Linhas duplicadas: {df.duplicated().sum()}")
+
+    sections = [
+        ("VISÃO GERAL POR COLUNA", "summary"),
+        ("VALORES NULOS", "missing"),
+        ("CARDINALIDADE", "cardinality"),
+        ("NUMÉRICAS", "numeric"),
+        ("CATEGÓRICAS", "categorical"),
+        ("OUTLIERS (IQR)", "outliers"),
+        ("INCONSISTÊNCIAS DE TEXTO", "text_issues"),
+        ("CORRELAÇÕES ALTAS (|r| >= 0.9)", "high_correlations"),
+        ("COLUNAS CONSTANTES / QUASE CONSTANTES", "constant_columns"),
+        ("SUGESTÕES DE CONVERSÃO DE TIPO", "type_suggestions"),
+    ]
+    for title, key in sections:
+        data = report[key]
+        print(f"\n--- {title} ---")
+        if data is None or len(data) == 0:
+            print("(nada encontrado)")
+        else:
+            print(data.to_string(index=False))
+    print("\n" + sep)
+
+
+def compare(
+    df_a: pd.DataFrame,
+    df_b: pd.DataFrame,
+    names: tuple[str, str] = ("A", "B"),
+) -> dict[str, pd.DataFrame]:
+    """Compara dois DataFrames: schema, shape e distribuição das numéricas.
+
+    Útil para validar cargas de dados (ex.: mês anterior vs mês atual).
+
+    Retorna dict com 'schema' e 'numeric_shift'.
+    """
+    na, nb = names
+
+    # --- Schema ---
+    cols = sorted(set(df_a.columns) | set(df_b.columns))
+    schema_rows = []
+    for col in cols:
+        in_a, in_b = col in df_a.columns, col in df_b.columns
+        dtype_a = str(df_a[col].dtype) if in_a else "-"
+        dtype_b = str(df_b[col].dtype) if in_b else "-"
+        if not in_a:
+            status = f"apenas_em_{nb}"
+        elif not in_b:
+            status = f"apenas_em_{na}"
+        elif dtype_a != dtype_b:
+            status = "dtype_diferente"
+        else:
+            status = "ok"
+        schema_rows.append({
+            "coluna": col, f"dtype_{na}": dtype_a,
+            f"dtype_{nb}": dtype_b, "status": status,
+        })
+    schema = pd.DataFrame(schema_rows)
+
+    # --- Distribuição das numéricas em comum ---
+    common_num = [
+        c for c in df_a.columns
+        if c in df_b.columns
+        and pd.api.types.is_numeric_dtype(df_a[c])
+        and pd.api.types.is_numeric_dtype(df_b[c])
+    ]
+    shift_rows = []
+    for col in common_num:
+        sa, sb = df_a[col].dropna(), df_b[col].dropna()
+        mean_a = float(sa.mean()) if len(sa) else np.nan
+        mean_b = float(sb.mean()) if len(sb) else np.nan
+        delta = (
+            round((mean_b - mean_a) / abs(mean_a) * 100, 2)
+            if mean_a not in (0, np.nan) and not np.isnan(mean_a)
+            else np.nan
+        )
+        shift_rows.append({
+            "coluna": col,
+            f"media_{na}": round(mean_a, 4),
+            f"media_{nb}": round(mean_b, 4),
+            "delta_media_pct": delta,
+            f"nulos_{na}_pct": round(df_a[col].isna().mean() * 100, 2),
+            f"nulos_{nb}_pct": round(df_b[col].isna().mean() * 100, 2),
+        })
+    numeric_shift = pd.DataFrame(shift_rows)
+
+    return {"schema": schema, "numeric_shift": numeric_shift}

exploradata-0.1.0/src/exploradata.egg-info/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: exploradata
+Version: 0.1.0
+Summary: Ferramentas simples e composáveis para exploração de DataFrames (EDA)
+Author-email: Anna Gatelli <anna.gatelli@bateleur.com.br>
+License: MIT
+Project-URL: Homepage, https://github.com/anna-gatelli/exploradata
+Keywords: eda,pandas,data-exploration,data-quality
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: numpy>=1.23
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# exploradata
+
+Ferramentas simples e composáveis para exploração de DataFrames pandas (EDA).
+
+Todas as funções **retornam DataFrames** — dá para filtrar, ordenar, exportar e encadear. Quando você só quer olhar, use `verbose=True` ou a função `profile()`.
+
+## Instalação
+
+```bash
+pip install git+https://github.com/anna-gatelli/exploradata.git
+```
+
+Ou, para desenvolvimento local:
+
+```bash
+git clone https://github.com/anna-gatelli/exploradata.git
+cd exploradata
+pip install -e ".[dev]"
+```
+
+## Uso rápido
+
+```python
+import pandas as pd
+import exploradata as xd
+
+df = pd.read_csv("dados.csv")
+
+# Relatório completo de uma vez
+report = xd.profile(df)
+
+# Ou função por função:
+xd.unique_values(df, "cidade")   # únicos com frequência e %
+xd.summary(df)                   # df.info() melhorado
+xd.missing(df)                   # nulos ranqueados
+xd.outliers(df)                  # outliers por IQR (ou method="zscore")
+xd.peek(df)                      # head + amostra aleatória + tail
+```
+
+## Funções
+
+### Visão geral
+| Função | O que faz |
+|---|---|
+| `summary(df)` | Tipo, nulos, únicos, cardinalidade e memória por coluna |
+| `peek(df, n=5)` | head + amostra aleatória + tail em um só DataFrame |
+| `detect_types(df)` | Detecta números, datas e booleanos "disfarçados" em colunas de texto |
+
+### Qualidade
+| Função | O que faz |
+|---|---|
+| `missing(df)` | Nulos por coluna (contagem e %), ranqueados |
+| `duplicates(df, subset=None)` | Linhas duplicadas, completas ou por chave |
+| `outliers(df, method="iqr")` | Outliers por IQR ou z-score nas numéricas |
+| `text_issues(df)` | Espaços extras e variações de capitalização que inflam os únicos |
+
+### Por coluna
+| Função | O que faz |
+|---|---|
+| `unique_values(df, coluna, top=20)` | Valores únicos com frequência e % (sem coluna: todas) |
+| `cardinality(df)` | % de únicos + classificação (id, categoria, constante...) |
+| `describe_numeric(df)` | Estatísticas + percentis + skewness + kurtosis |
+| `describe_categorical(df)` | Moda, frequências e top valores |
+
+### Relações
+| Função | O que faz |
+|---|---|
+| `correlation(df, method="pearson")` | Matriz de correlação (pearson/spearman/kendall) |
+| `high_correlations(df, threshold=0.9)` | Pares de colunas possivelmente redundantes |
+| `constant_columns(df)` | Colunas constantes ou quase constantes |
+
+### Consolidado
+| Função | O que faz |
+|---|---|
+| `profile(df)` | Roda tudo e imprime relatório organizado; retorna dict de DataFrames |
+| `compare(df_a, df_b)` | Compara schema e distribuições — útil pra validar cargas |
+
+## Exemplo de saída
+
+```python
+>>> xd.unique_values(df, "cidade")
+  valor  frequencia    pct
+0    SP          38  38.00
+1    RJ          25  25.00
+2    BH          20  20.00
+3    sp          10  10.00
+4   " SP"         7   7.00
+```
+
+Repare que `text_issues(df)` avisaria que "SP", "sp" e " SP" provavelmente são o mesmo valor.
+
+## Rodando os testes
+
+```bash
+pytest
+```
+
+## Licença
+
+MIT

exploradata-0.1.0/src/exploradata.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/exploradata/__init__.py
+src/exploradata/columns.py
+src/exploradata/overview.py
+src/exploradata/quality.py
+src/exploradata/relations.py
+src/exploradata/report.py
+src/exploradata.egg-info/PKG-INFO
+src/exploradata.egg-info/SOURCES.txt
+src/exploradata.egg-info/dependency_links.txt
+src/exploradata.egg-info/requires.txt
+src/exploradata.egg-info/top_level.txt
+tests/test_exploradata.py

exploradata-0.1.0/src/exploradata.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

exploradata-0.1.0/src/exploradata.egg-info/requires.txt

@@ -0,0 +1,5 @@
+pandas>=1.5
+numpy>=1.23
+
+[dev]
+pytest>=7.0

exploradata-0.1.0/src/exploradata.egg-info/top_level.txt

@@ -0,0 +1 @@
+exploradata

exploradata-0.1.0/tests/test_exploradata.py

@@ -0,0 +1,114 @@
+"""Testes básicos do exploradata."""
+
+import numpy as np
+import pandas as pd
+import pytest
+
+import exploradata as xd
+
+
+@pytest.fixture
+def df():
+    rng = np.random.default_rng(42)
+    n = 100
+    return pd.DataFrame({
+        "id": range(n),
+        "cidade": rng.choice(["SP", "sp", " SP", "RJ", "BH"], n),
+        "valor": np.append(rng.normal(100, 10, n - 2), [500.0, -300.0]),
+        "valor_dobro": np.append(rng.normal(100, 10, n - 2), [500.0, -300.0]) * 2,
+        "constante": ["x"] * n,
+        "num_como_texto": [str(i) for i in range(n)],
+        "com_nulos": [None if i % 4 == 0 else i for i in range(n)],
+    })
+
+
+def test_summary(df):
+    s = xd.summary(df)
+    assert len(s) == len(df.columns)
+    assert s.loc[s["coluna"] == "com_nulos", "nulos"].iloc[0] == 25
+
+
+def test_unique_values_column(df):
+    u = xd.unique_values(df, "cidade", top=10)
+    assert set(u.columns) == {"valor", "frequencia", "pct"}
+    assert u["frequencia"].sum() == len(df)
+
+
+def test_unique_values_all(df):
+    res = xd.unique_values(df, top=5)
+    assert isinstance(res, dict)
+    assert set(res.keys()) == set(df.columns)
+
+
+def test_unique_values_missing_column(df):
+    with pytest.raises(KeyError):
+        xd.unique_values(df, "nao_existe")
+
+
+def test_missing(df):
+    m = xd.missing(df)
+    assert m.iloc[0]["coluna"] == "com_nulos"
+    assert m.iloc[0]["pct_nulos"] == 25.0
+
+
+def test_outliers(df):
+    o = xd.outliers(df)
+    valor = o[o["coluna"] == "valor"]
+    assert valor["n_outliers"].iloc[0] >= 2
+
+
+def test_text_issues(df):
+    t = xd.text_issues(df)
+    assert "cidade" in t["coluna"].values
+    row = t[t["coluna"] == "cidade"].iloc[0]
+    assert row["variantes_redundantes"] > 0
+
+
+def test_constant_columns(df):
+    c = xd.constant_columns(df)
+    assert "constante" in c["coluna"].values
+
+
+def test_high_correlations(df):
+    h = xd.high_correlations(df, threshold=0.9)
+    pairs = set(map(tuple, h[["coluna_a", "coluna_b"]].values))
+    assert ("valor", "valor_dobro") in pairs or ("valor_dobro", "valor") in pairs
+
+
+def test_detect_types(df):
+    t = xd.detect_types(df)
+    assert "num_como_texto" in t["coluna"].values
+
+
+def test_cardinality(df):
+    c = xd.cardinality(df)
+    assert c[c["coluna"] == "id"]["classificacao"].iloc[0] == "provavel_id"
+    assert c[c["coluna"] == "constante"]["classificacao"].iloc[0] == "constante"
+
+
+def test_peek(df):
+    p = xd.peek(df, n=3, random_state=0)
+    assert "_origem" in p.columns
+    assert len(p) == 9
+
+
+def test_duplicates():
+    d = pd.DataFrame({"a": [1, 1, 2], "b": ["x", "x", "y"]})
+    dups = xd.duplicates(d)
+    assert len(dups) == 2
+
+
+def test_profile(df, capsys):
+    report = xd.profile(df, verbose=False)
+    assert "summary" in report and "outliers" in report
+
+
+def test_compare(df):
+    df_b = df.copy()
+    df_b["valor"] = df_b["valor"] * 1.5
+    df_b = df_b.drop(columns=["constante"])
+    res = xd.compare(df, df_b)
+    schema = res["schema"]
+    assert (schema[schema["coluna"] == "constante"]["status"] == "apenas_em_A").all()
+    shift = res["numeric_shift"]
+    assert abs(shift[shift["coluna"] == "valor"]["delta_media_pct"].iloc[0] - 50) < 1