easyclassifier 0.8.1__py3-none-any.whl

easyclassifier/models.py

@@ -0,0 +1,94 @@
+"""Classifier registry (Phase 10 & 23).
+
+Each classifier is registered with a key, a friendly name, and a factory. New
+algorithms can be added here without touching the wizard. Optional
+dependencies (XGBoost, LightGBM) are detected gracefully.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Dict, List
+
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.linear_model import LogisticRegression
+from sklearn.naive_bayes import GaussianNB
+from sklearn.neural_network import MLPClassifier
+from sklearn.svm import SVC
+from sklearn.tree import DecisionTreeClassifier
+
+from .distances import make_knn
+
+
+@dataclass
+class ClassifierSpec:
+    key: str
+    name: str
+    factory: Callable[[], object]
+    help_key: str
+    available: bool = True
+    reason: str = ""
+
+
+# Every classifier that uses randomness gets a fixed seed, so the same data
+# and EasyClassifier version always give exactly the same results.
+SEED = 0
+
+
+def _svc():
+    # probability=True lets us compute ROC AUC / PR curves.
+    return SVC(probability=True, random_state=SEED)
+
+
+def _xgb_factory():
+    from xgboost import XGBClassifier
+    return XGBClassifier(eval_metric="logloss", verbosity=0,
+                         random_state=SEED)
+
+
+def _lgbm_factory():
+    from lightgbm import LGBMClassifier
+    return LGBMClassifier(verbose=-1, random_state=SEED)
+
+
+def _optional(key, name, factory, help_key, module) -> ClassifierSpec:
+    try:
+        __import__(module)
+        return ClassifierSpec(key, name, factory, help_key, True)
+    except Exception:  # noqa: BLE001
+        return ClassifierSpec(
+            key, name, factory, help_key, False,
+            reason=f"install '{module}' to enable",
+        )
+
+
+def build_registry() -> Dict[str, ClassifierSpec]:
+    specs = [
+        ClassifierSpec("decision_tree", "Decision Tree",
+                       lambda: DecisionTreeClassifier(random_state=SEED),
+                       "decision_tree"),
+        ClassifierSpec("random_forest", "Random Forest",
+                       lambda: RandomForestClassifier(random_state=SEED),
+                       "random_forest"),
+        ClassifierSpec("svm", "Support Vector Machine (SVM)",
+                       _svc, "svm"),
+        ClassifierSpec("logistic_regression", "Logistic Regression",
+                       lambda: LogisticRegression(max_iter=1000),
+                       "logistic_regression"),
+        ClassifierSpec("knn", "K-Nearest Neighbours (KNN)",
+                       lambda: make_knn("hassanat", 5), "knn"),
+        ClassifierSpec("naive_bayes", "Naive Bayes",
+                       GaussianNB, "naive_bayes"),
+        _optional("xgboost", "XGBoost", _xgb_factory, "xgboost", "xgboost"),
+        _optional("lightgbm", "LightGBM", _lgbm_factory, "lightgbm",
+                  "lightgbm"),
+        ClassifierSpec("neural_network", "Neural Network (MLP)",
+                       lambda: MLPClassifier(max_iter=500,
+                                             random_state=SEED),
+                       "neural_network"),
+    ]
+    return {s.key: s for s in specs}
+
+
+def available_specs(registry: Dict[str, ClassifierSpec]) -> List[ClassifierSpec]:
+    return list(registry.values())

easyclassifier/preprocessing.py

@@ -0,0 +1,219 @@
+"""Data cleaning, encoding, and scaling - leakage-safe.
+
+Two kinds of step are handled differently:
+
+* Row-level steps that learn nothing from the data (removing duplicate rows,
+  removing rows with missing values, casting text columns to text) are applied
+  once, before any train/test split.
+
+* Steps that *learn* something from the data (the mean/median used to fill
+  gaps, the scaling range, the list of categories) are placed inside a
+  scikit-learn Pipeline. During hold-out or cross-validation the pipeline is
+  re-fitted on each training part only, so no information from the test part
+  leaks into training.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+from sklearn.compose import ColumnTransformer
+from sklearn.impute import SimpleImputer
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import (
+    LabelEncoder,
+    MinMaxScaler,
+    OneHotEncoder,
+    OrdinalEncoder,
+    StandardScaler,
+)
+
+
+# --------------------------------------------------------------------------- #
+# Row-level cleaning (no learned statistics -> safe before splitting)
+# --------------------------------------------------------------------------- #
+
+def drop_missing_target(df: pd.DataFrame, target: str) -> Tuple[pd.DataFrame, int]:
+    """Rows without a class label cannot be used for training or testing."""
+    before = len(df)
+    df = df.dropna(subset=[target]).reset_index(drop=True)
+    return df, before - len(df)
+
+
+def drop_missing_rows(df: pd.DataFrame) -> Tuple[pd.DataFrame, int]:
+    before = len(df)
+    df = df.dropna().reset_index(drop=True)
+    return df, before - len(df)
+
+
+def duplicates_expected_by_chance(df: pd.DataFrame,
+                                  factor: float = 10.0) -> bool:
+    """True if identical rows are expected between *different* cases.
+
+    With few columns that each take few values (e.g. sex, region, a 0-24
+    score), different people often give identical answers; such rows are
+    real observations and must be kept. Only when the columns allow far more
+    combinations than there are rows (at least ``factor`` times as many) is
+    an identical row likely to be an accidental copy.
+    """
+    combos = 1.0
+    for c in df.columns:
+        combos *= max(1, df[c].nunique(dropna=False))
+        if combos >= factor * len(df):
+            return False
+    return True
+
+
+def remove_duplicates(df: pd.DataFrame) -> Tuple[pd.DataFrame, int]:
+    before = len(df)
+    df = df.drop_duplicates().reset_index(drop=True)
+    return df, before - len(df)
+
+
+def categorical_columns(X: pd.DataFrame) -> List[str]:
+    return [c for c in X.columns if not pd.api.types.is_numeric_dtype(X[c])]
+
+
+def numeric_columns(X: pd.DataFrame) -> List[str]:
+    return [c for c in X.columns if pd.api.types.is_numeric_dtype(X[c])]
+
+
+def cast_categoricals(X: pd.DataFrame) -> pd.DataFrame:
+    """Make every non-numeric column plain text (missing values stay missing).
+
+    This is a type conversion only; nothing is learned from the data.
+    """
+    X = X.copy()
+    for c in categorical_columns(X):
+        col = X[c].astype(object)
+        X[c] = col.where(col.isna(), col.astype(str))
+    return X
+
+
+# --------------------------------------------------------------------------- #
+# Target encoding (a fixed label mapping - not a learned statistic)
+# --------------------------------------------------------------------------- #
+
+def encode_target(y: pd.Series) -> Tuple[np.ndarray, List[str], LabelEncoder]:
+    """Class labels -> 0..k-1. Alphabetical order, except for ordered
+    categories (e.g. Low / Medium / High groups), which keep their order."""
+    le = LabelEncoder()
+    if isinstance(y.dtype, pd.CategoricalDtype) and y.cat.ordered:
+        present = [c for c in y.cat.categories if (y == c).any()]
+        le.classes_ = np.array([str(c) for c in present], dtype=object)
+        mapping = {str(c): i for i, c in enumerate(present)}
+        y_enc = y.astype(str).map(mapping).to_numpy(dtype=int)
+        return y_enc, [str(c) for c in present], le
+    y_enc = le.fit_transform(y.astype(str))
+    return y_enc, [str(c) for c in le.classes_], le
+
+
+# --------------------------------------------------------------------------- #
+# Learned preprocessing -> goes inside the Pipeline
+# --------------------------------------------------------------------------- #
+
+@dataclass
+class PrepConfig:
+    """User choices for the learned preprocessing steps."""
+
+    impute: str = "median"        # "mean" | "median" | "mode"
+    encoding: str = "auto"        # "auto" | "label" | "onehot"
+    scale_method: str = "standard"  # "standard" | "minmax"
+    scale: Optional[bool] = None  # True / False / None = decide per classifier
+    onehot_max_categories: int = 10
+
+
+def _onehot():
+    try:
+        return OneHotEncoder(handle_unknown="ignore", sparse_output=False)
+    except TypeError:  # scikit-learn < 1.2
+        return OneHotEncoder(handle_unknown="ignore", sparse=False)
+
+
+def _ordinal():
+    return OrdinalEncoder(handle_unknown="use_encoded_value", unknown_value=-1)
+
+
+def build_preprocessor(X: pd.DataFrame, cfg: PrepConfig,
+                       scale) -> ColumnTransformer:
+    """Build an *unfitted* transformer for the columns of ``X``.
+
+    ``scale``: False/None (no scaling), True (``cfg.scale_method``), or the
+    method itself, "standard" or "minmax".
+
+    Only column names and types are read from ``X`` here; all statistics are
+    learned later, when the pipeline is fitted on training data.
+    """
+    num_cols = numeric_columns(X)
+    cat_cols = categorical_columns(X)
+    num_strategy = "most_frequent" if cfg.impute == "mode" else cfg.impute
+    method = scale if isinstance(scale, str) else (
+        cfg.scale_method if scale else None)
+
+    transformers = []
+    if num_cols:
+        steps = [("impute", SimpleImputer(strategy=num_strategy))]
+        if method:
+            scaler = (MinMaxScaler() if method == "minmax"
+                      else StandardScaler())
+            steps.append(("scale", scaler))
+        transformers.append(("num", Pipeline(steps), num_cols))
+
+    if cat_cols:
+        if cfg.encoding == "label":
+            onehot_cols, ordinal_cols = [], cat_cols
+        elif cfg.encoding == "onehot":
+            onehot_cols, ordinal_cols = cat_cols, []
+        else:  # auto: one-hot for few categories, ordinal for many
+            onehot_cols = [c for c in cat_cols
+                           if X[c].nunique(dropna=True)
+                           <= cfg.onehot_max_categories]
+            ordinal_cols = [c for c in cat_cols if c not in onehot_cols]
+        impute = ("impute", SimpleImputer(strategy="most_frequent"))
+        if onehot_cols:
+            transformers.append(("cat_onehot", Pipeline(
+                [impute, ("encode", _onehot())]), onehot_cols))
+        if ordinal_cols:
+            transformers.append(("cat_ordinal", Pipeline(
+                [("impute", SimpleImputer(strategy="most_frequent")),
+                 ("encode", _ordinal())]), ordinal_cols))
+
+    return ColumnTransformer(transformers, remainder="drop")
+
+
+def build_pipeline(X: pd.DataFrame, cfg: PrepConfig, classifier,
+                   scale: bool) -> Pipeline:
+    """Preprocessing + classifier, fitted together on training data only."""
+    return Pipeline([
+        ("prep", build_preprocessor(X, cfg, scale)),
+        ("model", classifier),
+    ])
+
+
+def describe_transformed(X: pd.DataFrame, cfg: PrepConfig,
+                         scale: bool) -> np.ndarray:
+    """Transform the full data for *description only* (feature counts,
+    whether negative values occur). Never used for scoring."""
+    return build_preprocessor(X, cfg, scale).fit_transform(X)
+
+
+# --------------------------------------------------------------------------- #
+# Class balance
+# --------------------------------------------------------------------------- #
+
+def class_distribution(y) -> Dict[str, int]:
+    """Count rows per class, ignoring missing labels and mixed types."""
+    counts = pd.Series(np.asarray(y, dtype=object)).dropna().astype(str) \
+        .value_counts(sort=False)
+    return {str(k): int(v) for k, v in counts.items()}
+
+
+def imbalance_ratio(y) -> float:
+    """Ratio of the largest class to the smallest. 1.0 means balanced."""
+    counts = list(class_distribution(y).values())
+    if not counts or min(counts) == 0:
+        return float("inf")
+    return max(counts) / min(counts)

easyclassifier/recommend.py

@@ -0,0 +1,128 @@
+"""Smart recommendations (Phase 22).
+
+Inspects the dataset and suggests sensible methods in plain language.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+import pandas as pd
+
+from .dataset import Inspection
+from .preprocessing import duplicates_expected_by_chance, imbalance_ratio
+
+
+def _cat_cols(df, target) -> List[str]:
+    """Non-numeric feature columns (works for object and string dtypes)."""
+    return [c for c in df.columns
+            if c != target and not pd.api.types.is_numeric_dtype(df[c])]
+
+
+def missing_strategy(insp: Inspection) -> str:
+    """Recommend a default missing-value strategy key."""
+    if not insp.has_missing:
+        return "none"
+    # If missingness is small, filling is safer than dropping.
+    frac = insp.missing_total / max(1, insp.n_rows * insp.n_cols)
+    return "median" if frac < 0.2 else "drop"
+
+
+def encoding_method(df, target) -> str:
+    """Recommend an encoding method key based on categorical cardinality."""
+    cat_cols = _cat_cols(df, target)
+    if not cat_cols:
+        return "auto"
+    high_card = any(df[c].nunique() > 10 for c in cat_cols)
+    return "auto" if high_card else "onehot"
+
+
+# Distance- and margin-based classifiers depend on the units of the columns.
+SCALED_CLASSIFIERS = {"svm", "logistic_regression", "neural_network", "knn"}
+
+
+def scaling_for(key: str, knn_distance: Optional[str] = None,
+                choice: Optional[bool] = None,
+                method: str = "standard") -> Optional[str]:
+    """How to scale numeric columns for one classifier.
+
+    Returns None (no scaling), "standard" (mean 0, SD 1) or "minmax" (0-1).
+    ``choice`` is the user's answer: True / False, or None for automatic.
+
+    Automatic: tree-based models and Naive Bayes are not scaled; the others
+    are standardised; KNN with the Hassanat distance is scaled to 0-1, which
+    keeps all values non-negative (the formula's standard form) and gave
+    better results than unscaled data in EasyClassifier's benchmarks.
+    """
+    if choice is False:
+        return None
+    if choice is True:
+        return method
+    if key == "knn" and knn_distance == "hassanat":
+        return "minmax"
+    return "standard" if key in SCALED_CLASSIFIERS else None
+
+
+def validation_method(y) -> str:
+    """Recommend a validation strategy key based on class balance."""
+    ratio = imbalance_ratio(y)
+    if ratio > 1.5:
+        return "stratified"
+    return "kfold5"
+
+
+def build_notes(insp: Inspection, df, target, y) -> List[str]:
+    """Return a list of plain-language recommendation strings to show once."""
+    notes: List[str] = []
+
+    if insp.has_missing:
+        rec = missing_strategy(insp)
+        pct = 100 * insp.missing_total / max(1, insp.n_rows * insp.n_cols)
+        if rec == "drop":
+            notes.append(
+                f"{insp.missing_total} missing values ({pct:.1f}% of cells) "
+                "detected. That's a lot, so removing incomplete rows is a "
+                "reasonable default."
+            )
+        else:
+            notes.append(
+                f"{insp.missing_total} missing values ({pct:.1f}% of cells) "
+                "detected. Filling them with the median keeps all your rows."
+            )
+
+    if insp.has_duplicates:
+        if duplicates_expected_by_chance(df):
+            notes.append(
+                f"{insp.duplicate_rows} identical rows found. Your columns "
+                "allow only a few value combinations, so different cases "
+                "(e.g. people giving the same answers) are expected to "
+                "coincide. They will be kept.")
+        else:
+            notes.append(
+                f"{insp.duplicate_rows} duplicate rows detected. They are "
+                "probably accidental copies; removing them avoids "
+                "over-counting repeated records.")
+
+    cat_cols = _cat_cols(df, target)
+    if cat_cols:
+        high = [c for c in cat_cols if df[c].nunique() > 10]
+        if high:
+            notes.append(
+                "Some text columns have many categories. Automatic encoding "
+                "will label-encode those and one-hot encode the simpler ones."
+            )
+        else:
+            notes.append(
+                "Text columns detected with few categories each. One-hot "
+                "encoding is a safe choice."
+            )
+
+    ratio = imbalance_ratio(y)
+    if ratio > 1.5:
+        notes.append(
+            f"Classes are imbalanced (largest is {ratio:.1f}x the smallest). "
+            "Stratified cross-validation is recommended so each fold keeps the "
+            "same class mix."
+        )
+
+    return notes

easyclassifier/reporting.py

@@ -0,0 +1,70 @@
+"""Output files: CSV/Excel summaries, predictions, model, importance table.
+
+Figures are drawn by :mod:`easyclassifier.figures`.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import List, Optional
+
+import pandas as pd  # noqa: E402
+import joblib  # noqa: E402
+
+from .evaluation import Result, METRICS  # noqa: E402
+
+
+def ensure_dir(path: str) -> str:
+    os.makedirs(path, exist_ok=True)
+    return path
+
+
+def save_feature_importance(table: pd.DataFrame, path: str) -> str:
+    table.round(4).to_csv(path, index=False)
+    return path
+
+
+# --------------------------------------------------------------------------- #
+# Tabular summaries
+# --------------------------------------------------------------------------- #
+
+def results_dataframe(results: List[Result]) -> pd.DataFrame:
+    rows = []
+    for r in results:
+        row = {"Classifier": r.classifier_name}
+        for key, label in METRICS.items():
+            if key in r.metrics:
+                row[label] = round(r.metrics[key], 4)
+        rows.append(row)
+    return pd.DataFrame(rows)
+
+
+def save_summary_csv(results: List[Result], path: str) -> str:
+    results_dataframe(results).to_csv(path, index=False)
+    return path
+
+
+def save_excel(results: List[Result], path: str) -> Optional[str]:
+    try:
+        results_dataframe(results).to_excel(path, index=False,
+                                            sheet_name="Results")
+        return path
+    except Exception:  # noqa: BLE001 (openpyxl missing)
+        return None
+
+
+def save_predictions(result: Result, path: str) -> str:
+    names = result.class_names
+    df = pd.DataFrame({
+        "actual": [names[int(v)] if int(v) < len(names) else v
+                   for v in result.y_true],
+        "predicted": [names[int(v)] if int(v) < len(names) else v
+                      for v in result.y_pred],
+    })
+    df.to_csv(path, index=False)
+    return path
+
+
+def save_model(model, path: str) -> str:
+    joblib.dump(model, path)
+    return path