fast-borf

Official implementation of Bag-Of-Receptive-Fields (BORF), from the papers Fast, Interpretable, and Deterministic Time Series Classification With a Bag-of-Receptive-Fields (IEEE Access, 2024) and A Time-Aware Bag-of-Receptive-Fields for Interpretable Irregular Time Series Classification (arXiv, 2026).

BORF turns time series into sparse bag-of-words features. Each signal is cut into sliding windows at many window sizes, word lengths and dilations, every window becomes a SAX word, and the output counts how often each word occurs. The features are meant for linear models and can be mapped back to the parts of the series they come from.

BORF handles univariate and multivariate series, variable lengths, missing values and irregular sampling, and is a scikit-learn transformer. Compared with the aeon version, this package adds explanations (saliency maps and receptive fields), irregularly sampled series, channel groups, blockwise transformers and a fixed vocabulary option.

Installation

pip install fast-borf

The original implementation for regularly sampled series is available as release v0.1.0.

Quick start

import numpy as np
from sklearn.linear_model import RidgeClassifierCV
from sklearn.pipeline import make_pipeline

from fast_borf import BORF

rng = np.random.default_rng(0)
X = rng.standard_normal((100, 1, 200)).cumsum(axis=2)  # (n_series, n_signals, n_timestamps)
y = rng.integers(0, 2, 100)

model = make_pipeline(BORF(n_jobs=-1), RidgeClassifierCV())
model.fit(X, y)

See examples/ for complete scripts, and notebooks/classification_tutorial.ipynb for a step-by-step walkthrough of the process, classification and explanations, on regular and irregular series (install with the notebooks extra to run it).

Input formats

• NumPy array of shape (n_series, n_signals, n_timestamps). Use NaN for missing values and to pad shorter series.
• Ragged awkward array with the same nesting, for series of different lengths.
• Irregular sampling: put the timestamps of each series in an extra last channel and use BORF(time_channel=True). Timestamps must be strictly increasing within each series. Without a time channel, observations are treated as evenly spaced.

Main parameters

Inspecting the features

After fitting:

• configs_: the configurations (window size, word length, alphabet size, dilation, stride), in the order of the output columns.
• config_slices_[i]: the output columns of configuration i.
• feature_index_: for every output column, its configuration index, signal index (group index with channel_groups) and SAX word (as an integer in base alphabet_size).

Blockwise processing

block_transformer fits a copy of any scikit-learn transformer or pipeline on each configuration's columns, for example to normalize or select features per configuration:

from sklearn.feature_selection import SelectKBest, chi2
from sklearn.preprocessing import Normalizer

BORF(block_transformer=Normalizer())
BORF(block_transformer=SelectKBest(chi2, k=10))  # 10 words per configuration

feature_index_ and config_slices_ follow columns that the transformer keeps or selects.

Explanations

fast_borf.xai.BagOfReceptiveFields maps per-series feature importances back onto the series. The importances can come from anything: SHAP values, or for a linear model simply coefficient times feature value.

from fast_borf.xai import BagOfReceptiveFields

explainer = BagOfReceptiveFields(borf).build(X, y_true, y_pred, task="classification")
explainer.add_feature_importance(F)  # (n_series, n_features), or (n_classes, n_series, n_features)
explainer.map_contained_feature_importance_to_saliency()  # S_: importance per point
explainer.map_notcontained_feature_importance()  # F_norm_: importance of absent words

field = explainer.receptive_fields_[explainer.F_avg_rank_argsort_[0]]
field.alignments_indices[i]  # (occurrences, word_length, segment_size) points of each segment
field.mappings[i], field.alignments[i]  # their values and timestamps

Receptive fields are computed when first accessed. fast_borf.core exposes the underlying steps (segment_means, discretize, window_positions, panel_words) for custom analyses and plots. See examples/explanation.py.

BORF in aeon

A BORF transformer for regularly sampled series is also available in the aeon toolkit.

Development

pip install -e ".[dev]"
pre-commit install
pytest

The tests in tests/test_reference.py compare against outputs saved from the original implementation, so refactoring cannot silently change the features.

Citation

If you use BORF, please cite:

@article{spinnato2024borf,
  title   = {Fast, Interpretable, and Deterministic Time Series Classification With a Bag-of-Receptive-Fields},
  author  = {Spinnato, Francesco and Guidotti, Riccardo and Monreale, Anna and Nanni, Mirco},
  journal = {IEEE Access},
  volume  = {12},
  pages   = {137893--137912},
  year    = {2024},
  doi     = {10.1109/ACCESS.2024.3464743}
}

For irregularly sampled series (time_channel=True), please also cite:

@misc{spinnato2026timeawareborf,
  title         = {A Time-Aware Bag-of-Receptive-Fields for Interpretable Irregular Time Series Classification},
  author        = {Spinnato, Francesco},
  year          = {2026},
  eprint        = {2609.39268},
  archivePrefix = {arXiv},
  primaryClass  = {cs.LG},
  url           = {https://arxiv.org/abs/2609.39268}
}