XML Documentation

lib/statistics/Entropy.cs

@@ -1,19 +1,27 @@
 namespace QuanTAlib;
 
-using System;
-using System.Linq;
-
-// Shannon's Entropy calculation
+/// <summary>
+/// Measures the unpredictability of data using Shannon's Entropy.
+/// Provides insights into the randomness or information content of the time series.
+/// </summary>
 public class Entropy : AbstractBase
 {
     private readonly int Period;
     private readonly CircularBuffer _buffer;
 
+    /// <summary>
+    /// Initializes a new instance of the Entropy class.
+    /// </summary>
+    /// <param name="period">The number of data points to consider for calculation.</param>
+    /// <exception cref="ArgumentOutOfRangeException">
+    /// Thrown when the period is less than 2.
+    /// </exception>
     public Entropy(int period) : base()
     {
         if (period < 2)
         {
-            throw new ArgumentOutOfRangeException(nameof(period), "Period must be greater than or equal to 2 for entropy calculation.");
+            throw new ArgumentOutOfRangeException(nameof(period),
+                "Period must be greater than or equal to 2 for entropy calculation.");
         }
         Period = period;
         WarmupPeriod = 2;
@@ -22,18 +30,30 @@ public class Entropy : AbstractBase
         Init();
     }
 
+    /// <summary>
+    /// Initializes a new instance of the Entropy class with a data source.
+    /// </summary>
+    /// <param name="source">The source object that publishes data.</param>
+    /// <param name="period">The number of data points to consider.</param>
     public Entropy(object source, int period) : this(period)
     {
         var pubEvent = source.GetType().GetEvent("Pub");
         pubEvent?.AddEventHandler(source, new ValueSignal(Sub));
     }
 
+    /// <summary>
+    /// Resets the Entropy indicator to its initial state.
+    /// </summary>
     public override void Init()
     {
         base.Init();
         _buffer.Clear();
     }
 
+    /// <summary>
+    /// Manages the state of the indicator.
+    /// </summary>
+    /// <param name="isNew">Indicates if the current data point is new.</param>
     protected override void ManageState(bool isNew)
     {
         if (isNew)
@@ -43,6 +63,17 @@ public class Entropy : AbstractBase
         }
     }
 
+    /// <summary>
+    /// Performs the entropy calculation.
+    /// </summary>
+    /// <returns>
+    /// The calculated entropy value, normalized between 0 and 1.
+    /// 1 indicates maximum randomness, 0 indicates perfect predictability.
+    /// </returns>
+    /// <remarks>
+    /// Uses Shannon's Entropy formula and normalizes the result based on the
+    /// number of unique values in the current period.
+    /// </remarks>
     protected override double Calculation()
     {
         ManageState(Input.IsNew);
@@ -70,9 +101,11 @@ public class Entropy : AbstractBase
             double maxEntropy = Math.Log2(uniqueValueCount);
 
             entropy = entropy == 0 ? 1 : entropy / maxEntropy;
-
         }
-        else { entropy = 1; }
+        else
+        {
+            entropy = 1; // Default to maximum entropy when insufficient data
+        }
 
         IsHot = _buffer.Count >= Period;
         return entropy;