Merge pull request #192 from matthiaskoenig/sbmlsim2

Sensitivity and Uncertainty improvements

Author: matthiaskoenig

.bumpversion.toml

@@ -17,3 +17,4 @@ commit_args = ""
 
 [[tool.bumpversion.files]]
 filename = "./src/sbmlsim/__init__.py"
+filename = "./_docs/_quarto.yml"

README.md

@@ -39,8 +39,7 @@ pip install git+https://github.com/matthiaskoenig/sbmlsim.git@develop
 ```
 
 ## How to cite
-[![](https://zenodo.org/badge/55952847.svg)](https://zenodo.org/badge/latestdoi/55952847)
-
+[![DOI](https://zenodo.org/badge/55952847.svg)](https://zenodo.org/badge/latestdoi/55952847)
 
 ## License
 - Source Code: [MIT](https://opensource.org/license/MIT)

RELEASE.md

@@ -4,7 +4,7 @@
 * update release notes in `release-notes` with commit
 * make sure all tests run (`tox -p`)
 * check formating and linting (`ruff check`)
-* build documentation
+* build documentation (`cd _docs | quartodoc build | quatro render`)
 * test bump version (`uvx bump-my-version bump [major|minor|patch] --dry-run -vv`)
 * bump version (`uvx bump-my-version bump [major|minor|patch]`)
 * `git push --tags` (triggers release)

_docs/_quarto.yml

@@ -32,15 +32,16 @@ website:
     search: true
     contents:
        - index.qmd
-       - section: "Analysis"
+#       - section: "Analysis"
 #         contents:
 #          - text: Sensitivity Analysis
 #            href: sensitivity.qmd
-       - section: "API"
+       - section: "Reference"
          contents:
-          - text: "Sensitivity"
+          - text: "Overview"
             href: api/index.qmd
-          - text: "`sensitivity`"
+
+          - text: "Sensitivity & Uncertainty"
             href: api/sensitivity.qmd
           - text: "`sensitivity_fast`"
             href: api/sensitivity.sensitivity_fast.qmd
@@ -52,6 +53,13 @@ website:
             href: api/sensitivity.sensitivity_sobol.qmd
           - text: "`sensitivity_sampling`"
             href: api/sensitivity.sensitivity_sampling.qmd
+          - text: "`classification`"
+            href: api/sensitivity.classification.qmd
+
+
+          - text: "Parameter optimization"
+            href: api/fit.qmd
+
        - section: "Contributing"
          contents:
           - href: development.qmd
@@ -99,8 +107,8 @@ quartodoc:
   dir: api
 
   sections:
-    - title: API sensitivity
-      desc: Sensitivity functionality.
+    - title: Sensitivity
+      desc: Functionality related to sensitivity and uncertainty analysis.
       contents:
         # the functions being documented in the package.
         # you can refer to anything: class methods, modules, etc..
@@ -110,6 +118,11 @@ quartodoc:
         - name: sensitivity.sensitivity_sobol
         - name: sensitivity.sensitivity_morris
         - name: sensitivity.sensitivity_sampling
+        - name: sensitivity.classification
+    - title: Parameter optimization
+      desc: Functionality related to parameter optimization.
+      contents:
+        - name: fit
 
 filters:
   - interlinks

_docs/api/_sidebar.yml

@@ -9,6 +9,10 @@ website:
       - api/sensitivity.sensitivity_sobol.qmd
       - api/sensitivity.sensitivity_morris.qmd
       - api/sensitivity.sensitivity_sampling.qmd
-      section: API sensitivity
+      - api/sensitivity.classification.qmd
+      section: Sensitivity
+    - contents:
+      - api/fit.qmd
+      section: Parameter optimization
     id: api
   - id: dummy-sidebar

_docs/api/fit.qmd

@@ -0,0 +1,9 @@
+# fit { #sbmlsim.fit }
+
+`fit`
+
+Package for parameter fitting and parameter optimization.
+
+For additional resources see for instance
+https://petab.readthedocs.io/en/latest/index.html
+https://pyabc.readthedocs.io/en/latest/index.html

_docs/api/index.qmd

@@ -1,8 +1,8 @@
 # Function reference {.doc .doc-index}
 
-## API sensitivity
+## Sensitivity
 
-Sensitivity functionality.
+Functionality related to sensitivity and uncertainty analysis.
 
 | | |
 | --- | --- |
@@ -12,3 +12,12 @@ Sensitivity functionality.
 | [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. |
 | [sensitivity.sensitivity_sampling](sensitivity.sensitivity_sampling.qmd#sbmlsim.sensitivity.sensitivity_sampling) | Sampling-based sensitivity and uncertainty analysis. |
+| [sensitivity.classification](sensitivity.classification.qmd#sbmlsim.sensitivity.classification) | Classification of sensitivities and uncertainties. |
+
+## Parameter optimization
+
+Functionality related to parameter optimization.
+
+| | |
+| --- | --- |
+| [fit](fit.qmd#sbmlsim.fit) | Package for parameter fitting and parameter optimization. |

_docs/api/sensitivity.classification.qmd

@@ -0,0 +1,91 @@
+# sensitivity.classification { #sbmlsim.sensitivity.classification }
+
+`sensitivity.classification`
+
+Classification of sensitivities and uncertainties.
+
+## Classes
+
+| Name | Description |
+| --- | --- |
+| [SensitivityClassification](#sbmlsim.sensitivity.classification.SensitivityClassification) | Sensitivity classification. |
+| [UncertaintyClassification](#sbmlsim.sensitivity.classification.UncertaintyClassification) | Uncertainty classification. |
+
+### SensitivityClassification { #sbmlsim.sensitivity.classification.SensitivityClassification }
+
+```python
+sensitivity.classification.SensitivityClassification()
+```
+
+Sensitivity classification.
+
+### UncertaintyClassification { #sbmlsim.sensitivity.classification.UncertaintyClassification }
+
+```python
+sensitivity.classification.UncertaintyClassification()
+```
+
+Uncertainty classification.
+
+## Functions
+
+| Name | Description |
+| --- | --- |
+| [sensitivity_classification](#sbmlsim.sensitivity.classification.sensitivity_classification) | Classification of local sensitivity as per WHO IPCS guidance. |
+| [sensitivity_classification_symbol](#sbmlsim.sensitivity.classification.sensitivity_classification_symbol) | Calculates symbol for sensitivity classification. |
+| [uncertainty_classification](#sbmlsim.sensitivity.classification.uncertainty_classification) | Classification of uncertainty as per WHO IPCS guidance. |
+| [uncertainty_classification_symbol](#sbmlsim.sensitivity.classification.uncertainty_classification_symbol) | Calculates symbol for uncertainty classification. |
+
+### sensitivity_classification { #sbmlsim.sensitivity.classification.sensitivity_classification }
+
+```python
+sensitivity.classification.sensitivity_classification(s)
+```
+
+Classification of local sensitivity as per WHO IPCS guidance.
+
+Classification based on absolute sensitivity:
+
+- High: `|Si,j| >= 0.5`
+- Medium: `0.2 <= |Si,j| < 0.5`
+- Low: `0.1 <= |Si,j| < 0.2`
+- Negligible: `|Si,j| < 0.1`
+
+#### References {.doc-section .doc-section-references}
+
+International Programme on Chemical Safety (IPCS). Characterization and
+application of physiologically based pharmacokinetic models in risk assessment.
+World Health Organization; 2010. Contract No.: 9.
+
+### sensitivity_classification_symbol { #sbmlsim.sensitivity.classification.sensitivity_classification_symbol }
+
+```python
+sensitivity.classification.sensitivity_classification_symbol(s)
+```
+
+Calculates symbol for sensitivity classification.
+
+### uncertainty_classification { #sbmlsim.sensitivity.classification.uncertainty_classification }
+
+```python
+sensitivity.classification.uncertainty_classification(u)
+```
+
+Classification of uncertainty as per WHO IPCS guidance.
+
+- High: `Ui,j >= 2`
+- Medium: `0.3 <= |Ui,j| < 2`
+- Low: `0 <= |Ui,j| < 0.3`
+
+#### References {.doc-section .doc-section-references}
+
+International Programme on Chemical Safety (IPCS). Characterization and application of physiologically based pharmacokinetic models in risk assessment.
+World Health Organization; 2010. Contract No.: 9.
+
+### uncertainty_classification_symbol { #sbmlsim.sensitivity.classification.uncertainty_classification_symbol }
+
+```python
+sensitivity.classification.uncertainty_classification_symbol(u)
+```
+
+Calculates symbol for uncertainty classification.

_docs/api/sensitivity.sensitivity_local.qmd

@@ -31,6 +31,12 @@ 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 |
@@ -49,6 +55,7 @@ sensitivity.sensitivity_local.LocalSensitivityAnalysis(
     n_cores=None,
     cache_results=False,
     difference=0.01,
+    n_var=3,
 )
 ```
 
@@ -72,6 +79,7 @@ decrease) are evaluated in addition to a reference simulation.
 | --- | --- |
 | [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. |
+| [dfs_sensitivity](#sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.dfs_sensitivity) | Return sensitivity dataframe. |
 | [plot](#sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.plot) | Generate plots for normalized local sensitivities. |
 
 ##### calculate_sensitivity { #sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.calculate_sensitivity }
@@ -106,11 +114,20 @@ 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)
+- 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 { #sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.dfs_sensitivity }
+
+```python
+sensitivity.sensitivity_local.LocalSensitivityAnalysis.dfs_sensitivity()
+```
+
+Return sensitivity dataframe.
+
 ##### plot { #sbmlsim.sensitivity.sensitivity_local.LocalSensitivityAnalysis.plot }
 
 ```python
@@ -121,3 +138,5 @@ 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.

_docs/api/sensitivity.sensitivity_sampling.qmd

@@ -19,6 +19,8 @@ computed, including:
 - minimum and maximum
 - lower and upper quantiles (5% and 95%)
 
+Uncertainty is calculated as Ui,j = (Percentile97.5(i,j) - Percentile2.5(i,j)) / Percentile50(i,j)
+
 This approach focuses on uncertainty propagation rather than variance-based
 sensitivity indices and is therefore complementary to local and Sobol-based
 methods.