jasonlib-dev 0.1.0__py3-none-any.whl

jasonlib/_pivot_analysis.py

@@ -0,0 +1,308 @@
+"""Pivot breakout detection and analysis."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+
+import pandas as pd
+
+from jasonlib._models import JInterval
+from jasonlib._pivot_models import (
+    PivotAnalysisParameters,
+    PivotAnalysisResult,
+    PivotAnalysisSummary,
+    PivotSortOption,
+)
+from jasonlib._trend_models import CoinDataset, InsufficientDataError
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize_merge_time_precision(series: pd.Series) -> pd.Series:
+    """Force merge keys to a consistent timezone-aware precision for merge_asof."""
+    if series.dt.tz is None:
+        return series.dt.tz_localize("UTC").astype("datetime64[ns, UTC]")
+    return series.astype("datetime64[ns, UTC]")
+
+
+def detect_pivot_breakouts(
+    jason_data: dict[str, pd.DataFrame],
+    ohlc_data: dict[str, pd.DataFrame],
+    cooldown_hours: float = 24.0,
+    lookback_hours: float = 4.0,
+) -> pd.DataFrame:
+    """Vectorized pivot breakout detection.
+
+    Detects when price breaks above/below the pivot from N hours ago.
+    Uses pd.merge_asof for efficient time-series matching.
+    Cooldown period avoids recounting oscillations.
+
+    Args:
+        jason_data: JASON DataFrames with 'high_pivot', 'low_pivot' columns.
+        ohlc_data: OHLC DataFrames with 'close' column.
+        cooldown_hours: Minimum hours between counting separate breakout events.
+        lookback_hours: Hours to look back for pivot comparison.
+
+    Returns:
+        DataFrame with breakout status, distances, and counts per ticker.
+    """
+    breakout_data = {}
+    lookback_timedelta = pd.Timedelta(hours=lookback_hours)
+    cooldown_timedelta = pd.Timedelta(hours=cooldown_hours)
+
+    for ticker in jason_data.keys():
+        if ticker not in ohlc_data:
+            continue
+
+        jason_df = jason_data[ticker].copy()
+        ohlc_df = ohlc_data[ticker].copy()
+
+        if jason_df.empty or ohlc_df.empty or len(jason_df) < 2:
+            continue
+
+        if "high_pivot" not in jason_df.columns or "low_pivot" not in jason_df.columns:
+            continue
+
+        # === CURRENT STATUS (Latest values) ===
+        latest_price = ohlc_df["close"].iloc[-1]
+        latest_timestamp = ohlc_df.index[-1]
+
+        # Find pivot from lookback_hours ago for current status
+        lookback_time = latest_timestamp - lookback_timedelta
+        valid_jason = jason_df[jason_df.index < latest_timestamp]
+        if len(valid_jason) == 0:
+            continue
+
+        time_diffs = abs(valid_jason.index - lookback_time)
+        closest_idx = time_diffs.argmin()
+        lookback_jason = valid_jason.iloc[closest_idx]
+
+        high_pivot = lookback_jason["high_pivot"]
+        low_pivot = lookback_jason["low_pivot"]
+
+        # Calculate distances
+        dist_to_high_pct = ((latest_price - high_pivot) / high_pivot) * 100
+        dist_to_low_pct = ((latest_price - low_pivot) / low_pivot) * 100
+
+        if latest_price > high_pivot:
+            current_breakout = "High Broken"
+        elif latest_price < low_pivot:
+            current_breakout = "Low Broken"
+        else:
+            current_breakout = "Between Pivots"
+
+        # Merge OHLC and JASON data
+        merged = pd.merge(
+            ohlc_df[["close"]],
+            jason_df[["high_pivot", "low_pivot"]],
+            left_index=True,
+            right_index=True,
+            how="inner",
+        ).dropna()
+
+        if len(merged) < 2:
+            breakout_data[ticker] = {
+                "current_price": latest_price,
+                "high_pivot": high_pivot,
+                "low_pivot": low_pivot,
+                "dist_to_high_pivot_pct": dist_to_high_pct,
+                "dist_to_low_pivot_pct": dist_to_low_pct,
+                "current_breakout": current_breakout,
+                "high_breaks_count": 0,
+                "low_breaks_count": 0,
+                "total_breaks": 0,
+                "last_breakout_time": None,
+                "hours_since_last_breakout": None,
+            }
+            continue
+
+        high_breaks = 0
+        low_breaks = 0
+        last_high_break_time = None
+        last_low_break_time = None
+
+        # === VECTORIZED HISTORICAL BREAKOUT COUNTING ===
+        merged_with_target = merged.copy()
+        merged_with_target["target_time"] = merged_with_target.index - lookback_timedelta
+
+        # Prepare jason data for merge_asof
+        jason_for_merge = jason_df[["high_pivot", "low_pivot"]].copy()
+        jason_for_merge = jason_for_merge.reset_index()
+        jason_for_merge.columns = ["time", "lookback_high_pivot", "lookback_low_pivot"]
+        jason_for_merge["time"] = _normalize_merge_time_precision(jason_for_merge["time"])
+
+        merged_with_target = merged_with_target.reset_index()
+        merged_with_target.columns = ["time", "close", "high_pivot", "low_pivot", "target_time"]
+        merged_with_target["target_time"] = _normalize_merge_time_precision(
+            merged_with_target["target_time"]
+        )
+
+        # Merge lookback pivots using merge_asof (efficient nearest-match join)
+        result = pd.merge_asof(
+            merged_with_target.sort_values("target_time"),
+            jason_for_merge.sort_values("time"),
+            left_on="target_time",
+            right_on="time",
+            direction="nearest",
+            suffixes=("", "_lookup"),
+        )
+        result = result.set_index("time").sort_index()
+
+        # Vectorized breakout detection
+        result["above_high"] = result["close"] > result["lookback_high_pivot"]
+        result["below_low"] = result["close"] < result["lookback_low_pivot"]
+
+        # Detect crossovers (transitions from False to True)
+        result["high_cross"] = result["above_high"] & ~result["above_high"].shift(
+            1, fill_value=False
+        )
+        result["low_cross"] = result["below_low"] & ~result["below_low"].shift(
+            1, fill_value=False
+        )
+
+        # Apply cooldown — iterate only over crossover events
+        high_break_indices = result[result["high_cross"]].index
+        for break_time in high_break_indices:
+            if (
+                last_high_break_time is None
+                or (break_time - last_high_break_time) > cooldown_timedelta
+            ):
+                high_breaks += 1
+                last_high_break_time = break_time
+
+        low_break_indices = result[result["low_cross"]].index
+        for break_time in low_break_indices:
+            if (
+                last_low_break_time is None
+                or (break_time - last_low_break_time) > cooldown_timedelta
+            ):
+                low_breaks += 1
+                last_low_break_time = break_time
+
+        # Determine the last breakout time
+        last_breakout_time = None
+        if last_high_break_time is not None and last_low_break_time is not None:
+            last_breakout_time = max(last_high_break_time, last_low_break_time)
+        elif last_high_break_time is not None:
+            last_breakout_time = last_high_break_time
+        elif last_low_break_time is not None:
+            last_breakout_time = last_low_break_time
+
+        # Calculate time since last breakout
+        time_since_last_breakout = None
+        if last_breakout_time is not None:
+            time_since_last_breakout = (
+                latest_timestamp - last_breakout_time
+            ).total_seconds() / 3600.0
+
+        breakout_data[ticker] = {
+            "current_price": latest_price,
+            "high_pivot": high_pivot,
+            "low_pivot": low_pivot,
+            "dist_to_high_pivot_pct": dist_to_high_pct,
+            "dist_to_low_pivot_pct": dist_to_low_pct,
+            "current_breakout": current_breakout,
+            "high_breaks_count": high_breaks,
+            "low_breaks_count": low_breaks,
+            "total_breaks": high_breaks + low_breaks,
+            "last_breakout_time": last_breakout_time,
+            "hours_since_last_breakout": time_since_last_breakout,
+        }
+
+    return pd.DataFrame.from_dict(breakout_data, orient="index")
+
+
+_PIVOT_SORT_COLUMN_MAP: dict[PivotSortOption, str] = {
+    PivotSortOption.TOTAL_BREAKS: "total_breaks",
+    PivotSortOption.HIGH_BREAKS: "high_breaks_count",
+    PivotSortOption.LOW_BREAKS: "low_breaks_count",
+    PivotSortOption.BREAKOUT_STATUS: "current_breakout",
+}
+
+
+def compute_pivot_analysis(
+    datasets: list[CoinDataset],
+    interval: JInterval,
+    start_date: pd.Timestamp,
+    end_date: pd.Timestamp,
+    cooldown_hours: float = 24.0,
+    lookback_hours: float = 4.0,
+    sort_by: PivotSortOption = PivotSortOption.TOTAL_BREAKS,
+) -> PivotAnalysisResult:
+    """Compute pivot breakout analysis across a set of coins.
+
+    Args:
+        datasets: List of CoinDataset, each containing a coin identifier,
+            OHLC klines DataFrame (with 'close' column), and jason DataFrame
+            (with 'high_pivot', 'low_pivot' columns).
+        interval: Data interval (e.g., JInterval.H4, JInterval.D1).
+        start_date: Start of the analysis window.
+        end_date: End of the analysis window.
+        cooldown_hours: Minimum hours between counting separate breakout events.
+        lookback_hours: Hours to look back for pivot comparison.
+        sort_by: How to sort the breakout results.
+
+    Returns:
+        PivotAnalysisResult with summary metrics and breakout DataFrame.
+
+    Raises:
+        ValueError: If start_date > end_date.
+        InsufficientDataError: If no coins have enough data to produce results.
+    """
+    if start_date > end_date:
+        raise ValueError("start_date must be before or equal to end_date")
+
+    # Convert CoinDataset list to dict pairs for detect_pivot_breakouts
+    jason_data = {ds.coin: ds.jason_df for ds in datasets}
+    ohlc_data = {ds.coin: ds.klines_df for ds in datasets}
+
+    breakout_df = detect_pivot_breakouts(
+        jason_data=jason_data,
+        ohlc_data=ohlc_data,
+        cooldown_hours=cooldown_hours,
+        lookback_hours=lookback_hours,
+    )
+
+    if breakout_df.empty:
+        raise InsufficientDataError(
+            "No coins have enough data to produce pivot analysis results."
+        )
+
+    # Sort by requested column
+    sort_col = _PIVOT_SORT_COLUMN_MAP[sort_by]
+    sorted_df = breakout_df.sort_values(by=sort_col, ascending=False)
+
+    # Compute summary
+    summary = PivotAnalysisSummary(
+        high_pivots_broken=int((sorted_df["current_breakout"] == "High Broken").sum()),
+        low_pivots_broken=int((sorted_df["current_breakout"] == "Low Broken").sum()),
+        avg_total_breaks=float(sorted_df["total_breaks"].mean()),
+        between_pivots=int((sorted_df["current_breakout"] == "Between Pivots").sum()),
+    )
+
+    # Determine as_of from latest OHLC timestamp
+    latest_timestamps = []
+    for ds in datasets:
+        if ds.klines_df is not None and not ds.klines_df.empty:
+            latest_timestamps.append(pd.Timestamp(ds.klines_df.index.max()))
+    as_of = max(latest_timestamps) if latest_timestamps else datetime.now(timezone.utc)
+    # Ensure as_of is a proper datetime
+    if isinstance(as_of, pd.Timestamp):
+        as_of = as_of.to_pydatetime()
+
+    return PivotAnalysisResult(
+        start_date=start_date.strftime("%Y-%m-%d"),
+        end_date=end_date.strftime("%Y-%m-%d"),
+        interval=interval,
+        generated_at=datetime.now(timezone.utc),
+        as_of=as_of,
+        parameters=PivotAnalysisParameters(
+            cooldown_hours=cooldown_hours,
+            lookback_hours=lookback_hours,
+            sort_by=sort_by,
+            sort_options=list(PivotSortOption),
+        ),
+        summary=summary,
+        breakouts=sorted_df,
+    )

jasonlib/_pivot_models.py

@@ -0,0 +1,45 @@
+"""Pivot analysis data models and enums."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+
+import pandas as pd
+
+from jasonlib._models import JInterval
+from jasonlib._trend_models import BaseModelWithPandasFields
+
+
+class PivotSortOption(str, Enum):
+    """Sort options for pivot breakout results."""
+
+    TOTAL_BREAKS = "Total Breaks"
+    HIGH_BREAKS = "High Breaks"
+    LOW_BREAKS = "Low Breaks"
+    BREAKOUT_STATUS = "Breakout Status"
+
+
+class PivotAnalysisSummary(BaseModelWithPandasFields):
+    high_pivots_broken: int
+    low_pivots_broken: int
+    avg_total_breaks: float
+    between_pivots: int
+
+
+class PivotAnalysisParameters(BaseModelWithPandasFields):
+    cooldown_hours: float
+    lookback_hours: float
+    sort_by: PivotSortOption
+    sort_options: list[PivotSortOption]
+
+
+class PivotAnalysisResult(BaseModelWithPandasFields):
+    start_date: str
+    end_date: str
+    interval: JInterval
+    generated_at: datetime
+    as_of: datetime
+    parameters: PivotAnalysisParameters
+    summary: PivotAnalysisSummary
+    breakouts: pd.DataFrame

jasonlib/_trading_calendar.py

@@ -0,0 +1,93 @@
+"""Trading calendar constants and helpers for JASON calculations."""
+
+import logging
+
+from jasonlib._models import JAssetClass, JInterval
+
+TRADING_DAYS_PER_YEAR: dict[JAssetClass, int] = {
+    JAssetClass.CRYPTO: 365,
+    JAssetClass.EQUITIES: 252,
+    JAssetClass.COMMOD: 252,
+    JAssetClass.FX: 252,
+    JAssetClass.EQUITY_IDX: 252,
+}
+
+TRADING_HOURS_PER_DAY: dict[JAssetClass, float] = {
+    JAssetClass.CRYPTO: 24.0,
+    JAssetClass.EQUITIES: 6.5,
+    JAssetClass.COMMOD: 23.0,
+    JAssetClass.FX: 23.0,
+    JAssetClass.EQUITY_IDX: 23.0,
+}
+
+
+def normalize_asset_class(asset_class: JAssetClass | str | None) -> JAssetClass:
+    """Normalize legacy strings and enum members to JAssetClass.
+
+    Args:
+        asset_class: A JAssetClass member, a string alias, or None.
+            None defaults to CRYPTO.
+
+    Returns:
+        The resolved JAssetClass member.
+    """
+    if isinstance(asset_class, JAssetClass):
+        return asset_class
+    if asset_class is None:
+        return JAssetClass.CRYPTO
+
+    alias_map: dict[str, JAssetClass] = {
+        "commod": JAssetClass.COMMOD,
+        "commodity": JAssetClass.COMMOD,
+        "commodities": JAssetClass.COMMOD,
+        "crypto": JAssetClass.CRYPTO,
+        "fx": JAssetClass.FX,
+        "equity": JAssetClass.EQUITIES,
+        "equities": JAssetClass.EQUITIES,
+        "equity_idx": JAssetClass.EQUITY_IDX,
+    }
+    return alias_map.get(asset_class.strip().lower(), JAssetClass.CRYPTO)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a configured logger instance.
+
+    Args:
+        name: Name for the logger.
+
+    Returns:
+        Configured Logger with a StreamHandler and INFO level.
+    """
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter(
+            "[%(asctime)s] %(levelname)s %(name)s: %(message)s"
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    return logger
+
+
+def get_annualization_factor(interval: JInterval, asset_class: JAssetClass) -> float:
+    """Return the number of periods per year for the given interval and asset class.
+
+    Computes the annualization factor based on the interval duration in seconds,
+    trading days per year, and trading hours per day for the asset class.
+
+    Args:
+        interval: Candle interval.
+        asset_class: Asset class determining the trading calendar.
+
+    Returns:
+        Number of periods per year.
+    """
+    trading_days = TRADING_DAYS_PER_YEAR[asset_class]
+    hours_per_day = TRADING_HOURS_PER_DAY[asset_class]
+    trading_seconds_per_day = hours_per_day * 3600
+    if interval.seconds >= 86400:
+        periods_per_day = 1.0
+    else:
+        periods_per_day = trading_seconds_per_day / interval.seconds
+    return trading_days * periods_per_day