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)[source]#

Perform global sensitivity analysis on a fitted emulator.

Parameters:

  • method (str) – The sensitivity analysis method to perform, one of [“sobol”, “morris”].

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

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

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.

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