.. _method-import_points-variance_based_decomp:

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


Computes Sobol' main effects using a binned approach


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

   method-import_points-variance_based_decomp-drop_tolerance
   method-import_points-variance_based_decomp-num_bins


**Specification**

- *Alias:* None

- *Arguments:* None

- *Default:* no variance-based decomposition


**Child Keywords:**

+-------------------------+--------------------+--------------------+-----------------------------------------------+
| Required/Optional       | Description of     | Dakota Keyword     | Dakota Keyword Description                    |
|                         | Group              |                    |                                               |
+=========================+====================+====================+===============================================+
| Optional                                     | `drop_tolerance`__ | Suppresses output of sensitivity indices with |
|                                              |                    | values lower than this tolerance              |
+----------------------------------------------+--------------------+-----------------------------------------------+
| Optional                                     | `num_bins`__       | Number of bins used to compute the            |
|                                              |                    | variance-based decomposition                  |
+----------------------------------------------+--------------------+-----------------------------------------------+

.. __: method-import_points-variance_based_decomp-drop_tolerance.html
__ method-import_points-variance_based_decomp-num_bins.html



**Description**


Uses unstructured input-output samples to estimate
main effect indices. It cannot compute total indices.

**Expected Output**
Sensitivity indices for main effects *only* will be reported.  
Main effects (roughly) represent the percent contribution of 
each individual variable to the variance in the model response. 




**Examples**



.. code-block::

    method,
      sampling
        sample_type lhs
        samples = 100
        variance_based_decomp
          vbd_sampling_method binned

.. code-block::

    method,
        import_points
            import_points_file "all_samples.dat"
            variance_based_decomp

Note that since the ``import_points`` method only supports 
the binned approach, ``vbd_sampling_method`` is not specified.




**Theory**


The binned approach to computing Sobol' main effect indices is 
introduced in :cite:p:`Li16`. As opposed to pick-and-freeze 
approaches like :cite:p:`Sal04`, it does not require a specific
sampling structure. Given a set of randomly-generated input-output 
samples, it computes the main effect index by binning samples, 
computing a sample statistic for each bin, then computing another
sample statistic over the bins. 

Two algorithms are detailed in :cite:p:`Li16`: computing a 
sample expectation for each bin, then a sample variance, or 
computing a sample variance for each bin, then an expectation.
The second algorithm is implemented in Dakota.