DeTime

One Python and CLI interface for trend, oscillation, residual, components, and metadata.

DeTime provides one stable software surface for decomposition workflows that would otherwise be split across notebooks, method-specific wrappers, and one-off scripts. The product name is DeTime, the PyPI distribution is detime-toolkit, the canonical import is detime, and the legacy top-level tsdecomp import and CLI remain compatibility-only through 0.1.x, with earliest removal planned for 0.2.0.

The reviewed release version is 0.1.3. Its release identity is the de-time-v0.1.3 source tag and matching detime-toolkit==0.1.3 PyPI distribution. Use the editable contributor path below for development against the repository head.

Fast entry points:

• Documentation site
• Inline method gallery
• Beginner notebook method gallery
• Cross-package comparison
• Method comparison matrix
• Release manifest
• Release evidence tables

Scope

Use DeTime when you want:

• one decompose() entrypoint,
• one DecompositionConfig model for Python and CLI usage,
• one DecompResult contract for trend, season, residual, components, and meta,
• native acceleration where it materially improves throughput,
• multivariate decomposition workflows where shared structure matters,
• machine-facing workflows that need schemas, metadata-based shortlists, and compact result views.

Use a specialist package directly when you only need that package's deepest family-specific API.

Core and accelerated methods

The main package is centered on four core maintained methods:

• SSA
• STD
• STDR
• MSSA

The current native-backed accelerated set is broader:

• core native paths: SSA, STD, STDR, MSSA
• additional native-backed method: VMD
• lightweight native-backed baseline: MA_BASELINE
• experimental optional clustering path: GABOR_CLUSTER

Other retained methods are wrappers, Python implementations, or optional-backend integrations such as STL, MSTL, ROBUST_STL, EMD, CEEMDAN, WAVELET, MVMD, and MEMD.

Experimental neural decomposition blocks extracted as standalone DeTime methods are also available. They are package-level experimental operators for decomposition-head ablations, reusable result-contract tests, and interface coverage. Their architecture-derived identifiers record the cited source of inspiration; they are not complete implementations of the corresponding forecasting architectures and are excluded from recommendations unless allow_experimental is set explicitly.

Their source-paper links are listed in docs/method-references.md.

Benchmark-derived methods DR_TS_REG, DR_TS_AE, and SL_LIB do not ship in the main package. They belong to the companion benchmark repository systems-mechanobiology/de-time-bench.

Cross-package comparison

DeTime is positioned as a software-contract and machine-contract layer beside specialist packages, not as a replacement for all of them.

Broader time-series libraries such as Darts, aeon, and StatsForecast provide forecasting or time-series machine-learning abstractions. DeTime has a narrower boundary: standalone cross-family decomposition with shared configuration, results, metadata, schemas, CLI execution, profiling, and saved artifacts.

Full comparison details are in docs/comparisons.md; curated evidence files are kept in comparison_evidence.md.

Install

Install the latest released package from PyPI:

python -m pip install detime-toolkit

Install optional extras as needed:

python -m pip install "detime-toolkit[multivar]"
python -m pip install "detime-toolkit[emd,neural]"
python -m pip install "detime-toolkit[notebook]"

Install directly from GitHub when you need the unreleased main branch:

python -m pip install "git+https://github.com/systems-mechanobiology/DeTime.git"

Do not install the unrelated detime package from PyPI when you want this project; install detime-toolkit instead.

Quickstart

import numpy as np

from detime import DecompositionConfig, decompose

t = np.arange(120, dtype=float)
series = 0.03 * t + np.sin(2.0 * np.pi * t / 12.0)

result = decompose(
    series,
    DecompositionConfig(
        method="SSA",
        params={"window": 24, "rank": 6, "primary_period": 12},
    ),
)

print(result.trend.shape)
print(result.meta["backend_used"])

detime run \
  --method STD \
  --series examples/data/example_series.csv \
  --col value \
  --param period=12 \
  --out-dir out/std_run \
  --output-mode summary

CLI surface

The supported commands are:

• detime run
• detime batch
• detime profile
• detime version
• detime schema
• detime recommend
• detime benchmark

The legacy tsdecomp executable calls the same code path but emits a deprecation notice.

TSDecompose benchmark bridge

The benchmark code remains in the external Hugging Face bundle Zipeng365/TSDecompose-Benchmark. DeTime provides a bridge API and CLI that downloads the bundle's code/TSDecompose source snapshot into a local cache and runs its published paper-core runner.

This bridge executes code outside the installed DeTime package. It defaults to the reviewed 40-character Hugging Face dataset revision and scrubs common credential variables before starting the external runner. Running a branch or tag such as main requires both --allow-external-benchmark-code and --allow-unpinned-benchmark-revision.

Fast smoke run:

detime benchmark --allow-external-benchmark-code --out-dir out/tsdecompose-smoke

Full paper-core run:

detime benchmark --allow-external-benchmark-code --full --out-dir out/tsdecompose-paper-core

Python API:

from detime import run_tsdecompose_benchmark

result = run_tsdecompose_benchmark(
    smoke=True,
    out_dir="out/tsdecompose-smoke",
    allow_external_code=True,
)
print(result.leaderboard_path)

Machine-facing surface

DeTime now includes:

• packaged JSON schemas for config, result, meta, and method-registry,
• low-token result export modes: full, summary, and meta,
• machine-readable method metadata for registry, docs, and metadata-based shortlists,
• detime schema and detime recommend.

These interfaces support non-interactive automation. The maintained software claim remains the decomposition API, CLI, schemas, result object, metadata, and validated package boundary.

Package boundary

This repository ships the reusable decomposition software package, docs, tests, and examples needed for detime itself. Benchmark orchestration, leaderboard artifacts, benchmark scenario galleries, and benchmark-derived methods are split into the companion repository systems-mechanobiology/de-time-bench. The detime benchmark command is a bridge to the external TSDecompose benchmark bundle; it does not vendor benchmark-derived methods into the main package. The bridge is pinned and opt-in by default; unpinned external revisions require a second explicit flag and should be used only for local experiments.

Only the top-level tsdecomp import and CLI alias remain packaged for compatibility.

Quality and evidence

• Release smoke checks live in scripts/release_smoke_matrix.py.
• Documentation consistency checks live in scripts/check_doc_consistency.py.
• The current performance snapshot is generated by scripts/generate_performance_snapshot.py and stored under docs/assets/generated/evidence/.
• Comparison matrices are generated by benchmarks/software_comparison/generate_comparison_evidence.py.
• The coverage story is intentionally split into core-surface coverage and package-wide coverage so the denominator stays explicit.

Coverage from the 2026-07-14 checkout audit:

The JSON reports are stored in docs/assets/generated/evidence/coverage_core.json, docs/assets/generated/evidence/coverage_package.json, and docs/assets/generated/evidence/coverage_summary.json.

Release-validation runtime snapshot for selected native-backed paths in the reviewed environment. These values compare DeTime native-backed paths against internal Python fallback paths in one environment; they are not a portable cross-package benchmark.

A ratio above 1 means the native path was faster in this snapshot. The native path was faster for STD, STDR, MA baseline, and MSSA; the vectorized Python path was faster for SSA and VMD on this input and environment.

Experimental GABOR_CLUSTER timing is excluded from release-validation performance evidence. It can be generated separately with scripts/generate_performance_snapshot.py --include-experimental after a trained model object and optional clustering backend are reviewed.

Documentation and tutorial evidence:

Documentation

Core docs:

• Homepage: https://systems-mechanobiology.github.io/DeTime/
• Install: https://systems-mechanobiology.github.io/DeTime/install/
• Quickstart: https://systems-mechanobiology.github.io/DeTime/quickstart/
• Methods overview: https://systems-mechanobiology.github.io/DeTime/methods/
• Notebook gallery: https://systems-mechanobiology.github.io/DeTime/notebook-gallery/
• Tutorials: https://systems-mechanobiology.github.io/DeTime/tutorials/univariate/
• Quant Trading column: https://systems-mechanobiology.github.io/DeTime/tutorials/quant-trading/
• Hot Trend Lab: https://systems-mechanobiology.github.io/DeTime/tutorials/hot-trend-lab/
• API: https://systems-mechanobiology.github.io/DeTime/api/

Reference and review:

• Method matrix: https://systems-mechanobiology.github.io/DeTime/method-matrix/
• Config reference: https://systems-mechanobiology.github.io/DeTime/config-reference/
• Method references: https://systems-mechanobiology.github.io/DeTime/method-references/
• Machine API: https://systems-mechanobiology.github.io/DeTime/machine-api/
• Comparisons: https://systems-mechanobiology.github.io/DeTime/comparisons/
• Reproducibility: https://systems-mechanobiology.github.io/DeTime/reproducibility/

Project files

• Citation metadata: CITATION.cff
• Changelog: CHANGELOG.md
• Design notes: DESIGN.md
• Contributing guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Publishing notes: PUBLISHING.md
• Release manifest: RELEASE_MANIFEST.md
• Source/archive boundary: SOURCE_ARCHIVE_BOUNDARY.md
• Third-party licenses: THIRD_PARTY_LICENSES.md
• License audit notes: LICENSE_AUDIT.md
• Authors and credit: AUTHORS.md, CREDIT.md