Merge pull request #191 from matthiaskoenig/sbmlsim2

Fix #176, documentation sensitivity analysis

Author: matthiaskoenig

_docs/api/index.qmd

@@ -7,7 +7,7 @@ Sensitivity functionality.
 | | |
 | --- | --- |
 | [sensitivity](sensitivity.qmd#sbmlsim.sensitivity) | Sensitivity analysis. |
-| [sensitivity.sensitivity_local](sensitivity.sensitivity_local.qmd#sbmlsim.sensitivity.sensitivity_local) | Local sensitivity analysis based on finite differences. |
+| [sensitivity.sensitivity_local](sensitivity.sensitivity_local.qmd#sbmlsim.sensitivity.sensitivity_local) | Local sensitivity analysis using finite differences. |
 | [sensitivity.sensitivity_fast](sensitivity.sensitivity_fast.qmd#sbmlsim.sensitivity.sensitivity_fast) | Global sensitivity analysis using FAST (Fourier Amplitude Sensitivity Test). |
 | [sensitivity.sensitivity_sobol](sensitivity.sensitivity_sobol.qmd#sbmlsim.sensitivity.sensitivity_sobol) | Global sensitivity analysis using Sobol indices. |
 | [sensitivity.sensitivity_morris](sensitivity.sensitivity_morris.qmd#sbmlsim.sensitivity.sensitivity_morris) | Morris sensitivity analysis. |

_docs/api/sensitivity.sensitivity_local.qmd

@@ -2,43 +2,34 @@
 
 `sensitivity.sensitivity_local`
 
-Local sensitivity analysis based on finite differences.
+Local sensitivity analysis using finite differences.
 
-This module implements a local (derivative-based) sensitivity analysis using
-two-sided finite differences around a reference parameter set. Each model
-parameter is perturbed individually by a small relative amount, and the
-resulting change in model outputs is used to approximate local sensitivities.
+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 analysis is designed for deterministic simulation models and is
-particularly suited for:
+The method is intended for deterministic simulation models and is useful for:
 - Identifying locally influential parameters
-- Debugging and model inspection
-- Complementing global sensitivity analyses
-- Supporting parameter screening prior to optimization or uncertainty analysis
-
-Sensitivities are computed for each analysis group and output variable, and
-can be reported both as raw sensitivities and as normalized, dimensionless
-sensitivities.
-
-The implementation builds on the sbmlsim sensitivity framework and integrates
-with existing simulation, caching, and plotting utilities.
-
+- 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 {.doc-section .doc-section-notes}
 
-For each parameter p_i with reference value p_{i,0}, two perturbed simulations
-are generated:
-    p_i_plus  = p_{i,0} * (1 + difference)
-    p_i_minus = p_{i,0} * (1 - difference)
+For a parameter p with reference value p0, sensitivities are computed as:
 
-## Raw sensitivities are computed using a symmetric finite-difference scheme {.doc-section .doc-section-raw-sensitivities-are-computed-using-a-symmetric-finite-difference-scheme}
+    p_plus  = p0 * (1 + difference)
+    p_minus = p0 * (1 - difference)
 
-S(q_k, p_i) = (q_k(p_i_plus) - q_k(p_i_minus)) / (p_i_plus - p_i_minus)
+    S = (q(p_plus) - q(p_minus)) / (p_plus - p_minus)
 
-Normalized sensitivities represent the relative change in output per relative
-change in parameter:
-    S_norm(q_k, p_i) = S(q_k, p_i) * (p_{i,0} / q_k(p_{i,0}))
+Normalized sensitivities are defined as:
+
+    S_norm = S * (p0 / q(p0))
 
 ## Classes
 
@@ -63,34 +54,25 @@ sensitivity.sensitivity_local.LocalSensitivityAnalysis(
 
 Local sensitivity analysis based on symmetric finite differences.
 
-This class implements a local sensitivity analysis in which each model
-parameter is perturbed individually by a small relative amount while all
-other parameters are kept at their reference values.
-
-For each parameter, two simulations are performed (increase and decrease),
-in addition to a reference simulation. Sensitivities are computed for each
-output variable and analysis group.
-
-
+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 {.doc-section .doc-section-attributes}
 
-difference : float
-    Relative parameter perturbation used for the finite-difference
-    approximation (e.g., 0.01 corresponds to ±1% changes).
-
-#### Attributes
-
-| Name | Description |
-| --- | --- |
-| [num_samples](#sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.num_samples) | Return the number of samples required for the analysis. |
+| Name       | Type             | Description                                                                                                   |
+|------------|------------------|---------------------------------------------------------------------------------------------------------------|
+| difference | [float](`float`) | Relative parameter perturbation used for the finite-difference approximation (e.g., 0.01 corresponds to ±1%). |
+| prefix     | [str](`str`)     | Prefix used for naming result files.                                                                          |
 
 #### Methods
 
 | Name | Description |
 | --- | --- |
-| [calculate_sensitivity](#sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.calculate_sensitivity) | Compute raw and normalized local sensitivity matrices. |
-| [create_samples](#sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.create_samples) | Create parameter samples for the local sensitivity analysis. |
+| [calculate_sensitivity](#sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.calculate_sensitivity) | Compute raw and normalized local sensitivities. |
+| [create_samples](#sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.create_samples) | Create parameter samples for local sensitivity analysis. |
+| [plot](#sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.plot) | Generate plots for normalized local sensitivities. |
 
 ##### calculate_sensitivity { #sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.calculate_sensitivity }
 
@@ -101,35 +83,41 @@ sensitivity.sensitivity_local.LocalSensitivityAnalysis.calculate_sensitivity(
 )
 ```
 
-Compute raw and normalized local sensitivity matrices.
-
-This method calculates two-sided finite-difference sensitivities for
-each parameter–output combination and stores both raw and normalized
-sensitivity matrices.
-
-Optionally, results can be read from or written to a cache file.
-
+Compute raw and normalized local sensitivities.
 
+Sensitivities are calculated using a symmetric finite-difference scheme
+for each parameter–output combination.
 
 ###### Parameters {.doc-section .doc-section-parameters}
 
-cache_filename : str, optional
-    Filename for caching sensitivity results.
-cache : bool, optional
-    Whether to read from and/or write to the cache.
+| Name           | Type           | Description                                             | Default   |
+|----------------|----------------|---------------------------------------------------------|-----------|
+| cache_filename | [str](`str`)   | Filename used to read/write cached sensitivity results. | `None`    |
+| cache          | [bool](`bool`) | Whether cached results should be used.                  | `False`   |
 
 ##### create_samples { #sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.create_samples }
 
 ```python
 sensitivity.sensitivity_local.LocalSensitivityAnalysis.create_samples()
 ```
 
-Create parameter samples for the local sensitivity analysis.
+Create parameter samples for local sensitivity analysis.
 
 For each analysis group, this method constructs a sample matrix
 containing:
 - One reference parameter vector
 - Two perturbed parameter vectors per parameter (±difference)
 
-The samples are stored as xarray.DataArray objects and indexed by
-sample and parameter identifiers.
+Samples are stored as an ``xarray.DataArray`` indexed by sample and
+parameter identifiers.
+
+##### plot { #sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.plot }
+
+```python
+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.

_docs/api/sensitivity.sensitivity_morris.qmd

@@ -4,7 +4,30 @@
 
 Morris sensitivity analysis.
 
-Method of Morris, including groups and optimal trajectories (Morris 1991, Campolongo et al. 2007)
+This module implements the Method of Morris for global screening-based
+sensitivity analysis. The Morris method estimates *elementary effects* by
+sampling trajectories through the parameter space and provides qualitative
+and semi-quantitative measures of parameter importance.
+
+The implementation supports:
+
+- Classical Morris sampling (Morris, 1991)
+- Optimized trajectories (Campolongo et al., 2007)
+- Local optimization of trajectories (Ruano et al., 2012)
+
+For each output variable, the following Morris indices are computed:
+
+- mu: Mean of elementary effects
+- mu_star: Mean of absolute elementary effects
+- sigma: Standard deviation of elementary effects
+- mu_star_conf: Confidence interval of mu_star
+- r: Combined importance measure
+
+## References {.doc-section .doc-section-references}
+
+- Morris, M.D., 1991. Factorial Sampling Plans for Preliminary Computational Experiments. Technometrics 33, 161-174. https://doi.org/10.1080/00401706.1991.10484804
+- Campolongo, F., Cariboni, J., & Saltelli, A. 2007. An effective screening design for sensitivity analysis of large models. Environmental Modelling & Software, 22(10), 1509-1518. https://doi.org/10.1016/j.envsoft.2006.10.004
+- Ruano, M.V., Ribes, J., Seco, A., Ferrer, J., 2012. An improved sampling strategy based on trajectory design for application of the Morris method to systems with many input factors. Environmental Modelling & Software 37, 103-109. https://doi.org/10.1016/j.envsoft.2012.03.008
 
 ## Classes
 
@@ -33,15 +56,11 @@ sensitivity.sensitivity_morris.MorrisSensitivityAnalysis(
 
 Morris sensitivity analysis.
 
-Campolongo et al., [2] introduces an optimal trajectories approach which attempts to maximize the parameter space scanned for a given number of trajectories (where optimal_trajectories). The approach accomplishes this aim by randomly generating a high number of possible trajectories (500 to 1000 in [2]) and selecting a subset of r trajectories which have the highest spread in parameter space. The r variable in [2] corresponds to the optimal_trajectories parameter here.
+Campolongo et al., introduces an optimal trajectories approach which attempts to maximize the parameter space scanned for a given number of trajectories (where optimal_trajectories). The approach accomplishes this aim by randomly generating a high number of possible trajectories (500 to 1000) and selecting a subset of r trajectories which have the highest spread in parameter space. The r variable in corresponds to the optimal_trajectories parameter here.
 
 Calculating all possible combinations of trajectories can be computationally expensive. The number of factors makes little difference, but the ratio between number of optimal trajectories and the sample size results in an exponentially increasing number of scores that must be computed to find the optimal combination of trajectories. We suggest going no higher than 4 levels from a pool of 100 samples with this “brute force” approach.
 
-Ruano et al., [3] proposed an alternative approach with an iterative process that maximizes the distance between subgroups of generated trajectories, from which the final set of trajectories are selected, again maximizing the distance between each. The approach is not guaranteed to produce the most optimal spread of trajectories, but are at least locally maximized and significantly reduce the time taken to select trajectories. With local_optimization = True (which is default), it is possible to go higher than the previously suggested 4 levels from a pool of 100 samples.
-
-[1] Morris, M.D., 1991. Factorial Sampling Plans for Preliminary Computational Experiments. Technometrics 33, 161-174. https://doi.org/10.1080/00401706.1991.10484804
-[2] Campolongo, F., Cariboni, J., & Saltelli, A. 2007. An effective screening design for sensitivity analysis of large models. Environmental Modelling & Software, 22(10), 1509-1518. https://doi.org/10.1016/j.envsoft.2006.10.004
-[3] Ruano, M.V., Ribes, J., Seco, A., Ferrer, J., 2012. An improved sampling strategy based on trajectory design for application of the Morris method to systems with many input factors. Environmental Modelling & Software 37, 103-109. https://doi.org/10.1016/j.envsoft.2012.03.008
+Ruano et al., proposed an alternative approach with an iterative process that maximizes the distance between subgroups of generated trajectories, from which the final set of trajectories are selected, again maximizing the distance between each. The approach is not guaranteed to produce the most optimal spread of trajectories, but are at least locally maximized and significantly reduce the time taken to select trajectories. With local_optimization = True (which is default), it is possible to go higher than the previously suggested 4 levels from a pool of 100 samples.
 
 #### Methods
 
@@ -81,12 +100,12 @@ sensitivity.sensitivity_morris.MorrisSensitivityAnalysis.create_samples()
 Create samples using the Method of Morris.
  Three variants of Morris' sampling for elementary effects is supported:
 
-- Vanilla Morris (see [1])
+- Vanilla Morris
   when ``optimal_trajectories`` is ``None``/``False`` and
   ``local_optimization`` is ``False``
 - Optimised trajectories when ``optimal_trajectories=True`` using
-    Campolongo's enhancements (see [2]) and optionally Ruano's enhancement
-    (see [3]) when ``local_optimization=True``
+    Campolongo's enhancements and optionally Ruano's enhancement
+    when ``local_optimization=True``
 - Morris with groups when the problem definition specifies groups of
   parameters
 
@@ -97,19 +116,3 @@ sensitivity.sensitivity_morris.MorrisSensitivityAnalysis.plot()
 ```
 
 Morris plot.
-
-["mu", "mu_star", "sigma", "mu_star_conf"]
-
-## Functions
-
-| Name | Description |
-| --- | --- |
-| [plot_morris_indices](#sbmlsim.sensitivity.sensitivity_morris.plot_morris_indices) | Barplots and scatterplots of Morris indices. |
-
-### plot_morris_indices { #sbmlsim.sensitivity.sensitivity_morris.plot_morris_indices }
-
-```python
-sensitivity.sensitivity_morris.plot_morris_indices(sa, fig_path)
-```
-
-Barplots and scatterplots of Morris indices.

_docs/api/sensitivity.sensitivity_sampling.qmd

@@ -4,51 +4,24 @@
 
 Sampling-based sensitivity and uncertainty analysis.
 
-This module implements a sampling-based sensitivity analysis in which model
-parameters are varied simultaneously according to predefined bounds and
-probability assumptions, and the resulting distribution of model outputs is
-analyzed statistically.
+This module implements a sampling-based sensitivity and uncertainty analysis
+approach. Model parameters are varied simultaneously within their bounds, and
+the resulting distribution of model outputs is analyzed statistically.
 
-The primary purpose of this approach is to quantify output uncertainty and
-variability induced by parameter uncertainty, rather than to compute
-variance-decomposition sensitivity indices. It is therefore complementary to
-local (derivative-based) and global (variance-based) sensitivity analyses.
-
-Parameter samples are generated using Latin Hypercube Sampling (LHS), a
-stratified Monte Carlo method that ensures efficient coverage of the
-multidimensional parameter space. In the current implementation, parameters
-are sampled independently assuming uniform distributions within their bounds.
+Parameter samples are generated using Latin Hypercube Sampling (LHS), assuming
+independent and uniformly distributed parameters.
 
 For each analysis group and output variable, descriptive statistics are
-computed from the simulated sample ensemble, including:
+computed, including:
+
 - mean and median
 - standard deviation and coefficient of variation
 - minimum and maximum
-- selected quantiles (5% and 95%)
-
-These statistics provide a compact summary of output uncertainty and enable
-comparisons across model outputs and experimental or physiological conditions.
-
-The module is intended for:
-- uncertainty propagation analyses
-- robustness and variability assessments
-- exploratory model analysis and screening
-- reporting uncertainty ranges in computational modeling studies
-
-It integrates with the sbmlsim sensitivity framework and supports result
-caching, tabular export, and visualization of output distributions.
-
+- lower and upper quantiles (5% and 95%)
 
-
-## Notes {.doc-section .doc-section-notes}
-
-This method does not compute sensitivity indices in the strict variance-based
-sense (e.g., Sobol indices). Instead, it characterizes how uncertainty in
-parameters propagates to uncertainty in model outputs via sampling.
-
-Typical workflows combine this approach with local or global sensitivity
-analysis to obtain both quantitative sensitivity measures and uncertainty
-estimates.
+This approach focuses on uncertainty propagation rather than variance-based
+sensitivity indices and is therefore complementary to local and Sobol-based
+methods.
 
 ## Classes
 
@@ -73,11 +46,6 @@ sensitivity.sensitivity_sampling.SamplingSensitivityAnalysis(
 
 Sensitivity/uncertainty analysis based on sampling.
 
-#### more control on sampling {.doc-section .doc-section-more-control-on-sampling}
-
-cv: float = 0.1,
-distribution: DistributionType = DistributionType.NORMAL_DISTRIBUTION,
-
 #### Methods
 
 | Name | Description |