API Reference¶
Complete Python API specification for kymora v0.8.0.
The package ships full type annotations and a py.typed marker for mypy and language servers.
Batch Extraction¶
extract_features¶
```python skip extract_features( X: np.ndarray | Sequence[np.ndarray], profile: str | None = None, features: Sequence[str] | None = None, n_jobs: int | None = None, out: np.ndarray | None = None, views: Sequence[str] | None = None, precision: str | None = None, out_dtype: str | None = None, nan_policy: str | None = None, contiguous: str | None = None, ) -> np.ndarray
Extract features for every series in a batch.
**Parameters**
- `X` — 2D C-contiguous `float64` or `float32` array of shape `(n_series, length)`, or a sequence of 1D C-contiguous arrays with variable lengths. See [Numerics](numerics.md) for layout rules.
- `profile` — Execution profile: `"minimal"` (10 features), `"core33"` (default 33 features), `"extended"`, or `"full"`.
- `features` — Explicit list of feature names to extract, overriding profile selection.
- `n_jobs` — Worker-thread count for this call. `None` uses the shared global pool (all threads); scaling stops near the physical core count (see [Performance](performance.md)).
- `out` — Optional pre-allocated C-contiguous `float64` array of shape `(n_series, n_features)` to receive results in place without allocation.
- `views` — Optional sequence of time-series transform views to compute: `"raw"`, `"diff"`, `"diff2"`, `"detrend"`, `"znorm"`, `"abs"`, `"logret"`, `"rank"`. Features invariant to transforms are automatically pruned. Requires `float64` input.
- `precision` — Validated but informational: `"float64"`/`"float32"` accepted; accumulation is always `float64` and the input dtype governs the read path.
- `out_dtype` — `"float64"` (default) or `"float32"` (casts on write).
- `nan_policy` — `"propagate"` (default) or `"raise"`; see [Numerics](numerics.md).
- `contiguous` — `"error"` (default, reject non-C input) or `"copy"` (one explicit copy plus a `UserWarning`).
**Returns**
A 2D array of shape `(n_series, n_features)`; `float32` when `out_dtype="float32"`, otherwise `float64`.
```python
import numpy as np
import kymora
X = np.random.default_rng(0).standard_normal((1000, 500))
# Default Core33 batch extraction
feats = kymora.extract_features(X)
# Multi-view extraction across raw, differences, and z-normalization
feats_views = kymora.extract_features(X, views=["raw", "diff", "znorm"])
extract_features_df¶
```python skip extract_features_df( X: np.ndarray | Sequence[np.ndarray], profile: str | None = None, features: Sequence[str] | None = None, n_jobs: int | None = None, out: np.ndarray | None = None, views: Sequence[str] | None = None, ) -> pd.DataFrame
Same computation as `extract_features`, returned as a labeled `pandas.DataFrame`. Columns match `feature_names(...)`.
Requires `pandas` (`pip install "kymora[pandas]"`).
---
### sliding_features
```python skip
sliding_features(
x: np.ndarray,
window: int,
stride: int = 1,
profile: str | None = None,
features: Sequence[str] | None = None,
n_jobs: int | None = None,
out: np.ndarray | None = None,
nan_policy: str | None = None,
contiguous: str | None = None,
) -> np.ndarray
Extracts rolling-window feature matrices across a single long 1D series without copying window data.
Parameters
x— 1D C-contiguousfloat64array.window— Window length in samples (1 <= window <= len(x)).stride— Step between consecutive windows (>= 1, defaults to 1).profile,features,n_jobs,out,nan_policy,contiguous— as inextract_features.
Returns
A 2D float64 array of shape (n_windows, 33) where n_windows = (len(x) - window) // stride + 1.
Multichannel & Cross-Channel Extraction¶
extract_features_mc¶
```python skip extract_features_mc( X: np.ndarray | Sequence[np.ndarray], profile: str | None = None, features: Sequence[str] | None = None, cross: bool = True, max_pairs: int = 8, n_jobs: int | None = None, views: Sequence[str] | None = None, nan_policy: str | None = None, contiguous: str | None = None, ) -> np.ndarray
Extract per-channel features and cross-channel interaction metrics from multichannel time-series data. See [Multichannel](multivariate.md).
**Parameters**
- `X` — 3D C-contiguous `float64` array of shape `(n_samples, n_channels, length)`, or a list of 2D `(n_channels, length_i)` arrays for ragged lengths (channel count must agree).
- `profile` — Profile applied to each channel.
- `features` — Specific feature subset applied to each channel.
- `cross` — When `True`, computes cross-channel interaction metrics (pairwise cross-correlation peaks, lag offsets, cross-covariance, Pearson correlation, and global spectral coherence / eigenvalue spread).
- `max_pairs` — Maximum number of channel pairs evaluated for pairwise metrics (defaults to 8).
- `n_jobs` — Thread count.
- `views` — Optional multi-view transforms applied to each channel.
**Returns**
A 2D `float64` array of shape `(n_samples, total_features)`.
---
### extract_features_mc_df
```python skip
extract_features_mc_df(
X: np.ndarray | Sequence[np.ndarray],
profile: str | None = None,
features: Sequence[str] | None = None,
cross: bool = True,
max_pairs: int = 8,
n_jobs: int | None = None,
views: Sequence[str] | None = None,
) -> pd.DataFrame
Same computation as extract_features_mc, returned as a labeled pandas.DataFrame. Columns match feature_names_mc(...).
Streaming Extractor¶
StreamingExtractor¶
```python skip class StreamingExtractor: def init(self, window_size: int, anchor_interval: int | None = None, nan_policy: str | None = None) -> None: ... def push(self, value: float) -> bool: ... def compute(self, kind: str = "fast") -> np.ndarray: ... def reset(self) -> None: ... def set_anchor_interval(self, anchor_interval: int) -> None: ... @property def window_size(self) -> int: ... @property def anchor_interval(self) -> int: ... @property def is_full(self) -> bool: ... @staticmethod def fast_feature_names() -> list[str]: ...
Single-stream sliding-window extractor maintaining an internal circular buffer and amortized-$O(1)$ incremental state updates.
- `push(value)` returns `True` once the circular buffer has reached `window_size`. `window_size >= 1`.
- `compute("fast")` derives the 12 streaming features from accumulators in $O(1)$: no window scan, no allocation, no sorting, no FFT.
- `compute("all")` evaluates all 33 Core features over the current window ($O(W)$-plus, exact batch pipeline).
- `anchor_interval` sets the periodic exact re-anchor cadence in pushes (default 4096); a drift guard re-anchors earlier when needed. See [Streaming guide](streaming.md) for the full complexity and accuracy contract.
---
### MultiStreamExtractor
```python skip
class MultiStreamExtractor:
def __init__(self, n_streams: int, window_size: int) -> None: ...
def push_many(self, values: np.ndarray, contiguous: str | None = None) -> bool: ...
def compute(self, streams: list[int] | None = None, kind: str = "all") -> np.ndarray: ...
def reset(self, stream_idx: int | None = None) -> None: ...
@property
def n_streams(self) -> int: ...
@property
def window_size(self) -> int: ...
@property
def is_full(self) -> bool: ...
@property
def count(self) -> int: ...
@staticmethod
def fast_feature_names() -> list[str]: ...
Fleet streaming engine for processing thousands of time-series streams concurrently with contiguous memory layout and cache locality.
push_many(values)ingests a vector of values for all active streams simultaneously.compute(streams=None, kind="fast"|"all")extracts features across designated streams in parallel.
Supervised Feature Selection¶
select_features¶
```python skip select_features( F: np.ndarray | pd.DataFrame, y: Sequence[Any] | np.ndarray, task: str = "auto", fdr: float = 0.05, max_corr: float = 0.90, ) -> tuple[list[int], pd.DataFrame]
Select significant, non-redundant time-series features using hypothesis testing, False Discovery Rate (FDR) control, and correlation-threshold clustering.
**Parameters**
- `F` — Feature matrix of shape `(n_samples, n_features)`.
- `y` — Target labels or values of shape `(n_samples,)`.
- `task` — Task type: `"auto"`, `"classification"`, or `"regression"`.
- `fdr` — Benjamini-Hochberg FDR significance threshold (defaults to 0.05).
- `max_corr` — Pairwise correlation clustering threshold for redundancy pruning (defaults to 0.90).
**Returns**
`(selected_indices, report)` where `selected_indices` contains column indices of the selected features, and `report` provides a tabular summary of statistics, p-values, adjusted p-values, and cluster assignments.
---
### KymoraSelector
```python skip
class KymoraSelector:
def __init__(self, task: str = "auto", fdr: float = 0.05, max_corr: float = 0.90) -> None: ...
def fit(self, X: np.ndarray | pd.DataFrame, y: Sequence[Any] | np.ndarray) -> KymoraSelector: ...
def transform(self, X: np.ndarray | pd.DataFrame) -> np.ndarray | pd.DataFrame: ...
def fit_transform(self, X: np.ndarray | pd.DataFrame, y: Sequence[Any] | np.ndarray) -> np.ndarray | pd.DataFrame: ...
def get_support(self, indices: bool = False) -> np.ndarray: ...
Scikit-learn compatible transformer implementing FDR-controlled supervised feature selection for direct inclusion in ML pipelines.
KymoraTransformer¶
```python skip from kymora.sklearn import KymoraTransformer # pip install "kymora[sklearn]"
KymoraTransformer( profile: str = "core33", features: Sequence[str] | None = None, views: Sequence[str] | None = None, n_jobs: int | None = None, nan_policy: str | None = None, output_dtype: str | None = None, )
Scikit-learn compatible panel transformer: `(n_series, length)` in,
`(n_series, n_features)` out. Stateless `fit`, `get_feature_names_out`,
`set_output(transform="pandas" | "polars")`, clone- and pickle-safe,
passing the full `parametrize_with_checks` suite. See
[Quickstart](quickstart.md) for a pipeline example.
---
## Metadata & Introspection
### feature_names
```python skip
feature_names(
profile: str | None = None,
features: Sequence[str] | None = None,
views: Sequence[str] | None = None,
) -> list[str]
Returns output feature names in exact column order. Features 0..32 are frozen across all minor releases.
feature_names_mc¶
```python skip feature_names_mc( n_channels: int, profile: str | None = None, features: Sequence[str] | None = None, cross: bool = True, max_pairs: int = 8, views: Sequence[str] | None = None, ) -> list[str]
Returns output column names for multichannel extraction including channel prefixes and cross-channel metric names.
---
### list_profiles
```python skip
list_profiles() -> dict[str, int]
Returns available feature profile names mapped to their respective feature counts.
describe_feature¶
```python skip describe_feature(name: str) -> dict[str, str]
Returns metadata for a given feature name: cost class, needs, registered
aliases, plus core33 documentation fields (`definition`, `min_length`,
`nan_when`) — the same source `tools/gen_feature_docs.py` builds
[Feature reference](features.md) from.
---
## Hardware Auto-Tuning
### tune
```python skip
tune(
shapes: Sequence[tuple[int, int]] = ((1000, 500),),
budget_s: float = 10.0,
) -> dict[str, Any]
Microbenchmarks execution variants on current hardware and caches optimal execution parameters locally. Pool selection is recorded for forward compatibility.
Threading & Runtime Controls¶
- Scheduling is Rayon:
n_jobs=Noneuses the shared global pool (honorsRAYON_NUM_THREADS=N); an explicitn_jobsselects a cached per-count pool (no per-call construction cost since 0.8.0). - Expect scaling to stop near the physical core count (P-cores on hybrid
laptops); see Performance and
docs/internal/thread_scaling.mdfor the analysis. KYMORA_POOL(spin/rayon) is currently read by nothing — the persistent spin-pool prototype was removed from main toexperiment/spin-pool(seedocs/ROADMAP.md; revival is gated on docs/internal/arch.md Z6). Treat anytune()pool recommendation as provisional until the backend lands.