jasonlib-dev 0.1.0__py3-none-any.whl

jasonlib/__init__.py

@@ -0,0 +1,53 @@
+"""jasonlib - Core JASON pivot-based feature computation library.
+
+Public API::
+
+    from jasonlib import compute_jason, compute_trend_analysis, compute_pivot_analysis
+    from jasonlib import JAssetClass, JInterval, TrendFunction, PivotSortOption
+    from jasonlib import CoinDataset, TrendAnalysisResult, PivotAnalysisResult
+"""
+
+from jasonlib._calculator import compute_jason
+from jasonlib._models import JAssetClass, JInterval
+from jasonlib._trend_analysis import compute_trend_analysis
+from jasonlib._trend_models import (
+    ChartData,
+    CoinDataset,
+    CoinSeries,
+    InsufficientDataError,
+    MarketTrendSummary,
+    PlotWindow,
+    SummaryMetric,
+    TrendAnalysisResult,
+    TrendCharts,
+    TrendFunction,
+)
+from jasonlib._pivot_models import (
+    PivotSortOption,
+    PivotAnalysisSummary,
+    PivotAnalysisParameters,
+    PivotAnalysisResult,
+)
+from jasonlib._pivot_analysis import compute_pivot_analysis
+
+__all__ = [
+    "compute_jason",
+    "compute_trend_analysis",
+    "JAssetClass",
+    "JInterval",
+    "TrendFunction",
+    "CoinDataset",
+    "InsufficientDataError",
+    "TrendAnalysisResult",
+    "PlotWindow",
+    "SummaryMetric",
+    "MarketTrendSummary",
+    "CoinSeries",
+    "ChartData",
+    "TrendCharts",
+    "compute_pivot_analysis",
+    "PivotSortOption",
+    "PivotAnalysisSummary",
+    "PivotAnalysisParameters",
+    "PivotAnalysisResult",
+]

jasonlib/_calculator.py

@@ -0,0 +1,248 @@
+"""Core JASON feature computation."""
+
+import numpy as np
+import pandas as pd
+from tqdm import tqdm
+
+from jasonlib._models import JAssetClass, JInterval
+from jasonlib._numba_kernels import _calculate_metrics_for_window
+from jasonlib._trading_calendar import (
+    TRADING_DAYS_PER_YEAR,
+    TRADING_HOURS_PER_DAY,
+    get_logger,
+    normalize_asset_class,
+)
+
+logger = get_logger("jasonlib.calculator")
+
+_JASON_COLUMNS = [
+    "high_vol",
+    "high_days",
+    "high_z",
+    "high_pivot",
+    "high_json2",
+    "high_json2_plus_1d",
+    "high_json2_plus_2d",
+    "last_fx",
+    "low_json2",
+    "low_json2_plus_1d",
+    "low_json2_plus_2d",
+    "low_pivot",
+    "low_z",
+    "low_days",
+    "low_vol",
+]
+
+_ROUNDING = {
+    "high_vol": 2,
+    "high_days": 1,
+    "high_z": 2,
+    "low_z": 2,
+    "low_days": 1,
+    "low_vol": 2,
+}
+
+
+def compute_jason(
+    df: pd.DataFrame,
+    interval: JInterval,
+    asset_class: JAssetClass,
+    lookback: int = 7,
+    n_pivots: int = 5,
+    min_days: int = 1,
+) -> pd.DataFrame:
+    """Compute JASON pivot-based features from OHLC candle data.
+
+    Identifies high/low pivot points over a rolling lookback window,
+    weights the most frequent pivots, and derives volatility-adjusted
+    support/resistance levels (JSON2), Z-scores, and days-since-pivot
+    metrics.
+
+    Args:
+        df: OHLCV candle data.  Must be datetime-indexed (UTC
+            ``DatetimeIndex``).  Required columns and dtypes:
+
+            ========  =========  ============================
+            Column    Dtype      Description
+            ========  =========  ============================
+            ``open``  float64    Opening price of the candle
+            ``high``  float64    Highest price in the candle
+            ``low``   float64    Lowest price in the candle
+            ``close`` float64    Closing price of the candle
+            ========  =========  ============================
+
+            Additional columns are ignored.  Rows must be sorted ascending
+            by timestamp; the function will sort if they are not.
+        interval: Candle size.  Determines the number of candles that fit
+            inside the *lookback* window.
+        asset_class: Trading calendar to use.  Determines days per year
+            and hours per day for annualization.  Required — no default.
+        lookback: Lookback period in trading days for pivot detection.
+            Default ``7``.
+        n_pivots: Number of top pivots (by frequency) to weight.
+            Default ``5``.
+        min_days: Minimum number of days for a pivot to be considered.
+            Default ``1``.
+
+    Returns:
+        ``pd.DataFrame`` indexed by ``DatetimeIndex`` (UTC), starting from
+        the first candle after the lookback window.  Columns:
+
+        ======================  =========  ==========================================
+        Column                  Dtype      Description
+        ======================  =========  ==========================================
+        ``high_vol``            float64    Annualized volatility (%) at high pivots
+        ``high_days``           float64    Trading days since the high pivot
+        ``high_z``              float64    Z-score from high pivot to last close
+        ``high_pivot``          float64    Weighted average high pivot price
+        ``high_json2``          float64    Support level (high_pivot * exp(-2*std))
+        ``high_json2_plus_1d``  float64    Support level projected +1 day
+        ``high_json2_plus_2d``  float64    Support level projected +2 days
+        ``last_fx``             float64    Last closing price at this timestamp
+        ``low_json2``           float64    Resistance level (low_pivot * exp(+2*std))
+        ``low_json2_plus_1d``   float64    Resistance level projected +1 day
+        ``low_json2_plus_2d``   float64    Resistance level projected +2 days
+        ``low_pivot``           float64    Weighted average low pivot price
+        ``low_z``               float64    Z-score from low pivot to last close
+        ``low_days``            float64    Trading days since the low pivot
+        ``low_vol``             float64    Annualized volatility (%) at low pivots
+        ======================  =========  ==========================================
+
+        Volatility and Z-score columns are rounded to 2 decimal places.
+        Days columns are rounded to 1 decimal place.
+    """
+    if df.empty:
+        return pd.DataFrame()
+
+    df = df.sort_index()
+
+    normalized_ac = normalize_asset_class(asset_class)
+    days_in_year = float(TRADING_DAYS_PER_YEAR[normalized_ac])
+    hours_per_day = TRADING_HOURS_PER_DAY[normalized_ac]
+    seconds_per_trading_day = hours_per_day * 3600
+
+    # Quadratic variation for volatility estimation
+    m_big = np.log(df["high"] / df["open"])
+    m_small = np.log(df["low"] / df["open"])
+    x = np.log(df["close"] / df["open"])
+    qv_series = (
+        0.511 * (m_big - m_small) ** 2
+        - 0.019 * (x * (m_big + m_small) - 2 * m_big * m_small)
+        - 0.383 * x**2
+    )
+
+    highs = df["high"].to_numpy(dtype=np.float64)
+    lows = df["low"].to_numpy(dtype=np.float64)
+    closes = df["close"].to_numpy(dtype=np.float64)
+
+    candle_seconds = interval.seconds
+
+    if normalized_ac == JAssetClass.CRYPTO:
+        lookback_candles = int(lookback * 24 * 3600 // candle_seconds)
+    else:
+        lookback_candles = int(
+            lookback * seconds_per_trading_day // candle_seconds
+        )
+
+    window_size = lookback_candles + 1
+
+    s_in_year = days_in_year * seconds_per_trading_day
+    min_days_in_years = (min_days / days_in_year) - (candle_seconds / s_in_year)
+
+    qv_values = qv_series.to_numpy(dtype=np.float64)
+
+    t_seconds = np.arange(
+        window_size * candle_seconds, 0, -candle_seconds, dtype=np.float64
+    )
+    t_seconds = np.maximum(t_seconds, candle_seconds)
+    relative_time_in_years = t_seconds / s_in_year
+
+    num_points = len(df)
+    results: list[tuple] = []
+
+    for i in tqdm(
+        range(lookback_candles, num_points),
+        desc="Computing JASON",
+        leave=False,
+    ):
+        start_idx = i - lookback_candles
+        end_idx = i + 1
+
+        qv_window = qv_values[start_idx:end_idx]
+        qv_sum_rev = np.cumsum(qv_window[::-1])[::-1]
+        w_sum_rev = np.arange(len(qv_window), 0, -1, dtype=np.float64)
+        vols_window = np.sqrt(
+            (qv_sum_rev * s_in_year) / (w_sum_rev * candle_seconds)
+        )
+
+        res_tuple = _calculate_metrics_for_window(
+            highs[start_idx:end_idx],
+            lows[start_idx:end_idx],
+            closes[start_idx:end_idx],
+            vols_window,
+            relative_time_in_years,
+            n_pivots,
+            min_days_in_years,
+            days_in_year,
+        )
+        results.append(res_tuple)
+
+    if not results:
+        return pd.DataFrame()
+
+    result_df = pd.DataFrame(
+        results, index=df.index[lookback_candles:], columns=_JASON_COLUMNS
+    )
+    result_df =  result_df.round(_ROUNDING)
+    result_df = _calculate_ztv(result_df)
+    return result_df
+
+
+
+
+# ============================================================================
+# ZTV AND LATEST METRICS
+# ============================================================================
+
+def _calculate_ztv(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Calculates all ZTV and Days metrics and returns a single DataFrame.
+
+    ZTV (Z-Time-Volatility) is a conviction score combining Z-Score, Time, and Volatility.
+    It measures the total power of a price move as a percentage of theoretical maximum.
+
+    Args:
+        jason_df: DataFrame with JASON features including:
+            - high_z, low_z: Z-scores
+            - high_vol, low_vol: Volatility at pivots
+            - high_days, low_days: Days since pivots
+
+    Returns:
+        DataFrame with additional columns:
+            - high_ztv, low_ztv: Raw ZTV values
+            - high_ztv_ratio, low_ztv_ratio: ZTV as ratio of max (0-1)
+            - high_days_ratio, low_days_ratio: Days as ratio of max (0-1)
+    """
+    # if jason_df.empty:
+    #     return pd.DataFrame()
+
+    # df = jason_df.copy()
+
+
+    # ZTV Metrics Logic
+    MAX_Z = 2.5
+    MAX_DAYS_ZTV = 4.0
+    MAX_VOL = 100.0
+    max_ztv = MAX_VOL * MAX_Z * np.sqrt(MAX_DAYS_ZTV)
+
+    df['high_ztv'] = df['high_z'] * df['high_vol'] * np.sqrt(df['high_days'].astype(float))
+    df['low_ztv'] = df['low_z'] * df['low_vol'] * np.sqrt(df['low_days'].astype(float))
+    df['high_ztv_ratio'] = (df['high_ztv'] / max_ztv).clip(0, 1)
+    df['low_ztv_ratio'] = (df['low_ztv'] / max_ztv).clip(0, 1)
+
+    # Days Metrics Logic
+    MAX_DAYS_RATIO = 5.0
+    df['high_days_ratio'] = (df['high_days'] / MAX_DAYS_RATIO).clip(0, 1)
+    df['low_days_ratio'] = (df['low_days'] / MAX_DAYS_RATIO).clip(0, 1)
+
+    return df

jasonlib/_math.py

@@ -0,0 +1,52 @@
+"""Sigmoid utility functions for trend score calculations."""
+
+import numpy as np
+import pandas as pd
+
+
+def sigmoid_z(x: pd.Series, threshold: float = 2.0, k: float = 10.0) -> pd.Series:
+    """Apply a sigmoid function centered around a threshold.
+
+    Args:
+        x: Input Series.
+        threshold: Center point of the sigmoid.
+        k: Steepness factor.
+
+    Returns:
+        Sigmoid-transformed Series with same index.
+    """
+    numeric_x = x.astype(float).to_numpy()
+    result = 1 / (1 + np.exp(-k * (numeric_x - threshold)))
+    return pd.Series(result, index=x.index)
+
+
+def sigmoid_diff(x: pd.Series, threshold: float = 1.0, k: float = 10.0) -> pd.Series:
+    """Apply a differential sigmoid creating symmetric positive/negative mapping.
+
+    Args:
+        x: Input Series.
+        threshold: Threshold for the differential.
+        k: Steepness factor.
+
+    Returns:
+        Differential sigmoid-transformed Series with same index.
+    """
+    numeric_x = x.astype(float).to_numpy()
+    result = 1 + 1 / (1 + np.exp(-k * (numeric_x - threshold))) - 1 / (1 + np.exp(-k * (-numeric_x + threshold)))
+    return pd.Series(result, index=x.index)
+
+
+def sigmoid_vol(x: pd.Series, hist_vol: float = 50.0, k: float = 0.2) -> pd.Series:
+    """Apply a sigmoid function for volatility weighting.
+
+    Args:
+        x: Input Series of volatility values.
+        hist_vol: Historical volatility center point.
+        k: Steepness factor.
+
+    Returns:
+        Sigmoid-weighted Series with same index.
+    """
+    numeric_x = x.astype(float).to_numpy()
+    result = 1 / (1 + np.exp(-k * (numeric_x - hist_vol)))
+    return pd.Series(result, index=x.index)

jasonlib/_models.py

@@ -0,0 +1,62 @@
+"""JASON domain model enums."""
+
+from enum import Enum
+
+import pandas as pd
+
+
+class JAssetClass(str, Enum):
+    """Supported asset classes for JASON calculations.
+
+    Determines the trading calendar used for time-aware computations:
+    - CRYPTO: 365 days/year, 24 hours/day
+    - EQUITY: 252 trading days/year, 6.5 hours/day (US market hours)
+    - COMMOD: 252 trading days/year, 23 hours/day (CME Globex)
+    - FX: 252 trading days/year, 23 hours/day (CME Globex)
+    - EQUITY_IDX: 252 trading days/year, 23 hours/day (CME Globex)
+    """
+
+    CRYPTO = "CRYPTO"
+    FX = "FX"
+    COMMOD = "COMMOD"
+    EQUITIES = "EQUITIES"
+    EQUITY_IDX = "EQUITY_IDX"
+
+
+_INTERVAL_SECONDS = {
+    "1m": 60,
+    "5m": 300,
+    "15m": 900,
+    "30m": 1800,
+    "1h": 3600,
+    "4h": 14400,
+    "12h": 43200,
+    "1d": 86400,
+}
+
+
+class JInterval(str, Enum):
+    """Supported candle intervals for JASON calculations.
+
+    Uses MetaTrader-style naming: M for minutes, H for hours, D for days.
+    Each member's string value is the compact interval notation (e.g. "1h").
+    Use the ``seconds`` property to get the candle duration in seconds.
+    """
+
+    M1 = "1m"
+    M5 = "5m"
+    M15 = "15m"
+    M30 = "30m"
+    H1 = "1h"
+    H4 = "4h"
+    H12 = "12h"
+    D1 = "1d"
+
+    @property
+    def seconds(self) -> int:
+        """Return candle duration in seconds."""
+        return _INTERVAL_SECONDS[self.value]
+
+    def to_timedelta(self) -> pd.Timedelta:
+        """Convert interval to pandas Timedelta."""
+        return pd.Timedelta(seconds=self.seconds)

jasonlib/_numba_kernels.py

@@ -0,0 +1,195 @@
+"""Numba JIT-compiled computational kernels for JASON feature calculation."""
+
+from typing import Tuple
+
+import numpy as np
+from numba import jit
+
+
+@jit(nopython=True, cache=True)
+def _unique_with_counts(arr: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+    """Numba-compatible implementation of np.unique with return_counts=True.
+
+    Args:
+        arr: Input array to find unique values in.
+
+    Returns:
+        Tuple of (unique_values, counts).
+    """
+    if arr.size == 0:
+        return np.empty(0, dtype=arr.dtype), np.empty(0, dtype=np.int64)
+    a = np.sort(arr)
+    mask = np.empty(a.shape, dtype=np.bool_)
+    mask[:1] = True
+    mask[1:] = a[1:] != a[:-1]
+    unique_vals = a[mask]
+    unique_indices = np.nonzero(mask)[0]
+    counts = np.diff(np.append(unique_indices, a.size))
+    return unique_vals, counts
+
+
+@jit(nopython=True, cache=True)
+def _calculate_metrics_for_window(
+    highs: np.ndarray,
+    lows: np.ndarray,
+    closes: np.ndarray,
+    vols: np.ndarray,
+    time_in_years: np.ndarray,
+    n_pivots: int,
+    min_days_in_years: float,
+    days_in_year: float,
+) -> Tuple:
+    """Calculate JASON metrics for a single lookback window.
+
+    Identifies high/low pivot points by frequency, weights the top N pivots,
+    and computes Z-scores, days-since-pivot, volatility, and JSON2
+    (volatility-adjusted support/resistance) levels.
+
+    Args:
+        highs: High prices for the window.
+        lows: Low prices for the window.
+        closes: Close prices for the window.
+        vols: Annualized volatility values for the window.
+        time_in_years: Relative time array in years for the window.
+        n_pivots: Number of top pivots to consider.
+        min_days_in_years: Minimum days threshold in years.
+        days_in_year: Trading days per year (365 for crypto, 252 for equities).
+
+    Returns:
+        Tuple of 15 float values:
+            (high_vol, high_days, high_z, high_pivot, high_json2,
+             high_json2_plus_1d, high_json2_plus_2d, last_close, low_json2,
+             low_json2_plus_1d, low_json2_plus_2d, low_pivot, low_z,
+             low_days, low_vol)
+    """
+    window_size = len(highs)
+    last_close = closes[-1]
+    high_pivot_indices = np.empty(window_size, dtype=np.int64)
+    low_pivot_indices = np.empty(window_size, dtype=np.int64)
+    last_max_idx = window_size - 1
+    last_min_idx = window_size - 1
+
+    for i in range(window_size - 1, -1, -1):
+        if highs[i] > highs[last_max_idx]:
+            last_max_idx = i
+        if lows[i] < lows[last_min_idx]:
+            last_min_idx = i
+        high_pivot_indices[i] = last_max_idx
+        low_pivot_indices[i] = last_min_idx
+
+    valid_pivot_mask = time_in_years > min_days_in_years
+    top_n_h_indices, h_weights = np.empty(0, dtype=np.int64), np.empty(
+        0, dtype=np.int64
+    )
+    h_pivots = high_pivot_indices[valid_pivot_mask]
+
+    if len(h_pivots) > 0:
+        unique_h_pivots, h_counts = _unique_with_counts(h_pivots)
+        h_sorted_indices = np.argsort(h_counts)[::-1][:n_pivots]
+        top_n_h_indices = unique_h_pivots[h_sorted_indices]
+        h_weights = h_counts[h_sorted_indices]
+
+    top_n_l_indices, l_weights = np.empty(0, dtype=np.int64), np.empty(
+        0, dtype=np.int64
+    )
+    l_pivots = low_pivot_indices[valid_pivot_mask]
+
+    if len(l_pivots) > 0:
+        unique_l_pivots, l_counts = _unique_with_counts(l_pivots)
+        l_sorted_indices = np.argsort(l_counts)[::-1][:n_pivots]
+        top_n_l_indices = unique_l_pivots[l_sorted_indices]
+        l_weights = l_counts[l_sorted_indices]
+
+    h_ave_pivot, h_ave_days, h_ave_vol, h_ave_z = 0.0, 0.0, 0.0, 0.0
+    h_ave_json2, h_ave_json2_plus1d, h_ave_json2_plus2d = 0.0, 0.0, 0.0
+
+    if len(top_n_h_indices) > 0:
+        total_h_weight = np.sum(h_weights)
+        if total_h_weight > 0:
+            for i in range(len(top_n_h_indices)):
+                idx, weight = top_n_h_indices[i], h_weights[i]
+                pivot_high, pivot_vol = highs[idx], vols[idx]
+                pivot_time = max(time_in_years[idx], 1.0 / days_in_year)
+                std_dev = pivot_vol * np.sqrt(pivot_time)
+                # TODO: Workaround as current model crushes when high==low for a candle
+                std_dev = max(std_dev, 0.0000000001)
+                h_ave_pivot += pivot_high * weight
+                h_ave_days += time_in_years[idx] * days_in_year * weight
+                h_ave_vol += pivot_vol * weight
+                h_ave_z += np.log(pivot_high / last_close) / std_dev * weight
+                h_ave_json2 += pivot_high * np.exp(-2.0 * std_dev) * weight
+                std_dev_plus1d = pivot_vol * np.sqrt(
+                    pivot_time + 1.0 / days_in_year
+                )
+                h_ave_json2_plus1d += (
+                    pivot_high * np.exp(-2.0 * std_dev_plus1d) * weight
+                )
+                std_dev_plus2d = pivot_vol * np.sqrt(
+                    pivot_time + 2.0 / days_in_year
+                )
+                h_ave_json2_plus2d += (
+                    pivot_high * np.exp(-2.0 * std_dev_plus2d) * weight
+                )
+            h_ave_pivot /= total_h_weight
+            h_ave_days /= total_h_weight
+            h_ave_vol /= total_h_weight
+            h_ave_z /= total_h_weight
+            h_ave_json2 /= total_h_weight
+            h_ave_json2_plus1d /= total_h_weight
+            h_ave_json2_plus2d /= total_h_weight
+
+    l_ave_pivot, l_ave_days, l_ave_vol, l_ave_z = 0.0, 0.0, 0.0, 0.0
+    l_ave_json2, l_ave_json2_plus1d, l_ave_json2_plus2d = 0.0, 0.0, 0.0
+
+    if len(top_n_l_indices) > 0:
+        total_l_weight = np.sum(l_weights)
+        if total_l_weight > 0:
+            for i in range(len(top_n_l_indices)):
+                idx, weight = top_n_l_indices[i], l_weights[i]
+                pivot_low, pivot_vol = lows[idx], vols[idx]
+                pivot_time = max(time_in_years[idx], 1.0 / days_in_year)
+                std_dev = pivot_vol * np.sqrt(pivot_time)
+                # TODO: Workaround as current model crushes when high==low for a candle
+                std_dev = max(std_dev, 0.0000000001)
+                l_ave_pivot += pivot_low * weight
+                l_ave_days += time_in_years[idx] * days_in_year * weight
+                l_ave_vol += pivot_vol * weight
+                l_ave_z += np.log(last_close / pivot_low) / std_dev * weight
+                l_ave_json2 += pivot_low * np.exp(2.0 * std_dev) * weight
+                std_dev_plus1d = pivot_vol * np.sqrt(
+                    pivot_time + 1.0 / days_in_year
+                )
+                l_ave_json2_plus1d += (
+                    pivot_low * np.exp(2.0 * std_dev_plus1d) * weight
+                )
+                std_dev_plus2d = pivot_vol * np.sqrt(
+                    pivot_time + 2.0 / days_in_year
+                )
+                l_ave_json2_plus2d += (
+                    pivot_low * np.exp(2.0 * std_dev_plus2d) * weight
+                )
+            l_ave_pivot /= total_l_weight
+            l_ave_days /= total_l_weight
+            l_ave_vol /= total_l_weight
+            l_ave_z /= total_l_weight
+            l_ave_json2 /= total_l_weight
+            l_ave_json2_plus1d /= total_l_weight
+            l_ave_json2_plus2d /= total_l_weight
+
+    return (
+        h_ave_vol * 100,
+        h_ave_days,
+        h_ave_z,
+        h_ave_pivot,
+        h_ave_json2,
+        h_ave_json2_plus1d,
+        h_ave_json2_plus2d,
+        last_close,
+        l_ave_json2,
+        l_ave_json2_plus1d,
+        l_ave_json2_plus2d,
+        l_ave_pivot,
+        l_ave_z,
+        l_ave_days,
+        l_ave_vol * 100,
+    )