easyclassifier 0.8.1__py3-none-any.whl

easyclassifier/target.py

@@ -0,0 +1,202 @@
+"""Choosing and checking the column to predict (the target / class column).
+
+Everything here is plain logic with no user interaction, so it can be tested
+directly. The wizard uses it to
+
+* describe every column in plain words so the user can pick the right one,
+* suggest the most likely class column,
+* catch unsuitable choices (a single value, an ID column, a measurement
+  instead of a category, classes with too few rows), and
+* turn a measurement into categories when the user wants that.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+# Kinds of column
+CATEGORY = "category"          # a sensible class column
+MEASUREMENT = "measurement"    # numbers with many different values
+ID_LIKE = "id"                 # different in every row (an identifier)
+CONSTANT = "constant"          # a single value, nothing to predict
+MANY_TEXT = "many_text"        # text with very many different values
+EMPTY = "empty"                # no values at all
+
+COMMON_TARGET_NAMES = [
+    "target", "label", "class", "outcome", "result", "disease",
+    "diagnosis", "purchased", "churn", "y", "category", "species",
+    "status", "response", "grade",
+]
+
+MIN_ROWS_PER_CLASS = 2         # fewer than this cannot be tested at all
+FEW_ROWS_PER_CLASS = 5         # fewer than this gives unreliable results
+
+
+def _max_categories(n_rows: int) -> int:
+    """How many different values a class column may reasonably have."""
+    return max(20, int(0.05 * n_rows))
+
+
+def _is_integer_valued(s: pd.Series) -> bool:
+    v = s.dropna().to_numpy(dtype=float)
+    return bool(len(v)) and bool(np.all(np.equal(np.mod(v, 1), 0)))
+
+
+def _fmt(v) -> str:
+    if isinstance(v, (float, np.floating)) and float(v).is_integer():
+        return str(int(v))
+    if isinstance(v, (float, np.floating)):
+        return f"{v:.4g}"
+    return str(v)
+
+
+@dataclass
+class ColumnInfo:
+    name: str
+    kind: str
+    n_unique: int
+    n_values: int
+    label: str                    # one-line plain-language description
+    counts: Dict[str, int] = field(default_factory=dict)
+
+
+def describe_column(s: pd.Series) -> ColumnInfo:
+    """Classify a column and describe it in plain words."""
+    name = str(s.name)
+    vals = s.dropna()
+    n, u = len(vals), int(vals.nunique())
+    numeric = (pd.api.types.is_numeric_dtype(s)
+               and not pd.api.types.is_bool_dtype(s))
+
+    if n == 0:
+        return ColumnInfo(name, EMPTY, 0, 0, f"{name} - empty column")
+    if u == 1:
+        return ColumnInfo(name, CONSTANT, 1, n,
+                          f"{name} - only one value ({_fmt(vals.iloc[0])})")
+
+    looks_like_id = "id" in name.lower().replace("_", " ").split() or \
+        name.lower().endswith("id")
+    if u == n and n >= 20:
+        consecutive = (numeric and _is_integer_valued(vals)
+                       and vals.max() - vals.min() + 1 == n)
+        if not numeric or consecutive or looks_like_id:
+            return ColumnInfo(name, ID_LIKE, u, n,
+                              f"{name} - different in every row "
+                              "(looks like an ID)")
+
+    if numeric and u > 2:
+        integer = _is_integer_valued(vals)
+        mostly_distinct = u > 10 and u > n / 2
+        if (not integer and u > 10) or mostly_distinct \
+                or u > _max_categories(n):
+            return ColumnInfo(
+                name, MEASUREMENT, u, n,
+                f"{name} - numbers from {_fmt(vals.min())} to "
+                f"{_fmt(vals.max())} ({u} different)")
+
+    if not numeric and u > _max_categories(n):
+        return ColumnInfo(name, MANY_TEXT, u, n,
+                          f"{name} - {u} different text values")
+
+    counts = vals.value_counts()
+    shown = ", ".join(_fmt(v) for v in counts.index[:3])
+    more = ", ..." if u > 3 else ""
+    return ColumnInfo(name, CATEGORY, u, n,
+                      f"{name} - {u} categories ({shown}{more})",
+                      counts={_fmt(k): int(v) for k, v in counts.items()})
+
+
+def suggest_target(df: pd.DataFrame) -> Optional[str]:
+    """Most likely class column, or None if nothing looks suitable."""
+    infos = {c: describe_column(df[c]) for c in df.columns}
+    lower = {str(c).lower(): c for c in df.columns}
+    for name in COMMON_TARGET_NAMES:
+        c = lower.get(name)
+        if c is not None and infos[c].kind == CATEGORY:
+            return c
+    # Otherwise the last category-like column (class columns are usually
+    # last), preferring few categories.
+    cands = [c for c in df.columns if infos[c].kind == CATEGORY]
+    if not cands:
+        return None
+    return min(reversed(cands), key=lambda c: infos[c].n_unique)
+
+
+# --------------------------------------------------------------------------- #
+# Class-size checks
+# --------------------------------------------------------------------------- #
+
+def tiny_and_small_classes(s: pd.Series) -> Tuple[List[str], List[str]]:
+    """Classes with fewer than 2 rows (unusable) and fewer than 5 (risky)."""
+    counts = s.dropna().astype(str).value_counts()
+    tiny = [k for k, v in counts.items() if v < MIN_ROWS_PER_CLASS]
+    small = [k for k, v in counts.items()
+             if MIN_ROWS_PER_CLASS <= v < FEW_ROWS_PER_CLASS]
+    return tiny, small
+
+
+# --------------------------------------------------------------------------- #
+# Turning a measurement into categories
+# --------------------------------------------------------------------------- #
+
+GROUP_NAMES = {
+    2: ["Low", "High"],
+    3: ["Low", "Medium", "High"],
+    4: ["Very low", "Low", "High", "Very high"],
+}
+
+
+def group_equal(s: pd.Series, k: int) -> Tuple[pd.Series, List[float], str]:
+    """Split numbers into ``k`` groups of (roughly) equal size.
+
+    Returns the new labels, the cut-points, and a description. If many rows
+    share the same value, fewer groups may result.
+    """
+    vals = pd.to_numeric(s, errors="coerce")
+    uniq = np.sort(vals.dropna().unique())
+    cuts = []
+    for q in vals.quantile([i / k for i in range(1, k)]).tolist():
+        # A value >= cut goes to the higher group. A cut at (or below) the
+        # smallest value would leave the lowest group empty, so move it to
+        # the next value up - e.g. many zeros give "0" vs "above 0".
+        above = uniq[uniq > q] if q <= uniq[0] else uniq[uniq >= q]
+        if len(above):
+            cuts.append(float(above[0]))
+    cuts = sorted(set(cuts))
+    if not cuts:
+        raise ValueError("all values are the same; cannot form groups")
+    return _cut(vals, cuts)
+
+
+def group_at(s: pd.Series, threshold: float) -> Tuple[pd.Series, List[float], str]:
+    """Two groups: below the threshold, and at or above it."""
+    vals = pd.to_numeric(s, errors="coerce")
+    return _cut(vals, [float(threshold)])
+
+
+def _cut(vals: pd.Series, cuts: List[float]) -> Tuple[pd.Series, List[float], str]:
+    cuts = sorted(set(float(c) for c in cuts))
+    k = len(cuts) + 1
+    names = GROUP_NAMES.get(k, [f"Group {i + 1}" for i in range(k)])
+    labels = []
+    for i in range(k):
+        if i == 0:
+            rng = f"< {_fmt(cuts[0])}"
+        elif i == k - 1:
+            rng = f">= {_fmt(cuts[-1])}"
+        else:
+            rng = f"{_fmt(cuts[i - 1])} to < {_fmt(cuts[i])}"
+        labels.append(f"{names[i]} ({rng})")
+    codes = np.searchsorted(np.asarray(cuts), vals.to_numpy(dtype=float),
+                            side="right")
+    # An ordered category keeps Low < Medium < High in tables and figures.
+    out = pd.Series(pd.Categorical(
+        [labels[c] if not np.isnan(v) else np.nan
+         for c, v in zip(codes, vals.to_numpy(dtype=float))],
+        categories=labels, ordered=True), index=vals.index, name=vals.name)
+    desc = "; ".join(labels)
+    return out, cuts, desc

easyclassifier/ui.py

@@ -0,0 +1,281 @@
+"""Terminal user-interface helpers for EasyClassifier.
+
+All user interaction goes through these functions so the rest of the code
+never touches ``input``/``print`` directly. This keeps the wizard logic clean
+and makes the interface easy to swap out later (e.g. for a GUI).
+
+The helpers are intentionally plain-text and dependency-free so they work in
+any terminal.
+"""
+
+from __future__ import annotations
+
+import textwrap
+from typing import List, Optional, Sequence, Tuple
+
+
+# --------------------------------------------------------------------------- #
+# Basic output
+# --------------------------------------------------------------------------- #
+
+WIDTH = 66
+
+
+def _line(char: str = "-") -> str:
+    return char * WIDTH
+
+
+def rule(char: str = "-") -> None:
+    print(_line(char))
+
+
+def banner(title: str, subtitle: str = "") -> None:
+    """Print a boxed banner."""
+    print()
+    rule("=")
+    print(title.center(WIDTH))
+    if subtitle:
+        print(subtitle.center(WIDTH))
+    rule("=")
+
+
+def header(text: str) -> None:
+    """Section header."""
+    print()
+    rule()
+    print(text)
+    rule()
+
+
+def info(text: str) -> None:
+    for line in textwrap.wrap(text, WIDTH) or [""]:
+        print(line)
+
+
+def note(text: str) -> None:
+    print(f"  * {text}")
+
+
+def success(text: str) -> None:
+    print(f"[OK] {text}")
+
+
+def warn(text: str) -> None:
+    print(f"[!]  {text}")
+
+
+def error(text: str) -> None:
+    print(f"[X]  {text}")
+
+
+def blank() -> None:
+    print()
+
+
+def pause(msg: str = "Press ENTER to continue...") -> None:
+    try:
+        input("\n" + msg)
+    except EOFError:
+        pass
+
+
+# --------------------------------------------------------------------------- #
+# Input primitives
+# --------------------------------------------------------------------------- #
+
+def _read(prompt: str) -> str:
+    try:
+        return input(prompt)
+    except EOFError:
+        # Non-interactive / piped input exhausted.
+        print()
+        raise KeyboardInterrupt
+
+
+def ask_text(prompt: str, default: Optional[str] = None,
+             allow_empty: bool = False) -> str:
+    """Free-text input with an optional default."""
+    suffix = f" [{default}]" if default is not None else ""
+    while True:
+        value = _read(f"{prompt}{suffix}\n>> ").strip()
+        if not value:
+            if default is not None:
+                return default
+            if allow_empty:
+                return ""
+            error("Please enter a value.")
+            continue
+        return value
+
+
+def ask_yes_no(prompt: str, default: Optional[bool] = None) -> bool:
+    """Yes/No question. Returns True for yes."""
+    if default is True:
+        hint = " [Y/n]"
+    elif default is False:
+        hint = " [y/N]"
+    else:
+        hint = " [y/n]"
+    while True:
+        value = _read(f"{prompt}{hint}\n>> ").strip().lower()
+        if not value and default is not None:
+            return default
+        if value in ("y", "yes", "1"):
+            return True
+        if value in ("n", "no", "2"):
+            return False
+        error("Please answer y or n.")
+
+
+def menu(prompt: str, options: Sequence[str],
+         default: Optional[int] = None,
+         allow_help: bool = True,
+         help_keys: Optional[Sequence[str]] = None) -> int:
+    """Numbered single-choice menu.
+
+    Returns the zero-based index of the chosen option.
+    Options are displayed starting at 1. If ``help_keys`` is provided the user
+    may type ``?N`` to see help for option N (handled by the caller via the
+    returned sentinel).
+    """
+    print()
+    print(prompt)
+    for i, opt in enumerate(options, start=1):
+        print(f"  {i}. {opt}")
+    hint = ""
+    if default is not None:
+        hint = f" (default {default + 1})"
+    if allow_help:
+        hint += "  |  type ?N for help on option N"
+    while True:
+        raw = _read(f"Choose 1-{len(options)}{hint}\n>> ").strip()
+        if not raw and default is not None:
+            return default
+        if allow_help and raw.startswith("?"):
+            num = raw[1:].strip()
+            if num.isdigit() and 1 <= int(num) <= len(options):
+                return -int(num)  # sentinel: caller shows help
+            error("Type ? followed by a valid option number, e.g. ?2")
+            continue
+        if raw.isdigit() and 1 <= int(raw) <= len(options):
+            return int(raw) - 1
+        error(f"Please enter a number between 1 and {len(options)}.")
+
+
+def multi_select(prompt: str, options: Sequence[str],
+                 default_all: bool = True,
+                 default: Optional[List[int]] = None) -> List[int]:
+    """Multiple-choice checkbox menu.
+
+    User enters comma-separated numbers, 'all', or 'none'. ENTER gives
+    ``default`` if provided, otherwise all (``default_all``) or none.
+    Returns a list of zero-based indices.
+    """
+    if default is None:
+        default = list(range(len(options))) if default_all else []
+    print()
+    print(prompt)
+    for i, opt in enumerate(options, start=1):
+        mark = "x" if i - 1 in default else " "
+        print(f"  [{mark}] {i}. {opt}")
+    if len(default) == len(options):
+        default_hint = "ENTER = all"
+    elif not default:
+        default_hint = "ENTER = none"
+    else:
+        default_hint = "ENTER = " + ",".join(str(i + 1) for i in default)
+    while True:
+        raw = _read(
+            f"Enter numbers separated by commas, or 'all' / 'none' "
+            f"[{default_hint}]\n>> "
+        ).strip().lower()
+        if not raw:
+            return list(default)
+        if raw == "all":
+            return list(range(len(options)))
+        if raw == "none":
+            return []
+        try:
+            picks = sorted({
+                int(p) - 1 for p in raw.replace(" ", "").split(",") if p != ""
+            })
+        except ValueError:
+            error("Please enter numbers separated by commas.")
+            continue
+        if all(0 <= p < len(options) for p in picks) and picks:
+            return picks
+        error(f"Please enter numbers between 1 and {len(options)}.")
+
+
+def choose_from_list(prompt: str, items: Sequence[str],
+                     extra_options: Sequence[str] = ()) -> Tuple[int, bool]:
+    """Present a list of items plus optional extra menu entries.
+
+    Returns ``(index, is_extra)``. If ``is_extra`` is True the index refers to
+    ``extra_options``; otherwise it refers to ``items``.
+    """
+    combined = list(items) + list(extra_options)
+    idx = menu(prompt, combined, allow_help=False)
+    if idx >= len(items):
+        return idx - len(items), True
+    return idx, False
+
+
+def pick_from_long_list(prompt: str, labels: Sequence[str],
+                        names: Sequence[str],
+                        default: Optional[int] = None,
+                        marks: Optional[dict] = None,
+                        page_size: int = 20) -> int:
+    """Choose one item from a possibly very long list.
+
+    Numbers stay the same while paging or searching, so the user can always
+    type the number they saw. Typing text shows only the items whose name
+    contains that text. Returns the zero-based index into ``labels``.
+    """
+    marks = marks or {}
+    shown = list(range(len(labels)))
+    page = 0
+    while True:
+        pages = max(1, (len(shown) + page_size - 1) // page_size)
+        page = min(page, pages - 1)
+        print()
+        print(prompt)
+        visible = shown[page * page_size:(page + 1) * page_size]
+        for i in visible:
+            print(f"  {i + 1:>3}. {labels[i]}{marks.get(i, '')}")
+        if default is not None and default not in visible:
+            print(f"  Suggested: {default + 1}. {labels[default]}")
+        hints = []
+        if default is not None:
+            hints.append(f"ENTER = {default + 1}, the suggested one")
+        if pages > 1:
+            hints.append(f"page {page + 1} of {pages}: 'n' next, 'p' back")
+        if len(labels) > page_size or len(shown) < len(labels):
+            hints.append("type part of a name to search"
+                         + (", 'all' to list everything"
+                            if len(shown) < len(labels) else ""))
+        if hints:
+            print("  (" + "; ".join(hints) + ")")
+        raw = _read("Choose a number\n>> ").strip()
+        low = raw.lower()
+        if not raw:
+            if default is not None:
+                return default
+            error("Please type a number.")
+        elif raw.isdigit():
+            n = int(raw)
+            if 1 <= n <= len(labels):
+                return n - 1
+            error(f"Please enter a number between 1 and {len(labels)}.")
+        elif low in ("n", "next"):
+            page = page + 1 if page + 1 < pages else page
+        elif low in ("p", "back", "prev"):
+            page = max(0, page - 1)
+        elif low == "all":
+            shown, page = list(range(len(labels))), 0
+        else:
+            found = [i for i, nm in enumerate(names) if low in str(nm).lower()]
+            if found:
+                shown, page = found, 0
+            else:
+                error(f"No column name contains '{raw}'.")