twiga 0.1.0__py3-none-any.whl

twiga/__init__.py

@@ -0,0 +1,102 @@
+"""Twiga - point and probabilistic time series forecasting.
+
+Public API
+----------
+The symbols exported here are the **stable public API**.  Everything else
+(submodules, internal helpers, model classes) may change without notice.
+
+Stable
+~~~~~~
+- :class:`TwigaForecaster`          - main entry point
+- :class:`DataPipelineConfig`       - data pipeline configuration
+- :class:`ForecasterConfig`         - training configuration
+- :class:`BaseModelConfig`          - base model configuration
+- :class:`ConformalConfig`          - conformal prediction configuration
+- :func:`get_model`                 - registry lookup by name
+- :func:`evaluate_forecast`         - evaluation helper
+
+Experimental (may change in minor versions)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- :class:`BaseMLPConfig`, :class:`NeuralModelConfig`, :class:`BaseSearchSpace`
+- :class:`ForecastResult`, :class:`ForecastCollection`, :class:`ForecastKind`
+
+Optional submodule imports
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Tree-boosting models require ``pip install 'twiga[gbtree]'``::
+
+    from twiga.models.ml import LIGHTGBMConfig, LIGHTGBMModel
+
+Neural network models require ``pip install 'twiga[nn]'``::
+
+    from twiga.models.nn import MLPFConfig, MLPFModel
+
+SHAP explainability requires ``pip install 'twiga[explain]'``::
+
+    from twiga.core.explain import ShapExplainer
+
+Plotting requires ``pip install 'twiga[plots]'``::
+
+    from twiga.core.plot import plot_forecast
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from twiga.core.config import (
+    BaseMLPConfig,
+    BaseModelConfig,
+    BaseSearchSpace,
+    ConformalConfig,
+    DataPipelineConfig,
+    ForecasterConfig,
+    NeuralModelConfig,
+)
+from twiga.core.exceptions import (
+    ConfigurationError,
+    MissingExtraError,
+    NotFittedError,
+    PipelineError,
+    TwigaError,
+    require_extra,
+)
+from twiga.core.metrics import evaluate_forecast
+from twiga.core.utils import configure, get_logger
+from twiga.forecaster.core import TwigaForecaster
+from twiga.forecaster.registry import get_model
+from twiga.forecaster.result import ForecastCollection, ForecastKind, ForecastResult
+
+__all__ = [
+    # ── Stable public API ──────────────────────────────────────────────────
+    # Main entry point
+    "TwigaForecaster",
+    # Configuration
+    "DataPipelineConfig",
+    "ForecasterConfig",
+    "BaseModelConfig",
+    "ConformalConfig",
+    # Registry
+    "get_model",
+    # Evaluation
+    "evaluate_forecast",
+    # Exceptions
+    "TwigaError",
+    "ConfigurationError",
+    "MissingExtraError",
+    "NotFittedError",
+    "PipelineError",
+    "require_extra",
+    # Logging
+    "configure",
+    "get_logger",
+    # ── Experimental ──────────────────────────────────────────────────────
+    "BaseMLPConfig",
+    "BaseSearchSpace",
+    "NeuralModelConfig",
+    "ForecastCollection",
+    "ForecastKind",
+    "ForecastResult",
+]
+
+try:
+    __version__ = version("twiga")
+except PackageNotFoundError:
+    __version__ = "0.0.1"

twiga/core/__init__.py

@@ -0,0 +1,58 @@
+"""Core infrastructure: config, data pipeline, metrics, logging."""
+
+from twiga.core.config import (
+    BaseMLPConfig,
+    BaseModelConfig,
+    BaseSearchSpace,
+    ConformalConfig,
+    DataPipelineConfig,
+    ForecasterConfig,
+    NeuralModelConfig,
+)
+from twiga.core.exceptions import (
+    ConfigurationError,
+    MissingExtraError,
+    NotFittedError,
+    PipelineError,
+    TwigaError,
+    require_extra,
+)
+from twiga.core.metrics import (
+    evaluate_forecast,
+    evaluate_interval_forecast,
+    evaluate_parametric_forecast,
+    evaluate_point_forecast,
+    evaluate_quantile_forecast,
+    evaluate_samples_forecast,
+)
+from twiga.core.utils import LogContext, configure, get_logger, log_section
+
+__all__ = [
+    # Exceptions
+    "TwigaError",
+    "ConfigurationError",
+    "MissingExtraError",
+    "NotFittedError",
+    "PipelineError",
+    "require_extra",
+    # Config
+    "BaseMLPConfig",
+    "BaseModelConfig",
+    "BaseSearchSpace",
+    "ConformalConfig",
+    "DataPipelineConfig",
+    "ForecasterConfig",
+    "NeuralModelConfig",
+    # Metrics
+    "evaluate_forecast",
+    "evaluate_interval_forecast",
+    "evaluate_parametric_forecast",
+    "evaluate_point_forecast",
+    "evaluate_quantile_forecast",
+    "evaluate_samples_forecast",
+    # Logging
+    "LogContext",
+    "configure",
+    "get_logger",
+    "log_section",
+]

twiga/core/backtester.py

@@ -0,0 +1,499 @@
+from abc import ABC, abstractmethod
+
+from dateutil.relativedelta import relativedelta  # type: ignore[import-untyped]
+import numpy as np
+import pandas as pd
+
+from twiga.core.utils.logger import get_logger
+
+log = get_logger(__name__)
+
+
+class SplitState:
+    """Holds time periods for training and forecasting splits.
+
+    Attributes:
+        train_start (pd.Timestamp): Start timestamp of training period.
+        train_end (pd.Timestamp): End timestamp of training period.
+        forecast_start (pd.Timestamp): Start timestamp of forecast period.
+        forecast_end (pd.Timestamp): End timestamp of forecast period.
+    """
+
+    def __init__(self, train_start, train_end, forecast_start, forecast_end):
+        self.train_start = train_start
+        self.train_end = train_end
+        self.forecast_start = forecast_start
+        self.forecast_end = forecast_end
+
+
+class TimeBasedSplit(ABC):
+    """Abstract base class implementing core time-based splitting logic.
+
+    This class validates split parameters and provides properties to compute
+    time deltas for the training period, forecast period, gap, and stride.
+
+    Attributes:
+        split_freq (str): Time unit for splits (e.g., 'days', 'months').
+        train_size (int): Training period length in `split_freq` units.
+        test_size (int): Forecast period length in `split_freq` units.
+        gap (int): Gap between train and forecast periods.
+        stride (int): Step size between splits.
+        window (str): Window type ('rolling' or 'expanding').
+    """
+
+    def __init__(
+        self,
+        split_freq: str,
+        train_size: int,
+        test_size: int,
+        gap: int = 0,
+        stride: int | None = None,
+        window: str = "rolling",
+    ) -> None:
+        """Initialize time-based split parameters.
+
+        Args:
+            split_freq (str): Time unit for splits (e.g., 'days', 'months').
+            train_size (int): Training period length in split_freq units.
+            test_size (int): Forecast period length in split_freq units.
+            gap (int): Gap between training and forecast periods (default: 0).
+            stride (int, optional): Step size between splits (default: test_size).
+            window (str): Window type ('rolling' or 'expanding') (default: 'rolling').
+
+        Raises:
+            ValueError: If any parameter is invalid. In particular, train_size must be a
+                        positive integer that is greater than or equal to test_size.
+        """
+        self.split_freq = split_freq
+        self.train_size = train_size
+        self.test_size = test_size
+        self.gap = gap
+        self.stride = stride if stride is not None else test_size
+        self.window = window
+        self._validate_arguments()
+
+    def _validate_arguments(self) -> None:
+        """Validate input parameters meet requirements."""
+        valid_frequencies = ["days", "minutes", "hours", "weeks", "months", "years"]
+        if self.split_freq not in valid_frequencies:
+            raise ValueError(f"split_freq must be one of {valid_frequencies}. Got '{self.split_freq}'.")
+        if self.window not in ["rolling", "expanding"]:
+            raise ValueError("window must be either 'rolling' or 'expanding'.")
+        if not isinstance(self.gap, int) or self.gap < 0:
+            raise ValueError("gap must be a non-negative integer.")
+        if not isinstance(self.train_size, int) or self.train_size <= 0:
+            raise ValueError("train_size must be a positive integer.")
+        if not isinstance(self.test_size, int) or self.test_size <= 0:
+            raise ValueError("test_size must be a positive integer.")
+        if self.train_size < self.test_size:
+            raise ValueError(
+                f"train_size must be greater than or equal to test_size. "
+                f"Got train_size = {self.train_size} and test_size = {self.test_size}.",
+            )
+        if not isinstance(self.stride, int) or self.stride <= 0:
+            raise ValueError("stride must be a positive integer.")
+
+    @property
+    def train_delta(self) -> relativedelta:
+        """Calculate training period duration."""
+        return relativedelta(**{self.split_freq: self.train_size})
+
+    @property
+    def forecast_delta(self) -> relativedelta:
+        """Calculate forecast period duration."""
+        return relativedelta(**{self.split_freq: self.test_size})
+
+    @property
+    def gap_delta(self) -> relativedelta:
+        """Calculate gap duration."""
+        return relativedelta(**{self.split_freq: self.gap})
+
+    @property
+    def stride_delta(self) -> relativedelta:
+        """Calculate stride duration."""
+        return relativedelta(**{self.split_freq: self.stride})
+
+    def _splits_from_period(self, time_start, time_end):
+        """Generate splits between start and end times.
+
+        Args:
+            time_start (pd.Timestamp): Start timestamp.
+            time_end (pd.Timestamp): End timestamp.
+
+        Yields:
+            SplitState: A split state containing train and forecast period boundaries.
+
+        Raises:
+            ValueError: If time_start is not before time_end.
+        """
+        if time_start >= time_end:
+            raise ValueError("time_start must be before time_end.")
+
+        is_rolling = self.window == "rolling"
+        train_start = time_start
+        train_end = train_start + self.train_delta
+        forecast_start = train_end + self.gap_delta
+        forecast_end = forecast_start + self.forecast_delta
+
+        while forecast_end <= time_end:
+            yield SplitState(train_start, train_end, forecast_start, forecast_end)
+            if is_rolling:
+                train_start += self.stride_delta
+            train_end += self.stride_delta
+            forecast_start += self.stride_delta
+            forecast_end += self.stride_delta
+
+    @abstractmethod
+    def split(self, data: pd.DataFrame):
+        """Generate train/test splits from data."""
+
+
+class TimeBasedCV(TimeBasedSplit):
+    """Concrete time-based cross-validation implementation for pandas DataFrames.
+
+    This class creates splits based on a datetime column and returns train/test indices,
+    along with the corresponding time periods.
+
+    Attributes:
+        date_column (str): Name of the timestamp column in the DataFrame.
+        num_splits (int): Optional number of splits to generate.
+    """
+
+    def __init__(
+        self,
+        split_freq,
+        test_size,
+        train_size=None,
+        gap=0,
+        stride=None,
+        window="rolling",
+        date_column="timestamp",
+        num_splits=None,
+    ):
+        if (train_size is None) and (num_splits is None):
+            raise ValueError("Either train_size or num_splits must be provided, not both None.")
+        self.split_freq = split_freq
+        self.test_size = test_size
+        self.train_size = train_size if train_size is not None else 0  # Set temporarily
+        self.gap = gap
+        self.stride = stride if stride is not None else test_size
+        self.window = window
+        self.date_column = date_column
+        self.num_splits = num_splits
+        self._split_scheme = {}
+        self.time_values = None
+        if train_size is not None:
+            super().__init__(
+                split_freq=split_freq,
+                train_size=train_size,
+                test_size=test_size,
+                gap=gap,
+                stride=self.stride,
+                window=window,
+            )
+
+    def duration_in_units(self, start: pd.Timestamp, end: pd.Timestamp, split_freq: str) -> int:
+        """Compute the duration between start and end in the specified split_freq units.
+
+        For 'days', 'minutes', 'hours', and 'weeks', a simple conversion based on timedelta is used.
+        For 'months' and 'years', relativedelta is used to account for variable lengths.
+
+        Args:
+            start (pd.Timestamp): Start timestamp.
+            end (pd.Timestamp): End timestamp.
+            split_freq (str): One of 'days', 'minutes', 'hours', 'weeks', 'months', or 'years'.
+
+        Returns:
+            int: Duration in the specified units.
+
+        Raises:
+            ValueError: If split_freq is unsupported.
+        """
+        diff = end - start
+        conversion = {
+            "days": diff.days,
+            "minutes": int(diff.total_seconds() / 60),
+            "hours": int(diff.total_seconds() / 3600),
+            "weeks": diff.days // 7,
+        }
+        if split_freq in conversion:
+            return conversion[split_freq]
+        if split_freq == "months":
+            rd = relativedelta(end, start)
+            return rd.years * 12 + rd.months
+        if split_freq == "years":
+            return relativedelta(end, start).years
+        raise ValueError(f"Unsupported split_freq: {split_freq}")
+
+    def _validate_train_size(self) -> None:
+        """Ensure that the computed train_size is valid and at least as long as test_size."""
+        if not isinstance(self.train_size, int) or self.train_size <= 0:
+            raise ValueError(f"Calculated train_size must be a positive integer. Got {self.train_size}.")
+        if self.train_size < self.test_size:
+            raise ValueError(
+                f"Calculated train_size must be greater than or equal to test_size. "
+                f"Got train_size = {self.train_size}, test_size = {self.test_size}.",
+            )
+
+    def set_split_scheme(
+        self,
+        time_values: pd.Series,
+        start_dt: pd.Timestamp | None = None,
+        end_dt: pd.Timestamp | None = None,
+    ) -> None:
+        """Calculate split indices from time series data.
+
+        The method sorts the datetime series, determines the time range to use,
+        and computes indices for training and forecast periods based on the provided
+        parameters. If num_splits is set, it adjusts train_size accordingly.
+
+        Args:
+            time_values (pd.Series): Datetime series to split.
+            start_dt (pd.Timestamp, optional): Override start time (default: min of series).
+            end_dt (pd.Timestamp, optional): Override end time (default: max of series).
+
+        Raises:
+            ValueError: If time_values is not a datetime series.
+        """
+        if not pd.api.types.is_datetime64_any_dtype(time_values):
+            raise ValueError("time_values must be a datetime series.")
+
+        # Sort data by time
+        indices = np.arange(len(time_values))
+        sorted_order = np.argsort(time_values)
+        self.time_values = time_values.iloc[sorted_order]
+        indices = indices[sorted_order]
+
+        # Determine time range
+        time_start = start_dt or self.time_values.min()
+        time_end = end_dt or self.time_values.max()
+
+        # Adjust parameters if num_splits is specified.
+        if self.num_splits is not None:
+            total_duration = self.duration_in_units(time_start, time_end, self.split_freq)
+            max_possible_splits = (total_duration - 2 * self.test_size - self.gap) / self.stride
+            if self.num_splits >= max_possible_splits:
+                log.warning(
+                    "Not enough time for %d splits. Reducing num_splits to maximum possible: %d.",
+                    self.num_splits,
+                    max_possible_splits,
+                )
+                self.num_splits = int(max_possible_splits)
+            self.train_size = total_duration - self.test_size - self.gap - (self.num_splits - 1) * self.stride
+            self._validate_train_size()
+
+        self._split_scheme = {}
+        for i, split in enumerate(self._splits_from_period(time_start, time_end)):
+            train_mask = (self.time_values >= split.train_start) & (self.time_values < split.train_end)
+            test_mask = (self.time_values >= split.forecast_start) & (self.time_values < split.forecast_end)
+
+            if train_mask.any() and test_mask.any():
+                self._split_scheme[i] = {
+                    "train_idx": indices[train_mask],
+                    "test_idx": indices[test_mask],
+                    "train_period": (split.train_start, split.train_end),
+                    "test_period": (split.forecast_start, split.forecast_end),
+                }
+
+        if self.num_splits is not None and len(self._split_scheme) != self.num_splits:
+            log.warning(
+                "Requested %d splits but generated %d. Time range: %s to %s",
+                self.num_splits,
+                len(self._split_scheme),
+                time_start,
+                time_end,
+            )
+        self.num_splits = len(self._split_scheme)
+
+    def get_scheme(self) -> dict:
+        """Return the current split configuration.
+
+        Returns:
+            dict: A dictionary containing the train/test split indices and periods.
+
+        Raises:
+            ValueError: If the split scheme has not been initialized.
+        """
+        if not self._split_scheme:
+            raise ValueError("Split scheme not initialized. Call set_split_scheme() first.")
+        return self._split_scheme.copy()
+
+    def split(self, data: pd.DataFrame, start_dt: pd.Timestamp | None = None, end_dt: pd.Timestamp | None = None):
+        """Generate validated train/test splits.
+
+        Args:
+            data (pd.DataFrame): DataFrame containing the date column.
+            start_dt (pd.Timestamp, optional): Override split start time.
+            end_dt (pd.Timestamp, optional): Override split end time.
+
+        Yields:
+            tuple: (train_df, test_df, scheme, split_key).
+
+        Raises:
+            ValueError: If the required date column is missing or if the computed indices exceed data bounds.
+        """
+        if self.date_column not in data.columns:
+            raise ValueError(f"Missing time column: '{self.date_column}' in the data.")
+
+        if not self._split_scheme:
+            self.set_split_scheme(data[self.date_column], start_dt, end_dt)
+
+        max_index = max(np.max(np.concatenate([s["train_idx"], s["test_idx"]])) for s in self._split_scheme.values())
+        if max_index >= len(data):
+            raise ValueError(
+                f"Data has {len(data)} rows but splits require index {max_index}. Check your time series range.",
+            )
+
+        for split_key, scheme in self._split_scheme.items():
+            train_df = data.iloc[scheme["train_idx"]].reset_index(drop=True)
+            test_df = data.iloc[scheme["test_idx"]].reset_index(drop=True)
+            yield train_df, test_df, scheme, split_key
+
+    def plot_split_scheme(
+        self,
+        data: pd.DataFrame | None = None,
+        train_ratio: float = 1.0,
+        start_dt: pd.Timestamp | None = None,
+        end_dt: pd.Timestamp | None = None,
+        title: str = "Cross-validation split scheme",
+        colors: dict[str, str] | None = None,
+        alpha: float = 0.88,
+        x_ticks: int = 6,
+        font_size: int = 10,
+        line_width: float = 0.8,
+        x_axis_angle: int = 30,
+        legend_pos: str = "top",
+    ):
+        """Visualize the time series cross-validation split scheme.
+
+        Renders a Gantt-style plot with one horizontal bar per fold, colour-coded
+        by segment (Train / Val / Test), styled with the Twiga theme.
+
+        Args:
+            data: Input DataFrame containing temporal data. Used to derive the
+                split scheme when it has not been pre-computed.
+            train_ratio: Proportion of training indices used for training; the
+                remainder becomes a validation segment.
+            start_dt: Optional start timestamp passed to ``set_split_scheme``.
+            end_dt: Optional end timestamp passed to ``set_split_scheme``.
+            title: Plot title.
+            colors: Custom colour mapping for segments.  Keys must be title-case:
+                ``"Train"``, ``"Val"``, ``"Test"``.
+            alpha: Bar transparency (0–1).
+            x_ticks: Number of date ticks on the x-axis.
+            font_size: Base font size in points.
+            line_width: Axis line stroke width.
+            x_axis_angle: Rotation angle for x-axis tick labels.
+            legend_pos: Legend position - ``"top"``, ``"bottom"``, ``"left"``,
+                ``"right"``, or ``"none"``.
+
+        Returns:
+            A Lets-Plot ``ggplot`` object.
+
+        Raises:
+            ValueError: If ``train_ratio`` is outside [0, 1] or the split scheme
+                is not initialised and no ``data`` is provided.
+
+        Example:
+            >>> splitter = TimeBasedCV(split_freq="days", test_size=5, train_size=20, date_column="date")
+            >>> splitter.set_split_scheme(data["date"])
+            >>> splitter.plot_split_scheme(data, train_ratio=0.8, title="CV Scheme")
+        """
+        from lets_plot import (
+            aes,
+            geom_rect,
+            ggplot,
+            labs,
+            scale_fill_manual,
+            scale_x_continuous,
+            scale_y_continuous,
+        )
+
+        from twiga.core.plot import TWIGA_PALETTE, twiga_theme
+
+        if not 0 <= train_ratio <= 1:
+            raise ValueError("train_ratio must be between 0 and 1.")
+
+        if not hasattr(self, "_split_scheme") or not self._split_scheme:
+            if data is not None:
+                self.set_split_scheme(data[self.date_column], start_dt, end_dt)
+            else:
+                raise ValueError("Split scheme not initialized and no data provided.")
+
+        default_colors = {
+            "Train": TWIGA_PALETTE[0],  # teal
+            "Val": TWIGA_PALETTE[5],  # emerald
+            "Test": TWIGA_PALETTE[1],  # amber
+        }
+        # Accept legacy lowercase keys for backward compatibility
+        color_mapping = {k.title(): v for k, v in colors.items()} if colors else default_colors
+
+        _bar_h = 0.55
+        segments = []
+        for fold_idx, scheme in self._split_scheme.items():
+            fold = fold_idx + 1
+            train_indices = scheme["train_idx"]
+            train_size = int(train_ratio * len(train_indices))
+            val_size = len(train_indices) - train_size
+
+            segments.append(
+                {
+                    "fold": fold,
+                    "segment": "Train",
+                    "start": train_indices[0],
+                    "end": train_indices[0] + train_size,
+                    "ymin": fold - _bar_h / 2,
+                    "ymax": fold + _bar_h / 2,
+                },
+            )
+            if val_size > 0:
+                segments.append(
+                    {
+                        "fold": fold,
+                        "segment": "Val",
+                        "start": train_indices[0] + train_size,
+                        "end": train_indices[0] + train_size + val_size,
+                        "ymin": fold - _bar_h / 2,
+                        "ymax": fold + _bar_h / 2,
+                    },
+                )
+            segments.append(
+                {
+                    "fold": fold,
+                    "segment": "Test",
+                    "start": scheme["test_idx"][0],
+                    "end": scheme["test_idx"][-1],
+                    "ymin": fold - _bar_h / 2,
+                    "ymax": fold + _bar_h / 2,
+                },
+            )
+
+        df = pd.DataFrame(segments)
+
+        time_values = pd.Series(self.time_values)
+        x_breaks = np.linspace(0, len(time_values) - 1, x_ticks, dtype=int).tolist()
+        x_labels = time_values.iloc[x_breaks].dt.strftime("%Y-%m-%d").tolist()
+
+        n_folds = self.num_splits
+        fold_breaks = list(range(1, n_folds + 1))
+        fold_labels = [f"Fold {i}" for i in fold_breaks]
+
+        return (
+            ggplot(df)
+            + geom_rect(
+                aes(xmin="start", xmax="end", ymin="ymin", ymax="ymax", fill="segment"),
+                size=0,
+                alpha=alpha,
+            )
+            + scale_fill_manual(values=color_mapping)
+            + scale_x_continuous(breaks=x_breaks, labels=x_labels)
+            + scale_y_continuous(breaks=fold_breaks, labels=fold_labels)
+            + labs(title=title, x="Date", y="", fill="")
+            + twiga_theme(
+                font_size=font_size,
+                line_width=line_width,
+                x_axis_angle=x_axis_angle,
+                legend_pos=legend_pos,  # type: ignore[arg-type]
+                grid=False,
+            )
+        )

twiga/core/config/__init__.py

@@ -0,0 +1,27 @@
+"""Domain-specific configuration classes.
+
+These configs describe the problem domain (data structure, CV strategy,
+uncertainty quantification) rather than a specific model architecture.
+"""
+
+from pydantic import Field
+
+from .base import BaseModelConfig
+from .characterisation import CharacterisationConfig
+from .conformal import ConformalConfig
+from .data import DataPipelineConfig
+from .forecaster import ForecasterConfig
+from .neural import BaseMLPConfig, NeuralModelConfig
+from .search_space import BaseSearchSpace
+
+__all__ = [
+    "BaseMLPConfig",
+    "BaseModelConfig",
+    "BaseSearchSpace",
+    "CharacterisationConfig",
+    "ConformalConfig",
+    "DataPipelineConfig",
+    "Field",
+    "ForecasterConfig",
+    "NeuralModelConfig",
+]