API Reference#

SimDec main namespace.

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

SimDec decomposition.

Parameters:

inputsDataFrame of shape (n_runs, n_factors): Input variables.
outputDataFrame of shape (n_runs, 1): 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.palette(states: list[int], cmaps: list[LinearSegmentedColormap] = None) → list[list[float]][source]#

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

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.

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

Generate a table of statistics for all scenarios.

Parameters:

var_nameslist of str

Variables name.

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.visualization(*, bins: DataFrame, palette: list[list[float]], n_bins: str | int = 'auto', kind: Literal['histogram', 'boxplot'] = 'histogram', ax=None) → Axes[source]#

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.

Returns:

axAxes: Matplotlib axis.