Sensitivity Module

The processing module provides transformers for data processing and manipulation.

class corrai.sensitivity.Sanalysis(parameters, model, simulation_options=None, x_needed=False)

Bases: ABC, SampleMethodsMixin

Abstract base class for Sensitivity Analysis workflows.

A Sanalysis combines: - A Sampler, which generates parameter samples and runs simulations. - An Analyser, which processes aggregated outputs to compute sensitivity

indices using SALib or other frameworks.

This class provides methods to: - Generate samples and run simulations (add_sample). - Aggregate simulation results (analyze). - Visualize results via bar plots, dynamic plots, or parallel coordinates.

Subclasses must implement: - _set_sampler: to choose the sampling strategy (Sobol, Morris, FAST, …). - _set_analyser: to choose the analysis backend (SALib, custom).

Parameters:

• parameters (list[Parameter]) – Parameters that define the sampling space.

• model (Model) – Model instance to be simulated.

• simulation_options (dict) – Options passed to the model simulation.

• x_needed (bool) – If True, the analyser requires access to the normalized design matrix (X) in addition to outputs (Y).

Variables:

• sampler (Sampler) – Sampling and simulation manager.

• analyser (object) – Sensitivity analysis backend (e.g., SALib analyser).

• x_needed (bool) – Whether the analyser requires explicit input matrix X.

Notes

This class is abstract and not meant to be instantiated directly. Use a concrete subclass such as SobolSanalysis, MorrisSanalysis, or FASTSanalysis.

__init__(parameters, model, simulation_options=None, x_needed=False)

property sample

property parameters

property values

property results

property model

property simulation_options

abstractmethod _set_sampler(parameters, model, simulation_options=None)

Return a method-specific sampler.

add_sample(simulate=True, n_cpu=1, **sample_kwargs)

Generate and add new parameter samples.

Parameters:

• simulate (bool) – If True, run model simulations for the new samples.

• n_cpu (int) – Number of CPUs to use for parallel simulations.

• **sample_kwargs – Additional arguments passed to the sampler’s add_sample.

Examples

>>> sa = SobolSanalysis(parameters, model)
>>> sa.add_sample(N=256)

analyze(indicator, method='mean', agg_method_kwarg=None, reference_time_series=None, freq=None, **analyse_kwargs)

Run sensitivity analysis on aggregated simulation results.

Parameters:

• indicator (str) – Column name in results to analyze.

• method (str) – Aggregation method to apply to each sample’s time series (e.g., “mean”, “sum”, “cv_rmse”).

• agg_method_kwarg (dict) – Extra kwargs passed to the aggregation function.

• reference_time_series (Series) – Required for error-based metrics (e.g., “cv_rmse”).

• freq (str) – If provided, perform analysis per time bin.

• **analyse_kwargs – Additional arguments for the analyser.

Returns:

• If freq is None: sensitivity metrics for the aggregated result.

• If freq is set: a Series indexed by time bins, each containing sensitivity metrics.

Return type:

Series

Notes

• If x_needed=True, the analyser will receive both X and Y.

• The analyser is typically an object from SALib.

salib_plot_bar(indicator, sensitivity_metric, sensitivity_method_name, method='mean', unit='', reference_time_series=None, agg_method_kwarg=None, title=None, plot_kwargs=None, **analyse_kwarg)

Bar plot of sensitivity metrics.

Parameters:

• indicator (str) – Name of the indicator.

• sensitivity_metric (str) – Metric to plot (e.g., “S1”, “ST”).

• sensitivity_method_name (str) – Method name (“Sobol”, “Morris”, …).

• method (str) – Aggregation method.

• unit (str) – Unit to display in axis labels.

• reference_time_series (Series) – Required for error-based aggregation.

• agg_method_kwarg (dict) – Extra kwargs for aggregation.

• title (str) – Custom figure title.

Returns:

A bar chart of sensitivity indices per parameter.

Return type:

go.Figure

salib_plot_dynamic_metric(indicator, sensitivity_metric, sensitivity_method_name, freq=None, method='mean', unit='', agg_method_kwarg=None, reference_time_series=None, title=None, stacked=False, plot_kwargs=None, **analyse_kwarg)

Dynamic sensitivity plot across time bins.

Useful for time-dependent analysis of parameter influence.

Returns:

Stacked or line plot of sensitivity metrics over time.

Return type:

go.Figure

salib_plot_matrix(indicator, sensitivity_method_name, method='mean', reference_time_series=None, agg_method_kwarg=None, title=None, fixed_range=True, plot_kwargs=None, **analyse_kwarg)

Plot 2nd-order interaction matrix of sensitivity indices.

Parameters:

• indicator (str) – Name of the indicator.

• sensitivity_method_name (str) – Method name (“Sobol”, “FAST”).

• method (str) – Aggregation method.

• unit (str, optional) – Unit to display.

• reference_time_series (Series) – Required for error-based aggregation.

• agg_method_kwarg (dict) – Extra kwargs for aggregation.

• title (str) – Custom figure title.

Returns:

Heatmap or matrix visualization of 2nd-order indices.

Return type:

go.Figure

class corrai.sensitivity.SobolSanalysis(parameters, model, simulation_options=None, calc_second_order=True)

Bases: Sanalysis

Sobol sensitivity analysis class.

This class extends Sanalysis and provides variance-based global sensitivity analysis following the Sobol method. Sampling of the parameter space is performed using the Saltelli scheme, which ensures efficient estimation of first-order, second-order, and total-order Sobol indices.

Parameters:

• parameters (list[Parameter]) – Parameters that define the sampling space.

• model (Model) – Model instance to be simulated.

• simulation_options (dict) – Options passed to the model simulation.

• calc_second_order (bool) – Whether to compute second-order (interaction) Sobol indices. This value is fixed at construction and used consistently for both sampling and analysis. Setting it to False reduces the required sample size from N*(2D+2) to N*(D+2).

Notes

Sobol analysis requires a single call to add_sample(). Calling it more than once would concatenate independent Saltelli matrices, which invalidates the variance decomposition. A ValueError is raised on any subsequent call.

__init__(parameters, model, simulation_options=None, calc_second_order=True)

add_sample(N, simulate=True, n_cpu=1, **sample_kwargs)

Generate and add new parameter samples.

Parameters:

• simulate (bool) – If True, run model simulations for the new samples.

• n_cpu (int) – Number of CPUs to use for parallel simulations.

• **sample_kwargs – Additional arguments passed to the sampler’s add_sample.

Examples

>>> sa = SobolSanalysis(parameters, model)
>>> sa.add_sample(N=256)

analyze(indicator, method='mean', agg_method_kwarg=None, reference_time_series=None, freq=None, **analyse_kwargs)

Run sensitivity analysis on aggregated simulation results.

Parameters:

• indicator (str) – Column name in results to analyze.

• method (str) – Aggregation method to apply to each sample’s time series (e.g., “mean”, “sum”, “cv_rmse”).

• agg_method_kwarg (dict) – Extra kwargs passed to the aggregation function.

• reference_time_series (Series) – Required for error-based metrics (e.g., “cv_rmse”).

• freq (str | Timedelta | timedelta) – If provided, perform analysis per time bin.

• **analyse_kwargs – Additional arguments for the analyser.

Returns:

• If freq is None: sensitivity metrics for the aggregated result.

• If freq is set: a Series indexed by time bins, each containing sensitivity metrics.

Return type:

Series

Notes

• If x_needed=True, the analyser will receive both X and Y.

• The analyser is typically an object from SALib.

plot_bar(indicator='res', sensitivity_metric='ST', method='mean', reference_time_series=None, unit='', agg_method_kwarg=None, title=None, plot_kwargs=None, **analyse_kwargs)

plot_dynamic_metric(indicator='res', sensitivity_metric='ST', freq=None, method='mean', reference_time_series=None, unit='', agg_method_kwarg=None, title=None, plot_kwargs=None)

plot_s2_matrix(indicator='res', method='mean', reference_time_series=None, agg_method_kwarg=None, title=None, fixed_range=True, plot_kwargs=None, **analyse_kwargs)

class corrai.sensitivity.MorrisSanalysis(parameters, model, simulation_options=None)

Bases: Sanalysis

__init__(parameters, model, simulation_options=None)

add_sample(N, simulate=True, n_cpu=1, num_levels=4, **sample_kwargs)

Generate and add new parameter samples.

Parameters:

• simulate (bool) – If True, run model simulations for the new samples.

• n_cpu (int) – Number of CPUs to use for parallel simulations.

• **sample_kwargs – Additional arguments passed to the sampler’s add_sample.

Examples

>>> sa = SobolSanalysis(parameters, model)
>>> sa.add_sample(N=256)

analyze(indicator, method='mean', agg_method_kwarg=None, reference_time_series=None, freq=None, **analyse_kwargs)

Run sensitivity analysis on aggregated simulation results.

Parameters:

• indicator (str) – Column name in results to analyze.

• method (str) – Aggregation method to apply to each sample’s time series (e.g., “mean”, “sum”, “cv_rmse”).

• agg_method_kwarg (dict) – Extra kwargs passed to the aggregation function.

• reference_time_series (Series) – Required for error-based metrics (e.g., “cv_rmse”).

• freq (str | Timedelta | timedelta) – If provided, perform analysis per time bin.

• **analyse_kwargs (object) – Additional arguments for the analyser.

Returns:

• If freq is None: sensitivity metrics for the aggregated result.

• If freq is set: a Series indexed by time bins, each containing sensitivity metrics.

Return type:

Series

Notes

• If x_needed=True, the analyser will receive both X and Y.

• The analyser is typically an object from SALib.

plot_scatter(indicator='res', method='mean', reference_time_series=None, agg_method_kwarg=None, title='Morris Sensitivity Analysis', unit='', scaler=100, autosize=True, plot_kwargs=None, **analyse_kwargs)

plot_bar(indicator='res', sensitivity_metric='euclidian_distance', method='mean', reference_time_series=None, unit='', agg_method_kwarg=None, title=None, plot_kwargs=None, **analyse_kwargs)

plot_dynamic_metric(indicator='res', sensitivity_metric='euclidian_distance', freq=None, method='mean', reference_time_series=None, unit='', agg_method_kwarg=None, title=None, plot_kwargs=None)

class corrai.sensitivity.FASTSanalysis(parameters, model, simulation_options=None)

Bases: Sanalysis

__init__(parameters, model, simulation_options=None)

add_sample(N, M=4, simulate=True, n_cpu=1, **sample_kwargs)

Generate and add new parameter samples.

Parameters:

• simulate (bool) – If True, run model simulations for the new samples.

• n_cpu (int) – Number of CPUs to use for parallel simulations.

• **sample_kwargs – Additional arguments passed to the sampler’s add_sample.

Examples

>>> sa = SobolSanalysis(parameters, model)
>>> sa.add_sample(N=256)

plot_bar(indicator='res', sensitivity_metric='ST', method='mean', reference_time_series=None, unit='', agg_method_kwarg=None, title=None, plot_kwargs=None, **analyse_kwargs)

plot_dynamic_metric(indicator='res', sensitivity_metric='ST', freq=None, method='mean', reference_time_series=None, unit='', agg_method_kwarg=None, title=None, plot_kwargs=None)

class corrai.sensitivity.RBDFASTSanalysis(parameters, model, simulation_options=None)

Bases: Sanalysis

__init__(parameters, model, simulation_options=None)

plot_bar(indicator='res', sensitivity_metric='S1', method='mean', reference_time_series=None, unit='', agg_method_kwarg=None, title=None, plot_kwargs=None, **analyse_kwargs)

plot_dynamic_metric(indicator='res', sensitivity_metric='S1', freq=None, method='mean', reference_time_series=None, unit='', agg_method_kwarg=None, title=None, plot_kwargs=None)