dMod2/README.Rmd at master · dModverse/dMod2 · GitHub

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
---
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 -->

[![R-CMD-check](https://github.com/dModverse/dMod2/actions/workflows/R-CMD-check.yaml/badge.svg)](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 |

Two models are worked through end to end:

- [STAT5 dimerisation after Epo stimulation](examples/boehm.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.
- [`inst/examples/example_BachmannMSB2011.R`](inst/examples/example_BachmannMSB2011.R):
  the JAK2-STAT5 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.

## 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)