0.2.0 Correlation

Author: RobTillaart

libraries/Correlation/Correlation.cpp

@@ -1,13 +1,16 @@
 //
 //    FILE: Correlation.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.4
+// VERSION: 0.2.0
 // PURPOSE: Arduino Library to determine correlation between X and Y dataset
 //
 //  HISTORY:
-//  0.1.4  2021-08-26  improve performance calculate
+//  0.2.0  2021-08-26  Add flags to skip Rsquare and Esquare calculation
+//                     will improve performance calculate
+//                     fixed sign of R correlation coefficient
 //
-//  0.1.3  2021-01-16  add size in constructor, 
+//  0.1.4  2021-08-26  improve performance calculate
+//  0.1.3  2021-01-16  add size in constructor,
 //                     add statistical + debug functions
 //  0.1.2  2020-12-17  add arduino-CI + unit tests
 //                     + size() + getAvgX() + getAvgY()
@@ -21,7 +24,8 @@
 
 Correlation::Correlation(uint8_t size)
 {
-  _size = size;
+  _size = 20;
+  if (size >  0) _size = size;
   _x = (float *) malloc(_size * sizeof(float));
   _y = (float *) malloc(_size * sizeof(float));
   clear();
@@ -30,8 +34,8 @@ Correlation::Correlation(uint8_t size)
 
 Correlation::~Correlation()
 {
-  free(_x);
-  free(_y);
+  if (_x) free(_x);
+  if (_y) free(_y);
 }
 
 
@@ -45,11 +49,13 @@ void Correlation::clear()
   _avgY            = 0;
   _a               = 0;
   _b               = 0;
-  _rSquare         = 0;
+  _r               = 0;
   _sumErrorSquare  = 0;
   _sumXiYi         = 0;
   _sumXi2          = 0;
   _sumYi2          = 0;
+  _doR2            = true;
+  _doE2            = true;
 }
 
 
@@ -69,10 +75,10 @@ bool Correlation::add(float x, float y)
 }
 
 
-bool Correlation::calculate()
+bool Correlation::calculate(bool forced)
 {
   if (_count == 0) return false;
-  if (!_needRecalculate) return true;
+  if (! (_needRecalculate || forced)) return true;
 
   // CALC AVERAGE X, AVERAGE Y
   float avgx = 0;
@@ -84,7 +90,7 @@ bool Correlation::calculate()
   }
   avgx /= _count;
   avgy /= _count;
-  
+
   _avgX = avgx;
   _avgY = avgy;
 
@@ -102,25 +108,31 @@ bool Correlation::calculate()
   }
   float b = sumXiYi / sumXi2;
   float a = avgy - b * avgx;
-  // bool CORLIB_CALC_R_SQUARE
-  _rSquare = sumXiYi * sumXiYi / (sumXi2 * sumYi2);  
- 
+
   _a       = a;
   _b       = b;
-  _sumXiYi = sumXiYi; 
-  _sumXi2  = sumXi2; 
-  _sumYi2  = sumYi2; 
+  _sumXiYi = sumXiYi;
+  _sumXi2  = sumXi2;
+  _sumYi2  = sumYi2;
 
-  // bool CORLIB_CALC_E_SQUARE
-  // CALC _sumErrorSquare
-  float sumErrorSquare = 0;
-  for (uint8_t i = 0; i < _count; i++)
+  if (_doR2 == true)
+  {
+    // R is calculated instead of rSquared so we do not loose the sign.
+    // Rsquare  from R is much faster than R from Rsquare.
+    _r = sumXiYi / sqrt(sumXi2 * sumYi2);
+  }
+
+  if (_doE2 == true)
   {
-    float EY =  a + b * _x[i];
-    float ei = _y[i] - EY;
-    sumErrorSquare += (ei * ei);
+    float sumErrorSquare = 0;
+    for (uint8_t i = 0; i < _count; i++)
+    {
+      float EY =  a + b * _x[i];
+      float ei = _y[i] - EY;
+      sumErrorSquare += (ei * ei);
+    }
+    _sumErrorSquare = sumErrorSquare;
   }
-  _sumErrorSquare = sumErrorSquare;
   _needRecalculate = false;
   return true;
 }

libraries/Correlation/Correlation.h

@@ -2,7 +2,7 @@
 //
 //    FILE: Correlation.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.4
+// VERSION: 0.2.0
 // PURPOSE: Calculate Correlation from a small dataset.
 // HISTORY: See Correlation.cpp
 //
@@ -11,7 +11,7 @@
 #include "Arduino.h"
 
 
-#define CORRELATION_LIB_VERSION          (F("0.1.4"))
+#define CORRELATION_LIB_VERSION          (F("0.2.0"))
 
 
 class Correlation
@@ -20,42 +20,65 @@ class Correlation
   Correlation(uint8_t size = 20);   // WARNING calculate memory usage !!
   ~Correlation();
 
-  // returns true if the value is added to internal array.
+  // returns true if the pair of values is added to internal array.
   // returns false when internal array is full.
   bool    add(float x, float y);
 
+  // administrative functions
   uint8_t count() { return _count; };
   uint8_t size()  { return _size; };
   void    clear();
 
-  // in running mode, adding new values will replace old ones
-  // this constantly adapts the regression params A and B.
+
+  // in running mode, adding new pair of values will replace old ones
+  // this constantly adapts the regression parameters A and B (iff calculate is called)
   void    setRunningCorrelation(bool rc) { _runningMode = rc; };
   bool    getRunningCorrelation()        { return _runningMode; };
 
-  // worker, to calculate the correlation params. 
-  // MUST be called before getting the params A, B, R, Rsquare, Esquare, 
-  //                                          avgX and avgY
+
+  // worker, to calculate the correlation parameters.
+  // MUST be called before retrieving the parameters 
+  //      A, B, R, Rsquare, Esquare, avgX and avgY
+  //
+  // parameter forced overrules the _needRecalculate flag.
+  //           forced is default false to maintain backwards compatibility
+  //
   // returns false if contains no elements ==> count() == 0
-  bool    calculate();
+  bool    calculate(bool forced = false);
+  // enables / disables R, Rsquare and Esquare calculation
+  // This can be used to speed up the calculate function if
+  // these values are not used in your project.
+  void    setR2Calculation(bool doR2) { _doR2 = doR2; };
+  bool    getR2Calculation() { return _doR2; };
+  void    setE2Calculation(bool doE2) { _doE2 = doE2; };
+  bool    getE2Calculation() { return _doE2; };
+
 
   // Y = A + B * X
+  // note if no elements are added or calculate is not called
+  //      the values for A and B are 0
   float   getA()       { return _a; };
   float   getB()       { return _b; };
 
-  // returns R == correlation coefficient
-  float   getR()       { return sqrt(_rSquare); };
-  float   getRsquare() { return _rSquare; };
-  
-  // returns sum of the errors squared
+
+  // getR() returns correlation coefficient  (0.2.0 fixed sign)
+  float   getR()       { return _r; };
+  float   getRsquare() { return _r * _r; };
+
+
+  // returns sum of the errors squared == indication of 'spread'
+  // the smaller this value the more the points are on/near one line.
   float   getEsquare() { return _sumErrorSquare; };
 
-  // get the average values of the datasets (as it is available)
+
+  // get the average values of the datasets (if count > 0)
   float   getAvgX()    { return _avgX; };
   float   getAvgY()    { return _avgY; };
-  
+
+
   // based on the dataset get the estimated values for X and Y
-  // library does not return confidence interval for these. 
+  // it uses the last calculated A and B
+  // library does not return a confidence interval for these values.
   float   getEstimateY(float x);
   float   getEstimateX(float y);
 
@@ -73,6 +96,7 @@ class Correlation
   bool    setY(uint8_t idx, float y);            // returns true if succeeded
   float   getX(uint8_t idx);    // idem
   float   getY(uint8_t idx);    // idem
+
   float   getSumXiYi() { return _sumXiYi; };
   float   getSumXi2()  { return _sumXi2;  };
   float   getSumYi2()  { return _sumYi2;  };
@@ -84,6 +108,8 @@ class Correlation
   uint8_t _count = 0;
   bool    _runningMode = false;
   bool    _needRecalculate = true;
+  bool    _doE2 = true;
+  bool    _doR2 = true;
 
   float *  _x;
   float *  _y;
@@ -92,7 +118,7 @@ class Correlation
   float   _avgY;
   float   _a;
   float   _b;
-  float   _rSquare;
+  float   _r;
   float   _sumErrorSquare;
   float   _sumXiYi;
   float   _sumXi2;

libraries/Correlation/README.md

@@ -17,12 +17,15 @@ This library calculates the coefficients of the linear correlation
 between two (relative small) datasets. The size of these datasets is 
 20 by default. The size can be set in the constructor. 
 
-The formula of the correlation is expressed as **Y = A + B \* X**,
-
 Please note that the correlation uses about ~50 bytes per instance,
 and 2 floats == 8 bytes per pair of elements.
 So ~120 elements will use up 50% of the RAM of an UNO.
 
+The formula of the correlation is expressed as **Y = A + B \* X**,
+
+If all points are on a vertical line, the parameter B will be NAN,
+This will happen if the **sumXi2** is zero or very small. 
+
 Use with care.
 
 
@@ -31,47 +34,75 @@ Use with care.
 
 ### Constructor
 
-- **Correlation(uint8_t size = 20)** allocates the array needed and resets internal admin.
+- **Correlation(uint8_t size = 20)** allocates the array needed and resets internal admin. Size should be between 1 and 255. Size = 0 will set the size to 20.
 - **~Correlation()** frees the allocated arrays.
 
 
 ### Base functions
 
-- **bool add(float x, float y)** adds a pair of **floats** to the internal storage. 
+- **bool add(float x, float y)** adds a pair of **floats** to the internal storage arrays's.
 Returns true if the value is added, returns false when internal array is full.
-When running correlation is set, it will replace the oldest element and return true.
-- **uint8_t count()** returns the amount of items in the internal arrays.
+When running correlation is set, **add()** will replace the oldest element and return true.
+Warning: **add()** does not check if the floats are NAN or INFINITE.
+- **uint8_t count()** returns the amount of items in the internal arrays. 
+This number is always between 0 ..**size()**
 - **uint8_t size()** returns the size of the internal arrays.
-- **void clear()** resets the datastructure to start condition (zero elements added)
+- **void clear()** resets the data structures to the start condition (zero elements added)
 - **bool calculate()** does the math to calculate the correlation parameters A, B and R. 
 This function will be called automatically when needed.
 You can call it on a more convenient time. 
 Returns false if nothing to calculate **count == 0**
+- **void setR2Calculation(bool)** enables / disables the calculation of Rsquared.
+- **bool getR2Calculation()** returns the flag set.
+- **void setE2Calculation(bool)** enables / disables the calculation of Esquared.
+- **bool getE2Calculation()** returns the flag set.
+
+After the calculation the following functions can be called to return the core values.
 - **float getA()** returns the A parameter of formula **Y = A + B \* X**
 - **float getB()** returns the B parameter of formula **Y = A + B \* X**
-- **float getR()** returns the correlation coefficient R. 
+- **float getR()** returns the correlation coefficient R which is always between -1 .. 1
 The closer to 0 the less correlation there is between X and Y. 
 Correlation can be positive or negative. 
-Most often the R squared **sqr(R)** is used.
-- **float getRsquare()** returns the **sqr(R)** which is always between 0.. 1.
+Most often the Rsquare **R x R** is used.
+- **float getRsquare()** returns **R x R** which is always between 0.. 1.
 - **float getEsquare()** returns the error squared to get an indication of the
-quality of the relation.
+quality of the correlation.
 - **float getAvgX()** returns the average of all elements in the X dataset.
 - **float getAvgY()** returns the average of all elements in the Y dataset.
 - **float getEstimateX(float y)** use to calculate the estimated X for a given Y.
 - **float getEstimateY(float x)** use to calculate the estimated Y for a given X.
 
 
+#### Correlation Coefficient R
+
+Indicative description of the correlation
+
+|  R            |  correlation  |
+|:-------------:|:--------------|
+| +1.0          | Perfect       |
+| +0.8 to +1.0  | Very strong   |
+| +0.6 to +0.8  | Strong        |
+| +0.4 to +0.6  | Moderate      |
+| +0.2 to +0.4  | Weak          |
+|  0.0 to +0.2  | Very weak     |
+|  0.0 to -0.2  | Very weak     |
+| -0.2 to -0.4  | Weak          |
+| -0.4 to -0.6  | Moderate      |
+| -0.6 to -0.8  | Strong        |
+| -0.8 to -1.0  | Very strong   |
+| -1.0          | Perfect       |
+
+
 ### Running correlation
 
 - **void setRunningCorrelation(bool rc)** sets the internal variable 
 runningMode which allows **add()** to overwrite old elements in the
 internal arrays. 
-- **bool getRunningCorrelation()** returns the runningMOde flag.
+- **bool getRunningCorrelation()** returns the runningMode flag.
 
-The running correlation will be calculated over the last **count** elements. 
-This allows for more adaptive formula finding e.g. find the relation between
-temperature and humidity per hour.
+The running correlation will be calculated over the last **count** elements. If the array is full, count will be size.
+This running correlation allows for more adaptive formula finding e.g. find the relation between
+temperature and humidity per hour, and how it changes over time.
 
 
 ### Statistical
@@ -89,10 +120,10 @@ It also depends on **R** of course. Idem for **getEstimateY()**
 
 ### Debugging / educational
 
-Normally not used.
+Normally not used. For all these functions idx should be < count!
 
 - **bool setXY(uint8_t idx, float x, float y)** overwrites a pair of values.
-Returns true if succeeded, idx should be < count!
+Returns true if succeeded.
 - **bool setX(uint8_t idx, float x)** overwrites single X.
 - **bool setY(uint8_t idx, float y)** overwrites single Y.
 - **float getX(uint8_t idx)** returns single value.
@@ -106,7 +137,7 @@ Returns true if succeeded, idx should be < count!
 
 - Template version
 The constructor should get a TYPE parameter, as this
-allows smaller datatypes to be analyzed taking less memory.
+allows smaller data types to be analysed taking less memory.
 
 
 ## Operation