API Reference

SimDec main namespace.

simdec.decomposition(inputs: DataFrame, output: DataFrame, *, sensitivity_indices: ndarray, dec_limit: float | None = None, auto_ordering: bool = True, states: list[int] | None = None, statistic: Literal['mean', 'median'] | None = 'mean') → DecompositionResult

SimDec decomposition.

Parameters:

inputsDataFrame of shape (n_runs, n_factors)

Input variables.

outputDataFrame of shape (n_runs, 1) or (n_runs,)

Target variable.

sensitivity_indicesndarray of shape (n_factors, 1)

Sensitivity indices, combined effect of each input.

dec_limitfloat

Explained variance ratio to filter the number input variables.

auto_orderingbool

Automatically order input columns based on the relative sensitivity_indices or use the provided order.

stateslist of int, optional

List of possible states for the considered parameter.

statistic{“mean”, “median”}, optional

Statistic to compute in each bin.

Returns:

resDecompositionResult

An object with attributes:

var_nameslist of string (n_factors, 1)

Variable names.

statisticndarray of shape (n_factors, 1)

Statistic in each bin.

binsDataFrame

Multidimensional bins.

stateslist of int

List of possible states for the considered parameter.

simdec.heterogeneity_indices(output: Series, inputs: DataFrame, split_variable: str | Series, n_subdivisions: int | None = None, plot: bool = False) → HeterogeneityResult

Heterogeneity indices.

Compute sensitivity-based heterogeneity across subdivisions of a variable.

Parameters:

outputpd.Series

Model output vector.

inputspd.DataFrame

Input/feature matrix.

split_variablestr or pd.Series

Variable to split on. If string, must be a column in ‘inputs’.

n_subdivisionsint, optional

Number of regions for continuous variables. Defaults to 4.

plotbool, default False

If True, displays a stacked bar chart of regional sensitivity profiles by calling plot_heterogeneity(). The chart shows variance contributions of each input across subdivisions of split_variable, ranked by global sensitivity indices. To capture the returned matplotlib.axes.Axes object, call plot_heterogeneity() directly on the result instead.

Returns:

resHeterogeneityResult

An object with attributes:

summaryDataFrame

A summary of calculated heterogeneity indices.

regional_profilesDataFrame

Regional sensitivity indices for each input across subdivisions.

split_namestr

The name of the variable used to split the data.

simdec.palette(states: list[int], cmaps: list[LinearSegmentedColormap] = None) → list[list[float]]

Colour palette.

The product of the states gives the number of scenarios. For each scenario, a colour is set.

Parameters:

stateslist of int

List of possible states for the considered parameter.

cmapslist of LinearSegmentedColormap

List of colormaps. Must have the same number of colormaps as the number of first level of states.

Returns

——-

palettelist of float of size (n, 4)

List of colors corresponding to scenarios. RGBA formatted.

simdec.sensitivity_indices(inputs: DataFrame | ndarray, output: DataFrame | ndarray, print_indices: bool = False) → SensitivityAnalysisResult

Sensitivity indices.

The sensitivity_indices express how much variability of the output is explained by the inputs.

Parameters:

inputsndarray or DataFrame of shape (n_runs, n_factors)

Input variables.

outputndarray or DataFrame of shape (n_runs, 1)

Target variable.

print_indicesbool, default False

If True, displays computed indices.

Returns:

resSensitivityAnalysisResult

An object with attributes:

sindarray of shape (n_factors, 1)

Sensitivity indices, combined effect of each input.

foendarray of shape (n_factors, 1)

First-order effects (also called ‘main’ or ‘individual’).

soendarray of shape (n_factors, n_factors)

Second-order effects (also called ‘interaction’).

Examples

>>> import numpy as np
>>> from scipy.stats import qmc
>>> import simdec as sd

We define first the function that we want to analyse. We use the well studied Ishigami function:

>>> def f_ishigami(x):
...     return (np.sin(x[0]) + 7 * np.sin(x[1]) ** 2
...             + 0.1 * (x[2] ** 4) * np.sin(x[0]))

Then we generate inputs using the Quasi-Monte Carlo method of Sobol’ in order to cover uniformly our space. And we compute outputs of the function.

>>> rng = np.random.default_rng()
>>> inputs = qmc.Sobol(d=3, seed=rng).random(2**18)
>>> inputs = qmc.scale(
...     sample=inputs,
...     l_bounds=[-np.pi, -np.pi, -np.pi],
...     u_bounds=[np.pi, np.pi, np.pi]
... )
>>> output = f_ishigami(inputs.T)

We can now pass our inputs and outputs to the sensitivity_indices function:

>>> res = sd.sensitivity_indices(inputs=inputs, output=output)
>>> res.si
array([0.43157591, 0.44241433, 0.11767249])

simdec.states_expansion(states: list[int], inputs: DataFrame) → list[list[str]]

Expand states list to fully represent all scenarios.

simdec.tableau(*, var_names: list[str], statistic: ndarray, states: list[int | list[str]], bins: DataFrame, palette: ndarray) → tuple[DataFrame, Styler]

Generate a table of statistics for all scenarios.

Parameters:

var_nameslist of str

Variables name.

statisticndarray of shape (n_factors, 1)

Statistic in each bin.

stateslist of int or list of str

For each variable, number of states. Can either be a scalar or a list.

states=[2, 2] or states=[['a', 'b'], ['low', 'high']]

binsDataFrame

Multidimensional bins.

palettelist of int of size (n, 4)

Ordered list of colours corresponding to each state.

Returns:

tableDataFrame

Summary table of statistics for the scenarios.

stylerStyler

Object to style the table with colours and formatting.

simdec.two_output_visualization(*, bins: DataFrame, bins2: DataFrame, palette: list[list[float]], n_bins: str | int = 'auto', output_name: str = 'Output 1', output_name2: str = 'Output 2', xlim: tuple[float, float] | None = None, ylim: tuple[float, float] | None = None, r_scatter: float = 1.0, print_legend: bool = False, decomposition: DecompositionResult | None = None) → tuple[Figure, ndarray]

Two-output visualization.

Produces a 2x2 figure * top-left : stacked histogram for output 1 (axes hidden) * bottom-left : scatter of output 1 vs output 2, coloured by scenario * bottom-right: rotated stacked histogram for output 2 (axes hidden) * top-right : empty

Parameters:

binsDataFrame

Multidimensional bins for the primary output.

bins2DataFrame

Multidimensional bins for the secondary output.

palettelist of int of size (n, 4)

List of colours corresponding to scenarios.

n_binsstr or int

Number of bins for the histograms.

output_namestr, default “Output 1”

Axis label for the primary output.

output_name2str, default “Output 2”

Axis label for the secondary output.

xlimtuple of float, optional

Limits for the primary output axis (scatter x / top histogram).

ylimtuple of float, optional

Limits for the secondary output axis (scatter y / right histogram).

r_scatterfloat, default 1.0

Fraction of data points shown in the scatter plot.

print_legend: Boolean, optional

Prints plot legend.

decomposition: DecompositionResult, optional

Required for print_legend.

Returns:

figFigure

axsndarray of shape (2, 2)

simdec.visualization(*, bins: DataFrame, palette: list[list[float]], n_bins: str | int = 'auto', kind: Literal['histogram', 'boxplot'] = 'histogram', ax=None, print_legend: bool = False, decomposition: DecompositionResult | None = None) → Axes

Histogram plot of scenarios.

Parameters:

binsDataFrame

Multidimensional bins.

palettelist of int of size (n, 4)

List of colours corresponding to scenarios.

n_binsstr or int

Number of bins or method from np.histogram_bin_edges.

kind: {“histogram”, “boxplot”}

Histogram or Box Plot.

axAxes, optional

Matplotlib axis.

print_legend: Boolean, optional

Prints plot legend.

decomposition: DecompositionResult, optional

Required for print_legend.

Returns:

axAxes

Matplotlib axis.