finmlkit.bar.utils module

finmlkit.bar.utils.check_timestamps_order(timestamps: ndarray[tuple[int, ...], dtype[int64]]) → bool

Are timestamps sorted in ascending order? :param timestamps: nanosec timestamps array :return: True if timestamps are sorted in ascending order else False

finmlkit.bar.utils.comp_price_tick_size(prices: ndarray[tuple[int, ...], dtype[float64]]) → float

Estimate the smallest price increment (tick size) based on trade prices.

Parameters:

prices – Array of trade prices.

Returns:

Estimated price tick size. Returns 0.0 if undeterminable.

Raises:

ValueError – If input array is empty.

finmlkit.bar.utils.comp_price_tick_size_old(prices: ndarray[tuple[int, ...], dtype[float64]]) → float

Legacy method to estimate tick size using median price differences.

Parameters:

prices – Array of trade prices.

Returns:

Rounded tick size estimate.

Raises:

ValueError – If input array is empty.

finmlkit.bar.utils.comp_trade_side(price: float, prev_price: float, prev_tick: int) → Literal[-1, 1]

Classify a trade as buy or sell using the tick rule from AFML.

Parameters:

• price – Current trade price.

• prev_price – Previous trade price.

• prev_tick – Previous tick direction.

Returns:

1 for an upward move (buy), -1 for a downward move (sell).

finmlkit.bar.utils.comp_trade_side_vector(prices: ndarray[tuple[int, ...], dtype[float64]]) → ndarray[tuple[int, ...], dtype[int8]]

Compute tick rule-based trade sides for a sequence of prices.

Parameters:

prices – Sequence of trade prices.

Returns:

Sequence of trade sides (1 for buy, -1 for sell).

finmlkit.bar.utils.fast_sort_trades(timestamps: ndarray[tuple[int, ...], dtype[int64]], prices: ndarray[tuple[int, ...], dtype[float64]], amounts: ndarray[tuple[int, ...], dtype[float32]], is_buyer_maker: ndarray[tuple[int, ...], dtype[bool]] | None = None) → tuple[ndarray[tuple[int, ...], dtype[int64]], ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float32]], ndarray[tuple[int, ...], dtype[bool]] | None]

Fast sorting of trade data by timestamps using Numba. For very large datasets, this is much faster than pandas sorting.

Parameters:

• timestamps – nanosec timestamp array

• prices – raw trades price array

• amounts – raw trades amount array

• is_buyer_maker – Optional array for trade side

Returns:

tuple of sorted (timestamps, prices, amounts, is_buyer_maker)

finmlkit.bar.utils.footprint_to_dataframe(bar_timestamps, price_levels, buy_volumes, sell_volumes, buy_ticks, sell_ticks, buy_imbalance, sell_imbalance, price_tick)

Convert footprint bar data into a structured pandas DataFrame.

Parameters:

• bar_timestamps – Bar timestamps as nanosecond integers.

• price_levels – List of price levels per bar (ascending order).

• buy_volumes – List of buy volumes per level.

• sell_volumes – List of sell volumes per level.

• buy_ticks – List of buy ticks per level.

• sell_ticks – List of sell ticks per level.

• buy_imbalance – List of boolean arrays for buy imbalances.

• sell_imbalance – List of boolean arrays for sell imbalances.

• price_tick – Price tick size to scale levels.

Returns:

DataFrame indexed by bar ID and timestamp with footprint metrics.

finmlkit.bar.utils.median3(a, b, c)

Median 3 filter. Find the median of three numbers. :param a: first number :param b: second number :param c: third number :return: median of a, b, c

finmlkit.bar.utils.merge_split_trades(timestamps: ndarray[tuple[int, ...], dtype[int64]], prices: ndarray[tuple[int, ...], dtype[float64]], amounts: ndarray[tuple[int, ...], dtype[float32]], is_buyer_maker: ndarray[tuple[int, ...], dtype[bool]] | None) → tuple[ndarray[tuple[int, ...], dtype[int64]], ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float32]], ndarray[tuple[int, ...], dtype[int8]]]

Merge split transaction trades. Inputs must already be ordered by (timestamp, price, side).

Parameters:

• timestamps – nanosec timestamp array

• prices – raw trades price array

• amounts – raw trades amount array

• is_buyer_maker – Optional array to compute side

Returns:

a tuple of arrays containing: 1. the merged trades timestamps 2. the merged trades price 3. the merged trades amount 4. the merged trades side if is_buyer_maker provided (else empty list)