rage-tools 0.1.0__py3-none-any.whl

rage_tools/__init__.py

@@ -0,0 +1,75 @@
+from .data_cleaning import (
+    clean_column_names,
+    remove_duplicates,
+    missing_value_summary,
+    handle_missing_values,
+)
+from .eda import (
+    dataset_overview,
+    numeric_summary,
+    categorical_summary,
+    detect_outliers_iqr,
+)
+from .preprocessing import (
+    cap_outliers_iqr,
+    scale_numeric_features,
+    encode_categorical,
+    split_features_target,
+    auto_preprocess,  # <-- Added here!
+)
+from .evaluation import (
+    evaluate_regression,
+    evaluate_classification,
+)
+from .utils import (
+    timer,
+    reduce_memory_usage,
+)
+
+__all__ = [
+    "clean_column_names",
+    "remove_duplicates",
+    "missing_value_summary",
+    "handle_missing_values",
+    "dataset_overview",
+    "numeric_summary",
+    "categorical_summary",
+    "detect_outliers_iqr",
+    "cap_outliers_iqr",
+    "scale_numeric_features",
+    "encode_categorical",
+    "split_features_target",
+    "auto_preprocess",  # <-- And added here!
+    "evaluate_regression",
+    "evaluate_classification",
+    "timer",
+    "reduce_memory_usage",
+]
+
+from .data_cleaning import (
+    clean_column_names,
+    remove_duplicates,
+    missing_value_summary,
+    handle_missing_values,
+)
+from .eda import (
+    dataset_overview,
+    numeric_summary,
+    categorical_summary,
+    detect_outliers_iqr,
+)
+from .preprocessing import (
+    cap_outliers_iqr,
+    scale_numeric_features,
+    encode_categorical,
+    split_features_target,
+    auto_preprocess,
+)
+from .evaluation import (
+    evaluate_regression,
+    evaluate_classification,
+)
+from .utils import (
+    timer,
+    reduce_memory_usage,
+)

rage_tools/data_cleaning.py

@@ -0,0 +1,78 @@
+# Missing values, duplicates, column names
+import pandas as pd
+from typing import Optional, List, Union
+
+
+def clean_column_names(df: pd.DataFrame) -> pd.DataFrame:
+    """Standardize DataFrame column names to snake_case."""
+    df = df.copy()
+    df.columns = (
+        df.columns
+        .str.strip()
+        .str.lower()
+        .str.replace(r"\s+", "_", regex=True)
+        .str.replace(r"[^a-z0-9_]", "", regex=True)
+    )
+    return df
+
+
+def remove_duplicates(
+    df: pd.DataFrame, 
+    subset: Optional[List[str]] = None, 
+    keep: str = "first"
+) -> pd.DataFrame:
+    """Drop duplicate rows and reset the index."""
+    df = df.copy()
+    df = df.drop_duplicates(subset=subset, keep=keep).reset_index(drop=True)
+    return df
+
+
+def missing_value_summary(df: pd.DataFrame) -> pd.DataFrame:
+    """Return a summary table of columns containing missing values."""
+    missing_count = df.isna().sum()
+    missing_pct = (missing_count / len(df)) * 100
+
+    summary = pd.DataFrame({
+        "missing_count": missing_count,
+        "missing_pct": missing_pct.round(2),
+        "dtype": df.dtypes
+    })
+    return summary[summary["missing_count"] > 0].sort_values(
+        by="missing_pct", ascending=False
+    )
+
+
+def handle_missing_values(
+    df: pd.DataFrame,
+    numeric_strategy: str = "median",
+    categorical_strategy: str = "mode",
+    fill_value: Optional[Union[str, int, float]] = None
+) -> pd.DataFrame:
+    """
+    Fill missing values automatically across numeric and categorical columns.
+    numeric_strategy: 'mean', 'median', or 'zero'
+    categorical_strategy: 'mode' or 'constant'
+    """
+    df = df.copy()
+    
+    # 1. Handle Numeric Columns
+    num_cols = df.select_dtypes(include=["number"]).columns
+    for col in num_cols:
+        if df[col].isna().sum() > 0:
+            if numeric_strategy == "median":
+                df[col] = df[col].fillna(df[col].median())
+            elif numeric_strategy == "mean":
+                df[col] = df[col].fillna(df[col].mean())
+            elif numeric_strategy == "zero":
+                df[col] = df[col].fillna(0)
+
+    # 2. Handle Categorical / Object Columns
+    cat_cols = df.select_dtypes(include=["object", "category"]).columns
+    for col in cat_cols:
+        if df[col].isna().sum() > 0:
+            if categorical_strategy == "mode" and not df[col].mode().empty:
+                df[col] = df[col].fillna(df[col].mode()[0])
+            elif categorical_strategy == "constant":
+                df[col] = df[col].fillna(fill_value if fill_value is not None else "Unknown")
+
+    return df

rage_tools/eda.py

@@ -0,0 +1,95 @@
+# Statistics, correlations, outliers
+
+# Dataset overview, numeric/categorical summaries, and outlier detection
+import pandas as pd
+import numpy as np
+from typing import Dict, Any
+
+
+def dataset_overview(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Generate a comprehensive column-by-column health report of the DataFrame
+    (dtype, missing count/%, unique values, and sample value).
+    """
+    overview = pd.DataFrame({
+        "dtype": df.dtypes,
+        "non_null_count": df.notna().sum(),
+        "missing_count": df.isna().sum(),
+        "missing_pct": ((df.isna().sum() / len(df)) * 100).round(2),
+        "unique_values": df.nunique(),
+        "sample_value": [df[col].dropna().iloc[0] if not df[col].dropna().empty else None for col in df.columns]
+    })
+    return overview
+
+
+def numeric_summary(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Extended descriptive statistics for numeric columns, including 
+    skewness, kurtosis, and Interquartile Range (IQR).
+    """
+    num_df = df.select_dtypes(include=["number"])
+    if num_df.empty:
+        return pd.DataFrame()
+
+    stats = num_df.describe().T
+    stats["skewness"] = num_df.skew().round(3)
+    stats["kurtosis"] = num_df.kurt().round(3)
+    stats["iqr"] = (stats["75%"] - stats["25%"]).round(3)
+    return stats.round(3)
+
+
+def categorical_summary(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Summary of categorical/object columns showing unique classes,
+    most frequent value (top), and its percentage share.
+    """
+    cat_df = df.select_dtypes(include=["object", "category"])
+    if cat_df.empty:
+        return pd.DataFrame()
+
+    records = []
+    for col in cat_df.columns:
+        non_null = cat_df[col].dropna()
+        top_val = non_null.mode().iloc[0] if not non_null.empty else None
+        top_freq = (non_null == top_val).sum() if top_val is not None else 0
+        
+        records.append({
+            "column": col,
+            "unique_classes": cat_df[col].nunique(),
+            "top_value": top_val,
+            "top_freq": top_freq,
+            "top_pct": round((top_freq / len(df)) * 100, 2) if len(df) > 0 else 0.0
+        })
+
+    return pd.DataFrame(records).set_index("column")
+
+
+def detect_outliers_iqr(df: pd.DataFrame, factor: float = 1.5) -> pd.DataFrame:
+    """
+    Detect outliers in numeric columns using the 1.5 * IQR rule.
+    Returns a summary table of outlier counts, percentages, and bounds.
+    """
+    num_df = df.select_dtypes(include=["number"])
+    records = []
+
+    for col in num_df.columns:
+        series = num_df[col].dropna()
+        if series.empty:
+            continue
+            
+        q1 = series.quantile(0.25)
+        q3 = series.quantile(0.75)
+        iqr = q3 - q1
+        lower_bound = q1 - (factor * iqr)
+        upper_bound = q3 + (factor * iqr)
+
+        outliers = series[(series < lower_bound) | (series > upper_bound)]
+        records.append({
+            "column": col,
+            "outlier_count": len(outliers),
+            "outlier_pct": round((len(outliers) / len(df)) * 100, 2),
+            "lower_bound": round(lower_bound, 2),
+            "upper_bound": round(upper_bound, 2)
+        })
+
+    return pd.DataFrame(records).set_index("column")

rage_tools/evaluation.py

@@ -0,0 +1,75 @@
+# Model metrics and evaluation helpers
+
+# Regression and Classification evaluation metrics
+import numpy as np
+import pandas as pd
+from typing import Union, Optional
+
+ArrayLike = Union[pd.Series, np.ndarray, list]
+
+
+def evaluate_regression(
+    y_true: ArrayLike, 
+    y_pred: ArrayLike, 
+    n_features: Optional[int] = None
+) -> pd.DataFrame:
+    """
+    Calculate MAE, MSE, RMSE, R2, and (optionally) Adjusted R2 for regression models.
+    """
+    y_t = np.asarray(y_true, dtype=float)
+    y_p = np.asarray(y_pred, dtype=float)
+
+    mae = np.mean(np.abs(y_t - y_p))
+    mse = np.mean((y_t - y_p) ** 2)
+    rmse = np.sqrt(mse)
+
+    ss_res = np.sum((y_t - y_p) ** 2)
+    ss_tot = np.sum((y_t - np.mean(y_t)) ** 2)
+    r2 = 1 - (ss_res / ss_tot) if ss_tot != 0 else 0.0
+
+    metrics = {
+        "MAE": round(mae, 4),
+        "MSE": round(mse, 4),
+        "RMSE": round(rmse, 4),
+        "R2": round(r2, 4),
+    }
+
+    if n_features is not None and len(y_t) > n_features + 1:
+        n = len(y_t)
+        adj_r2 = 1 - ((1 - r2) * (n - 1) / (n - n_features - 1))
+        metrics["Adjusted_R2"] = round(adj_r2, 4)
+
+    return pd.DataFrame([metrics], index=["Regression Metrics"])
+
+
+def evaluate_classification(y_true: ArrayLike, y_pred: ArrayLike) -> pd.DataFrame:
+    """
+    Calculate Accuracy, Precision, Recall, F1-Score, and Confusion Matrix counts
+    for binary classification (0 and 1).
+    """
+    y_t = np.asarray(y_true, dtype=int)
+    y_p = np.asarray(y_pred, dtype=int)
+
+    tp = int(np.sum((y_t == 1) & (y_p == 1)))
+    tn = int(np.sum((y_t == 0) & (y_p == 0)))
+    fp = int(np.sum((y_t == 0) & (y_p == 1)))
+    fn = int(np.sum((y_t == 1) & (y_p == 0)))
+
+    total = len(y_t)
+    accuracy = (tp + tn) / total if total > 0 else 0.0
+    precision = tp / (tp + fp) if (tp + fp) > 0 else 0.0
+    recall = tp / (tp + fn) if (tp + fn) > 0 else 0.0
+    f1 = (2 * precision * recall) / (precision + recall) if (precision + recall) > 0 else 0.0
+
+    metrics = {
+        "Accuracy": round(accuracy, 4),
+        "Precision": round(precision, 4),
+        "Recall": round(recall, 4),
+        "F1_Score": round(f1, 4),
+        "TP": tp,
+        "TN": tn,
+        "FP": fp,
+        "FN": fn,
+    }
+
+    return pd.DataFrame([metrics], index=["Classification Metrics"])

rage_tools/preprocessing.py

@@ -0,0 +1,161 @@
+# Outlier capping, feature scaling, categorical encoding, train-test split, and auto-pipeline
+import re
+import pandas as pd
+import numpy as np
+from typing import List, Optional, Tuple
+
+from rage_tools.data_cleaning import (
+    clean_column_names,
+    remove_duplicates,
+    handle_missing_values,
+)
+from rage_tools.utils import timer, reduce_memory_usage
+
+
+def cap_outliers_iqr(
+    df: pd.DataFrame, 
+    columns: Optional[List[str]] = None, 
+    factor: float = 1.5
+) -> pd.DataFrame:
+    """
+    Cap (clip) extreme outliers in numeric columns to the lower and upper IQR bounds
+    instead of dropping rows.
+    """
+    df = df.copy()
+    if columns is None:
+        columns = df.select_dtypes(include=["number"]).columns.tolist()
+
+    for col in columns:
+        q1 = df[col].quantile(0.25)
+        q3 = df[col].quantile(0.75)
+        iqr = q3 - q1
+        lower_bound = q1 - (factor * iqr)
+        upper_bound = q3 + (factor * iqr)
+        df[col] = df[col].clip(lower=lower_bound, upper=upper_bound)
+
+    return df
+
+
+def scale_numeric_features(
+    df: pd.DataFrame, 
+    columns: Optional[List[str]] = None, 
+    method: str = "standard"
+) -> pd.DataFrame:
+    """
+    Scale numeric features using 'standard' (Z-score) or 'minmax' (0 to 1) scaling.
+    """
+    df = df.copy()
+    if columns is None:
+        columns = df.select_dtypes(include=["number"]).columns.tolist()
+
+    for col in columns:
+        if method == "standard":
+            std = df[col].std()
+            if std != 0 and not np.isnan(std):
+                df[col] = (df[col] - df[col].mean()) / std
+        elif method == "minmax":
+            min_val = df[col].min()
+            max_val = df[col].max()
+            if max_val != min_val:
+                df[col] = (df[col] - min_val) / (max_val - min_val)
+        else:
+            raise ValueError("method must be 'standard' or 'minmax'")
+
+    return df
+
+
+def encode_categorical(
+    df: pd.DataFrame, 
+    columns: Optional[List[str]] = None, 
+    drop_first: bool = True
+) -> pd.DataFrame:
+    """
+    One-hot encode categorical columns and return numeric (0/1) columns.
+    """
+    df = df.copy()
+    if columns is None:
+        columns = df.select_dtypes(include=["object", "category"]).columns.tolist()
+
+    if not columns:
+        return df
+
+    return pd.get_dummies(df, columns=columns, drop_first=drop_first, dtype=int)
+
+
+def split_features_target(
+    df: pd.DataFrame, 
+    target_col: str, 
+    test_size: float = 0.2, 
+    random_state: int = 42
+) -> Tuple[pd.DataFrame, pd.DataFrame, pd.Series, pd.Series]:
+    """
+    Shuffle and split DataFrame into X_train, X_test, y_train, y_test.
+    """
+    if target_col not in df.columns:
+        raise ValueError(f"Target column '{target_col}' not found in DataFrame.")
+
+    df_shuffled = df.sample(frac=1.0, random_state=random_state).reset_index(drop=True)
+    split_idx = int(len(df_shuffled) * (1 - test_size))
+
+    train_df = df_shuffled.iloc[:split_idx]
+    test_df = df_shuffled.iloc[split_idx:]
+
+    X_train = train_df.drop(columns=[target_col])
+    y_train = train_df[target_col]
+    X_test = test_df.drop(columns=[target_col])
+    y_test = test_df[target_col]
+
+    return X_train, X_test, y_train, y_test
+
+
+@timer
+def auto_preprocess(
+    df: pd.DataFrame,
+    target_col: Optional[str] = None,
+    cap_outliers: bool = True,
+    scale_method: Optional[str] = "standard",
+    encode_cats: bool = True,
+    optimize_memory: bool = True,
+) -> pd.DataFrame:
+    """
+    Master 1-click pipeline:
+    1. Cleans column names
+    2. Removes duplicates
+    3. Imputes missing values
+    4. Caps IQR outliers (excluding target_col)
+    5. Scales numeric features (excluding target_col)
+    6. One-hot encodes categorical features (excluding target_col)
+    7. Optimizes memory usage
+    """
+    df = clean_column_names(df)
+    df = remove_duplicates(df)
+    df = handle_missing_values(df)
+
+    # Clean target_col name the exact same way clean_column_names does
+    target_clean = None
+    if target_col:
+        target_clean = re.sub(r"\s+", "_", target_col.strip().lower())
+        target_clean = re.sub(r"[^a-z0-9_]", "", target_clean)
+
+    num_cols = [
+        c for c in df.select_dtypes(include=["number"]).columns 
+        if c != target_clean
+    ]
+    cat_cols = [
+        c for c in df.select_dtypes(include=["object", "category"]).columns 
+        if c != target_clean
+    ]
+
+    if cap_outliers and num_cols:
+        df = cap_outliers_iqr(df, columns=num_cols)
+
+    if scale_method and num_cols:
+        df = scale_numeric_features(df, columns=num_cols, method=scale_method)
+
+    if encode_cats and cat_cols:
+        df = encode_categorical(df, columns=cat_cols, drop_first=True)
+
+    if optimize_memory:
+        df = reduce_memory_usage(df, verbose=True)
+
+    return df

rage_tools/utils.py

@@ -0,0 +1,52 @@
+# General reusable functions
+
+# Memory optimization, execution timer decorator, and reproducibility helpers
+import time
+import functools
+import numpy as np
+import pandas as pd
+from typing import Callable, Any
+
+
+def timer(func: Callable) -> Callable:
+    """Decorator to measure and print the execution time of any function."""
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs) -> Any:
+        start_time = time.perf_counter()
+        result = func(*args, **kwargs)
+        elapsed = time.perf_counter() - start_time
+        print(f"[TIMER] '{func.__name__}' executed in {elapsed:.4f}s")
+        return result
+    return wrapper
+
+
+def reduce_memory_usage(df: pd.DataFrame, verbose: bool = True) -> pd.DataFrame:
+    """
+    Downcast numeric columns (int64/float64) to the smallest safe subtype
+    to save RAM on large datasets.
+    """
+    df = df.copy()
+    start_mem = df.memory_usage().sum() / (1024 ** 2)
+
+    for col in df.select_dtypes(include=["int", "float"]).columns:
+        col_type = df[col].dtype
+        c_min = df[col].min()
+        c_max = df[col].max()
+
+        if str(col_type).startswith("int"):
+            if c_min > np.iinfo(np.int8).min and c_max < np.iinfo(np.int8).max:
+                df[col] = df[col].astype(np.int8)
+            elif c_min > np.iinfo(np.int16).min and c_max < np.iinfo(np.int16).max:
+                df[col] = df[col].astype(np.int16)
+            elif c_min > np.iinfo(np.int32).min and c_max < np.iinfo(np.int32).max:
+                df[col] = df[col].astype(np.int32)
+        else:
+            if c_min > np.finfo(np.float32).min and c_max < np.finfo(np.float32).max:
+                df[col] = df[col].astype(np.float32)
+
+    end_mem = df.memory_usage().sum() / (1024 ** 2)
+    if verbose:
+        reduction = 100 * (start_mem - end_mem) / start_mem if start_mem > 0 else 0
+        print(f"Memory reduced from {start_mem:.4f} MB to {end_mem:.4f} MB ({reduction:.1f}% saved)")
+
+    return df

rage_tools-0.1.0.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: rage-tools
+Version: 0.1.0
+Summary: RAGE Data Science & ML Toolkit for fast cleaning, EDA, preprocessing, and evaluation.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: numpy>=1.24.0
+
+# 🛠️ ds_toolkit
+
+A fast, modular Python library for automating daily Data Science & Machine Learning workflows.
+
+## 🚀 Installation (Editable Mode)
+```bash
+pip install -e .

rage_tools-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+rage_tools/__init__.py,sha256=InEHcLusWCNUQs6hl569ppWimRSLopf0EHe9MVWlL8Q,1651
+rage_tools/data_cleaning.py,sha256=MV-PVXOuVToTsyeeCds6FduCsXTyx_udJKocreYJxeU,2635
+rage_tools/eda.py,sha256=Tf0QUAVuXNl4MOwu_mAKYV4ow6-wwUb6TpFM5GfeQ6A,3283
+rage_tools/evaluation.py,sha256=FbxLDRHprVyS-dRmagMKQjlPPrpUxR1PHg3ZyqNGWM4,2336
+rage_tools/preprocessing.py,sha256=BO_n95HrmjE4jcLlYdAoc8P082aQDDacagzELS7IlY0,4927
+rage_tools/utils.py,sha256=Bu0PcMi9FBLk1mGYXDkaBjwUeXhFXbNqhsTTDlGU0kg,1998
+rage_tools-0.1.0.dist-info/METADATA,sha256=F8FTqPC_dmzibwCw0cNaXWYI8PJLejF2sv6ihVQEDq8,467
+rage_tools-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rage_tools-0.1.0.dist-info/top_level.txt,sha256=b3xFrOfZkbaIf2S247-KuNfQlxPcY-KCqlE0Phjr_wY,11
+rage_tools-0.1.0.dist-info/RECORD,,

rage_tools-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
+

rage_tools-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rage_tools