ceph/src/boost/libs/math/doc/distributions/skew_normal.qbk

   1 [section:skew_normal_dist Skew Normal Distribution]
   2
   3 ``#include <boost/math/distributions/skew_normal.hpp>``
   4
   5    namespace boost{ namespace math{
   6
   7    template <class RealType = double,
   8              class ``__Policy``   = ``__policy_class`` >
   9    class skew_normal_distribution;
  10
  11    typedef skew_normal_distribution<> normal;
  12
  13    template <class RealType, class ``__Policy``>
  14    class skew_normal_distribution
  15    {
  16    public:
  17       typedef RealType value_type;
  18       typedef Policy   policy_type;
  19       // Constructor:
  20       skew_normal_distribution(RealType location = 0, RealType scale = 1, RealType shape = 0);
  21       // Accessors:
  22       RealType location()const; // mean if normal.
  23       RealType scale()const; // width, standard deviation if normal.
  24       RealType shape()const; // The distribution is right skewed if shape > 0 and is left skewed if shape < 0.
  25                              // The distribution is normal if shape is zero.
  26    };
  27
  28    }} // namespaces
  29
  30 The skew normal distribution is a variant of the most well known
  31 Gaussian statistical distribution.
  32
  33 The skew normal distribution with shape zero resembles the
  34 [@http://en.wikipedia.org/wiki/Normal_distribution Normal Distribution],
  35 hence the latter can be regarded as a special case of the more generic skew normal distribution.
  36
  37 If the standard (mean = 0, scale = 1) normal distribution probability density function is
  38
  39 [space][space][equation normal01_pdf]
  40
  41 and the cumulative distribution function
  42
  43 [space][space][equation normal01_cdf]
  44
  45 then the [@http://en.wikipedia.org/wiki/Probability_density_function PDF]
  46 of the [@http://en.wikipedia.org/wiki/Skew_normal_distribution skew normal distribution]
  47 with shape parameter [alpha], defined by O'Hagan and Leonhard (1976) is
  48
  49 [space][space][equation skew_normal_pdf0]
  50
  51 Given [@http://en.wikipedia.org/wiki/Location_parameter location] [xi],
  52 [@http://en.wikipedia.org/wiki/Scale_parameter scale] [omega],
  53 and [@http://en.wikipedia.org/wiki/Shape_parameter shape] [alpha],
  54 it can be
  55 [@http://en.wikipedia.org/wiki/Skew_normal_distribution transformed],
  56 to the form:
  57
  58 [space][space][equation skew_normal_pdf]
  59
  60 and [@http://en.wikipedia.org/wiki/Cumulative_distribution_function CDF]:
  61
  62 [space][space][equation skew_normal_cdf]
  63
  64 where ['T(h,a)] is Owen's T function, and ['[Phi](x)] is the normal distribution.
  65
  66 The variation the PDF and CDF with its parameters is illustrated
  67 in the following graphs:
  68
  69 [graph skew_normal_pdf]
  70 [graph skew_normal_cdf]
  71
  72 [h4 Member Functions]
  73
  74    skew_normal_distribution(RealType location = 0, RealType scale = 1, RealType shape = 0);
  75
  76 Constructs a skew_normal distribution with location [xi],
  77 scale [omega] and shape [alpha].
  78
  79 Requires scale > 0, otherwise __domain_error is called.
  80
  81    RealType location()const;
  82
  83 returns the location [xi] of this distribution,
  84
  85    RealType scale()const;
  86
  87 returns the scale [omega] of this distribution,
  88
  89    RealType shape()const;
  90
  91 returns the shape [alpha] of this distribution.
  92
  93 (Location and scale function match other similar distributions,
  94 allowing the functions `find_location` and `find_scale` to be used generically).
  95
  96 [note While the shape parameter may be chosen arbitrarily (finite),
  97 the resulting [*skewness] of the distribution is in fact limited to about (-1, 1);
  98 strictly, the interval is (-0.9952717, 0.9952717).
  99
 100 A parameter [delta] is related to the shape [alpha] by
 101 [delta] = [alpha] / (1 + [alpha][pow2]),
 102 and used in the expression for skewness
 103 [equation skew_normal_skewness]
 104 ] [/note]
 105
 106 [h4 References]
 107
 108 * [@http://azzalini.stat.unipd.it/SN/ Skew-Normal Probability Distribution] for many links and bibliography.
 109 * [@http://azzalini.stat.unipd.it/SN/Intro/intro.html A very brief introduction to the skew-normal distribution]
 110 by Adelchi Azzalini (2005-11-2).
 111 * See a [@http://www.tri.org.au/azzalini.html skew-normal function animation].
 112
 113 [h4 Non-member Accessors]
 114
 115 All the [link math_toolkit.dist_ref.nmp usual non-member accessor functions]
 116 that are generic to all distributions are supported: __usual_accessors.
 117
 118 The domain of the random variable is ['-[max_value], +[min_value]].
 119 Infinite values are not supported.
 120
 121 There are no [@http://en.wikipedia.org/wiki/Closed-form_expression closed-form expression]
 122 known for the mode and median, but these are computed for the
 123
 124 * mode - by finding the maximum of the PDF.
 125 * median - by computing `quantile(1/2)`.
 126
 127 The maximum of the PDF is sought through searching the root of f'(x)=0.
 128
 129 Both involve iterative methods that will have lower accuracy than other estimates.
 130
 131 [h4 Testing]
 132
 133 __R using library(sn) described at
 134 [@http://azzalini.stat.unipd.it/SN/  Skew-Normal Probability Distribution],
 135 and at [@http://cran.r-project.org/web/packages/sn/sn.pd R skew-normal(sn) package].
 136
 137 Package sn provides functions related to the skew-normal (SN)
 138 and the skew-t (ST) probability distributions,
 139 both for the univariate and for the the multivariate case,
 140 including regression models.
 141
 142 __Mathematica was also used to generate some more accurate spot test data.
 143
 144 [h4 Accuracy]
 145
 146 The skew_normal distribution with shape = zero is implemented as a special case,
 147 equivalent to the normal distribution in terms of the
 148 [link math_toolkit.sf_erf.error_function error function],
 149 and therefore should have excellent accuracy.
 150
 151 The PDF and mean, variance, skewness and kurtosis are also accurately evaluated using
 152 [@http://en.wikipedia.org/wiki/Analytical_expression analytical expressions].
 153 The CDF requires [@http://en.wikipedia.org/wiki/Owen%27s_T_function Owen's T function]
 154 that is evaluated using a Boost C++ __owens_t implementation of the algorithms of
 155 M. Patefield and D. Tandy, Journal of Statistical Software, 5(5), 1-25 (2000);
 156 the complicated accuracy of this function is discussed in detail at __owens_t.
 157
 158 The median and mode are calculated by iterative root finding, and both will be less accurate.
 159
 160 [h4 Implementation]
 161
 162 In the following table, [xi] is the location of the distribution,
 163 and [omega] is its scale, and [alpha] is its shape.
 164
 165 [table
 166 [[Function][Implementation Notes]]
 167 [[pdf][Using:[equation skew_normal_pdf] ]]
 168 [[cdf][Using: [equation skew_normal_cdf][br]
 169 where ['T(h,a)] is Owen's T function, and ['[Phi](x)] is the normal distribution. ]]
 170 [[cdf complement][Using: complement of normal distribution + 2 * Owens_t]]
 171 [[quantile][Maximum of the pdf is sought through searching the root of f'(x)=0]]
 172 [[quantile from the complement][-quantile(SN(-location [xi], scale [omega], -shape[alpha]), p)]]
 173 [[location][location [xi]]]
 174 [[scale][scale [omega]]]
 175 [[shape][shape [alpha]]]
 176 [[median][quantile(1/2)]]
 177 [[mean][[equation skew_normal_mean]]]
 178 [[mode][Maximum of the pdf is sought through searching the root of f'(x)=0]]
 179 [[variance][[equation skew_normal_variance] ]]
 180 [[skewness][[equation skew_normal_skewness] ]]
 181 [[kurtosis][kurtosis excess-3]]
 182 [[kurtosis excess] [ [equation skew_normal_kurt_ex] ]]
 183 ] [/table]
 184
 185 [endsect] [/section:skew_normal_dist skew_Normal]
 186
 187 [/ skew_normal.qbk
 188   Copyright 2012 Bejamin Sobotta, John Maddock and Paul A. Bristow.
 189   Distributed under the Boost Software License, Version 1.0.
 190   (See accompanying file LICENSE_1_0.txt or copy at
 191   http://www.boost.org/LICENSE_1_0.txt).
 192 ]
 193