--------------------------------------------------------
lines 19-113 of file: devel/cmd/data_density_command.cpp
--------------------------------------------------------

{xrst_begin data_density_command}

Data Density Command: Change the Density for an Integrand
#########################################################

Syntax
******

| ``dismod_at`` *database* ``data_density``
| ``dismod_at`` *database* ``data_density`` *integrand_name* *density_name* *eta_factor* *nu*

Purpose
*******
This command is used to change the density used for an integrand
during subsequent fits. .
If :ref:`data_table@density_id`
corresponds to :ref:`density_table@density_name@binomial`,
the corresponding :ref:`data_table@meas_std` is null and
hence the density can't be changed.

database
********
Is an
`sqlite <https://sqlite.org/index.html>`_ database containing the
``dismod_at`` :ref:`input-name` tables which are not modified.
If this is the only argument, all the data densities are set back to the
values specified by the :ref:`data_table-name` .

integrand_name
**************
This is the
:ref:`integrand<integrand_table@integrand_name>` that we setting
the density for.

density_name
************
This is the :ref:`density_table@density_name`
that we are using for the new density,
except when the original density is binomial.

eta_factor
**********
This specifies the value of
:ref:`statistic@Notation@eta` used with this density setting.
This value is not used when the density is
:ref:`density_table@Notation@Linear`
(You can use the text ``null`` in this case).
If the density is
:ref:`density_table@Notation@Log Scaled` ,
the value of *eta* used with this density is

    *eta* = *eta_factor* * ``median`` ( *meas_value*  )

Here ``median`` ( *meas_value* ) is the median of the
:ref:`data_table@meas_value` in the data table.

nu
**
This specifies the value of
:ref:`statistic@Notation@nu` used with this density setting.
This value is only used when the density is
``students`` or ``log_students`` .
(You can use text ``null`` is when it is not used.)

data_subset_table
*****************
Only rows of the :ref:`data_subset_table-name` that correspond to this integrand
are modified.

density_id
==========
The subset table :ref:`data_subset_table@density_id`
for this integrand is changed to this *density* .

eta
===
If the density is
:ref:`density_table@Notation@Log Scaled` ,
the subset table :ref:`data_subset_table@eta`
is set to the value defined above.
Otherwise, it is set to null.

nu
==
If the density is ``students`` or ``log_students`` ,
the subset table :ref:`data_subset_table@nu`
is set to the value specified above.
Otherwise, it is set to null.

Example
*******
The file :ref:`user_data_density.py-name` contains an example and test
using this command.

{xrst_end data_density_command}