gemseo / uncertainty / sensitivity / hsic

Show inherited members

analysis module

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

class gemseo.uncertainty.sensitivity.hsic.analysis.HSICAnalysis(disciplines, parameter_space, n_samples, output_names=(), algo='', algo_options=mappingproxy({}), formulation='MDF', **formulation_options)[source]

Bases: SensitivityAnalysis

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.uncertainty.use_cases.ishigami.ishigami_discipline import (
...     IshigamiDiscipline,
... )
>>> from gemseo.uncertainty.use_cases.ishigami.ishigami_space import (
...     IshigamiSpace,
... )
>>>
>>> discipline = IshigamiDiscipline()
>>> uncertain_space = IshigamiSpace()
>>>
>>> analysis = HSICAnalysis([discipline], uncertain_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 (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 SensitivityAnalysis.DEFAULT_DRIVER.

    By default it is set to “”.

  • algo_options (Mapping[str, DOELibraryOptionType]) –

    The options of the DOE algorithm.

    By default it is set to {}.

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

class AnalysisType(value)[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)[source]

Bases: StrEnum

The covariance model type.

GAUSSIAN = 'Gaussian'

Squared exponential covariance model.

class Method(value)[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 StatisticEstimator(value)[source]

Bases: StrEnum

The statistic estimator type.

USTAT = 'U-statistic'

U-statistic.

VSTAT = 'V-statistic'

V-statistic.

compute_indices(outputs=(), 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:

  • outputs (str | Sequence[str] | Mapping[str, tuple[Iterable[float], Iterable[float]]]) –

    For global sensitivity analysis, 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. For target and conditional sensitivity analyses, the names and the lower and upper bounds of these outputs specified as {name: (lower, upper), ...}; this argument is mandatory.

    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.

With the following structure:

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

Return type:

dict[str, FirstOrderIndicesType]

DEFAULT_DRIVER: ClassVar[str] = 'OT_MONTE_CARLO'
dataset: IODataset

The dataset containing the discipline evaluations.

default_output: Iterable[str]

The default outputs of interest.

property hsic: dict[str, list[dict[str, ndarray]]]

The HSIC indices.

With the following structure:

{
    "output_name": [
        {
            "input_name": data_array,
        }
    ]
}
property p_value_asymptotic: dict[str, list[dict[str, ndarray]]]

The p-value obtained with an asymptotic formula.

With the following structure:

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

Note

Not yet implemented in OpenTURNS for conditional analysis.

property p_value_permutation: dict[str, list[dict[str, ndarray]]]

The p-value estimated through permutations.

With the following structure:

{
    "output_name": [
        {
            "input_name": data_array,
        }
    ]
}
property r2_hsic: dict[str, list[dict[str, ndarray]]]

The normalized HSIC indices.

With the following structure:

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