DOCSEARCHbyAlgolia
Submit Docs

TabPFN-TS

repository·main·Indexed 19 days ago

https://github.com/priorlabs/tabpfn-time-series

A zero-shot time series forecasting library that leverages the TabPFN tabular foundation model to transform univariate forecasting into a tabular regression task. It provides fast, training-free point and probabilistic forecasting via the TabPFNTSPipeline. The library includes the TabPFNTSExplainer for explainability (PDP, Window SHAP, and Series Decomposition), a FeatureTransformer for temporal feature engineering, and support for both local GPU execution and cloud-based inference.

Tokens
12.6K
Snippets
45
Records
53
Agent score
65%

What's inside tabpfn-time-series

  1. Understand Window SHAP feature grouping in TabPFNTSExplainer

    main

    When using TabPFNTSExplainer for Window SHAP, attributions are applied to interpretable feature groups rather than raw featurizer columns. This ensures calendar concepts (like hour_of_day) appear as single entities rather than separate sin/cos pairs.

    Feature groups include:

    • Calendar Concepts: One group per concept (e.g., hour_of_day, day_of_week), which owns its corresponding {concept}_sin and {concept}_cos columns.
    • Trend: Composed of running_index and year (non-periodic drift terms).
    • Auto-seasonal: Auto-detected Fourier columns (sin_#.../cos_#...) derived from a Fast Fourier Transform (FFT) over the series.
    • User Covariates: One group per remaining column.

  2. Use TabPFNTSExplainer for time series explainability

    main

    The TabPFNTSExplainer class wraps a fitted TabPFNTSPipeline to provide three types of lightweight explanations for forecasts. It is designed to be computationally efficient by fitting the model once per window and reusing that fit across perturbations.

    Available explanation methods:

    1. Partial Dependence (PDP): Shows the partial dependence of the point forecast over calendar concepts (e.g., hour of day, day of week) and known covariates. Calendar concepts are evaluated in their original feature space (e.g., 0..23 for hour) and then re-encoded to sin/cos.
    2. Window SHAP: Provides grouped Shapley attributions of the point forecast across rolling forecast windows. This is plotted as a feature × time "spectrogram". It uses shapiq's KernelSHAP to estimate values. You can configure the window size and forecasting horizon via keyword arguments.
    3. Series Decomposition: A model-free additive decomposition of the target signal (not the forecast) into trend + per-time-feature seasonal components + residual (e.g., observed = trend + hour_of_day + day_of_week + residual).

    Note on Features: TabPFN-Time Series does not use lagged features. Auto-regressive signals are captured implicitly through seasonal features. Consequently, you will not see lagged features in SHAP plots or PDP results.

  3. Understand the TabPFN-TS covariate model

    main

    TabPFN-TS frames univariate time series forecasting as a tabular regression problem. It supports specific types of input columns:

    Input column typeSupported?Notes
    Target (univariate or multivariate)✅Multivariate targets are decomposed into N independent univariate forecasts.
    Known dynamic covariates (e.g. holidays)✅Future values must be supplied in future_df.
    Past dynamic covariates (e.g. weather observations)❌Dropped — no future values available.
    Static covariates (e.g. item_id, store_size)❌Currently dropped.
    Engineered temporal features (calendar, sin/cos, ...)✅Auto-generated by TABPFN_TS_DEFAULT_FEATURES.

    Note: If your forecasting task relies heavily on past_dynamic or static_columns, performance may be lower than dedicated multivariate or static-aware models.

  6. Quickstart with TabPFNTSPipeline

    main

    The TabPFNTSPipeline is the primary interface for zero-shot time series forecasting. By default, it uses a cloud client (via tabpfn-client), meaning you can perform fast inference without requiring a local GPU.

    To use the pipeline, initialize TabPFNTSPipeline and call predict_df with your context data and the desired prediction length.

    from tabpfn_time_series import TabPFNTSPipeline

pipeline = TabPFNTSPipeline()  # uses the cloud client by default — no GPU needed
predictions = pipeline.predict_df(context_df, prediction_length=24)

  7. Install tabpfn-time-series

    main

    You can install the package via pip to use it in your projects.

    To install the package for standard use:

    pip install tabpfn-time-series

    If you are a developer and want to install the package in editable mode with all development dependencies, use:

    pip install -e ".[dev]"
# or with uv
uv pip install -e ".[dev]"

  8. Install explainability dependencies and run the electricity example

    main

    To use the explainability features (which require shapiq and matplotlib), install the library with the [explainability] extra. You can then run the provided electricity dataset example to generate figures in the explainability_outputs/ directory.

    pip install 'tabpfn-time-series[explainability]'
python examples/explainability_electricity.py

  9. Set up the GIFT-EVAL evaluation environment

    main

    To prepare your environment for evaluating TabPFN-TS on GIFT-EVAL, use the provided setup script. This script installs all necessary dependencies and automatically downloads the required GIFT-EVAL datasets.

    Navigate to the gift_eval directory and execute setup.sh.

    cd gift_eval
./setup.sh

  10. Aggregate evaluation results

    main

    Evaluation results for each dataset are stored in separate files. To merge all results into a single file for comparison, use the aggregate_results.py utility. The --result_root_dir argument should point to the same directory used as --output_dir during the evaluation step.

    python aggregate_results.py --result_root_dir <result_root_dir>

  11. Run TabPFN-TS evaluation on a dataset

    main

    After setup, you can evaluate a specific dataset using the evaluate.py script. You must specify the dataset name and the directory where results should be saved.

    Note: It is highly recommended to run this on a GPU or multi-GPU machine. The implementation supports multi-GPU inference to mitigate TabPFN-TS inference speed limitations.

    python evaluate.py --dataset <dataset_name> --output_dir <output_dir>

  12. How TabPFNTSPipeline handles large datasets (Batching)

    main

    To prevent Out-Of-Memory (OOM) errors on the host machine when processing very large datasets (e.g., tens of thousands of series), TabPFNTSPipeline uses a row-bounded batching mechanism controlled by max_featurize_rows.

    How it works:

    1. The pipeline calculates the number of rows required for each item_id (capped by max_context_length).
    2. It iterates through item_ids, grouping them into batches such that the total number of rows in the batch does not exceed max_featurize_rows.
    3. Each batch is featurized and predicted independently.
    4. The results are concatenated back together, preserving the original item_id order.

    This process is numerically identical to processing the entire dataset at once but caps peak host memory usage. Setting max_featurize_rows=None disables this batching behavior.