---------------------------------------------------
lines 6-101 of file: python/dismod_at/plot_curve.py
---------------------------------------------------

{xrst_begin plot_curve}
{xrst_spell
  pdf
}

Plot Log-Scaled Values With Respect To Age and Time
###################################################

Syntax
******
{xrst_literal
    # BEGIN syntax
    # END syntax
}

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

plot_title
**********
This argument can be ``None`` .
It is a ``str`` title printed at the top of every plot.

plot_limit
**********
This argument can't be ``None`` .
It is a ``dict`` with the following keys:

age_min
=======
is a ``float`` containing the minimum age in the plot region.

age_max
=======
is a ``float`` containing the maximum age in the plot region.

time_min
========
is a ``float`` containing the minimum time in the plot region.

time_max
========
is a ``float`` containing the maximum time in the plot region.

plot_data
*********
This argument can't be ``None`` .
It is a ``dict`` where each element is a ``list`` .
The key for the dictionary is the name of the value *z* being plotted.
For each *z_name* is in *plot_data* ,

    *z_list* = *plot_data* [ *z_name* ]

is a ``list`` .
Each element of this list is a ``dict`` with the following keys:
``'age'`` , ``'time'`` , ``'value'`` .
In addition, it may also contain the key ``'std'`` .

age
===
For each *row* in *z_list* , *row* [ ``'age'`` ]
is the age corresponding to this value of *z* .

time
====
For each *row* in *z_list* , *row* [ ``'time'`` ]
is the time corresponding to this value of *z* .
For each age value in a *z_list* ,
the set of time value must be the same; i.e.,
the set of age an time values form a rectangular grid.

value
=====
For each *row* in *z_list* , *row* [ ``'value'`` ]
is the value of *z* .
All of these values must be non-negative and they must
not all be zero.

std
===
For each *row* in *z_list* , *row* [ ``'std'`` ]
is the standard deviation corresponding to this value of *z* .
This key is optional. It appears for one element of a *z_list* ,
it must appear for all the elements of the *z_list* .
This can change between different *z_name* values.
Furthermore, it this appears, it will be plotted and it must not be all zero
(for one *z_list* ).

Example
*******
See :ref:`user_plot_curve.py-name`

{xrst_end plot_curve}