ml-experiment-framework 0.1.0__py3-none-any.whl

__init__.py

@@ -0,0 +1,3 @@
+"""Classic Machine Learning Framework - dynamic, leakage-safe AutoML-style experimentation."""
+
+__version__ = "0.1.0"

data/__init__.py

@@ -0,0 +1,6 @@
+from .loader import load_dataset
+from .validator import validate_dataset
+from .profiler import profile_dataset
+from .splitter import split_data
+
+__all__ = ["load_dataset", "validate_dataset", "profile_dataset", "split_data"]

data/loader.py

@@ -0,0 +1,84 @@
+"""Data loading with support for CSV and Parquet; extensible registry."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, Dict, Optional, Union
+
+import pandas as pd
+
+from src.utils.logging import get_logger
+
+logger = get_logger("data.loader")
+
+LoaderFn = Callable[[Path], pd.DataFrame]
+
+_LOADERS: Dict[str, LoaderFn] = {}
+
+
+def register_loader(extension: str):
+    """Decorator to register a file-format loader."""
+
+    def decorator(fn: LoaderFn):
+        _LOADERS[extension.lower().lstrip(".")] = fn
+        return fn
+
+    return decorator
+
+
+@register_loader("csv")
+def _load_csv(path: Path) -> pd.DataFrame:
+    return pd.read_csv(path)
+
+
+@register_loader("parquet")
+@register_loader("pq")
+def _load_parquet(path: Path) -> pd.DataFrame:
+    return pd.read_parquet(path)
+
+
+def load_dataset(
+    path: Union[str, Path],
+    **kwargs,
+) -> pd.DataFrame:
+    """
+    Load a tabular dataset from disk.
+
+    Supported formats (by extension): csv, parquet.
+    Additional loaders can be registered via @register_loader.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Dataset file not found: {path}")
+    if not path.is_file():
+        raise ValueError(f"Path is not a file: {path}")
+
+    ext = path.suffix.lower().lstrip(".")
+    if ext not in _LOADERS:
+        raise ValueError(
+            f"Unsupported file format '.{ext}'. "
+            f"Supported: {sorted(_LOADERS.keys())}. "
+            "Register a new loader with @register_loader if needed."
+        )
+
+    logger.info(f"Loading dataset from {path}")
+    try:
+        df = _LOADERS[ext](path)
+    except Exception as e:
+        raise RuntimeError(f"Failed to read dataset {path}: {e}") from e
+
+    if df is None or len(df) == 0:
+        raise ValueError(f"Dataset is empty: {path}")
+
+    logger.info(f"Dataset shape: {df.shape[0]} rows × {df.shape[1]} columns")
+    return df
+
+
+def load_train_test(
+    train_path: Union[str, Path],
+    test_path: Optional[Union[str, Path]] = None,
+) -> tuple[pd.DataFrame, Optional[pd.DataFrame]]:
+    """Load train and optional external test datasets."""
+    train = load_dataset(train_path)
+    test = load_dataset(test_path) if test_path else None
+    return train, test

data/profiler.py

@@ -0,0 +1,182 @@
+"""EDA / profiling (exploratory only — no fit that affects final pipeline)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+import pandas as pd
+
+from src.utils.logging import get_logger
+
+logger = get_logger("data.profiler")
+
+
+def _safe_skew(s: pd.Series) -> float:
+    try:
+        return float(s.dropna().skew())
+    except Exception:
+        return float("nan")
+
+
+def profile_dataset(
+    df: pd.DataFrame,
+    target: Optional[str] = None,
+    feature_types: Optional[Dict[str, str]] = None,
+    artifacts_dir: Optional[Path] = None,
+    max_cat_levels: int = 20,
+) -> Dict[str, Any]:
+    """
+    Produce a structured EDA profile.
+
+    Plots are optional (written under artifacts_dir/plots if provided).
+    This function must never fit transformers used by the final model.
+    """
+    logger.info("Running EDA / profiling...")
+    profile: Dict[str, Any] = {
+        "overview": {
+            "n_rows": int(df.shape[0]),
+            "n_cols": int(df.shape[1]),
+            "memory_mb": float(df.memory_usage(deep=True).sum() / 1e6),
+            "dtypes": {c: str(t) for c, t in df.dtypes.items()},
+        },
+        "missing": {},
+        "numeric": {},
+        "categorical": {},
+        "target": {},
+        "duplicates": int(df.duplicated().sum()),
+    }
+
+    # Missing
+    miss = df.isna().sum()
+    miss_pct = (miss / len(df) * 100).round(2)
+    profile["missing"] = {
+        c: {"count": int(miss[c]), "pct": float(miss_pct[c])}
+        for c in df.columns
+        if miss[c] > 0
+    }
+
+    # Infer rough types if not provided
+    if feature_types is None:
+        feature_types = {}
+        for c in df.columns:
+            if c == target:
+                continue
+            if pd.api.types.is_numeric_dtype(df[c]):
+                feature_types[c] = "numeric"
+            else:
+                feature_types[c] = "categorical"
+
+    numeric_cols = [c for c, t in feature_types.items() if t == "numeric" and c in df.columns]
+    cat_cols = [c for c, t in feature_types.items() if t in ("categorical", "boolean") and c in df.columns]
+
+    for c in numeric_cols:
+        s = df[c]
+        profile["numeric"][c] = {
+            "mean": float(s.mean()) if s.notna().any() else None,
+            "median": float(s.median()) if s.notna().any() else None,
+            "std": float(s.std()) if s.notna().any() else None,
+            "min": float(s.min()) if s.notna().any() else None,
+            "max": float(s.max()) if s.notna().any() else None,
+            "skew": _safe_skew(s),
+            "n_unique": int(s.nunique(dropna=True)),
+            "n_missing": int(s.isna().sum()),
+        }
+
+    for c in cat_cols:
+        s = df[c]
+        vc = s.value_counts(dropna=False).head(max_cat_levels)
+        profile["categorical"][c] = {
+            "n_unique": int(s.nunique(dropna=True)),
+            "n_missing": int(s.isna().sum()),
+            "top_values": {str(k): int(v) for k, v in vc.items()},
+        }
+
+    if target and target in df.columns:
+        y = df[target]
+        if pd.api.types.is_numeric_dtype(y) and y.nunique(dropna=True) > 20:
+            profile["target"] = {
+                "type": "regression",
+                "mean": float(y.mean()),
+                "median": float(y.median()),
+                "std": float(y.std()),
+                "min": float(y.min()),
+                "max": float(y.max()),
+                "skew": _safe_skew(y),
+                "n_missing": int(y.isna().sum()),
+            }
+        else:
+            vc = y.value_counts(dropna=False)
+            profile["target"] = {
+                "type": "classification",
+                "n_classes": int(y.nunique(dropna=True)),
+                "distribution": {str(k): int(v) for k, v in vc.items()},
+                "n_missing": int(y.isna().sum()),
+            }
+
+    # Optional plots
+    if artifacts_dir is not None:
+        try:
+            _write_basic_plots(df, target, numeric_cols, cat_cols, Path(artifacts_dir))
+        except Exception as e:
+            logger.warning(f"Could not write EDA plots: {e}")
+
+    logger.info(
+        f"EDA complete — numeric: {len(numeric_cols)}, categorical: {len(cat_cols)}, "
+        f"columns with missing: {len(profile['missing'])}"
+    )
+    return profile
+
+
+def _write_basic_plots(
+    df: pd.DataFrame,
+    target: Optional[str],
+    numeric_cols: List[str],
+    cat_cols: List[str],
+    artifacts_dir: Path,
+) -> None:
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    import seaborn as sns
+
+    plot_dir = artifacts_dir / "plots"
+    plot_dir.mkdir(parents=True, exist_ok=True)
+
+    # Missing heatmap (sample columns if many)
+    miss_cols = [c for c in df.columns if df[c].isna().any()][:30]
+    if miss_cols:
+        fig, ax = plt.subplots(figsize=(10, 4))
+        sns.heatmap(df[miss_cols].isna(), cbar=False, ax=ax, yticklabels=False)
+        ax.set_title("Missing values (subset of columns)")
+        fig.tight_layout()
+        fig.savefig(plot_dir / "missing_heatmap.png", dpi=100)
+        plt.close(fig)
+
+    # Target distribution
+    if target and target in df.columns:
+        fig, ax = plt.subplots(figsize=(6, 4))
+        y = df[target]
+        if pd.api.types.is_numeric_dtype(y) and y.nunique() > 20:
+            ax.hist(y.dropna(), bins=40, edgecolor="black", alpha=0.7)
+            ax.set_title(f"Target distribution: {target}")
+        else:
+            y.value_counts().plot(kind="bar", ax=ax)
+            ax.set_title(f"Target class distribution: {target}")
+        fig.tight_layout()
+        fig.savefig(plot_dir / "target_distribution.png", dpi=100)
+        plt.close(fig)
+
+    # Numeric correlations (sample)
+    num = [c for c in numeric_cols if c != target][:15]
+    if len(num) >= 2:
+        fig, ax = plt.subplots(figsize=(8, 6))
+        corr = df[num].corr(numeric_only=True)
+        sns.heatmap(corr, ax=ax, cmap="RdBu_r", center=0, annot=False)
+        ax.set_title("Numeric feature correlations (subset)")
+        fig.tight_layout()
+        fig.savefig(plot_dir / "correlation_heatmap.png", dpi=100)
+        plt.close(fig)
+
+    logger.info(f"EDA plots saved to {plot_dir}")

data/splitter.py

@@ -0,0 +1,70 @@
+"""Train/test split — always before any learned preprocessing."""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+import pandas as pd
+from sklearn.model_selection import train_test_split
+
+from src.utils.logging import get_logger
+
+logger = get_logger("data.splitter")
+
+
+def split_data(
+    df: pd.DataFrame,
+    target: str,
+    test_size: float = 0.2,
+    random_state: int = 42,
+    stratify: bool | str = "auto",
+    problem_type: Optional[str] = None,
+) -> Tuple[pd.DataFrame, pd.DataFrame, pd.Series, pd.Series]:
+    """
+    Split into X_train, X_test, y_train, y_test.
+
+    Stratification is used for classification when appropriate.
+    """
+    if target not in df.columns:
+        raise ValueError(f"Target '{target}' not in dataframe columns.")
+
+    # Drop rows with missing target
+    mask = df[target].notna()
+    n_drop = int((~mask).sum())
+    if n_drop > 0:
+        logger.warning(f"Dropping {n_drop} rows with missing target before split.")
+        df = df.loc[mask].copy()
+
+    y = df[target]
+    X = df.drop(columns=[target])
+
+    use_stratify = False
+    if stratify == "auto":
+        if problem_type and "classification" in problem_type:
+            # Stratify only if every class has enough samples
+            min_count = y.value_counts().min()
+            if min_count >= 2 and test_size * len(y) >= y.nunique():
+                use_stratify = True
+            else:
+                logger.warning(
+                    "Stratification disabled: some classes have too few samples for stratified split."
+                )
+        use_stratify = use_stratify
+    elif stratify is True:
+        use_stratify = True
+
+    stratify_arr = y if use_stratify else None
+
+    X_train, X_test, y_train, y_test = train_test_split(
+        X,
+        y,
+        test_size=test_size,
+        random_state=random_state,
+        stratify=stratify_arr,
+    )
+
+    logger.info(
+        f"Split — train: {len(X_train)} rows, test: {len(X_test)} rows "
+        f"(test_size={test_size}, stratify={use_stratify})"
+    )
+    return X_train, X_test, y_train, y_test

data/validator.py

@@ -0,0 +1,106 @@
+"""Dataset validation before any modeling."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+
+from src.utils.logging import get_logger
+
+logger = get_logger("data.validator")
+
+
+@dataclass
+class ValidationReport:
+    n_rows: int
+    n_cols: int
+    n_duplicates: int
+    target_present: bool
+    target_missing: int
+    issues: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+    dtypes: Dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "n_rows": self.n_rows,
+            "n_cols": self.n_cols,
+            "n_duplicates": self.n_duplicates,
+            "target_present": self.target_present,
+            "target_missing": self.target_missing,
+            "issues": self.issues,
+            "warnings": self.warnings,
+            "dtypes": self.dtypes,
+        }
+
+
+def validate_dataset(
+    df: pd.DataFrame,
+    target: Optional[str] = None,
+    require_target: bool = True,
+) -> ValidationReport:
+    """
+    Validate basic integrity of a dataset.
+
+    Raises ValueError on critical issues (empty, missing target when required).
+    """
+    issues: List[str] = []
+    warnings: List[str] = []
+
+    n_rows, n_cols = df.shape
+    if n_rows == 0:
+        raise ValueError("Dataset has zero rows.")
+    if n_cols == 0:
+        raise ValueError("Dataset has zero columns.")
+
+    n_duplicates = int(df.duplicated().sum())
+    if n_duplicates > 0:
+        warnings.append(f"Found {n_duplicates} duplicate rows ({100 * n_duplicates / n_rows:.1f}%).")
+
+    target_present = False
+    target_missing = 0
+    if target is not None:
+        if target not in df.columns:
+            if require_target:
+                raise ValueError(
+                    f"Target column '{target}' was not found. "
+                    f"Available columns: {list(df.columns)[:20]}{'...' if len(df.columns) > 20 else ''}"
+                )
+            issues.append(f"Target column '{target}' not found.")
+        else:
+            target_present = True
+            target_missing = int(df[target].isna().sum())
+            if target_missing > 0:
+                warnings.append(
+                    f"Target '{target}' has {target_missing} missing values "
+                    f"({100 * target_missing / n_rows:.1f}%). Rows with missing target will be dropped."
+                )
+            n_unique = df[target].nunique(dropna=True)
+            if n_unique < 2 and require_target:
+                raise ValueError(
+                    f"Target '{target}' has fewer than 2 unique values (n_unique={n_unique}). "
+                    "Cannot train a supervised model."
+                )
+
+    dtypes = {c: str(df[c].dtype) for c in df.columns}
+
+    report = ValidationReport(
+        n_rows=n_rows,
+        n_cols=n_cols,
+        n_duplicates=n_duplicates,
+        target_present=target_present,
+        target_missing=target_missing,
+        issues=issues,
+        warnings=warnings,
+        dtypes=dtypes,
+    )
+
+    for w in warnings:
+        logger.warning(w)
+    for i in issues:
+        logger.error(i)
+
+    logger.info(f"Validation OK — {n_rows} rows, {n_cols} columns, {n_duplicates} duplicates")
+    return report

detection/__init__.py

@@ -0,0 +1,5 @@
+from .problem_type import detect_problem_type
+from .feature_types import detect_feature_types
+from .target import analyze_target
+
+__all__ = ["detect_problem_type", "detect_feature_types", "analyze_target"]