----------------------------------------------
lines 6-124 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.

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.

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}