gemseo.uncertainty.sensitivity.morris_analysis module#

Class for the estimation of Morris indices.

OAT technique#

The purpose of the One-At-a-Time (OAT) methodology is to quantify the elementary effect

\[df_i = f(X_1+dX_1,\ldots,X_{i-1}+dX_{i-1},X_i+dX_i,\ldots,X_d) - f(X_1+dX_1,\ldots,X_{i-1}+dX_{i-1},X_i,\ldots,X_d)\]

associated with a small variation \(dX_i\) of \(X_i\) with

\[df_1 = f(X_1+dX_1,\ldots,X_d)-f(X_1,\ldots,X_d)\]

The elementary effects \(df_1,\ldots,df_d\) are computed sequentially from an initial point

\[X=(X_1,\ldots,X_d)\]

From these elementary effects, we can compare their absolute values \(|df_1|,\ldots,|df_d|\) and sort \(X_1,\ldots,X_d\) accordingly.

Morris technique#

Then, the purpose of the Morris' methodology is to repeat the OAT method from different initial points \(X^{(1)},\ldots,X^{(r)}\) and compare the input variables in terms of mean

\[\mu_i^* = \frac{1}{r}\sum_{j=1}^r|df_i^{(j)}|\]

and standard deviation

\[\sigma_i = \sqrt{\frac{1}{r}\sum_{j=1}^r\left(|df_i^{(j)}|-\mu_i\right)^2}\]

where \(\mu_i = \frac{1}{r}\sum_{j=1}^rdf_i^{(j)}\).

This methodology relies on the MorrisAnalysis class.

class MorrisAnalysis(samples='')[source]#

Bases: BaseSensitivityAnalysis

Sensitivity analysis based on the Morris' indices.

MorrisAnalysis.indices contains both \(\mu^*\), \(\mu\) and \(\sigma\) while MorrisAnalysis.main_indices represents \(\mu^*\). Lastly, the MorrisAnalysis.plot() method represents the input variables as a scatter plot where \(X_i\) has as coordinates \((\mu_i^*,\sigma_i)\). The bigger \(\mu_i^*\) is, the more significant \(X_i\) is. Concerning \(\sigma_i\), it highlights non-linear effects along \(X_i\) or cross-effects between \(X_i\) and other parameter(s).

The user can specify the DOE algorithm name to select the initial points, as well as the number of replicates and the relative step for the input variations.

Examples

>>> from numpy import pi
>>> from gemseo import create_discipline, create_parameter_space
>>> from gemseo.uncertainty.sensitivity.morris_analysis import MorrisAnalysis
>>>
>>> expressions = {"y": "sin(x1)+7*sin(x2)**2+0.1*x3**4*sin(x1)"}
>>> discipline = create_discipline(
...     "AnalyticDiscipline", expressions=expressions
... )
>>>
>>> parameter_space = create_parameter_space()
>>> parameter_space.add_random_variable(
...     "x1", "OTUniformDistribution", minimum=-pi, maximum=pi
... )
>>> parameter_space.add_random_variable(
...     "x2", "OTUniformDistribution", minimum=-pi, maximum=pi
... )
>>> parameter_space.add_random_variable(
...     "x3", "OTUniformDistribution", minimum=-pi, maximum=pi
... )
>>>
>>> analysis = MorrisAnalysis()
>>> analysis.compute_samples([discipline], parameter_space, n_samples=0)
>>> indices = analysis.compute_indices()
Parameters:

samples (IODataset | str | Path) --

The samples for the estimation of the sensitivity indices, either as an IODataset or as a pickle file path generated from the IODataset.to_pickle method. If empty, use compute_samples().

By default it is set to "".

class Method(value)[source]#

Bases: StrEnum

The names of the sensitivity methods.

MU_STAR = 'MU_STAR'#

The mean of the absolute finite difference.

SIGMA = 'SIGMA'#

The standard deviation of the absolute finite difference.

class SensitivityIndices(mu: 'FirstOrderIndicesType' = <factory>, mu_star: 'FirstOrderIndicesType' = <factory>, sigma: 'FirstOrderIndicesType' = <factory>, relative_sigma: 'FirstOrderIndicesType' = <factory>, min: 'FirstOrderIndicesType' = <factory>, max: 'FirstOrderIndicesType' = <factory>)[source]#

Bases: object

Parameters:
max: dict[str, list[dict[str, ndarray[Any, dtype[floating[Any]]]]]]#
min: dict[str, list[dict[str, ndarray[Any, dtype[floating[Any]]]]]]#
mu: dict[str, list[dict[str, ndarray[Any, dtype[floating[Any]]]]]]#
mu_star: dict[str, list[dict[str, ndarray[Any, dtype[floating[Any]]]]]]#
relative_sigma: dict[str, list[dict[str, ndarray[Any, dtype[floating[Any]]]]]]#
sigma: dict[str, list[dict[str, ndarray[Any, dtype[floating[Any]]]]]]#
compute_indices(output_names=(), normalize=False)[source]#

Compute the sensitivity indices.

Parameters:
  • output_names (str | Iterable[str]) --

    The name(s) of the output(s) for which to compute the sensitivity indices. If empty, use the names of the outputs set at instantiation.

    By default it is set to ().

  • normalize (bool) --

    Whether to normalize the indices with the empirical bounds of the outputs.

    By default it is set to False.

Returns:

The sensitivity indices.

Given a sensitivity method, an input variable and an output variable, the sensitivity index which is a 1D NumPy array can be accessed through indices.method_name[output_name][output_component][input_name].

Return type:

SensitivityIndices

compute_samples(disciplines, parameter_space, n_samples, output_names=(), algo='', algo_settings=mappingproxy({}), backup_settings=None, n_replicates=5, step=0.05, formulation_name='MDF', **formulation_settings)[source]#

Compute the samples for the estimation of the sensitivity indices.

Parameters:
  • disciplines (Collection[Discipline]) -- The discipline or disciplines to use for the analysis.

  • parameter_space (ParameterSpace) -- A parameter space.

  • n_samples (int) -- A number of samples. If 0, the number of samples is computed by the algorithm.

  • output_names (Iterable[str]) --

    The disciplines' outputs to be considered for the analysis. If empty, use all the outputs.

    By default it is set to ().

  • algo (str) --

    The name of the DOE algorithm. If empty, use the BaseSensitivityAnalysis.DEFAULT_DRIVER.

    By default it is set to "".

  • algo_settings (Mapping[str, DriverSettingType]) --

    The settings of the DOE algorithm.

    By default it is set to {}.

  • backup_settings (BackupSettings | None) -- The settings of the backup file to store the evaluations if any.

  • n_replicates (int) --

    The number of times the OAT method is repeated. Used only if n_samples is None. Otherwise, this number is the greater integer \(r\) such that \(r(d+1)\leq\) n_samples and \(r(d+1)\) is the number of samples actually carried out.

    By default it is set to 5.

  • step (float) --

    The finite difference step of the OAT method.

    By default it is set to 0.05.

  • formulation_name (str) --

    The name of the BaseMDOFormulation to sample the disciplines.

    By default it is set to "MDF".

  • **formulation_settings (Any) -- The settings of the BaseMDOFormulation.

Returns:

The samples for the estimation of the sensitivity indices.

Raises:

ValueError -- If at least one input dimension is not equal to 1.

Return type:

IODataset

plot(output, input_names=(), title='', save=True, show=False, file_path='', directory_path='', file_name='', file_format='', offset=1, lower_mu=None, lower_sigma=None)[source]#

Plot the Morris indices for each input variable.

For \(i\in\{1,\ldots,d\}\), plot \(\mu_i^*\) in function of \(\sigma_i\).

Parameters:
  • output (VariableType) -- The output for which to display sensitivity indices, either a name or a tuple of the form (name, component). If name, its first component is considered.

  • input_names (Iterable[str]) --

    The input variables for which to display the sensitivity indices. If empty, display all the input variables.

    By default it is set to ().

  • title (str) --

    The title of the plot, if any.

    By default it is set to "".

  • save (bool) --

    If True, save the figure.

    By default it is set to True.

  • show (bool) --

    If True, show the figure.

    By default it is set to False.

  • file_path (str | Path) --

    A file path. Either a complete file path, a directory name or a file name. If empty, use a default file name and a default directory. The file extension is inferred from filepath extension, if any.

    By default it is set to "".

  • directory_path (str | Path) --

    The path to the directory where to save the plots.

    By default it is set to "".

  • file_name (str) --

    The name of the file.

    By default it is set to "".

  • file_format (str) --

    A file format, e.g. 'png', 'pdf', 'svg', ... Used when file_path does not have any extension. If empty, use a default file extension.

    By default it is set to "".

  • offset (float) --

    The offset to display the inputs names, expressed as a percentage applied to both x-range and y-range.

    By default it is set to 1.

  • lower_mu (float | None) -- The lower bound for \(\mu\). If None, use a default value.

  • lower_sigma (float | None) -- The lower bound for \(\sigma\). If None, use a default value.

Returns:

The plot figure.

Return type:

Figure

DEFAULT_DRIVER: ClassVar[str] = 'PYDOE_LHS'#
property n_replicates: int#

The number of OAT replicates.

property outputs_bounds: dict[str, list[float]]#

The empirical bounds of the outputs.