update readme.md

RobTillaart · Jun 30, 2023 · c78245d · c78245d
1 parent bebf7fb
commit c78245d
Show file tree

Hide file tree

Showing 5 changed files with 280 additions and 4 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - fix #18 add **range()** and **middle()**
   - fast first order functions, based on minimum() and maximum()
   - statistic value is (very) limited.
+  - add example.
 - update readme.md
 
 

diff --git a/README.md b/README.md
@@ -77,9 +77,9 @@ Alternatively one need to define the statistic object with a more precise data t
 - **typename T sum()**      returns zero if count == zero.
 - **typename T minimum()**  returns zero if count == zero.
 - **typename T maximum()**  returns zero if count == zero.
-- **typename T range()**    returns maximum - minimum.
-- **typename T middle()**   returns (minimum + maximum)/2. If T is an integer type rounding errors are possible
-- **typename T average()**  returns NAN  if count == zero.
+- **typename T range()**    returns maximum - minimum. 
+- **typename T middle()**   returns (minimum + maximum)/2. If T is an integer type rounding errors are possible.
+- **typename T average()**  returns NAN if count == zero.
 
 These three functions only work if **useStdDev == true** (in the template).
 
@@ -89,7 +89,7 @@ pop_stdev = population standard deviation,
 - **typename T unbiased_stdev()** returns NAN if count == zero.
 
 
-#### Deprecated methods:
+#### Deprecated methods
 
 - **Statistic(bool)** Constructor previously used to enable/disable the standard deviation functions. 
 This argument now has no effect.  It is recommended to migrate your code to the default constructor 
@@ -98,6 +98,20 @@ This argument now has no effect.  It is recommended to migrate your code to the
 It is recommended to migrate your code to `clear()` (with no arguments).
 
 
+#### Range() and middle()
+
+**Range()** and **middle()** are fast functions with limited statistical value. 
+Still they have their uses.
+
+Given enough samples (e.g. 100+) and a normal distribution of the samples the **range()** is expected 
+to be 3 to 4 times the **pop_stdev()**. 
+If the range is larger than 4 standard deviations one might have added one or more outliers.
+
+Given enough samples (e.g. 100+) and a normal distribution, the **middle()** and **average()** are 
+expected to be close to each other.
+Note: outliers can disrupt the **middle()**, Several non-normal distributions do too.
+
+
 ## Operational
 
 See examples.

diff --git a/examples/Average/performance.1.0.5.txt b/examples/Average/performance.1.0.5.txt
@@ -0,0 +1,101 @@
+D:\Rob\WORK\Arduino\libraries\Statistic\examples\Average\Average.ino
+Demo Statistics lib 1.0.5
+        Count: 10000
+          Min: 1.0100
+          Max: 100.9600
+      Average: 50.9408
+     variance: 835.0057
+    pop stdev: 28.8965
+ unbias stdev: 28.8979
+     time(ms): 2536
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9800
+      Average: 51.4161
+     variance: 839.9565
+    pop stdev: 28.9820
+ unbias stdev: 28.9835
+     time(ms): 2535
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9800
+      Average: 50.9561
+     variance: 833.2212
+    pop stdev: 28.8656
+ unbias stdev: 28.8670
+     time(ms): 2536
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9700
+      Average: 51.4648
+     variance: 849.5839
+    pop stdev: 29.1476
+ unbias stdev: 29.1491
+     time(ms): 2537
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9800
+      Average: 50.8610
+     variance: 842.0071
+    pop stdev: 29.0174
+ unbias stdev: 29.0188
+     time(ms): 2537
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9800
+      Average: 51.2327
+     variance: 816.5170
+    pop stdev: 28.5748
+ unbias stdev: 28.5762
+     time(ms): 2535
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9800
+      Average: 50.8115
+     variance: 835.1608
+    pop stdev: 28.8991
+ unbias stdev: 28.9006
+     time(ms): 2536
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9800
+      Average: 50.7948
+     variance: 842.5279
+    pop stdev: 29.0263
+ unbias stdev: 29.0278
+     time(ms): 2535
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9500
+      Average: 51.0943
+     variance: 831.8248
+    pop stdev: 28.8414
+ unbias stdev: 28.8428
+     time(ms): 2536
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9700
+      Average: 50.8915
+     variance: 836.6669
+    pop stdev: 28.9252
+ unbias stdev: 28.9266
+     time(ms): 2536
+=====================================
+        Count: 10000
+          Min: 1.0100
+          Max: 100.9800
+      Average: 50.8437
+     variance: 825.5516
+    pop stdev: 28.7324
+ unbias stdev: 28.7339
+     time(ms): 2536
+=====================================
diff --git a/examples/statistic_range_middle/output_1.0.5.txt b/examples/statistic_range_middle/output_1.0.5.txt
@@ -0,0 +1,104 @@
+D:\Rob\WORK\Arduino\libraries\Statiop stdev: 28.8965
+ range/stddev: 3.4589
+=====================================
+D:\Rob\WORK\Arduino\libraries\Statistic\examples\statistic_range_middle\statistic_range_middle.ino
+STATISTIC_LIB_VERSION: 1.0.5
+        Count: 10000
+          Min: 1.0100
+          Max: 100.9600
+        Range: 99.9500
+       Middle: 50.9850
+      Average: 50.9408
+ middle - avg: 0.0442
+     variance: 835.0057
+    pop stdev: 28.8965
+ range/stddev: 3.4589
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9800
+        Range: 99.9800
+       Middle: 50.9900
+      Average: 51.4161
+ middle - avg: -0.4261
+     variance: 839.9565
+    pop stdev: 28.9820
+ range/stddev: 3.4497
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9800
+        Range: 99.9800
+       Middle: 50.9900
+      Average: 50.9561
+ middle - avg: 0.0339
+     variance: 833.2212
+    pop stdev: 28.8656
+ range/stddev: 3.4636
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9700
+        Range: 99.9700
+       Middle: 50.9850
+      Average: 51.4648
+ middle - avg: -0.4798
+     variance: 849.5839
+    pop stdev: 29.1476
+ range/stddev: 3.4298
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9800
+        Range: 99.9800
+       Middle: 50.9900
+      Average: 50.8610
+ middle - avg: 0.1290
+     variance: 842.0071
+    pop stdev: 29.0174
+ range/stddev: 3.4455
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9800
+        Range: 99.9800
+       Middle: 50.9900
+      Average: 51.2327
+ middle - avg: -0.2427
+     variance: 816.5170
+    pop stdev: 28.5748
+ range/stddev: 3.4989
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9800
+        Range: 99.9800
+       Middle: 50.9900
+      Average: 50.8115
+ middle - avg: 0.1785
+     variance: 835.1608
+    pop stdev: 28.8991
+ range/stddev: 3.4596
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9800
+        Range: 99.9800
+       Middle: 50.9900
+      Average: 50.7948
+ middle - avg: 0.1952
+     variance: 842.5279
+    pop stdev: 29.0263
+ range/stddev: 3.4445
+=====================================
+        Count: 10000
+          Min: 1.0000
+          Max: 100.9500
+        Range: 99.9500
+       Middle: 50.9750
+      Average: 51.0943
+ middle - avg: -0.1193
+     variance: 831.8248
+    pop stdev: 28.8414
+ range/stddev: 3.4655
+=====================================
diff --git a/examples/statistic_range_middle/statistic_range_middle.ino b/examples/statistic_range_middle/statistic_range_middle.ino
@@ -0,0 +1,56 @@
+//
+//    FILE: statistic_range_middle.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: Sample sketch for statistic library Arduino
+
+
+#include "Statistic.h"
+
+statistic::Statistic<float, uint32_t, true> myStats;
+// Statistic myStats;  // pre 1.0.0 declaration
+
+
+void setup(void)
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("STATISTIC_LIB_VERSION: ");
+  Serial.println(STATISTIC_LIB_VERSION);
+  myStats.clear();  //  explicitly start clean
+}
+
+
+void loop(void)
+{
+  long rn = random(0, 9999);
+  myStats.add(rn / 100.0 + 1);
+  if (myStats.count() == 10000)
+  {
+    Serial.print("        Count: ");
+    Serial.println(myStats.count());
+    Serial.print("          Min: ");
+    Serial.println(myStats.minimum(), 4);
+    Serial.print("          Max: ");
+    Serial.println(myStats.maximum(), 4);
+    Serial.print("        Range: ");
+    Serial.println(myStats.range(), 4);
+    Serial.print("       Middle: ");
+    Serial.println(myStats.middle(), 4);
+    Serial.print("      Average: ");
+    Serial.println(myStats.average(), 4);
+    Serial.print(" middle - avg: ");
+    Serial.println(myStats.middle() - myStats.average(), 4);
+    Serial.print("     variance: ");
+    Serial.println(myStats.variance(), 4);
+    Serial.print("    pop stdev: ");
+    Serial.println(myStats.pop_stdev(), 4);
+    Serial.print(" range/stddev: ");
+    Serial.println(myStats.range() / myStats.pop_stdev(), 4);
+    Serial.println("=====================================");
+    myStats.clear();
+    delay(1000);
+  }
+}
+
+
+//  -- END OF FILE --