Skip to main content

Kymora

High-Performance Time-Series Feature Extraction. Rust Core. Python Ease.

PyPI - Version PyPI - Python Version License: MIT CI Docs

Batch time-series feature extraction: 33 features at 3.18 ms median per 1,000 series x 500 steps, with zero defensive memory copies.

Kymora is a minimalistic, dependency-light time-series feature extraction library designed to make extracting statistical, temporal, and spectral features across large datasets fast and memory-efficient. It combines a zero-copy Rust engine with a clean, Scikit-Learn-compatible Python interface—ideal for machine learning pipelines, quantitative finance, real-time sensor telemetry, and high-throughput research.

PyPI • Features • Installation • Quickstart • Benchmarks • Streaming & Real-Time Telemetry • Scikit-Learn Integration • Documentation • Website


Why Kymora?

Traditional Python time-series feature libraries (tsfresh, TSFEL, catch22) force a painful trade-off: wait minutes to hours for feature extraction, or risk Out-Of-Memory (OOM) crashes from defensive copies. Kymora eliminates that trade-off.

  • Throughput (measured): Best run 436,719 series/second (median 314,450) on an i7-13620H laptop, 10 cores / 16 threads — about 262× catch22 and 6,570× tsfresh raw time on the same machine (per-feature: 393× and 279× — see Benchmarks and CLAIMS.md).
  • Zero-Copy Ingestion: Directly borrows contiguous NumPy buffer pointers via PyO3. No data duplication, no DataFrame melting, and zero intermediate memory ballooning.
  • 33 Curated, High-Signal Features: Avoids the curse of dimensionality. Features are mathematically non-redundant ($|r| < 0.70$ for 83.3% of pairs), spanning distribution moments, quantiles, crossings, spectral power, and permutation entropy.
  • Full Multi-Core Scaling (GIL-Free): Releases Python's Global Interpreter Lock (GIL) across the entire computation region, saturating all CPU cores with Rayon's work-stealing scheduler.
  • Real-Time Streaming Ready: Maintain rolling windows with incremental state updates using the built-in StreamingExtractor — amortized $O(1)$ per-sample ingestion plus a fast 12-feature tier with no sorting and no FFT.

Key Features

  • Zero-Copy Hybrid Architecture: PyO3 bindings pass 2D NumPy pointer references directly into native-Rust multi-core loops without copying a single byte.
  • Batch-First Parallelism: Processes $N$ series in parallel across hardware threads instead of running serial Python loops.
  • Dual API Support: Extract raw 2D NumPy matrices for maximum speed, or labeled Pandas/Polars DataFrames for immediate exploratory analysis.
  • Scikit-Learn Compatible: Drop KymoraTransformer into any sklearn.pipeline.Pipeline or cross-validation grid search.
  • Realfft & Histogram Quantiles: Preallocated per-worker FFT scratch and histogram multi-select quantiles ensure predictable sub-millisecond execution.
  • Streaming & Sliding Windows: Extract rolling features over continuous data streams without reallocating buffers.

Installation

Precompiled binary wheels are available on PyPI (kymora) for Linux (x86_64, aarch64), macOS (Apple Silicon arm64, Intel x86_64), and Windows (x64). No Rust compiler required!

pip install kymora

From Source (Development)

git clone https://github.com/Aamodx6/Kymora.git
cd Kymora
pip install maturin
maturin develop --release

Quickstart

1. Batch Feature Extraction (2D NumPy)

Extract 33 features from 100,000 series in under a second:

import numpy as np
import kymora as km

# 1,000 series of 500 time-steps (float64)
X = np.random.randn(1000, 500)

# Extract 33 features (zero-copy, multi-threaded)
features = km.extract_features(X)

print("Output shape:", features.shape)      # (1000, 33)
print("Feature names:", km.feature_names()[:5])
# ['mean', 'std', 'var', 'min', 'max', ...]

2. Labeled Pandas DataFrame

# Returns a labeled pandas DataFrame with clean column headers
df = km.extract_features_df(X)
print(df.head())

3. Ragged Series of Different Lengths

# Sequences of varying lengths are supported natively
arr1 = np.random.randn(300)
arr2 = np.random.randn(500)
arr3 = np.random.randn(120)

features = km.extract_features([arr1, arr2, arr3])
print(features.shape)  # (3, 33)

4. Sliding Windows over a Long Signal

# Extract rolling window features from a 1D continuous sensor stream
signal = np.random.randn(100_000)
windowed_features = km.sliding_features(signal, window=256, stride=64)

Scikit-Learn Pipeline

Integrate directly into standard classification, regression, or clustering pipelines (pip install "kymora[sklearn]" for the optional dependency):

import numpy as np
from kymora.sklearn import KymoraTransformer
from sklearn.pipeline import Pipeline
from sklearn.ensemble import RandomForestClassifier
from sklearn.preprocessing import StandardScaler

# Assemble end-to-end reproducible pipeline
pipeline = Pipeline([
    ("features", KymoraTransformer()),  # (n_series, length) -> (n_series, 33)
    ("scaler", StandardScaler()),
    ("classifier", RandomForestClassifier(n_estimators=100))
])

# Synthetic training data (n_samples, time_steps) — replace with your series
rng = np.random.default_rng(0)
X_train = rng.standard_normal((40, 128))
y_train = (X_train.sum(axis=1) > 0).astype(int)
X_test = rng.standard_normal((10, 128))

# Fit on raw time-series training data (n_samples, time_steps)
pipeline.fit(X_train, y_train)
y_pred = pipeline.predict(X_test)

Streaming & Real-Time Telemetry

Maintain running statistical features in real-time embedded systems or trading loops without recomputing from scratch:

import numpy as np
from kymora import StreamingExtractor

# Initialize streaming extractor with window capacity
stream = StreamingExtractor(window_size=500)
incoming_data_feed = iter(np.random.default_rng(1).standard_normal(600))

for tick in incoming_data_feed:
    stream.push(tick)
    
    # 1. Fast 12-feature tier (O(1) accumulator reads — no scan, no sorting, no FFT):
    # Returns 12 features: mean, std, var, skew, kurt, abs_energy, rms,
    # mean_abs_change, mean_change, cid_ce, zero_crossings, trend_slope.
    # Accuracy matches batch within rtol 1e-9 (see docs/streaming.md for the
    # large-offset skew/kurt conditioning note).
    fast_features = stream.compute(kind="fast")
    
    # 2. Complete 33-feature set evaluated over the current rolling window:
    all_features = stream.compute(kind="all")

Profiles & Feature Catalog

Choose the performance-to-breadth profile that fits your pipeline:

  • minimal (10 features): Centered moments, extrema, energy, zero crossings. Zero sorting and zero FFT overhead (~1.20 ms per 1,000 series; 833,333 series/s, re-measured 2026-10-05).
  • core33 (33 features - Default): Frozen authoritative v1.0 set spanning all temporal, quantile, and spectral domains (~2.88 ms median per 1,000 series on i7-13620H / 16 threads, re-measured 2026-10-05; the 2026-10-04 F1 pool measured 3.18 ms / 314,450 series/s — run-to-run spread, both artifacts committed; 0.0964 µs per series-feature).
  • extended (143 features): Adds distribution statistics, crossings, nonlinear stats, PACF (Levinson-Durbin), full linear regression trend, and spectral aggregations.
  • full (543 features): Complete high-coverage bank including all 400 FFT coefficient parameters extracted directly from the precomputed spectrum with zero redundant transforms.
import kymora

# List available profiles and feature counts
print(kymora.list_profiles())
# {'minimal': 10, 'core33': 33, 'extended': 143, 'full': 543}

# Inspect individual features and their computational prerequisites
print(kymora.describe_feature("autocorr_lag_1"))

Benchmarks

All numbers below are pooled medians from interleaved rounds with 95% bootstrap CIs, subprocess-isolated, GC disabled — from one laptop (i7-13620H, 10 cores (6P+4E) / 16 threads, Windows 11, Performance plan, AC online). Exploratory single-machine numbers, not fleet evidence. Claim→artifact map: CLAIMS.md. Artifacts: benchmarks/results/F1_REPORT.md (raw-time + competitor rounds, 2026-10-04), benchmarks/results/EQUAL_FEATURE_REPORT.md + 2026-10-05_equal_feature/ (equal-feature, 2026-10-05), benchmarks/results/2026-10-05_remeasure/ (profiles / scaling / memory, 2026-10-05):

Equal-feature comparison — the like-for-like table (1,000 × 500)

Both sides compute exactly the same features: each library is restricted to the subset whose definitions match kymora's, and every feature pair is numerically verified before timing (parity gate: max rel err ≤ 1e-9; artifact 2026-10-05_equal_feature/parity.json). 16 threads:

Library Equal features Kymora med (ms) Library med (ms) Ratio (95% CI)
numba baseline 33 4.72 16.05 3.4× slower [3.1, 3.9]
numpy baseline 33 4.68 285.50 61.0× slower [60.0, 62.0]
TSFEL 13 3.92 2,213.69 564.6× slower [509.7, 781.4]
tsfresh 13 4.94 8,359.45 1,693.8× slower [1,645.5, 1,900.1]

Kymora is fastest on all 16 equal-feature rows measured across 4 shapes (ratios 3.4×–1,693.8×; full tables: benchmarks/results/EQUAL_FEATURE_REPORT.md). catch22 has no row here by design: none of its 22 features is definition-identical to a core33 feature (mapping and near-miss analysis: docs/benchmarks/feature_mapping.md).

Profile throughput (1,000 × 500, 16 threads — re-measured 2026-10-05):

Profile Features Latency (1k) Per-Series Per-Feature Cost Throughput
minimal 10 1.20 ms 1.20 µs 0.120 µs 833,333 series/s
core33 33 2.88 ms 2.88 µs 0.0873 µs 346,963 series/s
extended 143 10.10 ms 10.10 µs 0.0706 µs 99,028 series/s
full 543 11.10 ms 11.10 µs 0.0204 µs 90,052 series/s

Artifact: benchmarks/results/2026-10-05_remeasure/profiles.jsonl (medians of subprocess-isolated runs per profile).

Multi-core scaling (core33, 1,000 × 500 — re-measured 2026-10-05):

Worker Threads Latency Per-Series Cost Speedup vs 1 Thread Scaling Efficiency
1 Thread 12.47 ms 12.47 µs 1.00× 100.0%
2 Threads 7.01 ms 7.01 µs 1.78× 89.0%
4 Threads 4.11 ms 4.11 µs 3.03× 75.7%
8 Threads 3.03 ms 3.03 µs 4.12× 51.5%
16 Threads 2.93 ms 2.93 µs 4.25× 26.6%
32 Threads 3.51 ms 3.51 µs 3.56× 11.1%

Efficiency drops past ~4–8 threads on this hybrid P+E-core laptop (oversubscription past 10 physical cores); treat the shape of this table as hardware-bound. Artifact: benchmarks/results/2026-10-05_remeasure/scaling.jsonl.

Raw-time comparison — full default catalogs (1,000 × 500)

Each library times its full default catalog end to end, including the input reshaping it requires (tsfresh's long-format DataFrame, catch22/TSFEL's per-series loop):

Library Features Runtime (1k × 500) Series / sec Speedup (raw time) Per-feature Speedup (per-feature)
Kymora (core33) 33 3.18 ms 314,450 Baseline (1.0×) 0.0964 µs Baseline (1.0×)
catch22 22 833.1 ms 1,200 262× slower 37.87 µs 393×
TSFEL 156 2,541.6 ms 393 799× slower 16.29 µs 169×
tsfresh 777 20,891.2 ms 48 6,570× slower 26.89 µs 279×

Pooled medians: kymora over 4 HEAD rounds (n=400 runs), competitors over 10 rounds (n=53/83/64); 95% bootstrap CIs in benchmarks/results/F1_REPORT.md. Raw time answers "how long for the batch"; per-feature answers "how expensive each number is". Different feature counts mean different work — read both columns, and prefer the equal-feature table above for a like-for-like claim.

Where Kymora is slower

Honest losses, with evidence (benchmarks/results/L1_ROOT_CAUSE.md, B3_REPORT.md):

  • Tiny single-shot calls. A fixed per-call floor (~0.6–0.7 ms measured: FFI entry + rayon pool wake) dominates when the whole call is smaller than that. Against a hand-written numba baseline on the same 33 features, kymora was 17.9×–40.2× slower at 1 × 100 and 3.1×–5.7× slower at 10 × 500 (95% CIs exclude 1.0). Per-series compute is competitive at these shapes — the floor and the pool wake are the cost.
  • Thread wake at small n. At 100 × 100, 16 threads made kymora ~27% slower than 1 thread (pool wake/join swamps ~12 µs/series of compute). Scaling efficiency at small batches is poor regardless of core count.
  • Single-series tail latency at very short lengths. At length 10, kymora wins the median (345.8 µs vs numpy's 1,317.6 µs) but loses the tail (p99 15.4 ms, max 29.1 ms) to wake jitter.
  • Not a robust loss: the 100 × 500 rows against the numba baseline are parity within noise (0.94×–0.99×, CI crosses 1.0).

Guidance: batch many series into one call, or use StreamingExtractor for one-series-at-a-time ingest. At ≥1,000 series the picture inverts — kymora beats the numba baseline 3.4×–11.1× on identical features (equal-feature table above).

Memory footprint (re-measured 2026-10-05, fresh-process peak RSS):

  • Kymora (core33, 100,000 × 500): +417.7 MiB peak over a bare interpreter — input 385.4 MiB, extraction overhead +32.3 MiB, output matrix 25.2 MiB (= 100,000 × 33 × 8 B).
  • tsfresh (EfficientFCParameters, 777 features): extraction peak +281.9 MiB at 1,000 × 500 and +407.5 MiB at 10,000 × 500 (long-format DataFrame plus intermediate frames).
  • The tsfresh 100,000 × 500 cell is a multi-hour run — PENDING, tracked in CLAIMS.md.

Artifact: benchmarks/results/2026-10-05_remeasure/memory.jsonl.


The 33 Curated Features

Kymora deliberately computes 33 high-signal, non-redundant features spanning all temporal domains (exact catalog: kymora.feature_names()):

  • Moments: mean, std, var, skewness, kurtosis.
  • Extrema & quantiles: min, max, median, quantile_10, quantile_25, quantile_75, quantile_90.
  • Energy & shape: abs_energy, root_mean_square, number_of_peaks.
  • Differences & trend: mean_abs_change, mean_change, cid_ce, mean_second_derivative_central, trend_slope, trend_r2.
  • Crossings & runs: zero_crossings, mean_crossings, longest_strike_above_mean, longest_strike_below_mean.
  • Autocorrelation: autocorr_lag_1, autocorr_lag_2, autocorr_lag_5, autocorr_lag_10.
  • Spectral: dominant_frequency, spectral_centroid, spectral_entropy.
  • Complexity: permutation_entropy (order 3, delay 1).

Contributing

Contributions, bug reports, and PRs are welcome! Please check CONTRIBUTING.md for details on setting up the local Rust/Python development environment and running the benchmark suites.


License

Distributed under the MIT License. See LICENSE for details.

Built with Rust and Python by Aamod.

Metadata

Release files for kymora 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kymora 0.8.0
File Size Uploaded Provenance Actions
kymora-0.8.0.tar.gz 2.9 MB With provenance Details for kymora-0.8.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for kymora 0.8.0
File Actions
kymora-0.8.0-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for kymora-0.8.0-cp310-abi3-win_amd64.whl
kymora-0.8.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.10 abi3 Linux glibc 2.17+ x86-64 Details for kymora-0.8.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
kymora-0.8.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.10 abi3 Linux glibc 2.17+ ARM64 Details for kymora-0.8.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
kymora-0.8.0-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for kymora-0.8.0-cp310-abi3-macosx_11_0_arm64.whl
kymora-0.8.0-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for kymora-0.8.0-cp310-abi3-macosx_10_12_x86_64.whl

Total release size: 9.7 MB

Release files / kymora-0.8.0.tar.gz

Download URL kymora-0.8.0.tar.gz
Size 2.9 MB
Tags Source
SHA-256 checksum
How to use checksums
8f8c6639cfe28ced3bc9e5bfb92729a384a3507efe303487a5129e5c10f5790e
BLAKE2b-256 checksum
How to use checksums
b8689e9588eeab747f84d10135e8e7d7149154faa7055f8640f7f8ba23a9a8c1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

Release files / kymora-0.8.0-cp310-abi3-win_amd64.whl

Download URL kymora-0.8.0-cp310-abi3-win_amd64.whl
Size 712.3 kB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
7e6aeddba226813a1549166675978cb01ff8006715e51e6addd58a8a825050e7
BLAKE2b-256 checksum
How to use checksums
5fa851136179d229d47c4d7d0757874c5e5351cc7221ae7b9707e14f2bad3ca3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

Release files / kymora-0.8.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL kymora-0.8.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 2.6 MB
Tags CPython 3.10 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
4bd771aee7af72089f6f4701876bab6409ad613c81a48adc94ac74ce7a3009e1
BLAKE2b-256 checksum
How to use checksums
097f13d31b5caa1710daf57a2c35ef5408d852df2f9aaa94445cbe05414a5560
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

Release files / kymora-0.8.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL kymora-0.8.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 2.0 MB
Tags CPython 3.10 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
272e86a33836b96271f68a74e9d19d5c41ff33129ecdd6854b018af23880360a
BLAKE2b-256 checksum
How to use checksums
576cd92b312912ed29f3dca65e864d8ea687642bfb99e2686ed54483e1932a08
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

Release files / kymora-0.8.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL kymora-0.8.0-cp310-abi3-macosx_11_0_arm64.whl
Size 658.6 kB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
3f55279c09c39e6226dfc42577a68318a2097597eab29fc4da92e9e348790f4e
BLAKE2b-256 checksum
How to use checksums
2f7b1947f04986a4ef5d9cc62a2acbdfae8a4d6f9d9d61ce38749186001ee716
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

Release files / kymora-0.8.0-cp310-abi3-macosx_10_12_x86_64.whl

Download URL kymora-0.8.0-cp310-abi3-macosx_10_12_x86_64.whl
Size 788.2 kB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
17c80eaa03d416d2b2b0a33779a6501d74d6721c8b1d98075bf1da0833044d3d
BLAKE2b-256 checksum
How to use checksums
5f450331e2e1d3e585f8178b63f88ec1a151b5a7819c49b500826d34cfc14ceb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

Security for kymora 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for kymora-0.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.8.0 This release

6 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page