.. _`output:tabular`:

===================
Tabular Output Data
===================

In a number of contexts, Dakota can output information in a
whitespace-separated columnar data file, a tabular data file. The most
common usage, to capture the iteration history in a tabular file, is
enabled by including the :dakkw:`environment-tabular_data`
keyword in the specification (see :numref:`output:incont` for an example).

This output format facilitates the transfer of Dakota’s iteration history data to external
mathematical analysis and/or graphics plotting packages (e.g., MATLAB, TECplot, Excel, S-plus, Minitab).

.. note::

   The default file name for the top-level tabular output data is "**dakota_tabular.dat**",
   though you may wish to choose an alternate name. 

------------------
Rosenbrock Example
------------------

.. code-block::

    %eval_id   interface   x1     x2   response_fn_1
           1       NO_ID   -2     -2            3609
           2       NO_ID   -1.5   -2          1812.5
           3       NO_ID   -1     -2             904
           4       NO_ID   -0.5   -2           508.5


The first line contains the names of the variables and responses, as well as headers for the evaluation id and interface
columns:

.. code-block::

    %eval_id   interface   x1     x2   response_fn_1


The number of function evaluations will match the number of evaluations listed in the summary part of the output file for single
method approaches; the names of inputs and outputs will match the descriptors specified in the input file. The interface
column is useful when a Dakota input file contains more than one simulation interface. In this instance, there is only one, and
it has no id interface specified, so Dakota has supplied a default value of NO ID. This file is ideal for import into other
data analysis packages.

------------------------------
Container Optimization Example
------------------------------

Example tabular output
from the “container” optimization problem is shown in
:numref:`output:tabcont`. This :ref:`annotated tabular format <input:tabularformat>`
file contains the complete history of data requests from NPSOL (8
requests map into a total of 40 function evaluations when including the
central finite differencing). The first column is the data request
number, the second column is the interface ID (which is ``NO_ID`` if the
user does not specify a name for the interface), the third and fourth
columns are the design parameter values (labeled in the example as
“``H``” and “``D``”), the fifth column is the objective function
(labeled “``obj_fn``”), and the sixth column is the nonlinear equality
constraint (labeled “``nln_eq_con_1``”).

.. code-block::
   :name: output:tabcont
   :caption: Dakota’s tabular output file showing the iteration history of the “container” optimization problem.

   %eval_id interface             H              D         obj_fn   nln_eq_con_1 
          1     NO_ID           4.5            4.5    107.1314511     8.04440764 
          2     NO_ID   5.801246882    3.596476363    94.33737399    -4.59103645 
          3     NO_ID   5.197920019    3.923577479     97.7797214  -0.6780884711 
          4     NO_ID   4.932877133    4.044776216    98.28930566  -0.1410680284 
          5     NO_ID   4.989328733    4.026133158     98.4270019 -0.005324671422 
          6     NO_ID   4.987494493    4.027041977    98.43249058 -7.307058453e-06 
          7     NO_ID   4.987391669     4.02708372    98.43249809 -2.032538049e-08 
          8     NO_ID   4.987389423    4.027084627    98.43249812 -9.691802916e-12 

Any evaluations from Dakota’s internal finite differencing are
suppressed, to facilitate rapid plotting of the most critical data. This
suppression of lower level data is consistent with the data that is sent
:ref:`to the graphics windows <output:graphics>`. If this data suppression is
undesirable, :ref:`this section <restart:utility:tabular>`
describes an approach where every function evaluation, even the ones
from finite differencing, can be saved to a file in tabular format by
using the Dakota restart utility.

.. note::

   The second column labeled “:ref:`interface <interface>`” is new as of
   Dakota 6.1. It identifies which interface was used to map the variables
   to responses on each line of the tabular file (recall that the interface
   defines which simulation is being run though the :ref:`analysis driver <couplingtosimulations-main>`
   specification). Disambiguating the interface is important when using
   hybrid methods, multi-fidelity methods, or nested models. In more
   common, simpler analyses, users typically ignore the first two columns
   and only focus on the columns of inputs (variables) and outputs
   (responses). *To generate tabular output in Dakota 6.0 format, use the
   :ref:`custom-annotated format <input:tabularformat>`.*

.. note::

   As of Dakota 6.1, the tabular file will include columns
   for all of the variables (both active and inactive) present in a given
   interface. Previously, Dakota only wrote the “active” variables. Recall
   that some variables may be inactive if they are not operated on by a
   particular method (e.g. uncertain variables might not be active in an
   optimization, design variables may not be active in a sampling study).
   The order of the variables printed out will be in Dakota’s standard
   variable ordering, which is indicated by the input specification order,
   and summarized in the Dakota Reference Manual.