Sensitivity analysis

SensitivityAnalysis runs variance-based (Sobol) global sensitivity analysis over the parameters selected for identification.

sensitivity_analysis.sensitivityAnalysis.SensitivityAnalysis

SensitivityAnalysis(
    model_path,
    model_type,
    file_name_prefix,
    sa_options,
    DEBUG=False,
    param_id_output_dir=None,
    resources_dir=None,
    model_out_names=[],
    solver_info={},
    dt=0.01,
    optimiser_options={},
    param_id_obs_path=None,
    params_for_id_path=None,
    operation_funcs_external_path=None,
    cost_funcs_external_path=None,
)

Variance-based (Sobol) global sensitivity analysis for a 0D model.

Wraps the Sobol SA manager and coordinates loading observation data, selecting parameters, running the analysis, and ranking the most impactful parameters. Construct from a config dict with init_from_dict.

Typical flow::

sa = SensitivityAnalysis.init_from_dict(inp)
sa.set_ground_truth_data(obs_data_dict)
sa.set_params_for_id(params_for_id_dict)
sa.run_sensitivity_analysis(sa_options)
top = sa.choose_most_impactful_params_sobol(top_n=5, index_type='ST')

Parameters:

Name	Description	Default
`model_path`	Path to the generated model file.	required
`model_type`	`'cellml_only'`, `'python'` or `'casadi_python'`.	required
`file_name_prefix`	Model name prefix.	required
`sa_options`	SA options dict (`method`, `sample_type`, `num_samples`, `output_dir`).	required
`DEBUG`	Enable debug behaviour.	`False`
`param_id_output_dir`	Root output directory.	`None`
`resources_dir`	Directory holding input resources.	`None`
`model_out_names`	Optional explicit list of model output variable names.	`[]`
`solver_info`	Solver config dict.	`{}`
`dt`	Output sampling step (s).	`0.01`
`optimiser_options`	Options dict (used if a nominal calibration is run).	`{}`
`param_id_obs_path`	Optional path to an `obs_data.json`.	`None`
`params_for_id_path`	Optional path to a `{prefix}_params_for_id.csv`.	`None`

init_from_dict `classmethod`

init_from_dict(inp_data_dict)

Build a SensitivityAnalysis from a configuration dict.

file_prefix is accepted as an alias for file_name_prefix.

Parameters:

Name	Type	Description	Default
`inp_data_dict`		Configuration dict (see `get_default_inp_data_dict`).	required

Returns:

Name	Type	Description
`SensitivityAnalysis`		A configured instance.

set_ground_truth_data

set_ground_truth_data(obs_data_dict)

Set the observation data defining the outputs of interest.

Parameters:

Name	Type	Description	Default
`obs_data_dict`		Observation data dict (see `ObsDataCreator`).	required

set_params_for_id

set_params_for_id(params_for_id_dict)

Set which parameters to vary and their bounds.

Parameters:

Name	Type	Description	Default
`params_for_id_dict`		List of parameter entries (see `CVS0DParamID.set_params_for_id`).	required

set_sa_options

set_sa_options(sa_options)

Set/update the sensitivity-analysis options dict.

Parameters:

Name	Type	Description	Default
`sa_options`		e.g. `method` (see `sa_method_choices()` / the sensitivity_analysis schema), `sample_type`, `num_samples`, `output_dir`.	required

set_model_out_names

set_model_out_names(obs_data_dict)

Derive and store the model output variable names from the obs data.

add_user_operation_func

add_user_operation_func(func)

Register a custom feature-extraction function (see CVS0DParamID.add_user_operation_func).

run_sensitivity_analysis

run_sensitivity_analysis(sa_options=None)

Run the sensitivity analysis, dispatching by method.

Parameters:

Name	Type	Description	Default
`sa_options`		Optional options dict; if omitted, the options set at construction (or via `set_sa_options`) are used. `method` is one of the values declared for `sa_options.method` in the sensitivity_analysis schema (`ANALYSIS_OPTIONS` in parsers.PrimitiveParsers) -- see `sa_method_choices()`.	`None`

run_sobol_sensitivity

run_sobol_sensitivity(sa_options=None)

Run Sobol SA and (on rank 0) save indices and plots.

Computes first-order (S1), total (ST) and second-order (S2) Sobol indices. Ground-truth data and parameters for id must be set first.

Parameters:

Name	Type	Description	Default
`sa_options`		Optional options dict (see `set_sa_options`).	`None`

choose_most_impactful_params_sobol

choose_most_impactful_params_sobol(
    top_n=5,
    index_type="ST",
    criterion="max",
    threshold=0.01,
    use_threshold=False,
)

Ranks and returns parameters based on Sobol indices.

Parameters:

Name	Type	Description	Default
`top_n`	`int`	Max number of parameters to return.	`5`
`index_type`	`str`	'ST' or 'S1'.	`'ST'`
`criterion`	`str or func`	'max', 'mean', or custom lambda.	`'max'`
`threshold`	`float`	Minimum score required. Only applied if use_threshold=True.	`0.01`
`use_threshold`	`bool`	Whether to reject parameters below the threshold.	`False`

Sensitivity analysis