--------------------------------------------
lines 189-467 of file: xrst/all_node_db.xrst
--------------------------------------------

{xrst_begin option_all_table}
{xrst_spell
  bnd
  cpus
  mul
  std
  dage
  dtime
}

All Node Option Table
#####################
This table specifies certain at_cascade options

Table Format
************

option_all_id
=============
is the :ref:`all_node_db@Primary Key` for this table.

option_name
===========
This column of the option table has type ``text``.
It specifies a name that is attached to each option value.

option_value
============
This column of the option table has type ``text``.
It specifies a value that is attached to each option name.

absolute_covariates
*******************
This is a space separated list of the names for the
covariates that always have reference value zero.
If this option does not appear, there are no absolute covariates.
This option is only used when
:ref:`create_all_node_db@cov_reference_table` is None in a
call to create_all_node_db.
In any event, it is overridden by the final values in
:ref:`cov_reference_table-name` .

balance_fit
***********
The subsample of the data with size
:ref:`option_all_table@max_fit` always attempts to balance child nodes; i.e,
get an equal number of data values for each child of the node
currently being fit.
If this option appears,
:ref:`option_all_table@max_fit` must appear.
This option specifies additional balancing that dismod_at should do
for the randomly selected data subsample.
It is a space separated list with the following values
in the following order:

1. *cov_name* is the name of the covariate that we are balancing.
2. *value_1*  is the lower covariate value that we are balancing.
3. *value_2*  is the upper covariate values that we are balancing.

If this option appears, the :ref:`option_all_table@max_fit` option
must also appear.

freeze_type
***********
This options specifies the type of freeze corresponding to the rows of the
:ref:`mulcov_freeze_table-name` .
It is either ``mean`` or ``posterior`` and its default is ``mean`` .
Each row of the mulcov_freeze table specifies a freeze job
and a freeze covariate multiplier.

mean
====
If the freeze_type is ``mean`` ,
the mean (optimal value) for the freeze covariate multiplier
determined by the freeze job will be the lower and upper limit
for the covariate multiplier in descendants of the freeze job;
see :ref:`create_job_table@job_table@parent_job_id` in the job table.
Note that if the lower and upper limits are equal, the corresponding
model variable is treated as if it has no uncertainty.

posterior
=========
If the freeze_type is ``posterior`` ,
the freeze covariate multiplier posterior, determined by the freeze job,
will be its prior distribution for all the descendants of the freeze job.
This enables one to account for the uncertainty of covariate multiplier values.

max_abs_effect
**************
If this option appears, it specifies an extra bound on the
absolute value of the covariate multipliers,
except for measurement noise multipliers.
To be specific, the bound on the covariate multiplier is as large as possible
under the condition

    *max_abs_effect* <= | *mul_bnd* * ( *cov_value* - *cov_ref* ) |

where *mul_bnd* is the non-negative covariate multiplier bound,
*cov_value* is a data table value of the covariate,
and *cov_ref* is the reference value for the covariate.
It is an extra bound because it is in addition to the priors for a
covariate multiplier.

max_fit
*******
This is a text representation of a non-negative integer specifying
the maximum number of values to fit for each integrand.
If more than this number of values are available,
at a :ref:`glossary@fit_node` and for one integrand,
a randomly selected set of the values
are held out so that only this number are included in the fit.
If this option does not appear, all of the data for each integrand is included
(unless held out in the root_node data table or option table).

mulcov_freeze
=============
If the split_reference_id and the node_id for a fit appears in the
:ref:`mulcov_freeze_table-name`, the maximum number of values to fit is doubled.
This results in a better representation of the covariate multipliers
before freezing them for the jobs that will use the value determined
by this fit.

max_fit_parent
**************
If this option appears,
:ref:`option_all_table@max_fit` must appear.
This option specifies the maximum number of parent node data
values for each integrand and *max_fit* only applies to the child node.
If this option does not appear,
*max_fit* applies to all the data that is include for a fit.
Note that data corresponding to the parent node
will not be used when fitting any of its descendants.

max_number_cpu
**************
This is the maximum number of cpus (processors) that
:ref:`cascade_root_node-name` or :ref:`continue_cascade-name` can use.
If this is one (more than one) the jobs in the
:ref:`create_job_table@job_table`
will be run in sequentially (in parallel).
If running sequentially, the command output is printed to the screen.
Otherwise, it is printed to a file called $code trace.out$ in the
output directory corresponding to the job being run.
If this option does not appear, the value one is used.

no_ode_ignore
*************
The is a space separated list of rate and integrand names
that should be ignored when during a :ref:`no_ode_fit-name` .
The priors for the following variables will not be changed by no_ode_fit:

#. The rate names in *no_ode_ignore* .
#. The covariate multiplies that affect the rates in *no_ode_ignore*.
#. The covariate multiplies that affect measurement values for
   the integrands in *no_ode_ignore* .

number_sample
*************
This is the number of independent samples of the posterior distribution
for the fitted variables to generate (for each fit).
These samples are used by the dismod_at predict command to get
predictions for the children of the node being fit.
When splitting, the samples are used to predict for the
same node at the new split covariate values.
If this option does not appear, the value 20 is used.

perturb_optimization_scale
**************************
This is the standard deviation of the log of a random multiplier.
The multiplier is used to randomly shift the
optimization scaling point from the prior mean.
The scaling point is then projected back to the feasible region.
This avoids bad scaling when the prior mean
is very close to the solution.
If this option does not appear, or if it is zero,
the scaling point is equal to the prior mean for all variables.

perturb_optimization_start
**************************
This is similar to perturb_optimization_scale except that the
starting point (instead of the scaling point) is shifted.

sample_method
*************
This is the dismod_at sampling method used to create posterior samples
of the model variables for each fit.
It must be one of the following:
``asymptotic`` , ``censor_asymptotic`` or ``simulate`` .
These samples are used to create prior for the fit's
:ref:`glossary@child jobs` and for dismod_at predictions; e.g.,
:ref:`csv.predict-name` .
It is an error for *sample_method* to be ``simulate`` and
:ref:`option_all_table@number_sample` to be greater than 20.
If this option does not appear, the value ``asymptotic`` is used.

shared_memory_prefix
********************
This is used at the start of name for shared memory for this cascade.
No two cascades can run with the same shared_memory_prefix.
If this option does not appear, the empty string is used
for the shared_memory_prefix.

refit_split
***********
If this option appears, it specifies if there should be a fits,
at the same node that a split occurs at,
after the split by value of the fitting covariate.
The possible values for this option are true and false
and its default value is false.
If this is true, then the fits after the split will be used
to get the priors for the child node.
If it is false, the fit before the split will be used and there
with be no other fits at the same node.
If :ref:`split_reference_table-name` is empty, this option must be false.

result_dir
**********
This option must appear and
all of the at_cascade output files are placed in this directory.

root_node_name
**************
This option_name must appear and the corresponding option_value
is the name of the :ref:`glossary@root_node` in the node table of the
:ref:`glossary@root_database` .
(The node table is the same in all the dismod_at databases.)

root_database
*************
This option_name must appear and the corresponding option_value

root_split_reference_name
*************************
This is the `split_reference_table.split_reference_name`
corresponding to the root_database.
If :ref:`split_reference_table-name` is empty (is not empty)
this option must not (must) appear.
is the name of the :ref:`glossary@root_database` .

split_covariate_name
********************
is the name, in the root_database covariate table, of the splitting
covariate.
If :ref:`split_reference_table-name` is empty (is not empty)
this option must not (must) appear.

shift_prior_std_factor
**********************
This factor multiplies the parent fit posterior standard deviation
for the :ref:`create_shift_db@shift_databases@Value Priors`
in the shifted databases (except for the covariate multipliers).
If it is greater (less) than one, the child priors are larger (smaller)
than the posterior corresponding to the parent node fit.
If this option does not appear, the value one is used for the factor.

shift_prior_std_factor_mulcov
*****************************
This factor multiplies the parent fit posterior standard deviation
for the covariate multipliers in the shifted databases.
If this option does not appear,
*shift_prior_std_factor* is used for the factor.

shift_prior_dage
****************
The possible values for this option are true and false
and its default value is true.
It this is false, no dage priors are created for the child jobs;
see :ref:`create_shift_db@shift_databases@dage and dtime Priors` .

shift_prior_dtime
*****************
The possible values for this option are true and false
and its default value is true.
It this is false, no dtime priors are created for the child jobs.
If both *shift_prior_dage* and *shift_prior_dtime* are false,
only value priors are created for the child jobs.


{xrst_end option_all_table}