-------------------------------------------------
lines 5-159 of file: xrst/table/avgint_table.xrst
-------------------------------------------------

{xrst_begin avgint_table}
{xrst_spell
  mtexcess
  mtother
}

The avgint Table: Defines Average Integrand Cases
#################################################

See Also
********
:ref:`predict_table-name` .

Purpose
*******
Given a value for the :ref:`model_variables-name` ,
this table contains the other information necessary so that
the :ref:`predict_command-name` can compute
:ref:`average integrand<avg_integrand@Average Integrand, A_i>` values
that correspond to any possible case,
(not just the cases in the :ref:`data_table-name` ).
For an example of how to use this table, see the discussion of
parent and child rates below.

Usage
=====
This table is only used by the :ref:`predict_command-name` .
It can be changed, and the predict command can be re-run,
without needing to re-run any other commands.

Parent Rates
============
The :ref:`parent rates<avg_integrand@Rate Functions@Parent Rate, q_k>`
:math:`q_k (a, t)` can be computed by using the following settings
in this table:

#. Set *node_id* to the
   :ref:`parent node id<option_table@Parent Node@parent_node_id>` .
#. Set *integrand_id* to the integrand
   corresponding to rate *k* .
#. Set *age_lower* and *age_upper* set to :math:`a`.
#. Set *time_lower* and *time_upper* to :math:`t`.
#. The *weight_id* does not matter because we are not averaging
   over age or time.
#. Set the
   :ref:`avgint_table@Covariates` to null.

Note that the rates and integrands have the following correspondence:

( *iota* , :ref:`Sincidence<avg_integrand@Integrand, I_i(a,t)>` ),
( *rho* , :ref:`remission<avg_integrand@Integrand, I_i(a,t)>` ),
( *chi* , :ref:`mtexcess<avg_integrand@Integrand, I_i(a,t)>` ),
( *omega* , :ref:`mtother<avg_integrand@Integrand, I_i(a,t)>` ).

Child Rates
===========
The child rates can be computed as
:ref:`adjusted rates<avg_integrand@Rate Functions@Adjusted Rate, r_ik>`
:math:`r_{i,k} (a, t)` using the following modifications to the
parent rate settings above:

#. Set *node_id* to the node table
   :ref:`node_table@node_id` for this child.
#. Set each
   :ref:`covariate<avgint_table@Covariates>` to its average value
   for this child.
#. Set the :ref:`avgint_table@subgroup_id` to the
   subgroup of interest for this child.

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

integrand_id
************
This column has type ``integer`` and is the
:ref:`integrand_table@integrand_id` that identifies
the integrand for this case.

node_id
*******
This column has type ``integer`` and is the
:ref:`node_table@node_id` that identifies
the node for this case.
If the :ref:`integrand_table@integrand_name`
begins with ``mulcov_`` , *node_id* should be null.
Otherwise *node_id* should not be null.

subgroup_id
***********
This column has type ``integer`` and is the
:ref:`subgroup_table@subgroup_id` that identifies
the subgroup for this case.
The chosen subgroup affects the results through its affect on
the covariate multipliers; see :ref:`mulcov_table-name` .

weight_id
*********
This column has type ``integer`` and is the
:ref:`weight_grid_table@weight_id` that identifies
the weighting used for this case.

null
====
If *weight_id* is ``null`` ,
the constant weighting is used for this data point.

age_lower
*********
This column has type ``real`` and is the lower age limit
for this case.
It must be greater than or equal the minimum :ref:`age_table-name` value.

age_upper
*********
This column has type ``real`` and is the upper age limit
for this case.
It must be greater than or equal the corresponding *age_lower*
and less than or equal the maximum :ref:`age_table-name` value.

time_lower
**********
This column has type ``real`` and is the lower time limit
for this case.
It must be greater than or equal the minimum :ref:`time_table-name` value.

time_upper
**********
This column has type ``real`` and is the upper time limit
for this case.
It must be greater than or equal the corresponding *time_lower*
and less than or equal the maximum :ref:`time_table-name` value.

Covariates
**********
The covariate columns have type ``real`` and column names
that begin with the two characters ``x_`` .
For each valid :ref:`covariate_table@covariate_id` ,
column ``x_`` *covariate_id* contains
the value, for this measurement, of the covariate specified by
*covariate_id* .
The covariate value ``null`` is interpreted as the
:ref:`covariate_table@reference` value for
the corresponding covariate.
{xrst_toc_hidden
   example/table/avgint_table.py
}
Example
*******
The file :ref:`avgint_table.py-name`
contains an example ``avgint`` table.

{xrst_end avgint_table}