buildFromText: Build a model from the contents of delimited textfiles

In dkneis/rodeo: A Code Generator for ODE-Based Models

Build a model from the contents of delimited textfiles

Description

The function builds a rodeo-based model by importing all declarations and equations from tables stored as delimited text.

Usage

buildFromText(
  declarations,
  equations,
  sep = "\t",
  dim = 1,
  set_defaults = TRUE,
  fortran = FALSE,
  sources = NULL,
  ...
)

Arguments

declarations	File path of a delimited text file holding the declaration of state variables, parameters, and functions. See below for details about the expected file contents.
equations	File path of a delimited text file holding mathematical expressions of process rates and stoichiometric factors forming the right hand sides of a system of simultaneous ODE. See below for details about the expected file contents.
sep	The column delimiter used in the input text files.
dim	The number of spatial compartments, possibly in multiple dimensions. For single-box models without spatial resolution, use dim=1 (default). For a one-dimensional model with 10 compartments use, e.g., dim=10. See the dim argument of the method initialize for further details.
set_defaults	If TRUE, parameters and initial values will be set according to the contents of the 'default' columns of the workbook sheets 'declarations', respectively. If FALSE, values must be set explicitly using the class methods setPars and setVars. An attempt to use set_defaults=TRUE when dim != 1 will be ignored (with a warning).
fortran	Controls the language of code generation. The default (FALSE) produces R code. Use TRUE if you want to use compiled Fortran code for better performance. In the latter case, you will need a Fortran compiler which is accessible by R.
sources	Only relevant if fortran=TRUE. The argument allows the name(s) of additional source file(s) to be provided for processing by the Fortran compiler. In any case, the Fortran code in sources must implement a module with the fixed name 'functions'. This module must contain all user-defined functions referenced in any process rate expressions or any cell of the stoichiometry matrix.
...	Optional arguments passed to read.table.

Value

An object of class rodeo.

Note

The delimited text files provided as input are parsed by read.table with header=TRUE and the delimiter specified by sep. The files must contain the following:

• 'declarations' Declares the identifiers of state variables, parameters, and functions used in the model equations. Mandatory columns are 'type', 'name', 'unit', 'description', and 'default'. Entries in the type column must be one of 'variable', 'parameter', or 'function'. If source code is generated for R (fortran=FALSE), any declared functions must be accessible in the environment where the model is run. If fortran=TRUE, the functions must be implemented in the file(s) listed in sources to be included in compilation. Entries in the 'name' column must be unique, valid identifier names (character followed by characters, digits, underscore). Entries in the 'default' column shall be numeric.

• 'equations' Specifies the model equations. Mandatory columns are 'name', 'unit', 'description', 'rate' plus one column for every state variable of the model. The 'rate' columns holds math expressions for the process rates and columns named after state variables contain the corresponding expressions representing stoichiometric factors. All columns are of type character.

The best way to understand the contents of the input files is to study the examples in the folder 'models' shipped with the package. Type system.file("models", package="rodeo") at the R prompt to see where this folder is installed on your system. A full example is given below.

Author(s)

David Kneis [e-mail]

See Also

buildFromWorkbook provides similar functionality

Examples

# Build and run a SEIR type epidemic model
decl <- system.file("models/SEIR_declarations.txt", package="rodeo")
eqns <- system.file("models/SEIR_equations.txt", package="rodeo")
m <- buildFromText(decl, eqns)
x <- m$dynamics(times=0:30, fortran=FALSE)
print(head(x))

dkneis/rodeo documentation built on Dec. 11, 2024, 12:20 p.m.