Skip to content

README.md

Latest commit

 

History

History
116 lines (89 loc) · 4.56 KB

README.md

File metadata and controls

116 lines (89 loc) · 4.56 KB
Raw

dMod2 - Dynamic Modeling and Parameter Estimation in R

R-CMD-check

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. The default backend is cppDE, which generates C++ with forward and reverse derivatives to second order; cOde with deSolve is available as an alternative.

Installation

remotes::install_github("dModverse/dMod2")

The backend 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::

    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: 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: the model of Bachmann et al. (2011), 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: the model of Kok et al. (2020), 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 from profile likelihoods to a prediction band, and a Hodgkin-Huxley neuron 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, 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, 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