----------------------------------------------
lines 6-131 of file: at_cascade/fit_one_job.py
----------------------------------------------

{xrst_begin fit_one_job}
{xrst_spell
  obj
  var
}

Run One Job
###########

Prototype
*********
{xrst_literal
   # BEGIN_DEF
   # END_DEF
}

Default Value
*************
The only argument that can be None is *trace_file_obj*.

job_table
*********
This is a :ref:`create_job_table@job_table` containing the jobs
necessary to fit the :ref:`glossary@fit_goal_set`.

run_job_id
**********
This is the :ref:`create_job_table@job_table@job_id`
for the job that is run.
If *run_job_id* is zero, this job has no ancestors.
This is a special case for :ref:`fit_one_job@fit_database@fit_var`

all_node_database
*****************
is a python string specifying the location of the
:ref:`all_node_db-name`
relative to the current working directory.

node_table
**********
is a ``list`` of ``dict`` containing the node table for this cascade.

fit_integrand
*************
is a ``set`` of integrand_id values that occur in the data table; see
:ref:`get_fit_integrand-name`.

fit_type
********
is a ``str`` equal to 'both' or 'fixed' and specifies the type
of fit that dismod_at will do.

first_fit
*********
If *first_fit* is True, this is assumed to be an
:ref:`glossary@input_node_database`.
Otherwise, it is assumed that this
routine has previously been called with *first_fit* equal to True.

trace_file_obj
**************
If this argument is not None, it is a ``io.TextIOBase`` object
corresponding to a file that is opened for writing the tracing output
for this job.

fit_database
************
The :ref:`glossary@fit_database` for this fit is
*fit_node_dir*\ ``/dismod.db`` where *fit_node_dir*
is the :ref:`get_database_dir@database_dir` returned by
get_database_dir for the fit node and split_reference_id corresponding
to *run_job_id*.

Upon Input
==========
On input, *fit_database* is an :ref:`glossary@input_node_database`.

fit_var
=======
Upon return, the fit_var table correspond to the posterior
mean for the model variables for the fit_node.
If :ref:`fit_one_job@run_job_id` is not zero
and there is no data corresponding to this fit,
the fit is not done because an ancestor job can be used to predict for this job.
In this case a no data abort message will appear in the
:ref:`fit_one_job@fit_database@log` table.

sample
======
Upon return,
the sample table contains the corresponding samples from the posterior
distribution for the model variables for the fit_node.

log
===
The log table is initialized as empty when ``fit_one_job`` starts.
Upon return or abort due to an exception,
the log table contains a summary of the operations preformed by dismod.
In addition,
the following entries will be added to the log table
if the corresponding event occurs:

.. csv-table::
   :header-rows:1

   message_type, message,        event
   at_cascade,   no data: abort, abort fit because all the data is held out
   at_cascade,   fit: OK,        the maximum likelihood problem was solved
   at_cascade,   sample: OK,     the posterior samples were computed
   at_cascade,   children: OK,   the child databases with priors were created

Note that the events depend on each other in the following way:

#. If children: OK is present, then sample: OK is present.
#. If sample: OK is present, then fit: OK is present.
#. If fit: OK is present, then no data: abort is **not** present.


Exception
*********
If there is no data from this fit, this routine will raise an exception
with a message that starts with: ``no data: abort`` ; i.e., the same
as the message it puts in the log.


{xrst_end fit_one_job}