Uncertainty Quantification
==========================

Uncertainty quantification, in the narrow sense used here, is **forward
propagation**: you have a sample of parameter vectors representing the
uncertainty in the inputs, and you want the induced distribution of the model's
outputs -- steady states, impulse responses, theoretical moments, forecasts,
variance and historical decompositions, and so on. (For *which* inputs drive
that output uncertainty, see the :doc:`GSA tools <mcf>`.)

Where the parameter draws come from
-----------------------------------

- **Posterior draws** -- after Bayesian estimation, the estimated object
  carries a sampler: ``params = mest.estim_.sampler(N)`` returns ``N`` draws
  from the posterior (or use ``posterior_sample(mest, N)``). See
  :doc:`../Estimation/Posterior simulation`.
- **Prior draws** -- with priors set on the model, sample parameter vectors
  from the prior with ``randsample(m, N)`` (or ``draw_parameter``); useful for
  *prior predictive* analysis.
- **A design over a calibration range** -- when you only have ranges (no
  distribution), sweep them with a quasi-Monte-Carlo low-discrepancy design
  (Sobol, Halton, ...) -- the same sampling engine the GSA tools use; the Sobol
  sequence generator is ``quasi_monte_carlo.sobol``.

Propagating uncertainty through the model
-----------------------------------------

Most analysis methods accept a ``params`` argument -- a matrix (or struct) of
draws -- and then return one result per draw instead of a single one::

	params = mest.estim_.sampler(1000);              % 1000 posterior draws

	myirfs = irf(mest, shock_names, 40, params);     % distribution of IRFs
	fkst   = forecast(mest, db, '2020Q1', params);   % predictive density
	vd     = variance_decomposition(mest, params);   % distribution of decomp.
	hd     = historical_decomposition(mest, params); % distribution of decomp.

Each output is then a sample of paths; summarise it with ``fanchart`` /
``plot_fanchart`` (and the other :doc:`plotting helpers <../Plotting tools>`)::

	out = fanchart(myirfs.(shock).(var), [30 50 68 90]);   % credible bands
	plot_fanchart(out)

(this is the same pattern used throughout the :doc:`reduced-form VAR chapter
<../ReducedFormVAR_capabilities/Main Reduced form VAR Modeling>`).

From propagation to sensitivity
-------------------------------

Once you have an input sample together with the corresponding output values,
the two GSA tools tell you which inputs matter:

- :doc:`Monte Carlo filtering <mcf>` -- partition the draws by whether the
  output satisfies a chosen condition ("behave" vs "non-behave") and look for
  parameters whose conditional distributions differ between the two groups;
- :doc:`high-dimensional model representation <hdmr>` -- fit a low-order
  surrogate of the input-to-output map and read off variance-based (Sobol-type)
  first-order and total sensitivity indices (and use the surrogate as a fast
  emulator).

.. todo::

   Add a worked example: estimate a small model, propagate the posterior
   through ``irf`` / ``forecast``, plot the resulting fan charts, and then run
   ``mcf`` / ``hdmr`` on the same sample.