doc headers

lib/statistics/cointegration/Cointegration.Tests.cs

@@ -581,12 +581,12 @@ public class CointegrationTests
     {
         // Create two cointegrated series: B = A + noise
         var indicator = new Cointegration(20);
-        var random = new Random(42);
+        var random = new GBM(startPrice: 100.0, sigma: 1.0, seed: 42);
 
         for (int i = 0; i < 100; i++)
         {
             double a = 100.0 + i * 0.1;
-            double b = a + random.NextDouble() * 0.1 - 0.05; // Highly correlated
+            double b = a + Math.Log(random.Next().Close / 100.0) * 0.1; // Highly correlated
 
             indicator.Update(a, b);
         }
@@ -601,7 +601,7 @@ public class CointegrationTests
         // Create two non-cointegrated series (random walks)
         var indicatorCointegrated = new Cointegration(20);
         var indicatorRandom = new Cointegration(20);
-        var random = new Random(42);
+        var random = new GBM(startPrice: 100.0, sigma: 1.0, seed: 42);
 
         double walkA = 100.0;
         double walkB = 100.0;
@@ -610,12 +610,13 @@ public class CointegrationTests
         {
             // Cointegrated pair
             double a1 = 100.0 + i * 0.1;
-            double b1 = a1 + random.NextDouble() * 0.1;
+            double noise1 = Math.Log(random.Next().Close / 100.0);
+            double b1 = a1 + noise1 * 0.1;
             indicatorCointegrated.Update(a1, b1);
 
             // Random walks
-            walkA += random.NextDouble() - 0.5;
-            walkB += random.NextDouble() - 0.5;
+            walkA += Math.Log(random.Next().Close / 100.0);
+            walkB += Math.Log(random.Next().Close / 100.0);
             indicatorRandom.Update(walkA, walkB);
         }
 

lib/statistics/cointegration/Cointegration.Validation.Tests.cs

@@ -10,6 +10,9 @@ public class CointegrationValidationTests
 {
     private const double Tolerance = 1e-6;
 
+    // GBM-based noise helper: log-return from seeded GBM price stream as centered noise.
+    private static double GbmNoise(GBM gbm) => Math.Log(gbm.Next().Close / 100.0);
+
     #region Statistical Property Validation
 
     [Fact]
@@ -18,12 +21,12 @@ public class CointegrationValidationTests
         // Two series with near-perfect linear relationship should show strong cointegration
         // Adding small noise to avoid zero-variance residuals
         var indicator = new Cointegration(20);
-        var random = new Random(42);
+        var random = new GBM(startPrice: 100.0, sigma: 1.0, seed: 42);
 
         for (int i = 0; i < 100; i++)
         {
-            double a = 100.0 + i * 0.5 + (random.NextDouble() - 0.5) * 0.1;
-            double b = 2.0 * a + 10.0 + (random.NextDouble() - 0.5) * 0.1;
+            double a = 100.0 + i * 0.5 + GbmNoise(random) * 0.1;
+            double b = 2.0 * a + 10.0 + GbmNoise(random) * 0.1;
             indicator.Update(a, b);
         }
 
@@ -55,12 +58,12 @@ public class CointegrationValidationTests
     {
         // B = k * A + small noise (near-proportional relationship)
         var indicator = new Cointegration(20);
-        var random = new Random(42);
+        var random = new GBM(startPrice: 100.0, sigma: 1.0, seed: 43);
 
         for (int i = 0; i < 100; i++)
         {
             double a = 50.0 + i * 0.3 + Math.Sin(i * 0.2) * 5.0;
-            double noise = (random.NextDouble() - 0.5) * 0.5;
+            double noise = GbmNoise(random) * 0.5;
             double b = 1.5 * a + noise;
             indicator.Update(a, b);
         }
@@ -73,12 +76,12 @@ public class CointegrationValidationTests
     {
         // B = α + β*A + small_noise
         var indicator = new Cointegration(20);
-        var random = new Random(42);
+        var random = new GBM(startPrice: 100.0, sigma: 1.0, seed: 44);
 
         for (int i = 0; i < 100; i++)
         {
             double a = 100.0 + i * 0.2;
-            double noise = (random.NextDouble() - 0.5) * 0.5; // Small noise
+            double noise = GbmNoise(random) * 0.5; // Small noise
             double b = 25.0 + 0.8 * a + noise;
             indicator.Update(a, b);
         }
@@ -245,12 +248,12 @@ public class CointegrationValidationTests
     public void Cointegration_SmallPeriod_WorksCorrectly()
     {
         var indicator = new Cointegration(3); // Minimum practical period
-        var random = new Random(42);
+        var random = new GBM(startPrice: 100.0, sigma: 1.0, seed: 45);
 
         for (int i = 0; i < 20; i++)
         {
-            double a = 100.0 + i + (random.NextDouble() - 0.5) * 0.1;
-            double b = 50.0 + 0.5 * a + (random.NextDouble() - 0.5) * 0.1;
+            double a = 100.0 + i + GbmNoise(random) * 0.1;
+            double b = 50.0 + 0.5 * a + GbmNoise(random) * 0.1;
             indicator.Update(a, b);
         }
 
@@ -263,12 +266,12 @@ public class CointegrationValidationTests
     public void Cointegration_LargePeriod_WorksCorrectly()
     {
         var indicator = new Cointegration(100);
-        var random = new Random(42);
+        var random = new GBM(startPrice: 100.0, sigma: 1.0, seed: 46);
 
         for (int i = 0; i < 150; i++)
         {
-            double a = 100.0 + i * 0.1 + (random.NextDouble() - 0.5) * 0.1;
-            double b = 30.0 + 0.8 * a + (random.NextDouble() - 0.5) * 0.1;
+            double a = 100.0 + i * 0.1 + GbmNoise(random) * 0.1;
+            double b = 30.0 + 0.8 * a + GbmNoise(random) * 0.1;
             indicator.Update(a, b);
         }
 

lib/statistics/cointegration/Cointegration.md

@@ -1,5 +1,22 @@
 # Cointegration: Engle-Granger Two-Step Cointegration Test
 
+| Property         | Value                            |
+| ---------------- | -------------------------------- |
+| **Category**     | Statistic                        |
+| **Inputs**       | Source (close)                          |
+| **Parameters**   | `period` (default 20)                      |
+| **Outputs**      | Single series (Cointegration)                       |
+| **Output range** | Varies (see docs)                     |
+| **Warmup**       | `period + 1` bars                          |
+
+### TL;DR
+
+- The Cointegration indicator measures the long-run equilibrium relationship between two price series using the Engle-Granger two-step method with an...
+- Parameterized by `period` (default 20).
+- Output range: Varies (see docs).
+- Requires `period + 1` bars of warmup before first valid output (IsHot = true).
+- Validated against TA-Lib, Skender, and Tulip reference implementations where available.
+
 > "Correlation tells you they move together. Cointegration tells you they're bound together. Two stocks can be uncorrelated yet cointegrated, or perfectly correlated yet destined to drift apart forever. The difference between 'similar direction' and 'shared destiny' is the difference between a tourist attraction and a gravitational orbit."
 
 The Cointegration indicator measures the long-run equilibrium relationship between two price series using the Engle-Granger two-step method with an Augmented Dickey-Fuller (ADF) test. Unlike correlation, which measures short-term co-movement, cointegration tests whether two non-stationary series share a common stochastic trend—meaning they may diverge temporarily but are statistically bound to revert to their equilibrium relationship.
@@ -270,4 +287,4 @@ coint.Update(101.0, 51.0, isNew: false); // Recalculates without advancing state
 - Engle, R.F. and Granger, C.W.J. (1987). "Co-integration and Error Correction: Representation, Estimation, and Testing." *Econometrica*, 55(2), 251-276.
 - Dickey, D.A. and Fuller, W.A. (1979). "Distribution of the Estimators for Autoregressive Time Series with a Unit Root." *Journal of the American Statistical Association*, 74(366), 427-431.
 - TradingView. "Cointegration Indicator (PineScript)." *TradingView Community Scripts*.
-- Vidyamurthy, G. (2004). "Pairs Trading: Quantitative Methods and Analysis." *Wiley Finance*.
+- Vidyamurthy, G. (2004). "Pairs Trading: Quantitative Methods and Analysis." *Wiley Finance*.