finmlkit.feature.core.utils module

General utility functions not exclusively for OHLCV bar data.

finmlkit.feature.core.utils.comp_burst_ratio(series: ndarray[tuple[int, ...], dtype[float64]], window: int) → ndarray[tuple[int, ...], dtype[float64]][source]

Compute the burst ratio of a time series. :param series: Time series data. :param window: Window size for the rolling calculation. :return: series of burst ratios (same size as input)

finmlkit.feature.core.utils.comp_lagged_returns(timestamps: ndarray[tuple[int, ...], dtype[int64]], close: ndarray[tuple[int, ...], dtype[float64]], return_window_sec: float, is_log: bool) → ndarray[tuple[int, ...], dtype[float64]][source]

Calculate the lagged returns on the given time window.

This function works for arbitrary time series data and does not require a fixed frequency. It computes the percentage change in price over a time lag window, aligned to timestamp precision.

Parameters:

  • timestamps – Timestamps series in nanoseconds.

  • close – Close price series.

  • return_window_sec – Time window in seconds for lagged return calculation. Set it to a small value (e.g. 1e-6) for 1 sample lag.

  • is_log – If True, compute log returns instead of simple returns.

Returns:

The lagged returns series as a float64 array.

Raises:

ValueError – If return_window_sec is less than or equal to zero.

Note

The function searches the closest earlier timestamp matching the lag time difference and computes percentage return as close[i] / close[lag_idx] - 1. Gaps and irregular timestamps are handled. Division by zero results in inf. If no valid lagged index is found, the return is NaN.

finmlkit.feature.core.utils.comp_zscore(x: ndarray[tuple[int, ...], dtype[float64]], window: int, ddof: int) → ndarray[tuple[int, ...], dtype[float64]][source]

Compute the z-score of a time series using a rolling window.

Parameters:

  • x – Input time series data.

  • window – Window size for the rolling calculation.

  • ddof – Delta degrees of freedom for standard deviation calculation.

Returns:

series of z-scores (same size as input)

finmlkit.feature.core.utils.pct_change(x: ndarray[tuple[int, ...], dtype[float64]], periods: int) → ndarray[tuple[int, ...], dtype[float64]][source]

Calculate the percentage change of a signal with a specified lag. :param x: the input signal :param periods: the lag period :return: the percentage change of the signal