Refactor standard deviation to include sample and population (#55)

Standard deviation parameters in full.json, full.php, full.yml and
README.md files were renamed for clarity. They now include both sample
and population standard deviation. Ensued that this change is correctly
reflected in related code and related tests have been added for standard
deviation of a population.

README.md

@@ -4,7 +4,7 @@
 [![Stable Version](https://poser.pugx.org/jbzoo/csv-blueprint/version)](https://packagist.org/packages/jbzoo/csv-blueprint/)    [![Total Downloads](https://poser.pugx.org/jbzoo/csv-blueprint/downloads)](https://packagist.org/packages/jbzoo/csv-blueprint/stats)    [![Docker Pulls](https://img.shields.io/docker/pulls/jbzoo/csv-blueprint.svg)](https://hub.docker.com/r/jbzoo/csv-blueprint)    [![Dependents](https://poser.pugx.org/jbzoo/csv-blueprint/dependents)](https://packagist.org/packages/jbzoo/csv-blueprint/dependents?order_by=downloads)    [![GitHub License](https://img.shields.io/github/license/jbzoo/csv-blueprint)](https://github.com/JBZoo/Csv-Blueprint/blob/master/LICENSE)
 
 <!-- rules-counter -->
-![Static Badge](https://img.shields.io/badge/Rules-92-green?label=Total%20Number%20of%20Rules&labelColor=blue&color=gray)    ![Static Badge](https://img.shields.io/badge/Rules-55-green?label=Cell%20Rules&labelColor=blue&color=gray)    ![Static Badge](https://img.shields.io/badge/Rules-37-green?label=Aggregate%20Rules&labelColor=blue&color=gray)
+![Static Badge](https://img.shields.io/badge/Rules-96-green?label=Total%20Number%20of%20Rules&labelColor=blue&color=gray)    ![Static Badge](https://img.shields.io/badge/Rules-55-green?label=Cell%20Rules&labelColor=blue&color=gray)    ![Static Badge](https://img.shields.io/badge/Rules-41-green?label=Aggregate%20Rules&labelColor=blue&color=gray)
 <!-- /rules-counter -->
 
 ## Introduction
@@ -295,10 +295,16 @@ columns:
       # A low standard deviation indicates that the data points tend to be close to the mean (also called the expected value) of the set.
       # A high standard deviation indicates that the data points are spread out over a wider range of values.
       # See: https://en.wikipedia.org/wiki/Standard_deviation.
-      standard_deviation: 5.123
-      standard_deviation_not: 4.123
-      standard_deviation_min: 1.123
-      standard_deviation_max: 10.123
+      sd_sample: 5.123
+      sd_sample_not: 4.123
+      sd_sample_min: 1.123
+      sd_sample_max: 10.123
+
+      # SD+ (Standard deviation for a population; uses population variance).
+      sd_population: 5.123
+      sd_population_not: 4.123
+      sd_population_min: 1.123
+      sd_population_max: 10.123
 
   - name: "another_column"
 

schema-examples/full.json

@@ -124,10 +124,15 @@
                 "sample_variance_min"     : 1.123,
                 "sample_variance_max"     : 10.123,
 
-                "standard_deviation"      : 5.123,
-                "standard_deviation_not"  : 4.123,
-                "standard_deviation_min"  : 1.123,
-                "standard_deviation_max"  : 10.123
+                "sd_sample"               : 5.123,
+                "sd_sample_not"           : 4.123,
+                "sd_sample_min"           : 1.123,
+                "sd_sample_max"           : 10.123,
+
+                "sd_population"           : 5.123,
+                "sd_population_not"       : 4.123,
+                "sd_population_min"       : 1.123,
+                "sd_population_max"       : 10.123
             }
         },
 

schema-examples/full.php

@@ -140,10 +140,15 @@
                 'sample_variance_min' => 1.123,
                 'sample_variance_max' => 10.123,
 
-                'standard_deviation'     => 5.123,
-                'standard_deviation_not' => 4.123,
-                'standard_deviation_min' => 1.123,
-                'standard_deviation_max' => 10.123,
+                'sd_sample'     => 5.123,
+                'sd_sample_not' => 4.123,
+                'sd_sample_min' => 1.123,
+                'sd_sample_max' => 10.123,
+
+                'sd_population'     => 5.123,
+                'sd_population_not' => 4.123,
+                'sd_population_min' => 1.123,
+                'sd_population_max' => 10.123,
             ],
         ],
 

schema-examples/full.yml

@@ -216,10 +216,16 @@ columns:
       # A low standard deviation indicates that the data points tend to be close to the mean (also called the expected value) of the set.
       # A high standard deviation indicates that the data points are spread out over a wider range of values.
       # See: https://en.wikipedia.org/wiki/Standard_deviation.
-      standard_deviation: 5.123
-      standard_deviation_not: 4.123
-      standard_deviation_min: 1.123
-      standard_deviation_max: 10.123
+      sd_sample: 5.123
+      sd_sample_not: 4.123
+      sd_sample_min: 1.123
+      sd_sample_max: 10.123
+
+      # SD+ (Standard deviation for a population; uses population variance).
+      sd_population: 5.123
+      sd_population_not: 4.123
+      sd_population_min: 1.123
+      sd_population_max: 10.123
 
   - name: "another_column"
 

src/Rules/Aggregate/ComboSdPopulation.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * JBZoo Toolbox - Csv-Blueprint.
+ *
+ * This file is part of the JBZoo Toolbox project.
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @license    MIT
+ * @copyright  Copyright (C) JBZoo.com, All rights reserved.
+ * @see        https://github.com/JBZoo/Csv-Blueprint
+ */
+
+declare(strict_types=1);
+
+namespace JBZoo\CsvBlueprint\Rules\Aggregate;
+
+use MathPHP\Statistics\Descriptive;
+
+final class ComboSdPopulation extends AbstarctAggregateRuleCombo
+{
+    protected const NAME = 'standard deviation (SD+)';
+
+    protected const HELP_TOP = [
+        'SD+ (Standard deviation for a population; uses population variance)',
+    ];
+
+    protected function getActualAggregate(array $colValues): ?float
+    {
+        return Descriptive::standardDeviation(self::stringsToFloat($colValues), Descriptive::POPULATION);
+    }
+}

src/Rules/Aggregate/ComboStandardDeviation.php → src/Rules/Aggregate/ComboSdSample.php

@@ -18,7 +18,7 @@
 
 use MathPHP\Statistics\Descriptive;
 
-final class ComboStandardDeviation extends AbstarctAggregateRuleCombo
+final class ComboSdSample extends AbstarctAggregateRuleCombo
 {
     protected const NAME = 'standard deviation (SD)';
 

tests/Rules/Aggregate/ComboSdPopulationTest.php

@@ -0,0 +1,40 @@
+<?php
+
+/**
+ * JBZoo Toolbox - Csv-Blueprint.
+ *
+ * This file is part of the JBZoo Toolbox project.
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @license    MIT
+ * @copyright  Copyright (C) JBZoo.com, All rights reserved.
+ * @see        https://github.com/JBZoo/Csv-Blueprint
+ */
+
+declare(strict_types=1);
+
+namespace JBZoo\PHPUnit\Rules\Aggregate;
+
+use JBZoo\CsvBlueprint\Rules\AbstarctRule as Combo;
+use JBZoo\CsvBlueprint\Rules\Aggregate\ComboSdPopulation;
+use JBZoo\PHPUnit\Rules\AbstractAggregateRuleCombo;
+
+use function JBZoo\PHPUnit\isSame;
+
+class ComboSdPopulationTest extends AbstractAggregateRuleCombo
+{
+    protected string $ruleClass = ComboSdPopulation::class;
+
+    public function testEqual(): void
+    {
+        $rule = $this->create(2.3570226039552, Combo::EQ);
+        isSame('', $rule->test([1, 5, 1, 1, 1, 2, 8, 1, 1]));
+
+        $rule = $this->create(3, Combo::EQ);
+        isSame(
+            'The standard deviation (SD+) in the column is "2.3570226039552", which is not equal than the expected "3"',
+            $rule->test([1, 5, 1, 1, 1, 2, 8, 1, 1]),
+        );
+    }
+}

tests/Rules/Aggregate/ComboStandardDeviationTest.php → tests/Rules/Aggregate/ComboSdSampleTest.php

@@ -17,14 +17,14 @@
 namespace JBZoo\PHPUnit\Rules\Aggregate;
 
 use JBZoo\CsvBlueprint\Rules\AbstarctRule as Combo;
-use JBZoo\CsvBlueprint\Rules\Aggregate\ComboStandardDeviation;
+use JBZoo\CsvBlueprint\Rules\Aggregate\ComboSdSample;
 use JBZoo\PHPUnit\Rules\AbstractAggregateRuleCombo;
 
 use function JBZoo\PHPUnit\isSame;
 
-class ComboStandardDeviationTest extends AbstractAggregateRuleCombo
+class ComboSdSampleTest extends AbstractAggregateRuleCombo
 {
-    protected string $ruleClass = ComboStandardDeviation::class;
+    protected string $ruleClass = ComboSdSample::class;
 
     public function testEqual(): void
     {