kalfa 3.0.0.dev0__py3-none-any.whl

kalfa/std/plots/curves.py

@@ -0,0 +1,56 @@
+from kalfa.records import reader
+from kalfa.std.plots.common import LEGEND_LIMIT, color_of, directory_of, dress, quiet, spans_decades
+
+
+DEFAULT_PREFIXES = ("train/", "val/")
+
+
+def turn_word(directory):
+    manifest = quiet(reader.read_manifest, directory) or {}
+    return "epoch" if manifest.get("unit") == "epochs" else "turn"
+
+
+def history_series(history, names=None):
+    found = {}
+    for position, line in enumerate(history):
+        turn = reader.turn_of(line, position)
+        for key, value in line.items():
+            if not isinstance(key, str) or not reader.is_number(value):
+                continue
+            if names is None and not key.startswith(DEFAULT_PREFIXES):
+                continue
+            if names is not None and key not in names:
+                continue
+            turns, values = found.setdefault(key, ([], []))
+            turns.append(turn)
+            values.append(value)
+    if names is not None:
+        return {name: found[name] for name in names if name in found}
+    return found
+
+
+def loss_curve(record, figures, series=None):
+    from matplotlib.ticker import MaxNLocator
+
+    directory = directory_of(record)
+    history = reader.read_history(directory)
+    names = None if series is None else ([series] if isinstance(series, str) else [str(name) for name in series])
+    found = history_series(history, names)
+    if not found:
+        return None
+    figure = figures.new(8.0, 5.0)
+    axis = figure.subplots()
+    for position, (name, (turns, values)) in enumerate(found.items()):
+        axis.plot(turns, values, label=name, color=color_of(figures, position), linewidth=1.8)
+    if spans_decades([value for _, values in found.values() for value in values]):
+        axis.set_yscale("log")
+    if len(found) <= LEGEND_LIMIT:
+        axis.legend(loc="upper right", frameon=False, ncols=1 if len(found) < 6 else 2)
+    word = turn_word(directory)
+    axis.xaxis.set_major_locator(MaxNLocator(integer=True))
+    axis.set_title(f"Training history ({len(history)} {word}s, {len(found)} series)", loc="left")
+    axis.set_xlabel(word)
+    axis.set_ylabel("value")
+    dress(axis)
+    figures.save(figure, "loss_curve")
+    return None

kalfa/std/plots/images.py

@@ -0,0 +1,188 @@
+import math
+
+import numpy
+
+from kalfa.core.errors import KalfaError
+from kalfa.std.plots.common import directory_of
+
+
+TEXT_LINES = 20
+TEXT_WIDTH = 120
+
+
+def first_output(outputs):
+    import torch
+
+    if isinstance(outputs, torch.Tensor):
+        return "output", outputs
+    items = outputs.items() if isinstance(outputs, dict) else enumerate(outputs or ())
+    for name, value in items:
+        if isinstance(value, torch.Tensor):
+            return str(name), value
+    return None, None
+
+
+def image_field(ctx, batch):
+    import torch
+
+    for name in getattr(getattr(ctx, "data", None), "inputs", None) or ():
+        if isinstance(batch.get(name), torch.Tensor):
+            return str(name)
+    for name, value in batch.items():
+        if isinstance(value, torch.Tensor) and value.ndim in (3, 4):
+            return str(name)
+    return None
+
+
+def shaped(output, images, name):
+    if output.shape[1:] == images.shape[1:]:
+        return output
+    if output.ndim >= 2 and len(output) == len(images) and output[0].numel() == images[0].numel():
+        return output.reshape(images.shape)
+    if output.ndim in (3, 4):
+        return output
+    raise KalfaError(f"image_pairs: the output {name!r} of shape {tuple(output.shape)} cannot be drawn like the "
+                     f"inputs of shape {tuple(images.shape)}")
+
+
+def pixels(images):
+    images = images.detach().float().cpu()
+    if images.ndim == 4:
+        if images.shape[1] not in (1, 3):
+            images = images[:, :1]
+        images = images.permute(0, 2, 3, 1)
+        if images.shape[-1] == 1:
+            images = images[..., 0]
+    return images.numpy()
+
+
+def show(axis, image, low, high):
+    scaled = numpy.clip((image - low) / (high - low), 0.0, 1.0) if high > low else numpy.zeros_like(image)
+    if scaled.ndim == 2:
+        axis.imshow(scaled, cmap="gray", vmin=0.0, vmax=1.0, interpolation="nearest")
+    else:
+        axis.imshow(scaled, interpolation="nearest")
+    axis.set_xticks([])
+    axis.set_yticks([])
+
+
+def image_pairs(record, figures, n=8, set="test", ctx=None):
+    import torch
+
+    if ctx is None:
+        raise KalfaError("image_pairs needs the run; redraw it with the record open")
+    loaders = ctx.loaders()
+    loader = loaders.get(set)
+    if loader is None:
+        raise KalfaError(f"image_pairs: the data has no {set!r} set; its sets are {sorted(loaders)}")
+    modes = getattr(ctx, "set_modes", None)
+    if callable(modes):
+        modes(False)
+    device = getattr(ctx, "device", None)
+    count = max(int(n), 1)
+    field = name = None
+    shown, guessed = [], []
+    with torch.no_grad():
+        for batch in loader:
+            if device is not None:
+                batch = device.move(batch)
+            if not isinstance(batch, dict):
+                raise KalfaError("image_pairs needs batches that map field names to tensors")
+            field = field or image_field(ctx, batch)
+            if field is None:
+                raise KalfaError(f"image_pairs: none of the batch fields {sorted(batch)} holds images")
+            images = batch[field]
+            if images.ndim not in (3, 4):
+                raise KalfaError(f"image_pairs: the input {field!r} of shape {tuple(images.shape)} is not a batch of "
+                                 f"images")
+            name, output = first_output(ctx.step.predict(batch, ctx))
+            if output is None:
+                raise KalfaError("image_pairs: the run predicts no tensor; train.predicts names the model to draw")
+            shown.append(images.detach().float().cpu())
+            guessed.append(shaped(output, images, name).detach().float().cpu())
+            if sum(len(piece) for piece in shown) >= count:
+                break
+    if not shown:
+        return None
+    inputs = pixels(torch.cat(shown)[:count])
+    outputs = pixels(torch.cat(guessed)[:count])
+    total = min(len(inputs), len(outputs))
+    values = numpy.concatenate([inputs[:total].reshape(-1), outputs[:total].reshape(-1)])
+    values = values[numpy.isfinite(values)]
+    low, high = (float(values.min()), float(values.max())) if values.size else (0.0, 1.0)
+    figure = figures.new(max(1.3 * total + 0.8, 3.2), 3.2)
+    axes = figure.subplots(2, total, squeeze=False)
+    for row, (images, label) in enumerate(((inputs, field), (outputs, name))):
+        for column in range(total):
+            show(axes[row][column], images[column], low, high)
+        axes[row][0].set_ylabel(label)
+    figure.suptitle(f"{field} and {name} ({set}, n = {total})", x=0.02, ha="left")
+    figures.save(figure, "image_pairs")
+    return None
+
+
+def sample_images(samples, path):
+    import torch
+
+    if isinstance(samples, (list, tuple)) and samples and all(isinstance(item, torch.Tensor) for item in samples):
+        try:
+            samples = torch.stack([item.detach().cpu() for item in samples])
+        except RuntimeError as error:
+            raise KalfaError(f"samples_grid: the tensors in {path.name} differ in shape: {error}") from None
+    if not isinstance(samples, torch.Tensor) or samples.ndim not in (3, 4) or not len(samples):
+        if isinstance(samples, torch.Tensor):
+            kind = f"a tensor of shape {tuple(samples.shape)}"
+        else:
+            kind = f"a {type(samples).__name__}"
+        raise KalfaError(f"samples_grid: {path.name} holds {kind}, not a batch of images (N, C, H, W)")
+    images = samples.detach().float().cpu()
+    if images.ndim == 4 and images.shape[1] not in (1, 3):
+        images = images[:, :1]
+    return images
+
+
+def text_sheet(path, figures, lines=None):
+    if lines is None:
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    shown = [line.expandtabs(4) for line in lines[:TEXT_LINES]]
+    shown = [line if len(line) <= TEXT_WIDTH else line[:TEXT_WIDTH - 3] + "..." for line in shown]
+    figure = figures.new(10.0, 0.8 + 0.22 * max(len(shown), 1))
+    axis = figure.subplots()
+    axis.axis("off")
+    axis.text(0.0, 1.0, "\n".join(shown) or "(empty)", family="monospace", fontsize=9, va="top", ha="left",
+              transform=axis.transAxes, parse_math=False)
+    axis.set_title(f"{path.name} (first {len(shown)} of {len(lines)} lines)", loc="left")
+    figures.save(figure, "samples_grid")
+    return None
+
+
+def samples_grid(record, figures, n=8, file="samples"):
+    import torch
+
+    from kalfa.std.samples import image_grid, is_text
+
+    directory = directory_of(record) / "samples"
+    stem = str(file)
+    names = [stem] if stem.endswith((".pt", ".txt")) else [f"{stem}.pt", f"{stem}.txt"]
+    path = next((directory / name for name in names if (directory / name).is_file()), None)
+    if path is None:
+        wanted = " or ".join(f"samples/{name}" for name in names)
+        raise KalfaError(f"samples_grid: {wanted} is missing in {directory.parent}; a sampler under generate or a "
+                         f"write_samples rule writes it")
+    if path.suffix == ".txt":
+        return text_sheet(path, figures)
+    loaded = torch.load(path, map_location="cpu", weights_only=False)
+    if is_text(loaded):
+        return text_sheet(path, figures, "\n\n".join(loaded).splitlines())
+    images = sample_images(loaded, path)
+    count = min(len(images), max(int(n), 1))
+    grid = image_grid(images[:count], columns=math.ceil(math.sqrt(count)))
+    height, width = grid.shape[:2]
+    scale = 8.0 / max(height, width)
+    figure = figures.new(max(width * scale + 0.4, 3.0), height * scale + 0.8)
+    axis = figure.subplots()
+    axis.imshow(grid, interpolation="nearest")
+    axis.axis("off")
+    axis.set_title(f"{path.name} ({count} of {len(images)} samples)", loc="left")
+    figures.save(figure, "samples_grid")
+    return None

kalfa/std/plots/pairs.py

@@ -0,0 +1,66 @@
+from kalfa.records import stats
+
+
+def read_predictions(directory):
+    frame = stats.read_predictions(directory)
+    return frame if frame is not None and len(frame) else None
+
+
+def pred_column(output):
+    return output if str(output).startswith("pred_") else f"pred_{output}"
+
+
+def prediction_pairs(frame, plan, pairs=None):
+    columns = [str(column) for column in frame.columns]
+    if pairs:
+        chosen = [(pred_column(output), str(target)) for output, target in dict(pairs).items()]
+        return [(pred, target) for pred, target in chosen if pred in columns and target in columns]
+    found = [(pair["pred"], pair["target"]) for pair in stats.prediction_pairs(frame, plan)]
+    paired = {pred for pred, _ in found}
+    preds = [column for column in columns if column.startswith("pred_") and column not in paired
+             and stats.spread_member(column, columns) is None]
+    targets = [name for name in stats.plan_targets(plan) if name in columns]
+    if not targets:
+        targets = [column for column in columns
+                   if not column.startswith(("pred_", "raw_", "prob_")) and column not in ("row", "set")]
+    if len(targets) == 1:
+        found.extend((pred, targets[0]) for pred in preds)
+        return found
+    for pred in preds:
+        output = pred[len("pred_"):]
+        matches = [target for target in targets if output == target or output.endswith(f"_{target}")]
+        if matches:
+            found.append((pred, max(matches, key=len)))
+    return found
+
+
+def pick_pair(frame, plan, pred=None, target=None):
+    column = None if pred is None else pred_column(pred)
+    if column is not None and target is not None:
+        columns = [str(name) for name in frame.columns]
+        return (column, str(target)) if column in columns and str(target) in columns else None
+    for found_pred, found_target in prediction_pairs(frame, plan):
+        if column is not None and found_pred != column:
+            continue
+        if target is not None and found_target != str(target):
+            continue
+        return found_pred, found_target
+    return None
+
+
+def chosen_pair(frame, plan, fitted, pred=None, target=None, prefer=None):
+    columns = [str(column) for column in frame.columns]
+    column = None if pred is None else pred_column(pred)
+    if column is not None and target is not None:
+        target = str(target)
+        if column not in columns or target not in columns:
+            return None
+        output = column[len("pred_"):]
+        scores = [name for name in columns if name.startswith(f"prob_{output}_")]
+        raw = f"raw_{output}" if f"raw_{output}" in columns else None
+        kind = stats.kind_of(frame, target, stats.classes_for(plan, fitted, target), scores)
+        return {"output": output, "pred": column, "target": target, "kind": kind, "raw": raw, "scores": scores}
+    found = [pair for pair in stats.prediction_pairs(frame, plan, fitted)
+             if (column is None or pair["pred"] == column) and (target is None or pair["target"] == str(target))]
+    preferred = [pair for pair in found if pair["kind"] == prefer]
+    return (preferred or found or [None])[0]

kalfa/std/plots/predictions.py

@@ -0,0 +1,154 @@
+import re
+
+import numpy
+
+from kalfa.records import reader, stats
+from kalfa.std.plots.common import color_of, directory_of, dress, label_text, quiet
+from kalfa.std.plots.pairs import chosen_pair, pred_column, prediction_pairs, read_predictions
+
+
+HORIZON = re.compile(r"(.+)_(\d+)")
+
+
+def numeric(frame, column):
+    return frame[column].dtype.kind in "fiu"
+
+
+def r_squared(truth, guess):
+    spread = float(numpy.sum((truth - truth.mean()) ** 2))
+    if spread <= 0:
+        return None
+    return 1.0 - float(numpy.sum((guess - truth) ** 2)) / spread
+
+
+def pred_vs_true(record, figures, pairs=None):
+    directory = directory_of(record)
+    frame = read_predictions(directory)
+    if frame is None:
+        return None
+    chosen = [(pred, target) for pred, target in prediction_pairs(frame, quiet(reader.read_plan, directory), pairs)
+              if numeric(frame, pred) and numeric(frame, target)]
+    if not chosen:
+        return None
+    columns = min(3, len(chosen))
+    rows = -(-len(chosen) // columns)
+    figure = figures.new(4.8 * columns, 4.4 * rows)
+    panels = [axis for row in figure.subplots(rows, columns, squeeze=False) for axis in row]
+    for axis, (pred, target) in zip(panels, chosen):
+        truth = frame[target].to_numpy(dtype="float64", na_value=numpy.nan)
+        guess = frame[pred].to_numpy(dtype="float64", na_value=numpy.nan)
+        keep = numpy.isfinite(truth) & numpy.isfinite(guess)
+        truth, guess = truth[keep], guess[keep]
+        if not len(truth):
+            axis.axis("off")
+            continue
+        axis.scatter(truth, guess, s=12, alpha=0.5, color=color_of(figures, 0), edgecolors="none", rasterized=True)
+        low = float(min(truth.min(), guess.min()))
+        high = float(max(truth.max(), guess.max()))
+        axis.plot([low, high], [low, high], color=color_of(figures, 1), linewidth=1.5, label="y = x")
+        axis.legend(loc="upper left", frameon=False)
+        score = r_squared(truth, guess)
+        note = f"R² {score:.3f}, " if score is not None else ""
+        axis.set_title(f"{target} ({note}n = {len(truth):,})", loc="left")
+        axis.set_xlabel(f"true {target}")
+        axis.set_ylabel(f"predicted ({pred[len('pred_'):]})")
+        dress(axis)
+    for axis in panels[len(chosen):]:
+        axis.axis("off")
+    figures.save(figure, "pred_vs_true")
+    return None
+
+
+def indexed(columns, name):
+    found = {}
+    for column in columns:
+        match = HORIZON.fullmatch(column)
+        if match is not None and match.group(1) == name:
+            found[int(match.group(2))] = column
+    return found
+
+
+def horizon_pair(frame, plan, pred=None, target=None):
+    columns = [str(column) for column in frame.columns]
+    stems = []
+    for column in columns:
+        match = HORIZON.fullmatch(column)
+        if match is not None and match.group(1) not in stems:
+            stems.append(match.group(1))
+    if pred is not None:
+        outputs = [pred_column(pred)[len("pred_"):]]
+    else:
+        outputs = [stem[len("pred_"):] for stem in stems if stem.startswith("pred_")]
+    known = [stem for stem in stems if not stem.startswith(("pred_", "raw_", "prob_"))]
+    pairings = stats.plan_pairings(plan)
+    for output in outputs:
+        guesses = indexed(columns, f"pred_{output}")
+        names = [str(target)] if target is not None else [pairings.get(output), *stats.plan_targets(plan), *known]
+        for name in names:
+            truths = indexed(columns, name) if name else {}
+            steps = sorted(step for step in guesses if step in truths)
+            if steps:
+                return output, name, [truths[step] for step in steps], [guesses[step] for step in steps]
+    return None
+
+
+def forecast_series(frame, plan, fitted, figures, pred, target):
+    pair = chosen_pair(frame, plan, fitted, pred, target, prefer="regression")
+    if pair is None or not numeric(frame, pair["pred"]) or not numeric(frame, pair["target"]):
+        return None
+    rows = frame["row"].to_numpy() if "row" in frame.columns else numpy.arange(len(frame))
+    truth = frame[pair["target"]].to_numpy(dtype="float64", na_value=numpy.nan)
+    guess = frame[pair["pred"]].to_numpy(dtype="float64", na_value=numpy.nan)
+    figure = figures.new(9.0, 4.2)
+    axis = figure.subplots()
+    axis.plot(rows, truth, color=color_of(figures, 0), linewidth=1.4, label="true")
+    axis.plot(rows, guess, color=color_of(figures, 1), linewidth=1.4, linestyle="--", label="predicted")
+    axis.legend(loc="upper right", frameon=False)
+    axis.set_title(f"{pair['target']} over rows (n = {len(frame):,})", loc="left")
+    axis.set_xlabel("row")
+    axis.set_ylabel(f"{pair['target']} and {pair['output']}")
+    dress(axis)
+    figures.save(figure, "forecast_samples")
+    return None
+
+
+def forecast_samples(record, figures, n=4, pred=None, target=None):
+    from matplotlib.ticker import MaxNLocator
+
+    directory = directory_of(record)
+    frame = stats.read_predictions(directory)
+    if frame is None or not len(frame):
+        return None
+    plan = quiet(reader.read_plan, directory)
+    if "row" in frame.columns:
+        frame = frame.sort_values("row", kind="stable")
+    found = horizon_pair(frame, plan, pred, target)
+    if found is None:
+        return forecast_series(frame, plan, quiet(reader.fields_of, directory), figures, pred, target)
+    output, name, truths, guesses = found
+    picked = numpy.unique(numpy.linspace(0, len(frame) - 1, min(max(int(n), 1), len(frame))).round().astype(int))
+    columns = 1 if len(picked) == 1 else 2
+    rows = -(-len(picked) // columns)
+    figure = figures.new(5.2 * columns, 2.4 * rows + 0.8)
+    panels = [axis for line in figure.subplots(rows, columns, squeeze=False) for axis in line]
+    steps = numpy.arange(1, len(truths) + 1)
+    truth = frame[truths].to_numpy(dtype="float64", na_value=numpy.nan)
+    guess = frame[guesses].to_numpy(dtype="float64", na_value=numpy.nan)
+    labels = frame["row"].to_numpy() if "row" in frame.columns else frame.index.to_numpy()
+    for index, (axis, position) in enumerate(zip(panels, picked)):
+        axis.plot(steps, truth[position], color=color_of(figures, 0), linewidth=1.8, marker="o", markersize=3,
+                  label="true")
+        axis.plot(steps, guess[position], color=color_of(figures, 1), linewidth=1.8, linestyle="--",
+                  label="predicted")
+        axis.set_title(f"row {label_text(labels[position])}", loc="left")
+        axis.xaxis.set_major_locator(MaxNLocator(integer=True))
+        if index + columns >= len(picked):
+            axis.set_xlabel("steps ahead")
+        dress(axis)
+    for axis in panels[len(picked):]:
+        axis.axis("off")
+    panels[0].legend(loc="upper left", frameon=False)
+    figure.suptitle(f"Forecast windows ({name} against {output}, {len(steps)} steps, {len(picked)} of "
+                    f"{len(frame):,} rows)", x=0.02, ha="left")
+    figures.save(figure, "forecast_samples")
+    return None