kalfa 3.0.0.dev0__py3-none-any.whl

kalfa/records/stats/choices.py

@@ -0,0 +1,282 @@
+import math
+import numbers
+
+import numpy
+
+from ...core.errors import KalfaError
+from ..reader import read_plan
+from .classes import (
+    COMPLEMENT,
+    NEGATED,
+    best_threshold,
+    binary_rows,
+    binary_stats,
+    in_unit,
+    multiclass_rows,
+    multiclass_stats,
+    score_values,
+)
+from .measures import color_column, embedding_stats, regression_stats, values_stats
+from .pairs import declared_targets, label_columns, score_labels, task_pairs
+from .tables import (
+    PREDICTIONS,
+    filtered,
+    finite,
+    image_column,
+    label_text,
+    load_table,
+    numbers_of,
+    numeric,
+    plain_value,
+    present,
+    read_fitted_fields,
+    rows_in,
+    texts,
+)
+
+
+KINDS = {"binary": "classification", "multiclass": "classification", "regression": "regression",
+         "embedding": "embedding", "values": "values"}
+GALLERY = 24
+CHOICES = ("task", "score", "positive", "threshold", "bins")
+HISTOGRAMS = {"binary": ("score_hist",), "multiclass": (), "regression": ("residual_hist", "truth_hist"),
+              "embedding": ("norm_hist",), "values": ("hist",)}
+MAX_BINS = 1000
+
+
+def entry(frame, position, truth=None, pred=None, score=None, error=None):
+    return {"index": int(frame.index[position]), "row": plain_value(rows_in(frame)[position]),
+            "truth": None if truth is None else plain_value(truth[position]),
+            "pred": None if pred is None else plain_value(pred[position]),
+            "score": None if score is None else plain_value(score[position]),
+            "error": None if error is None else plain_value(error[position])}
+
+
+def class_gallery(frame, truth, guess, keep, score=None):
+    wrong = keep & (truth != guess).astype(bool)
+    picked = numpy.r_[numpy.flatnonzero(wrong), numpy.flatnonzero(keep & ~wrong)][:GALLERY]
+    return [entry(frame, position, truth, guess, score) for position in picked]
+
+
+def class_scores(frame, columns, guess, picked):
+    found = numpy.full(len(guess), numpy.nan)
+    for position in picked:
+        column = columns.get(guess[position])
+        if column in frame.columns:
+            found[position] = numbers_of(frame[column].iloc[[position]])[0]
+    return found
+
+
+def gallery_of(frame, pair, task, choice):
+    pred, target = pair["pred"], pair["target"]
+    if task == "binary":
+        truth, guess, values, keep = binary_rows(frame, pred, target, choice["labels"], choice["score"],
+                                                 choice["threshold"])
+        return class_gallery(frame, truth, guess, keep, values)
+    if task == "multiclass":
+        truth, guess, keep = multiclass_rows(frame, pred, target)
+        wrong = keep & (truth != guess).astype(bool)
+        picked = numpy.r_[numpy.flatnonzero(wrong), numpy.flatnonzero(keep & ~wrong)][:GALLERY]
+        columns = label_columns(pair["scores"], pair["output"], pair["classes"])
+        return class_gallery(frame, truth, guess, keep, class_scores(frame, columns, guess, picked))
+    if task == "regression":
+        guess, truth = numbers_of(frame[pred]), numbers_of(frame[target])
+        error = guess - truth
+        keep = numpy.flatnonzero(numpy.isfinite(error))
+        picked = keep[numpy.argsort(-numpy.abs(error[keep]), kind="stable")][:GALLERY]
+        return [entry(frame, position, truth, guess, None, error) for position in picked]
+    color = choice.get("color")
+    truth = None if color is None else texts(frame[color])
+    guess = numbers_of(frame[pred]) if task == "values" else None
+    return [entry(frame, position, truth, guess) for position in range(min(len(frame), GALLERY))]
+
+
+def number_value(value, label):
+    try:
+        found = float(value)
+    except (TypeError, ValueError):
+        raise KalfaError(f"{label} must be a number, not {value!r}") from None
+    if not math.isfinite(found):
+        raise KalfaError(f"{label} must be a finite number, not {value!r}")
+    return found
+
+
+def bins_count(value, label):
+    if isinstance(value, bool) or not isinstance(value, (numbers.Integral, str)):
+        raise KalfaError(f"{label} must be a whole number, not {value!r}")
+    try:
+        found = int(value)
+    except ValueError:
+        raise KalfaError(f"{label} must be a whole number, not {value!r}") from None
+    if found < 1:
+        raise KalfaError(f"{label} must be at least 1, not {value!r}")
+    return min(found, MAX_BINS)
+
+
+def checked_bins(pred, wanted):
+    if wanted in (None, ""):
+        return {}
+    if not isinstance(wanted, dict):
+        raise KalfaError(f"the bins of {pred} must map histogram names to counts, like {{residual_hist: 60}}")
+    return {str(name): bins_count(count, f"the bins of {name} for {pred}") for name, count in wanted.items()}
+
+
+def checked_overrides(overrides, pairs):
+    if overrides in (None, {}):
+        return {}
+    if not isinstance(overrides, dict):
+        raise KalfaError("overrides must map prediction columns to choices")
+    known = [pair["pred"] for pair in pairs]
+    found = {}
+    for pred, choice in overrides.items():
+        if pred not in known:
+            raise KalfaError(f"no prediction pair {pred}; the table has {', '.join(known) or 'none'}")
+        if not isinstance(choice, dict):
+            raise KalfaError(f"the choice for {pred} must be a mapping of task, score, positive, threshold and bins")
+        unknown = sorted(set(choice) - set(CHOICES))
+        if unknown:
+            raise KalfaError(f"{pred} takes task, score, positive, threshold and bins, not {', '.join(unknown)}")
+        found[pred] = {key: value for key, value in choice.items() if key != "bins" and value not in (None, "")}
+        bins = checked_bins(pred, choice.get("bins"))
+        if bins:
+            found[pred]["bins"] = bins
+    return found
+
+
+def chosen_task(pair, choice):
+    task = choice.get("task") or pair["auto"]
+    if task not in pair["tasks"]:
+        raise KalfaError(f"{pair['pred']} cannot be read as {task}; it can be {', '.join(pair['tasks'])}")
+    return task
+
+
+def histogram_bins(pred, task, wanted, bins):
+    names = HISTOGRAMS[task]
+    unknown = sorted(set(wanted) - set(names))
+    if unknown:
+        kept = ", ".join(names) or "none"
+        raise KalfaError(f"{pred} read as {task} has no histogram {', '.join(unknown)}; its histograms are {kept}")
+    return {name: wanted.get(name, bins) for name in names}
+
+
+def score_candidates(frame, pair, positive, labels):
+    owners = score_labels(pair["scores"], pair["output"], labels)
+    found = [column for column, label in owners.items() if label == positive]
+    found += [f"{COMPLEMENT}{column}" if label in labels else column
+              for column, label in owners.items() if label != positive]
+    grows = list(pair["classes"])[1]
+    for column in (pair["raw"], pair["pred"]):
+        if column and column not in found and numeric(frame[column]):
+            values = numbers_of(frame[column])
+            if len(numpy.unique(finite(values))) > 2:
+                found.append(column if positive == grows else turned(column, values))
+    return found
+
+
+def turned(column, values):
+    return f"{COMPLEMENT}{column}" if in_unit(values) else f"{NEGATED}{column}"
+
+
+def binary_choice(frame, pair, choice):
+    labels = list(pair["classes"])
+    positive = labels[1]
+    if choice.get("positive") is not None:
+        wanted = label_text(choice["positive"])
+        if wanted not in labels:
+            raise KalfaError(f"positive must be one of {', '.join(labels)} for {pair['pred']}, not {wanted!r}")
+        positive = wanted
+    labels = [label for label in labels if label != positive] + [positive]
+    candidates = score_candidates(frame, pair, positive, labels)
+    score = candidates[0] if candidates else None
+    if choice.get("score") is not None:
+        if choice["score"] not in candidates:
+            shown = ", ".join(candidates) or "none"
+            raise KalfaError(f"score must be one of {shown} for {pair['pred']}, not {choice['score']!r}")
+        score = choice["score"]
+    threshold, rule, unit = None, None, True
+    if score is not None:
+        values = score_values(frame, score)
+        unit = in_unit(values)
+        if choice.get("threshold") is not None:
+            threshold, rule = number_value(choice["threshold"], "threshold"), "given"
+        elif unit:
+            threshold, rule = 0.5, "0.5"
+        else:
+            truth = texts(frame[pair["target"]])
+            keep = present(truth) & numpy.isfinite(values)
+            threshold, rule = best_threshold((truth == positive)[keep].astype(bool), values[keep]), "best_f1"
+    return {"labels": labels, "positive": positive, "score": score, "threshold": threshold, "rule": rule,
+            "unit": unit, "candidates": candidates}
+
+
+def headline(task, found):
+    if task == "regression":
+        return ("r2", found["r2"]) if found.get("r2") is not None else ("rmse", found.get("rmse"))
+    if task == "binary":
+        return ("auc", found["roc"]["auc"]) if found.get("roc") else ("f1", found.get("f1"))
+    if task == "multiclass":
+        return "accuracy", found.get("accuracy")
+    if task == "embedding":
+        explained = [value for value in (found.get("pca") or {}).get("explained") or [] if value is not None]
+        return "explained", float(sum(explained)) if explained else None
+    return "count", found.get("count")
+
+
+def overview_of(pairs):
+    tasks = {}
+    rows = []
+    for pair in pairs:
+        tasks[pair["task"]] = tasks.get(pair["task"], 0) + 1
+        key, value = headline(pair["task"], pair["stats"])
+        rows.append({"output": pair["output"], "pred": pair["pred"], "target": pair["target"], "task": pair["task"],
+                     "key": key, "value": value, "count": pair["stats"].get("count")})
+    return {"pairs": len(pairs), "tasks": tasks, "rows": rows}
+
+
+def scored(full, frame, base, choice, images, context, bins, sample, worst):
+    task = chosen_task(base, choice)
+    counts = histogram_bins(base["pred"], task, choice.get("bins") or {}, bins)
+    pair = {"output": base["output"], "pred": base["pred"], "columns": list(base["columns"]),
+            "target": base["target"], "kind": KINDS[task], "task": task, "auto": base["auto"],
+            "tasks": list(base["tasks"]), "raw": base["raw"], "scores": list(base["scores"]), "score": None,
+            "positive": None, "images": images}
+    details = {}
+    if task == "binary":
+        details = binary_choice(full, base, choice)
+        pair["score"], pair["positive"] = details["score"], details["positive"]
+        stats = binary_stats(frame, base["pred"], base["target"], details["labels"], details["score"],
+                             details["threshold"], details["rule"], details["unit"], counts["score_hist"],
+                             details["candidates"])
+    elif task == "multiclass":
+        stats = multiclass_stats(frame, base["pred"], base["target"], base["classes"], base["scores"])
+    elif task == "regression":
+        stats = regression_stats(frame, base["pred"], base["target"], bins=counts["truth_hist"], sample=sample,
+                                 worst=worst, residual_bins=counts["residual_hist"])
+    elif task == "embedding":
+        details = {"color": color_column(full, context["targets"], images)}
+        stats = embedding_stats(frame, base["columns"], details["color"], bins=counts["norm_hist"], sample=sample)
+    else:
+        stats = values_stats(frame, base["pred"], bins=counts["hist"])
+    if images:
+        stats["gallery"] = gallery_of(frame, base, task, details)
+    pair["stats"] = stats
+    return pair
+
+
+def prediction_stats(directory, plan=None, name=PREDICTIONS, where=None, bins=40, sample=2000, worst=20,
+                     overrides=None):
+    full = load_table(directory, name)
+    if full is None:
+        return None
+    full = full.reset_index(drop=True)
+    frame = filtered(full, where, name)
+    if plan is None:
+        plan = read_plan(directory)
+    fitted = read_fitted_fields(directory)
+    bases = task_pairs(full, plan, fitted)
+    choices = checked_overrides(overrides, bases)
+    images = image_column(full)
+    context = {"targets": declared_targets(plan, fitted, full)}
+    pairs = [scored(full, frame, base, choices.get(base["pred"]) or {}, images, context, bins, sample, worst)
+             for base in bases]
+    return {"rows": int(len(frame)), "pairs": pairs, "overview": overview_of(pairs)}

kalfa/records/stats/classes.py

@@ -0,0 +1,236 @@
+import numpy
+import pandas
+
+from .measures import histogram
+from .pairs import label_columns
+from .tables import finite, labels, numbers_of, ordered_labels, plain, present, texts
+
+
+RATES = ("accuracy", "precision", "recall", "f1", "specificity", "balanced_accuracy")
+SWEEP = 101
+CURVE = 2000
+COMPLEMENT = "1 - "
+NEGATED = "-"
+
+
+def ratio(part, whole):
+    return float(part) / float(whole) if whole else 0.0
+
+
+def positive_column(scores, output, classes):
+    named = label_columns(scores, output, classes).get(classes[1])
+    if named is not None:
+        return named
+    if len(scores) == 2:
+        return scores[1]
+    return scores[0] if len(scores) == 1 else None
+
+
+def thin(*arrays, limit=CURVE):
+    size = len(arrays[0])
+    if size <= limit:
+        return arrays
+    chosen = numpy.unique(numpy.round(numpy.linspace(0, size - 1, limit)).astype(int))
+    return tuple(array[chosen] for array in arrays)
+
+
+def binary_curves(truth, probabilities):
+    from sklearn.metrics import average_precision_score, precision_recall_curve, roc_auc_score, roc_curve
+
+    if len(numpy.unique(truth)) < 2:
+        return None, None
+    fpr, tpr, _ = roc_curve(truth, probabilities)
+    precision, recall, _ = precision_recall_curve(truth, probabilities)
+    fpr, tpr = thin(fpr, tpr)
+    precision, recall = thin(precision, recall)
+    roc = {"fpr": plain(fpr), "tpr": plain(tpr), "auc": float(roc_auc_score(truth, probabilities))}
+    pr = {"precision": plain(precision), "recall": plain(recall),
+          "ap": float(average_precision_score(truth, probabilities))}
+    return roc, pr
+
+
+def per_class_of(classes, confusion):
+    found = {}
+    for index, label in enumerate(classes):
+        hits = int(confusion[index, index])
+        predicted, actual = int(confusion[:, index].sum()), int(confusion[index, :].sum())
+        precision, recall = ratio(hits, predicted), ratio(hits, actual)
+        found[label] = {"precision": precision, "recall": recall,
+                        "f1": ratio(2 * precision * recall, precision + recall), "support": actual}
+    return found
+
+
+def confusion_of(classes, truth, guess):
+    position = {label: index for index, label in enumerate(classes)}
+    confusion = numpy.zeros((len(classes), len(classes)), dtype=numpy.int64)
+    for actual, predicted in zip(truth, guess):
+        confusion[position[actual], position[predicted]] += 1
+    return confusion
+
+
+def normalized(confusion):
+    totals = confusion.sum(axis=1, keepdims=True)
+    shares = numpy.divide(confusion, totals, out=numpy.zeros(confusion.shape, dtype=numpy.float64),
+                          where=totals > 0)
+    return shares.tolist()
+
+
+def classification_stats(frame, pred, target, raw=None, scores=None, classes=None):
+    guess, truth = texts(frame[pred]), texts(frame[target])
+    keep = present(guess) & present(truth)
+    guess, truth = guess[keep], truth[keep]
+    classes = labels(classes) or []
+    classes = classes + ordered_labels((set(truth.tolist()) | set(guess.tolist())) - set(classes))
+    confusion = confusion_of(classes, truth, guess)
+    count = int(len(truth))
+    roc = pr = None
+    output = pred[len("pred_"):] if pred.startswith("pred_") else pred
+    column = positive_column(list(scores), output, classes) if scores and len(classes) == 2 else None
+    if column is not None and column in frame.columns and count:
+        probabilities = pandas.to_numeric(frame[column], errors="coerce").to_numpy(dtype=numpy.float64)[keep]
+        finite_rows = numpy.isfinite(probabilities)
+        roc, pr = binary_curves((truth[finite_rows] == classes[1]).astype(int), probabilities[finite_rows])
+    return {"count": count, "accuracy": float(numpy.trace(confusion) / count) if count else None,
+            "classes": classes, "confusion": confusion.tolist(), "per_class": per_class_of(classes, confusion),
+            "roc": roc, "pr": pr}
+
+
+def rates(tn, fp, fn, tp):
+    count = tn + fp + fn + tp
+    if not count:
+        return {key: None for key in RATES}
+    recall, specificity = ratio(tp, tp + fn), ratio(tn, tn + fp)
+    present_rates = [rate for rate, size in ((recall, tp + fn), (specificity, tn + fp)) if size]
+    return {"accuracy": ratio(tp + tn, count), "precision": ratio(tp, tp + fp), "recall": recall,
+            "f1": ratio(2 * tp, 2 * tp + fp + fn), "specificity": specificity,
+            "balanced_accuracy": float(sum(present_rates) / len(present_rates))}
+
+
+def in_unit(values):
+    found = finite(values)
+    return not len(found) or (float(found.min()) >= 0.0 and float(found.max()) <= 1.0)
+
+
+def best_threshold(actual, values):
+    if not len(values):
+        return None
+    order = numpy.argsort(-values, kind="stable")
+    ranked, hits = values[order], actual[order]
+    tp, fp = numpy.cumsum(hits), numpy.cumsum(~hits)
+    ends = numpy.r_[ranked[1:] != ranked[:-1], True]
+    tp, fp, ranked = tp[ends], fp[ends], ranked[ends]
+    f1 = 2.0 * tp / numpy.maximum(tp + fp + int(hits.sum()), 1)
+    return float(ranked[int(numpy.argmax(f1))])
+
+
+def sweep_of(actual, values, unit):
+    if unit:
+        grid = numpy.linspace(0.0, 1.0, SWEEP)
+    else:
+        grid = numpy.unique(numpy.quantile(values, numpy.linspace(0.0, 1.0, SWEEP)))
+    positives, negatives = numpy.sort(values[actual]), numpy.sort(values[~actual])
+    tp = len(positives) - numpy.searchsorted(positives, grid, side="left")
+    fp = len(negatives) - numpy.searchsorted(negatives, grid, side="left")
+    fn = len(positives) - tp
+    return {"threshold": [float(value) for value in grid],
+            "precision": [ratio(hit, hit + miss) for hit, miss in zip(tp, fp)],
+            "recall": [ratio(hit, len(positives)) for hit in tp],
+            "f1": [ratio(2 * hit, 2 * hit + miss + lost) for hit, miss, lost in zip(tp, fp, fn)]}
+
+
+def score_hist_of(actual, values, unit, bins):
+    if unit:
+        edges = numpy.histogram_bin_edges(values, bins=bins, range=(0.0, 1.0))
+    else:
+        edges = numpy.histogram_bin_edges(values, bins=bins)
+    return {"edges": [float(edge) for edge in edges],
+            "negative": histogram(values[~actual], edges=edges)["counts"],
+            "positive": histogram(values[actual], edges=edges)["counts"]}
+
+
+def compared(values, threshold):
+    if threshold is None:
+        return numpy.zeros(len(values), dtype=bool)
+    with numpy.errstate(invalid="ignore"):
+        return values >= threshold
+
+
+def score_values(frame, score):
+    if score in frame.columns:
+        return numbers_of(frame[score])
+    if score.startswith(COMPLEMENT):
+        return 1.0 - numbers_of(frame[score[len(COMPLEMENT):]])
+    if score.startswith(NEGATED) and score[len(NEGATED):] in frame.columns:
+        return -numbers_of(frame[score[len(NEGATED):]])
+    return numbers_of(frame[score])
+
+
+def binary_rows(frame, pred, target, labels, score, threshold):
+    negative, positive = labels
+    truth = texts(frame[target])
+    keep = present(truth)
+    if score is None:
+        guess = texts(frame[pred])
+        return truth, guess, None, keep & present(guess)
+    values = score_values(frame, score)
+    guess = numpy.where(compared(values, threshold), positive, negative).astype(object)
+    return truth, guess, values, keep & numpy.isfinite(values)
+
+
+def binary_stats(frame, pred, target, labels, score=None, threshold=None, rule=None, unit=True, bins=40,
+                 candidates=None):
+    positive = labels[1]
+    truth, guess, values, keep = binary_rows(frame, pred, target, labels, score, threshold)
+    actual, predicted = (truth == positive)[keep].astype(bool), (guess == positive)[keep].astype(bool)
+    count = int(keep.sum())
+    tp, fp = int((actual & predicted).sum()), int((~actual & predicted).sum())
+    fn = int((actual & ~predicted).sum())
+    tn = count - tp - fp - fn
+    confusion = numpy.asarray([[tn, fp], [fn, tp]], dtype=numpy.int64)
+    stats = {"count": count, "labels": list(labels), "positive": positive, "score": score, "threshold": threshold,
+             "threshold_rule": rule, "confusion": confusion.tolist(), "confusion_normalized": normalized(confusion),
+             **rates(tn, fp, fn, tp), "roc": None, "pr": None, "score_hist": None, "sweep": None,
+             "candidates": list(candidates or []), "classes": list(labels),
+             "per_class": per_class_of(list(labels), confusion)}
+    if values is None or not count:
+        return stats
+    scored = values[keep]
+    stats["roc"], stats["pr"] = binary_curves(actual.astype(int), scored)
+    stats["score_hist"] = score_hist_of(actual, scored, unit, bins)
+    stats["sweep"] = sweep_of(actual, scored, unit)
+    return stats
+
+
+def multiclass_rows(frame, pred, target):
+    truth, guess = texts(frame[target]), texts(frame[pred])
+    return truth, guess, present(truth) & present(guess)
+
+
+def multiclass_stats(frame, pred, target, classes=None, scores=None):
+    truth, guess, keep = multiclass_rows(frame, pred, target)
+    truth, guess = truth[keep], guess[keep]
+    classes = list(classes or [])
+    classes = classes + ordered_labels((set(truth.tolist()) | set(guess.tolist())) - set(classes))
+    confusion = confusion_of(classes, truth, guess)
+    count = int(len(truth))
+    per_class = per_class_of(classes, confusion)
+    seen = [label for index, label in enumerate(classes) if confusion[index, :].sum() or confusion[:, index].sum()]
+    output = pred[len("pred_"):] if pred.startswith("pred_") else pred
+    columns = label_columns(scores or [], output, classes)
+    curves = {}
+    for label in classes:
+        column = columns.get(label)
+        if column is None or column not in frame.columns or not count:
+            continue
+        probabilities = numbers_of(frame[column])[keep]
+        rows = numpy.isfinite(probabilities)
+        roc, _ = binary_curves((truth[rows] == label).astype(int), probabilities[rows])
+        if roc is not None:
+            curves[label] = roc
+    return {"count": count, "classes": classes, "confusion": confusion.tolist(),
+            "confusion_normalized": normalized(confusion), "per_class": per_class,
+            "accuracy": ratio(numpy.trace(confusion), count) if count else None,
+            "macro_f1": float(numpy.mean([per_class[label]["f1"] for label in seen])) if seen else None,
+            "weighted_f1": float(sum(item["f1"] * item["support"] for item in per_class.values()) / count)
+            if count else None,
+            "roc": curves or None, "pr": None}

kalfa/records/stats/measures.py

@@ -0,0 +1,144 @@
+import numpy
+
+from .tables import finite, label_key, numbers_of, numeric, plain, rows_in, texts
+
+
+QUANTILES = {"p05": 0.05, "p25": 0.25, "p50": 0.5, "p75": 0.75, "p95": 0.95}
+COLORS = 20
+LABELS = 50
+
+
+def histogram(values, bins=40, edges=None):
+    array = finite(values)
+    if edges is not None:
+        counts, found = numpy.histogram(array, bins=numpy.asarray(edges, dtype=numpy.float64))
+    elif len(array):
+        counts, found = numpy.histogram(array, bins=bins)
+    else:
+        counts, found = numpy.histogram(array, bins=bins, range=(0.0, 1.0))
+    return {"edges": [float(edge) for edge in found], "counts": [int(count) for count in counts]}
+
+
+def quantiles_of(values):
+    if not len(values):
+        return {key: None for key in QUANTILES}
+    return {key: float(numpy.quantile(values, level)) for key, level in QUANTILES.items()}
+
+
+def regression_stats(frame, pred, target, bins=40, sample=2000, worst=20, seed=0, residual_bins=None):
+    guess = numbers_of(frame[pred])
+    truth = numbers_of(frame[target])
+    keep = numpy.isfinite(guess) & numpy.isfinite(truth)
+    guess, truth, rows = guess[keep], truth[keep], rows_in(frame)[keep]
+    count = int(len(guess))
+    residual = guess - truth
+    stats = {"count": count, "rmse": None, "mae": None, "r2": None, "bias": None,
+             "residual_quantiles": {key: None for key in QUANTILES},
+             "pred_hist": histogram(guess, bins), "truth_hist": histogram(truth, bins),
+             "residual_hist": histogram(residual, bins if residual_bins is None else residual_bins),
+             "scatter": {"row": [], "truth": [], "pred": []}, "worst": []}
+    if count == 0:
+        return stats
+    edges = numpy.histogram_bin_edges(numpy.concatenate([guess, truth]), bins=bins)
+    total = float(((truth - truth.mean()) ** 2).sum())
+    stats["rmse"] = float(numpy.sqrt((residual ** 2).mean()))
+    stats["mae"] = float(numpy.abs(residual).mean())
+    stats["r2"] = None if total == 0 else float(1.0 - float((residual ** 2).sum()) / total)
+    stats["bias"] = float(residual.mean())
+    stats["residual_quantiles"] = quantiles_of(residual)
+    stats["pred_hist"] = histogram(guess, edges=edges)
+    stats["truth_hist"] = histogram(truth, edges=edges)
+    chosen = numpy.arange(count)
+    if sample is not None and count > int(sample):
+        chosen = numpy.random.default_rng(seed).choice(count, int(sample), replace=False)
+    chosen = chosen[numpy.argsort(rows[chosen], kind="stable")]
+    stats["scatter"] = {"row": plain(rows[chosen]), "truth": plain(truth[chosen]), "pred": plain(guess[chosen])}
+    order = numpy.argsort(-numpy.abs(residual), kind="stable")[:max(int(worst or 0), 0)]
+    stats["worst"] = [{"row": row, "truth": float(truth[index]), "pred": float(guess[index]),
+                       "error": float(residual[index])} for index, row in zip(order, plain(rows[order]))]
+    return stats
+
+
+def matrix_of(frame, columns):
+    matrix = numpy.column_stack([numbers_of(frame[column]) for column in columns])
+    return matrix, numpy.isfinite(matrix).all(axis=1)
+
+
+def components(matrix):
+    centered = matrix - matrix.mean(axis=0)
+    _, spread, axes = numpy.linalg.svd(centered, full_matrices=False)
+    variance = spread ** 2
+    total = float(variance.sum())
+    axes = axes[:2]
+    signs = numpy.where(axes[numpy.arange(len(axes)), numpy.abs(axes).argmax(axis=1)] < 0, -1.0, 1.0)
+    coordinates = centered @ (axes * signs[:, None]).T
+    if coordinates.shape[1] < 2:
+        coordinates = numpy.column_stack([coordinates, numpy.zeros((len(coordinates), 2 - coordinates.shape[1]))])
+    explained = [float(variance[index] / total) if total > 0 and index < len(variance) else 0.0
+                 for index in range(2)]
+    return coordinates, explained
+
+
+def color_column(frame, targets, images=None):
+    columns = [str(column) for column in frame.columns]
+    if "label" in columns:
+        return "label"
+    for target in targets:
+        if target in columns:
+            return target
+    for column in columns:
+        if column in ("row", images) or column.startswith(("pred_", "raw_", "prob_")):
+            continue
+        series = frame[column]
+        if not numeric(series) and series.nunique(dropna=True) < COLORS:
+            return column
+    return None
+
+
+def sampled(count, sample, seed=0):
+    chosen = numpy.arange(count)
+    if sample is not None and count > int(sample):
+        chosen = numpy.sort(numpy.random.default_rng(seed).choice(count, int(sample), replace=False))
+    return chosen
+
+
+def embedding_stats(frame, columns, color=None, bins=40, sample=2000, seed=0):
+    matrix, keep = matrix_of(frame, columns)
+    matrix = matrix[keep]
+    count = int(len(matrix))
+    pca = {"x": [], "y": [], "explained": [None, None], "row": [], "index": [], "color": None, "color_by": color}
+    stats = {"count": count, "dims": len(columns), "pca": pca, "norm_hist": histogram([], bins)}
+    if not count:
+        return stats
+    coordinates, explained = components(matrix)
+    chosen = sampled(count, sample, seed)
+    positions = numpy.flatnonzero(keep)[chosen]
+    pca.update({"x": plain(coordinates[chosen, 0]), "y": plain(coordinates[chosen, 1]), "explained": explained,
+                "row": plain(rows_in(frame)[positions]), "index": [int(value) for value in frame.index[positions]]})
+    if color is not None:
+        pca["color"] = texts(frame[color].iloc[positions]).tolist()
+    stats["norm_hist"] = histogram(numpy.linalg.norm(matrix, axis=1), bins)
+    return stats
+
+
+def label_counts(values):
+    counts = {}
+    for value in values:
+        counts[value] = counts.get(value, 0) + 1
+    found = sorted(counts.items(), key=lambda item: (-item[1], label_key(item[0])))[:LABELS]
+    return {"labels": [label for label, _ in found], "counts": [count for _, count in found]}
+
+
+def values_stats(frame, pred, bins=40):
+    series = frame[pred]
+    if not numeric(series):
+        found = [value for value in texts(series).tolist() if value is not None]
+        return {"count": len(found), "mean": None, "std": None, "hist": None, "quantiles": None,
+                "labels": label_counts(found)}
+    values = finite(numbers_of(series))
+    count = int(len(values))
+    spread = {"min": float(values.min()) if count else None, **quantiles_of(values),
+              "max": float(values.max()) if count else None}
+    return {"count": count, "mean": float(values.mean()) if count else None,
+            "std": float(values.std()) if count else None, "hist": histogram(values, bins), "quantiles": spread,
+            "labels": None}