.. _method-import_points:

"""""""""""""
import_points
"""""""""""""


Imports points from file and computes statistics for them.




**Topics**


uncertainty_quantification, sampling


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

   method-import_points-id_method
   method-import_points-output
   method-import_points-final_solutions
   method-import_points-import_points_file
   method-import_points-variance_based_decomp
   method-import_points-std_regression_coeffs
   method-import_points-tolerance_intervals
   method-import_points-final_moments
   method-import_points-response_levels
   method-import_points-probability_levels
   method-import_points-reliability_levels
   method-import_points-gen_reliability_levels
   method-import_points-distribution
   method-import_points-model_pointer


**Specification**

- *Alias:* None

- *Arguments:* None


**Child Keywords:**

+-------------------------+--------------------+----------------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword             | Dakota Keyword Description                    |
|                         | Group              |                            |                                               |
+=========================+====================+============================+===============================================+
| Optional                                     | `id_method`__              | Name the method block; helpful when there are |
|                                              |                            | multiple                                      |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Optional                                     | `output`__                 | Control how much method information is        |
|                                              |                            | written to the screen and output file         |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Optional                                     | `final_solutions`__        | Number of designs returned as the best        |
|                                              |                            | solutions                                     |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Required                                     | `import_points_file`__     | File containing list of variable and response |
|                                              |                            | values to import for analysis.                |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Optional                                     | `variance_based_decomp`__  | Computes Sobol' main effects using a binned   |
|                                              |                            | approach                                      |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Optional                                     | `std_regression_coeffs`__  | Output Standardized Regression Coefficients   |
|                                              |                            | and R^2 for samples                           |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Optional                                     | `tolerance_intervals`__    | Computes the double sided tolerance interval  |
|                                              |                            | equivalent normal distribuion.                |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Optional                                     | `final_moments`__          | Output moments of the specified type and      |
|                                              |                            | include them within the set of final          |
|                                              |                            | statistics.                                   |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Optional                                     | `response_levels`__        | Values at which to estimate desired           |
|                                              |                            | statistics for each response                  |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Optional                                     | `probability_levels`__     | Specify probability levels at which to        |
|                                              |                            | estimate the corresponding response value     |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Optional                                     | `reliability_levels`__     | Specify reliability levels at which the       |
|                                              |                            | response values will be estimated             |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Optional                                     | `gen_reliability_levels`__ | Specify generalized relability levels at      |
|                                              |                            | which to estimate the corresponding response  |
|                                              |                            | value                                         |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Optional                                     | `distribution`__           | Selection of cumulative or complementary      |
|                                              |                            | cumulative functions                          |
+----------------------------------------------+----------------------------+-----------------------------------------------+
| Optional                                     | `model_pointer`__          | Identifier for model block to be used by a    |
|                                              |                            | method                                        |
+----------------------------------------------+----------------------------+-----------------------------------------------+

.. __: method-import_points-id_method.html
__ method-import_points-output.html
__ method-import_points-final_solutions.html
__ method-import_points-import_points_file.html
__ method-import_points-variance_based_decomp.html
__ method-import_points-std_regression_coeffs.html
__ method-import_points-tolerance_intervals.html
__ method-import_points-final_moments.html
__ method-import_points-response_levels.html
__ method-import_points-probability_levels.html
__ method-import_points-reliability_levels.html
__ method-import_points-gen_reliability_levels.html
__ method-import_points-distribution.html
__ method-import_points-model_pointer.html



**Description**


This method imports input-output points from a tabular file
and computes statistics for them. Correlation coefficients 
and moments are always computed. More advanced statistics, 
e.g., for sensitivity or reliability analysis, can optionally
be computed.

*Default Behavior*

By default, the ``import_points`` method operates on aleatory and epistemic
uncertain variables.  The types of variables can be restricted or
expanded (to include design or state variables) through use of the
``active`` keyword in the :dakkw:`variables` block in the Dakota input
file. 

*Expected Outputs*

As a default, Dakota provides correlation analyses for imported points.
Correlation tables are printed with the simple, partial, and rank
correlations between inputs and outputs. These can be useful to get a
quick sense of how correlated the inputs are to each other, and how
correlated various outputs are to inputs. ``variance_based_decomp`` employs
the binned Sobol' index method :cite:p:`Li16` to compute first-order Sobol'
indices for the imported points.

Additional statistics can be computed from the imported points using the following
keywords:

- ``response_levels``
- ``reliability_levels``
- ``probability_levels``
- ``gen_reliability_levels``

``response_levels`` computes statistics at the specified response value.
The other three allow the specification of the statistic value, and will
estimate the corresponding response value.

``distribution`` is used to specify whether the statistic values are
from cumulative or complementary cumulative functions.

*Expected HDF5 Output*

If Dakota was built with HDF5 support and run with the
:dakkw:`environment-results_output-hdf5` keyword, this method
writes the following results to HDF5:

* When :dakkw:`method-sampling-variance_based_decomp` is enabled  
   * :ref:`hdf5_results-vbd`

* For aleatory UQ studies  
   * :ref:`hdf5_results-pdf`
   * :ref:`hdf5_results-level_mappings`
   * :ref:`hdf5_results-sampling_moments`
   * :ref:`hdf5_results-correlations`

* For epistemic UQ studies
   * :ref:`hdf5_results-extreme_responses`
   * :ref:`hdf5_results-correlations`

*Usage Tips*

No error checking is done on the imported points, e.g., to confirm 
whether sample values fall within specified bounds in the variables
block, or to confirm the adequacy of the sample for computing a requested
statistic. Users should perform their own quality checks on their
input-output points before employing this method.

**Active Variables:** By default ``import_points`` imports only uncertain 
variables, and treats any design or state variables as 
constants.  However, if :dakkw:`variables-active`
:dakkw:`variables-active-all` is specified, statistics such as correlation 
coefficients will be computed over all variables, including uncertain, design, 
and state. The other ``active`` options can enable statistics computation over
other subsets of variables.




**Examples**



.. code-block::
    
    environment
    
    method
      import_points
        import_points_file 'all_points.dat'
        variance_based_decomp
    
    model
      single
    
    variables
      active uncertain
      uniform_uncertain = 2
        descriptors  =   'input1'     'input2'
        lower_bounds =  -2.0     -2.0
        upper_bounds =   2.0      2.0
      continuous_state = 1
        descriptors =   'constant1'
        initial_state = 100
    
    interface
      analysis_drivers 'text_book'
        fork
    
    responses
      response_functions = 1
      no_gradients
      no_hessians


This example illustrates a basic import points Dakota input file.

- The tabular file to import is specified using ``import_points_file`` option.
- Values for all variables, including state variables, are imported.
- Statistics such as correlation coefficients and binned Sobol' indices are only computed for the active variables.


