-----------------------------------------------
lines 6-249 of file: example/prevalence2iota.py
-----------------------------------------------

{xrst_begin_parent prevalence2iota}
{xrst_spell
  avg
  dage
  dtime
}

Example Estimation of iota From Prevalence Data
###############################################
For this example everything is constant in time so the
functions below do not depend on 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` is {n1, n5, n6},
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`.
We use *iota(a, n, I)* to denote the value for iota
as a function of age *a*, node number *n*, and income *I*.
We use *omega(a, n)* to denote the value for omega
as a function of age *a* and node number *n*.


Covariate
*********
There are two covariates for this example is income and *one*.
The reference value for income is the average income corresponding
to the :ref:`glossary@fit_node`.
The *one* covariate is always equal to 1 and its reference is always zero.

r_n
===
We use *r_n* for the reference value of income at node *n*.
The code below sets this reference using the name avg_income:
{xrst_literal
   # BEGIN avg_income
   # END avg_income
}

alpha
=====
We use *alpha*
for the :ref:`glossary@rate_value` covariate multiplier
which multiplies 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
}

gamma
=====
We use *gamma*
for the :ref:`glossary@meas_noise` covariate multiplier
which multiplies *one*.
This multiplier adds to the nose level for prevalence in log space,
because the density for the prevalence data is log Gaussian.


Random Effects
**************
For each node, there is a random effect on iota that is constant
in age and time. Note that the leaf nodes have random effect for the node
above them as well as their own random effect.

s_n
===
We use *s_n* to denote the sum of the random effects for node *n*.
The code below sets this sum using the name sum_random:
{xrst_literal
   # BEGIN sum_random
   # END sum_random
}

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

Random Seed
===========
The random seed can be used to reproduce results.
If the original value of this setting is zero, the clock is used get
a random seed. The actual value or *random_seed* is always printed.
{xrst_literal
   # BEGIN random_seed
   # END random_seed
}

rate_true(rate, a, t, n, c)
===========================
For *rate* equal to iota and omega,
this is the true value for *rate*
in node *n* at age *a*, time *t*, and covariate values *c*.
The covariate values are a list in the
same order as the covariate table.
The values *t* and *c[1]* 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@prevalence`.
This data is simulated without any noise
but it is modeled as having noise.

n_i
===
Data is only simulated for the leaf nodes; i.e.,
each *n_i* is in the set { n3, n4, n5, n6 }.
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.

a_i
===
For each leaf node, data is generated on the following *age_grid*:
{xrst_literal
   # BEGIN age_grid
   # END age_grid
}

I_i
===
For each leaf node and each age in *age_grid*,
data is generated for the following *income_grid*:
{xrst_literal
   # BEGIN income_grid
   # END income_grid
}
Note that the check of the fit for the nodes in the fit_goal_set
expects much more accuracy when the income grid is not chosen randomly.

Omega Constraints
*****************
The :ref:`omega_constraint-name` routine is used
to set the value of omega in the parent and child nodes.

Parent Rate Smoothing
*********************

iota
====
This is the smoothing used in the fit_node model for iota.
Note that the value part of this smoothing is only used for the *root_node*.
This smoothing uses the *age_gird* and one time point.
There are no :ref:`glossary@dtime` priors because there is only one time point.

Value Prior
===========
The following is the value prior used for the root_node
{xrst_literal
   # BEGIN iota_50
   # END iota_50
}
{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.

dage Prior
==========
The following is the dage prior used for the fit_node:
{xrst_literal
   # BEGIN parent_dage_prior
   # END parent_dage_prior
}

Child Rate Smoothing
********************
This is the smoothing used for the
random effect for each child of the fit_node.
There are no :ref:`glossary@dage` or dtime
priors because there is only one age and one time point in this smoothing.

Value Prior
===========
The following is the value prior used for the children of the fit_node:
{xrst_literal
   # BEGIN child_value_prior
   # END child_value_prior
}

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.

Gamma Smoothing
***************
This is the smoothing used for *gamma* which multiplies the *one* covariate.
There is only one age and one time point in this smoothing
so it does not have dage or dtime priors.
In addition, the value prior has upper and lower limits equal
to the constant returned by the lambda function in this smoothing:
{xrst_literal
   # BEGIN gamma_smooth
   # END gamma_smooth
}

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 prevalence2iota}