sensitivity.sensitivity_local¶

Local sensitivity analysis using finite differences.

This module implements a local, derivative-based sensitivity analysis using symmetric finite differences around a reference parameter set. Each model parameter is perturbed individually while all other parameters are kept constant.

The method is intended for deterministic simulation models and is useful for: - Identifying locally influential parameters - Debugging and inspecting model behavior - Screening parameters prior to optimization or uncertainty analysis - Complementing global sensitivity analysis methods

Sensitivities are computed per analysis group and output variable and are reported as both raw and normalized (dimensionless) sensitivities.

Notes

For a parameter p with reference value p0, sensitivities are computed as:

p_plus  = p0 * (1 + difference)
p_minus = p0 * (1 - difference)

S = (q(p_plus) - q(p_minus)) / (p_plus - p_minus)

Normalized sensitivities are defined as:

S_norm = S * (p0 / q(p0))

Here a multistep method is implemented following Najjar et al.

References

Najjar A, Hamadeh A, Krause S, Schepky A, Edginton A. Global sensitivity analysis of Open Systems Pharmacology Suite physiologically based pharmacokinetic models. CPT Pharmacometrics Syst Pharmacol. 2024 Dec;13(12):2052-2067. doi: 10.1002/psp4.13256. Epub 2024 Nov 5. PMID: 39498820; PMCID: PMC11646943.

LocalSensitivityAnalysis ¶

LocalSensitivityAnalysis(
    sensitivity_simulation,
    parameters,
    groups,
    results_path,
    seed=None,
    n_cores=None,
    cache_results=False,
    difference=0.01,
    n_var=3,
)

Bases: SensitivityAnalysis

Local sensitivity analysis based on symmetric finite differences.

Each model parameter is perturbed individually by a small relative amount around a reference parameter set, while all other parameters are held constant. For each parameter, two perturbed simulations (increase and decrease) are evaluated in addition to a reference simulation.

Attributes:

Name	Type	Description
`difference`	`float`	Relative parameter perturbation used for the finite-difference approximation (e.g., 0.01 corresponds to ±1%).
`prefix`	`str`	Prefix used for naming result files.

Initialize the local sensitivity analysis.

Parameters:

Name	Type	Description	Default
`sensitivity_simulation`	`SensitivitySimulation`	Simulation wrapper providing model execution and result handling.	required
`parameters`	`list[SensitivityParameter]`	List of model parameters to perturb.	required
`groups`	`list[AnalysisGroup]`	Analysis groups defining parameter modifications and conditions.	required
`results_path`	`Path`	Directory where results and plots will be stored.	required
`seed`	`int`	Random seed for reproducibility.	`None`
`n_cores`	`int`	Number of CPU cores used for parallel simulations.	`None`
`cache_results`	`bool`	Whether simulation and sensitivity results should be cached.	`False`
`difference`	`float`	Relative perturbation size used for finite differences. Defaults to 0.01 (±1%).	`0.01`
`n_var`	`int`	Represents the number of steps at which sensitivity is to be evaluated within the variation fold change	`3`

num_samples `property` ¶

num_samples

Return the total number of required simulation samples.

The local sensitivity analysis requires: - 2 + n_var simulations per parameter (positive and negative perturbations) - One reference simulation

Returns:

Name	Type	Description
`int`	`int`	Total number of parameter samples.

create_samples ¶

create_samples()

Create parameter samples for local sensitivity analysis.

For each analysis group, this method constructs a sample matrix containing: - One reference parameter vector - n_var perturbed parameter vectors per parameter (+difference) - n_var perturbed parameter vectors per parameter (-difference)

Samples are stored as an xarray.DataArray indexed by sample and parameter identifiers.

calculate_sensitivity ¶

calculate_sensitivity(cache_filename=None, cache=False)

Compute raw and normalized local sensitivities.

Sensitivities are calculated using a symmetric finite-difference scheme for each parameter–output combination.

Parameters:

Name	Type	Description	Default
`cache_filename`	`str`	Filename used to read/write cached sensitivity results.	`None`
`cache`	`bool`	Whether cached results should be used.	`False`

dfs_sensitivity ¶

dfs_sensitivity()

Return sensitivity dataframe.

plot ¶

plot()

Generate plots for normalized local sensitivities.

Produces heatmaps of normalized sensitivities for each analysis group and saves the figures to the results directory.

Using default cutoff of 0.1 for negligible.