[Summary view]

Differences Between: [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

   1  <?php
   2  
   3  namespace PhpOffice\PhpSpreadsheet\Calculation\Statistical\Distributions;
   4  
   5  use PhpOffice\PhpSpreadsheet\Calculation\ArrayEnabled;
   6  use PhpOffice\PhpSpreadsheet\Calculation\Functions;
   7  use PhpOffice\PhpSpreadsheet\Calculation\Information\ExcelError;
   8  use PhpOffice\PhpSpreadsheet\Calculation\Statistical\Averages;
   9  use PhpOffice\PhpSpreadsheet\Calculation\Statistical\StandardDeviations;
  10  
  11  class StandardNormal
  12  {
  13      use ArrayEnabled;
  14  
  15      /**
  16       * NORMSDIST.
  17       *
  18       * Returns the standard normal cumulative distribution function. The distribution has
  19       * a mean of 0 (zero) and a standard deviation of one. Use this function in place of a
  20       * table of standard normal curve areas.
  21       *
  22       * NOTE: We don't need to check for arrays to array-enable this function, because that is already
  23       *       handled by the logic in Normal::distribution()
  24       *       All we need to do is pass the value through as scalar or as array.
  25       *
  26       * @param mixed $value Float value for which we want the probability
  27       *                      Or can be an array of values
  28       *
  29       * @return array|float|string The result, or a string containing an error
  30       *         If an array of numbers is passed as an argument, then the returned result will also be an array
  31       *            with the same dimensions
  32       */
  33      public static function cumulative($value)
  34      {
  35          return Normal::distribution($value, 0, 1, true);
  36      }
  37  
  38      /**
  39       * NORM.S.DIST.
  40       *
  41       * Returns the standard normal cumulative distribution function. The distribution has
  42       * a mean of 0 (zero) and a standard deviation of one. Use this function in place of a
  43       * table of standard normal curve areas.
  44       *
  45       * NOTE: We don't need to check for arrays to array-enable this function, because that is already
  46       *       handled by the logic in Normal::distribution()
  47       *       All we need to do is pass the value and cumulative through as scalar or as array.
  48       *
  49       * @param mixed $value Float value for which we want the probability
  50       *                      Or can be an array of values
  51       * @param mixed $cumulative Boolean value indicating if we want the cdf (true) or the pdf (false)
  52       *                      Or can be an array of values
  53       *
  54       * @return array|float|string The result, or a string containing an error
  55       *         If an array of numbers is passed as an argument, then the returned result will also be an array
  56       *            with the same dimensions
  57       */
  58      public static function distribution($value, $cumulative)
  59      {
  60          return Normal::distribution($value, 0, 1, $cumulative);
  61      }
  62  
  63      /**
  64       * NORMSINV.
  65       *
  66       * Returns the inverse of the standard normal cumulative distribution
  67       *
  68       * @param mixed $value float probability for which we want the value
  69       *                      Or can be an array of values
  70       *
  71       * NOTE: We don't need to check for arrays to array-enable this function, because that is already
  72       *       handled by the logic in Normal::inverse()
  73       *       All we need to do is pass the value through as scalar or as array
  74       *
  75       * @return array|float|string The result, or a string containing an error
  76       *         If an array of numbers is passed as an argument, then the returned result will also be an array
  77       *            with the same dimensions
  78       */
  79      public static function inverse($value)
  80      {
  81          return Normal::inverse($value, 0, 1);
  82      }
  83  
  84      /**
  85       * GAUSS.
  86       *
  87       * Calculates the probability that a member of a standard normal population will fall between
  88       *     the mean and z standard deviations from the mean.
  89       *
  90       * @param mixed $value
  91       *                      Or can be an array of values
  92       *
  93       * @return array|float|string The result, or a string containing an error
  94       *         If an array of numbers is passed as an argument, then the returned result will also be an array
  95       *            with the same dimensions
  96       */
  97      public static function gauss($value)
  98      {
  99          if (is_array($value)) {
 100              return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $value);
 101          }
 102  
 103          if (!is_numeric($value)) {
 104              return ExcelError::VALUE();
 105          }
 106          /** @var float */
 107          $dist = self::distribution($value, true);
 108  
 109          return $dist - 0.5;
 110      }
 111  
 112      /**
 113       * ZTEST.
 114       *
 115       * Returns the one-tailed P-value of a z-test.
 116       *
 117       * For a given hypothesized population mean, x, Z.TEST returns the probability that the sample mean would be
 118       *     greater than the average of observations in the data set (array) — that is, the observed sample mean.
 119       *
 120       * @param mixed $dataSet The dataset should be an array of float values for the observations
 121       * @param mixed $m0 Alpha Parameter
 122       *                      Or can be an array of values
 123       * @param mixed $sigma A null or float value for the Beta (Standard Deviation) Parameter;
 124       *                       if null, we use the standard deviation of the dataset
 125       *                      Or can be an array of values
 126       *
 127       * @return array|float|string (string if result is an error)
 128       *         If an array of numbers is passed as an argument, then the returned result will also be an array
 129       *            with the same dimensions
 130       */
 131      public static function zTest($dataSet, $m0, $sigma = null)
 132      {
 133          if (is_array($m0) || is_array($sigma)) {
 134              return self::evaluateArrayArgumentsSubsetFrom([self::class, __FUNCTION__], 1, $dataSet, $m0, $sigma);
 135          }
 136  
 137          $dataSet = Functions::flattenArrayIndexed($dataSet);
 138  
 139          if (!is_numeric($m0) || ($sigma !== null && !is_numeric($sigma))) {
 140              return ExcelError::VALUE();
 141          }
 142  
 143          if ($sigma === null) {
 144              /** @var float */
 145              $sigma = StandardDeviations::STDEV($dataSet);
 146          }
 147          $n = count($dataSet);
 148  
 149          return 1 - self::cumulative((Averages::average($dataSet) - $m0) / ($sigma / sqrt($n)));
 150      }
 151  }