tabpfn-time-series 0.1.0__py3-none-any.whl

tabpfn_time_series/__init__.py

@@ -0,0 +1,11 @@
+from .feature import DefaultFeatures, FeatureTransformer
+from .predictor import TabPFNTimeSeriesPredictor, TabPFNMode
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DefaultFeatures",
+    "FeatureTransformer", 
+    "TabPFNTimeSeriesPredictor",
+    "TabPFNMode",
+]

tabpfn_time_series/data_preparation.py

@@ -0,0 +1,226 @@
+import pandas as pd
+import numpy as np
+
+import datasets
+from autogluon.timeseries import TimeSeriesDataFrame
+
+
+def generate_test_X(
+    train_tsdf: TimeSeriesDataFrame,
+    prediction_length: int,
+):
+    test_dfs = []
+    for item_id in train_tsdf.item_ids:
+        last_train_timestamp = train_tsdf.xs(item_id, level="item_id").index.max()
+        first_test_timestamp = pd.date_range(
+            start=last_train_timestamp, periods=2, freq=train_tsdf.freq
+        )[-1]
+        test_dfs.append(
+            pd.DataFrame(
+                {
+                    "target": np.full(prediction_length, np.nan),
+                    "timestamp": pd.date_range(
+                        start=first_test_timestamp,
+                        periods=prediction_length,
+                        freq=train_tsdf.freq,
+                    ),
+                    "item_id": item_id,
+                }
+            )
+        )
+
+    test_tsdf = TimeSeriesDataFrame.from_data_frame(pd.concat(test_dfs))
+    assert test_tsdf.item_ids.equals(train_tsdf.item_ids)
+
+    return test_tsdf
+
+
+# From pandas._libs.tslibs.dtypes.OFFSET_TO_PERIOD_FREQSTR
+offset_alias_to_period_alias = {
+    "WEEKDAY": "D",
+    "EOM": "M",
+    "BME": "M",
+    "SME": "M",
+    "BQS": "Q",
+    "QS": "Q",
+    "BQE": "Q",
+    "BQE-DEC": "Q",
+    "BQE-JAN": "Q",
+    "BQE-FEB": "Q",
+    "BQE-MAR": "Q",
+    "BQE-APR": "Q",
+    "BQE-MAY": "Q",
+    "BQE-JUN": "Q",
+    "BQE-JUL": "Q",
+    "BQE-AUG": "Q",
+    "BQE-SEP": "Q",
+    "BQE-OCT": "Q",
+    "BQE-NOV": "Q",
+    "MS": "M",
+    "D": "D",
+    "B": "B",
+    "min": "min",
+    "s": "s",
+    "ms": "ms",
+    "us": "us",
+    "ns": "ns",
+    "h": "h",
+    "QE": "Q",
+    "QE-DEC": "Q-DEC",
+    "QE-JAN": "Q-JAN",
+    "QE-FEB": "Q-FEB",
+    "QE-MAR": "Q-MAR",
+    "QE-APR": "Q-APR",
+    "QE-MAY": "Q-MAY",
+    "QE-JUN": "Q-JUN",
+    "QE-JUL": "Q-JUL",
+    "QE-AUG": "Q-AUG",
+    "QE-SEP": "Q-SEP",
+    "QE-OCT": "Q-OCT",
+    "QE-NOV": "Q-NOV",
+    "YE": "Y",
+    "YE-DEC": "Y-DEC",
+    "YE-JAN": "Y-JAN",
+    "YE-FEB": "Y-FEB",
+    "YE-MAR": "Y-MAR",
+    "YE-APR": "Y-APR",
+    "YE-MAY": "Y-MAY",
+    "YE-JUN": "Y-JUN",
+    "YE-JUL": "Y-JUL",
+    "YE-AUG": "Y-AUG",
+    "YE-SEP": "Y-SEP",
+    "YE-OCT": "Y-OCT",
+    "YE-NOV": "Y-NOV",
+    "W": "W",
+    "ME": "M",
+    "Y": "Y",
+    "BYE": "Y",
+    "BYE-DEC": "Y",
+    "BYE-JAN": "Y",
+    "BYE-FEB": "Y",
+    "BYE-MAR": "Y",
+    "BYE-APR": "Y",
+    "BYE-MAY": "Y",
+    "BYE-JUN": "Y",
+    "BYE-JUL": "Y",
+    "BYE-AUG": "Y",
+    "BYE-SEP": "Y",
+    "BYE-OCT": "Y",
+    "BYE-NOV": "Y",
+    "YS": "Y",
+    "BYS": "Y",
+    "QS-JAN": "Q",
+    "QS-FEB": "Q",
+    "QS-MAR": "Q",
+    "QS-APR": "Q",
+    "QS-MAY": "Q",
+    "QS-JUN": "Q",
+    "QS-JUL": "Q",
+    "QS-AUG": "Q",
+    "QS-SEP": "Q",
+    "QS-OCT": "Q",
+    "QS-NOV": "Q",
+    "QS-DEC": "Q",
+    "BQS-JAN": "Q",
+    "BQS-FEB": "Q",
+    "BQS-MAR": "Q",
+    "BQS-APR": "Q",
+    "BQS-MAY": "Q",
+    "BQS-JUN": "Q",
+    "BQS-JUL": "Q",
+    "BQS-AUG": "Q",
+    "BQS-SEP": "Q",
+    "BQS-OCT": "Q",
+    "BQS-NOV": "Q",
+    "BQS-DEC": "Q",
+    "YS-JAN": "Y",
+    "YS-FEB": "Y",
+    "YS-MAR": "Y",
+    "YS-APR": "Y",
+    "YS-MAY": "Y",
+    "YS-JUN": "Y",
+    "YS-JUL": "Y",
+    "YS-AUG": "Y",
+    "YS-SEP": "Y",
+    "YS-OCT": "Y",
+    "YS-NOV": "Y",
+    "YS-DEC": "Y",
+    "BYS-JAN": "Y",
+    "BYS-FEB": "Y",
+    "BYS-MAR": "Y",
+    "BYS-APR": "Y",
+    "BYS-MAY": "Y",
+    "BYS-JUN": "Y",
+    "BYS-JUL": "Y",
+    "BYS-AUG": "Y",
+    "BYS-SEP": "Y",
+    "BYS-OCT": "Y",
+    "BYS-NOV": "Y",
+    "BYS-DEC": "Y",
+    "Y-JAN": "Y-JAN",
+    "Y-FEB": "Y-FEB",
+    "Y-MAR": "Y-MAR",
+    "Y-APR": "Y-APR",
+    "Y-MAY": "Y-MAY",
+    "Y-JUN": "Y-JUN",
+    "Y-JUL": "Y-JUL",
+    "Y-AUG": "Y-AUG",
+    "Y-SEP": "Y-SEP",
+    "Y-OCT": "Y-OCT",
+    "Y-NOV": "Y-NOV",
+    "Y-DEC": "Y-DEC",
+    "Q-JAN": "Q-JAN",
+    "Q-FEB": "Q-FEB",
+    "Q-MAR": "Q-MAR",
+    "Q-APR": "Q-APR",
+    "Q-MAY": "Q-MAY",
+    "Q-JUN": "Q-JUN",
+    "Q-JUL": "Q-JUL",
+    "Q-AUG": "Q-AUG",
+    "Q-SEP": "Q-SEP",
+    "Q-OCT": "Q-OCT",
+    "Q-NOV": "Q-NOV",
+    "Q-DEC": "Q-DEC",
+    "W-MON": "W-MON",
+    "W-TUE": "W-TUE",
+    "W-WED": "W-WED",
+    "W-THU": "W-THU",
+    "W-FRI": "W-FRI",
+    "W-SAT": "W-SAT",
+    "W-SUN": "W-SUN",
+}
+
+
+# From https://github.com/amazon-science/chronos-forecasting/blob/ad410c9c0ae0d499aeec9a7af09b0636844b6274/scripts/evaluation/evaluate.py#L28
+def to_gluonts_univariate(hf_dataset: datasets.Dataset):
+    series_fields = [
+        col
+        for col in hf_dataset.features
+        if isinstance(hf_dataset.features[col], datasets.Sequence)
+    ]
+    series_fields.remove("timestamp")
+    dataset_length = hf_dataset.info.splits["train"].num_examples * len(series_fields)
+    dataset_freq = pd.infer_freq(hf_dataset[0]["timestamp"])
+    dataset_freq = offset_alias_to_period_alias.get(dataset_freq, dataset_freq)
+
+    gts_dataset = []
+    for hf_entry in hf_dataset:
+        for field in series_fields:
+            gts_dataset.append(
+                {
+                    "start": pd.Period(
+                        hf_entry["timestamp"][0],
+                        freq=dataset_freq,
+                    ),
+                    "target": hf_entry[field],
+                }
+            )
+    assert len(gts_dataset) == dataset_length
+
+    return gts_dataset
+
+
+def split_time_series_to_X_y(df: pd.DataFrame, target_col="target"):
+    X = pd.DataFrame(df.drop(columns=[target_col]))
+    y = pd.DataFrame(df[target_col])
+    return X, y

tabpfn_time_series/defaults.py

@@ -0,0 +1,5 @@
+TABPFN_DEFAULT_QUANTILE_CONFIG = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
+TABPFN_DEFAULT_CONFIG = {
+    "model": "2noar4o2",
+    "optimize_metric": "median",
+}

tabpfn_time_series/feature.py

@@ -0,0 +1,78 @@
+import numpy as np
+import pandas as pd
+from typing import Tuple, List, Callable
+
+import gluonts.time_feature
+from autogluon.timeseries import TimeSeriesDataFrame
+
+
+class DefaultFeatures:
+    @staticmethod
+    def add_running_index(df: pd.DataFrame) -> pd.Series:
+        df["running_index"] = range(len(df))
+        return df
+
+    @staticmethod
+    def add_calendar_features(df: pd.DataFrame) -> pd.DataFrame:
+        CALENDAR_COMPONENT = [
+            "year",
+            # "month",
+            # "day",
+        ]
+
+        CALENDAR_FEATURES = [
+            # (feature, natural seasonality)
+            ("hour_of_day", 24),
+            ("day_of_week", 7),
+            ("day_of_month", 30.5),
+            ("day_of_year", 365),
+            ("week_of_year", 52),
+            ("month_of_year", 12),
+        ]
+
+        timestamps = df.index.get_level_values("timestamp")
+
+        for component_name in CALENDAR_COMPONENT:
+            df[component_name] = getattr(timestamps, component_name)
+
+        for feature_name, seasonality in CALENDAR_FEATURES:
+            feature_func = getattr(gluonts.time_feature, f"{feature_name}_index")
+            feature = feature_func(timestamps).astype(np.int32)
+            if seasonality is not None:
+                df[f"{feature_name}_sin"] = np.sin(
+                    2 * np.pi * feature / (seasonality - 1)
+                )  # seasonality - 1 because the value starts from 0
+                df[f"{feature_name}_cos"] = np.cos(
+                    2 * np.pi * feature / (seasonality - 1)
+                )
+            else:
+                df[feature_name] = feature
+
+        return df
+
+
+class FeatureTransformer:
+    @staticmethod
+    def add_features(
+        train_tsdf: TimeSeriesDataFrame,
+        test_tsdf: TimeSeriesDataFrame,
+        feature_generators: List[Callable[[TimeSeriesDataFrame], TimeSeriesDataFrame]],
+        target_column: str = "target",
+    ) -> Tuple[TimeSeriesDataFrame, TimeSeriesDataFrame]:
+        assert target_column in train_tsdf.columns
+        assert test_tsdf[target_column].isna().all()
+
+        # Join train and test tsdf
+        tsdf = pd.concat([train_tsdf, test_tsdf])
+
+        # Apply feature generators
+        for func in feature_generators:
+            tsdf = tsdf.groupby(level="item_id", group_keys=False).apply(func)
+
+        # Split train and test tsdf
+        train_tsdf = tsdf.iloc[: len(train_tsdf)]
+        test_tsdf = tsdf.iloc[len(train_tsdf) :]
+
+        assert test_tsdf[target_column].isna().all()
+
+        return train_tsdf, test_tsdf

tabpfn_time_series/plot.py

@@ -0,0 +1,189 @@
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+
+from autogluon.timeseries import TimeSeriesDataFrame
+
+
+def is_subset(tsdf_A: TimeSeriesDataFrame, tsdf_B: TimeSeriesDataFrame) -> bool:
+    tsdf_index_set_A, tsdf_index_set_B = set(tsdf_A.index), set(tsdf_B.index)
+    return tsdf_index_set_A.issubset(tsdf_index_set_B)
+
+
+def plot_time_series(
+    df: TimeSeriesDataFrame,
+    item_ids: list[int] | None = None,
+    in_single_plot: bool = False,
+    y_limit: tuple[float, float] | None = None,
+    show_points: bool = False,
+    target_col: str = "target",
+):
+    if item_ids is None:
+        item_ids = df.index.get_level_values("item_id").unique()
+    elif not set(item_ids).issubset(df.index.get_level_values("item_id").unique()):
+        raise ValueError(f"Item IDs {item_ids} not found in the dataframe")
+
+    if not in_single_plot:
+        # create subplots
+        fig, axes = plt.subplots(
+            len(item_ids), 1, figsize=(10, 3 * len(item_ids)), sharex=True
+        )
+
+        if len(item_ids) == 1:
+            axes = [axes]
+
+        for ax, item_id in zip(axes, item_ids):
+            df_item = df.xs(item_id, level="item_id")
+            ax.plot(df_item.index, df_item[target_col])
+            if show_points:
+                ax.scatter(
+                    df_item.index,
+                    df_item[target_col],
+                    color="lightcoral",
+                    s=8,
+                    alpha=0.8,
+                )
+            ax.set_title(f"Item ID: {item_id}")
+            ax.set_xlabel("Timestamp")
+            ax.set_ylabel("Target")
+            if y_limit is not None:
+                ax.set_ylim(*y_limit)
+
+    else:
+        fig, ax = plt.subplots(1, 1, figsize=(10, 3))
+        for item_id in item_ids:
+            df_item = df.xs(item_id, level="item_id")
+            ax.plot(df_item.index, df_item[target_col], label=f"Item ID: {item_id}")
+            if show_points:
+                ax.scatter(
+                    df_item.index,
+                    df_item[target_col],
+                    color="lightcoral",
+                    s=8,
+                    alpha=0.8,
+                )
+        ax.legend()
+        if y_limit is not None:
+            ax.set_ylim(*y_limit)
+
+    plt.tight_layout()
+    plt.show()
+
+
+def plot_actual_ts(
+    train: TimeSeriesDataFrame,
+    test: TimeSeriesDataFrame,
+    item_ids: list[int] | None = None,
+    show_points: bool = False,
+):
+    if item_ids is None:
+        item_ids = train.index.get_level_values("item_id").unique()
+    elif not set(item_ids).issubset(train.index.get_level_values("item_id").unique()):
+        raise ValueError(f"Item IDs {item_ids} not found in the dataframe")
+
+    _, ax = plt.subplots(len(item_ids), 1, figsize=(10, 3 * len(item_ids)))
+    ax = [ax] if not isinstance(ax, np.ndarray) else ax
+
+    def plot_single_item(ax, item_id):
+        train_item = train.xs(item_id, level="item_id")
+        test_item = test.xs(item_id, level="item_id")
+
+        if is_subset(train_item, test_item):
+            ground_truth = test_item["target"]
+        else:
+            ground_truth = pd.concat([train_item[["target"]], test_item[["target"]]])
+        ax.plot(ground_truth.index, ground_truth, label="Ground Truth")
+        if show_points:
+            ax.scatter(
+                ground_truth.index, ground_truth, color="lightblue", s=8, alpha=0.8
+            )
+
+        train_item_length = train.xs(item_id, level="item_id").iloc[-1].name
+        ax.axvline(
+            x=train_item_length, color="r", linestyle="--", label="Train/Test Split"
+        )
+
+        ax.set_title(f"Item ID: {item_id}")
+        ax.legend()
+
+    for i, item_id in enumerate(item_ids):
+        plot_single_item(ax[i], item_id)
+
+    plt.tight_layout()
+    plt.show()
+
+
+def plot_pred_and_actual_ts(
+    pred: TimeSeriesDataFrame,
+    train: TimeSeriesDataFrame,
+    test: TimeSeriesDataFrame,
+    item_ids: list[int] | None = None,
+    show_quantiles: bool = True,
+    show_points: bool = False,
+):
+    if item_ids is None:
+        item_ids = train.index.get_level_values("item_id").unique()
+    elif not set(item_ids).issubset(train.index.get_level_values("item_id").unique()):
+        raise ValueError(f"Item IDs {item_ids} not found in the dataframe")
+
+    if pred.shape[0] != test.shape[0]:
+        if not is_subset(pred, test):
+            raise ValueError(
+                "Pred and Test have different number of items and Pred is not a subset of Test"
+            )
+
+        filled_pred = test.copy()
+        filled_pred["target"] = np.nan
+        for col in pred.columns:
+            filled_pred.loc[pred.index, col] = pred[col]
+        pred = filled_pred
+
+    assert pred.shape[0] == test.shape[0]
+
+    _, ax = plt.subplots(len(item_ids), 1, figsize=(10, 3 * len(item_ids)))
+    ax = [ax] if not isinstance(ax, np.ndarray) else ax
+
+    def plot_single_item(ax, item_id):
+        pred_item = pred.xs(item_id, level="item_id")
+        train_item = train.xs(item_id, level="item_id")
+        test_item = test.xs(item_id, level="item_id")
+
+        if is_subset(train_item, test_item):
+            ground_truth = test_item["target"]
+        else:
+            ground_truth = pd.concat([train_item[["target"]], test_item[["target"]]])
+        ax.plot(ground_truth.index, ground_truth, label="Ground Truth")
+        ax.plot(pred_item.index, pred_item["target"], label="Prediction")
+        if show_points:
+            ax.scatter(
+                ground_truth.index, ground_truth, color="lightblue", s=8, alpha=0.8
+            )
+
+        if show_quantiles:
+            # Plot the lower and upper bound of the quantile predictions
+            quantile_config = sorted(
+                pred_item.columns.drop(["target"]).tolist(), key=lambda x: float(x)
+            )
+            lower_quantile = quantile_config[0]
+            upper_quantile = quantile_config[-1]
+            ax.fill_between(
+                pred_item.index,
+                pred_item[lower_quantile],
+                pred_item[upper_quantile],
+                color="gray",
+                alpha=0.2,
+                label=f"{lower_quantile}-{upper_quantile} Quantile Range",
+            )
+
+        train_item_length = train.xs(item_id, level="item_id").iloc[-1].name
+        ax.axvline(
+            x=train_item_length, color="r", linestyle="--", label="Train/Test Split"
+        )
+        ax.set_title(f"Item ID: {item_id}")
+        ax.legend(loc="upper left", bbox_to_anchor=(0, 1))
+
+    for i, item_id in enumerate(item_ids):
+        plot_single_item(ax[i], item_id)
+
+    plt.tight_layout()
+    plt.show()

tabpfn_time_series/predictor.py

@@ -0,0 +1,47 @@
+import logging
+from enum import Enum
+
+from autogluon.timeseries import TimeSeriesDataFrame
+
+from tabpfn_time_series.tabpfn_worker import TabPFNClient, LocalTabPFN
+from tabpfn_time_series.defaults import TABPFN_DEFAULT_QUANTILE_CONFIG, TABPFN_DEFAULT_CONFIG
+
+logger = logging.getLogger(__name__)
+
+
+class TabPFNMode(Enum):
+    LOCAL = "tabpfn-local"
+    CLIENT = "tabpfn-client"
+
+
+class TabPFNTimeSeriesPredictor:
+    """
+    Given a TimeSeriesDataFrame (multiple time series), perform prediction on each time series individually.
+    """
+
+    def __init__(
+        self,
+        tabpfn_mode: TabPFNMode = TabPFNMode.CLIENT,
+        tabpfn_config: dict = TABPFN_DEFAULT_CONFIG,
+    ) -> None:
+        worker_mapping = {
+            TabPFNMode.CLIENT: lambda: TabPFNClient(tabpfn_config),
+            TabPFNMode.LOCAL: lambda: LocalTabPFN(tabpfn_config),
+        }
+        self.tabpfn_worker = worker_mapping[tabpfn_mode]()
+
+    def predict(
+        self,
+        train_tsdf: TimeSeriesDataFrame,  # with features and target
+        test_tsdf: TimeSeriesDataFrame,  # with features only
+        quantile_config: list[float] = TABPFN_DEFAULT_QUANTILE_CONFIG,
+    ) -> TimeSeriesDataFrame:
+        """
+        Predict on each time series individually (local forecasting).
+        """
+
+        logger.info(
+            f"Predicting {len(train_tsdf.item_ids)} time series with config{self.tabpfn_worker.tabpfn_config}"
+        )
+
+        return self.tabpfn_worker.predict(train_tsdf, test_tsdf, quantile_config)

tabpfn_time_series/tabpfn_worker.py

@@ -0,0 +1,224 @@
+import logging
+from abc import ABC, abstractmethod
+from joblib import Parallel, delayed
+
+import pandas as pd
+import numpy as np
+from scipy.stats import norm
+from autogluon.timeseries import TimeSeriesDataFrame
+
+from tabpfn_time_series.data_preparation import split_time_series_to_X_y
+from tabpfn_time_series.defaults import TABPFN_DEFAULT_QUANTILE_CONFIG
+
+logger = logging.getLogger(__name__)
+
+
+class TabPFNWorker(ABC):
+    def __init__(
+        self,
+        tabpfn_config: dict = {},
+        num_workers: int = 1,
+    ):
+        self.tabpfn_config = tabpfn_config
+        self.num_workers = num_workers
+
+    def predict(
+        self,
+        train_tsdf: TimeSeriesDataFrame,
+        test_tsdf: TimeSeriesDataFrame,
+        quantile_config: list[float],
+    ):
+        predictions = Parallel(
+            n_jobs=self.num_workers,
+            backend="loky",
+        )(
+            delayed(self._prediction_routine)(
+                item_id,
+                train_tsdf.loc[item_id],
+                test_tsdf.loc[item_id],
+                quantile_config,
+            )
+            for item_id in train_tsdf.item_ids
+        )
+
+        predictions = pd.concat(predictions)
+
+        # Sort predictions according to original item_ids order (important for MASE and WQL calculation)
+        predictions = predictions.loc[train_tsdf.item_ids]
+
+        return TimeSeriesDataFrame(predictions)
+
+    def _prediction_routine(
+        self,
+        item_id: str,
+        single_train_tsdf: TimeSeriesDataFrame,
+        single_test_tsdf: TimeSeriesDataFrame,
+        quantile_config: list[float],
+    ) -> pd.DataFrame:
+        test_index = single_test_tsdf.index
+        train_X, train_y = split_time_series_to_X_y(single_train_tsdf.copy())
+        test_X, _ = split_time_series_to_X_y(single_test_tsdf.copy())
+        train_y = train_y.squeeze()
+
+        train_y_has_constant_value = train_y.nunique() == 1
+        if train_y_has_constant_value:
+            logger.info("Found time-series with constant target")
+            result = self._predict_on_constant_train_target(
+                single_train_tsdf, single_test_tsdf, quantile_config
+            )
+        else:
+            # Call worker-specific prediction routine
+            result = self._worker_specific_prediction_routine(
+                train_X,
+                train_y,
+                test_X,
+                quantile_config,
+            )
+
+        result = pd.DataFrame(result, index=test_index)
+        result["item_id"] = item_id
+        result.set_index(["item_id", result.index], inplace=True)
+        return result
+
+    @abstractmethod
+    def _worker_specific_prediction_routine(
+        self,
+        train_X: pd.DataFrame,
+        train_y: pd.Series,
+        test_X: pd.DataFrame,
+        quantile_config: list[float],
+    ) -> pd.DataFrame:
+        pass
+
+    def _predict_on_constant_train_target(
+        self,
+        single_train_tsdf: TimeSeriesDataFrame,
+        single_test_tsdf: TimeSeriesDataFrame,
+        quantile_config: list[float],
+    ) -> pd.DataFrame:
+        # If train_y is constant, we return the constant value from the training set
+        mean_constant = single_train_tsdf.target.iloc[0]
+        result = {"target": np.full(len(single_test_tsdf), mean_constant)}
+
+        # For quantile prediction, we assume that the uncertainty follows a standard normal distribution
+        quantile_pred_with_uncertainty = norm.ppf(
+            quantile_config, loc=mean_constant, scale=1
+        )
+        result.update(
+            {
+                q: np.full(len(single_test_tsdf), v)
+                for q, v in zip(quantile_config, quantile_pred_with_uncertainty)
+            }
+        )
+
+        return result
+
+
+class TabPFNClient(TabPFNWorker):
+    def __init__(
+        self,
+        tabpfn_config: dict = {},
+        num_workers: int = 2,
+    ):
+        super().__init__(tabpfn_config, num_workers)
+
+        # Initialize the TabPFN client (e.g. sign up, login, etc.)
+        from tabpfn_client import init
+
+        init()
+
+    def predict(
+        self,
+        train_tsdf: TimeSeriesDataFrame,
+        test_tsdf: TimeSeriesDataFrame,
+        quantile_config: list[float],
+    ):
+        if not set(quantile_config).issubset(set(TABPFN_DEFAULT_QUANTILE_CONFIG)):
+            raise NotImplementedError(
+                f"TabPFNClient currently only supports {TABPFN_DEFAULT_QUANTILE_CONFIG} for quantile prediction,"
+                f" but got {quantile_config}."
+            )
+
+        return super().predict(train_tsdf, test_tsdf, quantile_config)
+
+    def _worker_specific_prediction_routine(
+        self,
+        train_X: pd.DataFrame,
+        train_y: pd.Series,
+        test_X: pd.DataFrame,
+        quantile_config: list[float],
+    ) -> pd.DataFrame:
+        from tabpfn_client import TabPFNRegressor
+
+        tabpfn = TabPFNRegressor(**self.tabpfn_config)
+        tabpfn.fit(train_X, train_y)
+        full_pred = tabpfn.predict_full(test_X)
+
+        result = {"target": full_pred[self._get_optimization_mode()]}
+        result.update({q: full_pred[f"quantile_{q:.2f}"] for q in quantile_config})
+
+        return result
+
+    def _get_optimization_mode(self):
+        if (
+            "optimize_metric" not in self.tabpfn_config
+            or self.tabpfn_config["optimize_metric"] is None
+        ):
+            return "mean"
+        elif self.tabpfn_config["optimize_metric"] in ["rmse", "mse", "r2", "mean"]:
+            return "mean"
+        elif self.tabpfn_config["optimize_metric"] in ["mae", "median"]:
+            return "median"
+        elif self.tabpfn_config["optimize_metric"] in ["mode", "exact_match"]:
+            return "mode"
+        else:
+            raise ValueError(f"Unknown metric {self.tabpfn_config['optimize_metric']}")
+
+
+class LocalTabPFN(TabPFNWorker):
+    def __init__(
+        self,
+        tabpfn_config: dict = {},
+    ):
+        # Local TabPFN has a different interface for declaring the model
+        if "model" in tabpfn_config:
+            config = tabpfn_config.copy()
+            config["model_path"] = self._parse_model_path(config["model"])
+            del config["model"]
+            tabpfn_config = config
+
+        super().__init__(tabpfn_config, num_workers=1)
+
+    def _worker_specific_prediction_routine(
+        self,
+        train_X: pd.DataFrame,
+        train_y: pd.Series,
+        test_X: pd.DataFrame,
+        quantile_config: list[float],
+    ) -> pd.DataFrame:
+        from tabpfn import TabPFNRegressor
+
+        tabpfn = TabPFNRegressor(**self.tabpfn_config)
+        tabpfn.fit(train_X, train_y)
+        full_pred = tabpfn.predict_full(test_X)
+
+        result = {"target": full_pred[tabpfn.get_optimization_mode()]}
+        if set(quantile_config).issubset(set(TABPFN_DEFAULT_QUANTILE_CONFIG)):
+            result.update({q: full_pred[f"quantile_{q:.2f}"] for q in quantile_config})
+        else:
+            import torch
+
+            criterion = full_pred["criterion"]
+            logits = torch.tensor(full_pred["logits"])
+            result.update({q: criterion.icdf(logits, q) for q in quantile_config})
+
+        return result
+
+    def _parse_model_path(self, model_name: str) -> str:
+        from pathlib import Path
+        import importlib.util
+
+        tabpfn_path = Path(importlib.util.find_spec("tabpfn").origin).parent
+        return str(
+            tabpfn_path / "model_cache" / f"model_hans_regression_{model_name}.ckpt"
+        )

tabpfn_time_series-0.1.0.dist-info/METADATA

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: tabpfn_time_series
+Version: 0.1.0
+Summary: Zero-shot time series forecasting with TabPFN
+Project-URL: Homepage, https://github.com/liam-sbhoo/tabpfn-time-series
+Project-URL: Bug Tracker, https://github.com/liam-sbhoo/tabpfn-time-series/issues
+Author-email: Liam Shi Bin Hoo <hoos@tf.uni-freiburg.de>
+License-File: LICENSE.txt
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: autogluon-timeseries
+Requires-Dist: gluonts
+Requires-Dist: pandas
+Requires-Dist: tabpfn-client
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Time Series Forecasting with TabPFN
+
+[![colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/liam-sbhoo/tabpfn-time-series/blob/main/demo.ipynb)
+[![Discord](https://img.shields.io/discord/1285598202732482621?color=7289da&label=Discord&logo=discord&logoColor=ffffff)](https://discord.com/channels/1285598202732482621/)
+[![arXiv](https://img.shields.io/badge/arXiv-<INDEX>-<COLOR>.svg)](https://arxiv.org/abs/2501.02945)
+
+
+We demonstrate that the tabular foundation model **TabPFN**, when paired with minimal featurization, can perform zero-shot time series forecasting. Its performance on point forecasting matches or even slightly outperforms state-of-the-art methods.
+
+## 📖 How does it work?
+
+Our work proposes to frame **univariate time series forecasting** as a **tabular regression problem**.
+
+![How it works](docs/tabpfn-ts-method-overview.png)
+
+Concretely, we:
+1. Transform a time series into a table
+2. Extract features from timestamp and add them to the table
+3. Perform regression on the table using TabPFN
+4. Use regression results as time series forecasting outputs
+
+For more details, please refer to our [paper](https://arxiv.org/abs/2501.02945) and our [poster](docs/tabpfn-ts-neurips-poster.pdf) (presented at NeurIPS 2024 TRL and TSALM workshops).
+
+## 👉 **Why gives us a try?**
+- **Zero-shot forecasting**: this method is extremely fast and requires no training, making it highly accessible for experimenting with your own problems.
+- **Point and probabilistic forecasting**: it provides accurate point forecasts as well as probabilistic forecasts.
+- **Support for exogenous variables**: if you have exogenous variables, this method can seemlessly incorporate them into the forecasting model.
+
+On top of that, thanks to [tabpfn-client](https://github.com/automl/tabpfn-client) from [Prior Labs](https://priorlabs.ai), you won’t even need your own GPU to run fast inference with TabPFN. 😉 We have included `tabpfn-client` as the default engine in our implementation.
+
+## How to use it?
+
+[![colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/liam-sbhoo/tabpfn-time-series/blob/main/demo.ipynb)
+
+The demo should explain it all. 😉

tabpfn_time_series-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+tabpfn_time_series/__init__.py,sha256=atVNap8tQLI0t5COkkCop-wbY3y1FdVxIMfvCf6VDsQ,257
+tabpfn_time_series/data_preparation.py,sha256=iNW7sAnRkTgmzzOEHBhkkTwm_lQ3p_Q9xgAQ5PbkOts,5416
+tabpfn_time_series/defaults.py,sha256=C9HiD7Zm0BzVfE9e2f8nhpiPQSYx79hWozvzb-93L40,165
+tabpfn_time_series/feature.py,sha256=_9FxfQfgPOOO1MiT8hB8523eZ3Nc5oKuoY7vcohKZZc,2531
+tabpfn_time_series/plot.py,sha256=bwSYcWBanzPrUxXKFsbqG8fyGsOJZfgU2v3NsxzTSXo,6571
+tabpfn_time_series/predictor.py,sha256=YfJIe8KsyzkwgX4EFAHR8dDp-mqSv9WK88_qO_EXlws,1505
+tabpfn_time_series/tabpfn_worker.py,sha256=3xInPzzQtmIBPjbc_5TaQsX3-Bl3WOlxttqj3KZlC9Q,7395
+tabpfn_time_series-0.1.0.dist-info/METADATA,sha256=3lPtIH1qAR58k6Y-19ZPN8fEEtNG1UKkW5qKZ-jh8e4,3147
+tabpfn_time_series-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+tabpfn_time_series-0.1.0.dist-info/licenses/LICENSE.txt,sha256=iwhPL7kIWQG6gyLZZwIMDItGrNgxMDIq9itxkUSMapY,11345
+tabpfn_time_series-0.1.0.dist-info/RECORD,,

tabpfn_time_series-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tabpfn_time_series-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Prior Labs GmbH
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.