slimtsf · Sliding-Window Multivariate Time-Series Forest

A minimal, scikit-learn–compatible library for classifying multivariate time-series data using multi-scale sliding-window feature extraction.

Install

pip install slimtsf

Quick Start

Full pipeline (recommended)

import numpy as np
from slimtsf import SlimTSFClassifier

# X: (n_cases, n_channels, n_timepoints)  — 3-D numpy array
X_train = np.random.randn(100, 3, 120)
y_train = np.array([0] * 50 + [1] * 50)

clf = SlimTSFClassifier(n_estimators=200, random_state=42)
clf.fit(X_train, y_train)

X_test = np.random.randn(20, 3, 120)
predictions  = clf.predict(X_test)        # shape (20,)
probabilities = clf.predict_proba(X_test) # shape (20, 2)

Transformers only (composable use)

from slimtsf import SlidingWindowIntervalTransformer, IntervalStatsPoolingTransformer

# Stage 1 — extract sliding-window features
stage1 = SlidingWindowIntervalTransformer(
    window_sizes=[8, 16, 32],      # or None for auto
    window_step_ratio=0.5,
    feature_functions=["mean", "std", "slope"],
)
interval_features = stage1.fit_transform(X_train)  # (n_cases, n_interval_features)

# Stage 2 — pool across windows
stage2 = IntervalStatsPoolingTransformer(aggregations=("min", "mean", "max"))
pooled = stage2.fit_transform(
    interval_features,
    feature_metadata=stage1.feature_metadata_,     # wires Stage 1 → Stage 2
)  # (n_cases, n_pooled_features)

Use with scikit-learn tools

Because SlimTSFClassifier exposes fitted stage attributes, you can access the underlying sklearn RF and use it with standard sklearn utilities:

from sklearn.model_selection import cross_val_score

# Fit first, then use sklearn metrics on transformed data
clf.fit(X_train, y_train)
Xt = clf.stage2_.transform(clf.stage1_.transform(X_train))

scores = cross_val_score(clf.stage3_, Xt, y_train, cv=5)
print(scores.mean())

How It Works

3-D time-series X  (n_cases, n_channels, n_timepoints)
    │
    ▼  Stage 1 — SlidingWindowIntervalTransformer
    │  Slide windows of multiple sizes across each channel.
    │  Compute mean / std / slope per window.
    │  Output: 2-D matrix  (n_cases, n_interval_features)
    │
    ▼  Stage 2 — IntervalStatsPoolingTransformer
    │  For each (channel, feature) group,
    │  pool across windows: min / mean / max.
    │  Output: 2-D compact matrix  (n_cases, n_pooled_features)
    │  *Note: Stage 1 and Stage 2 outputs are configurable for downstream use via `feature_mode` (`"both"` concatenates them).*
    │
    ▼  Stage 3 — Bootstrap Feature Selection (Optional)
    │  Run multiple bootstrap resampling passes (using tree or statistical methods)
    │  to rank and select the top most stable features by selection frequency count.
    │  Output: 2-D refined matrix  (n_cases, n_selected_features)
    │
    ▼  Stage 4 — RandomForestClassifier (scikit-learn)
       Classify the final selected feature matrix.
       Output: predicted labels / probabilities

API Reference

SlimTSFClassifier

Methods: fit(X, y) · predict(X) · predict_proba(X) · get_feature_names_out() · get_feature_selection_frequencies()

Fitted attributes: stage1_ · stage2_ · stage3_ · classes_ · n_features_in_ · feature_selection_counts_

SlidingWindowIntervalTransformer

Input: X — shape (n_cases, n_channels, n_timepoints)
Output: 2-D feature matrix (n_cases, n_interval_features)

Methods: fit(X) · transform(X) · fit_transform(X) · get_feature_names_out()
Fitted attributes: feature_metadata_ · interval_list_

IntervalStatsPoolingTransformer

Input: 2-D interval feature matrix from Stage 1 + feature_metadata
Output: 2-D pooled feature matrix (n_cases, n_pooled_features)

Methods: fit(X, feature_metadata) · transform(X) · fit_transform(X, feature_metadata) · get_feature_names_out()

Custom Feature Functions

from slimtsf import FeatureFunction, SlidingWindowIntervalTransformer
import numpy as np

# A custom feature: interquartile range
iqr = FeatureFunction(
    name="iqr",
    function=lambda seg: np.percentile(seg, 75, axis=1) - np.percentile(seg, 25, axis=1),
)

transformer = SlidingWindowIntervalTransformer(feature_functions=["mean", iqr])

Versioning

This project follows Semantic Versioning and Conventional Commits:

Development

git clone https://github.com/kennaruk/slimtsf.git
cd slimtsf
pip install -e ".[dev]"
pytest -v

AI Collaboration & System Context

SlimTSF ships with embedded AI context and directives to ensure robust Test-Driven Development (TDD). If you are using an AI coding assistant (like Antigravity or Cursor), it will automatically pick up the rules in the .agents/ directory:

• .agents/skills/slimtsf_tdd_workflow/SKILL.md — Enforces a strict Test-First -> Implement -> Re-test workflow.
• .agents/llm_context.md — Provides an architectural system overview for agents.

License

MIT — see LICENSE.