.. _method-multilevel_polynomial_chaos-variance_based_decomp:

"""""""""""""""""""""
variance_based_decomp
"""""""""""""""""""""


Activates global sensitivity analysis based on decomposition of
response variance into main, interaction, and total effects


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

   method-multilevel_polynomial_chaos-variance_based_decomp-interaction_order
   method-multilevel_polynomial_chaos-variance_based_decomp-drop_tolerance


**Specification**

- *Alias:* None

- *Arguments:* None

- *Default:* no variance-based decomposition


**Child Keywords:**

+-------------------------+--------------------+-----------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword        | Dakota Keyword Description                    |
|                         | Group              |                       |                                               |
+=========================+====================+=======================+===============================================+
| Optional                                     | `interaction_order`__ | Specify the maximum number of variables       |
|                                              |                       | allowed in an interaction when reporting      |
|                                              |                       | interaction metrics.                          |
+----------------------------------------------+-----------------------+-----------------------------------------------+
| Optional                                     | `drop_tolerance`__    | Suppresses output of sensitivity indices with |
|                                              |                       | values lower than this tolerance              |
+----------------------------------------------+-----------------------+-----------------------------------------------+

.. __: method-multilevel_polynomial_chaos-variance_based_decomp-interaction_order.html
__ method-multilevel_polynomial_chaos-variance_based_decomp-drop_tolerance.html



**Description**


Dakota can calculate sensitivity indices through variance-based
decomposition using the keyword ``variance_based_decomp``.  This
approach decomposes main, interaction, and total effects in order to
identify the most important variables and combinations of variables in
contributing to the variance of output quantities of interest.

*Default Behavior*

Because of processing overhead and output volume,
``variance_based_decomp`` is inactive by default, unless required for
dimension-adaptive refinement using Sobol' indices.

*Expected Outputs*

When ``variance_based_decomp`` is specified, sensitivity indices for
main effects, total effects, and any interaction effects will be
reported.  Each of these effects represents the percent contribution
to the variance in the model response, where main effects include the
aggregated set of \em univariate terms for each individual variable,
interaction effects represent the set of \em mixed terms (the complement
of the univariate set), and total effects represent the \em complete set
of terms (univariate and mixed) that contain each individual variable.
The aggregated set of main and interaction sensitivity indices will
sum to one, whereas the sum of total effects sensitivity indices will
be greater than one due to redundant counting of mixed terms.

*Usage Tips*

An important consideration is that the number of possible interaction
terms grows exponentially with dimension and expansion order.  To
mitigate this, both in terms of compute time and output volume,
possible interaction effects are suppressed whenever no contributions
are present due to the particular form of an expansion.  In addition,
the ``interaction_order`` and ``drop_tolerance`` controls can further
limit the computational and output requirements.



**Examples**



.. code-block::

    method,
            polynomial_chaos # or stoch_collocation
              sparse_grid_level = 3
              variance_based_decomp interaction_order = 2





**Theory**


In this context, we take sensitivity analysis to be global, not local
as when calculating derivatives of output variables with respect to
input variables. Our definition is similar to that of :cite:p:`Sal04` :
"The study of how uncertainty in the output of a model can be
apportioned to different sources of uncertainty in the model input."

Variance based decomposition is a way of using sets of samples to
understand how the variance of the output behaves, with respect to
each input variable. A larger value of the sensitivity index,
:math:`S_i` , means that the uncertainty in the input variable i has a
larger effect on the variance of the output. More details on the
calculations and interpretation of the sensitivity indices can be
found in :cite:p:`Weirs10`.