From ed40a44de7746002103968e318187c6b442e58c5 Mon Sep 17 00:00:00 2001
From: Oleksandr <oleksandr.kornijcuk@proton.me>
Date: Mon, 29 Jun 2026 18:34:11 +0200
Subject: [PATCH] Document NaN behavior for zero-variance inputs in
 Correlation.Pearson/WeightedPearson/Spearman

Pearson, WeightedPearson and Spearman return NaN when one of the input
series has zero variance (e.g. fewer than two elements, or all values
equal/tied after ranking), since the underlying formula divides by the
standard deviation of each series. This was previously undocumented,
which led to confusion in #650.

No behavior change; XML doc comments only.
---
 src/Numerics/Statistics/Correlation.cs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/Numerics/Statistics/Correlation.cs b/src/Numerics/Statistics/Correlation.cs
index 918cf93ce..cc8e6c00a 100644
--- a/src/Numerics/Statistics/Correlation.cs
+++ b/src/Numerics/Statistics/Correlation.cs
@@ -161,7 +161,7 @@ static double[] AutoCorrelationFft(double[] x, int kLow, int kHigh)
         /// </summary>
         /// <param name="dataA">Sample data A.</param>
         /// <param name="dataB">Sample data B.</param>
-        /// <returns>The Pearson product-moment correlation coefficient.</returns>
+        /// <returns>The Pearson product-moment correlation coefficient. Returns NaN if either series has zero variance (e.g. fewer than two elements, or all values equal).</returns>
         public static double Pearson(IEnumerable<double> dataA, IEnumerable<double> dataB)
         {
             int n = 0;
@@ -217,7 +217,7 @@ public static double Pearson(IEnumerable<double> dataA, IEnumerable<double> data
         /// <param name="dataA">Sample data A.</param>
         /// <param name="dataB">Sample data B.</param>
         /// <param name="weights">Corresponding weights of data.</param>
-        /// <returns>The Weighted Pearson product-moment correlation coefficient.</returns>
+        /// <returns>The Weighted Pearson product-moment correlation coefficient. Returns NaN if either series has zero weighted variance.</returns>
         public static double WeightedPearson(IEnumerable<double> dataA, IEnumerable<double> dataB, IEnumerable<double> weights)
         {
             double meanA = 0;
@@ -310,7 +310,7 @@ public static Matrix<double> PearsonMatrix(IEnumerable<double[]> vectors)
         /// </summary>
         /// <param name="dataA">Sample data series A.</param>
         /// <param name="dataB">Sample data series B.</param>
-        /// <returns>The Spearman ranked correlation coefficient.</returns>
+        /// <returns>The Spearman ranked correlation coefficient. Returns NaN if either series has zero variance after ranking (e.g. fewer than two elements, or all values tied).</returns>
         public static double Spearman(IEnumerable<double> dataA, IEnumerable<double> dataB)
         {
             return Pearson(Rank(dataA), Rank(dataB));