Repository navigation
Expand file tree
/
Copy pathREADME.Rmd
More file actions
108 lines (80 loc) · 4.81 KB
/
Copy pathREADME.Rmd
File metadata and controls
108 lines (80 loc) · 4.81 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
---
title: "dMod2 - Dynamic Modeling and Parameter Estimation in R"
output:
github_document:
toc: false
html_preview: false
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(
fig.path = "man/figures/README-",
fig.width = 10,
fig.height = 4,
out.width = "100%",
dev = "svglite",
message = FALSE,
warning = FALSE
)
```
<!-- badges: start -->
[](https://github.com/dModverse/dMod2/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
dMod2 builds ODE models of reaction networks, generates and compiles C++ code for them, and estimates their parameters from data. Prediction, observation, parameter transformation and objective functions return gradient and Hessian with their value, propagated forward or in one reverse sweep.
## System requirements
Model code is generated and compiled at run time, so **C and C++ compilers** and **Python with SymPy** are required; reticulate provides the Python packages on first use. On Linux the compilers are usually present, Windows users need [Rtools](https://cran.r-project.org/bin/windows/Rtools/). The default backend is [cppDE](https://github.com/dModverse/cppDE), which generates C++ with forward and reverse derivatives to second order; [cOde](https://github.com/dkaschek/cOde) with deSolve is available as an alternative.
## Installation
```r
remotes::install_github("dModverse/dMod2")
```
The backend [cppDE](https://github.com/dModverse/cppDE) comes along as a
`Remotes:` dependency and does not have to be installed separately.
### As an RStudio project
Working on the package itself is easier from a checkout.
1. **File → New Project → Version Control → Git**, repository URL
`https://github.com/dModverse/dMod2`.
2. Install the dependencies, including the ones declared under `Remotes:`:
```r
remotes::install_deps(dependencies = TRUE)
```
3. **Build → Install and Restart**.
`cppDE` installs the same way and has to be built first: dMod2 compiles the
generated model sources against its headers.
## Building a model
Models are assembled from four kinds of function objects that compose with `*` (concatenation, chain rule) and `+` (direct sum over experimental conditions):
| Object | Constructor | Role |
|---|---|---|
| `odemodel`, `prdfn` | `odemodel()`, `Xs()` | the compiled ODE and its sensitivities |
| `obsfn` | `Y()` | observation and error functions |
| `parfn` | `P()` | parameter transformations |
| `objfn` | `normL2()`, `constraintL2()` | objective functions |
Three models are worked through end to end:
- [STAT5 dimerisation after Epo stimulation](examples/Boehm_JProteomeRes2014.md): the model of
Boehm et al. (2014) from reactions to profile likelihoods, with a multistart
fit, an error model by restricted maximum likelihood and confidence
intervals.
- [JAK2-STAT5 signalling with feedbacks](examples/BachmannMSB2011.md): the model of
[Bachmann et al. (2011)](https://doi.org/10.1038/msb.2011.50), with 25 states
in two compartments, the negative feedbacks CIS, SOCS3 and SHP1, and 113
parameters estimated from 541 measurements across thirteen experiments.
- [IFN-alpha sensitization](examples/KokMSB2020.md): the model of
[Kok et al. (2020)](https://doi.org/10.15252/msb.20198955), its structural
identifiability, the fit at the published optimum over 25 conditions, the
gradient by forward sensitivities and by the reverse sweep, and the
sensitization of a second dose by a first.
All three are demos of the package, as are [bile acid
transport](examples/BA_transport.md) from profile likelihoods to a prediction band, and
a [Hodgkin-Huxley neuron](examples/HodgkinHuxley.md) with switches on time and
state. `demo("KokMSB2020", package = "dMod2")` runs one, `demo(package = "dMod2")`
lists them.
## Structural identifiability
`symmetryDetection()` finds the directions in parameters and initial values along
which the observations of a model do not change, and `symmetryReduction()` turns
them into a parameter transformation that removes them. Both run in the Python
package [symident](https://github.com/dModverse/symident), which dMod2 installs
from PyPI on first use; under `RETICULATE_PYTHON` install it there with
`pip install symident`. A steady-state start on coupled steady states needs
msolve, which `symmetryDetection()` offers to build when it is missing, or which
`SYMIDENT_MSOLVE` points to.
## Citation
There is no publication for dMod2 yet. The paper below describes [dMod](https://github.com/JetiLab/dMod), its predecessor, and is the reference for the modelling framework:
Kaschek D, Mader W, Fehling-Kaschek M, Rosenblatt M, Timmer J (2019). Dynamic Modeling, Parameter Estimation, and Uncertainty Analysis in R. *Journal of Statistical Software*, 88(10), 1-32. [doi:10.18637/jss.v088.i10](https://doi.org/10.18637/jss.v088.i10)