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
associated with a small variation \(dX_i\) of \(X_i\) with
The elementary effects \(df_1,\ldots,df_d\) are computed sequentially from an initial point
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 parameters in terms of mean
and standard deviation
where \(\mu_i = \frac{1}{r}\sum_{j=1}^rdf_i^{(j)}\).
This methodology relies on the MorrisAnalysis
class.
Classes:
|
Sensitivity analysis based on the Morris' indices. |
- class gemseo.uncertainty.sensitivity.morris.analysis.MorrisAnalysis(discipline, parameter_space, n_samples, algo=None, algo_options=None, n_replicates=5, step=0.05)[source]¶
Bases:
gemseo.uncertainty.sensitivity.analysis.SensitivityAnalysis
Sensitivity analysis based on the Morris’ indices.
MorrisAnalysis.indices
contains both \(\mu^*\), \(\mu\) and \(\sigma\) whileMorrisAnalysis.main_indices
represents \(\mu^*\). Lastly, theMorrisAnalysis.plot()
method represents the parameters 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.
- default_output¶
The default outputs of interest.
- Type
list(str)
- mu_¶
The mean effects with the following structure:
{ "output_name": [ { "input_name": data_array, } ] }
- Type
dict
- mu_star¶
The mean absolute effects with the following structure:
{ "output_name": [ { "input_name": data_array, } ] }
- Type
dict
- sigma¶
The variability of the effects with the following structure:
{ "output_name": [ { "input_name": data_array, } ] }
- Type
dict
- relative_sigma¶
The relative variability of the effects with the following structure:
{ "output_name": [ { "input_name": data_array, } ] }
- Type
dict
- min¶
The minimum effect with the following structure:
{ "output_name": [ { "input_name": data_array, } ] }
- Type
dict
- max¶
The maximum effect with the following structure:
{ "output_name": [ { "input_name": data_array, } ] }
- Type
dict
Examples
>>> from numpy import pi >>> from gemseo.api 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_dict=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( ... discipline, parameter_space, n_samples=None, n_replicates=5 ... ) >>> indices = analysis.compute_indices()
Initialize self. See help(type(self)) for accurate signature.
- Parameters
discipline (MDODiscipline) – A discipline.
parameter_space (DesignSpace) – A parameter space.
n_samples (Optional[int]) – A number of samples. If None, the number of samples is computed by the algorithm.
algo (Optional[str]) –
The name of the DOE algorithm. If None, use the
DEFAULT_DRIVER
.By default it is set to None.
algo_options (Optional[Mapping[str,DOELibraryOptionType]]) –
The options of the DOE algorithm.
By default it is set to None.
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.
- Return type
None
Attributes:
The sensitivity indices.
The names of the inputs.
The main sensitivity indices.
The name of the main method.
The number of OAT replicates.
The empirical bounds of the outputs.
Methods:
compute_indices
([outputs, normalize])Compute the sensitivity indices.
Convert
SensitivityAnalysis.indices
into aDataset
.plot
(output[, inputs, title, save, show, ...])Plot the Morris indices for each input variable.
plot_bar
(outputs[, inputs, standardize, ...])Plot the sensitivity indices on a bar chart.
plot_comparison
(indices, output[, inputs, ...])Plot a comparison between the current sensitivity indices and other ones.
plot_field
(output[, mesh, inputs, ...])Plot the sensitivity indices related to a 1D or 2D functional output.
plot_radar
(outputs[, inputs, standardize, ...])Plot the sensitivity indices on a radar chart.
sort_parameters
(output)Return the parameters sorted in descending order.
standardize_indices
(indices)Standardize the sensitivity indices for each output component.
- DEFAULT_DRIVER = 'lhs'¶
- compute_indices(outputs=None, normalize=False)[source]¶
Compute the sensitivity indices.
- Parameters
outputs (Optional[Sequence[str]]) –
The outputs for which to display sensitivity indices. If None, use the default outputs, that are all the discipline outputs.
By default it is set to None.
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.
With the following structure:
{ "method_name": { "output_name": [ { "input_name": data_array, } ] } }
- Return type
Dict[str, Dict[str, List[Dict[str, numpy.ndarray]]]]
- export_to_dataset()¶
Convert
SensitivityAnalysis.indices
into aDataset
.- Returns
The sensitivity indices.
- Return type
- property indices¶
The sensitivity indices.
With the following structure:
{ "method_name": { "output_name": [ { "input_name": data_array, } ] } }
- property inputs_names¶
The names of the inputs.
- property main_indices¶
The main sensitivity indices.
With the following structure:
{ "output_name": [ { "input_name": data_array, } ] }
- property main_method¶
The name of the main method.
- property n_replicates¶
The number of OAT replicates.
- property outputs_bounds¶
The empirical bounds of the outputs.
- plot(output, inputs=None, title=None, save=True, show=False, file_path=None, directory_path=None, file_name=None, file_format=None, 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 (Union[str, Tuple[str, int]]) – 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.
inputs (Optional[Iterable[str]]) –
The inputs to display. If None, display all.
By default it is set to None.
title (Optional[str]) –
The title of the plot. If None, no title.
By default it is set to None.
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 (Optional[Union[str, pathlib.Path]]) –
A file path. Either a complete file path, a directory name or a file name. If None, 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 None.
file_format (Optional[str]) –
A file format, e.g. ‘png’, ‘pdf’, ‘svg’, … Used when
file_path
does not have any extension. If None, use a default file extension.By default it is set to None.
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 (Optional[float]) –
The lower bound for \(\mu\). If None, use a default value.
By default it is set to None.
lower_sigma (Optional[float]) –
The lower bound for \(\sigma\). If None, use a default value.
By default it is set to None.
directory_path (Optional[Union[str, pathlib.Path]]) –
By default it is set to None.
file_name (Optional[str]) –
By default it is set to None.
- Return type
None
- plot_bar(outputs, inputs=None, standardize=False, title=None, save=True, show=False, file_path=None, directory_path=None, file_name=None, file_format=None, **options)¶
Plot the sensitivity indices on a bar chart.
This method may consider one or more outputs, as well as all inputs (default behavior) or a subset.
- Parameters
outputs (Union[str, Tuple[str, int], Sequence[Union[str, Tuple[str, int]]]]) – The outputs for which to display sensitivity indices, either a name, a list of names, a (name, component) tuple, a list of such tuples or a list mixing such tuples and names. When a name is specified, all its components are considered. If None, use the default outputs.
inputs (Optional[Iterable[str]]) –
The inputs to display. If None, display all.
By default it is set to None.
standardize (bool) –
If True, standardize the indices between 0 and 1 for each output.
By default it is set to False.
title (Optional[str]) –
The title of the plot. If None, no title.
By default it is set to None.
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 (Optional[Union[str, pathlib.Path]]) –
The path of the file to save the figures. If the extension is missing, use
file_extension
. If None, create a file path fromdirectory_path
,file_name
andfile_extension
.By default it is set to None.
directory_path (Optional[Union[str, pathlib.Path]]) –
The path of the directory to save the figures. If None, use the current working directory.
By default it is set to None.
file_name (Optional[str]) –
The name of the file to save the figures. If None, use a default one generated by the post-processing.
By default it is set to None.
file_format (Optional[str]) –
A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.
By default it is set to None.
**options (int) –
- Returns
A bar chart representing the sensitivity indices.
- Return type
- plot_comparison(indices, output, inputs=None, title=None, use_bar_plot=True, save=True, show=False, file_path=None, directory_path=None, file_name=None, file_format=None, **options)¶
Plot a comparison between the current sensitivity indices and other ones.
This method allows to use either a bar chart (default option) or a radar one.
- Parameters
indices (List[gemseo.uncertainty.sensitivity.analysis.SensitivityAnalysis]) – The sensitivity indices.
output (Union[str, Tuple[str, int]]) – 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.
inputs (Optional[Iterable[str]]) –
The inputs to display. If None, display all.
By default it is set to None.
title (Optional[str]) –
The title of the plot. If None, no title.
By default it is set to None.
use_bar_plot (bool) –
The type of graph. If True, use a bar plot. Otherwise, use a radar chart.
By default it is set to True.
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 (Optional[Union[str, pathlib.Path]]) –
The path of the file to save the figures. If None, create a file path from
directory_path
,file_name
andfile_format
.By default it is set to None.
directory_path (Optional[Union[str, pathlib.Path]]) –
The path of the directory to save the figures. If None, use the current working directory.
By default it is set to None.
file_name (Optional[str]) –
The name of the file to save the figures. If None, use a default one generated by the post-processing.
By default it is set to None.
file_format (Optional[str]) –
A file format, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.
By default it is set to None.
**options (bool) – The options passed to the underlying
DatasetPlot
.
- Returns
A graph comparing sensitivity indices.
- Return type
Union[gemseo.post.dataset.bars.BarPlot, gemseo.post.dataset.radar_chart.RadarChart]
- plot_field(output, mesh=None, inputs=None, standardize=False, title=None, save=True, show=False, file_path=None, directory_path=None, file_name=None, file_format=None, properties=None)¶
Plot the sensitivity indices related to a 1D or 2D functional output.
The output is considered as a 1D or 2D functional variable, according to the shape of the mesh on which it is represented.
- Parameters
output (Union[str, Tuple[str, int]]) – 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.
mesh (Optional[numpy.ndarray]) –
The mesh on which the p-length output is represented. Either a (1, p) array for a 1D functional output or a (2, p) array for a 2D one. If None, assume a 1D functional output.
By default it is set to None.
inputs (Optional[Iterable[str]]) –
The inputs to display. If None, display all inputs.
By default it is set to None.
standardize (bool) –
If True, standardize the indices between 0 and 1 for each output.
By default it is set to False.
title (Optional[str]) –
The title of the plot. If None, no title is displayed.
By default it is set to None.
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 (Optional[Union[str, pathlib.Path]]) –
The path of the file to save the figures. If None, create a file path from
directory_path
,file_name
andfile_extension
.By default it is set to None.
directory_path (Optional[Union[str, pathlib.Path]]) –
The path of the directory to save the figures. If None, use the current working directory.
By default it is set to None.
file_name (Optional[str]) –
The name of the file to save the figures. If None, use a default one generated by the post-processing.
By default it is set to None.
file_format (Optional[str]) –
A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.
By default it is set to None.
properties (Optional[Mapping[str, Union[str, int, float, Sequence[Union[str, int, float]]]]]) –
The general properties of a
DatasetPlot
.By default it is set to None.
- Returns
A bar plot representing the sensitivity indices.
- Raises
NotImplementedError – If the dimension of the mesh is greater than 2.
- Return type
Union[gemseo.post.dataset.curves.Curves, gemseo.post.dataset.surfaces.Surfaces]
- plot_radar(outputs, inputs=None, standardize=False, title=None, save=True, show=False, file_path=None, directory_path=None, file_name=None, file_format=None, min_radius=None, max_radius=None, **options)¶
Plot the sensitivity indices on a radar chart.
This method may consider one or more outputs, as well as all inputs (default behavior) or a subset.
For visualization purposes, it is also possible to change the minimum and maximum radius values.
- Parameters
outputs (Union[str, Tuple[str, int], Sequence[Union[str, Tuple[str, int]]]]) – The outputs for which to display sensitivity indices, either a name, a list of names, a (name, component) tuple, a list of such tuples or a list mixing such tuples and names. When a name is specified, all its components are considered. If None, use the default outputs.
inputs (Optional[Iterable[str]]) –
The inputs to display. If None, display all.
By default it is set to None.
standardize (bool) –
If True, standardize the indices between 0 and 1 for each output.
By default it is set to False.
title (Optional[str]) –
The title of the plot. If None, no title.
By default it is set to None.
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 (Optional[Union[str, pathlib.Path]]) –
The path of the file to save the figures. If the extension is missing, use
file_extension
. If None, create a file path fromdirectory_path
,file_name
andfile_extension
.By default it is set to None.
directory_path (Optional[Union[str, pathlib.Path]]) –
The path of the directory to save the figures. If None, use the current working directory.
By default it is set to None.
file_name (Optional[str]) –
The name of the file to save the figures. If None, use a default one generated by the post-processing.
By default it is set to None.
file_format (Optional[str]) –
A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.
By default it is set to None.
min_radius (Optional[float]) –
The minimal radial value. If None, from data.
By default it is set to None.
max_radius (Optional[float]) –
The maximal radial value. If None, from data.
By default it is set to None.
**options (bool) –
- Returns
A radar chart representing the sensitivity indices.
- Return type
- sort_parameters(output)¶
Return the parameters sorted in descending order.
- Parameters
output (Union[str, Tuple[str, int]]) – An output of the form
(name, component)
, where name is the output name and component is the output component. If a string is passed, the tuple(name, 0)
will be considered corresponding to the first component of the outputname
.- Returns
The input parameters sorted in descending order.
- Return type
List[str]
- static standardize_indices(indices)¶
Standardize the sensitivity indices for each output component.
Each index is replaced by its absolute value divided by the largest index. Thus, the standardized indices belong to the interval \([0,1]\).
- Parameters
indices (Dict[str, List[Dict[str, numpy.ndarray]]]) – The indices to be standardized.
- Returns
The standardized indices.
- Return type
Dict[str, List[Dict[str, numpy.ndarray]]]