gemseo / uncertainty / sensitivity / correlation

analysis module¶

Class for the estimation of various correlation coefficients.

class gemseo.uncertainty.sensitivity.correlation.analysis.CorrelationAnalysis(disciplines, parameter_space, n_samples, algo=None, algo_options=None, formulation='MDF', **formulation_options)[source]¶

Bases: gemseo.uncertainty.sensitivity.analysis.SensitivityAnalysis

Sensitivity analysis based on indices using correlation measures.

Examples

>>> from numpy import pi
>>> from gemseo.api import create_discipline, create_parameter_space
>>> from gemseo.uncertainty.sensitivity.correlation.analysis import (
...     CorrelationAnalysis
... )
>>>
>>> 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 = CorrelationAnalysis([discipline], parameter_space, n_samples=1000)
>>> indices = analysis.compute_indices()

Parameters

disciplines (Collection[MDODiscipline]) – The discipline or disciplines to use for the analysis.
parameter_space (ParameterSpace) – A parameter space.
n_samples (int) – A number of samples. If None, the number of samples is computed by the algorithm.
output_names – The disciplines’ outputs to be considered for the analysis. If None, use all the outputs.
algo (str | None) –
The name of the DOE algorithm. If None, use the SensitivityAnalysis.DEFAULT_DRIVER.

By default it is set to None.
algo_options (Mapping[str, DOELibraryOptionType] | None) –
The options of the DOE algorithm.

By default it is set to None.
formulation (str) –
The name of the MDOFormulation to sample the disciplines.

By default it is set to MDF.
**formulation_options (Any) – The options of the MDOFormulation.

Return type

None

compute_indices(outputs=None)[source]¶

Compute the sensitivity indices.

Parameters

outputs (Sequence[str] | None) –

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.

Returns

The sensitivity indices.

With the following structure:

{
    "method_name": {
        "output_name": [
            {
                "input_name": data_array,
            }
        ]
    }
}

Return type

dict[str, IndicesType]

export_to_dataset()¶

Convert SensitivityAnalysis.indices into a Dataset.

Returns: The sensitivity indices.
Return type: Dataset

plot(output, inputs=None, title=None, save=True, show=False, file_path=None, directory_path=None, file_name=None, file_format=None)[source]¶

Plot the sensitivity indices.

Parameters

output (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 (Iterable[str] | None) –
The inputs to display. If None, display all.

By default it is set to None.
title (str | None) –
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 (str | Path | None) –
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 (str | None) –
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.
directory_path (str | Path | None) –

By default it is set to None.
file_name (str | None) –

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 (OutputsType) – 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 (Iterable[str] | None) –
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 (str | None) –
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 (str | Path | None) –
The path of the file to save the figures. If the extension is missing, use file_extension. If None, create a file path from directory_path, file_name and file_extension.

By default it is set to None.
directory_path (str | Path | None) –
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 (str | None) –
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 (str | None) –
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

BarPlot

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[SensitivityAnalysis]) – The sensitivity indices.
output (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 (Iterable[str] | None) –
The inputs to display. If None, display all.

By default it is set to None.
title (str | None) –
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 (str | Path | None) –
The path of the file to save the figures. If None, create a file path from directory_path, file_name and file_format.

By default it is set to None.
directory_path (str | Path | None) –
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 (str | None) –
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 (str | None) –
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

BarPlot | 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 (str | tuple[str, int]) – The output for which to display sensitivity indices, either a name or a tuple of the form (name, component) where (name, component) is used to sort the inputs. If name, its first component is considered.
mesh (ndarray | None) –
The mesh on which the p-length output is represented. Either a p-length array for a 1D functional output or a (p, 2) array for a 2D one. If None, assume a 1D functional output.

By default it is set to None.
inputs (Iterable[str] | None) –
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 (str | None) –
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 (str | Path | None) –
The path of the file to save the figures. If None, create a file path from directory_path, file_name and file_extension.

By default it is set to None.
directory_path (str | Path | None) –
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 (str | None) –
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 (str | None) –
A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.

By default it is set to None.
properties (Mapping[str, DatasetPlotPropertyType]) –
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

Curves | Surfaces

plot_radar(outputs, inputs=None, title=None, save=True, show=False, file_path=None, directory_path=None, file_name=None, file_format=None, min_radius=- 1.0, max_radius=1.0, **options)[source]¶

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 (OutputsType) – 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 (Iterable[str] | None) –
The inputs to display. If None, display all.

By default it is set to None.
standardize – If True, standardize the indices between 0 and 1 for each output.
title (str | None) –
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 (str | Path | None) –
The path of the file to save the figures. If the extension is missing, use file_extension. If None, create a file path from directory_path, file_name and file_extension.

By default it is set to None.
directory_path (str | Path | None) –
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 (str | None) –
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 (str | None) –
A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.

By default it is set to None.
min_radius (float) –
The minimal radial value. If None, from data.

By default it is set to -1.0.
max_radius (float) –
The maximal radial value. If None, from data.

By default it is set to 1.0.
**options (bool) –

Returns

A radar chart representing the sensitivity indices.

Return type

RadarChart

sort_parameters(output)¶

Return the parameters sorted in descending order.

Parameters: output (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 output name.
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]]]

DEFAULT_DRIVER = 'OT_MONTE_CARLO'¶

dataset: gemseo.core.dataset.Dataset¶: The dataset containing the discipline evaluations.

default_output: list[str]¶: The default outputs of interest.

property indices: dict[str, Dict[str, List[Dict[str, numpy.ndarray]]]]¶

The sensitivity indices.

With the following structure:

{
    "method_name": {
        "output_name": [
            {
                "input_name": data_array,
            }
        ]
    }
}

Type: dict

property inputs_names: list[str]¶: The names of the inputs.

property main_indices: Dict[str, List[Dict[str, numpy.ndarray]]]¶

The main sensitivity indices.

With the following structure:

{
    "output_name": [
        {
            "input_name": data_array,
        }
    ]
}

property main_method: str¶: The name of the main method.

property pcc: Dict[str, List[Dict[str, numpy.ndarray]]]¶

The Partial Correlation Coefficients.

With the following structure:

{
    "output_name": [
        {
            "input_name": data_array,
        }
    ]
}

Type: dict

property pearson: Dict[str, List[Dict[str, numpy.ndarray]]]¶

The Pearson coefficients.

With the following structure:

{
    "output_name": [
        {
            "input_name": data_array,
        }
    ]
}

Type: dict

property prcc: Dict[str, List[Dict[str, numpy.ndarray]]]¶

The Partial Rank Correlation Coefficients.

With the following structure:

{
    "output_name": [
        {
            "input_name": data_array,
        }
    ]
}

Type: dict

property spearman: Dict[str, List[Dict[str, numpy.ndarray]]]¶

The Spearman coefficients.

ith the following structure:

{
    "output_name": [
        {
            "input_name": data_array,
        }
    ]
}

Type: dict

property src: Dict[str, List[Dict[str, numpy.ndarray]]]¶

The Standard Regression Coefficients.

With the following structure:

{
    "output_name": [
        {
            "input_name": data_array,
        }
    ]
}

Type: dict

property srrc: Dict[str, List[Dict[str, numpy.ndarray]]]¶

The Standard Rank Regression Coefficients.

With the following structure:

{
    "output_name": [
        {
            "input_name": data_array,
        }
    ]
}

Type: dict

property ssrrc: Dict[str, List[Dict[str, numpy.ndarray]]]¶

The Signed Standard Rank Regression Coefficients.

With the following structure:

{
    "output_name": [
        {
            "input_name": data_array,
        }
    ]
}