.. _method-gpais-probability_levels:

""""""""""""""""""
probability_levels
""""""""""""""""""


Specify probability levels at which to estimate the corresponding response value


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

   method-gpais-probability_levels-num_probability_levels


**Specification**

- *Alias:* None

- *Arguments:* REALLIST

- *Default:* No CDF/CCDF response levels to compute


**Child Keywords:**

+-------------------------+--------------------+----------------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword             | Dakota Keyword Description                    |
|                         | Group              |                            |                                               |
+=========================+====================+============================+===============================================+
| Optional                                     | `num_probability_levels`__ | Specify which ``probability_levels``          |
|                                              |                            | correspond to which response                  |
+----------------------------------------------+----------------------------+-----------------------------------------------+

.. __: method-gpais-probability_levels-num_probability_levels.html



**Description**


Response levels are calculated for
specified CDF/CCDF probabilities by
indexing into a sorted samples array (the response levels computed are
not interpolated and will correspond to one of the sampled values).

*Expected Output*

If ``probability_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.



**Examples**


The Dakota input file below specifies a sampling method with
probability levels of interest.


.. code-block::

    method,
            sampling,
       samples = 100 seed = 1
       complementary distribution
       probability_levels =  1. .66 .33  0.
        1. .8  .5   0.
        1. .3  .2   0.
    
    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 that correspond the
probability levels specified in the input file.  Those response values
are also 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.4221494996e+11   5.1384774972e-12
       3.4221494996e+11   4.0634975300e+11   5.1454122311e-12
       4.0634975300e+11   5.4196114379e+11   2.4334239039e-12
    PDF for response_fn_2:
              Bin Lower          Bin Upper      Density Value
              ---------          ---------      -------------
       4.6431154744e+04   5.6511827775e+04   1.9839945149e-05
       5.6511827775e+04   6.1603813790e+04   5.8916108390e-05
       6.1603813790e+04   7.8702465755e+04   2.9242071306e-05
    PDF for response_fn_3:
              Bin Lower          Bin Upper      Density Value
              ---------          ---------      -------------
       2.3796737090e+05   3.6997214153e+05   5.3028386523e-06
       3.6997214153e+05   3.8100966235e+05   9.0600055634e-06
       3.8100966235e+05   4.4111498127e+05   3.3274925348e-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
         --------------  -----------------  -----------------  -----------------
       2.7604749078e+11   1.0000000000e+00
       3.4221494996e+11   6.6000000000e-01
       4.0634975300e+11   3.3000000000e-01
       5.4196114379e+11   0.0000000000e+00
    Complementary Cumulative Distribution Function (CCDF) for response_fn_2:
         Response Level  Probability Level  Reliability Index  General Rel Index
         --------------  -----------------  -----------------  -----------------
       4.6431154744e+04   1.0000000000e+00
       5.6511827775e+04   8.0000000000e-01
       6.1603813790e+04   5.0000000000e-01
       7.8702465755e+04   0.0000000000e+00
    Complementary Cumulative Distribution Function (CCDF) for response_fn_3:
         Response Level  Probability Level  Reliability Index  General Rel Index
         --------------  -----------------  -----------------  -----------------
       2.3796737090e+05   1.0000000000e+00
       3.6997214153e+05   3.0000000000e-01
       3.8100966235e+05   2.0000000000e-01
       4.4111498127e+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.

An inverse mapping involves computing the belief and plausibility
response level for either a specified probability level or a specified
generalized reliability level (two results for each level mapping in
the evidence-based epistemic case, instead of the one result for each
level mapping in the aleatory case).


