Restore ewmVol to original RMS behavior; fix XML doc category tags

github-actions[bot] · Copilot · github-actions[bot] · commit 7614afa5b7a9 · 2026-03-09T12:26:38.000Z
- ewmVol (Series/Frame): restore original RiskMetrics RMS formula from main,
  preserving exact backward-compatible behavior for existing consumers
- ewmVol: update Obsolete message to redirect to ewmVolRMS (same formula)
  or ewmVolStdDev (mean-corrected standard deviation)
- ewmVol Frame: inline original RMS logic to avoid internal deprecation warning
- Fix all [category: ...] style XML doc comments to proper
  &lt;category&gt;...&lt;/category&gt; XML format (ewmVolRMS x2, ewmVol x2)
- Rename misleading test name from 'ewmVol on non-returns...' to
  'ewmVolStdDev on non-returns...' since it tests ewmVolStdDev

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/src/Deedle.Math/Finance.fs b/src/Deedle.Math/Finance.fs
@@ -49,7 +49,7 @@ type Finance =
   /// Computes vol as sqrt(EWM(x²)), which equals ewmMean for strictly positive sequences.
   /// Appropriate for returns series that are already mean-centred (e.g. zero-mean returns).
   ///
-  /// [category: Exponentially Weighted Moving]
+  /// <category>Exponentially Weighted Moving</category>
   static member ewmVolRMS (x:Series<'R, float>, ?com, ?span, ?halfLife, ?alpha) =
     let alpha = StatsInternal.ewDecay(com, span, halfLife, alpha)
     let x = x |> Series.dropMissing
@@ -69,7 +69,7 @@ type Finance =
   /// Exponentially weighted moving volatility using root mean square (no mean correction)
   /// applied to each column of a frame.
   ///
-  /// [category: Exponentially Weighted Moving]
+  /// <category>Exponentially Weighted Moving</category>
   static member ewmVolRMS (df:Frame<'R, 'C>, ?com, ?span, ?halfLife, ?alpha) =
     let alpha = StatsInternal.ewDecay(com, span, halfLife, alpha)
     df
@@ -79,19 +79,54 @@ type Finance =
 
   /// Exponentially weighted moving volatility on series.
   ///
-  /// [category: Exponentially Weighted Moving]
-  [<Obsolete("ewmVol is deprecated. Use ewmVolStdDev for mean-corrected standard deviation or ewmVolRMS for root-mean-square volatility.")>]
+  /// <category>Exponentially Weighted Moving</category>
+  [<Obsolete("ewmVol is deprecated. Use ewmVolRMS for the same root-mean-square behaviour, or ewmVolStdDev for mean-corrected standard deviation.")>]
   static member ewmVol (x:Series<'R, float>, ?com, ?span, ?halfLife, ?alpha) =
+    // Return to RiskMetrics: The Evolution of a Standard
+    // https://www.msci.com/documents/10199/dbb975aa-5dc2-4441-aa2d-ae34ab5f0945
     let alpha = StatsInternal.ewDecay(com, span, halfLife, alpha)
-    Finance.ewmVolStdDev(x, alpha = alpha)
+    let x = x |> Series.dropMissing
+    if x.KeyCount < 2 then
+      x |> Series.mapValues(fun _ -> nan)
+    else
+      let init = x |> Stats.stdDev
+      let data = x.Values |> Array.ofSeq
+      let res = Array.zeroCreate x.KeyCount
+      for i in [|0..x.KeyCount-1|] do
+        if i = 0 then
+          res.[i] <- init
+        else
+          let prev = res.[i-1]
+          let curr = data.[i]
+          res.[i] <- Math.Sqrt((1. - alpha) * prev * prev + alpha * curr * curr)
+      Series(x.Keys, res)
 
   /// Exponentially weighted moving volatility on frame.
   ///
-  /// [category: Exponentially Weighted Moving]
-  [<Obsolete("ewmVol is deprecated. Use ewmVolStdDev for mean-corrected standard deviation or ewmVolRMS for root-mean-square volatility.")>]
+  /// <category>Exponentially Weighted Moving</category>
+  [<Obsolete("ewmVol is deprecated. Use ewmVolRMS for the same root-mean-square behaviour, or ewmVolStdDev for mean-corrected standard deviation.")>]
   static member ewmVol (df:Frame<'R, 'C>, ?com, ?span, ?halfLife, ?alpha) =
     let alpha = StatsInternal.ewDecay(com, span, halfLife, alpha)
-    Finance.ewmVolStdDev(df, alpha = alpha)
+    df
+    |> Frame.getNumericCols
+    |> Series.mapValues(fun series ->
+        // Inline original ewmVol series logic to avoid deprecation warning at call site
+        let x = series |> Series.dropMissing
+        if x.KeyCount < 2 then
+          x |> Series.mapValues(fun _ -> nan)
+        else
+          let init = x |> Stats.stdDev
+          let data = x.Values |> Array.ofSeq
+          let res = Array.zeroCreate x.KeyCount
+          for i in [|0..x.KeyCount-1|] do
+            if i = 0 then
+              res.[i] <- init
+            else
+              let prev = res.[i-1]
+              let curr = data.[i]
+              res.[i] <- Math.Sqrt((1. - alpha) * prev * prev + alpha * curr * curr)
+          Series(x.Keys, res))
+    |> Frame.ofColumns
 
   /// Exponentially weighted moving variance on series
   static member ewmVar (x:Series<'R, float>, ?com, ?span, ?halfLife, ?alpha) =
diff --git a/tests/Deedle.Math.Tests/Finance.fs b/tests/Deedle.Math.Tests/Finance.fs
@@ -51,9 +51,9 @@ let ``Ex-ante vol of equally weighted portfolio using exponentially weighted cov
   annualVol1 |> should beWithin (annualVol2 +/- 1e-6)
 
 [<Test>]
-let ``ewmVol on non-returns series should return standard deviation not root-mean-square (issue #555)`` () =
-  // For a monotonically increasing sequence, ewmVol should give std (~5),
-  // not a value near the mean (~45) as the old incorrect formula produced.
+let ``ewmVolStdDev on non-returns series should return standard deviation not root-mean-square (issue #555)`` () =
+  // For a monotonically increasing sequence, ewmVolStdDev should give std (~5),
+  // not a value near the mean (~45) as the old incorrect ewmVol formula produced.
   let s = Series.ofValues [ for i in 1.0 .. 50.0 -> i ]
   let vol = Finance.ewmVolStdDev(s, span = 10.)
   let lastVol = vol |> Series.lastValue
