tscv-vision

tscv-vision is a framework for constructing, learning, combining, and evaluating structured representations of time-series data. It includes NumPy-first image encoders, classical feature descriptors, representation metadata, fusion utilities, leakage-safe evaluation, and sliding-window processing for long signals.

The project is designed for research, reproducible feature extraction, and lightweight production pipelines where the core dependency footprint should stay small.

Highlights

• Time-series imaging encoders: Gramian Angular Field, Gramian Angular Difference Field, recurrence plots, spectrograms, and additional registry encoders.
• Classical feature extractors: intensity statistics, normalized histograms, gradient histograms, Local Binary Patterns, and batch extraction.
• Sliding-window pipelines for long 1D or multichannel signals.
• CLI for .npy inputs with metadata-rich .npz outputs.
• Leakage-safe evaluation: nested cross-validation helpers, SciPy-free statistical tests, and a UCR/UEA benchmark harness that freezes its raw outputs.
• Optional extras for analytics, GPU acceleration, and deliberately separated experimental integrations.
• Release-ready packaging with PyPI Trusted Publishing and Zenodo metadata.

Installation

Install the core package:

pip install tscv-vision

Install optional extras only when needed. These extras extend the validated core and research surface:

The following extras expose experimental integration code kept for backwards compatibility while it is evaluated for extraction into a contrib package. See docs/scope.md for the module split.

Every optional import in the package belongs to one of these extras; tests/test_docs_sync.py fails the build if a new one appears without a documented install route.

For local development:

git clone https://github.com/DiogoRibeiro7/tscv-vision.git
cd tscv-vision
poetry install

Quick Start

import numpy as np
from tscv_vision import encoders, features, sliding

x = np.sin(np.linspace(0, 4 * np.pi, 128))

# Encode a series as a 2D image.
img = encoders.gaf(x)
print(img.shape)  # (128, 128)

# Extract a feature vector from one image.
vec = features.extract_feature_vector(img, bins=32)
print(vec.shape)

# Extract a stacked feature matrix from multiple images.
batch = features.extract_batch(np.stack([img, img]), bins=32)
print(batch.shape)

# Encode overlapping windows and keep their start indices.
images, starts = sliding.encode_sliding(x, encoder="gaf", size=64, hop=32)
print(images.shape, starts)

# Extract sliding-window feature vectors directly.
matrix, starts = sliding.features_for_sliding(x, encoder="gaf", size=64, hop=32)
print(matrix.shape, starts)

Command Line

Generate sample data:

python samples/generate.py

Extract features from one signal:

tscv-features \
  --encoders gaf \
  --input samples/sine.npy \
  --output out.npz \
  --features all \
  --bins 32

Run a sliding-window, multi-encoder pipeline:

tscv-features \
  --encoders gaf,spec \
  --fusion concat \
  --sliding \
  --win-len 128 \
  --hop 64 \
  --input samples/sine.npy \
  --output out_sliding.npz \
  --save-images \
  --save-meta

The output .npz contains feature arrays plus JSON metadata. Sliding runs can include window_starts, win_len, hop, and encoded image stacks.

Feature Surface

Encoders

Every encoder accepts a nan_policy and is reachable by registry name through encoders.get_encoder(name).

Encoders taking more than one series live in tscv_vision.multivariate:

Feature Extractors

The unified vector's length depends on bins and on which optional packages are installed, so query it rather than hard-coding it:

from tscv_vision.features import feature_layout, feature_vector_length

feature_vector_length(bins=32)   # 694 with core dependencies only
feature_layout(bins=32)          # {'intensity': 6, 'hist': 32, 'lbp': 256, ...}

Benchmarking

tscv_vision.evaluation compares encoders against standard baselines (1-NN Euclidean, raw features, optionally ROCKET) on UCR/UEA datasets using their predefined train/test splits. It writes one CSV row per (dataset, method, seed), a manifest pinning package versions and the git commit, and a summary applying Demšar-style checks: Friedman test, average ranks, Nemenyi critical difference and Holm-corrected pairwise Wilcoxon tests.

python -m tscv_vision.evaluation --archive /data/UCRArchive_2018 --out results/ucr

The harness appends each completed row, resumes existing results.csv files by default, and accepts --n-jobs for independent dataset/method/seed combinations. The archive is not redistributable and is not vendored here. See docs/benchmarks.md.

For model selection, prefer the nested-CV entry points — they re-run the whole selection procedure inside each outer fold, so the reported score is not contaminated by the choices it evaluates:

pipe.nested_score(X, y)      # AdaptivePipeline
auto.nested_score(X, y)      # AutoTSCV

Representations

tscv_vision.representations puts one interface over every encoder and lets you select them by scientific provenance rather than by name:

from tscv_vision.representations import get_representation, list_representations

rep = get_representation("gaf", image_size=32)
image = rep.transform(series)          # (32, 32) whatever the series length

rep.info.canonical_method              # True — reproduces Wang & Oates (2015)
rep.info.validation_level.label        # 'LEVEL 3 — reference'

# Build an experiment from methods that are actually validated:
list_representations(canonical_method=True, min_validation_level=3)
# ['gadf', 'gaf', 'mp', 'mtf', 'mtspec', 'ph', 'scat']

Every representation carries a RepresentationInfo with its family, reference, complexity, and a validation level from 0 (smoke-tested) to 4 (benchmarked on real data). The dataclass refuses to claim more than the tests deliver: marking something canonical without a reference, or above smoke level without naming the tests that back it, raises at construction.

The three interfaces — Representation, FittedRepresentation, PretrainedRepresentation — are kept apart because they have different leakage profiles. A fitted representation refuses to transform before fit, and as_sklearn() wraps any of them so the fitting happens inside a cross-validation fold. scikit-learn is not required to use them.

See docs/encoder_validation.md for the per-encoder matrix, generated from the metadata.

Representation analysis

tscv_vision.analysis includes NumPy-only tools for comparing representation spaces before combining them. Start with linear CKA:

from tscv_vision.analysis import representation_similarity

similarity = representation_similarity({
    "gaf": Z_gaf,
    "cwt": Z_cwt,
    "rp": Z_rp,
})

The same module reports mean redundancy, pairwise fusion gains over the best single representation, and entropy-based effective rank for collapse checks.

Scientific Naming Policy

A function carries the name of a published method only when it implements that method and has a test pinning it to a reference implementation (tests/test_reference_equivalence.py, checked against scikit-image, SciPy, pyts, ripser, persim and stumpy) or to its published formula (tests/test_encoder_definitions.py). Everything else is named descriptively, and its docstring states what it is and what it is not.

Six names changed in 0.2.0 under this policy — persistence_image, tpa, TSHAPExplainer, cross_causal_lag, bias_report and add_dp_noise. The old names keep working until 0.3.0 and emit DeprecationWarning. See the changelog for the reasoning behind each.

Documentation

• API reference
• Encoder validation matrix
• Benchmarks
• Paper draft
• Deployment guide
• Performance guide
• Release checklist
• Test matrix
• Troubleshooting
• Roadmap

Development

The project uses Poetry, Ruff, mypy, pytest, and pre-commit.

poetry install
poetry run pre-commit run --all-files
poetry run ruff check .
poetry run mypy src
poetry run pytest -q                   # core suite
poetry run pytest -m optional          # optional integrations
poetry run pytest -m optional tests/test_reference_equivalence.py

The default pytest invocation excludes the optional, slow and gpu markers; CI runs each in its own job so a regression in the optional integrations cannot hide behind the default marker expression. See docs/test-matrix.md.

Build and check distribution artifacts:

python -m build
python -m twine check dist/*

The default package build is pure Python. To opt into building the optional Cython extension locally, set:

TSCV_BUILD_EXT=1 python -m build

See CONTRIBUTING.md for contribution workflow, coding standards, and pull request expectations.

Releases, PyPI, and Zenodo

Tagged releases are published to PyPI through GitHub Actions using PyPI Trusted Publishing with OpenID Connect. No PyPI API token is stored in the repository.

Zenodo archiving is configured through .zenodo.json. After the repository is enabled in Zenodo's GitHub integration, each GitHub Release can be archived with a version DOI. Add the DOI badge here after the first archive is created.

Citation

If you use tscv-vision in academic work, cite the archived Zenodo release once available, or use the metadata in CITATION.cff.

Diogo Ribeiro. tscv-vision: Computer-vision feature engineering for 1D time series.
https://github.com/DiogoRibeiro7/tscv-vision

Support and Security

• General questions and usage problems: open a GitHub Discussion or issue.
• Bug reports and feature requests: use the issue templates.
• Security concerns: follow SECURITY.md.

Maintainer

• Diogo Ribeiro
• School of Media Arts and Design, Polytechnic of Porto, Portugal
• GitHub: @DiogoRibeiro7
• ORCID: 0009-0001-2022-7072
• Email: dfr@esmad.ipp.pt

License

tscv-vision is distributed under the MIT License.