portfolio_analyzer/sd2/

features.rs

//! # Features: what SD v2 looks at
//!
//! Classic SD looked at the market through three keyholes: one compression
//! measurement (21 bars), one momentum gauge (the Awesome Oscillator), and a
//! stopwatch that either said "active" or "expired".  Each keyhole is where
//! one of the known weaknesses came from:
//!
//! | Weakness | Keyhole | What v2 adds |
//! | --- | --- | --- |
//! | Short squeezes are missed | A 21-bar Bollinger band needs ~21 quiet bars before it can shrink | A second, 10-bar compression gauge, plus a *continuous* squeeze depth `q` |
//! | Momentum is one-dimensional | AO only, and a single AO colour change ends the trade | A panel of seven momentum gauges, blended, and a flip that must persist |
//! | No time decay | Active is a yes/no switch | A smooth strength curve over the life of the fire, and stored squeeze *energy* |
//!
//! This module only *measures*.  It does not decide anything; `model.rs`
//! learns how much each measurement is worth, and `engine.rs` turns that
//! into the SD number.
//!
//! ## Squeeze depth `q`
//!
//! The classic tiers compare `SMA + 2σ` with `SMA + k·ATR`.  The SMAs cancel,
//! so the test is really `2σ ≤ k·ATR`, i.e. `q = 2σ/ATR ≤ k`.  Writing it this
//! way gives one continuous number: `q < 1` is a high squeeze, `q < 1.5` mid,
//! `q < 2` low, and *how far* below 2 tells you how tightly coiled price is.

use super::primitives::*;
use super::squeeze::{run_clock, ClockSeries};
use crate::indicators::smf_derivative;

/// Which compression gauge drives the squeeze clock.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CompressionMode {
    /// The paper: 21-bar bands only.
    Classic,
    /// Also listen to a 10-bar gauge, so a brief, deep squeeze registers its
    /// true (higher) tier instead of being averaged away by 21 bars.
    MultiScale,
}

/// How the clock decides "momentum flipped".
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FlipMode {
    /// The paper: any one-bar AO colour change.
    AoColour,
    /// The blended momentum changes sign *and stays changed for 2 bars*.
    BlendedPersistent,
}

/// Knobs that change how features are measured (not how they are weighted).
#[derive(Debug, Clone, Copy)]
pub struct FeatureConfig {
    pub compression: CompressionMode,
    pub flip: FlipMode,
}

impl Default for FeatureConfig {
    fn default() -> Self {
        Self { compression: CompressionMode::MultiScale, flip: FlipMode::BlendedPersistent }
    }
}

/// Names of the model inputs, in column order.  Keep in sync with
/// [`FeatureFrame::row`].
pub const FEATURE_NAMES: &[&str] = &[
    // Momentum panel (each squashed to (-1, 1)).
    "m_ao", "m_ttm", "m_macd", "m_roc", "m_rsi", "m_smf8", "m_trend", "m_tsmom",
    // Momentum blend and agreement.
    "m_blend", "m_agree",
    // The same blend, switched on only while a fired squeeze is still alive,
    // and shaped by the time-decay kernel.
    "fire_x_blend", "fire_x_decay_blend",
    // Squeeze structure (direction-free: they tell the model *how much*
    // to trust momentum, through the interactions below).
    "energy_x_blend", "depth_x_blend",
    // Mean-reversion / exhaustion: price far from its 21 EMA.
    "stretch",
    // Group B structure, kept from v1.
    "semi",
];

/// Equal default weights for the momentum blend, before any learning.
pub const DEFAULT_BLEND: [f64; 8] = [0.125; 8];

/// All measurements for one symbol, one entry per bar.
pub struct FeatureFrame {
    pub n: usize,
    pub close: Vec<f64>,
    pub atr: Vec<f64>,
    /// Daily volatility of log returns (20-bar), used to put moves in σ units.
    pub vol20: Vec<f64>,
    /// Noise-robust daily volatility: variance of overlapping 5-bar returns
    /// over 60 bars, ÷ 5.  A bad print adds the same error to a 1-bar and a
    /// 5-bar return, but the 5-bar return carries 5× the real variance, so
    /// the noise share drops ~5×.
    pub vol_robust: Vec<f64>,
    /// Six-month volatility: the level short-term volatility drifts back to.
    pub vol126: Vec<f64>,
    pub q21: Vec<f64>,
    pub q10: Vec<f64>,
    pub comp: Vec<u8>,
    pub clock: ClockSeries,
    /// Integrated squeeze depth over the current lifecycle (held after firing).
    pub energy: Vec<f64>,
    /// 0..1 percentile of 21-bar bandwidth within the last 252 bars (low = coiled).
    pub width_pct: Vec<f64>,
    /// Momentum panel, squashed, `[bar][component]`.
    pub mom: Vec<[f64; 8]>,
    pub blend: Vec<f64>,
    pub agree: Vec<f64>,
    /// Time-decay strength of the current fire, 0..1.
    pub decay: Vec<f64>,
    pub stretch: Vec<f64>,
    pub semi: Vec<f64>,
}

/// Classic tier from a continuous depth.
pub fn tier(q: f64) -> u8 {
    if !q.is_finite() {
        0
    } else if q <= 1.0 {
        3
    } else if q <= 1.5 {
        2
    } else if q <= 2.0 {
        1
    } else {
        0
    }
}

/// The time-decay kernel.
///
/// `phase = τ / θ` is how far through its expected life the move is.  The
/// curve stays at 1 for the first 1.5 expected lifetimes and then halves
/// every further θ bars (0.5 at phase 2.5, 0.25 at 3.5).  The shape is not a
/// guess: it is the measured profile of post-fire move size.
pub fn decay_kernel(phase: f64) -> f64 {
    if !phase.is_finite() || phase < 0.0 {
        return 0.0;
    }
    // Measured (see `sd_backtest anatomy`): move size is flat for the first
    // ~1.5 expected lifetimes and then fades.  Half-life after that: ~1θ.
    let x = (phase - 1.5).max(0.0);
    (-x * std::f64::consts::LN_2).exp()
}

impl FeatureFrame {
    pub fn compute(bars: &[OHLCV], cfg: FeatureConfig) -> Self {
        let n = bars.len();
        let close: Vec<f64> = bars.iter().map(|b| b.close).collect();
        let hl2: Vec<f64> = bars.iter().map(|b| (b.high + b.low) / 2.0).collect();
        let high: Vec<f64> = bars.iter().map(|b| b.high).collect();
        let low: Vec<f64> = bars.iter().map(|b| b.low).collect();
        let atr21 = atr(bars, 21);
        let atr10 = atr(bars, 10);
        let std21 = rolling_std(&close, 21);
        let std10 = rolling_std(&close, 10);
        let q21: Vec<f64> = (0..n).map(|i| 2.0 * std21[i] / atr21[i]).collect();
        let q10: Vec<f64> = (0..n).map(|i| 2.0 * std10[i] / atr10[i]).collect();
        let comp: Vec<u8> = (0..n)
            .map(|i| match cfg.compression {
                CompressionMode::Classic => tier(q21[i]),
                // The 10-bar gauge may *raise* the tier only while the 21-bar
                // gauge already sees some compression, or when it sees a deep
                // (high) squeeze on its own.  That keeps one quiet week from
                // inventing squeezes in a volatile market.
                CompressionMode::MultiScale => {
                    let (slow, fast) = (tier(q21[i]), tier(q10[i]));
                    if slow > 0 || fast == 3 { slow.max(fast) } else { slow }
                }
            })
            .collect();

        // ── Momentum panel ────────────────────────────────────────────────
        let ao: Vec<f64> = sma(&hl2, 5).iter().zip(sma(&hl2, 34)).map(|(a, b)| a - b).collect();
        let sma20 = sma(&close, 20);
        let (hh, ll) = (highest(&high, 20), lowest(&low, 20));
        let ttm_src: Vec<f64> =
            (0..n).map(|i| close[i] - ((hh[i] + ll[i]) / 2.0 + sma20[i]) / 2.0).collect();
        let ttm = linreg_value(&ttm_src, 20);
        let macd = macd_hist(&close);
        let roc = diff(&close, 10);
        let rsi14 = rsi(&close, 14);
        let ema8 = ema(&close, 8);
        let ema21 = ema(&close, 21);
        let d = |x: &[f64]| -> Vec<f64> {
            std::iter::once(0.0).chain(x.windows(2).map(|w| w[1] - w[0])).collect()
        };
        let smf8 = smf_derivative(&d(&ema8), 21);
        let smf_price = smf_derivative(&d(&close), 21);
        let smf21 = smf_derivative(&d(&ema21), 21);
        let logret: Vec<f64> = (0..n)
            .map(|i| if i == 0 { 0.0 } else { (close[i] / close[i - 1]).ln() })
            .collect();
        let vol20 = rolling_std(&logret, 20);
        let ret5: Vec<f64> = (0..n)
            .map(|i| if i >= 5 { (close[i] / close[i - 5]).ln() } else { f64::NAN })
            .collect();
        let vol_robust: Vec<f64> = rolling_std(&ret5, 60).iter().map(|v| v / 5f64.sqrt()).collect();
        let vol126 = rolling_std(&logret, 126);

        let mut mom = vec![[0.0; 8]; n];
        for i in 0..n {
            let a = atr21[i];
            let tsm = if i >= 126 && vol126[i] > 0.0 {
                (close[i] / close[i - 126]).ln() / (vol126[i] * 126f64.sqrt())
            } else {
                f64::NAN
            };
            // Each scale is roughly "one typical day's worth" for that gauge,
            // so a squashed value of ±0.76 means "one typical unit".
            mom[i] = [
                squash(ao[i] / a, 1.5),
                squash(ttm[i] / a, 1.0),
                squash(macd[i] / a, 0.25),
                squash(roc[i] / (a * 10f64.sqrt()), 0.8),
                squash((rsi14[i] - 50.0) / 50.0, 0.3),
                squash(smf8[i] / a, 0.15),
                squash((ema8[i] - ema21[i]) / a, 1.0),
                squash(tsm, 1.0),
            ];
        }
        let blend: Vec<f64> =
            mom.iter().map(|m| m.iter().zip(DEFAULT_BLEND).map(|(x, w)| x * w).sum()).collect();
        let agree: Vec<f64> = mom
            .iter()
            .map(|m| m.iter().map(|x| x.signum()).sum::<f64>() / m.len() as f64)
            .collect();

        // ── Squeeze clock ─────────────────────────────────────────────────
        let flip: Vec<bool> = match cfg.flip {
            FlipMode::AoColour => {
                let up = |i: usize| i >= 1 && ao[i] > ao[i - 1];
                let dn = |i: usize| i >= 1 && ao[i] < ao[i - 1];
                (0..n).map(|i| i >= 1 && ((up(i) && !up(i - 1)) || (dn(i) && !dn(i - 1)))).collect()
            }
            // A flip counts only once the blend has held its new sign for two
            // bars; a single noisy bar no longer ends the trade.
            FlipMode::BlendedPersistent => (0..n)
                .map(|i| {
                    i >= 2
                        && blend[i].signum() == blend[i - 1].signum()
                        && blend[i - 1].signum() != blend[i - 2].signum()
                })
                .collect(),
        };
        let clock = run_clock(&comp, &flip);

        // Stored energy: integrate (2 - q) over the squeeze, freeze it once
        // the squeeze fires, forget it when a new squeeze starts or the fire
        // is long over.
        let mut energy = vec![0.0; n];
        for i in 0..n {
            let prev = if i > 0 { energy[i - 1] } else { 0.0 };
            let depth = (2.0 - q21[i]).max(0.0).min(2.0) + 0.5 * (2.0 - q10[i]).max(0.0).min(2.0);
            energy[i] = if clock.sq_start[i] {
                depth
            } else if clock.is_fired[i] {
                if clock.bars_since_fired[i] as f64 > 3.0 * clock.theta[i].max(1.0) { 0.0 } else { prev }
            } else if comp[i] > 0 {
                prev + depth
            } else {
                0.0
            };
        }

        let width: Vec<f64> = (0..n).map(|i| std21[i] / close[i]).collect();
        let width_pct: Vec<f64> = (0..n)
            .map(|i| {
                if i < 252 || !width[i].is_finite() {
                    return f64::NAN;
                }
                let w = &width[i - 251..=i];
                w.iter().filter(|v| **v < width[i]).count() as f64 / 251.0
            })
            .collect();

        let decay: Vec<f64> = (0..n)
            .map(|i| {
                if !clock.is_fired[i] {
                    return 0.0;
                }
                decay_kernel(clock.bars_since_fired[i] as f64 / clock.theta[i].max(1.0))
            })
            .collect();

        let stretch: Vec<f64> = (0..n).map(|i| squash((close[i] - ema21[i]) / atr21[i], 3.0)).collect();
        let semi: Vec<f64> = (0..n)
            .map(|i| {
                let dist = (close[i] - ema21[i]).abs() / ema21[i];
                let exhausted = dist >= 0.005 && smf21[i] <= smf_price[i];
                if exhausted && close[i] < ema21[i] {
                    1.0
                } else if exhausted && close[i] > ema21[i] {
                    -1.0
                } else {
                    0.0
                }
            })
            .collect();

        Self {
            n,
            close,
            atr: atr21,
            vol20,
            vol_robust,
            vol126,
            q21,
            q10,
            comp,
            clock,
            energy,
            width_pct,
            mom,
            blend,
            agree,
            decay,
            stretch,
            semi,
        }
    }

    /// Bars before this index have unreliable warm-up values.
    pub const WARMUP: usize = 260;

    /// Is a fired squeeze still alive on bar `i`?
    pub fn fire_alive(&self, i: usize) -> bool {
        self.clock.is_active[i]
    }

    /// The model input row for bar `i`, in [`FEATURE_NAMES`] order.
    pub fn row(&self, i: usize) -> Vec<f64> {
        let m = &self.mom[i];
        let b = self.blend[i];
        let alive = if self.fire_alive(i) { 1.0 } else { 0.0 };
        let fired = if self.clock.is_fired[i] { 1.0 } else { 0.0 };
        let energy = squash(self.energy[i], 8.0);
        let depth = squash((2.0 - self.q21[i]).max(0.0), 1.0);
        let mut r = Vec::with_capacity(FEATURE_NAMES.len());
        r.extend_from_slice(m);
        r.push(b);
        r.push(self.agree[i]);
        r.push(alive * b);
        r.push(fired * self.decay[i] * b);
        r.push(energy * b);
        r.push(depth * b);
        r.push(self.stretch[i]);
        r.push(self.semi[i]);
        r
    }

    pub fn row_is_valid(&self, i: usize) -> bool {
        i >= Self::WARMUP && self.row(i).iter().all(|v| v.is_finite()) && self.atr[i] > 0.0
    }
}