legacy-libs/grpc/deps/grpc/third_party/abseil-cpp/absl/random/internal/distribution_test_util.h

   1 // Copyright 2017 The Abseil Authors.
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //      https://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 #ifndef ABSL_RANDOM_INTERNAL_DISTRIBUTION_TEST_UTIL_H_
  16 #define ABSL_RANDOM_INTERNAL_DISTRIBUTION_TEST_UTIL_H_
  17
  18 #include <cstddef>
  19 #include <iostream>
  20 #include <vector>
  21
  22 #include "absl/strings/string_view.h"
  23 #include "absl/types/span.h"
  24
  25 // NOTE: The functions in this file are test only, and are should not be used in
  26 // non-test code.
  27
  28 namespace absl {
  29 namespace random_internal {
  30
  31 // http://webspace.ship.edu/pgmarr/Geo441/Lectures/Lec%205%20-%20Normality%20Testing.pdf
  32
  33 // Compute the 1st to 4th standard moments:
  34 // mean, variance, skewness, and kurtosis.
  35 // http://www.itl.nist.gov/div898/handbook/eda/section3/eda35b.htm
  36 struct DistributionMoments {
  37   size_t n = 0;
  38   double mean = 0.0;
  39   double variance = 0.0;
  40   double skewness = 0.0;
  41   double kurtosis = 0.0;
  42 };
  43 DistributionMoments ComputeDistributionMoments(
  44     absl::Span<const double> data_points);
  45
  46 std::ostream& operator<<(std::ostream& os, const DistributionMoments& moments);
  47
  48 // Computes the Z-score for a set of data with the given distribution moments
  49 // compared against `expected_mean`.
  50 double ZScore(double expected_mean, const DistributionMoments& moments);
  51
  52 // Returns the probability of success required for a single trial to ensure that
  53 // after `num_trials` trials, the probability of at least one failure is no more
  54 // than `p_fail`.
  55 double RequiredSuccessProbability(double p_fail, int num_trials);
  56
  57 // Computes the maximum distance from the mean tolerable, for Z-Tests that are
  58 // expected to pass with `acceptance_probability`. Will terminate if the
  59 // resulting tolerance is zero (due to passing in 0.0 for
  60 // `acceptance_probability` or rounding errors).
  61 //
  62 // For example,
  63 // MaxErrorTolerance(0.001) = 0.0
  64 // MaxErrorTolerance(0.5) = ~0.47
  65 // MaxErrorTolerance(1.0) = inf
  66 double MaxErrorTolerance(double acceptance_probability);
  67
  68 // Approximation to inverse of the Error Function in double precision.
  69 // (http://people.maths.ox.ac.uk/gilesm/files/gems_erfinv.pdf)
  70 double erfinv(double x);
  71
  72 // Beta(p, q) = Gamma(p) * Gamma(q) / Gamma(p+q)
  73 double beta(double p, double q);
  74
  75 // The inverse of the normal survival function.
  76 double InverseNormalSurvival(double x);
  77
  78 // Returns whether actual is "near" expected, based on the bound.
  79 bool Near(absl::string_view msg, double actual, double expected, double bound);
  80
  81 // Implements the incomplete regularized beta function, AS63, BETAIN.
  82 //    https://www.jstor.org/stable/2346797
  83 //
  84 // BetaIncomplete(x, p, q), where
  85 //   `x` is the value of the upper limit
  86 //   `p` is beta parameter p, `q` is beta parameter q.
  87 //
  88 // NOTE: This is a test-only function which is only accurate to within, at most,
  89 // 1e-13 of the actual value.
  90 //
  91 double BetaIncomplete(double x, double p, double q);
  92
  93 // Implements the inverse of the incomplete regularized beta function, AS109,
  94 // XINBTA.
  95 //   https://www.jstor.org/stable/2346798
  96 //   https://www.jstor.org/stable/2346887
  97 //
  98 // BetaIncompleteInv(p, q, beta, alhpa)
  99 //   `p` is beta parameter p, `q` is beta parameter q.
 100 //   `alpha` is the value of the lower tail area.
 101 //
 102 // NOTE: This is a test-only function and, when successful, is only accurate to
 103 // within ~1e-6 of the actual value; there are some cases where it diverges from
 104 // the actual value by much more than that.  The function uses Newton's method,
 105 // and thus the runtime is highly variable.
 106 double BetaIncompleteInv(double p, double q, double alpha);
 107
 108 }  // namespace random_internal
 109 }  // namespace absl
 110
 111 #endif  // ABSL_RANDOM_INTERNAL_DISTRIBUTION_TEST_UTIL_H_