gemseo.uncertainty.sensitivity.hsic_analysis module#

Sensitivity analysis based on the Hilbert-Schmidt independence criterion (HSIC).

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

Bases: BaseSensitivityAnalysis

Sensitivity analysis based on the Hilbert-Schmidt independence criterion (HSIC).

The compute_indices() method proposes three types of sensitivity analysis:

  • global sensitivity analysis (GSA, default) to identify the input variables most likely to cause the output to deviate from a nominal value,

  • target sensitivity analysis (TSA) to identify the input variables most likely to cause the output to reach a certain domain,

  • conditional sensitivity analysis (CSA) most likely to cause the output to deviate from a nominal value under the condition that the considered output is in a certain domain.

For GSA and CSA, the sensitivity indices can be estimated with both U- and V- statistics. For TSA, only U-statistics is possible.

Given a sensitivity analysis type and a statistics estimation technique, the compute_indices() method returns the standard HSIC indices and the normalized ones, also called R2-HSIC indices.

Examples

>>> from numpy import pi
>>> from gemseo import create_discipline, create_parameter_space
>>> from gemseo.uncertainty.sensitivity.hsic_analysis import HSICAnalysis
>>> from gemseo.problems.uncertainty.ishigami.ishigami_discipline import (
...     IshigamiDiscipline,
... )
>>> from gemseo.problems.uncertainty.ishigami.ishigami_space import (
...     IshigamiSpace,
... )
>>>
>>> discipline = IshigamiDiscipline()
>>> uncertain_space = IshigamiSpace()
>>>
>>> analysis = HSICAnalysis()
>>> analysis.compute_samples([discipline], uncertain_space, n_samples=1000)
>>> 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 AnalysisType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: StrEnum

The sensitivity analysis type.

CONDITIONAL = 'conditional'#

Conditional sensitivity analysis.

This sensitivity analysis is incompatible with StatisticEstimator.USTAT.

GLOBAL = 'global'#

Global sensitivity analysis.

TARGET = 'target'#

Target sensitivity analysis.

class CovarianceModel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: StrEnum

The covariance model type.

GAUSSIAN = 'Gaussian'#

Squared exponential covariance model.

class Method(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: StrEnum

The name of the sensitivity method.

HSIC = 'HSIC'#

The HSIC indices.

P_VALUE_ASYMPTOTIC = 'p-value-asymptotic'#

The p-value obtained with an asymptotic formula.

P_VALUE_PERMUTATION = 'p-value-permutation'#

The p-value estimated through permutations.

R2_HSIC = 'R2-HSIC'#

The normalized HSIC (R2-HSIC) indices.

class SensitivityIndices(hsic: 'FirstOrderIndicesType' = <factory>, r2_hsic: 'FirstOrderIndicesType' = <factory>, p_value_permutation: 'FirstOrderIndicesType' = <factory>, p_value_asymptotic: 'FirstOrderIndicesType' = <factory>)[source]#

Bases: object

Parameters:
hsic: dict[str, list[dict[str, ndarray[Any, dtype[floating[Any]]]]]]#

The HSIC indices.

p_value_asymptotic: dict[str, list[dict[str, ndarray[Any, dtype[floating[Any]]]]]]#

The p-value obtained with an asymptotic formula.

p_value_permutation: dict[str, list[dict[str, ndarray[Any, dtype[floating[Any]]]]]]#

The p-value estimated through permutations.

r2_hsic: dict[str, list[dict[str, ndarray[Any, dtype[floating[Any]]]]]]#

The normalized HSIC indices.

class StatisticEstimator(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: StrEnum

The statistic estimator type.

USTAT = 'U-statistic'#

U-statistic.

VSTAT = 'V-statistic'#

V-statistic.

compute_indices(output_names=(), output_bounds=(), statistic_estimator=StatisticEstimator.USTAT, input_covariance_model=CovarianceModel.GAUSSIAN, output_covariance_model=CovarianceModel.GAUSSIAN, analysis_type=AnalysisType.GLOBAL, seed=0, n_permutations=100)[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. In the case of target and conditional sensitivity analyses, these output names are the keys of the dictionary output_bounds and the argument output_names is ignored.

    By default it is set to ().

  • output_bounds (Mapping[str, tuple[Iterable[float], Iterable[float]]]) --

    The lower and upper bounds of the outputs specified as {name: (lower, upper), ...}. This argument is ignored in the case of global sensitivity analysis. This argument is mandatory in the case of target and conditional sensitivity analyses.

    By default it is set to ().

  • statistic_estimator (StatisticEstimator) --

    The name of the statistic estimator type. This argument is ignored when analysis_type is CONDITIONAL; in this case, the U-statistics do not exist and V-statistics are considered.

    By default it is set to "U-statistic".

  • input_covariance_model (CovarianceModel) --

    The name of the covariance model class of the estimator associated to the input variables.

    By default it is set to "Gaussian".

  • output_covariance_model (CovarianceModel) --

    The name of the covariance model class of the estimator associated to the output variables.

    By default it is set to "Gaussian".

  • analysis_type (AnalysisType) --

    The sensitivity analysis type.

    By default it is set to "global".

  • seed (int) --

    The seed for reproducible results.

    By default it is set to 0.

  • n_permutations (int) --

    The number of permutations used to estimate the p-values.

    By default it is set to 100.

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

DEFAULT_DRIVER: ClassVar[str] = 'OT_MONTE_CARLO'#