flowbars 0.1.0__py3-none-any.whl

flowbars/bars/minute/__init__.py

@@ -0,0 +1,99 @@
+"""Minute-OHLCV → bars path.
+
+Builds non-time bars from minute OHLCV candles instead of raw ticks.  Same
+output bar schema and the same orchestration engine as the tick path (batch,
+streaming ``update()``, state save/resume, callbacks, warmup, watermark dedup,
+strict ordering, calendars), plus a numba batch backend.
+
+Design decisions are specified in the repo's ``SPEC.md`` under
+"Minute-OHLCV → bars path — design".  Key points:
+
+* **Direct OHLCV accumulation** (not pseudo-tick resampling).
+* **Whole-minute attribution** — the crossing minute is consumed whole; only
+  the scalar metric excess rolls into the next bar (renko has no overflow).
+* **Minute tick rule** for signs — ``sign(close_i − close_{i−1})``, first
+  minute ``NaN`` (reused from :func:`flowbars.tick_rule.resolve_tick_signs`).
+* ``num_ticks`` counts **minutes**; ``dollar_value``/``vwap`` use
+  ``close × volume`` as the notional proxy.
+
+Bar types: volume, dollar, imbalance/run (volume, dollar), plus the
+minute-only volatility, relative-range, renko-displacement, and hybrid types.
+"""
+
+from __future__ import annotations
+
+from flowbars.bars.minute.accumulators import (
+    MinuteDollarAccumulator,
+    MinuteHybridAccumulator,
+    MinuteImbalanceAccumulator,
+    MinuteRangeAccumulator,
+    MinuteRenkoAccumulator,
+    MinuteRunAccumulator,
+    MinuteVolatilityAccumulator,
+    MinuteVolumeAccumulator,
+)
+from flowbars.bars.minute.engine import BaseMinuteBarConstructor
+
+# Registration side-effects: importing these modules registers every type.
+from flowbars.bars.minute.information import (
+    MinuteImbalanceDollarBarConstructor,
+    MinuteImbalanceVolumeBarConstructor,
+    MinuteRunDollarBarConstructor,
+    MinuteRunVolumeBarConstructor,
+    compute_imbalance_dollar_bars_from_minutes,
+    compute_imbalance_volume_bars_from_minutes,
+    compute_run_dollar_bars_from_minutes,
+    compute_run_volume_bars_from_minutes,
+)
+from flowbars.bars.minute.registry import MinuteBarRegistry
+from flowbars.bars.minute.standard import (
+    MinuteDollarBarConstructor,
+    MinuteVolumeBarConstructor,
+    compute_dollar_bars_from_minutes,
+    compute_volume_bars_from_minutes,
+)
+from flowbars.bars.minute.structural import (
+    MinuteHybridBarConstructor,
+    MinuteRangeBarConstructor,
+    MinuteRenkoBarConstructor,
+    MinuteVolatilityBarConstructor,
+    compute_hybrid_bars_from_minutes,
+    compute_range_bars_from_minutes,
+    compute_renko_bars_from_minutes,
+    compute_volatility_bars_from_minutes,
+)
+from flowbars.thresholds import MinuteCalibrationHelper
+
+__all__ = [
+    "BaseMinuteBarConstructor",
+    "MinuteBarRegistry",
+    "MinuteCalibrationHelper",
+    "MinuteDollarAccumulator",
+    "MinuteDollarBarConstructor",
+    "MinuteHybridAccumulator",
+    "MinuteHybridBarConstructor",
+    "MinuteImbalanceAccumulator",
+    "MinuteImbalanceDollarBarConstructor",
+    "MinuteImbalanceVolumeBarConstructor",
+    "MinuteRangeAccumulator",
+    "MinuteRangeBarConstructor",
+    "MinuteRenkoAccumulator",
+    "MinuteRenkoBarConstructor",
+    "MinuteRunAccumulator",
+    "MinuteRunDollarBarConstructor",
+    "MinuteRunVolumeBarConstructor",
+    "MinuteVolatilityAccumulator",
+    "MinuteVolatilityBarConstructor",
+    "MinuteVolumeAccumulator",
+    "MinuteVolumeBarConstructor",
+    "compute_dollar_bars_from_minutes",
+    "compute_hybrid_bars_from_minutes",
+    "compute_imbalance_dollar_bars_from_minutes",
+    "compute_imbalance_volume_bars_from_minutes",
+    "compute_range_bars_from_minutes",
+    "compute_renko_bars_from_minutes",
+    "compute_run_dollar_bars_from_minutes",
+    "compute_run_volume_bars_from_minutes",
+    "compute_volatility_bars_from_minutes",
+    "compute_volume_bars_from_minutes",
+]

flowbars/bars/minute/accumulators.py

@@ -0,0 +1,303 @@
+"""Accumulators for the minute-OHLCV → bars path.
+
+The first four mirror the tick accumulators but ingest whole-minute candles.
+The last four implement the minute-only structural bar types (volatility,
+relative range, renko displacement, hybrid).  All state values are
+JSON-serializable; prices carried across bars use ``None`` (never NaN).
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+
+from flowbars.bars.accumulators import (
+    BaseAccumulator,
+    DollarAccumulator,
+    ImbalanceAccumulator,
+    RunAccumulator,
+    VolumeAccumulator,
+    _minute_metric,
+)
+from flowbars.core import Bar, MinuteInfo
+
+
+class MinuteVolumeAccumulator(VolumeAccumulator):
+    """Volume accumulator for minute input (metric = minute volume)."""
+
+    def add_minute(self, minute: MinuteInfo) -> None:
+        super().add_minute(minute)
+        self._cum_volume += minute.volume
+
+
+class MinuteDollarAccumulator(DollarAccumulator):
+    """Dollar accumulator for minute input (metric = close × volume)."""
+
+    def add_minute(self, minute: MinuteInfo) -> None:
+        super().add_minute(minute)
+        self._cum_dollar += minute.close * minute.volume * self._multiplier
+
+
+class MinuteImbalanceAccumulator(ImbalanceAccumulator):
+    """Signed-imbalance accumulator for minute input (metric = volume or dollar)."""
+
+    def add_minute(self, minute: MinuteInfo) -> None:
+        super().add_minute(minute)
+        if minute.side is not None and not math.isnan(minute.side):
+            self._signed_imbalance += minute.side * _minute_metric(
+                minute, self._metric, self._multiplier
+            )
+
+
+class MinuteRunAccumulator(RunAccumulator):
+    """Same-sign run accumulator for minute input (metric = volume or dollar)."""
+
+    def add_minute(self, minute: MinuteInfo) -> None:
+        super().add_minute(minute)
+        side = minute.side if minute.side is not None else np.nan
+        self._accumulate_run(side, _minute_metric(minute, self._metric, self._multiplier))
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Structural (minute-only) accumulators
+# ═══════════════════════════════════════════════════════════════════════════════
+
+
+class MinuteVolatilityAccumulator(BaseAccumulator):
+    """Closes when cumulative absolute close-to-close returns cross a threshold.
+
+    Per-minute metric: ``|close − prev_close| / prev_close`` (0 for the first
+    minute of the stream or when ``prev_close == 0``).  ``prev_close`` carries
+    across bars; a session boundary resets it so an overnight gap contributes
+    nothing.  Scalar overflow rolls into the next bar.
+    """
+
+    def __init__(self, bar_type: str = "volatility") -> None:
+        super().__init__(bar_type)
+        self._cum_metric = 0.0
+        self._prev_close: float | None = None
+
+    def add_minute(self, minute: MinuteInfo) -> None:
+        super().add_minute(minute)
+        if self._prev_close is None or self._prev_close == 0.0:
+            metric = 0.0
+        else:
+            metric = abs(minute.close - self._prev_close) / self._prev_close
+        self._cum_metric += metric
+        self._prev_close = minute.close
+
+    def should_close(self, threshold: float) -> bool:
+        return self._cum_metric >= threshold
+
+    def close(self, threshold: float) -> Bar:
+        bar = self._emit_and_reset()
+        self._cum_metric = max(0.0, self._cum_metric - threshold)
+        return bar
+
+    def discard(self) -> None:
+        super().discard()
+        self._cum_metric = 0.0
+
+    def get_close_stats(self) -> tuple[float, float]:
+        return (self._cum_metric, 0.0)
+
+    def on_session_boundary(self) -> None:
+        self._prev_close = None
+
+    def get_state(self) -> dict[str, Any]:
+        state = super().get_state()
+        state["cum_metric"] = self._cum_metric
+        state["prev_close"] = self._prev_close
+        return state
+
+    def load_state(self, state: dict[str, Any]) -> None:
+        super().load_state(state)
+        self._cum_metric = state.get("cum_metric", 0.0)
+        self._prev_close = state.get("prev_close")
+
+
+class MinuteRangeAccumulator(BaseAccumulator):
+    """Closes when cumulative relative range crosses a threshold.
+
+    Per-minute metric: ``(high − low) / close`` (0 when ``close == 0``).
+    Scalar overflow rolls into the next bar.
+    """
+
+    def __init__(self, bar_type: str = "range") -> None:
+        super().__init__(bar_type)
+        self._cum_metric = 0.0
+
+    def add_minute(self, minute: MinuteInfo) -> None:
+        super().add_minute(minute)
+        if minute.close == 0.0:
+            metric = 0.0
+        else:
+            metric = (minute.high - minute.low) / minute.close
+        self._cum_metric += metric
+
+    def should_close(self, threshold: float) -> bool:
+        return self._cum_metric >= threshold
+
+    def close(self, threshold: float) -> Bar:
+        bar = self._emit_and_reset()
+        self._cum_metric = max(0.0, self._cum_metric - threshold)
+        return bar
+
+    def discard(self) -> None:
+        super().discard()
+        self._cum_metric = 0.0
+
+    def get_close_stats(self) -> tuple[float, float]:
+        return (self._cum_metric, 0.0)
+
+    def get_state(self) -> dict[str, Any]:
+        state = super().get_state()
+        state["cum_metric"] = self._cum_metric
+        return state
+
+    def load_state(self, state: dict[str, Any]) -> None:
+        super().load_state(state)
+        self._cum_metric = state.get("cum_metric", 0.0)
+
+
+class MinuteRenkoAccumulator(BaseAccumulator):
+    """Closes when price displacement from the bar's anchor crosses a threshold.
+
+    The anchor is the **open of the bar's first minute**, and that first
+    minute is evaluated against it (so a one-minute renko bar is possible).
+    Per-minute displacement: ``|close − anchor| / anchor`` (0 when the anchor
+    is non-positive).  Displacement is not additive, so there is **no
+    overflow** — the anchor resets on close.
+    """
+
+    def __init__(self, bar_type: str = "renko") -> None:
+        super().__init__(bar_type)
+        self._anchor: float | None = None
+        self._displacement = 0.0
+
+    def add_minute(self, minute: MinuteInfo) -> None:
+        super().add_minute(minute)
+        if self._anchor is None:
+            self._anchor = minute.open
+        if self._anchor <= 0.0:
+            self._displacement = 0.0
+        else:
+            self._displacement = abs(minute.close - self._anchor) / self._anchor
+
+    def should_close(self, threshold: float) -> bool:
+        return self._displacement >= threshold
+
+    def close(self, threshold: float) -> Bar:
+        bar = self._emit_and_reset()
+        self._anchor = None
+        self._displacement = 0.0
+        return bar
+
+    def discard(self) -> None:
+        super().discard()
+        self._anchor = None
+        self._displacement = 0.0
+
+    def get_close_stats(self) -> tuple[float, float]:
+        return (self._displacement, 0.0)
+
+    def get_state(self) -> dict[str, Any]:
+        state = super().get_state()
+        state["anchor"] = self._anchor
+        state["displacement"] = self._displacement
+        return state
+
+    def load_state(self, state: dict[str, Any]) -> None:
+        super().load_state(state)
+        self._anchor = state.get("anchor")
+        self._displacement = state.get("displacement", 0.0)
+
+
+class MinuteHybridAccumulator(BaseAccumulator):
+    """Closes when **both** cumulative notional and cumulative volatility targets are met.
+
+    Two running metrics: ``Σ close × volume`` and the volatility metric
+    ``Σ |close − prev_close| / prev_close`` (0 for the first minute or when
+    ``prev_close == 0``).  Both thresholds live on the accumulator.  At close,
+    both scalar excesses roll into the next bar (the scalar-metric rule
+    applied twice).  A session boundary resets ``prev_close``.
+    """
+
+    def __init__(
+        self,
+        bar_type: str = "hybrid",
+        dollar_threshold: float = 0.0,
+        volatility_threshold: float = 0.0,
+    ) -> None:
+        super().__init__(bar_type)
+        if dollar_threshold < 0:
+            raise ValueError(f"dollar_threshold must be non-negative, got {dollar_threshold}")
+        if volatility_threshold < 0:
+            raise ValueError(
+                f"volatility_threshold must be non-negative, got {volatility_threshold}"
+            )
+        self._dollar_threshold = dollar_threshold
+        self._volatility_threshold = volatility_threshold
+        self._cum_dollar = 0.0
+        self._cum_vol = 0.0
+        self._prev_close: float | None = None
+
+    def add_minute(self, minute: MinuteInfo) -> None:
+        super().add_minute(minute)
+        self._cum_dollar += minute.close * minute.volume * self._multiplier
+        if self._prev_close is None or self._prev_close == 0.0:
+            metric = 0.0
+        else:
+            metric = abs(minute.close - self._prev_close) / self._prev_close
+        self._cum_vol += metric
+        self._prev_close = minute.close
+
+    def should_close(self, threshold: float) -> bool:
+        # ``threshold`` (the engine's static threshold) is the dollar target
+        # for API symmetry; both targets are read from the accumulator.
+        return (
+            self._cum_dollar >= self._dollar_threshold
+            and self._cum_vol >= self._volatility_threshold
+        )
+
+    def close(self, threshold: float) -> Bar:
+        bar = self._emit_and_reset()
+        self._cum_dollar = max(0.0, self._cum_dollar - self._dollar_threshold)
+        self._cum_vol = max(0.0, self._cum_vol - self._volatility_threshold)
+        return bar
+
+    def discard(self) -> None:
+        super().discard()
+        self._cum_dollar = 0.0
+        self._cum_vol = 0.0
+
+    def get_close_stats(self) -> tuple[float, float]:
+        return (self._cum_dollar, 0.0)
+
+    def on_session_boundary(self) -> None:
+        self._prev_close = None
+
+    def get_params(self) -> dict[str, Any]:
+        params = super().get_params()
+        params["dollar_threshold"] = self._dollar_threshold
+        params["volatility_threshold"] = self._volatility_threshold
+        return params
+
+    def get_state(self) -> dict[str, Any]:
+        state = super().get_state()
+        state["cum_dollar"] = self._cum_dollar
+        state["cum_vol"] = self._cum_vol
+        state["prev_close"] = self._prev_close
+        state["dollar_threshold"] = self._dollar_threshold
+        state["volatility_threshold"] = self._volatility_threshold
+        return state
+
+    def load_state(self, state: dict[str, Any]) -> None:
+        super().load_state(state)
+        self._cum_dollar = state.get("cum_dollar", 0.0)
+        self._cum_vol = state.get("cum_vol", 0.0)
+        self._prev_close = state.get("prev_close")
+        self._dollar_threshold = state.get("dollar_threshold", 0.0)
+        self._volatility_threshold = state.get("volatility_threshold", 0.0)

flowbars/bars/minute/engine.py

@@ -0,0 +1,244 @@
+"""Shared engine for the minute-OHLCV → bars path.
+
+The minute path reuses :class:`~flowbars.bars.constructor.BaseBarConstructor`
+for all orchestration (streaming ``update``, batch, warmup, watermark dedup,
+strict ordering, callbacks, session calendars, and state save/resume).  This
+module supplies the minute-specific input hooks:
+
+* :meth:`BaseMinuteBarConstructor._extract_batch_arrays` — pulls
+  ``(timestamps, opens, highs, lows, closes, volumes, signs)`` from a
+  :class:`~flowbars.schema.MinuteSchemaMapping` DataFrame and derives minute
+  signs with the tick rule applied to closes.
+* :meth:`BaseMinuteBarConstructor._prepare_input` — derives the minute tick
+  rule for streaming inputs whose ``side`` is ``None``.
+* :meth:`BaseMinuteBarConstructor._ingest_input` — calls
+  ``accumulator.add_minute``.
+
+Design decisions are specified in the repo's ``SPEC.md`` under
+"Minute-OHLCV → bars path — design". Key points: direct OHLCV accumulation,
+whole-minute attribution (only the scalar metric excess rolls), the minute
+tick rule ``sign(close_i − close_{i−1})`` with first-minute ``NaN``,
+``num_ticks`` counts **minutes**, and ``dollar_value``/``vwap`` use
+``close × volume`` as the notional proxy.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import replace
+from typing import Any, ClassVar, Literal
+
+import numpy as np
+import pandas as pd
+
+from flowbars.bars.constructor import BaseBarConstructor
+from flowbars.core import MinuteInfo, TickInfo
+from flowbars.schema import MinuteSchemaMapping
+from flowbars.thresholds import EWMAThresholdEstimator, ThresholdEstimator
+from flowbars.tick_rule import resolve_tick_signs
+
+_DEFAULT_MINUTE_SCHEMA = MinuteSchemaMapping(
+    {
+        "timestamp": "timestamp",
+        "open": "open",
+        "high": "high",
+        "low": "low",
+        "close": "close",
+        "volume": "volume",
+    }
+)
+
+
+class BaseMinuteBarConstructor(BaseBarConstructor):
+    """Shared engine for bar types built from minute OHLCV candles."""
+
+    input_kind: ClassVar[str] = "minute"
+
+    # Session-end behavior for the in-progress bar.  Minute bars opt in to
+    # the full policy set; tick bars support force-close only.
+    session_policies: ClassVar[tuple[str, ...]] = ("close", "discard", "carry")
+
+    def __init__(
+        self,
+        accumulator: Any,
+        threshold_estimator: ThresholdEstimator,
+        calendar: Any = None,
+        schema: MinuteSchemaMapping | None = None,
+        watermark: str | None = "timestamp",
+        stream_id: str = "default",
+        strict_ordering: bool = False,
+        warmup_bars: int = 0,
+        warmup_minutes: int | None = None,
+        backend: Any = "python",
+        on_bar: Any = None,
+        on_threshold_update: Any = None,
+        multiplier: float = 1.0,
+        volume_type: str = "base",
+        session_policy: Literal["close", "carry", "discard"] = "close",
+        session_estimator: Literal["persist", "reset"] = "persist",
+    ) -> None:
+        super().__init__(
+            accumulator=accumulator,
+            threshold_estimator=threshold_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,
+            session_policy=session_policy,
+            session_estimator=session_estimator,
+        )
+        # Previous minute close/derived sign for the streaming tick rule.
+        self._prev_close: float | None = None
+        self._prev_sign: float = np.nan
+
+    # ── input hooks ─────────────────────────────────────────────────────
+
+    def _default_schema(self) -> MinuteSchemaMapping:
+        return _DEFAULT_MINUTE_SCHEMA
+
+    def _extract_batch_arrays(self, df: pd.DataFrame) -> tuple[np.ndarray, ...]:
+        assert isinstance(self._schema, MinuteSchemaMapping)
+        timestamps, opens, highs, lows, closes, volumes, sides = self._schema.extract_arrays(df)
+        signs = resolve_tick_signs(closes, sides)
+        return (timestamps, opens, highs, lows, closes, volumes, signs)
+
+    def _make_input(
+        self, arrays: tuple[np.ndarray, ...], i: int, watermark: np.ndarray | None
+    ) -> MinuteInfo:
+        timestamps, opens, highs, lows, closes, volumes, signs = arrays
+        return MinuteInfo(
+            timestamp=int(timestamps[i]),
+            open=float(opens[i]),
+            high=float(highs[i]),
+            low=float(lows[i]),
+            close=float(closes[i]),
+            volume=float(volumes[i]),
+            side=float(signs[i]),
+            watermark=int(watermark[i]) if watermark is not None else None,
+        )
+
+    def _prepare_input(self, item: TickInfo | MinuteInfo) -> TickInfo | MinuteInfo:
+        """Derive the minute tick rule when no side was supplied."""
+        if not isinstance(item, MinuteInfo):
+            raise TypeError(f"Minute constructors require MinuteInfo, got {type(item).__name__}")
+
+        close = item.close
+        if item.side is None:
+            if self._prev_close is None:
+                sign = np.nan
+            else:
+                diff = close - self._prev_close
+                if diff > 0.0:
+                    sign = 1.0
+                elif diff < 0.0:
+                    sign = -1.0
+                else:
+                    sign = self._prev_sign
+            if not math.isnan(sign):
+                item = replace(item, side=sign)
+            self._prev_sign = sign
+        else:
+            self._prev_sign = item.side
+
+        self._prev_close = close
+        return item
+
+    def _ingest_input(self, item: TickInfo | MinuteInfo) -> None:
+        assert isinstance(item, MinuteInfo)
+        self._accumulator.add_minute(item)
+
+    # ── state ───────────────────────────────────────────────────────────
+
+    def _extra_state(self) -> dict[str, Any]:
+        prev_sign = self._prev_sign
+        return {
+            "prev_close": self._prev_close,
+            "prev_sign": None if math.isnan(prev_sign) else prev_sign,
+        }
+
+    def _load_extra_state(self, state: dict[str, Any]) -> None:
+        self._prev_close = state.get("prev_close")
+        prev_sign = state.get("prev_sign")
+        self._prev_sign = np.nan if prev_sign is None else float(prev_sign)
+
+    def _on_session_boundary(self) -> None:
+        """A session gap is not a tick-rule move: clear derived-sign state."""
+        self._prev_close = None
+        self._prev_sign = np.nan
+
+    # ── numba dispatch ──────────────────────────────────────────────────
+
+    def _numba_config(self) -> dict[str, float]:
+        estimator = self._threshold_estimator
+        config: dict[str, float] = {"multiplier": self.multiplier}
+        if isinstance(estimator, EWMAThresholdEstimator):
+            config["alpha"] = estimator.alpha
+            config["initial_ewa_t"] = estimator.ewa_t
+            config["initial_ewa_proportion"] = estimator.ewa_proportion
+        else:
+            config["threshold"] = estimator.current_threshold
+        volatility_threshold = getattr(self._accumulator, "_volatility_threshold", None)
+        if volatility_threshold is not None:
+            config["volatility_threshold"] = float(volatility_threshold)
+        return config
+
+    def _batch_numba(
+        self,
+        arrays: tuple[np.ndarray, ...],
+        watermark: np.ndarray | None = None,
+    ) -> pd.DataFrame:
+        """Run the batch loop through the minute numba kernels.
+
+        Falls back to the Python engine when numba is unavailable, the
+        calendar produces session boundaries, or the constructor is not
+        pristine.  The kernels are stateless — they do not advance the Python
+        accumulator/estimator — so incremental batches must use the Python
+        backend, which is what the non-pristine fallback does.
+        """
+        import warnings
+
+        from flowbars.bars.numba_backend import _NUMBA_AVAILABLE, _get_compilation_warning
+
+        if not _NUMBA_AVAILABLE:
+            _get_compilation_warning()
+            return self._batch_python(arrays, watermark)
+
+        if self._calendar.has_sessions:
+            warnings.warn(
+                "This calendar produces session boundaries, which the numba "
+                "backend does not support. Falling back to the Python path.",
+                stacklevel=2,
+            )
+            return self._batch_python(arrays, watermark)
+
+        if not self._is_pristine():
+            warnings.warn(
+                "The numba backend requires a pristine constructor (no prior "
+                "update()/batch() calls and no restored state). Falling back "
+                "to the Python path.",
+                stacklevel=2,
+            )
+            return self._batch_python(arrays, watermark)
+
+        from flowbars.bars.minute.numba import numba_batch_minute
+
+        bar_type = self._accumulator._bar_type
+        try:
+            bar_data, bt = numba_batch_minute(bar_type, arrays, self._numba_config())
+        except Exception:
+            warnings.warn(
+                f"numba compilation/execution failed for {bar_type}. "
+                "Falling back to the Python path.",
+                stacklevel=2,
+            )
+            return self._batch_python(arrays, watermark)
+
+        return self._finalize_numba_result(bar_data, bt)