------------------------------------------------
lines 5-163 of file: xrst/table/prior_table.xrst
------------------------------------------------

{xrst_begin prior_table}

The Prior Table
###############

Purpose
*******
Each row of the ``prior`` table defines a statistical
prior for a single :ref:`model_variables-name` ; i.e.,
one scalar value.
Multiple rows of the prior table may apply to the same model variable;
e.g., there may be a
:ref:`value prior<smooth_grid_table@value_prior_id>` ,
:ref:`age difference prior<smooth_grid_table@dage_prior_id>` , and
:ref:`time difference prior<smooth_grid_table@dtime_prior_id>`
for the same model variable.

prior_id
********
This column has type ``integer`` and is the primary key for this table.
Its initial value is zero, and it increments by one for each row.

prior_name
**********
This column has type ``text`` and has a different value for every row;
i.e., the names are unique and can act as substitutes for the primary key.
The names are intended to be easier for a human to remember than the ids.

density_id
**********
This column has type ``integer`` and its value is the
:ref:`density_table-name` primary key that identifies the
density function for this prior.
A prior *density_id* cannot correspond to a
+:ref:`density_table@density_name@binomial` density.

lower
*****
This column has type ``real`` and specifies a lower bound
for the prior.
Note that the value ``null`` is interpreted as minus infinity; see
:ref:`database@Null@Bounds` .

upper
*****
This column has type ``real`` and specifies a upper bound
for the prior.
Note that the value ``null`` is interpreted as plus infinity; see
:ref:`database@Null@Bounds` .
It *upper* is ``null`` then ``lower`` must also be ``null`` ;
i.e., either both limits or neither limit is specified.

mean
****
This column has type ``real`` and specifies the mean
(before truncation by the lower and upper limits)
for the prior.
It must hold that

   *lower* <= *mean* <= *upper*

uniform
=======
If *density_id* corresponds to a
:ref:`density_table@density_name@uniform` ,
and :ref:`init_command@start_var_table`
is set to the prior mean,
the value of *mean* only affects the
starting point for the optimization.
Otherwise, when the density is uniform, the value of *mean*
has no effect.

std
***
This column has type ``real`` .
In the case where *density* is ``uniform`` ,
this value is not used and can be ``null`` .
Otherwise, this value must be a positive number.
These standard deviations are
before truncation by the lower and upper limits.

Linear Scaling
==============
If the density is :ref:`density_table@Notation@Linear` ,
*std* is the standard deviation for the corresponding random variable.

Log Scaling
===========
If the density is
:ref:`density_table@Notation@Log Scaled` and for a
:ref:`statistic@Weighted Residual Function, R@Value` ,

   *delta* = ``log`` ( *mean* + *eta* + *std* ) ``- log`` ( *mean* + *eta* )

is the standard deviation for the
log of the random variable plus *eta* ; see
:ref:`fixed_value<fixed_value@delta_j>` and
:ref:`random_value<random_value@delta_j>`  definitions of *delta* .
Using the notation ``~=`` for approximately equal,
and taking the derivative of the log at the midpoint for the difference,
we get

   *delta* ~= *std* / ( *mean* + *eta* + *std* /2 )

If this density is used for a
:ref:`statistic@Weighted Residual Function, R@Difference` ,
*std* is the standard deviation for the difference of the
corresponding random variables.
If the density is also log scaled,
*std* is the standard deviation for the difference of the
log of the corresponding random variables.

eta
***
This column has type ``real`` and only affects the prior
when the *density* is
Log-Gaussian, Log-Laplace or Log-Students.
In these cases, it is the offset in the corresponding log transformation.
The value of *eta* can still affect the scaling of the
fixed effects (see below).

null
====
In the cases that are not log densities,
this field can be ``null`` .

Scaling Fixed Effects
=====================
If *eta* is not null, and it is a
:ref:`value prior<smooth_grid_table@value_prior_id>` for a
:ref:`fixed effect<model_variables@Fixed Effects, theta>` ,
the model variable is offset log scaled during the optimization.
To be specific, if :math:`\theta_j` is the fixed effect and :math:`\eta_j`
is the corresponding offset in the log transformation,
the optimizer sees the variable
:math:`\log( \theta_j + \eta_j)` in place of :math:`\theta_j`.
In this case it must hold that *lower* + *eta*  > 0 .

nu
**
This column has type ``real`` and is only used in the
cases where *density* is ``students``
or ``log_students`` .
In these cases, it is the
degrees of freedom in the corresponding distribution.

null
====
In the cases that are not Student densities,
this field can be ``null`` .
{xrst_toc_hidden
   example/table/prior_table.py
}
Example
*******
The file :ref:`prior_table.py-name`
contains an example ``prior`` table.

{xrst_end prior_table}