-----------------------------------------------
lines 6-183 of file: example/split_covariate.py
-----------------------------------------------

{xrst_begin_parent split_covariate}
{xrst_spell
  dage
  dtime
}

Example Using split_reference Table
###################################
This example splits the analysis by sex.
To simplify the example everything is constant w.r.t. age and time.

Nodes
*****
The following is a diagram of the node tree for this example.
The :ref:`glossary@root_node` is n0,
the :ref:`glossary@fit_goal_set`
and the leaf nodes are {n3, n4, n5, n6}::

                     n0
             /-----/\-----\
          n1              n2
         /  \            /  \
      n3    n4        n5    n6

fit_goal_set
============
{xrst_literal
    # BEGIN fit_goal_set
    # END fit_goal_set
}

Rates
*****
The only non-zero dismod_at rates for this example are
:ref:`glossary@iota`.and :ref:`glossary@omega`.

Splitting Covariate
*******************
This cascade is set up to split by the sex covariate at level zero.
Both the *refit_split* true and false cases are run.
The :ref:`option_all_table-name` for this example is:
{xrst_literal
    # BEGIN option_all_table
    # END option_all_table
}
{xrst_literal
    # BEGIN refit_split
    # END refit_split
}
The :ref:`split_reference_table-name` for this example is:
{xrst_literal
    # BEGIN split_reference_table
    # END split_reference_table
}
The :ref:`node_split_table-name` for this example is
{xrst_literal
    # BEGIN node_split_table
    # END node_split_table
}
Note that we have used node_name (instead of node_id) here and let
:ref:`create_all_node_db-name` do the conversion to node_id.
The cascade computation tree is::

                     /-------------n0-------------\
             /---female---\                /----male----\
            n1             n2            n1              n2
         /  \            /  \          /  \            /  \
      n3    n4        n5    n6      n3    n4        n5    n6

The sex reference value for the root node (n0) corresponds to both sexes:
{xrst_literal
    # BEGIN root_split_reference_id
    # END root_split_reference_id
}

Covariate
*********
There are two covariates for this example, sex and income.
Income is the only :ref:`glossary@Relative Covariate`:
{xrst_literal
    # BEGIN avg_income
    # END avg_income
}

alpha
=====
We use *alpha*
for the :ref:`glossary@rate_value` covariate multiplier
that multipliers income.
This multiplier affects the value of iota.
The true value for *alpha* (used which simulating the data) is
{xrst_literal
    # BEGIN alpha_true
    # END alpha_true
}

Random Effects
**************
There are no random effect for this example.

Simulated Data
**************

rate_true(rate, a, t, n, c)
===========================
For *rate* equal to iota or omega,
this is the true value for *rate*
in node *n* at age *a*, time *t*, and covariate values *c=[sex,income]*.
The covariate values are a list in the same order as the covariate table.
The values *a* and *t* are not used by this function for this example.
{xrst_literal
    # BEGIN rate_true
    # END rate_true
}

y_i
===
The only simulated integrand for this example is :ref:`glossary@Sincidence`
which is a direct measurement of iota.
This data is simulated without any noise; i.e.,
the i-th measurement is simulated as
*y_i = rate_true('iota', None, None, n, [sex, I_i])*
where *n* is the node, *sex* is the sex covariate value, and
*I_i* is the income for the i-th measurement.
The data is modeled as having noise even though there is no simulated noise.

Cases Simulated
===============
Data is simulated for the leaf nodes for female, male sexes; i.e.,
each *n_i* is in the set { n3, n4, n5, n6 } and the female, male sexes.
Since the data does not have any nose, the data residuals are a measure
of how good the fit is for the nodes in the fit_goal_set below the female
and male sexes.

Parent Rate Smoothing
*********************
This is the iota smoothing used for the fit_node.
There are no :ref:`glossary@dage` or :ref:`glossary@dtime`
priors because there is only one age and one time point in the smoothing grid.

Value Prior
===========
The following is the value prior used for the root_node
{xrst_literal
    # BEGIN parent_value_prior
    # END parent_value_prior
}
The mean and standard deviation are only used for the root_node.
The :ref:`create_shift_db-name`
routine replaces them for other nodes.

Alpha Smoothing
***************
This is the smoothing used for *alpha* which multiplies the income covariate.
There is only one age and one time point in this smoothing
so it does not have dage or dtime priors.

Value Prior
===========
The following is the value prior used for this smoothing:
{xrst_literal
    # BEGIN alpha_value_prior
    # END alpha_value_prior
}
The mean and standard deviation are only used for the root_node.
The create_shift_db
routine replaces them for other nodes.

Checking The Fit
****************
The results of the fit are checked by check_cascade_node
using the :ref:`check_cascade_node@avgint_table`
that was created by the root_node_db routine.
The node_id for each row is replaced by the node_id for the
fit being checked.
routine uses these tables to check that fit against the truth.

{xrst_end split_covariate}