easyclassifier 0.8.1__py3-none-any.whl

easyclassifier/__init__.py

@@ -0,0 +1,23 @@
+"""EasyClassifier - Machine Learning without Programming.
+
+A guided, menu-driven wizard that lets non-programmers build and evaluate
+classification models from a CSV file.
+"""
+
+__version__ = "0.8.1"
+__author__ = "Ahmad Hassanat"
+
+CITATION = (
+    "Hassanat, A. (2026). EasyClassifier: Machine Learning without "
+    "Programming (Version {version}) [Software].".format(version=__version__)
+)
+
+from .wizard import Wizard  # noqa: E402
+
+
+def run():
+    """Launch the interactive wizard."""
+    Wizard().run()
+
+
+__all__ = ["Wizard", "run", "__version__", "CITATION"]

easyclassifier/__main__.py

@@ -0,0 +1,61 @@
+"""Console entry point for EasyClassifier.
+
+Start the wizard with either of:
+
+    easyclassifier
+    python -m easyclassifier
+
+Options:
+
+    --version   show the installed version and exit
+    --help      show this help and exit
+"""
+
+import sys
+
+HELP = """EasyClassifier - machine learning classification without programming.
+
+Usage:
+  easyclassifier            start the step-by-step wizard
+  python -m easyclassifier  the same, if the 'easyclassifier' command is
+                            not found
+
+Options:
+  --version   show the installed version
+  --help      show this help
+
+The wizard asks for a data file (.csv or .xlsx). Type 'demo' at that
+question to try it with a built-in example. Results are saved in a new
+folder inside 'Results', in the folder you started from.
+"""
+
+
+def main(argv=None):
+    args = sys.argv[1:] if argv is None else list(argv)
+    if any(a in ("-h", "--help", "/?") for a in args):
+        print(HELP)
+        return 0
+    if any(a in ("-V", "--version") for a in args):
+        from . import __version__
+        print(f"EasyClassifier {__version__} "
+              f"(Python {sys.version.split()[0]})")
+        return 0
+    if args:
+        print(f"Unknown option: {' '.join(args)}\n")
+        print(HELP)
+        return 2
+
+    import warnings
+    # Keep the screen clean for non-programmers; details go to the log.
+    warnings.filterwarnings("ignore")
+    from . import run
+    try:
+        run()
+    except KeyboardInterrupt:
+        print("\n\nExiting EasyClassifier. Goodbye!")
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

easyclassifier/dataset.py

@@ -0,0 +1,142 @@
+"""Dataset loading and inspection."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass
+class Inspection:
+    """Summary of a dataset's structure and quality."""
+
+    n_rows: int
+    n_cols: int
+    columns: List[str]
+    numeric_cols: List[str]
+    categorical_cols: List[str]
+    missing_total: int
+    missing_by_col: dict
+    duplicate_rows: int
+    columns_with_missing: List[str] = field(default_factory=list)
+
+    @property
+    def has_missing(self) -> bool:
+        return self.missing_total > 0
+
+    @property
+    def has_duplicates(self) -> bool:
+        return self.duplicate_rows > 0
+
+
+def clean_path(raw: str) -> str:
+    """Turn what the user typed or dragged into the window into a path.
+
+    * Dragging a file into a terminal adds quotes (Windows) or escapes
+      spaces with a backslash (macOS / Linux); PowerShell may add "& ".
+    * ``~`` means the home folder.
+    * If the name has no extension, .csv / .xlsx are tried.
+    """
+    p = raw.strip()
+    if p.startswith("& "):
+        p = p[2:].strip()
+    if len(p) >= 2 and p[0] == p[-1] and p[0] in "\"'":
+        p = p[1:-1]
+    if os.sep == "/" and "\\ " in p:
+        p = p.replace("\\ ", " ")
+    p = os.path.expanduser(p)
+    if not os.path.splitext(p)[1] and not os.path.isfile(p):
+        for ext in (".csv", ".xlsx"):
+            if os.path.isfile(p + ext):
+                return p + ext
+    return p
+
+
+EXCEL_EXTENSIONS = (".xlsx", ".xlsm")
+
+
+def load_csv(path: str) -> pd.DataFrame:
+    """Load a CSV file (or the first sheet of an Excel .xlsx file),
+    tolerating common separators and encodings."""
+    if not os.path.isfile(path):
+        raise FileNotFoundError(path)
+    ext = os.path.splitext(path)[1].lower()
+    if ext in EXCEL_EXTENSIONS:
+        return pd.read_excel(path)
+    if ext == ".xls":
+        raise ValueError("old .xls Excel files are not supported; please "
+                         "save the sheet as .xlsx or .csv in Excel "
+                         "(File > Save As)")
+    # Try a few sensible fallbacks for real-world CSVs.
+    attempts = [
+        dict(),
+        dict(sep=";"),
+        dict(encoding="latin-1"),
+        dict(sep=";", encoding="latin-1"),
+    ]
+    for kwargs in attempts:
+        try:
+            df = pd.read_csv(path, **kwargs)
+        except Exception:  # noqa: BLE001
+            continue
+        if df.shape[1] > 1:
+            if kwargs.get("sep") == ";":
+                df = fix_decimal_commas(df)
+            return df
+    # Fall back to the plain read and let its error (if any) surface.
+    return pd.read_csv(path)
+
+
+def fix_decimal_commas(df: pd.DataFrame) -> pd.DataFrame:
+    """Semicolon-separated files (Excel in many countries) write decimals
+    with a comma: 3,5. Turn such text columns into numbers when *every*
+    value converts; anything else is left unchanged."""
+    df = df.copy()
+    for c in df.columns:
+        if pd.api.types.is_numeric_dtype(df[c]):
+            continue
+        s = df[c].dropna().astype(str).str.strip()
+        if s.empty or not s.str.contains(",", regex=False).any():
+            continue
+        conv = pd.to_numeric(s.str.replace(",", ".", regex=False),
+                             errors="coerce")
+        if conv.notna().all():
+            df[c] = pd.to_numeric(
+                df[c].astype(str).str.strip().str.replace(",", ".",
+                                                         regex=False),
+                errors="coerce")
+    return df
+
+
+def inspect(df: pd.DataFrame) -> Inspection:
+    """Produce an :class:`Inspection` summary of a dataframe."""
+    numeric_cols = df.select_dtypes(include=[np.number]).columns.tolist()
+    categorical_cols = [c for c in df.columns if c not in numeric_cols]
+    missing_by_col = {
+        c: int(df[c].isna().sum()) for c in df.columns if df[c].isna().any()
+    }
+    return Inspection(
+        n_rows=int(df.shape[0]),
+        n_cols=int(df.shape[1]),
+        columns=df.columns.tolist(),
+        numeric_cols=numeric_cols,
+        categorical_cols=categorical_cols,
+        missing_total=int(df.isna().sum().sum()),
+        missing_by_col=missing_by_col,
+        duplicate_rows=int(df.duplicated().sum()),
+        columns_with_missing=list(missing_by_col.keys()),
+    )
+
+
+def guess_target(df: pd.DataFrame) -> Optional[str]:
+    """Best guess at which column holds the class labels.
+
+    Delegates to :func:`easyclassifier.target.suggest_target`, which only
+    suggests columns that look like groups (never IDs or measurements).
+    """
+    from .target import suggest_target
+    return suggest_target(df)

easyclassifier/demo_data.py

@@ -0,0 +1,32 @@
+"""Built-in demo dataset so users can try the tool without their own CSV."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+
+def load_demo() -> pd.DataFrame:
+    """Return a small, friendly classification dataset (the Iris flowers)."""
+    try:
+        from sklearn.datasets import load_iris
+        data = load_iris(as_frame=True)
+        df = data.frame.copy()
+        # Give it human-friendly column names and a text target.
+        df = df.rename(columns={
+            "sepal length (cm)": "sepal_length",
+            "sepal width (cm)": "sepal_width",
+            "petal length (cm)": "petal_length",
+            "petal width (cm)": "petal_width",
+        })
+        df["Species"] = pd.Categorical.from_codes(
+            data.target, data.target_names
+        ).astype(str)
+        df = df.drop(columns=["target"])
+        return df
+    except Exception:  # noqa: BLE001
+        # Extremely small fallback if sklearn datasets are unavailable.
+        return pd.DataFrame({
+            "x1": [1, 2, 3, 4, 5, 6],
+            "x2": [6, 5, 4, 3, 2, 1],
+            "Species": ["A", "A", "A", "B", "B", "B"],
+        })

easyclassifier/diagnostics.py

@@ -0,0 +1,95 @@
+"""Learning curve and plain-language interpretations of results.
+
+* ``learning_curve_data`` - how the score changes as more training rows are
+  used ("would more data help?").
+* ``interpret_learning_curve`` / ``interpret_comparison`` - one or two
+  sentences a non-specialist can act on.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+import numpy as np
+from sklearn.model_selection import StratifiedKFold, learning_curve
+
+from .evaluation import SELECTION_LABEL
+
+TRAIN_SIZES = np.linspace(0.2, 1.0, 5)
+
+
+def learning_curve_data(spec, X, y, seed: int = 42) -> Optional[Dict]:
+    """Balanced accuracy on training and validation rows for 20%...100% of
+    the available training rows (5-fold cross-validation). Returns None if
+    the data are too small to compute it."""
+    y = np.asarray(y)
+    smallest = int(np.min(np.unique(y, return_counts=True)[1]))
+    n_splits = max(2, min(5, smallest))
+    if len(y) < 20 or smallest < 2:
+        return None
+    cv = StratifiedKFold(n_splits=n_splits, shuffle=True, random_state=seed)
+    sizes, train, val = learning_curve(
+        spec.factory(), X, y, train_sizes=TRAIN_SIZES, cv=cv,
+        scoring="balanced_accuracy", shuffle=True, random_state=seed,
+        error_score=np.nan)
+    keep = ~np.all(np.isnan(val), axis=1)
+    if keep.sum() < 2:
+        return None
+    return {
+        "sizes": sizes[keep],
+        "train_mean": np.nanmean(train[keep], axis=1),
+        "train_std": np.nanstd(train[keep], axis=1),
+        "val_mean": np.nanmean(val[keep], axis=1),
+        "val_std": np.nanstd(val[keep], axis=1),
+    }
+
+
+def interpret_learning_curve(d: Dict) -> str:
+    """Would more data probably help? Based on the last part of the curve."""
+    v = d["val_mean"]
+    gain = float(v[-1] - v[-2])
+    gap = float(d["train_mean"][-1] - v[-1])
+    if gain > 0.01:
+        s = ("The score was still rising when all rows were used, so "
+             "collecting more data would probably improve the results.")
+    elif gain < -0.01:
+        s = ("The score did not improve at the end of the curve; more data "
+             "of the same kind is unlikely to help much.")
+    else:
+        s = ("The score had levelled off, so more data of the same kind is "
+             "unlikely to improve the results much.")
+    if gap > 0.15:
+        s += (" The model does much better on its training rows than on new "
+              "rows, a sign that it partly memorises the training data.")
+    return s
+
+
+def interpret_comparison(results: List) -> str:
+    """Is the best classifier clearly better than the runner-up?"""
+    if len(results) < 2:
+        return ""
+    a, b = results[0], results[1]
+    diff = a.selection_score - b.selection_score
+    spread = (float(np.std(a.fold_scores)) if len(a.fold_scores) > 1
+              else None)
+    label = SELECTION_LABEL.lower()
+    if diff < 0.0005:
+        tied = [r.classifier_name for r in results
+                if a.selection_score - r.selection_score < 0.0005]
+        return (f"{', '.join(tied[:-1])} and {tied[-1]} had the same "
+                f"{label}; {a.classifier_name} was selected because it is "
+                "listed first. They perform equally well on this data.")
+    if spread is None:
+        return (f"{a.classifier_name} had the highest {label}; with a "
+                "single test split the uncertainty of this ranking cannot be "
+                "judged.")
+    if diff < spread:
+        return (f"{a.classifier_name} had the highest {label}, but its lead "
+                f"over {b.classifier_name} ({diff * 100:.1f} percentage "
+                f"points) is smaller than the variation between test folds "
+                f"({spread * 100:.1f} points). The top classifiers perform "
+                "similarly; the choice between them is not clear-cut.")
+    return (f"{a.classifier_name} had the highest {label}, ahead of "
+            f"{b.classifier_name} by {diff * 100:.1f} percentage points, "
+            "which is larger than the variation between test folds "
+            f"({spread * 100:.1f} points).")

easyclassifier/distances.py

@@ -0,0 +1,152 @@
+"""Distance metrics for the KNN classifier, including the Hassanat distance.
+
+Hassanat distance (per dimension i):
+
+    if min(a_i, b_i) >= 0   (normal form):
+        D = 1 - (1 + min) / (1 + max)
+
+    if min(a_i, b_i) <  0   (signed form, for negative values):
+        D = 1 - (1 + min + |min|) / (1 + max + |min|)
+
+    HD(A, B) = sum_i D(a_i, b_i)
+
+Each dimension contributes at most 1, which makes the metric invariant to
+data scale, noise and outliers.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+import numpy as np
+from sklearn.base import BaseEstimator, ClassifierMixin
+from sklearn.neighbors import KNeighborsClassifier
+
+
+HASSANAT_CITATION = (
+    "Hassanat, A. B. (2014). Dimensionality Invariant Similarity Measure. "
+    "Journal of American Science, 10(8). arXiv:1409.0923."
+)
+
+HASSANAT_CITATIONS: List[str] = [HASSANAT_CITATION]
+
+# key -> (menu label, sklearn metric name or None for custom)
+DISTANCES: Dict[str, tuple] = {
+    "hassanat": ("Hassanat distance (robust to outliers)",
+                 None),
+    "euclidean": ("Euclidean distance", "euclidean"),
+    "manhattan": ("Manhattan (city-block) distance", "manhattan"),
+    "chebyshev": ("Chebyshev distance", "chebyshev"),
+    "canberra": ("Canberra distance", "canberra"),
+    "cosine": ("Cosine distance", "cosine"),
+}
+
+DISTANCE_HELP = {
+    "hassanat": "The Hassanat distance compares each feature using the ratio "
+                "of its smaller to larger value, so every feature adds at most "
+                "1 to the total; one extreme value cannot dominate. "
+                "EasyClassifier scales the columns to 0-1 first, which gave "
+                "the best results in its benchmarks. Citation: "
+                + HASSANAT_CITATION,
+    "euclidean": "Euclidean distance is the straight-line distance between "
+                 "two points. Sensitive to scale, so scaling is advised.",
+    "manhattan": "Manhattan distance adds up the absolute differences of "
+                 "each feature, like walking city blocks.",
+    "chebyshev": "Chebyshev distance uses only the single largest feature "
+                 "difference.",
+    "canberra": "Canberra distance is a weighted version of Manhattan that "
+                "is sensitive to small values near zero.",
+    "cosine": "Cosine distance compares the direction of two rows, ignoring "
+              "their size.",
+}
+
+
+# --------------------------------------------------------------------------- #
+# Hassanat distance
+# --------------------------------------------------------------------------- #
+
+def hassanat_distance(a, b) -> float:
+    """Hassanat distance between two 1-D vectors."""
+    a = np.asarray(a, dtype=float)
+    b = np.asarray(b, dtype=float)
+    mn = np.minimum(a, b)
+    mx = np.maximum(a, b)
+    shift = np.where(mn < 0, -mn, 0.0)  # |min| only when min < 0
+    return float(np.sum(1.0 - (1.0 + mn + shift) / (1.0 + mx + shift)))
+
+
+MAX_CHUNK_CELLS = 4_000_000   # ~32 MB per temporary array
+
+
+def hassanat_matrix(XA, XB, chunk: int = 256) -> np.ndarray:
+    """Pairwise Hassanat distances (rows of XA vs rows of XB), vectorised.
+
+    Rows of XA are processed in chunks small enough that the temporary
+    arrays stay within a few hundred MB, even for large datasets.
+    """
+    XA = np.asarray(XA, dtype=float)
+    XB = np.asarray(XB, dtype=float)
+    per_row = max(1, XB.shape[0] * XB.shape[1])
+    chunk = max(1, min(chunk, MAX_CHUNK_CELLS // per_row))
+    out = np.empty((XA.shape[0], XB.shape[0]))
+    for s in range(0, XA.shape[0], chunk):
+        A = XA[s:s + chunk, None, :]
+        mn = np.minimum(A, XB[None, :, :])
+        mx = np.maximum(A, XB[None, :, :])
+        shift = np.where(mn < 0, -mn, 0.0)
+        out[s:s + chunk] = np.sum(
+            1.0 - (1.0 + mn + shift) / (1.0 + mx + shift), axis=2)
+    return out
+
+
+def hassanat_form(X) -> dict:
+    """Report whether the normal or signed form of the formula is used."""
+    X = np.asarray(X, dtype=float)
+    neg_cols = int(np.sum((X < 0).any(axis=0)))
+    if neg_cols == 0:
+        return {"form": "normal", "negative_features": 0,
+                "text": "Normal form used (all feature values are >= 0)."}
+    return {"form": "signed", "negative_features": neg_cols,
+            "text": (f"Signed form used: {neg_cols} feature(s) contain "
+                     "negative values, so the negative-value case "
+                     "1 - (1+min+|min|)/(1+max+|min|) was applied to them.")}
+
+
+class HassanatKNN(BaseEstimator, ClassifierMixin):
+    """K-Nearest Neighbours classifier using the Hassanat distance."""
+
+    def __init__(self, n_neighbors: int = 5):
+        self.n_neighbors = n_neighbors
+
+    def fit(self, X, y):
+        self.X_ = np.asarray(X, dtype=float)
+        y = np.asarray(y)
+        self.classes_, self.y_ = np.unique(y, return_inverse=True)
+        return self
+
+    def _neighbors(self, X):
+        D = hassanat_matrix(X, self.X_)
+        k = min(self.n_neighbors, self.X_.shape[0])
+        idx = np.argpartition(D, k - 1, axis=1)[:, :k]
+        return idx
+
+    def predict_proba(self, X):
+        idx = self._neighbors(X)
+        votes = self.y_[idx]
+        n_cls = len(self.classes_)
+        proba = np.zeros((votes.shape[0], n_cls))
+        for c in range(n_cls):
+            proba[:, c] = (votes == c).sum(axis=1)
+        return proba / proba.sum(axis=1, keepdims=True)
+
+    def predict(self, X):
+        return self.classes_[np.argmax(self.predict_proba(X), axis=1)]
+
+
+def make_knn(distance: str = "hassanat", k: int = 5):
+    """Factory returning a KNN classifier for the chosen distance."""
+    if distance == "hassanat":
+        return HassanatKNN(n_neighbors=k)
+    metric = DISTANCES[distance][1]
+    return KNeighborsClassifier(n_neighbors=k, metric=metric,
+                                algorithm="brute")