cdfn, cdfnc
==============================================
Purpose
----------------
:func:`cdfn` computes the cumulative distribution function
(cdf) of the Normal distribution. :func:`cdfnc` computes 1
minus the cdf of the Normal distribution.
Format
----------------
.. function:: p = cdfn(x[, mu, sigma])
p = cdfnc(x)
:param x: Values at which to evaluate the normal cumulative distribution function or the complement of the normal cdf.
:type x: NxK matrix
:param mu: Optional input, mean parameter.
:type mu: scalar
:param std: Optional input, standard deviation.
:type std: scalar
:return p: Each element in *p* is the normal cumulative distribution function evaluated at the corresponding element in *x*.
:rtype p: NxK matrix
:return pc: Each element in *pc* is the complement of the normal cumulative distribution function evaluated at the corresponding element in *x*.
:rtype pc: NxK matrix
Examples
----------------
Example 1: Basic use
++++++++++++++++++++
::
// Value to compute
x = 0.5;
p = cdfn(x);
pc = cdfnc(x);
After above code,
::
p = 0.69146246
pc = 0.30853754
Example 2: Specify mean and standard deviation
++++++++++++++++++++++++++++++++++++++++++++++
::
// Value
x = 0.5;
// Mean
mu = 1.1;
// Standard deviation
std = 3;
p = cdfn(x, mu, std);
After above code,
::
p = 0.42074029
Example 3
++++++++++
::
// Value
x = { -2 -1 0 1 2 };
p = cdfn(x);
pc = cdfnc(x);
After above code,
::
x = -2.0000000 -1.0000000 0.0000000 1.0000000 2.0000000
p = 0.0227501 0.15865525 0.5000000 0.8413447 0.9772498
pc = 0.9772498 0.84134475 0.5000000 0.1586552 0.0227501
Remarks
------------
Note that:
::
cdfn(x) + cdfnc(x) = 1
However, many applications expect :code:`cdfn(x)` to approach 1 but never
actually reach it. Because of this, we have capped the return value of
:func:`cdfn` at :math:`1 - machine\:\ epsilon`, or approximately :math:`1 - 1.11e-16`. As the
relative error of :func:`cdfn` is about :math:`\pm 5e-15` for :code:`cdfn(x)` around 1, this does
not invalidate the result. What it does mean is that for :math:`abs(x) >
\approx 8.2924`, the identity does not hold true. If you have a need
for the uncapped value of :func:`cdfn`, the following code will return it:
::
p = cdfn(x);
if p >= 1-eps;
p = 1;
endif;
where the value of machine epsilon is obtained as follows:
::
x = 1;
do while 1-x /= 1;
eps = x;
x = x/2;
endo;
Note that this is an alternate definition of machine epsilon. Machine
epsilon is usually defined as the smallest number such that
:math:`1 + machine\:\ epsilon > 1`, which is about 2.23e-16. This defines machine
epsilon as the smallest number such that :math:`1 - machine\:\ epsilon < 1`, or
about 1.11e-16.
The :func:`erf` and :func:`erfc` functions are also provided, and may sometimes be more
useful than :func:`cdfn` and :func:`cdfnc`.
.. seealso:: Functions :func:`erf`, :func:`erfc`, :func:`cdfBeta`, :func:`cdfChic`, :func:`cdfTc`, :func:`cdfFc`, :func:`gamma`