Converting Statistical functions to be array-enabled (phase #2)

Author: MarkBaker

src/PhpSpreadsheet/Calculation/Statistical.php

@@ -1155,7 +1155,7 @@ public static function NEGBINOMDIST($failures, $successes, $probability)
      * @param mixed $stdDev Standard Deviation
      * @param mixed $cumulative
      *
-     * @return float|string The result, or a string containing an error
+     * @return array|float|string The result, or a string containing an error
      */
     public static function NORMDIST($value, $mean, $stdDev, $cumulative)
     {
@@ -1176,7 +1176,7 @@ public static function NORMDIST($value, $mean, $stdDev, $cumulative)
      * @param mixed $mean Mean Value
      * @param mixed $stdDev Standard Deviation
      *
-     * @return float|string The result, or a string containing an error
+     * @return array|float|string The result, or a string containing an error
      */
     public static function NORMINV($probability, $mean, $stdDev)
     {

src/PhpSpreadsheet/Calculation/Statistical/Distributions/Normal.php

@@ -2,12 +2,15 @@
 
 namespace PhpOffice\PhpSpreadsheet\Calculation\Statistical\Distributions;
 
+use PhpOffice\PhpSpreadsheet\Calculation\ArrayEnabled;
 use PhpOffice\PhpSpreadsheet\Calculation\Engineering;
 use PhpOffice\PhpSpreadsheet\Calculation\Exception;
 use PhpOffice\PhpSpreadsheet\Calculation\Functions;
 
 class Normal
 {
+    use ArrayEnabled;
+
     public const SQRT2PI = 2.5066282746310005024157652848110452530069867406099;
 
     /**
@@ -18,17 +21,23 @@ class Normal
      * testing.
      *
      * @param mixed $value Float value for which we want the probability
+     *                      Or can be an array of values
      * @param mixed $mean Mean value as a float
+     *                      Or can be an array of values
      * @param mixed $stdDev Standard Deviation as a float
+     *                      Or can be an array of values
      * @param mixed $cumulative Boolean value indicating if we want the cdf (true) or the pdf (false)
+     *                      Or can be an array of values
      *
-     * @return float|string The result, or a string containing an error
+     * @return array|float|string The result, or a string containing an error
+     *         If an array of numbers is passed as an argument, then the returned result will also be an array
+     *            with the same dimensions
      */
     public static function distribution($value, $mean, $stdDev, $cumulative)
     {
-        $value = Functions::flattenSingleValue($value);
-        $mean = Functions::flattenSingleValue($mean);
-        $stdDev = Functions::flattenSingleValue($stdDev);
+        if (is_array($value) || is_array($mean) || is_array($stdDev) || is_array($cumulative)) {
+            return self::evaluateArrayArguments([self::class, __FUNCTION__], $value, $mean, $stdDev, $cumulative);
+        }
 
         try {
             $value = DistributionValidations::validateFloat($value);
@@ -56,16 +65,21 @@ public static function distribution($value, $mean, $stdDev, $cumulative)
      * Returns the inverse of the normal cumulative distribution for the specified mean and standard deviation.
      *
      * @param mixed $probability Float probability for which we want the value
+     *                      Or can be an array of values
      * @param mixed $mean Mean Value as a float
+     *                      Or can be an array of values
      * @param mixed $stdDev Standard Deviation as a float
+     *                      Or can be an array of values
      *
-     * @return float|string The result, or a string containing an error
+     * @return array|float|string The result, or a string containing an error
+     *         If an array of numbers is passed as an argument, then the returned result will also be an array
+     *            with the same dimensions
      */
     public static function inverse($probability, $mean, $stdDev)
     {
-        $probability = Functions::flattenSingleValue($probability);
-        $mean = Functions::flattenSingleValue($mean);
-        $stdDev = Functions::flattenSingleValue($stdDev);
+        if (is_array($probability) || is_array($mean) || is_array($stdDev)) {
+            return self::evaluateArrayArguments([self::class, __FUNCTION__], $probability, $mean, $stdDev);
+        }
 
         try {
             $probability = DistributionValidations::validateProbability($probability);

tests/PhpSpreadsheetTests/Calculation/Functions/Statistical/NormDistTest.php

@@ -2,6 +2,7 @@
 
 namespace PhpOffice\PhpSpreadsheetTests\Calculation\Functions\Statistical;
 
+use PhpOffice\PhpSpreadsheet\Calculation\Calculation;
 use PhpOffice\PhpSpreadsheet\Calculation\Statistical;
 use PHPUnit\Framework\TestCase;
 
@@ -22,4 +23,32 @@ public function providerNORMDIST(): array
     {
         return require 'tests/data/Calculation/Statistical/NORMDIST.php';
     }
+
+    /**
+     * @dataProvider providerNormDistArray
+     */
+    public function testNormDistArray(array $expectedResult, string $values, string $mean, string $stdDev): void
+    {
+        $calculation = Calculation::getInstance();
+
+        $formula = "=NORMDIST({$values}, {$mean}, {$stdDev}, false)";
+        $result = $calculation->_calculateFormulaValue($formula);
+        self::assertEqualsWithDelta($expectedResult, $result, 1.0e-14);
+    }
+
+    public function providerNormDistArray(): array
+    {
+        return [
+            'row/column vectors' => [
+                [
+                    [0.04324582990797181, 0.03549422283581691, 0.026885636057682592],
+                    [0.07365402806066465, 0.038837210996642585, 0.015790031660178828],
+                    [0.12098536225957167, 0.0022159242059690033, 7.991870553452737E-6],
+                ],
+                '12',
+                '{10, 6, 3}',
+                '{9; 5; 2}',
+            ],
+        ];
+    }
 }

tests/PhpSpreadsheetTests/Calculation/Functions/Statistical/NormInvTest.php

@@ -2,6 +2,7 @@
 
 namespace PhpOffice\PhpSpreadsheetTests\Calculation\Functions\Statistical;
 
+use PhpOffice\PhpSpreadsheet\Calculation\Calculation;
 use PhpOffice\PhpSpreadsheet\Calculation\Statistical;
 use PHPUnit\Framework\TestCase;
 
@@ -22,4 +23,32 @@ public function providerNORMINV(): array
     {
         return require 'tests/data/Calculation/Statistical/NORMINV.php';
     }
+
+    /**
+     * @dataProvider providerNormInvArray
+     */
+    public function testNormInvArray(array $expectedResult, string $probabilities, string $mean, string $stdDev): void
+    {
+        $calculation = Calculation::getInstance();
+
+        $formula = "=NORMINV({$probabilities}, {$mean}, {$stdDev})";
+        $result = $calculation->_calculateFormulaValue($formula);
+        self::assertEqualsWithDelta($expectedResult, $result, 1.0e-14);
+    }
+
+    public function providerNormInvArray(): array
+    {
+        return [
+            'row/column vectors' => [
+                [
+                    [2.651020499553155, 4.651020499553155],
+                    [1.9765307493297324, 3.9765307493297324],
+                    [-0.7214282515639576, 1.2785717484360424],
+                ],
+                '0.25',
+                '{4, 6}',
+                '{2; 3; 7}',
+            ],
+        ];
+    }
 }