------------------------------------------------------
lines 6-118 of file: python/dismod_at/plot_data_fit.py
------------------------------------------------------

{xrst_begin plot_data_fit}
{xrst_spell
  pdf
}

Plot The Data Fit By Integrand
##############################

Syntax
******
#
# As Program
# ==========
# ``dismod-at`` *database* ``plot_data_fit`` *pdf_file* *plot_title max_plot*
#
# As Python Function
# ==================
{xrst_literal
    # BEGIN syntax
    # END syntax
}

log table
*********
This command uses :ref:`python_log_command-name` to enter
begin and end markers in the database log table.

database
********
This ``str`` is the file name for
an existing dismod_at database that contains the results of a
:ref:`fit_command-name` .
This argument can't be ``None`` .

pdf_file
********
This ``str``
is the location where the pdf file containing the plot will be placed.
This argument can't be ``None`` .

plot_title
**********
This ``str`` is extra text printed at the beginning of the
title for each plot.
If this argument is ``None`` , there is no extra text.

max_plot
********
This is a ``int`` specifying the maximum number of points
to plot per integrand.
If this argument is less that the number of values for an integrand,
the values are randomly sub-sampled keeping the same order.
The x-axis (data index) is the original index value before sub-sampling.
If this argument is ``None`` no sub-sampling is done.

integrand_list
**************
Each element of this ``list`` is a ``str`` containing an
:ref:`integrand_table@integrand_name`
that we are plotting the fit for.
If this argument is ``None`` all of the integrands,
except those with names that begin with ``mulcov_`` ,
are included.

n_fit_dict
**********
This is a dictionary with keys that are the integrand names
in *integrand_list* .
(If *integrand_list* is ``None`` , the keys are all the
integrand names that do not begin with ``mulcov_`` .)
The value *n_fit_dict* [ *key* ] is the number of rows
in the :ref:`data_subset_table-name` that correspond to this integrand and
are not held out in the data table (see below).
If this is less than 2, the corresponding integrand is not plotted.

Plot Legend
***********

Data Table Hold Out
===================
We use data table hold out to refer to values that have
*hold_out* equal to one in the data table.
This does not include hold outs created by the hold out command
or hold outs created by the hold option.
The data table hold out values are not included during the automatic
choice of the plotting limits.

Point Symbol
============
Values that are within the automatically chosen plotting limits
are plotted using the point character ``.`` .

Plus Symbol
===========
Values that are outside the automatically chosen plotting limits
are plotted using the point plus character ``+`` .

Green
=====
Values that correspond to data that is held out in the data table
are plotted using the color green.

Red and Black
=============
Values that correspond to data that is not held out in the data table,
and is not within (is within) the automatically chosen limits,
are plotted using the color red (black).

Example
*******
:ref:`user_plot_data_fit.py-name` .

{xrst_end plot_data_fit}