autoemulate.core.sensitivity_analysis

autoemulate.core.sensitivity_analysis#

class SensitivityAnalysis(emulator, x=None, problem=None)[source]#

Bases: ConversionMixin

Global sensitivity analysis.

run(method='sobol', n_samples=1024, conf_level=0.95, include_prediction_variance=False, n_bootstrap=100)[source]#

Perform global sensitivity analysis on a fitted emulator.

Parameters:

  • method (Literal["sobol", "morris"]) – The sensitivity analysis method to perform. Case-insensitive.

  • n_samples (int) – Number of samples to generate for the analysis. Higher values give more accurate results but increase computation time. Defaults to 1024.

  • conf_level (float) – Confidence level (between 0 and 1) for calculating confidence intervals of the Sobol sensitivity indices. Defaults to 0.95 (95% confidence).

  • include_prediction_variance (bool) – Whether to incorporate emulator prediction variance into sensitivity index uncertainty estimates using bootstrap sampling. Applicable for both “sobol” and “morris” methods when emulator supports UQ. Defaults to False.

  • n_bootstrap (int) – Number of bootstrap samples to use when include_prediction_variance=True. Defaults to 100.

Returns:

DataFrame with columns:

  • ’parameter’: Input parameter name

  • ’output’: Output variable name

If using Sobol, the columns include:

  • ’index’: S1, S2 or ST (first, second, and total order sensitivity)

  • ’confidence’: confidence intervals for each index

If using Morris, the columns include:

  • ’mu’: mean of the distribution of elementary effects

  • ’mu_star’: mean of the distribution of absolute value

  • ’sigma’: standard deviation of the distribution, used as indication of

    interactions between parameters

  • ’mu_star_conf: boostrapped confidence interval

Return type:

pandas.DataFrame

Notes

The Sobol method requires N * (2D + 2) model evaluations, where D is the number of input parameters. For example, with N=1024 and 5 parameters, this requires 12,288 evaluations. The Morris method requires far fewer computations.

When include_prediction_variance=True, the emulator’s prediction uncertainty is incorporated by sampling from the predicted distribution, then computing sensitivity indices for each bootstrap sample.

Specifically, the approach is: 1. Compute baseline indices on the predictive mean outputs. 2. Draw n_bootstrap replicated output sets per design point. 3. Recompute indices for each replicate. 4. Estimate predictive SD of each index and combine with SALib’s sampling with root-sum-of-squares.

Key Assumptions: approximate independence of sampling and predictive uncertainties and near-normal index estimator distribution. See private method docstring _run_sa_with_prediction_variance for detailed discussion.

static plot_sobol(results, index='S1', ncols=None, figsize=None, fname=None)[source]#

Plot Sobol sensitivity analysis results. Optionally save to file.

Parameters:

  • results (pd.DataFrame) – The results from sobol_results_to_df.

  • index (str) – The type of sensitivity index to plot. - “S1”: first-order indices - “S2”: second-order/interaction indices - “ST”: total-order indices Defaults to “S1”.

  • ncols (int | None) – The number of columns in the plot. Defaults to 3 if there are 3 or more outputs, otherwise the number of outputs. Defaults to None.

  • figsize (tuple | None) – Figure size as (width, height) in inches. If None, set automatically. Defaults to None.

  • fname (str | None) – If provided, saves the figure to this file path. Defaults to None.

static plot_morris(results, param_groups=None, ncols=None, figsize=None, fname=None)[source]#

Plot Morris analysis results. Optionally save to file.

Parameters:

  • results (pd.DataFrame) – The results from sobol_results_to_df.

  • param_groups (dic[str, list[str]] | None) – Optional parameter groupings used to give all the same plot color of the form ({<group name> : [param1, …], }).

  • ncols (int, optional) – The number of columns in the plot. Defaults to 3 if there are 3 or more outputs, otherwise the number of outputs.

  • figsize (tuple, optional) – Figure size as (width, height) in inches.If None, set calculated.

  • fname (str | None) – If provided, saves the figure to this file path. Defaults to None.

static top_n_sobol_params(sa_results_df, top_n, sa_index='ST')[source]#

Return top_n most important parameters given Sobol sensitivity analysis.

In case of multiple outputs, averages over them to rank the parameters.

Parameters:

  • sa_results_df (pd.DataFrame) – Dataframe results by SensitivityAnalysis().run()

  • top_n (int) – Number of parameters to return.

  • sa_index (str) – Which sensitivity index to rank the parameters by. One of [“S1”, “S2”, “ST].

Returns:

List of top_n parameter names.

Return type:

list[str]

plot_sa_heatmap(results, index='ST', top_n=None, cmap='coolwarm', normalize=True, figsize=None, fname=None)[source]#

Plot a normalized Sobol sensitivity analysis heatmap.

Parameters:

  • results (pd.DataFrame) – Sensitivity index dataframe with columns [‘index’, ‘parameter’, ‘output’, ‘value’].

  • index (str) – The type of sensitivity index to plot (e.g., ‘ST’).

  • top_n (int | None) – Number of top parameters to include. If None, returns all. Defaults to None.

  • cmap (str) – Matplotlib colormap. Defaults to ‘coolwarm’.

  • normalize (bool) – Wheterto normalize values to [0, 1]. Defaults to True.

  • figsize (tuple | None) – Figure size as (width, height) in inches. Defaults to None.

  • fname (str | None) – If provided, saves the figure to this file path. Defaults to None.

Contents