gemseo / uncertainty / sensitivity / correlation

analysis module

Class for the estimation of various correlation coefficients.

Classes:

CorrelationAnalysis(discipline, …[, algo, …])

Sensitivity analysis based on indices using correlation measures.

class gemseo.uncertainty.sensitivity.correlation.analysis.CorrelationAnalysis(discipline, parameter_space, n_samples, algo=None, algo_options=None)[source]

Bases: gemseo.uncertainty.sensitivity.analysis.SensitivityAnalysis

Sensitivity analysis based on indices using correlation measures.

Attributes
  • default_output (list(str)) – The default outputs of interest.

  • dataset (Dataset) – The dataset containing the discipline evaluations.

Parameters
  • discipline (MDODiscipline) –

  • parameter_space (ParameterSpace) –

  • n_samples (int) –

  • algo (Optional[str]) –

  • algo_options (Optional[Mapping]) –

Return type

None

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_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 = CorrelationAnalysis(discipline, parameter_space, n_samples=1000)
>>> indices = analysis.compute_indices()

Initialize self. See help(type(self)) for accurate signature.

Parameters
  • discipline (MDODiscipline) – A discipline.

  • parameter_space (ParameterSpace) – A parameter space.

  • n_samples (int) – A number of samples.

  • algo (Optional[str]) – The name of the DOE algorithm. If None, use the DEFAULT_DRIVER.

  • algo_options (Optional[Mapping]) – The options of the DOE algorithm.

Return type

None

Attributes:

DEFAULT_DRIVER

indices

The sensitivity indices.

inputs_names

The name of the inputs.

main_indices

The main sensitivity indices.

main_method

The name of the main method.

pcc

The Partial Correlation Coefficients.

pearson

The Pearson coefficients.

prcc

The Partial Rank Correlation Coefficients.

spearman

The Spearman coefficients.

src

The Standard Regression Coefficients.

srrc

The Standard Rank Regression Coefficients.

ssrrc

The Signed Standard Rank Regression Coefficients.

Methods:

compute_indices([outputs])

Compute the sensitivity indices.

export_to_dataset()

Convert this SensitivityIndices instance into a Dataset.

plot(output[, inputs, title, save, show, …])

Plot the sensitivity indices.

plot_bar(outputs[, inputs, title, save, …])

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, title, …])

Plot the sensitivity indices related to a 1D or 2D functional output.

plot_radar(outputs[, inputs, title, save, …])

Plot the sensitivity indices on a radar chart.

sort_parameters(output)

Return the parameters sorted in descending order.

DEFAULT_DRIVER = 'OT_MONTE_CARLO'
compute_indices(outputs=None)[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.

Returns

The sensitivity indices.

With the following structure:

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

Return type

Dict[str, Dict[str, Dict[str, numpy.ndarray]]]

export_to_dataset()

Convert this SensitivityIndices instance into a Dataset.

Returns

The sensitivity indices.

Return type

Dataset

property indices

The sensitivity indices.

With the following structure:

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

dict

property inputs_names

The name 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 pcc

The Partial Correlation Coefficients.

With the following structure:

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

dict

property pearson

The Pearson coefficients.

With the following structure:

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

dict

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 (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.

  • title (Optional[str]) – The title of the plot. If None, no title.

  • save (bool) – If True, save the figure.

  • show (bool) – If True, show the figure.

  • 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.

  • 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.

  • directory_path (Optional[Union[str, pathlib.Path]]) –

  • file_name (Optional[str]) –

Return type

None

plot_bar(outputs, inputs=None, 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.

  • title (Optional[str]) – The title of the plot. If None, no title.

  • save (bool) – If True, save the figure.

  • show (bool) – If True, show the figure.

  • 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 from directory_path, file_name and file_extension.

  • directory_path (Optional[Union[str, pathlib.Path]]) – The path of the directory to save the figures. If None, use the current working directory.

  • file_name (Optional[str]) – The name of the file to save the figures. If None, use a default one generated by the post-processing.

  • file_format (Optional[str]) – A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.

  • options (int) –

Returns

A bar chart representing the sensitivity indices.

Return type

gemseo.post.dataset.bars.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[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.

  • title (Optional[str]) – The title of the plot. If None, no title.

  • use_bar_plot (bool) – The type of graph. If True, use a bar plot. Otherwise, use a radar chart.

  • save (bool) – If True, save the figure.

  • show (bool) – If True, show the figure.

  • 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 and file_format.

  • directory_path (Optional[Union[str, pathlib.Path]]) – The path of the directory to save the figures. If None, use the current working directory.

  • file_name (Optional[str]) – The name of the file to save the figures. If None, use a default one generated by the post-processing.

  • file_format (Optional[str]) – A file format, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.

  • **options – The options passed to the underlying DatasetPlot.

  • options (bool) –

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, 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.

  • inputs (Optional[Iterable[str]]) – The inputs to display. If None, display all inputs.

  • title (Optional[str]) – The title of the plot. If None, no title is displayed.

  • save (bool) – If True, save the figure.

  • show (bool) – If True, show the figure.

  • 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 and file_extension.

  • directory_path (Optional[Union[str, pathlib.Path]]) – The path of the directory to save the figures. If None, use the current working directory.

  • file_name (Optional[str]) – The name of the file to save the figures. If None, use a default one generated by the post-processing.

  • file_format (Optional[str]) – A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.

  • properties (Optional[Mapping]) – The general properties of a DatasetPlot.

Return type

Union[gemseo.post.dataset.curves.Curves, gemseo.post.dataset.surfaces.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 (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.

  • title (Optional[str]) – The title of the plot. If None, no title.

  • save (bool) – If True, save the figure.

  • show (bool) – If True, show the figure.

  • 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 from directory_path, file_name and file_extension.

  • directory_path (Optional[Union[str, pathlib.Path]]) – The path of the directory to save the figures. If None, use the current working directory.

  • file_name (Optional[str]) – The name of the file to save the figures. If None, use a default one generated by the post-processing.

  • file_format (Optional[str]) – A file extension, e.g. ‘png’, ‘pdf’, ‘svg’, … If None, use a default file extension.

  • min_radius (float) – The minimal radial value. If None, from data.

  • max_radius (float) – The maximal radial value. If None, from data.

  • options (bool) –

Returns

A radar chart representing the sensitivity indices.

Return type

gemseo.post.dataset.radar_chart.RadarChart

property prcc

The Partial Rank Correlation Coefficients.

With the following structure:

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

dict

sort_parameters(output)

Return the parameters sorted in descending order.

Parameters

output (Tuple[str, int]) – An output of the form (name, component), where name is the output name and component is the output component.

Returns

The input parameters sorted in descending order.

Return type

List[str]

property spearman

The Spearman coefficients.

ith the following structure:

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

dict

property src

The Standard Regression Coefficients.

With the following structure:

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

dict

property srrc

The Standard Rank Regression Coefficients.

With the following structure:

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

dict

property ssrrc

The Signed Standard Rank Regression Coefficients.

With the following structure:

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