.. _method-import_points: """"""""""""" import_points """"""""""""" Imports points from file and computes statistics for them. **Topics** - :ref:`uncertainty_quantification ` - :ref:`sampling ` .. toctree:: :hidden: :maxdepth: 1 method-import_points-model_pointer method-import_points-response_levels method-import_points-reliability_levels method-import_points-probability_levels method-import_points-gen_reliability_levels method-import_points-distribution method-import_points-final_moments 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 **Specification** - *Alias:* None - *Arguments:* None - *JSON argument key:* None **Child Keywords:** +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Required/Optional | Description of Group | JSON Group Key | Dakota Keyword | Dakota Keyword Description | +=========================+========================+====================+================================+============================================================+ | Optional | | | `model_pointer`__ | Identifier for model block to be used by a method | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `response_levels`__ | Values at which to estimate desired statistics for each | | | | | | response | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `reliability_levels`__ | Specify reliability levels at which the response values | | | | | | will be estimated | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | Optional | | | `probability_levels`__ | Specify probability levels at which to estimate the | | | | | | corresponding response value | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | 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 | | | `final_moments`__ | Output moments of the specified type and include them | | | | | | within the set of final statistics. | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ | 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. | +-------------------------+------------------------+--------------------+--------------------------------+------------------------------------------------------------+ .. __: method-import_points-model_pointer.html __ method-import_points-response_levels.html __ method-import_points-reliability_levels.html __ method-import_points-probability_levels.html __ method-import_points-gen_reliability_levels.html __ method-import_points-distribution.html __ method-import_points-final_moments.html __ 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 **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** .. tab:: Freeform .. code-block:: dakota 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 .. tab:: JSON .. code-block:: json { "method": [ { "import_points": { "import_points_file": { "filename": "all_points.dat" }, "variance_based_decomp": {} } } ], "model": [ { "single": {} } ], "variables": [ { "active": { "uncertain": true }, "uniform_uncertain": { "descriptors": [ "input1", "input2" ], "lower_bounds": [ -2.0, -2.0 ], "upper_bounds": [ 2.0, 2.0 ], "count": 2 }, "continuous_state": { "descriptors": [ "constant1" ], "initial_state": [ 100 ], "count": 1 } } ], "interface": [ { "analysis_drivers": { "drivers": [ "text_book" ], "interface_type": { "fork": {} } } } ], "responses": [ { "response_type": { "response_functions": { "count": 1 } }, "gradient_type": { "no_gradients": true }, "hessian_type": { "no_hessians": true } } ] } 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.