README.Rmd

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

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.

## Mixed-effects models

Random effects are written as effect formulas on the parameter transformation, in
the notation of lme4, and `em()` fits them by marginal maximum likelihood: FOCEI,
adaptive sparse-grid quadrature, laplaceEM or SAEM. Besides normal random effects,
Laplace, spike-and-slab and Dirichlet-process ones select which groups differ, with
their hyperparameters estimated in the same fit. The demo [alignment](examples/alignment.md)
aligns qPCR experiments and Western blots with a random gel background together with
targeted mass spectrometry in nM with `align()`.

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

## Distributed computing

`distributedComputing()` runs fits, profiles or any other R code as tasks in the
background: on the local machine, on machines reached by ssh with the cores each may
use, or as an array job of a SLURM cluster through a job script template. The
[guide](examples/distributedComputing.md) shows how.

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