.. _method-approximate_control_variate-export_sample_sequence-custom_annotated:

""""""""""""""""
custom_annotated
""""""""""""""""


Selects custom-annotated tabular file format



**Topics**


file_formats


.. toctree::
   :hidden:
   :maxdepth: 1

   method-approximate_control_variate-export_sample_sequence-custom_annotated-header
   method-approximate_control_variate-export_sample_sequence-custom_annotated-eval_id
   method-approximate_control_variate-export_sample_sequence-custom_annotated-interface_id


**Specification**

- *Alias:* None

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+--------------------+---------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword     | Dakota Keyword Description                  |
|                         | Group              |                    |                                             |
+=========================+====================+====================+=============================================+
| Optional                                     | `header`__         | Enable header row in custom-annotated       |
|                                              |                    | tabular file                                |
+----------------------------------------------+--------------------+---------------------------------------------+
| Optional                                     | `eval_id`__        | Enable evaluation ID column in              |
|                                              |                    | custom-annotated tabular file               |
+----------------------------------------------+--------------------+---------------------------------------------+
| Optional                                     | `interface_id`__   | Enable interface ID column in               |
|                                              |                    | custom-annotated tabular file               |
+----------------------------------------------+--------------------+---------------------------------------------+

.. __: method-approximate_control_variate-export_sample_sequence-custom_annotated-header.html
__ method-approximate_control_variate-export_sample_sequence-custom_annotated-eval_id.html
__ method-approximate_control_variate-export_sample_sequence-custom_annotated-interface_id.html



**Description**


A custom-annotated tabular file is a whitespace-separated text file
typically containing row data for variables, or variables followed by
responses, though the format is used for other tabular exports/imports
as well.  Custom-annotated allows user options for whether ``header``
row, ``eval_id`` column, and ``interface_id`` column appear in the
tabular file, thus bridging ``freeform`` and (fully) ``annotated``.

*Default Behavior*

The ``annotated`` format is the default for tabular export/import. To
control which header row and columns are in the input/output, specify
``custom_annotated``, followed by options, in the relevant
export/import context.

*Usage Tips*


- Prior to October 2011, calibration and surrogate data files were in free-form format. They now default to ``annotated`` format, though ``freeform`` remains an option.
- When importing tabular data, a warning will be generated if a specific number of data are expected, but extra is found and an error generated when there is insufficient data.
- Some TPLs like SCOLIB and JEGA manage their own file I/O and only support the ``freeform`` option.



**Examples**


Export a custom-annotated tabular file in Dakota 6.0 format, which
contained only header and eval_id (no interface_id), and data for
variables and responses.  Input file fragment:

.. code-block::

    environment
      tabular_data
        tabular_data_file = 'dakota_summary.dat'
        custom_annotated header eval_id

Resulting tabular file:

.. code-block::

    eval_id             x1             x2         obj_fn nln_ineq_con_1 nln_ineq_con_2
    1                   0.9            1.1         0.0002           0.26           0.76
    2               0.90009            1.1 0.0001996404857   0.2601620081       0.759955
    3               0.89991            1.1 0.0002003604863   0.2598380081       0.760045
    ...