flowbars 0.1.0__py3-none-any.whl

flowbars/bars/information/__init__.py

@@ -0,0 +1,41 @@
+"""Information-driven bar types: imbalance and run (tick, volume, dollar variants)."""
+
+from flowbars.bars.information.imbalance_dollar_bars import (
+    ImbalanceDollarBarConstructor,
+    compute_imbalance_dollar_bars,
+)
+from flowbars.bars.information.imbalance_tick_bars import (
+    ImbalanceTickBarConstructor,
+    compute_imbalance_tick_bars,
+)
+from flowbars.bars.information.imbalance_volume_bars import (
+    ImbalanceVolumeBarConstructor,
+    compute_imbalance_volume_bars,
+)
+from flowbars.bars.information.run_dollar_bars import (
+    RunDollarBarConstructor,
+    compute_run_dollar_bars,
+)
+from flowbars.bars.information.run_tick_bars import (
+    RunTickBarConstructor,
+    compute_run_tick_bars,
+)
+from flowbars.bars.information.run_volume_bars import (
+    RunVolumeBarConstructor,
+    compute_run_volume_bars,
+)
+
+__all__ = [
+    "ImbalanceDollarBarConstructor",
+    "ImbalanceTickBarConstructor",
+    "ImbalanceVolumeBarConstructor",
+    "RunDollarBarConstructor",
+    "RunTickBarConstructor",
+    "RunVolumeBarConstructor",
+    "compute_imbalance_dollar_bars",
+    "compute_imbalance_tick_bars",
+    "compute_imbalance_volume_bars",
+    "compute_run_dollar_bars",
+    "compute_run_tick_bars",
+    "compute_run_volume_bars",
+]

flowbars/bars/information/imbalance_dollar_bars.py

@@ -0,0 +1,200 @@
+"""Imbalance bars (dollar) — close when absolute signed dollar-imbalance crosses an adaptive threshold.
+
+Same two-component EWMA formula as tick-imbalance bars, but the imbalance
+is weighted by notional value (price × volume) instead of tick count.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import pandas as pd
+
+from flowbars.bars.accumulators import ImbalanceAccumulator
+from flowbars.bars.constructor import BaseBarConstructor
+from flowbars.bars.registry import BarRegistry
+from flowbars.calendars import TradingCalendar
+from flowbars.schema import SchemaMapping
+from flowbars.thresholds import EWMAThresholdEstimator
+
+
+class ImbalanceDollarBarConstructor(BaseBarConstructor):
+    """Bar constructor for dollar-imbalance bars.
+
+    A dollar-imbalance bar closes when the absolute signed dollar-imbalance
+    reaches or exceeds an **adaptive** threshold estimated by an EWMA.
+
+    Parameters
+    ----------
+    span : float, default 20.0
+        EWMA span for the two-component threshold formula.
+    halflife : float or None, default None
+        EWMA halflife.  Takes precedence over *span* when given.
+    initial_ewa_t : float, default 1.0
+        Initial seed for :math:`E[T]` (expected dollar value per bar).
+    initial_ewa_proportion : float, default 0.5
+        Initial seed for :math:`E[\\theta]` (expected imbalance proportion).
+    warmup_bars : int, default 0
+        Number of initial bars to discard while the EWMA converges.
+    calendar : TradingCalendar, optional
+    schema : SchemaMapping, optional
+    watermark : str or None, default ``"timestamp"``
+        Dedup key for idempotent resume (``"timestamp"``, a column name, or
+        ``None`` to disable).
+    strict_ordering : bool, default False
+        If True, raise ``TickDataError`` when a tick arrives with a timestamp
+        earlier than the previous tick's (out-of-order input).
+    backend : str, default ``"python"``
+        ``"python"`` or ``"numba"``.  The numba backend accelerates
+        :meth:`batch` only; ``update`` always uses Python.
+    stream_id : str, default ``"default"``
+    on_bar : callable or None
+    on_threshold_update : callable or None
+    """
+
+    def __init__(
+        self,
+        span: float = 20.0,
+        halflife: float | None = None,
+        initial_ewa_t: float = 1.0,
+        initial_ewa_proportion: float = 0.5,
+        warmup_bars: int = 0,
+        warmup_minutes: int | None = None,
+        calendar: TradingCalendar | None = None,
+        schema: SchemaMapping | None = None,
+        watermark: str | None = "timestamp",
+        stream_id: str = "default",
+        strict_ordering: bool = False,
+        backend: Literal["python", "numba"] = "python",
+        on_bar: Any = None,
+        on_threshold_update: Any = None,
+        multiplier: float = 1.0,
+        volume_type: str = "base",
+    ) -> None:
+        accumulator = ImbalanceAccumulator(bar_type="imbalance_dollar", metric="dollar")
+        estimator = EWMAThresholdEstimator(
+            bar_family="imbalance",
+            span=span,
+            halflife=halflife,
+            initial_ewa_t=initial_ewa_t,
+            initial_ewa_proportion=initial_ewa_proportion,
+        )
+
+        super().__init__(
+            accumulator=accumulator,
+            threshold_estimator=estimator,
+            calendar=calendar,
+            schema=schema,
+            watermark=watermark,
+            stream_id=stream_id,
+            strict_ordering=strict_ordering,
+            warmup_bars=warmup_bars,
+            warmup_minutes=warmup_minutes,
+            backend=backend,
+            on_bar=on_bar,
+            on_threshold_update=on_threshold_update,
+            multiplier=multiplier,
+            volume_type=volume_type,
+        )
+
+    @classmethod
+    def from_state(  # type: ignore[override]
+        cls,
+        state: dict[str, Any],
+        calendar: TradingCalendar | None = None,
+        schema: SchemaMapping | None = None,
+        *,
+        verify_identity: bool = True,
+    ) -> ImbalanceDollarBarConstructor:
+        """Reconstruct an ``ImbalanceDollarBarConstructor`` from a saved state dict."""
+        acc_state = state["accumulator"]
+        acc = ImbalanceAccumulator(
+            bar_type=state["bar_type"],
+            metric=acc_state["metric"],
+        )
+        est = EWMAThresholdEstimator.from_state(state["threshold_estimator"])
+        inst: ImbalanceDollarBarConstructor = super().from_state(
+            state, acc, est, calendar, schema, verify_identity=verify_identity
+        )  # type: ignore[assignment]
+        return inst
+
+
+def compute_imbalance_dollar_bars(
+    ticks_df: pd.DataFrame,
+    span: float = 20.0,
+    halflife: float | None = None,
+    initial_ewa_t: float = 1.0,
+    initial_ewa_proportion: float = 0.5,
+    warmup_bars: int = 0,
+    warmup_minutes: int | None = None,
+    schema: SchemaMapping | None = None,
+    watermark: str | None = "timestamp",
+    strict_ordering: bool = False,
+    calendar: TradingCalendar | None = None,
+    *,
+    backend: Literal["python", "numba"] = "python",
+    stream_id: str = "default",
+    on_bar: Any = None,
+    on_threshold_update: Any = None,
+    multiplier: float = 1.0,
+    volume_type: str = "base",
+) -> pd.DataFrame:
+    """Build dollar-imbalance bars from a DataFrame of ticks.
+
+    Parameters
+    ----------
+    ticks_df : pd.DataFrame
+        Tick-level data with user-mapped columns.
+    span : float, default 20.0
+        EWMA span for the adaptive threshold.
+    halflife : float or None, default None
+        EWMA halflife (takes precedence over *span*).
+    initial_ewa_t : float, default 1.0
+        Initial seed for expected dollar value per bar.
+    initial_ewa_proportion : float, default 0.5
+        Initial seed for expected imbalance proportion.
+    warmup_bars : int, default 0
+        Number of initial bars to discard.
+    schema : SchemaMapping, optional
+    watermark : str or None, default ``"timestamp"``
+        Dedup key for idempotent resume (``"timestamp"``, a column name, or
+        ``None`` to disable).
+    strict_ordering : bool, default False
+        If True, raise ``TickDataError`` when a tick arrives with a timestamp
+        earlier than the previous tick's (out-of-order input).
+    calendar : TradingCalendar, optional
+    backend : str, default ``"python"``
+        ``"python"`` or ``"numba"``.
+    stream_id : str, default ``"default"``
+    on_bar : callable or None
+    on_threshold_update : callable or None
+
+    Returns
+    -------
+    pd.DataFrame
+        Completed bars as a DataFrame.
+    """
+    ctor = ImbalanceDollarBarConstructor(
+        span=span,
+        halflife=halflife,
+        initial_ewa_t=initial_ewa_t,
+        initial_ewa_proportion=initial_ewa_proportion,
+        warmup_bars=warmup_bars,
+        warmup_minutes=warmup_minutes,
+        calendar=calendar,
+        schema=schema,
+        watermark=watermark,
+        strict_ordering=strict_ordering,
+        backend=backend,
+        stream_id=stream_id,
+        on_bar=on_bar,
+        on_threshold_update=on_threshold_update,
+        multiplier=multiplier,
+        volume_type=volume_type,
+    )
+    return ctor.batch(ticks_df)
+
+
+BarRegistry.register(
+    "imbalance_dollar", ImbalanceDollarBarConstructor, batch_fn=compute_imbalance_dollar_bars
+)

flowbars/bars/information/imbalance_tick_bars.py

@@ -0,0 +1,206 @@
+"""Imbalance bars (tick) — close when absolute signed tick-imbalance crosses an adaptive threshold.
+
+Uses the two-component EWMA formula from AFML §2.4:
+
+.. math::
+
+    T_n = E[T]_n \\times |E[\\theta]_n|
+
+where :math:`E[T]_n` is the expected tick count per bar and
+:math:`E[\\theta]_n` is the expected signed-imbalance proportion.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import pandas as pd
+
+from flowbars.bars.accumulators import ImbalanceAccumulator
+from flowbars.bars.constructor import BaseBarConstructor
+from flowbars.bars.registry import BarRegistry
+from flowbars.calendars import TradingCalendar
+from flowbars.schema import SchemaMapping
+from flowbars.thresholds import EWMAThresholdEstimator
+
+
+class ImbalanceTickBarConstructor(BaseBarConstructor):
+    """Bar constructor for tick-imbalance bars.
+
+    A tick-imbalance bar closes when the absolute signed tick-imbalance
+    reaches or exceeds an **adaptive** threshold estimated by an EWMA.
+
+    Parameters
+    ----------
+    span : float, default 20.0
+        EWMA span for the two-component threshold formula.
+    halflife : float or None, default None
+        EWMA halflife.  Takes precedence over *span* when given.
+    initial_ewa_t : float, default 1.0
+        Initial seed for :math:`E[T]` (expected tick count per bar).
+    initial_ewa_proportion : float, default 0.5
+        Initial seed for :math:`E[\\theta]` (expected imbalance proportion).
+    warmup_bars : int, default 0
+        Number of initial bars to discard while the EWMA converges.
+    calendar : TradingCalendar, optional
+    schema : SchemaMapping, optional
+    watermark : str or None, default ``"timestamp"``
+        Dedup key for idempotent resume (``"timestamp"``, a column name, or
+        ``None`` to disable).
+    strict_ordering : bool, default False
+        If True, raise ``TickDataError`` when a tick arrives with a timestamp
+        earlier than the previous tick's (out-of-order input).
+    backend : str, default ``"python"``
+        ``"python"`` or ``"numba"``.  The numba backend accelerates
+        :meth:`batch` only; ``update`` always uses Python.
+    stream_id : str, default ``"default"``
+    on_bar : callable or None
+    on_threshold_update : callable or None
+    """
+
+    def __init__(
+        self,
+        span: float = 20.0,
+        halflife: float | None = None,
+        initial_ewa_t: float = 1.0,
+        initial_ewa_proportion: float = 0.5,
+        warmup_bars: int = 0,
+        warmup_minutes: int | None = None,
+        calendar: TradingCalendar | None = None,
+        schema: SchemaMapping | None = None,
+        watermark: str | None = "timestamp",
+        stream_id: str = "default",
+        strict_ordering: bool = False,
+        backend: Literal["python", "numba"] = "python",
+        on_bar: Any = None,
+        on_threshold_update: Any = None,
+        multiplier: float = 1.0,
+        volume_type: str = "base",
+    ) -> None:
+        accumulator = ImbalanceAccumulator(bar_type="imbalance_tick", metric="tick")
+        estimator = EWMAThresholdEstimator(
+            bar_family="imbalance",
+            span=span,
+            halflife=halflife,
+            initial_ewa_t=initial_ewa_t,
+            initial_ewa_proportion=initial_ewa_proportion,
+        )
+
+        super().__init__(
+            accumulator=accumulator,
+            threshold_estimator=estimator,
+            calendar=calendar,
+            schema=schema,
+            watermark=watermark,
+            stream_id=stream_id,
+            strict_ordering=strict_ordering,
+            warmup_bars=warmup_bars,
+            warmup_minutes=warmup_minutes,
+            backend=backend,
+            on_bar=on_bar,
+            on_threshold_update=on_threshold_update,
+            multiplier=multiplier,
+            volume_type=volume_type,
+        )
+
+    @classmethod
+    def from_state(  # type: ignore[override]
+        cls,
+        state: dict[str, Any],
+        calendar: TradingCalendar | None = None,
+        schema: SchemaMapping | None = None,
+        *,
+        verify_identity: bool = True,
+    ) -> ImbalanceTickBarConstructor:
+        """Reconstruct an ``ImbalanceTickBarConstructor`` from a saved state dict."""
+        acc_state = state["accumulator"]
+        acc = ImbalanceAccumulator(
+            bar_type=state["bar_type"],
+            metric=acc_state["metric"],
+        )
+        est = EWMAThresholdEstimator.from_state(state["threshold_estimator"])
+        inst: ImbalanceTickBarConstructor = super().from_state(
+            state, acc, est, calendar, schema, verify_identity=verify_identity
+        )  # type: ignore[assignment]
+        return inst
+
+
+def compute_imbalance_tick_bars(
+    ticks_df: pd.DataFrame,
+    span: float = 20.0,
+    halflife: float | None = None,
+    initial_ewa_t: float = 1.0,
+    initial_ewa_proportion: float = 0.5,
+    warmup_bars: int = 0,
+    warmup_minutes: int | None = None,
+    schema: SchemaMapping | None = None,
+    watermark: str | None = "timestamp",
+    strict_ordering: bool = False,
+    calendar: TradingCalendar | None = None,
+    *,
+    backend: Literal["python", "numba"] = "python",
+    stream_id: str = "default",
+    on_bar: Any = None,
+    on_threshold_update: Any = None,
+    multiplier: float = 1.0,
+    volume_type: str = "base",
+) -> pd.DataFrame:
+    """Build tick-imbalance bars from a DataFrame of ticks.
+
+    Parameters
+    ----------
+    ticks_df : pd.DataFrame
+        Tick-level data with user-mapped columns.
+    span : float, default 20.0
+        EWMA span for the adaptive threshold.
+    halflife : float or None, default None
+        EWMA halflife (takes precedence over *span*).
+    initial_ewa_t : float, default 1.0
+        Initial seed for expected tick count per bar.
+    initial_ewa_proportion : float, default 0.5
+        Initial seed for expected imbalance proportion.
+    warmup_bars : int, default 0
+        Number of initial bars to discard.
+    schema : SchemaMapping, optional
+    watermark : str or None, default ``"timestamp"``
+        Dedup key for idempotent resume (``"timestamp"``, a column name, or
+        ``None`` to disable).
+    strict_ordering : bool, default False
+        If True, raise ``TickDataError`` when a tick arrives with a timestamp
+        earlier than the previous tick's (out-of-order input).
+    calendar : TradingCalendar, optional
+    backend : str, default ``"python"``
+        ``"python"`` or ``"numba"``.
+    stream_id : str, default ``"default"``
+    on_bar : callable or None
+    on_threshold_update : callable or None
+
+    Returns
+    -------
+    pd.DataFrame
+        Completed bars as a DataFrame.
+    """
+    ctor = ImbalanceTickBarConstructor(
+        span=span,
+        halflife=halflife,
+        initial_ewa_t=initial_ewa_t,
+        initial_ewa_proportion=initial_ewa_proportion,
+        warmup_bars=warmup_bars,
+        warmup_minutes=warmup_minutes,
+        calendar=calendar,
+        schema=schema,
+        watermark=watermark,
+        strict_ordering=strict_ordering,
+        backend=backend,
+        stream_id=stream_id,
+        on_bar=on_bar,
+        on_threshold_update=on_threshold_update,
+        multiplier=multiplier,
+        volume_type=volume_type,
+    )
+    return ctor.batch(ticks_df)
+
+
+BarRegistry.register(
+    "imbalance_tick", ImbalanceTickBarConstructor, batch_fn=compute_imbalance_tick_bars
+)

flowbars/bars/information/imbalance_volume_bars.py

@@ -0,0 +1,200 @@
+"""Imbalance bars (volume) — close when absolute signed volume-imbalance crosses an adaptive threshold.
+
+Same two-component EWMA formula as tick-imbalance bars, but the imbalance
+is weighted by trade volume instead of tick count.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import pandas as pd
+
+from flowbars.bars.accumulators import ImbalanceAccumulator
+from flowbars.bars.constructor import BaseBarConstructor
+from flowbars.bars.registry import BarRegistry
+from flowbars.calendars import TradingCalendar
+from flowbars.schema import SchemaMapping
+from flowbars.thresholds import EWMAThresholdEstimator
+
+
+class ImbalanceVolumeBarConstructor(BaseBarConstructor):
+    """Bar constructor for volume-imbalance bars.
+
+    A volume-imbalance bar closes when the absolute signed volume-imbalance
+    reaches or exceeds an **adaptive** threshold estimated by an EWMA.
+
+    Parameters
+    ----------
+    span : float, default 20.0
+        EWMA span for the two-component threshold formula.
+    halflife : float or None, default None
+        EWMA halflife.  Takes precedence over *span* when given.
+    initial_ewa_t : float, default 1.0
+        Initial seed for :math:`E[T]` (expected volume per bar).
+    initial_ewa_proportion : float, default 0.5
+        Initial seed for :math:`E[\\theta]` (expected imbalance proportion).
+    warmup_bars : int, default 0
+        Number of initial bars to discard while the EWMA converges.
+    calendar : TradingCalendar, optional
+    schema : SchemaMapping, optional
+    watermark : str or None, default ``"timestamp"``
+        Dedup key for idempotent resume (``"timestamp"``, a column name, or
+        ``None`` to disable).
+    strict_ordering : bool, default False
+        If True, raise ``TickDataError`` when a tick arrives with a timestamp
+        earlier than the previous tick's (out-of-order input).
+    backend : str, default ``"python"``
+        ``"python"`` or ``"numba"``.  The numba backend accelerates
+        :meth:`batch` only; ``update`` always uses Python.
+    stream_id : str, default ``"default"``
+    on_bar : callable or None
+    on_threshold_update : callable or None
+    """
+
+    def __init__(
+        self,
+        span: float = 20.0,
+        halflife: float | None = None,
+        initial_ewa_t: float = 1.0,
+        initial_ewa_proportion: float = 0.5,
+        warmup_bars: int = 0,
+        warmup_minutes: int | None = None,
+        calendar: TradingCalendar | None = None,
+        schema: SchemaMapping | None = None,
+        watermark: str | None = "timestamp",
+        stream_id: str = "default",
+        strict_ordering: bool = False,
+        backend: Literal["python", "numba"] = "python",
+        on_bar: Any = None,
+        on_threshold_update: Any = None,
+        multiplier: float = 1.0,
+        volume_type: str = "base",
+    ) -> None:
+        accumulator = ImbalanceAccumulator(bar_type="imbalance_volume", metric="volume")
+        estimator = EWMAThresholdEstimator(
+            bar_family="imbalance",
+            span=span,
+            halflife=halflife,
+            initial_ewa_t=initial_ewa_t,
+            initial_ewa_proportion=initial_ewa_proportion,
+        )
+
+        super().__init__(
+            accumulator=accumulator,
+            threshold_estimator=estimator,
+            calendar=calendar,
+            schema=schema,
+            watermark=watermark,
+            stream_id=stream_id,
+            strict_ordering=strict_ordering,
+            warmup_bars=warmup_bars,
+            warmup_minutes=warmup_minutes,
+            backend=backend,
+            on_bar=on_bar,
+            on_threshold_update=on_threshold_update,
+            multiplier=multiplier,
+            volume_type=volume_type,
+        )
+
+    @classmethod
+    def from_state(  # type: ignore[override]
+        cls,
+        state: dict[str, Any],
+        calendar: TradingCalendar | None = None,
+        schema: SchemaMapping | None = None,
+        *,
+        verify_identity: bool = True,
+    ) -> ImbalanceVolumeBarConstructor:
+        """Reconstruct an ``ImbalanceVolumeBarConstructor`` from a saved state dict."""
+        acc_state = state["accumulator"]
+        acc = ImbalanceAccumulator(
+            bar_type=state["bar_type"],
+            metric=acc_state["metric"],
+        )
+        est = EWMAThresholdEstimator.from_state(state["threshold_estimator"])
+        inst: ImbalanceVolumeBarConstructor = super().from_state(
+            state, acc, est, calendar, schema, verify_identity=verify_identity
+        )  # type: ignore[assignment]
+        return inst
+
+
+def compute_imbalance_volume_bars(
+    ticks_df: pd.DataFrame,
+    span: float = 20.0,
+    halflife: float | None = None,
+    initial_ewa_t: float = 1.0,
+    initial_ewa_proportion: float = 0.5,
+    warmup_bars: int = 0,
+    warmup_minutes: int | None = None,
+    schema: SchemaMapping | None = None,
+    watermark: str | None = "timestamp",
+    strict_ordering: bool = False,
+    calendar: TradingCalendar | None = None,
+    *,
+    backend: Literal["python", "numba"] = "python",
+    stream_id: str = "default",
+    on_bar: Any = None,
+    on_threshold_update: Any = None,
+    multiplier: float = 1.0,
+    volume_type: str = "base",
+) -> pd.DataFrame:
+    """Build volume-imbalance bars from a DataFrame of ticks.
+
+    Parameters
+    ----------
+    ticks_df : pd.DataFrame
+        Tick-level data with user-mapped columns.
+    span : float, default 20.0
+        EWMA span for the adaptive threshold.
+    halflife : float or None, default None
+        EWMA halflife (takes precedence over *span*).
+    initial_ewa_t : float, default 1.0
+        Initial seed for expected volume per bar.
+    initial_ewa_proportion : float, default 0.5
+        Initial seed for expected imbalance proportion.
+    warmup_bars : int, default 0
+        Number of initial bars to discard.
+    schema : SchemaMapping, optional
+    watermark : str or None, default ``"timestamp"``
+        Dedup key for idempotent resume (``"timestamp"``, a column name, or
+        ``None`` to disable).
+    strict_ordering : bool, default False
+        If True, raise ``TickDataError`` when a tick arrives with a timestamp
+        earlier than the previous tick's (out-of-order input).
+    calendar : TradingCalendar, optional
+    backend : str, default ``"python"``
+        ``"python"`` or ``"numba"``.
+    stream_id : str, default ``"default"``
+    on_bar : callable or None
+    on_threshold_update : callable or None
+
+    Returns
+    -------
+    pd.DataFrame
+        Completed bars as a DataFrame.
+    """
+    ctor = ImbalanceVolumeBarConstructor(
+        span=span,
+        halflife=halflife,
+        initial_ewa_t=initial_ewa_t,
+        initial_ewa_proportion=initial_ewa_proportion,
+        warmup_bars=warmup_bars,
+        warmup_minutes=warmup_minutes,
+        calendar=calendar,
+        schema=schema,
+        watermark=watermark,
+        strict_ordering=strict_ordering,
+        backend=backend,
+        stream_id=stream_id,
+        on_bar=on_bar,
+        on_threshold_update=on_threshold_update,
+        multiplier=multiplier,
+        volume_type=volume_type,
+    )
+    return ctor.batch(ticks_df)
+
+
+BarRegistry.register(
+    "imbalance_volume", ImbalanceVolumeBarConstructor, batch_fn=compute_imbalance_volume_bars
+)