continuousintelligence 0.1.0__py3-none-any.whl

continuousintelligence/__init__.py

@@ -0,0 +1,9 @@
+"""Continuous Intelligence models."""
+
+from . import ci_proto
+from ._example import load_example
+from ._loader import load_model
+from ._plot import plot_forecast
+from .ci_proto import Forecaster
+
+__all__ = ["ci_proto", "Forecaster", "load_example", "load_model", "plot_forecast"]

continuousintelligence/_data/NOTICE

@@ -0,0 +1,16 @@
+Bike Sharing dataset — hourly bicycle rentals in Washington, D.C.
+
+Hadi Fanaee-T (2013). Bike Sharing [Dataset]. UCI Machine Learning Repository.
+https://doi.org/10.24432/C5W894
+Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0):
+https://creativecommons.org/licenses/by/4.0/
+
+Source: https://archive.ics.uci.edu/static/public/275/bike+sharing+dataset.zip
+Extract: hour.csv, total rentals (cnt), 9–13 June 2012 (120 hourly observations).
+Changes: selected dates and columns, renamed cnt to rentals; no smoothing or imputation.
+The following 24 rows contain forecast timestamps only; their values are empty.
+
+Publication requested by the source dataset:
+Fanaee-T, H. and Gama, J. (2013). Event labeling combining ensemble detectors and
+background knowledge. Progress in Artificial Intelligence.
+https://doi.org/10.1007/s13748-013-0040-3

continuousintelligence/_data/bike_sharing.csv

@@ -0,0 +1,145 @@
+timestamp,rentals,split
+2012-06-09T00:00:00,206,history
+2012-06-09T01:00:00,123,history
+2012-06-09T02:00:00,89,history
+2012-06-09T03:00:00,40,history
+2012-06-09T04:00:00,8,history
+2012-06-09T05:00:00,19,history
+2012-06-09T06:00:00,80,history
+2012-06-09T07:00:00,87,history
+2012-06-09T08:00:00,244,history
+2012-06-09T09:00:00,340,history
+2012-06-09T10:00:00,466,history
+2012-06-09T11:00:00,569,history
+2012-06-09T12:00:00,531,history
+2012-06-09T13:00:00,585,history
+2012-06-09T14:00:00,593,history
+2012-06-09T15:00:00,555,history
+2012-06-09T16:00:00,534,history
+2012-06-09T17:00:00,495,history
+2012-06-09T18:00:00,451,history
+2012-06-09T19:00:00,360,history
+2012-06-09T20:00:00,363,history
+2012-06-09T21:00:00,316,history
+2012-06-09T22:00:00,214,history
+2012-06-09T23:00:00,230,history
+2012-06-10T00:00:00,158,history
+2012-06-10T01:00:00,116,history
+2012-06-10T02:00:00,73,history
+2012-06-10T03:00:00,29,history
+2012-06-10T04:00:00,10,history
+2012-06-10T05:00:00,13,history
+2012-06-10T06:00:00,30,history
+2012-06-10T07:00:00,62,history
+2012-06-10T08:00:00,181,history
+2012-06-10T09:00:00,266,history
+2012-06-10T10:00:00,413,history
+2012-06-10T11:00:00,499,history
+2012-06-10T12:00:00,502,history
+2012-06-10T13:00:00,492,history
+2012-06-10T14:00:00,500,history
+2012-06-10T15:00:00,475,history
+2012-06-10T16:00:00,508,history
+2012-06-10T17:00:00,521,history
+2012-06-10T18:00:00,490,history
+2012-06-10T19:00:00,375,history
+2012-06-10T20:00:00,363,history
+2012-06-10T21:00:00,253,history
+2012-06-10T22:00:00,159,history
+2012-06-10T23:00:00,110,history
+2012-06-11T00:00:00,41,history
+2012-06-11T01:00:00,24,history
+2012-06-11T02:00:00,17,history
+2012-06-11T03:00:00,6,history
+2012-06-11T04:00:00,7,history
+2012-06-11T05:00:00,37,history
+2012-06-11T06:00:00,144,history
+2012-06-11T07:00:00,503,history
+2012-06-11T08:00:00,651,history
+2012-06-11T09:00:00,316,history
+2012-06-11T10:00:00,147,history
+2012-06-11T11:00:00,202,history
+2012-06-11T12:00:00,261,history
+2012-06-11T13:00:00,248,history
+2012-06-11T14:00:00,259,history
+2012-06-11T15:00:00,259,history
+2012-06-11T16:00:00,427,history
+2012-06-11T17:00:00,800,history
+2012-06-11T18:00:00,831,history
+2012-06-11T19:00:00,596,history
+2012-06-11T20:00:00,394,history
+2012-06-11T21:00:00,250,history
+2012-06-11T22:00:00,164,history
+2012-06-11T23:00:00,80,history
+2012-06-12T00:00:00,28,history
+2012-06-12T01:00:00,16,history
+2012-06-12T02:00:00,6,history
+2012-06-12T03:00:00,12,history
+2012-06-12T04:00:00,4,history
+2012-06-12T05:00:00,29,history
+2012-06-12T06:00:00,136,history
+2012-06-12T07:00:00,303,history
+2012-06-12T08:00:00,613,history
+2012-06-12T09:00:00,285,history
+2012-06-12T10:00:00,125,history
+2012-06-12T11:00:00,65,history
+2012-06-12T12:00:00,95,history
+2012-06-12T13:00:00,59,history
+2012-06-12T14:00:00,60,history
+2012-06-12T15:00:00,116,history
+2012-06-12T16:00:00,239,history
+2012-06-12T17:00:00,681,history
+2012-06-12T18:00:00,653,history
+2012-06-12T19:00:00,491,history
+2012-06-12T20:00:00,386,history
+2012-06-12T21:00:00,274,history
+2012-06-12T22:00:00,207,history
+2012-06-12T23:00:00,89,history
+2012-06-13T00:00:00,34,history
+2012-06-13T01:00:00,28,history
+2012-06-13T02:00:00,4,history
+2012-06-13T03:00:00,8,history
+2012-06-13T04:00:00,10,history
+2012-06-13T05:00:00,40,history
+2012-06-13T06:00:00,194,history
+2012-06-13T07:00:00,505,history
+2012-06-13T08:00:00,713,history
+2012-06-13T09:00:00,352,history
+2012-06-13T10:00:00,198,history
+2012-06-13T11:00:00,246,history
+2012-06-13T12:00:00,334,history
+2012-06-13T13:00:00,255,history
+2012-06-13T14:00:00,320,history
+2012-06-13T15:00:00,281,history
+2012-06-13T16:00:00,392,history
+2012-06-13T17:00:00,857,history
+2012-06-13T18:00:00,744,history
+2012-06-13T19:00:00,671,history
+2012-06-13T20:00:00,448,history
+2012-06-13T21:00:00,396,history
+2012-06-13T22:00:00,238,history
+2012-06-13T23:00:00,153,history
+2012-06-14T00:00:00,,forecast
+2012-06-14T01:00:00,,forecast
+2012-06-14T02:00:00,,forecast
+2012-06-14T03:00:00,,forecast
+2012-06-14T04:00:00,,forecast
+2012-06-14T05:00:00,,forecast
+2012-06-14T06:00:00,,forecast
+2012-06-14T07:00:00,,forecast
+2012-06-14T08:00:00,,forecast
+2012-06-14T09:00:00,,forecast
+2012-06-14T10:00:00,,forecast
+2012-06-14T11:00:00,,forecast
+2012-06-14T12:00:00,,forecast
+2012-06-14T13:00:00,,forecast
+2012-06-14T14:00:00,,forecast
+2012-06-14T15:00:00,,forecast
+2012-06-14T16:00:00,,forecast
+2012-06-14T17:00:00,,forecast
+2012-06-14T18:00:00,,forecast
+2012-06-14T19:00:00,,forecast
+2012-06-14T20:00:00,,forecast
+2012-06-14T21:00:00,,forecast
+2012-06-14T22:00:00,,forecast
+2012-06-14T23:00:00,,forecast

continuousintelligence/_example.py

@@ -0,0 +1,20 @@
+"""The bundled real-data forecasting example."""
+
+import csv
+from importlib.resources import files
+
+import torch
+from torch import Tensor
+
+
+def load_example() -> Tensor:
+    """Return the example's observed history as a CPU float32 tensor ``[1, 120]``.
+
+    Forecast rows are excluded. Each call returns a new tensor. Data attribution
+    and source information accompany the CSV in ``_data/NOTICE``.
+    """
+    with files("continuousintelligence").joinpath("_data/bike_sharing.csv").open() as stream:
+        values = [
+            float(row["rentals"]) for row in csv.DictReader(stream) if row["split"] == "history"
+        ]
+    return torch.tensor([values], dtype=torch.float32)

continuousintelligence/_loader.py

@@ -0,0 +1,140 @@
+"""Local and Hugging Face model loading for Continuous Intelligence."""
+
+import json
+import math
+import re
+from contextlib import nullcontext
+from functools import cache
+from pathlib import Path, PureWindowsPath
+
+import torch
+
+from .ci_proto import Forecaster
+
+_COMMIT = re.compile(r"[0-9a-f]{40}")
+
+
+def _device(name: str) -> torch.device:
+    if name == "auto":
+        name = "cuda" if torch.cuda.is_available() else "cpu"
+    if name not in ("cpu", "cuda"):
+        raise ValueError("device must be 'cpu', 'cuda', or 'auto'")
+    if name == "cuda" and not torch.cuda.is_available():
+        raise RuntimeError("CUDA was requested but is not available")
+    return torch.device(name)
+
+
+def _files(
+    source: str | Path, tta_config: str | Path | None, revision: str | None
+) -> tuple[Path, Path, Path | None]:
+    path = Path(source).expanduser()
+    if path.exists():
+        if revision is not None:
+            raise ValueError("revision applies only to Hugging Face models")
+    else:
+        if (
+            isinstance(source, Path)
+            or str(source).startswith(("/", "./", "../", "~", ".\\", "..\\"))
+            or "\\" in str(source)
+            or PureWindowsPath(source).drive
+            or str(source).count("/") != 1
+            or path.parent.is_dir()
+            or path.suffix in (".ckpt", ".pt", ".pth")
+            or tta_config is not None
+        ):
+            raise FileNotFoundError(path)
+        from huggingface_hub import hf_hub_download, snapshot_download
+
+        info = Path(hf_hub_download(repo_id=str(source), filename="config.json", revision=revision))
+        commit = info.parent.name if _COMMIT.fullmatch(info.parent.name) else revision
+        path = Path(
+            snapshot_download(
+                repo_id=str(source),
+                revision=commit,
+                allow_patterns=["model.ckpt", "model-long.ckpt", "tta.json"],
+            )
+        )
+    info = None
+    if path.is_dir():
+        if tta_config is not None:
+            raise ValueError("a model bundle uses its own tta.json")
+        info = path / "config.json" if (path / "config.json").is_file() else None
+        path, tta_config = path / "model.ckpt", path / "tta.json"
+    elif tta_config is None:
+        raise ValueError("a standalone checkpoint requires tta_config")
+    tta = Path(tta_config).expanduser()
+    for file in (path, tta):
+        if not file.is_file():
+            raise FileNotFoundError(file)
+    return path, tta, info
+
+
+def _model_info(path: Path, forecaster: Forecaster) -> dict:
+    """Read a bundle's ``config.json`` and check it describes the loaded weights."""
+    info = json.loads(path.read_text())
+    if not isinstance(info, dict):
+        raise ValueError("config.json must contain a JSON object")
+    missing = {"name", "parameters", "quantiles"} - set(info)
+    if missing:
+        raise ValueError(f"config.json is missing {sorted(missing)}")
+    model = forecaster._model
+    quantiles = forecaster.quantiles.tolist()
+    if (
+        not isinstance(info["quantiles"], list)
+        or len(info["quantiles"]) != len(quantiles)
+        or not all(
+            isinstance(given, (int, float)) and math.isclose(given, level, abs_tol=1e-6)
+            for given, level in zip(info["quantiles"], quantiles, strict=True)
+        )
+    ):
+        raise ValueError("config.json quantiles do not match the checkpoint")
+    if info["parameters"] != sum(parameter.numel() for parameter in model.parameters()):
+        raise ValueError("config.json parameters do not match the checkpoint")
+    return info
+
+
+def load_model(
+    checkpoint: str | Path,
+    tta_config: str | Path | None = None,
+    device: str = "auto",
+    *,
+    revision: str | None = None,
+) -> Forecaster:
+    """Load a local model bundle, Hugging Face model ID, or checkpoint plus TTA file.
+
+    Bundles contain ``model.ckpt`` (weights and embedded architecture) and
+    ``tta.json``. Hub bundles also contain ``config.json``, which describes the
+    model and is returned by ``Forecaster.info``; it is checked against the
+    weights. Hub files are fetched together from the same revision;
+    pass a commit SHA to pin it. Hub IDs use ``owner/model`` strings. Use a
+    ``Path`` or ``./`` prefix to mark an ambiguous relative path as local.
+    An optional ``model-long.ckpt`` shares the bundle's TTA and is selected
+    when history exceeds the primary checkpoint's context length.
+    """
+    placement = _device(device)
+    path, tta_path, info_path = _files(checkpoint, tta_config, revision)
+    payload = torch.load(path, map_location="cpu", weights_only=True, mmap=True)
+    from .ci_proto._checkpoint import from_checkpoint
+
+    forecaster = from_checkpoint(payload, tta_path, placement)
+    placement = forecaster.device
+    if info_path is not None:
+        forecaster._info = _model_info(info_path, forecaster)
+    long_path = path.with_name("model-long.ckpt")
+    if tta_config is None and long_path.is_file() and forecaster._model.config.context_len:
+        quantiles = forecaster.quantiles
+        future_len = forecaster._model.config.future_len
+
+        @cache
+        def load_long() -> Forecaster:
+            context = torch.cuda.device(placement) if placement.type == "cuda" else nullcontext()
+            with context:
+                long = load_model(long_path, tta_path, device=placement.type)
+            if not torch.equal(long.quantiles, quantiles) or (
+                long._model.config.future_len != future_len
+            ):
+                raise ValueError("long checkpoint must have the same quantiles and forecast window")
+            return long
+
+        forecaster._long_model = load_long
+    return forecaster

continuousintelligence/_plot.py

@@ -0,0 +1,158 @@
+"""Plot observed history and forecast quantiles."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import torch
+from torch import Tensor
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+
+def plot_forecast(
+    history: Tensor,
+    prediction: Tensor,
+    quantiles: Tensor,
+    *,
+    timestamps: Sequence | Tensor | None = None,
+    ylabel: str = "Value",
+    output: str | Path | None = None,
+) -> Figure:
+    """Plot ``[variables, time]`` history and ``[variables, quantiles, horizon]`` predictions.
+
+    ``quantiles`` is the model's probability grid. Each variable gets one panel,
+    showing the median and available nested intervals between 0.1 and 0.9.
+    ``timestamps`` may supply a shared date axis covering history plus horizon;
+    otherwise the forecast starts at step zero. Returns a Matplotlib figure and
+    optionally saves it to ``output``.
+    """
+    if any(not isinstance(value, Tensor) for value in (history, prediction, quantiles)):
+        raise ValueError("history, prediction and quantiles must be PyTorch tensors")
+    if any(value.is_complex() for value in (history, prediction, quantiles)):
+        raise ValueError("plot inputs must be real")
+    if history.ndim != 2 or min(history.shape) < 1:
+        raise ValueError("history must be a nonempty [variables, time] tensor")
+    if prediction.ndim != 3 or min(prediction.shape) < 1 or prediction.shape[0] != history.shape[0]:
+        raise ValueError("prediction must have shape [variables, quantiles, horizon]")
+    if (
+        quantiles.ndim != 1
+        or len(quantiles) != prediction.shape[1]
+        or not bool(((quantiles > 0) & (quantiles < 1)).all())
+        or not bool((quantiles.diff() > 0).all())
+    ):
+        raise ValueError("quantiles must be a matching, strictly increasing probability grid")
+    if bool(history.isinf().any()) or not bool(prediction.isfinite().all()):
+        raise ValueError("history must be finite or NaN and predictions must be finite")
+    history, prediction, quantiles = (
+        value.detach().cpu().float() for value in (history, prediction, quantiles)
+    )
+    levels = torch.arange(1, 10) / 10
+    columns = (quantiles[:, None] - levels).abs().argmin(dim=0)
+    available = torch.isclose(quantiles[columns], levels, atol=1e-6, rtol=0)
+    if not available[4]:
+        raise ValueError("quantiles must include the median (0.5)")
+    import matplotlib.dates as mdates
+    import matplotlib.pyplot as plt
+    from matplotlib import font_manager
+
+    count, length = history.shape
+    horizon = prediction.shape[-1]
+    if timestamps is None:
+        times = torch.arange(-length, horizon).numpy()
+    else:
+        import pandas as pd
+
+        if isinstance(timestamps, Tensor):
+            timestamps = timestamps.detach().cpu().numpy()
+        times = pd.DatetimeIndex(pd.to_datetime(timestamps))
+        if len(times) != length + horizon or times.hasnans or not times.is_unique:
+            raise ValueError("timestamps must cover history plus horizon without missing dates")
+        if not times.is_monotonic_increasing:
+            raise ValueError("timestamps must be strictly increasing")
+    past, future = times[:length], times[length:]
+    background, panel, teal = "#173446", "#1d3d50", "#549a8b"
+    white, muted, grid = "#fafbfb", "#b6c3c9", "#2d4d5d"
+    fonts = {font.name for font in font_manager.fontManager.ttflist}
+    with plt.rc_context(
+        {
+            "font.family": "Aptos" if "Aptos" in fonts else "DejaVu Sans",
+            "font.size": 14,
+            "axes.labelsize": 16,
+            "text.color": white,
+            "axes.labelcolor": muted,
+            "xtick.color": muted,
+            "ytick.color": muted,
+            "savefig.dpi": 180,
+        }
+    ):
+        figure, panels = plt.subplots(count, 1, figsize=(13.5, 5.8 * count), squeeze=False)
+        figure.set_facecolor(background)
+        figure.subplots_adjust(left=0.09, right=0.98, bottom=0.15 / count, top=0.97, hspace=0.3)
+        for index, axes in enumerate(panels[:, 0]):
+            axes.set_facecolor(panel)
+            axes.axvspan(future[0], future[-1], color="#214452", linewidth=0)
+            axes.axvline(future[0], color=teal, linewidth=1.2, linestyle=":")
+            axes.grid(color=grid, linewidth=0.7)
+            axes.set_axisbelow(True)
+            axes.spines[["top", "right", "left"]].set_visible(False)
+            axes.spines["bottom"].set_color(grid)
+            axes.tick_params(length=0, pad=8)
+            axes.set_xlim(past[0], future[-1])
+            axes.plot(past, history[index], color=white, linewidth=1.7, label="History")
+            for lo, hi, alpha in [(0, 8, 0.22), (1, 7, 0.20), (2, 6, 0.18), (3, 5, 0.16)]:
+                if available[lo] and available[hi]:
+                    axes.fill_between(
+                        future,
+                        prediction[index, columns[lo]],
+                        prediction[index, columns[hi]],
+                        color=teal,
+                        alpha=alpha,
+                        linewidth=0,
+                        label="10–90% quantiles" if lo == 0 else None,
+                    )
+            median = prediction[index, columns[4]]
+            axes.plot(
+                future, median, color="#76c6b3", linewidth=2.4, label="Median forecast", zorder=4
+            )
+            axes.plot(
+                [past[-1], future[0]],
+                [float(history[index, -1]), float(median[0])],
+                color="#76c6b3",
+                linewidth=1.5,
+                linestyle=":",
+            )
+            axes.set_ylabel(ylabel)
+            if count > 1:
+                axes.set_title(f"Series {index + 1}", color=white)
+            low, high = axes.get_ylim()
+            if low < 0 < high:
+                axes.axhline(0, color=muted, alpha=0.3, linewidth=0.8)
+            if timestamps is not None:
+                if times[-1] - times[0] <= pd.Timedelta(days=14):
+                    axes.xaxis.set_major_locator(mdates.DayLocator())
+                    axes.xaxis.set_major_formatter(mdates.DateFormatter("%a %d %b"))
+                else:
+                    locator = mdates.AutoDateLocator()
+                    axes.xaxis.set_major_locator(locator)
+                    axes.xaxis.set_major_formatter(mdates.ConciseDateFormatter(locator))
+            axes.legend(
+                loc="upper left",
+                frameon=True,
+                facecolor=background,
+                edgecolor=grid,
+                framealpha=0.95,
+                fontsize=15,
+                labelcolor=white,
+                borderpad=0.9,
+            )
+        if timestamps is None:
+            panels[-1, 0].set_xlabel("Time step relative to forecast origin")
+        if output is not None:
+            path = Path(output).expanduser()
+            path.parent.mkdir(parents=True, exist_ok=True)
+            figure.savefig(path, facecolor=figure.get_facecolor())
+    return figure

continuousintelligence/_vendor/__init__.py

@@ -0,0 +1 @@
+"""Bundled third-party inference kernels."""