0.1.2 Kurtosis

libraries/Kurtosis/CHANGELOG.md

@@ -6,11 +6,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.1.2] - 2024-06-01
+- add **kurtosis_stand_alone.ino** example.
+- minor edits
+
 ## [0.1.1] - 2024-05-22
 - add **operator +** and **operator +=**
 - update readme.md
 
-
 ## [0.1.0] - 2024-05-21
 - initial version
 

libraries/Kurtosis/Kurtosis.h

@@ -3,7 +3,7 @@
 //    FILE: Kurtosis.h
 //  AUTHOR: Rob Tillaart
 //    DATE: 2024-05-21
-// VERSION: 0.1.1
+// VERSION: 0.1.2
 // PURPOSE: Arduino library for calculating skewness and kurtosis of a dataset.
 //     URL: https://github.com/RobTillaart/Kurtosis
 //
@@ -13,7 +13,7 @@
 //  Experimental
 
 
-#define KURTOSIS_LIB_VERSION        "0.1.1"
+#define KURTOSIS_LIB_VERSION        "0.1.2"
 
 
 class Kurtosis

libraries/Kurtosis/README.md

@@ -32,7 +32,6 @@ The code of this library is based upon the code of **John D. Cook** in the blog
 "Computing skewness and kurtosis in one pass". Thanks for his kind permission!
 See - https://www.johndcook.com/blog/skewness_kurtosis/
 
-
 I adapted the code on a few places to improve performance a bit.
 Furthermore I named the library Kurtosis as calculating that metric is the 
 prime purpose of this library.
@@ -43,6 +42,32 @@ Links to other information are welcome.
 
 The code is not well tested or verified so use with care.
 
+
+#### Interpretation of Kurtosis metric.
+
+- https://en.wiktionary.org/wiki/mesokurtosis et al.
+
+First order interpretation.
+
+Define: Excess Kurtosis is calculated as kurtosis - 3.
+
+There are three levels of kurtosis.
+
+- Mesokurtosis: An excess kurtosis of approx 0. The normal (Gaussian) distribution is mesokurtic
+- Platykurtosis: A negative excess kurtosis. Platykurtic distributions have a "thin tail", they have relative few outliers.
+- Leptokurtosis: A positive excess kurtosis. Leptokurtic distributions have a "thick tail", they have many outliers.
+
+
+#### Interpretation of Skewness metric.
+
+First order interpretation.
+
+- Skewness between -0.5 and 0.5 => normal distribution
+- Skewness between -1.0 and 1.0 => reasonable normal distribution
+- Skewness smaller than -1.0 => left skewed distribution
+- Skewness larger than 1.0 => right skewed distribution
+
+
 #### Related
 
 - https://github.com/RobTillaart/Histogram
@@ -118,7 +143,7 @@ For adding distributions.
 - add examples to explain the purpose.
 - extend unit tests.
 - ask the experts
-- investigate the order of adding on the metrics.
+- investigate the order of adding values on the metrics.
 
 #### Could
 

libraries/Kurtosis/examples/kurtosis_stand_alone/kurtosis_stand_alone.ino

@@ -0,0 +1,115 @@
+//
+//    FILE: kurtosis_stand_alone.ino
+//  AUTHOR: Rob Tillaart
+//    DATE: 2024-05-26
+// PURPOSE: stand alone kurtosis function
+//     URL: https://github.com/RobTillaart/Kurtosis
+
+
+//  #include "Kurtosis.h"
+
+double arr[100];
+
+
+//
+//                size * sum( (arr[i] - average)^4 )
+//  kurtosis() = ------------------------------------
+//                   sum( (arr[i] - average)^2 )^2
+//
+double kurtosis(double *arr, uint16_t size)
+{
+  // Average
+  double sum = 0;
+  for (uint16_t i = 0; i < size; i++) sum += arr[i];
+  double average = sum / size;
+
+  //  sum((x - average)^2)
+  //  sum((x - average)^4)
+  double a = 0;
+  double b = 0;
+  for (uint16_t i = 0; i < size; i++)
+  {
+    double val = arr[i] - average;
+    val *= val;  //  (arr[i] - average)^2
+    b   += val;
+    val *= val;  //  (arr[i] - average)^4
+    a   += val;
+  }
+
+  return (size * a) / (b * b);
+}
+
+
+//                   sum( (arr[i] - average)^3 )
+//                   ---------------------------
+//                              size
+//  skewness() = ------------------------------------
+//                   sum( (arr[i] - average)^2 )^1.5
+//                   ---------------------------
+//                             size^1.5
+//
+//  simplified
+//
+//                sqrt(size) * sum( (arr[i] - average)^3 )
+//  skewness() = ------------------------------------------
+//                   sum( (arr[i] - average)^2 )^1.5
+//
+double skewness(double *arr, uint16_t size)
+{
+  //  average
+  double sum = 0;
+  for (uint16_t i = 0; i < size; i++) sum += arr[i];
+  double average = sum / size;
+
+  //  a = sum((x - average)^2)
+  //  b = sum((x - average)^2)
+  double a = 0;
+  double b = 0;
+  for (uint16_t i = 0; i < size; i++)
+  {
+    double val = arr[i] - average;
+    double val2 = val * val;   //  (arr[i] - average)^2
+    double val3 = val2 * val;  //  (arr[i] - average)^3
+    b += val2;
+    a += val3;
+  }
+
+  return sqrt(1.0 * size) * a * pow(b, -1.5);
+}
+
+
+///////////////////////////////////////////////////////////////////////
+//
+//  MAIN
+//
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.println();
+
+  //  fill array with random values.
+  for (int i = 0; i < 100; i++)
+  {
+    arr[i] = 0.001 * random(i * 10);  //  skewed on purpose
+  }
+
+  Serial.println();
+  delay(100);
+
+  Serial.println();
+  Serial.println("COUNT:\t100");
+  Serial.print("KURTOSIS:\t");
+  Serial.println(kurtosis(arr, 100), 3);
+  Serial.print("SKEWNESS:\t");
+  Serial.println(skewness(arr, 100), 3);
+  Serial.println();
+}
+
+
+void loop()
+{
+}
+
+
+//  -- END OF FILE --

libraries/Kurtosis/library.json

@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/Kurtosis.git"
   },
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT",
   "frameworks": "*",
   "platforms": "*",

libraries/Kurtosis/library.properties

@@ -1,5 +1,5 @@
 name=Kurtosis
-version=0.1.1
+version=0.1.2
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Arduino library for calculating skewness and kurtosis of a dataset.