jlprep 0.1.0__py3-none-any.whl

jlprep/__init__.py

@@ -0,0 +1,36 @@
+# jlprep/__init__.py
+
+__version__ = "0.1.0"
+
+# Importando funções diretamente para facilitar o uso
+from .cleaning import remove_duplicates, remove_outliers, clean_missing
+from .encoding import encode_label, encode_onehot
+from .exploration import summarize_data, value_counts_plot, check_data_quality
+from .quality import check_class_balance
+from .diagnostics import analyze_dataset
+from .comparison import compare_datasets
+from .reporting import generate_report
+
+__all__ = ["remove_duplicates",
+           "remove_outliers",
+           "clean_missing",
+           "encode_label",
+           "encode_onehot",
+           "summarize_data",
+           "value_counts_plot",
+           "check_class_balance",
+           "check_data_quality",
+           "analyze_dataset",
+           "compare_datasets",
+           "generate_report"]
+
+
+"""
+JlPrep - Biblioteca de pré-processamento de dados para Machine Learning
+
+Desenvolvida por João Lucas para facilitar tarefas como:
+- Limpeza de dados
+- Tratamento de valores ausentes
+- Codificação de variáveis categóricas
+- Análise exploratória (em futuras versões)
+"""

jlprep/cleaning.py

@@ -0,0 +1,209 @@
+__all__ = ["remove_duplicates",
+           "remove_outliers",
+           "clean_missing"]
+
+import pandas as pd
+
+def remove_duplicates(data: pd.DataFrame,
+                      visualization: bool = False,
+                      remove: bool = False) -> pd.DataFrame:
+    """
+    Remove ou visualiza duplicatas de um dataframe.
+
+    :param data: Dataframe com os dados a serem analisados.
+    :param visualization: Se True, visualiza as duplicatas no Dataframe.
+    :param remove: Se True, remove as duplicatas no Dataframe.
+    :return: Dataframe com ou sem duplicatas, dependendo do parâmetro 'remove'
+    
+    """
+    #Verificando o comportamento
+    if visualization and remove:
+        print("Exibindo duplicatas")
+        print(data[data.duplicated()])
+        print("\nRemovendo duplicatas...")
+        return data.drop_duplicates()
+        
+    elif visualization:
+        
+        print("Exibindo duplicatas:")
+        return data[data.duplicated()]
+
+    elif remove:
+       
+        print("Removendo duplicatas...")
+        return data.drop_duplicates()
+
+    else:
+        
+        print("Nenhuma ação foi realizada. Use 'visualization' para visualizar ou 'remove' para remover duplicatas.")
+        return data
+
+
+
+def remove_outliers(data: pd.DataFrame,
+                    method:str = "iqr",
+                    threshold: float = 1.5,
+                    columns: list[str] | None = None) -> pd.DataFrame:
+
+    """
+    Remove outliers de um DataFrame com base em métodos estatísticos.
+
+    Parâmetros
+    ----------
+    data : pandas.DataFrame
+        Conjunto de dados a ser processado.
+    method : str, opcional (default='iqr')
+        Método usado para detecção de outliers. Pode ser:
+        - 'iqr': usa o intervalo interquartil (Q1 - 1.5*IQR, Q3 + 1.5*IQR)
+        - 'zscore': usa o desvio padrão em relação à média.
+    threshold : float, opcional (default=1.5)
+        Fator usado para definir o limite dos outliers.
+        - Para 'iqr': multiplicador do IQR.
+        - Para 'zscore': valor absoluto do Z-score máximo permitido.
+    columns : list ou None, opcional
+        Lista de colunas numéricas a serem analisadas. Se None, aplica em todas as colunas numéricas.
+
+    Retorna
+    -------
+    pandas.DataFrame
+        DataFrame sem os outliers detectados.
+
+    Lança
+    -----
+    ValueError
+    Se o método informado não for reconhecido ou se o threshold for menor ou igual a zero.
+
+    KeyError
+        Se alguma coluna informada não existir no DataFrame.
+
+    TypeError
+        Se alguma coluna informada não for numérica.
+    """
+
+    df = data.copy()
+
+    # Seleciona as colunas numéricas
+    if columns is None:
+        columns = df.select_dtypes(include=["number"]).columns.tolist()
+
+
+    # Valida as colunas
+    for col in columns:
+        if col not in df.columns:
+            raise KeyError(f"A coluna '{col}' não existe no DataFrame.")
+
+        # Verifica se as colunas são numéricas
+        if not pd.api.types.is_numeric_dtype(df[col]):
+            raise TypeError(f"A coluna '{col}' deve ser numérica")
+
+
+    if threshold <= 0:
+        raise ValueError("O threshold deve ser maior que zero.")
+    
+    # Verifica o método escolhido
+    match method:
+        case "iqr":
+
+            for col in columns:
+                Q1 = df[col].quantile(0.25)
+                Q3 = df[col].quantile(0.75)
+                IQR = Q3 - Q1
+
+                lower_limit = Q1 - threshold * IQR
+                upper_limit = Q3 + threshold * IQR
+
+                df = df[(df[col] >= lower_limit) & (df[col] <= upper_limit)]
+
+            return df
+            
+
+        case "zscore":
+
+            for col in columns:
+                mean = df[col].mean()
+                std = df[col].std()
+
+                z_scores = (df[col] - mean) / std
+
+                df = df[z_scores.abs() <= threshold]
+
+            return df
+            
+        case _:
+            raise ValueError(f"Método '{method}' não reconhecido. Use 'iqr' ou 'zscore'.")
+        
+
+
+
+def clean_missing(
+        data: pd.DataFrame,
+        strategy: str = "drop",
+        columns: list[str] | None = None,
+        value: object | None = None,
+        threshold: float | None = None,
+        visualize: bool = False
+    ) -> pd.DataFrame:
+    
+    """
+    Trata valores ausentes em um DataFrame com diferentes estratégias.
+
+    Parâmetros:
+    - data: DataFrame do pandas.
+    - strategy: Estratégia de tratamento. Pode ser 'drop', 'mean', 'median', 'mode', 'value' ou 'interpolate'.
+    - columns: Lista de colunas a serem tratadas. Se None, serão escolhidas com base na estratégia.
+    - value: Valor específico para preenchimento (usado apenas se strategy='value').
+    - threshold: Proporção de valores ausentes para remover colunas (usado apenas com strategy='drop').
+    - visualize: Se True, exibe o resumo de valores ausentes antes do tratamento.
+
+    Retorna:
+    - DataFrame com valores ausentes tratados.
+    """
+
+    df = data.copy()
+
+    if columns is None:
+        if strategy in ["mean", "median", "zscore"]:
+            columns = df.select_dtypes(include=["number"]).columns
+        elif strategy in ["mode", "value", "drop", "interpolate"]:
+            columns = df.columns
+        else:
+            raise ValueError(f"Estratégia '{strategy}' não reconhecida.")
+
+    match strategy:
+        case "drop":
+            if threshold is not None:
+                
+                df = df.loc[:, df.isnull().mean() < threshold]
+            else:
+                
+                df = df.dropna(subset=columns)
+
+        case "mean":
+            for col in columns:
+                df[col] = df[col].fillna(df[col].mean())
+
+        case "median":
+            for col in columns:
+                df[col] = df[col].fillna(df[col].median())
+
+        case "mode":
+            for col in columns:
+                mode = df[col].mode()
+                if not mode.empty:
+                    df[col] = df[col].fillna(mode[0])
+
+        case "value":
+            if value is None:
+                raise ValueError("Para a estratégia 'value', o parâmetro 'value' deve ser fornecido.")
+            for col in columns:
+                df[col] = df[col].fillna(value)
+
+        case "interpolate":
+            df[columns] = df[columns].interpolate()
+
+        case _:
+            raise ValueError(f"Estratégia '{strategy}' não reconhecida.")
+
+    return df
+
+            

jlprep/comparison.py

@@ -0,0 +1,55 @@
+
+__all__ = ["comparison"]
+
+import pandas as pd
+
+
+def compare_datasets(
+    original: pd.DataFrame,
+    processed: pd.DataFrame
+) -> dict:
+    """
+    Compara indicadores de dois DataFrames antes e depois
+    de um procedimento de pré-processamento.
+    """
+    if not isinstance(original, pd.DataFrame):
+        raise TypeError("original deve ser um DataFrame.")
+
+    if not isinstance(processed, pd.DataFrame):
+        raise TypeError("processed deve ser um DataFrame.")
+
+    def metrics(df):
+        total_cells = df.shape[0] * df.shape[1]
+        missing = int(df.isna().sum().sum())
+
+        return {
+            "rows": len(df),
+            "columns": len(df.columns),
+            "missing_values": missing,
+            "missing_percentage": round(
+                missing / total_cells * 100, 2
+            ) if total_cells else 0.0,
+            "duplicates": int(df.duplicated().sum()),
+        }
+
+    before = metrics(original)
+    after = metrics(processed)
+
+    return {
+        "before": before,
+        "after": after,
+        "changes": {
+            "row_difference": after["rows"] - before["rows"],
+            "column_difference": (
+                after["columns"] - before["columns"]
+            ),
+            "missing_difference": (
+                after["missing_values"]
+                - before["missing_values"]
+            ),
+            "duplicate_difference": (
+                after["duplicates"] - before["duplicates"]
+            ),
+        },
+    }
+  

jlprep/diagnostics.py

@@ -0,0 +1,129 @@
+__all__ = ["diagnostics"]
+
+import pandas as pd
+
+
+def analyze_dataset(df: pd.DataFrame, target: str | None = None) -> dict:
+    """
+    Analisa um DataFrame e gera um diagnóstico com recomendações.
+
+    A análise não modifica os dados originais.
+    """
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError("df deve ser um DataFrame do Pandas.")
+
+    if target is not None and target not in df.columns:
+        raise KeyError(f"Coluna-alvo '{target}' não encontrada.")
+
+    alerts = []
+
+    # 1. Valores ausentes
+    for column in df.columns:
+        missing_count = int(df[column].isna().sum())
+
+        if missing_count == 0:
+            continue
+
+        missing_pct = (
+            missing_count / len(df) * 100 if len(df) else 0.0
+        )
+
+        if pd.api.types.is_numeric_dtype(df[column]):
+            suggestion = (
+                "Investigar a distribuição da variável e avaliar "
+                "imputação pela mediana ou outra estratégia adequada."
+            )
+        else:
+            suggestion = (
+                "Investigar os valores ausentes e avaliar "
+                "imputação pela moda ou criação de uma categoria."
+            )
+
+        alerts.append({
+            "type": "missing_values",
+            "column": column,
+            "count": missing_count,
+            "percentage": round(missing_pct, 2),
+            "recommendation": suggestion,
+        })
+
+    # 2. Registros duplicados
+    duplicates = int(df.duplicated().sum())
+
+    if duplicates:
+        alerts.append({
+            "type": "duplicates",
+            "count": duplicates,
+            "recommendation": (
+                "Verificar se os registros repetidos são erros "
+                "antes de removê-los."
+            ),
+        })
+
+    # 3. Outliers pelo método IQR
+    numeric_columns = df.select_dtypes(include="number").columns
+
+    for column in numeric_columns:
+        if column == target:
+            continue
+
+        values = df[column].dropna()
+
+        if len(values) < 4:
+            continue
+
+        q1 = values.quantile(0.25)
+        q3 = values.quantile(0.75)
+        iqr = q3 - q1
+
+        if iqr == 0:
+            continue
+
+        lower = q1 - 1.5 * iqr
+        upper = q3 + 1.5 * iqr
+
+        outlier_count = int(
+            ((values < lower) | (values > upper)).sum()
+        )
+
+        if outlier_count:
+            alerts.append({
+                "type": "outliers",
+                "column": column,
+                "count": outlier_count,
+                "method": "IQR",
+                "recommendation": (
+                    "Investigar os valores extremos antes de "
+                    "decidir pela remoção ou transformação."
+                ),
+            })
+
+    # 4. Balanceamento das classes
+    if target is not None:
+        counts = df[target].value_counts(dropna=True)
+
+        if len(counts) >= 2:
+            majority = int(counts.max())
+            minority = int(counts.min())
+            ratio = majority / minority
+
+            if ratio >= 3:
+                alerts.append({
+                    "type": "class_imbalance",
+                    "column": target,
+                    "ratio": round(ratio, 2),
+                    "recommendation": (
+                        "Investigar o impacto do desbalanceamento "
+                        "e avaliar métricas por classe e "
+                        "estratégias de amostragem."
+                    ),
+                })
+
+    return {
+        "rows": len(df),
+        "columns": len(df.columns),
+        "target": target,
+        "total_alerts": len(alerts),
+        "alerts": alerts,
+    }
+  

jlprep/encoding.py

@@ -0,0 +1,116 @@
+__all__ = ["encode_label",
+           "encode_onehot"]
+
+import pandas as pd
+
+
+def encode_label(data: pd.DataFrame,
+                columns: list[str] | None = None,
+                return_mapping: bool = False) -> pd.DataFrame:
+
+    
+    """
+
+    Aplica codificação label encoding em colunas categóricas de um Dataframe.
+
+    Cada valor único de texto é substituído por um número inteiro, facilitando o uso
+    de dados categóricos em algoritmos de Machine Learning.
+
+    Parâmetros:
+    ----------
+    data: pandas.Dataframe
+        O DataFrame de entrada que contém os dados a serem codificados
+
+    columns: list (opcional)
+        Lista de colunas a serem codificadas. Se "None", todas as colunas do tipo 'object' serão usadas.
+
+    return_mapping : bool, opcional
+        Se True, retorna também um dicionário com os mapeamentos de rótulo para número inteiro
+        para cada coluna codificada.
+
+    Retorna:
+    -------
+    pandas.DataFrame
+        O DataFrame com as colunas especificadas codificadas.
+
+    dict (opcional)
+        Um dicionário contendo os mapeamentos usados para cada coluna, se return_mapping=True.
+    """
+
+    if columns is None:
+        columns = data.select_dtypes(include=["object", "string", "category"]).columns
+
+    if return_mapping:
+        mapping_dict = {}
+
+    for col in columns:
+        unique_values = data[col].unique()
+        mapping = {label: idx for idx, label in enumerate(unique_values)}
+        data[col] = data[col].map(mapping)
+
+        if return_mapping:
+            mapping_dict[col] = mapping
+
+    
+    if return_mapping:
+        return data, mapping_dict
+    return data
+
+
+
+def encode_onehot(
+    data: pd.DataFrame,
+    columns: list[str] | None = None,
+    drop_first: bool = False
+) -> pd.DataFrame:
+    """
+    Codifica variáveis categóricas usando One-Hot Encoding.
+
+    Parâmetros
+    ----------
+    data : pandas.DataFrame
+        DataFrame contendo os dados.
+
+    columns : list[str] | None, opcional
+        Lista das colunas categóricas que serão codificadas.
+        Se None, todas as colunas dos tipos 'object', 'string' e 'category'
+        serão utilizadas.
+
+    drop_first : bool, opcional
+        Se True, remove a primeira categoria de cada coluna codificada,
+        evitando multicolinearidade.
+
+    Retorna
+    -------
+    pandas.DataFrame
+        Novo DataFrame contendo as colunas categóricas codificadas.
+
+    Levanta
+    -------
+    KeyError
+        Se alguma coluna informada não existir no DataFrame.
+
+    TypeError
+        Se alguma coluna informada não for categórica.
+    """
+
+    if columns is None:
+        columns = data.select_dtypes(include=["object", "string", "category"]).columns.tolist()
+
+    for col in columns:
+        if col not in data.columns:
+            raise KeyError(f"A coluna '{col}' não existe no DataFrame.")
+
+        if not (
+            pd.api.types.is_object_dtype(data[col])
+            or pd.api.types.is_string_dtype(data[col])
+            or pd.api.types.is_categorical_dtype(data[col])
+        ):
+            raise TypeError(f"A coluna '{col}' deve ser categórica.")
+
+    return pd.get_dummies(
+        data,
+        columns=columns,
+        drop_first=drop_first,
+        dtype=int
+    )

jlprep/exploration.py

@@ -0,0 +1,254 @@
+# preprocess/exploration.py
+from pandas.api.types import (
+    is_numeric_dtype,
+    is_categorical_dtype,
+    is_object_dtype,
+    is_bool_dtype,
+)
+
+import pandas as pd
+
+__all__ = ["summarize_data",
+           "value_counts_plot",
+           "check_data_quality"]
+
+def summarize_data(data: pd.DataFrame):
+    """
+    Gera um resumo exploratório do DataFrame:
+      - Tamanho (linhas/colunas)
+      - Tipos de dados por coluna
+      - Valores ausentes (contagem e %)
+      - Estatísticas por coluna:
+          * Numéricas: média, mediana, moda, min, max
+          * Categóricas (object/category/bool): moda, nº de categorias únicas, freq. da moda
+    Retorna:
+      dict: {nome_da_coluna: {estatísticas...}}
+    """
+    # 1) Tamanho
+    print("Número de linhas e colunas:", len(data), "linhas,", len(data.columns), "colunas")
+
+    # 2) Tipos
+    print("\nTipos de dados por coluna:")
+    print(data.dtypes)
+
+    # 3) Ausentes (contagem e %)
+    print("\nValores ausentes por coluna (ordem decrescente):")
+    print(data.isnull().sum().sort_values(ascending=False))
+
+    print("\nPorcentagem de valores ausentes por coluna:")
+    print(((data.isnull().sum() / len(data)) * 100).round(2))
+
+    # 4) Amostra
+    print("\n5 primeiras linhas do DataFrame:")
+    print(data.head(5))
+
+    # 5) Estatísticas por coluna
+    resumo = {}
+    for col in data.columns:
+        if is_numeric_dtype(data[col]):
+            s = data[col].dropna()
+            moda_series = s.mode()
+            moda = moda_series.iloc[0] if not moda_series.empty else None
+            resumo[col] = {
+                "média": s.mean() if not s.empty else None,
+                "mediana": s.median() if not s.empty else None,
+                "moda": moda,
+                "mínimo": s.min() if not s.empty else None,
+                "máximo": s.max() if not s.empty else None,
+            }
+        elif is_categorical_dtype(data[col]) or is_object_dtype(data[col]) or is_bool_dtype(data[col]):
+            s = data[col].dropna()
+            moda_series = s.mode()
+            moda = moda_series.iloc[0] if not moda_series.empty else None
+            freq_moda = s.value_counts().iloc[0] if not s.value_counts().empty else 0
+            resumo[col] = {
+                "moda": moda,
+                "n_categorias": s.nunique(),
+                "freq_moda": int(freq_moda),
+            }
+        else:
+            # Para tipos como datetime, etc., um resumo simples:
+            s = data[col].dropna()
+            resumo[col] = {
+                "tipo": str(data[col].dtype),
+                "n_únicos": s.nunique(),
+            }
+
+    # Imprime o resumo
+    for col, stats in resumo.items():
+        print(f"\nColuna: {col}")
+        for k, v in stats.items():
+            print(f"  {k}: {v}")
+
+    return resumo
+
+
+def value_counts_plot(
+        data: pd.DataFrame,
+        column: str,
+        normalize: bool = False,
+        top_n: int | None = None
+    ) -> None:
+     
+     import matplotlib.pyplot as plt
+
+     """
+    Gera um gráfico de barras com a contagem (ou proporção) dos valores únicos
+    em uma coluna categórica.
+
+    Parâmetros
+    ----------
+    data : pandas.DataFrame
+        O DataFrame com os dados.
+    column : str
+        Nome da coluna categórica a ser analisada.
+    normalize : bool, opcional (default=False)
+        Se True, mostra proporções (%) em vez de contagens absolutas.
+    top_n : int, opcional
+        Se definido, mostra apenas as top N categorias mais frequentes.
+
+    Retorno
+    -------
+    None
+        Exibe o gráfico.
+    """
+     
+     #Obtendo frequências
+     counts = data[column].value_counts(normalize=normalize)
+
+     if top_n is not None:
+         counts = counts.head(top_n)
+
+     counts.plot(kind="bar")
+     plt.title(f"Distribuição de valores - {column}")
+     plt.xlabel("Categorias")
+     plt.ylabel("Frequências (%)" if normalize else "Frequências")
+     plt.show()
+
+
+
+def check_data_quality(data: pd.DataFrame):
+    """
+    Analisa a qualidade dos dados de um DataFrame.
+
+    Funcionalidades:
+    - Valores ausentes (%)
+    - Duplicatas por coluna (%)
+    - Outliers (IQR) para colunas numéricas (quantidade)
+    - Cardinalidade de colunas categóricas (com gráfico)
+
+    Parâmetros
+    ----------
+    data : pandas.DataFrame
+        O DataFrame a ser analisado.
+
+    Retornos
+    -------
+    dict
+        Dicionários com informações sobre valores ausentes, duplicatas,
+        outliers e cardinalidade.
+    """
+
+    import numpy as np
+    import matplotlib.pyplot as plt
+    from pandas.api.types import is_numeric_dtype, is_object_dtype, is_categorical_dtype
+
+    dict_missing_col = {}
+    dict_duplicated_col = {}
+    dict_outliers_col = {}
+    dict_cardinality = {}
+
+    total_rows = len(data)
+
+    # Valores ausentes
+    for col in data.columns:
+        percentual_missing = (data[col].isnull().sum() / total_rows) * 100
+        dict_missing_col[col] = round(float(percentual_missing), 2)
+
+    # Duplicatas
+    for col in data.columns:
+        duplicated_count = total_rows - data[col].nunique()
+        duplicated_percent = (duplicated_count / total_rows) * 100
+        dict_duplicated_col[col] = {
+            "quantidade": int(duplicated_count),
+            "percentual": round(float(duplicated_percent), 2)
+        }
+
+    # Outliers (IQR)
+    for col in data.columns:
+        if is_numeric_dtype(data[col]):
+            col_clean = data[col].dropna()
+
+            Q1 = np.percentile(col_clean, 25)
+            Q3 = np.percentile(col_clean, 75)
+            IQR = Q3 - Q1
+
+            lower_bound = Q1 - 1.5 * IQR
+            upper_bound = Q3 + 1.5 * IQR
+
+            outliers_count = ((col_clean < lower_bound) | (col_clean > upper_bound)).sum()
+            dict_outliers_col[col] = int(outliers_count)
+
+    # Cardinalidade (object + categorical)
+    for col in data.columns:
+        if is_object_dtype(data[col]) or is_categorical_dtype(data[col]):
+            unique_values = data[col].nunique()
+            proportion = (unique_values / total_rows) * 100
+
+            dict_cardinality[col] = {
+                "unicos": int(unique_values),
+                "percentual": round(float(proportion), 2)
+            }
+
+    # PRINT ORGANIZADO
+    print("\n=== QUALIDADE DOS DADOS ===\n")
+
+    print("🔹 Valores ausentes:")
+    for col, perc in dict_missing_col.items():
+        if perc > 0:
+            print(f"- {col}: {perc}%")
+
+    print("\n🔹 Duplicatas:")
+    for col, info in dict_duplicated_col.items():
+        if info["quantidade"] > 0:
+            print(f"- {col}: {info['quantidade']} ({info['percentual']}%)")
+
+    print("\n🔹 Outliers:")
+    has_outliers = False
+    for col, count in dict_outliers_col.items():
+        if count > 0:
+            print(f"- {col}: {count} outliers")
+            has_outliers = True
+    if not has_outliers:
+        print("- Nenhum outlier detectado")
+
+    print("\n🔹 Cardinalidade:")
+    if dict_cardinality:
+        for col, info in dict_cardinality.items():
+            print(f"- {col}: {info['unicos']} valores únicos ({info['percentual']}%)")
+
+            if info["percentual"] > 50:
+                print(f"  ⚠️ Alta cardinalidade, considerar tratamento")
+    else:
+        print("- Nenhuma coluna categórica detectada")
+
+    # Gráfico de cardinalidade
+    if dict_cardinality:
+        cols = list(dict_cardinality.keys())
+        percents = [info["percentual"] for info in dict_cardinality.values()]
+
+        plt.figure(figsize=(10, 6))
+        plt.bar(cols, percents)
+        plt.xticks(rotation=45, ha="right")
+        plt.ylabel("Percentual de cardinalidade")
+        plt.title("Cardinalidade das colunas categóricas")
+        plt.show()
+
+    # Retorno estruturado
+    return {
+        "missing": dict_missing_col,
+        "duplicated": dict_duplicated_col,
+        "outliers": dict_outliers_col,
+        "cardinality": dict_cardinality
+    }
+

jlprep/quality.py

@@ -0,0 +1,122 @@
+# preprocess/exploration.py
+from pandas.api.types import (
+    is_numeric_dtype,
+    is_categorical_dtype,
+    is_object_dtype,
+    is_bool_dtype,
+)
+
+import pandas as pd
+import matplotlib.pyplot as plt
+
+__all__ = ["check_class_balance"]
+
+def check_class_balance(
+    data: pd.DataFrame,
+    target: str,
+    plot: bool = False
+) -> dict:
+    """
+    Analisa o balanceamento das classes em uma variável alvo de um dataset.
+
+    Esta função calcula a distribuição das classes, identifica o tipo de problema
+    (classificação binária ou multiclasse), mede o nível de desbalanceamento por meio
+    da razão entre a classe majoritária e minoritária (imbalance ratio) e fornece
+    um diagnóstico com sugestões de tratamento.
+
+    Parâmetros
+    ----------
+    data : pandas.DataFrame
+        Dataset contendo a variável alvo.
+
+    target : str
+        Nome da coluna que representa a variável alvo.
+
+    plot : bool, opcional (default=False)
+        Se True, exibe um gráfico de barras com a distribuição das classes.
+
+    Retorna
+    -------
+    dict
+        Um dicionário contendo:
+        - n_classes
+        - problem_type
+        - imbalance_ratio
+        - status
+        - suggestion
+
+    Levanta
+    -------
+    KeyError
+        Se a coluna especificada não existir.
+
+    TypeError
+        Se o parâmetro target não for uma string.
+
+    ValueError
+        Se a variável alvo possuir menos de duas classes.
+    """
+
+    if not isinstance(target, str):
+        raise TypeError("O parâmetro 'target' deve ser uma string.")
+
+    if target not in data.columns:
+        raise KeyError(f"A coluna '{target}' não existe no DataFrame.")
+
+    col = data[target].dropna()
+
+    class_count = col.value_counts()
+    class_proportion = col.value_counts(normalize=True) * 100
+
+    n_classes = len(class_count)
+
+    if n_classes == 2:
+        problem = "Binary classification"
+    elif n_classes > 2:
+        problem = "Multiclass classification"
+    else:
+        raise ValueError("O dataset deve possuir pelo menos duas classes.")
+
+    max_class = class_count.max()
+    min_class = class_count.min()
+
+    imbalance_ratio = max_class / min_class
+
+    if imbalance_ratio <= 1.5:
+        status = "Dataset balanceado"
+        suggestion = "Nenhuma ação necessária."
+
+    elif imbalance_ratio <= 3:
+        status = "Dataset levemente desbalanceado"
+        suggestion = "Monitorar o desempenho do modelo."
+
+    elif imbalance_ratio <= 10:
+        status = "Dataset moderadamente desbalanceado"
+        suggestion = "Considerar técnicas de balanceamento."
+
+    else:
+        status = "Dataset altamente desbalanceado"
+        suggestion = "Aplicar técnicas de balanceamento (SMOTE, Oversampling, etc.)."
+
+    print("Distribuição das classes:\n")
+
+    for classe in class_count.index:
+        print(f"{classe}: {class_count[classe]} ({class_proportion[classe]:.2f}%)")
+
+    print(f"\nNúmero de classes: {n_classes}")
+    print(f"Tipo de problema: {problem}")
+    print(f"\nImbalance ratio: {imbalance_ratio:.2f}")
+    print(f"Status: {status}")
+    print(f"Sugestão: {suggestion}")
+
+    if plot:
+        class_count.plot(kind="bar", title="Distribuição das classes")
+        plt.show()
+
+    return {
+        "n_classes": n_classes,
+        "problem_type": problem,
+        "imbalance_ratio": imbalance_ratio,
+        "status": status,
+        "suggestion": suggestion
+    }

jlprep/reporting.py

@@ -0,0 +1,288 @@
+"""Geração de relatórios HTML a partir de analyze_dataset e compare_datasets."""
+from __future__ import annotations
+
+__all__ = ["reporting"]
+
+
+from datetime import datetime
+from html import escape
+from pathlib import Path
+from typing import Any
+import webbrowser
+
+
+def _text(value: Any) -> str:
+    return escape(str(value), quote=True)
+
+
+def _number(value: Any) -> str:
+    return _text(value if value is not None else "—")
+
+
+def generate_report(
+    diagnosis: dict,
+    comparison: dict | None = None,
+    output_path: str | Path = "jlprep_report.html",
+    title: str = "Relatório de qualidade dos dados — JlPrep",
+    open_browser: bool = False,
+) -> Path:
+    """Gera um relatório HTML local com diagnóstico e comparação."""
+
+    if not isinstance(diagnosis, dict) or not isinstance(
+        diagnosis.get("alerts"), list
+    ):
+        raise TypeError(
+            "diagnosis deve ser o retorno de analyze_dataset()."
+        )
+
+    if comparison is not None and not isinstance(comparison, dict):
+        raise TypeError(
+            "comparison deve ser o retorno de compare_datasets()."
+        )
+
+    path = Path(output_path).expanduser().resolve()
+
+    if path.suffix.lower() != ".html":
+        raise ValueError("O arquivo deve terminar em .html")
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    labels = {
+        "missing_values": "Valores ausentes",
+        "duplicates": "Registros duplicados",
+        "outliers": "Valores extremos (IQR)",
+        "class_imbalance": "Desbalanceamento de classes",
+    }
+
+    metric_labels = {
+        "rows": "Registros",
+        "columns": "Colunas",
+        "missing_values": "Células ausentes",
+        "missing_percentage": "Ausentes (%)",
+        "duplicates": "Duplicatas",
+    }
+
+    alerts = diagnosis["alerts"]
+    alert_html = []
+
+    for alert in alerts:
+        if not isinstance(alert, dict):
+            continue
+
+        details = []
+
+        fields = [
+            ("column", "Coluna"),
+            ("count", "Ocorrências"),
+            ("percentage", "Percentual (%)"),
+            ("ratio", "Razão"),
+            ("method", "Método"),
+        ]
+
+        for key, label in fields:
+            if key in alert:
+                details.append(
+                    f'<span class="chip">'
+                    f'{label}: {_text(alert[key])}'
+                    f'</span>'
+                )
+
+        recommendation = alert.get(
+            "recommendation",
+            "Investigar o indicador antes de decidir o tratamento.",
+        )
+
+        alert_html.append(
+            '<article class="alert">'
+            f'<h3>{_text(labels.get(alert.get("type"), alert.get("type", "Alerta")))}</h3>'
+            f'<div class="chips">{"".join(details)}</div>'
+            f'<p><strong>Recomendação:</strong> '
+            f'{_text(recommendation)}</p>'
+            '</article>'
+        )
+
+    if not alert_html:
+        alert_html = [
+            '<p class="empty">Nenhum alerta encontrado pelas regras '
+            'implementadas. Isso não garante ausência de problemas.</p>'
+        ]
+
+    comparison_html = ""
+
+    if comparison is not None:
+        before = comparison.get("before", {})
+        after = comparison.get("after", {})
+
+        if not isinstance(before, dict) or not isinstance(after, dict):
+            raise ValueError(
+                "comparison precisa conter 'before' e 'after'."
+            )
+
+        rows = []
+
+        for key, label in metric_labels.items():
+            if key in before or key in after:
+                rows.append(
+                    f'<tr><th scope="row">{_text(label)}</th>'
+                    f'<td>{_number(before.get(key))}</td>'
+                    f'<td>{_number(after.get(key))}</td></tr>'
+                )
+
+        comparison_html = (
+            '<section class="panel">'
+            '<h2>Comparação antes e depois</h2>'
+            '<p class="muted">Indicadores agregados; '
+            'não identifica alterações individuais de registros.</p>'
+            '<div class="table-wrap"><table>'
+            '<thead><tr><th>Indicador</th>'
+            '<th>Antes</th><th>Depois</th></tr></thead>'
+            f'<tbody>{"".join(rows)}</tbody>'
+            '</table></div></section>'
+        )
+
+    generated = datetime.now().strftime("%d/%m/%Y %H:%M")
+
+    html = f"""<!doctype html>
+<html lang="pt-BR">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{_text(title)}</title>
+<style>
+:root {{
+    --bg: #f4f7fb;
+    --ink: #17243a;
+    --muted: #596b82;
+    --line: #dce5ef;
+    --brand: #2357a4;
+    --paper: #fff;
+}}
+* {{ box-sizing: border-box; }}
+body {{
+    margin: 0;
+    background: var(--bg);
+    font: 16px/1.55 system-ui, sans-serif;
+    color: var(--ink);
+}}
+header {{
+    background: linear-gradient(110deg, #17396d, #2862b1);
+    color: white;
+    padding: 38px max(24px, calc((100vw - 1040px)/2));
+}}
+header p {{ opacity: .88; margin: 6px 0 0; }}
+main {{
+    max-width: 1040px;
+    margin: 30px auto 70px;
+    padding: 0 20px;
+}}
+h1 {{ font-size: 2rem; margin: 0; }}
+h2 {{ margin: 0 0 14px; font-size: 1.25rem; }}
+h3 {{ margin: 0 0 8px; font-size: 1.03rem; }}
+.cards {{
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+    gap: 14px;
+    margin-bottom: 24px;
+}}
+.card, .panel {{
+    background: var(--paper);
+    border: 1px solid var(--line);
+    border-radius: 14px;
+    box-shadow: 0 4px 16px #17243a0a;
+}}
+.card {{ padding: 20px; }}
+.card .value {{
+    font-size: 2rem;
+    font-weight: 750;
+    color: var(--brand);
+}}
+.card .label {{
+    color: var(--muted);
+    font-size: .9rem;
+}}
+.panel {{ padding: 24px; margin-bottom: 22px; }}
+.alert {{
+    border-left: 4px solid #e6a43d;
+    background: #fffbf3;
+    padding: 16px 18px;
+    margin: 12px 0;
+    border-radius: 7px;
+}}
+.alert p {{ margin: 10px 0 0; }}
+.chips {{ display: flex; gap: 8px; flex-wrap: wrap; }}
+.chip {{
+    background: #e8eef7;
+    border-radius: 999px;
+    padding: 3px 10px;
+    font-size: .85rem;
+}}
+.muted, .empty {{ color: var(--muted); }}
+.table-wrap {{ overflow-x: auto; }}
+table {{ width: 100%; border-collapse: collapse; text-align: left; }}
+th, td {{ padding: 12px 14px; border-bottom: 1px solid var(--line); }}
+thead {{ background: #eaf1fa; }}
+footer {{
+    text-align: center;
+    color: var(--muted);
+    font-size: .85rem;
+    margin-top: 25px;
+}}
+@media print {{
+    body {{ background: white; }}
+    .panel, .card {{ box-shadow: none; break-inside: avoid; }}
+}}
+</style>
+</head>
+<body>
+<header>
+    <h1>{_text(title)}</h1>
+    <p>Gerado em {generated} · Diagnóstico automatizado</p>
+</header>
+<main>
+<section class="cards">
+    <div class="card">
+        <div class="label">Registros</div>
+        <div class="value">{_number(diagnosis.get("rows"))}</div>
+    </div>
+    <div class="card">
+        <div class="label">Colunas</div>
+        <div class="value">{_number(diagnosis.get("columns"))}</div>
+    </div>
+    <div class="card">
+        <div class="label">Alertas</div>
+        <div class="value">{len(alerts)}</div>
+    </div>
+    <div class="card">
+        <div class="label">Variável-alvo</div>
+        <div class="value" style="font-size:1.3rem;overflow-wrap:anywhere">
+            {_text(diagnosis.get("target") or "Não definida")}
+        </div>
+    </div>
+</section>
+
+<section class="panel">
+    <h2>Diagnóstico e recomendações</h2>
+    {"".join(alert_html)}
+</section>
+
+{comparison_html}
+
+<section class="panel">
+    <h2>Como interpretar</h2>
+    <p>Os alertas indicam situações que merecem investigação.
+    Valores extremos não são necessariamente erros, e nem toda
+    ausência ou duplicata deve ser removida. As recomendações
+    não substituem a análise do contexto dos dados.</p>
+</section>
+
+<footer>JlPrep · Relatório gerado localmente.</footer>
+</main>
+</body>
+</html>"""
+
+    path.write_text(html, encoding="utf-8")
+
+    if open_browser:
+        webbrowser.open(path.as_uri())
+
+    return path

jlprep-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: jlprep
+Version: 0.1.0
+Summary: Biblioteca Python para pré-processamento e análise da qualidade de dados
+Author: Joao Lucas Moreira de Sousa
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+
+# jlprep
+
+Biblioteca em Python para **análise e pré-processamento de dados** voltada para aplicações de Machine Learning.
+
+A `jlprep` foi desenvolvida como parte de um **Trabalho de Conclusão de Curso (TCC)**, com foco na análise e melhoria da qualidade de dados utilizados em modelos de Machine Learning.
+
+---
+
+## Objetivo
+
+A biblioteca busca centralizar etapas comuns do pré-processamento de dados, como:
+
+* Limpeza de dados
+* Codificação de variáveis categóricas
+* Análise exploratória
+* Avaliação da qualidade dos dados
+
+Além disso, fornece **diagnósticos interpretáveis**, auxiliando na tomada de decisão antes do treinamento de modelos de Machine Learning.
+
+---
+
+## Contexto do TCC
+
+Este projeto foi desenvolvido no contexto do tema:
+
+> **Qualidade dos dados em Machine Learning (dados faltantes, desbalanceados e ruidosos)**
+
+A proposta da `jlprep` é oferecer uma abordagem prática para identificação e tratamento desses problemas, reunindo funcionalidades essenciais em uma única biblioteca.
+
+---
+
+## Funcionalidades
+
+### Limpeza de dados
+
+* Remoção de valores duplicados
+* Tratamento de valores faltantes
+* Remoção de outliers
+
+### Transformação
+
+* Label Encoding
+* One-Hot Encoding
+
+### Exploração de dados
+
+* Resumo estatístico do dataset
+* Visualização da distribuição de valores
+
+### Qualidade dos dados
+
+* Verificação de inconsistências
+* Análise de desbalanceamento de classes
+* Sugestões de pré-processamento
+
+---
+
+## Instalação
+
+Clone o repositório e acesse a pasta do projeto.
+
+Em seguida, instale as dependências necessárias utilizando o arquivo `requirements.txt`:
+
+```bash
+python -m pip install -r requirements.txt
+```
+
+As principais dependências utilizadas pelo projeto são:
+
+* `pandas`
+* `matplotlib`
+* `pytest`
+
+---
+
+## Testes
+
+Os testes automatizados estão localizados na pasta `tests/`.
+
+Para executar todos os testes, utilize:
+
+```bash
+python -m pytest
+```
+
+Para executar um teste específico:
+
+```bash
+python -m pytest tests/test_encode_onehot.py
+```
+
+---
+
+## Exemplo de uso
+
+```python
+import pandas as pd
+
+from jlprep import check_class_balance
+
+df = pd.DataFrame({
+    "classe": ["A", "A", "B", "B", "A"]
+})
+
+resultado = check_class_balance(
+    df,
+    target="classe"
+)
+
+print(resultado)
+```
+
+A função retorna um dicionário contendo informações sobre a quantidade de classes, o tipo de classificação, o nível de desbalanceamento e uma sugestão de tratamento.
+
+---
+
+## Estrutura do projeto
+
+```text
+JlPrep/
+├── jlprep/
+│   ├── __init__.py
+│   ├── cleaning.py
+│   ├── encoding.py
+│   ├── exploration.py
+│   └── quality.py
+│
+├── tests/
+│   ├── test_clean_missing.py
+│   ├── test_encode_label.py
+│   ├── test_encode_onehot.py
+│   ├── test_remove_outliers.py
+│   └── test_check_class_balance.py
+│
+├── examples/
+├── requirements.txt
+└── README.md
+```
+
+---
+
+## Projeto acadêmico
+
+A `jlprep` foi desenvolvida como parte de um Trabalho de Conclusão de Curso, com o objetivo de aplicar conceitos de programação em Python, pré-processamento de dados, qualidade de dados e testes automatizados em uma biblioteca voltada para aplicações de Machine Learning.

jlprep-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+jlprep/__init__.py,sha256=G7F1Pm1CqC9h-0Yz-eDDd1z19iMhWULBtkO-EcUz2MM,1149
+jlprep/cleaning.py,sha256=VH5AwLuJIqOJtKFIZqM1Q0vGNoDxdNv1SKoovcnyJAk,6600
+jlprep/comparison.py,sha256=jFu23h_BCYRQstaFE68nG-dtdcIIb9mJgv0huQV_Vxc,1537
+jlprep/diagnostics.py,sha256=d3qH4YgVd7LKRUerrPTTYBlI-kgC_rYUhxgwfDFON4w,3760
+jlprep/encoding.py,sha256=-cmUGERgsxU-ulSFpZRXilCZqUaGMfml3uv8-Wu_nNI,3347
+jlprep/exploration.py,sha256=4A3sU3XUWDi5P7OMxkjMprNxfbUE8So0gU-LAt52Oc8,8136
+jlprep/quality.py,sha256=XnlzjUZ3uZdCUE1lc44uXYOO8s5zARchY2IeNQNJ0Pc,3517
+jlprep/reporting.py,sha256=l68p7gcX5FdrAszVB89mWu14J_xBFezrWTzwT6rLxtE,8266
+jlprep-0.1.0.dist-info/METADATA,sha256=obtheANuJN54oV-mqL_drF8Q87m0vLxmGXy8DlNLYBc,3962
+jlprep-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+jlprep-0.1.0.dist-info/top_level.txt,sha256=GZfxq8otRhKKyaFna4n68IIDh1P-ISwvT6Eh1jZlfrc,7
+jlprep-0.1.0.dist-info/RECORD,,

jlprep-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jlprep-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+jlprep