----------------------------------------------
lines 5-399 of file: xrst/model/statistic.xrst
----------------------------------------------

{xrst_begin statistic}
{xrst_spell
  cen
  erfc
}

Some Statistical Function Definitions
#####################################

Notation
********

y
=
If :math:`z` is not present,
we are computing residual and statistical density for :math:`y`
or :math:`\log( y + \eta )`.

z
=
If :math:`z` is present,
we are computing the residual and statistical density for :math:`z - y`
or :math:`\log( z + \eta ) - \log ( y + \eta )`.
This is used for smoothing difference of :ref:`model_variables-name`
with respect to age and time.

mu
==
In the linear case, :math:`\mu` denotes
the expected value for :math:`y` or
the difference between :math:`y` and :math:`z`.
In the log case, it denotes
the expected value for :math:`\log( y + \eta )` or
the difference between :math:`\log( y + \eta )` and
:math:`\log( z + \eta )`.

delta
=====
If the density is
:ref:`density_table@Notation@Linear` ,
this is the standard deviation for :math:`y` or :math:`z - y`,
If the density is
:ref:`density_table@Notation@Log Scaled` ,
this is the standard deviation for :math:`\log( y + \eta )`
or :math:`\log( z + \eta )  - \log ( y + \eta )`.
Note that :math:`\delta` has a different definition for different cases:

#. For data cases, other than binomial, :math:`\delta` is define by
   the transformed standard deviation
   :ref:`delta<data_like@Transformed Standard Deviation, delta_i(theta)>`
   :math:`\delta_i( \theta )`.
#. For value prior cases, :math:`\delta` is defined by
   the transformed standard deviation
   :ref:`fixed_value@delta_j` ,
   :ref:`random_value@delta_j` ,
#. For difference prior cases, :math:`\delta` is the same as
   the prior table standard deviation
   :ref:`smooth_dage@sigma_ij` ,
   :ref:`smooth_dtime@sigma_ij` .

eta
===
We use :math:`\eta` to denote the offset in log transform
for the corresponding entry in the
:ref:`data<data_table@eta>` or
:ref:`prior<prior_table@eta>` table.

nu
==
We use :math:`\nu` to denote the degrees of freedom in Student's-t
for the corresponding entry in the
:ref:`data<data_table@nu>` or
:ref:`prior<prior_table@nu>` table.

d
=
We use :math:`d` to denote the *density_id*
for the corresponding entry in the
:ref:`data<data_table@density_id>` or
:ref:`prior<prior_table@density_id>` table.
In an abuse of notation,
we write :math:`\eta[d]`, :math:`\nu[d]`
for the offset and degrees corresponding to the same entry in the
data or prior table.

Weighted Residual Function, R
*****************************

Value
=====
If the density is
:ref:`density_table@density_name@uniform` ,
the weighted residual function for values is

.. math::

    R(y, \mu, \delta, d) = 0

If the density is
:ref:`density_table@Notation@Linear` ,
the weighted residual function for values is

.. math::

    R(y, \mu, \delta, d) = \frac{y - \mu}{\delta}

If the density is
:ref:`density_table@Notation@Log Scaled` ,
the weighted residual function for values is

.. math::

    R(y, \mu, \delta, d)
    =
    \frac{
        \log( y + \eta[d] ) - \log( \mu + \eta[d] )
    }{
        \delta
    }

Note that, for both the linear and log case,
:math:`\mu` has the same units as :math:`y`.

Difference
==========
If the density is uniform,
the weighted residual function for differences is

.. math::

    R(z, y, \mu, \delta, d) = 0

If the density is
:ref:`density_table@Notation@Linear` ,
the weighted residual function for differences is

.. math::

    R(z, y, \mu, \delta, d) = \frac{z - y - \mu}{\delta}

Note that, in the linear case, all the arguments (except :math:`d`)
have the same units.
If the density is
:ref:`density_table@Notation@Log Scaled` ,
the weighted residual function for differences is

.. math::

    R(z, y, \mu, \delta, d)
    =
    \frac{
        \log(z + \eta[d] ) - \log( y + \eta[d] ) - \mu
    }{
        \delta
    }

Note that in the log case, :math:`z, y` and :math:`\eta` have the same units
while :math:`\mu` and :math:`\delta` are in log space.

Log-Density Function, D
***********************
In the discussion below,
log scaling refers to scaling the argument to the density function and
log-density refers to taking the log of the result of the
density function.

Uniform
=======
If the density is ``uniform`` ,
the log-density function for values :math:`D(y, \mu, \delta, d)`,
and for differences :math:`D(z, y, \mu, \delta, d)`,
are both defined by :math:`D = 0`.

Binomial
========
The :ref:`density_table@density_name@binomial`
density can only used for the likelihood of data values
(not for variable priors).
The corresponding
log-density function :math:`D(y, \mu, \delta, d)` is defined by

.. math::

    D
    =
    \log \left[ {n \choose k} \mu^k (1- \mu )^{n-k} \right]

#. Here :math:`n` is the sample size for this data value :math:`y` ,
   :math:`k = n y` is the success count, and
   :math:`\mu` is the :ref:`average integrand <avg_integrand-name>`
   corresponding to :math:`y` .
#. The standard deviation for :math:`k` is :math:`\sqrt{n \mu (1 - \mu)}` .
   Dividing by :math:`n` and dropping the :math:`(1 - \mu)` term,
   the weight residuals for this distribution are computed using
   :math:`\delta = \sqrt{\mu / n}` .
#. If the average integrand for binomial data is zero, you will get
   a message saying that the corresponding standard deviation is
   not greater than zero.

Gaussian
========
If the density name is ``gaussian`` ,
the log-density functions for values :math:`D(y, \mu, \delta, d)`,
and for differences :math:`D(z, y, \mu, \delta, d)`,
are defined by

.. math::

    D
    =
    - \log \left( \delta \sqrt{2 \pi} \right) - \frac{1}{2} R^2

where :math:`D` and :math:`R` have the same arguments;
see :ref:`statistic@Weighted Residual Function, R` .

Censored Gaussian
=================
If the density name is ``cen_gaussian`` ,
the log-density function is not defined for differences.
The log-density function for values :math:`y > 0`
is the same as for the ``gaussian`` case.
The log-density function for the values :math:`y \leq 0`,
is defined by

.. math::

    D(y, \mu, \delta, d)
    =
    \log ( \R{erfc}[ \mu / ( \delta \sqrt{2} ) ] ) - \log(2)

where :math:`\R{erfc}` is the complementary error function;
see the Gaussian case for the
:ref:`censored density<censor_density@Gaussian@Censored Density, G(y,mu,delta,c)>`
where the censoring value is :math:`c = 0`.

Log-Gaussian
============
If the density name is ``log_gaussian`` ,
the log-density function for values is

.. math::

    D(y, \mu, \delta, d)
    =
    - \log \left[ \delta \sqrt{2 \pi} \right]
    - \frac{1}{2} R(y, \mu, \delta, d)^2

The log-density function for differences is

.. math::

    D(z, y, \mu, \delta, d)
    =
    - \log \left( \delta \sqrt{2 \pi} \right)
    - \frac{1}{2} R(z, y, \mu, \delta, d)^2

Censored Log-Gaussian
=====================
If the density name is ``cen_log_gaussian`` ,
the log-density function is not defined for differences.
The log-density function for values :math:`y > 0`
is the same as for the ``log_gaussian`` case.
The log-density function for the values :math:`y \leq 0`,
is defined by

.. math::

    D(y, \mu, \delta, d)
    =
    \log ( \R{erfc}[ ( \mu - \eta ) / ( \delta \sqrt{2} ) ] ) - \log(2)

where we the arguments to :math:`\delta` are the same as
in the log Gaussian case
and :math:`\R{erfc}` is the complementary error function;
see the Gaussian case for the
:ref:`censored density<censor_density@Gaussian@Censored Density, G(y,mu,delta,c)>`
where the censoring value is :math:`c = \eta`.

Laplace
=======
If the density name is ``laplace`` ,
the log-density functions for values :math:`D(y, \mu, \delta, d)`,
and for differences :math:`D(z, y, \mu, \delta, d)`,
are defined by

.. math::

    D
    =
    - \log \left( \delta \sqrt{2} \right) - \sqrt{2} | R |

where :math:`D` and :math:`R` have the same arguments.

Censored Laplace
================
If the density name is ``cen_laplace`` ,
the log-density function is not defined for differences.
The log-density function for values :math:`y > 0`
is the same as for the ``laplace`` case.
The log-density function for the values :math:`y \leq 0`,
is defined by

.. math::

    D(y, \mu, \delta, d)
    =
    - \mu \sqrt{2} / \delta - \log(2)

where :math:`\R{erfc}` is the complementary error function;
see the Gaussian case for the
:ref:`censored density<censor_density@Laplace@Censored Density, L(y,mu,delta,c)>`
where the censoring value is :math:`c = 0`.

Log-Laplace
===========
If the density name is ``log_laplace`` ,
the log-density function for values is

.. math::

    D(y, \mu, \delta, d)
    =
    - \log \left[ \delta \sqrt{2} \right]
    - \sqrt{2} \left| R(y, \mu, \delta, d) \right|

The log-density function for differences is

.. math::

    D(z, y, \mu, \delta, d)
    =
    - \log \left( \delta \sqrt{2} \right)
    - \sqrt{2} \left| R(z, y, \mu, \delta, d) \right|

Censored Log-Laplace
====================
If the density name is ``cen_log_laplace`` ,
the log-density function is not defined for differences.
The log-density function for values :math:`y > 0`
is the same as for the ``log_laplace`` case.
The log-density function for the values :math:`y \leq 0`,
is defined by

.. math::

    D(y, \mu, \delta, d)
    =
    - ( \mu - \eta ) \sqrt{2} / \delta - \log(2)

where we the arguments to :math:`\delta` are the same as
in the log Laplace case.
See the Laplace case for the
:ref:`censored density<censor_density@Laplace@Censored Density, L(y,mu,delta,c)>`
where the censoring value is :math:`c = \eta`.

Student's-t
===========
If the density name is ``students`` ,
the log-density functions for values :math:`D(y, \mu, \delta, d)`,
and for differences :math:`D(z, y, \mu, \delta, d)`,
are defined by

.. math::

    D
    =
    \log \left(
    \frac{ \Gamma( ( \nu + 1 ) / 2 ) }{ \sqrt{ \nu \pi } \Gamma( \nu / 2 ) }
    \right)
    -
    \frac{\nu + 1}{2} \log \left( 1 + R^2 / ( \nu - 2 ) \right)

where :math:`D` and :math:`R` have the same arguments
and we have abbreviated :math:`\nu[d]` using just :math:`\nu`.

Log-Student's-t
===============
If the density name is ``log_students`` ,
the log-density functions for values :math:`D(y, \mu, \delta, d)`,
and for differences :math:`D(z, y, \mu, \delta, d)`,
are defined by

.. math::

    D
    =
    \log \left(
    \frac{ \Gamma( ( \nu + 1 ) / 2 ) }{ \sqrt{ \nu \pi } \Gamma( \nu / 2 ) }
    \right)
    -
    \frac{\nu + 1}{2} \log \left( 1 + R^2 / ( \nu - 2 ) \right)

where :math:`D` and :math:`R` have the same arguments.

{xrst_end statistic}