jasonlib-dev 0.1.0__py3-none-any.whl

jasonlib/_trend_models.py

@@ -0,0 +1,165 @@
+"""Trend analysis data models, enums, and constants."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+import pandas as pd
+from pydantic import BaseModel, ConfigDict
+
+from jasonlib._models import JInterval
+
+
+class TrendFunction(str, Enum):
+    """Available trend score functions.
+
+    Each member's value is the human-readable score name used as
+    DataFrame column headers and display labels.
+    """
+
+    LOG_RETURNS = "Log Returns"
+    Z_SCORE_ABOVE_THRESHOLD = "Z-Score > Threshold"
+    Z_SCORE_LOW_VOL = "Z-Score Low Vol"
+    AVG_Z_DIFF = "Avg Z-Diff"
+    Z_DIFF_ABOVE_THRESHOLD = "Z-Diff > Threshold"
+    PIVOTS_DIFFERENCE = "Pivots Difference"
+    TIME_SINCE_PIVOTS = "Time Since Pivots"
+    OBV_MOMENTUM = "OBV Momentum"
+    TREND_EFFICIENCY = "Trend Efficiency"
+    VOL_RETURN_CORRELATION = "Vol-Return Correlation"
+
+
+class InsufficientDataError(Exception):
+    """Raised when there is not enough data to compute trend analysis."""
+
+    pass
+
+
+class BaseModelWithPandasFields(BaseModel):
+    """Base model that allows pandas types as fields."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class CoinDataset(BaseModelWithPandasFields):
+    """Input container for a single coin's data.
+
+    Attributes:
+        coin: Coin identifier (e.g. "BTCUSDT").
+        klines_df: OHLC DataFrame with columns: open, high, low, close, volume.
+            DatetimeIndex, UTC-aware.
+        jason_df: JASON features DataFrame with columns: high_z, low_z, high_vol,
+            low_vol, high_days, low_days, high_pivot, low_pivot.
+            DatetimeIndex, UTC-aware.
+    """
+
+    coin: str
+    klines_df: pd.DataFrame
+    jason_df: pd.DataFrame
+
+
+class PlotWindow(BaseModel):
+    """Chart plot window time range."""
+
+    label: str
+    start_timestamp: datetime
+    end_timestamp: datetime
+
+
+class SummaryMetric(BaseModel):
+    """A labelled metric value for market trend summary."""
+
+    label: str
+    value: float
+
+
+class MarketTrendSummary(BaseModel):
+    """Market-wide trend summary with current value and historical deltas."""
+
+    market_trend: SummaryMetric
+    delta_24h: SummaryMetric
+    delta_3d: SummaryMetric
+    delta_7d: SummaryMetric
+
+
+class CoinSeries(BaseModelWithPandasFields):
+    """Normalized price series for a single coin in a chart.
+
+    Attributes:
+        coin: Coin identifier.
+        average_score: The coin's average trend score.
+        series: Datetime-indexed pandas Series of normalized prices (base 100).
+    """
+
+    coin: str
+    average_score: float
+    series: pd.Series
+
+
+class ChartData(BaseModelWithPandasFields):
+    """Chart payload with title and coin series."""
+
+    title: str
+    subtitle: str
+    series: list[CoinSeries]
+
+
+class TrendCharts(BaseModelWithPandasFields):
+    """Leader and lagger chart data."""
+
+    spot_price_leaders: ChartData
+    spot_price_laggers: ChartData
+
+
+class TrendAnalysisResult(BaseModelWithPandasFields):
+    """Complete result of a trend analysis computation.
+
+    Attributes:
+        start_date: Analysis window start (YYYY-MM-DD).
+        end_date: Analysis window end (YYYY-MM-DD).
+        interval: Candle interval used.
+        generated_at: Timestamp when the analysis was generated.
+        as_of: Timestamp of the most recent data point.
+        top_n: Number of top/bottom coins in charts.
+        plot_window: Chart time range.
+        summary: Market-wide trend summary.
+        charts: Leader and lagger charts.
+        ranking: DataFrame with columns for price changes, rank deltas,
+            Average Score, and individual trend function scores.
+            Index is coin identifiers.
+    """
+
+    start_date: str
+    end_date: str
+    interval: JInterval
+    generated_at: datetime
+    as_of: datetime
+    top_n: int
+    plot_window: PlotWindow
+    summary: MarketTrendSummary
+    charts: TrendCharts
+    ranking: pd.DataFrame
+
+
+TREND_COLUMN_LABELS: dict[str, str] = {
+    "coin": "Coin",
+    "last_spot": "Last Spot",
+    "change_24h": "24h Chg%",
+    "previous_change_24h": "Prev. 24h Chg%",
+    "change_7d": "7d Chg%",
+    "rank_delta_24h": "Rank Δ 24h",
+    "rank_delta_7d": "Rank Δ 7d",
+    "average_score": "Average Score",
+    "Log Returns": "Log Returns",
+    "Z-Score > Threshold": "Direct. Extension",
+    "Z-Score Low Vol": "Vol Cone Exp.",
+    "Avg Z-Diff": "Var. Diff.",
+    "Z-Diff > Threshold": "Adj. Var. Diff.",
+    "Pivots Difference": "Pivots Difference",
+    "Time Since Pivots": "Time in Trend",
+    "OBV Momentum": "OBV Momentum",
+    "Trend Efficiency": "Trend Efficiency",
+    "Vol-Return Correlation": "Vol-Return Correlation",
+}

jasonlib_dev-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: jasonlib-dev
+Version: 0.1.0
+Summary: Core JASON pivot-based feature computation library
+Requires-Python: >=3.13
+Requires-Dist: numba<0.63.0,>=0.62.1
+Requires-Dist: numpy<2.4.0,>=2.3.0
+Requires-Dist: pandas<4.0.0,>=3.0.1
+Requires-Dist: pydantic<3.0.0,>=2.11.0
+Requires-Dist: tqdm<5.0.0,>=4.67.1

jasonlib_dev-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+jasonlib/__init__.py,sha256=Jke729kx0ryB6fv4nbAmtqCEiVp_tPGKgtmhQFHmjIk,1434
+jasonlib/_calculator.py,sha256=g7XhsH_swuOEguk3TncQorwb7mpTA2hHuivFAVODDjk,9010
+jasonlib/_math.py,sha256=fi54oDdcOCp6Pr6AfXJhL64P6DuFypkNNrzR0vxmbEU,1709
+jasonlib/_models.py,sha256=AUIh1GWr2YwbsSvsufJAD17XXidyZmCdUnKpilbUVWQ,1600
+jasonlib/_numba_kernels.py,sha256=5qnc2N8xkqw-9vg3okyUhNB6YbBZNXf4P2UUrZN9SN4,7756
+jasonlib/_pivot_analysis.py,sha256=cc8h61aPnQbBXwlnysmITnJ69SjdxRVW6hRQIDz2yuY,11875
+jasonlib/_pivot_models.py,sha256=9PjurXotmNUyJROrq8PGWsaPZJgKrin90OfeGBCwsYA,1136
+jasonlib/_trading_calendar.py,sha256=KgfvTg6VAQdy5tLJjnioBLy6bZJ4wF9TyJIylUSoYMA,2950
+jasonlib/_trend_analysis.py,sha256=GV4iOLrR71gI2LoZt8CvX_b947cmW9YClvxWlYm3Z30,23469
+jasonlib/_trend_models.py,sha256=Msgmj3rsvTMXvpebt2yHv3r5lBV7SOx6ngn4_mJs_uQ,4806
+jasonlib_dev-0.1.0.dist-info/METADATA,sha256=CcO9000i6sQ5LJ8Dh0EODg5_u3xUCpl4FFQpan0YdRk,322
+jasonlib_dev-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+jasonlib_dev-0.1.0.dist-info/RECORD,,

jasonlib_dev-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any