.. _method-importance_sampling-response_levels:
"""""""""""""""
response_levels
"""""""""""""""
Values at which to estimate desired statistics for each response
.. toctree::
:hidden:
:maxdepth: 1
method-importance_sampling-response_levels-num_response_levels
method-importance_sampling-response_levels-compute
**Specification**
- *Alias:* None
- *Arguments:* REALLIST
- *Default:* No CDF/CCDF probabilities/reliabilities to compute
**Child Keywords:**
+-------------------------+--------------------+-------------------------+-----------------------------------------------+
| Required/Optional | Description of | Dakota Keyword | Dakota Keyword Description |
| | Group | | |
+=========================+====================+=========================+===============================================+
| Optional | `num_response_levels`__ | Number of values at which to estimate desired |
| | | statistics for each response |
+----------------------------------------------+-------------------------+-----------------------------------------------+
| Optional | `compute`__ | Selection of statistics to compute at each |
| | | response level |
+----------------------------------------------+-------------------------+-----------------------------------------------+
.. __: method-importance_sampling-response_levels-num_response_levels.html
__ method-importance_sampling-response_levels-compute.html
**Description**
The ``response_levels`` specification provides the target response
values for which to compute probabilities, reliabilities, or generalized
reliabilities (forward mapping).
*Default Behavior*
If ``response_levels`` are not specified, no statistics will be computed. If they are, probabilities will be computed by default.
*Expected Outputs*
If ``response_levels`` are specified, Dakota will create two tables in
the standard output: a Probability Density function (PDF) histogram
and a Cumulative Distribution Function (CDF) table. The PDF histogram
has the lower and upper endpoints of each bin and the corresponding
density of that bin. Note that the PDF histogram has bins defined by
the ``probability_levels`` and/or ``response_levels`` in the Dakota
input file. If there are not very many levels, the histogram will be
coarse. Dakota does not do anything to optimize the bin size or
spacing. The CDF table has the list of response levels and the
corresponding probability that the response value is less than or
equal to each response level threshold.
*Usage Tips*
The ``num_response_levels`` is used to specify which arguments of the ``response_level``
correspond to which response.
**Examples**
For example, specifying a ``response_level`` of
52.3 followed with ``compute`` ``probabilities`` will result in the
calculation of the probability that the response value is less than or equal to
52.3, given the uncertain distributions on the inputs.
For an example with multiple responses, the following specification
.. code-block::
response_levels = 1. 2. .1 .2 .3 .4 10. 20. 30.
num_response_levels = 2 4 3
would assign the first two response levels (1., 2.) to response
function 1, the next four response levels (.1, .2, .3, .4) to response
function 2, and the final three response levels (10., 20., 30.) to
response function 3. If the ``num_response_levels`` key were omitted
from this example, then the response levels would be evenly distributed
among the response functions (three levels each in this case).
The Dakota input file below specifies a sampling method with
response levels of interest.
.. code-block::
method,
sampling,
samples = 100 seed = 1
complementary distribution
response_levels = 3.6e+11 4.0e+11 4.4e+11
6.0e+04 6.5e+04 7.0e+04
3.5e+05 4.0e+05 4.5e+05
variables,
normal_uncertain = 2
means = 248.89, 593.33
std_deviations = 12.4, 29.7
descriptors = 'TF1n' 'TF2n'
uniform_uncertain = 2
lower_bounds = 199.3, 474.63
upper_bounds = 298.5, 712.
descriptors = 'TF1u' 'TF2u'
weibull_uncertain = 2
alphas = 12., 30.
betas = 250., 590.
descriptors = 'TF1w' 'TF2w'
histogram_bin_uncertain = 2
num_pairs = 3 4
abscissas = 5 8 10 .1 .2 .3 .4
counts = 17 21 0 12 24 12 0
descriptors = 'TF1h' 'TF2h'
histogram_point_uncertain
real = 1
num_pairs = 2
abscissas = 3 4
counts = 1 1
descriptors = 'TF3h'
interface,
system asynch evaluation_concurrency = 5
analysis_driver = 'text_book'
responses,
response_functions = 3
no_gradients
no_hessians
Given the above Dakota input file, the following excerpt from the
output shows the PDF and CCDF generated. Note that the bounds on the
bins of the PDF are the response values specified in the input file.
The probability levels corresponding to those response values are
shown in the CCDF.
.. code-block::
Probability Density Function (PDF) histograms for each response function:
PDF for response_fn_1:
Bin Lower Bin Upper Density Value
--------- --------- -------------
2.7604749078e+11 3.6000000000e+11 5.3601733194e-12
3.6000000000e+11 4.0000000000e+11 4.2500000000e-12
4.0000000000e+11 4.4000000000e+11 3.7500000000e-12
4.4000000000e+11 5.4196114379e+11 2.2557612778e-12
PDF for response_fn_2:
Bin Lower Bin Upper Density Value
--------- --------- -------------
4.6431154744e+04 6.0000000000e+04 2.8742313192e-05
6.0000000000e+04 6.5000000000e+04 6.4000000000e-05
6.5000000000e+04 7.0000000000e+04 4.0000000000e-05
7.0000000000e+04 7.8702465755e+04 1.0341896485e-05
PDF for response_fn_3:
Bin Lower Bin Upper Density Value
--------- --------- -------------
2.3796737090e+05 3.5000000000e+05 4.2844660868e-06
3.5000000000e+05 4.0000000000e+05 8.6000000000e-06
4.0000000000e+05 4.5000000000e+05 1.8000000000e-06
Level mappings for each response function:
Complementary Cumulative Distribution Function (CCDF) for response_fn_1:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- -----------------
3.6000000000e+11 5.5000000000e-01
4.0000000000e+11 3.8000000000e-01
4.4000000000e+11 2.3000000000e-01
Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- -----------------
6.0000000000e+04 6.1000000000e-01
6.5000000000e+04 2.9000000000e-01
7.0000000000e+04 9.0000000000e-02
Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
Response Level Probability Level Reliability Index General Rel Index
-------------- ----------------- ----------------- -----------------
3.5000000000e+05 5.2000000000e-01
4.0000000000e+05 9.0000000000e-02
4.5000000000e+05 0.0000000000e+00
**Theory**
Sets of response-probability pairs computed with the forward/inverse
mappings define either a cumulative distribution function (CDF) or a
complementary cumulative distribution function (CCDF) for each
response function.
In the case of evidence-based epistemic methods,
this is generalized to define either cumulative belief and
plausibility functions (CBF and CPF) or complementary cumulative
belief and plausibility functions (CCBF and CCPF) for each response
function.
A forward mapping involves computing the belief and
plausibility probability level for a specified response level.