---------------------------------------------------
lines 18-112 of file: devel/cmd/predict_command.cpp
---------------------------------------------------

{xrst_begin predict_command}

The Predict Command
###################

Syntax
******
| ``dismod_at`` *database* ``predict`` *source*
| ``dismod_at`` *database* ``predict`` *source* ``zero_meas_value``
| ``dismod_at`` *database* ``predict`` *source*  ``fit_var`` *scale*
| ``dismod_at`` *database* ``predict`` *source* ``fit_var`` *scale*
  ``zero_meas_value``

database
********
Is an
`sqlite <https://sqlite.org/index.html>`_ database containing the
``dismod_at`` :ref:`input-name` tables which are not modified.

source
******
This argument specifies where model variable values to use
for the predictions. The possible values are listed below:

sample
======
If *source* is ``sample`` ,
the values in the :ref:`sample_table-name` are used for the predictions.
In this case there are
:ref:`simulate_command@number_simulate` sets
of model variables that predictions are computed for.
If the samples were simulated using the
:ref:`sample_command@asymptotic` method,
they may not be within the lower and upper limits for the
corresponding variables.
The variables are censored to be within their limits before
the predictions are computed.

fit_var
=======
If *source* is ``fit_var`` ,
the values in the :ref:`fit_var_table-name` are used for the predictions.
In this case there is only one set of model variables that the
predictions are computed for and
:ref:`predict_table@sample_index` is always zero.

truth_var
=========
If *source* is ``truth_var`` ,
the values in the :ref:`truth_var_table-name` are used for the predictions.
In this case there is only one set of model variables that the
predictions are computed for and
:ref:`predict_table@sample_index` is always zero.

zero_meas_value
***************
If this argument is present, the value zero is used for the
:ref:`mulcov_table@mulcov_type@meas_value` covariate multipliers
(instead of the value in the *source* table).
This predicts what the mean of the corresponding data
would be if there were no measurement value covariate effects.

fit_var scale
*************
If ``fit_var`` *scale* follows *source* ,
*source* must be ``sample`` and the samples are scaled
before the predictions are made.
Let *i* be the :ref:`sample_table@sample_index` in the sample table.
Let *j* the :ref:`sample_table@var_id` in the sample table and the
:ref:`fit_var_table@fit_var_id` in the fit_var table.
The scaled samples are defined by

    scaled_sample(i,j) = fit_var(j)  + scale * ( sample(i,j)  - fit_var(j) )


predict_table
*************
A new :ref:`predict_table-name` is created each time this command is run.
It contains the
:ref:`average integrand<avg_integrand@Average Integrand, A_i>`
values for set of model variables
and each
:ref:`predict_table@avgint_id`
in the
:ref:`predict_table@Avgint Subset` .
{xrst_toc_hidden
    example/get_started/predict_command.py
}
Example
*******
The files :ref:`predict_command.py-name` and
:ref:`user_predict_fit.py-name` contain examples and tests
using this command.

{xrst_end predict_command}