---------------------------------------------------
lines 6-69 of file: at_cascade/com_cov_reference.py
---------------------------------------------------

{xrst_begin com_cov_reference}

Compute Covariate Reference Values
##################################
Compute covariate references by averaging values in the data table
for a specific node and split reference value.

Prototype
*********
{xrst_literal ,
   # BEGIN_DEF, # END_DEF
   # BEGIN_RETURN, # END_RETURN
}

option_all_table
****************
The :ref:`option_all_table@split_covariate_name` and
:ref:`option_all_table@absolute_covariates` rows of this table
(if they exist) are the only rows of this table that are used.

split_reference_table
*********************
is the :ref:`split_reference_table-name` as a ``list``
of ``dict`` .

node_table
**********
This is a list of dict representing the node table in the
:ref:`glossary@root_database` .

covariate_table
***************
This is the covariate table for any fit or the one in the
root node database.

shift_node_id
*************
This is the dismod_at node that the computed
covariate reference values correspond to.

split_reference_id
******************
This is the :ref:`split_reference_table@split_reference_id` that the
computed covariate reference values correspond to.

cov_reference_list
******************
1. The return value is a ``list`` with length equal to the
   length of the covariate table (in the root node database).
2. The :ref:`option_all_table@absolute_covariates` have the same
   reference value as in the :ref:`glossary@root_database` .
3. The splitting covariate has reference value corresponding to
   *split_reference_id* in the split_reference table.
4. The :ref:`glossary@Relative Covariate` reference values are equal to
   the average of the corresponding covariates in the data table.
5. Only rows of the data table that get included when *shift_node_id*
   is the parent node are included in the average.
6. Only rows of the data that are within the max difference for the splitting
   covariate for this *split_reference_id* are included in the average.
7. null values for a covariate are not included in the average.
8. If there are no values to average for a relative covariate, the reference
   in the root_database covariate table is used for that covariate.

{xrst_end com_cov_reference}