.. _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-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 | | | +=========================+====================+============================+===============================================+ | 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-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.