feat(family-15): add 17 risk/performance metrics

CHANGELOG.md

@@ -8,6 +8,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **Family 15 — Risk / Performance metrics (17 new indicators).** Implemented
+  pragmatically as standard `Indicator`s rather than a separate
+  `wickra-metrics` crate; the input is a scalar `f64` per bar (period return,
+  equity sample, or trade P&L depending on the metric).
+  - **Scalar `Indicator<f64>` — 14 metrics:** Sharpe Ratio, Sortino Ratio,
+    Calmar Ratio, Omega Ratio, Max Drawdown (rolling), Average Drawdown,
+    Drawdown Duration (time-under-water), Pain Index, Value at Risk
+    (historical, linear-interpolated percentile), Conditional Value at Risk
+    (Expected Shortfall), Profit Factor, Gain/Loss Ratio, Recovery Factor,
+    Kelly Criterion.
+  - **Two-series `Indicator<(f64, f64)>` — 3 metrics on `(asset_return,
+    benchmark_return)` pairs:** Treynor Ratio, Information Ratio,
+    Jensen's Alpha (CAPM).
 - **Candlestick patterns family (15 indicators).** A new "Candlestick
   Patterns" family covers the standard 1- to 3-bar reversal and
   continuation shapes: `Doji`, `Hammer`, `InvertedHammer`, `HangingMan`,

README.md

@@ -109,7 +109,7 @@ python -m benchmarks.compare_libraries
 
 ## Indicators
 
-196 streaming-first indicators across fifteen families. Every one passes the
+213 streaming-first indicators across sixteen families. Every one passes the
 `batch == streaming` equivalence test, reference-value tests, and reset
 semantics tests.
 
@@ -130,6 +130,7 @@ semantics tests.
 | Ichimoku & Charts    | Ichimoku Kinko Hyo (Tenkan, Kijun, Senkou A/B, Chikou), Heikin-Ashi |
 | Candlestick Patterns | Doji, Hammer, Inverted Hammer, Hanging Man, Shooting Star, Engulfing, Harami, Morning/Evening Star, Three White Soldiers/Black Crows, Piercing Line/Dark Cloud Cover, Marubozu, Tweezer, Spinning Top, Three Inside Up/Down, Three Outside Up/Down |
 | Market Profile       | Value Area (POC / VAH / VAL), Initial Balance, Opening Range |
+| Risk / Performance   | Sharpe Ratio, Sortino Ratio, Calmar Ratio, Omega Ratio, Max Drawdown, Average Drawdown, Drawdown Duration, Pain Index, Value at Risk, Conditional Value at Risk (CVaR), Profit Factor, Gain/Loss Ratio, Recovery Factor, Kelly Criterion, Treynor Ratio, Information Ratio, Alpha (Jensen) |
 
 Adding a new indicator means implementing one trait in Rust; all four bindings
 inherit it automatically.
@@ -202,7 +203,7 @@ A Python live-trading example using the public `websockets` package lives at
 ```
 wickra/
 ├── crates/
-│   ├── wickra-core/         core engine + all 196 indicators
+│   ├── wickra-core/         core engine + all 213 indicators
 │   ├── wickra/              top-level facade crate (publishes on crates.io) + benches/
 │   └── wickra-data/         CSV reader, tick aggregator, live exchange feeds
 ├── bindings/

bindings/node/__tests__/indicators.test.js

@@ -17,6 +17,7 @@ const open = close.map((c) => c - 0.5);
 
 function eq(a, b) {
   if (Number.isNaN(a)) return Number.isNaN(b);
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return a === b;
   return Math.abs(a - b) < 1e-9;
 }
 
@@ -102,8 +103,46 @@ const scalarFactories = {
   MedianAbsoluteDeviation: () => new wickra.MedianAbsoluteDeviation(20),
   Autocorrelation: () => new wickra.Autocorrelation(20, 1),
   HurstExponent: () => new wickra.HurstExponent(40, 4),
+  // Family 15 — Risk / Performance metrics (scalar f64 input).
+  SharpeRatio: () => new wickra.SharpeRatio(20, 0),
+  SortinoRatio: () => new wickra.SortinoRatio(20, 0),
+  CalmarRatio: () => new wickra.CalmarRatio(20),
+  OmegaRatio: () => new wickra.OmegaRatio(20, 0),
+  MaxDrawdown: () => new wickra.MaxDrawdown(20),
+  AverageDrawdown: () => new wickra.AverageDrawdown(20),
+  DrawdownDuration: () => new wickra.DrawdownDuration(),
+  PainIndex: () => new wickra.PainIndex(20),
+  ValueAtRisk: () => new wickra.ValueAtRisk(20, 0.95),
+  ConditionalValueAtRisk: () => new wickra.ConditionalValueAtRisk(20, 0.95),
+  ProfitFactor: () => new wickra.ProfitFactor(20),
+  GainLossRatio: () => new wickra.GainLossRatio(20),
+  RecoveryFactor: () => new wickra.RecoveryFactor(),
+  KellyCriterion: () => new wickra.KellyCriterion(20),
 };
 
+// --- Two-series (asset, benchmark) ratio indicators ---
+
+const ratioPairFactories = {
+  TreynorRatio: () => new wickra.TreynorRatio(20, 0),
+  InformationRatio: () => new wickra.InformationRatio(20),
+  Alpha: () => new wickra.Alpha(20, 0),
+};
+
+const asset = Array.from({ length: N }, (_, i) => 0.001 + Math.sin(i * 0.15) * 0.01);
+const bench = Array.from({ length: N }, (_, i) => 0.001 + Math.sin(i * 0.15) * 0.007);
+
+for (const [name, make] of Object.entries(ratioPairFactories)) {
+  test(`${name}: streaming update matches batch (pair)`, () => {
+    const batch = make().batch(asset, bench);
+    const streaming = make();
+    assert.equal(batch.length, N);
+    for (let i = 0; i < N; i++) {
+      const s = num(streaming.update(asset[i], bench[i]));
+      assert.ok(eq(s, batch[i]), `${name} mismatch at ${i}: ${s} vs ${batch[i]}`);
+    }
+  });
+}
+
 for (const [name, make] of Object.entries(scalarFactories)) {
   test(`${name}: streaming update matches batch`, () => {
     const batch = make().batch(close);

bindings/node/index.js

@@ -310,7 +310,7 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { version, SMA, EMA, WMA, RSI, DEMA, TEMA, HMA, ROC, TRIX, SMMA, TRIMA, ZLEMA, MOM, CMO, DPO, StdDev, UlcerIndex, VerticalHorizontalFilter, ZScore, MACD, BollingerBands, ATR, Stochastic, OBV, ADX, ADXR, CCI, WilliamsR, MFI, PSAR, Keltner, Donchian, VWAP, RollingVWAP, AwesomeOscillator, Aroon, KAMA, RVI, PGO, KST, SMI, LaguerreRSI, ConnorsRSI, Inertia, ALMA, McGinleyDynamic, FRAMA, VIDYA, JMA, Alligator, EVWMA, APO, AwesomeOscillatorHistogram, CFO, ZeroLagMACD, ElderImpulse, STC, T3, TSI, PMO, TII, ADL, VolumePriceTrend, ChaikinMoneyFlow, ChaikinOscillator, ForceIndex, EaseOfMovement, KVO, VolumeOscillator, NVI, PVI, WilliamsAD, AnchoredVWAP, DemandIndex, TSV, VZO, MarketFacilitationIndex, SuperTrend, ChandelierExit, ChandeKrollStop, AtrTrailingStop, HiLoActivator, VoltyStop, YoyoExit, DonchianStop, PercentageTrailingStop, StepTrailingStop, RenkoTrailingStop, TypicalPrice, MedianPrice, WeightedClose, LinearRegression, LinRegSlope, AcceleratorOscillator, BalanceOfPower, ChoppinessIndex, TrueRange, ChaikinVolatility, LinRegAngle, BollingerBandwidth, PercentB, NATR, HistoricalVolatility, AroonOscillator, Vortex, RWI, WaveTrend, MassIndex, StochRSI, UltimateOscillator, PPO, Coppock, VWMA, RVIVolatility, ParkinsonVolatility, GarmanKlassVolatility, RogersSatchellVolatility, YangZhangVolatility, MaEnvelope, AccelerationBands, StarcBands, AtrBands, HurstChannel, LinRegChannel, StandardErrorBands, DoubleBollinger, TtmSqueeze, FractalChaosBands, VwapStdDevBands, ClassicPivots, FibonacciPivots, Camarilla, WoodiePivots, DemarkPivots, WilliamsFractals, ZigZag, TDSetup, TDSequential, TDDeMarker, TDREI, TDPressure, TDCombo, TDCountdown, TDLines, TDRangeProjection, TDDifferential, TDOpen, TDRiskLevel, SuperSmoother, FisherTransform, InverseFisherTransform, Decycler, DecyclerOscillator, RoofingFilter, CenterOfGravity, CyberneticCycle, InstantaneousTrendline, EhlersStochastic, EmpiricalModeDecomposition, HilbertDominantCycle, AdaptiveCycle, SineWave, MAMA, FAMA, Ichimoku, HeikinAshi, Variance, CoefficientOfVariation, Skewness, Kurtosis, StandardError, DetrendedStdDev, RSquared, MedianAbsoluteDeviation, Autocorrelation, HurstExponent, PearsonCorrelation, Beta, SpearmanCorrelation, ValueArea, InitialBalance, OpeningRange, Doji, Hammer, InvertedHammer, HangingMan, ShootingStar, Engulfing, Harami, MorningEveningStar, ThreeSoldiersOrCrows, PiercingDarkCloud, Marubozu, Tweezer, SpinningTop, ThreeInside, ThreeOutside } = nativeBinding
+const { version, SMA, EMA, WMA, RSI, DEMA, TEMA, HMA, ROC, TRIX, SMMA, TRIMA, ZLEMA, MOM, CMO, DPO, StdDev, UlcerIndex, VerticalHorizontalFilter, ZScore, MACD, BollingerBands, ATR, Stochastic, OBV, ADX, ADXR, CCI, WilliamsR, MFI, PSAR, Keltner, Donchian, VWAP, RollingVWAP, AwesomeOscillator, Aroon, KAMA, RVI, PGO, KST, SMI, LaguerreRSI, ConnorsRSI, Inertia, ALMA, McGinleyDynamic, FRAMA, VIDYA, JMA, Alligator, EVWMA, APO, AwesomeOscillatorHistogram, CFO, ZeroLagMACD, ElderImpulse, STC, T3, TSI, PMO, TII, ADL, VolumePriceTrend, ChaikinMoneyFlow, ChaikinOscillator, ForceIndex, EaseOfMovement, KVO, VolumeOscillator, NVI, PVI, WilliamsAD, AnchoredVWAP, DemandIndex, TSV, VZO, MarketFacilitationIndex, SuperTrend, ChandelierExit, ChandeKrollStop, AtrTrailingStop, HiLoActivator, VoltyStop, YoyoExit, DonchianStop, PercentageTrailingStop, StepTrailingStop, RenkoTrailingStop, TypicalPrice, MedianPrice, WeightedClose, LinearRegression, LinRegSlope, AcceleratorOscillator, BalanceOfPower, ChoppinessIndex, TrueRange, ChaikinVolatility, LinRegAngle, BollingerBandwidth, PercentB, NATR, HistoricalVolatility, AroonOscillator, Vortex, RWI, WaveTrend, MassIndex, StochRSI, UltimateOscillator, PPO, Coppock, VWMA, RVIVolatility, ParkinsonVolatility, GarmanKlassVolatility, RogersSatchellVolatility, YangZhangVolatility, MaEnvelope, AccelerationBands, StarcBands, AtrBands, HurstChannel, LinRegChannel, StandardErrorBands, DoubleBollinger, TtmSqueeze, FractalChaosBands, VwapStdDevBands, ClassicPivots, FibonacciPivots, Camarilla, WoodiePivots, DemarkPivots, WilliamsFractals, ZigZag, TDSetup, TDSequential, TDDeMarker, TDREI, TDPressure, TDCombo, TDCountdown, TDLines, TDRangeProjection, TDDifferential, TDOpen, TDRiskLevel, SuperSmoother, FisherTransform, InverseFisherTransform, Decycler, DecyclerOscillator, RoofingFilter, CenterOfGravity, CyberneticCycle, InstantaneousTrendline, EhlersStochastic, EmpiricalModeDecomposition, HilbertDominantCycle, AdaptiveCycle, SineWave, MAMA, FAMA, Ichimoku, HeikinAshi, Variance, CoefficientOfVariation, Skewness, Kurtosis, StandardError, DetrendedStdDev, RSquared, MedianAbsoluteDeviation, Autocorrelation, HurstExponent, PearsonCorrelation, Beta, SpearmanCorrelation, ValueArea, InitialBalance, OpeningRange, Doji, Hammer, InvertedHammer, HangingMan, ShootingStar, Engulfing, Harami, MorningEveningStar, ThreeSoldiersOrCrows, PiercingDarkCloud, Marubozu, Tweezer, SpinningTop, ThreeInside, ThreeOutside, SharpeRatio, SortinoRatio, CalmarRatio, OmegaRatio, MaxDrawdown, AverageDrawdown, DrawdownDuration, PainIndex, ValueAtRisk, ConditionalValueAtRisk, ProfitFactor, GainLossRatio, RecoveryFactor, KellyCriterion, TreynorRatio, InformationRatio, Alpha } = nativeBinding
 
 module.exports.version = version
 module.exports.SMA = SMA
@@ -510,3 +510,21 @@ module.exports.Tweezer = Tweezer
 module.exports.SpinningTop = SpinningTop
 module.exports.ThreeInside = ThreeInside
 module.exports.ThreeOutside = ThreeOutside
+// Family 15: Risk / Performance metrics
+module.exports.SharpeRatio = SharpeRatio
+module.exports.SortinoRatio = SortinoRatio
+module.exports.CalmarRatio = CalmarRatio
+module.exports.OmegaRatio = OmegaRatio
+module.exports.MaxDrawdown = MaxDrawdown
+module.exports.AverageDrawdown = AverageDrawdown
+module.exports.DrawdownDuration = DrawdownDuration
+module.exports.PainIndex = PainIndex
+module.exports.ValueAtRisk = ValueAtRisk
+module.exports.ConditionalValueAtRisk = ConditionalValueAtRisk
+module.exports.ProfitFactor = ProfitFactor
+module.exports.GainLossRatio = GainLossRatio
+module.exports.RecoveryFactor = RecoveryFactor
+module.exports.KellyCriterion = KellyCriterion
+module.exports.TreynorRatio = TreynorRatio
+module.exports.InformationRatio = InformationRatio
+module.exports.Alpha = Alpha