Blurb::
Supply scalar calibration data only

Description::

Enables text file import of experimental observations for use in
calibration, for scalar responses only, with optional scalar variance
information.  For more complex data import cases see \ref
responses-calibration_terms-calibration_data  Dakota will calibrate
model variables to best match these data.  

Key options include:
  \li format: whether the data file is in \c annotated, \c
    custom_annotated, or \c freeform format
  \li content: where \c num_experiments, \c
    num_config_variables, and \c experiment_variance_type indicate which
    columns appear in the data.

In the most general case, the content of the data file is described by
the arguments of three optional parameters.
<ul>
  <li> \c num_experiments ( \f$ N_{exp} \f$ )

    Default: \f$ N_{exp} = 1 \f$ 

    This indicates that the data represent multiple experiments,
    where each experiment might be conducted with different values of
    configuration variables.  An experiment can also be thought 
    of as a replicate, where the experiments are 
    run at the same values of the configuration variables. 
  </li>
  <li> \c num_config_variables ( \f$ N_{cfg} \f$ )

    Configuration variables specify the values of experimental
    conditions at which data were collected.  The variables in these
    columns must correspond to state variables in the calibration
    study.  The simulation model will be run at each configuration and
    compared to the appropriate experiment data.

  </li>
  <li> \c experiment_variance_type ('none' or 'scalar')

    This indicates if the data file contains variances for measurement error 
    of the experimental data.  The default is 'none'.

  </li>
</ul>

While some components may be omitted, the most complete version of a
an annotated calibration data file could include columns corresponding
to experiment ID, configuration variables, function value
observations, and variances (observation errors), shown here in
annotated format:
\verbatim
%exp_id | configuration xvars | y data observations | y data variances
1         7.8  7                21.9372  1.8687       0.25  0.04
2         8.6  2                19.0779  4.8976       0.25  0.04
3         8.4  8                38.2758  4.4559       0.25  0.04
4         4.2  1                39.7600  6.4631       0.25  0.04
\endverbatim

Each row in the file corresponds to an experiment or replicate
observation of an experiment to be compared to the model output.  This
example shows 4 experiments, governed by two configuration variables
(one real-valued and one integer-valued), two responses (QOIs), and
corresponding observation errors with standard deviation 0.5 and 0.2.

<b> Usage Tips </b>

\li The \c calibration_data_file keyword is used when \em only scalar
calibration terms are present.  If there are field calibration terms,
instead use \ref responses-calibration_terms-calibration_data.  For
mixed scalar and field calibration terms, one may use the \ref
responses-calibration_terms-calibration_data-scalar_data_file
specification, which uses the format described on this page.

\li <b>Attention:</b> In versions of Dakota prior to 6.14,
string-valued configuration variables were specified in data files
with 0-based indices into the admissible values. As of Dakota 6.14,
strings must be specified by value. For example a string-valued
configuration variable for an experimental condition might appear in
the file as \c low_pressure vs. \c high_pressure.

Topics::	

Examples::

<b>Simple Case:</b> In the simplest case, no data content descriptors
are specified:

\verbatim
responses
  calibration_terms = 2
    descriptors = 'volts' 'amps'
    calibration_data_file = 'circuit.dat'
      annotated
\endverbatim

And the data file \c circuit.dat must contain only the \f$ y^{Data}
\f$ observations which represent a single experimental observation.
In this case, the data file should have \f$ N_{terms} = 2 \f$ columns
(for volts, amps) and 1 row, where \f$ N_{terms} \f$ is the value of
\ref responses-calibration_terms.  The data file is shown here in
annotated format:

\verbatim
%exp_id | y data observations
1         21.9372  1.8687    
\endverbatim

For each function evaluation, Dakota will run the analysis driver,
which must return \f$ N_{terms} = 2 \f$ model responses. Then the
residuals are computed as: \f[ R_{i} = y^{Model}_i - y^{Data}_{i}. \f]

These residuals can be weighted using \ref
responses-calibration_terms-weights.

<b>Multiple experiments:</b> One might specify \c num_experiments \f$
N_E \f$ indicating that there are multiple experiments.  When multiple
experiments are present, %Dakota will expand the number of residuals
for the repeat measurement data and difference with the data
accordingly. For example, if the user has \f$ N_E = 4\f$ experiments
in the example above with 2 calibration terms, the input file would
contain

\verbatim
responses
  calibration_terms = 2
    descriptors = 'volts' 'amps'
    calibration_data_file = 'circuit.dat'
      annotated
      num_experiments = 4
\endverbatim

And the \c calibration_data_file would need to contain 2 rows (one for
each experiment), and each row should contain 2 experimental data
values that will be differenced with respect to the appropriate model
response:

\verbatim
%exp_id  | y data observations 
1          21.9372  1.8687     
2          19.0779  4.8976     
3          38.2758  4.4559     
4          39.7600  6.4631     
\endverbatim

To summarize, %Dakota will calculate the sum of the squared
residuals as: \f[f = \sum_{i=1}^{N_E}R_{i}^2\f] where the residuals
now are calculated as: \f[R_{i} = y^{Model}_i(\theta) -
y^{Data}_{i}. \f]

<b> With experimental variances:</b> If information is known about the
measurement error and the uncertainty in the measurement, that can be
specified by sending the measurement error variance to Dakota.  In
this case, the keyword \c experiment_variance_type is added, followed by a 
string of variance types of length one or of length \f$N_{terms} \f$ , where
\f$ N_{terms} \f$ is the value of \ref responses-calibration_terms.
The \c experiment_variance_type for each response can be 'none' or 'scalar'.
NOTE: you must specify the same \c experiment_variance_type for all scalar 
terms. That is, they will all be 'none' or all be 'scalar.'

\verbatim
responses
  calibration_terms = 2
    descriptors = 'volts' 'amps'
    calibration_data_file = 'circuit.dat'
      annotated
      experiment_variance_type 'scalar'
\endverbatim

For each response that has a 'scalar' variance type, each row of the
datafile will now have \f$ N_{terms} = 2\f$ of \f$ y \f$ data values
(volts, amps) followed by \f$ N_{terms} =2 \f$ columns that specify
the measurement error (in units of variance, not standard deviation)
for volts, amps.  An example with two experiments in annotated format:

\verbatim
%exp_id | y data observations | y data variances
1         21.9372  1.8687       0.25  0.04
\endverbatim

Dakota will run the analysis driver, which must return \f$ N_{terms}
\f$ responses. Then the residuals are computed as: 

\f[ R_{i} = \frac{y^{Model}_i - y^{Data}_{i}}{\sqrt{{var}_i}} \f] 

for \f$ i = 1 \dots N_{terms} \f$.  

<b>Putting all the options together:</b> Specifying all these options
together might look like

\verbatim
responses
  calibration_terms = 2
    descriptors = 'volts' 'amps'
    calibration_data_file = 'circuit.dat'
      annotated
      num_experiments = 4
      experiment_variance_type 'scalar'
\endverbatim

Dakota will expect a data file

\verbatim
%exp_id | configuration xvars | y data observations | y data variances
1         7.8  7                21.9372  1.8687       0.25  0.04
2         8.6  2                19.0779  4.8976       0.25  0.04
3         8.4  8                38.2758  4.4559       0.25  0.04
4         4.2  1                39.7600  6.4631       0.25  0.04
\endverbatim

To compute residuals for each experiment, e.g., exp_id = 4, Dakota will

<ol>
  <li>Evaluate the computational model at the specified configuration 
      (state variables = [4.2, 1]).</li>

  <li>Difference the resulting 2 function values with the data
      [39.7600 volts, 6.4631 amps]</li>

  <li>Weight by the standard deviation = sqrt([0.25  0.04])</li>
</ol>

Theory::
Faq::
See_Also:: responses-calibration_terms-calibration_data	
