jlprep 0.1.0__tar.gz

jlprep-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,144 @@
+# 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/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-0.1.0/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-0.1.0/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"]
+            ),
+        },
+    }
+