-----------------------------------------------
lines 5-107 of file: example/user/hold_out_2.py
-----------------------------------------------

# {xrst_begin user_hold_out_2.py}
# {xrst_comment_ch #}
#
# hold_out Command: Balancing Sex Covariate Values
# ################################################
#
# Purpose
# *******
# This example shows how to balance
# :ref:`hold_out_command@Balancing@Covariates`
# using the hold_out command.
#
# Integrands
# **********
# For this example there is only one integrand, ``Sincidence`` .
#
# Nodes
# *****
# There are Three nodes, ``europe`` , ``germany`` and ``italy`` .
#
# random_seed
# ***********
# If this is zero, the clock is used to seed the random number generator:
# {xrst_code py}
random_seed = 0
# {xrst_code}
#
# alpha_true
# **********
# True value of the covariate multiplier used to simulate data:
# {xrst_spell_off}
# {xrst_code py}
alpha_true  = 0.3
# {xrst_code}
# {xrst_spell_on}
# This multiplies the sex covariate and affects *iota* .
#
# iota_avg
# ********
# Average value of *iota* .
# {xrst_spell_off}
# {xrst_code py}
iota_avg    = 0.01
# {xrst_code}
# {xrst_spell_on}
#
# True Iota
# *********
# True value for iota used to simulate the data:
# {xrst_spell_off}
# {xrst_code py}
import math
def iota_true(node, sex) :
    effect  = alpha_true * sex
    if node == 'germany' :
        iota    = 1.2 * iota_avg  * math.exp( effect )
    elif node == 'italy' :
        iota    = 0.8 * iota_avg * math.exp( effect )
    elif node == 'europe' :
        iota    = iota_avg * math.exp( effect )
    return iota
# {xrst_code}
# {xrst_spell_on}
#
# Parent Node
# ***********
# For this example the parent node is europe and we are only fitting
# fixed effects, so the variation between germany and italy is noise in
# the model.
#
# Data
# ****
# For each node, the data comes in pairs with both sexes represented equally.
# The problem with the data is that we are only fitting fixed effects.
# Thus the variation in the node for each data point is a confounding
# covariate when we sub-sample without balancing the sex covariate.
#
# Model
# *****
# There is only one rate *iota* and it is constant as a function
# of age and time. In addition, there is one covariate multiplier
# for income.
#
# fitting
# *******
# For this example we are only fitting the fixed effects,
# so the variation between germany and italy is a confounding covariate.
#
# hold_out
# ********
# This example uses the version of the hold_out command that includes
# :ref:`balancing covariates<hold_out_command@Balancing@Covariates>` .
# Note that balancing the sex covariate leads to much more accurate
# estimates of the covariate multiplier *alpha* .
#
# Source Code
# ***********
# {xrst_literal
#     BEGIN PYTHON
#     END PYTHON
# }
#
# {xrst_end user_hold_out_2.py}