sensitivity.sensitivity_local

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.

Classes

Name	Description
LocalSensitivityAnalysis	Local sensitivity analysis based on symmetric finite differences.

LocalSensitivityAnalysis

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

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.

Methods

Name	Description
calculate_sensitivity	Compute raw and normalized local sensitivities.
create_samples	Create parameter samples for local sensitivity analysis.
dfs_sensitivity	Return sensitivity dataframe.
plot	Generate plots for normalized local sensitivities.

calculate_sensitivity

sensitivity.sensitivity_local.LocalSensitivityAnalysis.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

create_samples

sensitivity.sensitivity_local.LocalSensitivityAnalysis.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.

dfs_sensitivity

sensitivity.sensitivity_local.LocalSensitivityAnalysis.dfs_sensitivity()

Return sensitivity dataframe.

plot

sensitivity.sensitivity_local.LocalSensitivityAnalysis.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.