jasonlib-dev 0.1.0__py3-none-any.whl

jasonlib/_trend_analysis.py

@@ -0,0 +1,634 @@
+"""Trend analysis engine: scoring, ranking, and chart construction."""
+
+from __future__ import annotations
+
+import logging
+from typing import Callable, Dict, List, Optional
+
+import numpy as np
+import pandas as pd
+
+from jasonlib._math import sigmoid_diff, sigmoid_vol, sigmoid_z
+from jasonlib._models import JAssetClass, JInterval
+from jasonlib._trading_calendar import get_annualization_factor
+from jasonlib._trend_models import (
+    ChartData,
+    CoinDataset,
+    CoinSeries,
+    InsufficientDataError,
+    MarketTrendSummary,
+    PlotWindow,
+    SummaryMetric,
+    TREND_COLUMN_LABELS,
+    TrendAnalysisResult,
+    TrendCharts,
+    TrendFunction,
+)
+
+logger = logging.getLogger("jasonlib.trend_analysis")
+
+
+# ============================================================================
+# HALF-LIFE WEIGHTS
+# ============================================================================
+
+_HALF_LIFE_WEIGHTS: Dict[pd.Timedelta, float] = {
+    pd.Timedelta("1D"): 3.0,
+    pd.Timedelta("3D"): 2.0,
+    pd.Timedelta("7D"): 1.0,
+}
+
+
+# ============================================================================
+# SCORE HELPER
+# ============================================================================
+
+def _calculate_weighted_average_score(
+    data_series: pd.Series,
+    half_life_weights: Dict[pd.Timedelta, float],
+) -> float:
+    weighted_scores = 0.0
+    total_weight = 0.0
+    for hl, weight in half_life_weights.items():
+        score = data_series.ewm(halflife=hl, times=data_series.index).mean().iloc[-1]
+        weighted_scores += score * weight
+        total_weight += weight
+    if total_weight == 0:
+        return 0.0
+    return weighted_scores / total_weight
+
+
+# ============================================================================
+# TREND SCORE FUNCTIONS
+# ============================================================================
+
+def _log_returns(
+    ohlc: pd.DataFrame,
+    jason: pd.DataFrame,
+    half_life_weights: Dict[pd.Timedelta, float],
+    **kwargs,
+) -> float:
+    log_returns = np.log(ohlc["close"]).diff()
+    weighted_scores = 0.0
+    total_weight = 0.0
+    for hl, weight in half_life_weights.items():
+        ewm_mean_return = log_returns.ewm(halflife=hl, times=log_returns.index).mean().iloc[-1]
+        score = np.clip(ewm_mean_return * 100, -1, 1)
+        weighted_scores += score * weight
+        total_weight += weight
+    if total_weight == 0:
+        return 0.0
+    return weighted_scores / total_weight
+
+
+def _z_score_above_threshold(
+    ohlc: pd.DataFrame,
+    jason: pd.DataFrame,
+    half_life_weights: Dict[pd.Timedelta, float],
+    threshold: float = 2.0,
+    **kwargs,
+) -> float:
+    z_signal = sigmoid_z(jason["low_z"], threshold) - sigmoid_z(jason["high_z"], threshold)
+    return _calculate_weighted_average_score(z_signal, half_life_weights)
+
+
+def _z_score_low_vol(
+    ohlc: pd.DataFrame,
+    jason: pd.DataFrame,
+    half_life_weights: Dict[pd.Timedelta, float],
+    interval: JInterval = JInterval.H4,
+    threshold: float = 2.0,
+    **kwargs,
+) -> float:
+    annualization_factor = get_annualization_factor(interval, JAssetClass.CRYPTO)
+    historical_vol = 100 * np.log(ohlc["close"]).diff().std() * np.sqrt(annualization_factor)
+    vol_weight_low = sigmoid_vol(jason["low_vol"], hist_vol=historical_vol)
+    vol_weight_high = sigmoid_vol(jason["high_vol"], hist_vol=historical_vol)
+    z_signal = (
+        vol_weight_low * sigmoid_z(jason["low_z"], threshold)
+        - vol_weight_high * sigmoid_z(jason["high_z"], threshold)
+    )
+    return _calculate_weighted_average_score(z_signal, half_life_weights)
+
+
+def _avg_z_diff(
+    ohlc: pd.DataFrame,
+    jason: pd.DataFrame,
+    half_life_weights: Dict[pd.Timedelta, float],
+    **kwargs,
+) -> float:
+    z_diff = jason["low_z"] - jason["high_z"]
+    return _calculate_weighted_average_score(z_diff, half_life_weights)
+
+
+def _avg_z_diff_above_threshold(
+    ohlc: pd.DataFrame,
+    jason: pd.DataFrame,
+    half_life_weights: Dict[pd.Timedelta, float],
+    threshold: float = 1.0,
+    **kwargs,
+) -> float:
+    z_diff = jason["low_z"] - jason["high_z"]
+    z_signal = sigmoid_diff(z_diff, threshold=threshold)
+    return _calculate_weighted_average_score(z_signal, half_life_weights)
+
+
+def _pivots_difference(
+    ohlc: pd.DataFrame,
+    jason: pd.DataFrame,
+    half_life_weights: Dict[pd.Timedelta, float],
+    **kwargs,
+) -> float:
+    price_range = abs(ohlc["close"].iloc[-1] - ohlc["close"].iloc[0])
+    if price_range == 0:
+        return 0.0
+    pivots_diff = (jason["high_pivot"].diff() - jason["low_pivot"].diff()) / price_range
+    return _calculate_weighted_average_score(pivots_diff, half_life_weights)
+
+
+def _pivots_time_difference(
+    ohlc: pd.DataFrame,
+    jason: pd.DataFrame,
+    half_life_weights: Dict[pd.Timedelta, float],
+    **kwargs,
+) -> float:
+    time_pivot_diff = jason["low_days"] - jason["high_days"]
+    return _calculate_weighted_average_score(time_pivot_diff, half_life_weights)
+
+
+def _obv_momentum(
+    ohlc: pd.DataFrame,
+    jason: pd.DataFrame,
+    half_life_weights: Dict[pd.Timedelta, float],
+    **kwargs,
+) -> float:
+    if "Volume" not in ohlc.columns and "volume" not in ohlc.columns:
+        return 0.0
+    vol_col = "Volume" if "Volume" in ohlc.columns else "volume"
+    price_change = ohlc["close"].diff()
+    signed_volume = np.sign(price_change).fillna(0) * ohlc[vol_col]
+    obv = signed_volume.cumsum()
+    obv_diff = obv.diff()
+    weighted_scores = 0.0
+    total_weight = 0.0
+    for hl, weight in half_life_weights.items():
+        obv_momentum = obv_diff.ewm(halflife=hl, times=obv_diff.index).mean().iloc[-1]
+        ewm_volume = ohlc[vol_col].ewm(halflife=hl, times=ohlc[vol_col].index).mean().iloc[-1]
+        if ewm_volume == 0:
+            score = 0.0
+        else:
+            score = np.clip(obv_momentum / ewm_volume, -1, 1)
+        weighted_scores += score * weight
+        total_weight += weight
+    if total_weight == 0:
+        return 0.0
+    return weighted_scores / total_weight
+
+
+def _trend_efficiency(
+    ohlc: pd.DataFrame,
+    jason: pd.DataFrame,
+    half_life_weights: Dict[pd.Timedelta, float],
+    **kwargs,
+) -> float:
+    price_diffs = ohlc["close"].diff()
+    weighted_scores = 0.0
+    total_weight = 0.0
+    for hl, weight in half_life_weights.items():
+        ewm_direction = price_diffs.ewm(halflife=hl, times=price_diffs.index).mean().iloc[-1]
+        ewm_volatility = price_diffs.abs().ewm(halflife=hl, times=price_diffs.index).mean().iloc[-1]
+        if ewm_volatility == 0:
+            score = 0.0
+        else:
+            efficiency_score = ewm_direction / ewm_volatility
+            score = np.clip(efficiency_score, -1, 1)
+        weighted_scores += score * weight
+        total_weight += weight
+    if total_weight == 0:
+        return 0.0
+    return weighted_scores / total_weight
+
+
+def _volatility_return_correlation(
+    ohlc: pd.DataFrame,
+    jason: pd.DataFrame,
+    half_life_weights: Dict[pd.Timedelta, float],
+    **kwargs,
+) -> float:
+    returns = np.log(ohlc["close"]).diff()
+    volatility = returns.rolling(window=5).std()
+    valid = pd.concat([returns, volatility], axis=1, keys=["returns", "volatility"]).dropna()
+    if valid.empty:
+        return 0.0
+    returns = valid["returns"]
+    volatility = valid["volatility"]
+    weighted_scores = 0.0
+    total_weight = 0.0
+    for hl, weight in half_life_weights.items():
+        correlation = returns.ewm(halflife=hl).corr(volatility).fillna(0)
+        score = float(correlation.iloc[-1]) if not correlation.empty else 0.0
+        weighted_scores += score * weight
+        total_weight += weight
+    if total_weight == 0:
+        return 0.0
+    return weighted_scores / total_weight
+
+
+# ============================================================================
+# FUNCTION REGISTRY
+# ============================================================================
+
+_TREND_FUNCTION_MAP: Dict[TrendFunction, Callable] = {
+    TrendFunction.LOG_RETURNS: _log_returns,
+    TrendFunction.Z_SCORE_ABOVE_THRESHOLD: _z_score_above_threshold,
+    TrendFunction.Z_SCORE_LOW_VOL: _z_score_low_vol,
+    TrendFunction.AVG_Z_DIFF: _avg_z_diff,
+    TrendFunction.Z_DIFF_ABOVE_THRESHOLD: _avg_z_diff_above_threshold,
+    TrendFunction.PIVOTS_DIFFERENCE: _pivots_difference,
+    TrendFunction.TIME_SINCE_PIVOTS: _pivots_time_difference,
+    TrendFunction.OBV_MOMENTUM: _obv_momentum,
+    TrendFunction.TREND_EFFICIENCY: _trend_efficiency,
+    TrendFunction.VOL_RETURN_CORRELATION: _volatility_return_correlation,
+}
+
+
+# ============================================================================
+# TREND ANALYZER CLASS
+# ============================================================================
+
+class TrendAnalyzer:
+    """Multi-factor trend scorer using exponentially weighted averages.
+
+    Args:
+        interval: Candle interval for the data being analyzed.
+        trend_functions: Which trend functions to compute.
+    """
+
+    def __init__(self, interval: JInterval, trend_functions: list[TrendFunction]) -> None:
+        self.interval = interval
+        self.trend_functions = trend_functions
+        self.half_life_weights = _HALF_LIFE_WEIGHTS
+
+    def run_analysis_from_data(
+        self,
+        ohlc_data: Dict[str, pd.DataFrame],
+        jason_data: Dict[str, pd.DataFrame],
+    ) -> pd.DataFrame:
+        """Run trend analysis on pre-fetched data.
+
+        Args:
+            ohlc_data: OHLC DataFrames keyed by coin identifier.
+            jason_data: JASON DataFrames keyed by coin identifier.
+
+        Returns:
+            DataFrame with normalized trend scores and Average Score, sorted descending.
+            Empty DataFrame if no coins have data.
+        """
+        all_scores: Dict[str, Dict[str, float]] = {}
+        active_coins = list(jason_data.keys())
+
+        for coin in active_coins:
+            coin_ohlc = ohlc_data.get(coin)
+            coin_jason = jason_data.get(coin)
+            if coin_ohlc is None or coin_jason is None:
+                continue
+            if coin_ohlc.empty or coin_jason.empty:
+                continue
+
+            coin_scores: Dict[str, float] = {}
+            for func in self.trend_functions:
+                try:
+                    score_method = _TREND_FUNCTION_MAP.get(func)
+                    if score_method:
+                        score = score_method(
+                            coin_ohlc,
+                            coin_jason,
+                            self.half_life_weights,
+                            interval=self.interval,
+                        )
+                        coin_scores[func.value] = score
+                    else:
+                        coin_scores[func.value] = 0.0
+                except Exception as e:
+                    logger.warning("Error computing %s for %s: %s", func.value, coin, e)
+                    coin_scores[func.value] = 0.0
+
+            all_scores[coin] = coin_scores
+
+        if not all_scores:
+            return pd.DataFrame()
+
+        df = pd.DataFrame(all_scores).T
+        available_funcs = [f.value for f in self.trend_functions if f.value in df.columns]
+        if available_funcs:
+            df = df[available_funcs]
+
+        df_normalized = df.div(df.abs().max()).fillna(0)
+        df_normalized["Average Score"] = df_normalized.mean(axis=1)
+        return df_normalized.sort_values(by="Average Score", ascending=False).round(4)
+
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+def _slice_data_for_end_time(
+    data: Dict[str, pd.DataFrame],
+    start_time: pd.Timestamp,
+    end_time: pd.Timestamp,
+) -> Dict[str, pd.DataFrame]:
+    sliced: Dict[str, pd.DataFrame] = {}
+    for coin, df in data.items():
+        if df is None or df.empty:
+            continue
+        window = df[(df.index >= start_time) & (df.index <= end_time)]
+        if not window.empty:
+            sliced[coin] = window
+    return sliced
+
+
+def _calculate_market_trend_summary(
+    ranking_df: pd.DataFrame,
+    trend_df_t24: pd.DataFrame,
+    trend_df_t3d: pd.DataFrame,
+    trend_df_t7d: pd.DataFrame,
+) -> MarketTrendSummary:
+    market_average = float(ranking_df["Average Score"].mean())
+
+    if not trend_df_t24.empty and "Average Score" in trend_df_t24.columns:
+        delta_24h = market_average - float(trend_df_t24["Average Score"].mean())
+    else:
+        delta_24h = 0.0
+
+    if not trend_df_t3d.empty and "Average Score" in trend_df_t3d.columns:
+        delta_3d = market_average - float(trend_df_t3d["Average Score"].mean())
+    else:
+        delta_3d = 0.0
+
+    if not trend_df_t7d.empty and "Average Score" in trend_df_t7d.columns:
+        delta_7d = market_average - float(trend_df_t7d["Average Score"].mean())
+    else:
+        delta_7d = 0.0
+
+    return MarketTrendSummary(
+        market_trend=SummaryMetric(label="MARKET TREND", value=market_average),
+        delta_24h=SummaryMetric(label="Δ 24H", value=delta_24h),
+        delta_3d=SummaryMetric(label="Δ 3D", value=delta_3d),
+        delta_7d=SummaryMetric(label="Δ 7D", value=delta_7d),
+    )
+
+
+def _build_price_rows(
+    ohlc_data: Dict[str, pd.DataFrame],
+    ranking_index: pd.Index,
+    periods_24h: int,
+    periods_7d: int,
+) -> pd.DataFrame:
+    price_rows: Dict[str, dict] = {}
+    min_periods = max((2 * periods_24h), periods_7d) + 1 if periods_24h > 0 or periods_7d > 0 else 1
+
+    for coin in ranking_index:
+        coin_ohlc = ohlc_data.get(coin)
+        if coin_ohlc is not None and not coin_ohlc.empty and len(coin_ohlc) > min_periods:
+            close_series = coin_ohlc["close"]
+            last_price = close_series.iloc[-1]
+            price_24h_ago = close_series.iloc[-1 - periods_24h] if periods_24h > 0 else last_price
+            price_48h_ago = close_series.iloc[-1 - (2 * periods_24h)] if periods_24h > 0 else last_price
+            price_7d_ago = close_series.iloc[-1 - periods_7d] if periods_7d > 0 else last_price
+
+            price_rows[coin] = {
+                "Last Spot": last_price,
+                "24h Chg%": (last_price / price_24h_ago - 1) if price_24h_ago != 0 else 0.0,
+                "Prev. 24h Chg%": (price_24h_ago / price_48h_ago - 1) if price_48h_ago != 0 else 0.0,
+                "7d Chg%": (last_price / price_7d_ago - 1) if price_7d_ago != 0 else 0.0,
+            }
+            continue
+
+        price_rows[coin] = {
+            "Last Spot": coin_ohlc["close"].iloc[-1] if coin_ohlc is not None and not coin_ohlc.empty else np.nan,
+            "24h Chg%": np.nan,
+            "Prev. 24h Chg%": np.nan,
+            "7d Chg%": np.nan,
+        }
+
+    return pd.DataFrame.from_dict(price_rows, orient="index")
+
+
+def _build_chart_series(
+    ranking_df: pd.DataFrame,
+    ohlc_data: Dict[str, pd.DataFrame],
+    count: int,
+    plot_start: pd.Timestamp,
+    chart_title: str,
+    chart_subtitle: str,
+    worst: bool = False,
+) -> ChartData:
+    selected = (
+        ranking_df["Average Score"].nsmallest(count)
+        if worst
+        else ranking_df["Average Score"].nlargest(count)
+    )
+
+    series_payload: List[CoinSeries] = []
+    for coin, average_score in selected.items():
+        coin_ohlc = ohlc_data.get(coin)
+        if coin_ohlc is None or coin_ohlc.empty:
+            continue
+
+        prices = coin_ohlc["close"].loc[plot_start:]
+        if prices.empty:
+            continue
+
+        normalized_prices = (prices / prices.iloc[0]) * 100.0
+        series_payload.append(
+            CoinSeries(
+                coin=coin,
+                average_score=float(average_score),
+                series=normalized_prices,
+            )
+        )
+
+    return ChartData(
+        title=chart_title,
+        subtitle=chart_subtitle,
+        series=series_payload,
+    )
+
+
+# ============================================================================
+# PUBLIC ENTRY POINT
+# ============================================================================
+
+def compute_trend_analysis(
+    datasets: list[CoinDataset],
+    interval: JInterval,
+    start_date: pd.Timestamp,
+    end_date: pd.Timestamp,
+    top_n: int = 4,
+    plot_window_days: Optional[int] = None,
+    trend_functions: Optional[list[TrendFunction]] = None,
+) -> TrendAnalysisResult:
+    """Compute trend analysis across a set of coins.
+
+    Args:
+        datasets: List of CoinDataset, each containing a coin identifier,
+            OHLC klines DataFrame, and jason DataFrame.
+        interval: Data interval (e.g., JInterval.H4, JInterval.D1).
+        start_date: Start of the analysis window.
+        end_date: End of the analysis window.
+        top_n: Number of top/bottom coins to include in charts.
+        plot_window_days: Chart lookback window in days. If None, derived
+            from the analysis period (clamped to 7-30 days).
+        trend_functions: Subset of trend functions to compute. If None,
+            all 10 are computed.
+
+    Returns:
+        TrendAnalysisResult with summary metrics, charts, and ranking DataFrame.
+
+    Raises:
+        ValueError: If start_date > end_date.
+        InsufficientDataError: If no coins have enough data to produce results.
+
+    Note:
+        For meaningful historical delta metrics (24h, 3d, 7d), provide data
+        starting at least 42 days (7d * 5 lookback + 7d) before end_date.
+    """
+    if start_date > end_date:
+        raise ValueError("start_date must be before or equal to end_date")
+
+    trend_functions_to_use = trend_functions or list(TrendFunction)
+
+    # Convert datasets to dicts
+    ohlc_data: Dict[str, pd.DataFrame] = {ds.coin: ds.klines_df for ds in datasets}
+    jason_data: Dict[str, pd.DataFrame] = {ds.coin: ds.jason_df for ds in datasets}
+
+    analyzer = TrendAnalyzer(interval=interval, trend_functions=trend_functions_to_use)
+
+    # Period calculations
+    interval_td = interval.to_timedelta()
+    try:
+        periods_24h = int(pd.Timedelta("24h") / interval_td)
+    except ZeroDivisionError:
+        periods_24h = 0
+    try:
+        periods_7d = int(pd.Timedelta("7D") / interval_td)
+    except ZeroDivisionError:
+        periods_7d = 0
+
+    lookback_mult = pd.Timedelta("7D") * 5
+
+    # Historical snapshots
+    end_t24 = end_date - pd.Timedelta(days=1)
+    start_t24 = end_t24 - lookback_mult
+    trend_df_t24 = analyzer.run_analysis_from_data(
+        _slice_data_for_end_time(ohlc_data, start_t24, end_t24),
+        _slice_data_for_end_time(jason_data, start_t24, end_t24),
+    )
+    historical_ranks_t24 = (
+        trend_df_t24["Average Score"].rank(ascending=False).astype(int).rename("Rank_T24")
+        if not trend_df_t24.empty and "Average Score" in trend_df_t24.columns
+        else pd.Series(dtype=int, name="Rank_T24")
+    )
+
+    end_t3d = end_date - pd.Timedelta(days=3)
+    start_t3d = end_t3d - lookback_mult
+    trend_df_t3d = analyzer.run_analysis_from_data(
+        _slice_data_for_end_time(ohlc_data, start_t3d, end_t3d),
+        _slice_data_for_end_time(jason_data, start_t3d, end_t3d),
+    )
+
+    end_t7d = end_date - pd.Timedelta(days=7)
+    start_t7d = end_t7d - lookback_mult
+    trend_df_t7d = analyzer.run_analysis_from_data(
+        _slice_data_for_end_time(ohlc_data, start_t7d, end_t7d),
+        _slice_data_for_end_time(jason_data, start_t7d, end_t7d),
+    )
+    historical_ranks_t7d = (
+        trend_df_t7d["Average Score"].rank(ascending=False).astype(int).rename("Rank_T7d")
+        if not trend_df_t7d.empty and "Average Score" in trend_df_t7d.columns
+        else pd.Series(dtype=int, name="Rank_T7d")
+    )
+
+    # Check that at least one coin has data overlapping the requested window
+    sliced_for_window = _slice_data_for_end_time(ohlc_data, start_date, end_date)
+    if not sliced_for_window:
+        raise InsufficientDataError(
+            "No coins have data within the requested date range "
+            f"[{start_date}, {end_date}]."
+        )
+
+    # Current ranking
+    ranking_df = analyzer.run_analysis_from_data(ohlc_data, jason_data)
+    if ranking_df.empty:
+        raise InsufficientDataError("No coins have enough data to produce trend analysis results.")
+
+    current_ranks = ranking_df["Average Score"].rank(ascending=False).astype(int).rename("Rank_T0")
+    price_df = _build_price_rows(ohlc_data, ranking_df.index, periods_24h, periods_7d)
+
+    combined_df = pd.concat([price_df, ranking_df, current_ranks], axis=1)
+    combined_df = combined_df.join(historical_ranks_t24).join(historical_ranks_t7d)
+    combined_df["Rank Δ 24h"] = (combined_df["Rank_T24"] - combined_df["Rank_T0"]).fillna(0).astype(int)
+    combined_df["Rank Δ 7d"] = (combined_df["Rank_T7d"] - combined_df["Rank_T0"]).fillna(0).astype(int)
+
+    ordered_columns = [
+        "Last Spot",
+        "24h Chg%",
+        "Prev. 24h Chg%",
+        "7d Chg%",
+        "Rank Δ 24h",
+        "Rank Δ 7d",
+        "Average Score",
+        *[tf.value for tf in trend_functions_to_use],
+    ]
+    combined_df = combined_df.reindex(columns=[col for col in ordered_columns if col in combined_df.columns])
+
+    # Plot window
+    if plot_window_days is None:
+        analysis_period_days = max(0, (end_date.normalize() - start_date.normalize()).days + 1)
+        plot_window_days = max(7, min(30, analysis_period_days))
+    plot_label = f"{plot_window_days}d"
+
+    latest_timestamp = max(df.index.max() for df in ohlc_data.values() if df is not None and not df.empty)
+    plot_start = latest_timestamp - pd.Timedelta(days=plot_window_days)
+    subtitle = latest_timestamp.strftime("%Y-%m-%d %H:%M UTC")
+
+    return TrendAnalysisResult(
+        start_date=start_date.strftime("%Y-%m-%d"),
+        end_date=end_date.strftime("%Y-%m-%d"),
+        interval=interval,
+        generated_at=pd.Timestamp.now("UTC").to_pydatetime(),
+        as_of=latest_timestamp.to_pydatetime(),
+        top_n=top_n,
+        plot_window=PlotWindow(
+            label=plot_label,
+            start_timestamp=plot_start.to_pydatetime(),
+            end_timestamp=latest_timestamp.to_pydatetime(),
+        ),
+        summary=_calculate_market_trend_summary(
+            combined_df,
+            trend_df_t24=trend_df_t24,
+            trend_df_t3d=trend_df_t3d,
+            trend_df_t7d=trend_df_t7d,
+        ),
+        charts=TrendCharts(
+            spot_price_leaders=_build_chart_series(
+                ranking_df=combined_df,
+                ohlc_data=ohlc_data,
+                count=top_n,
+                plot_start=plot_start,
+                chart_title="Spot Price - Leaders",
+                chart_subtitle=subtitle,
+                worst=False,
+            ),
+            spot_price_laggers=_build_chart_series(
+                ranking_df=combined_df,
+                ohlc_data=ohlc_data,
+                count=top_n,
+                plot_start=plot_start,
+                chart_title="Spot Price - Laggers",
+                chart_subtitle=subtitle,
+                worst=True,
+            ),
+        ),
+        ranking=combined_df,
+    )