ffm_run: Run the model with a given table of parameters.

View source: R/ffm_api_functions.R

ffm_runR Documentation

Run the model with a given table of parameters.

Description

This function requests the Scala model application to run a simulation with the given input parameters and write results to a SQLite database file. For a related set of simulations (e.g. when exploring the effects of variation over a subset of parameters), the function can be called repeatedly (once for each realization of the parameters) with the same database file specified, and each set of results will be appended to the database with an incremented replicate ID number.

Usage

ffm_run(params, db.path, default.species.params = NULL, db.recreate = FALSE)

Arguments

params

A data frame of parameters

db.path

The path and filename of a new or existing SQLite database file to which simulation results will be written.

default.species.params

An optional data frame with species as rows and parameters as columns giving default values to use for species parameters not specified in the input params table. Any subset of species parameters can be specified. Column names must match the parameter names in the ParamInfo table (case is ignored). An NA value indicates no default. This allows default values for a particular parameter to be provided for only a subset of species.

db.recreate

If TRUE and the file specified by db.path exists, the database will be recreated and any prior results will be lost. If FALSE (default) and the file exists, the simulation results will be appended to the database with an incremented replicate ID value (field repId in all tables).

Details

To run the external Scala model application, the function first writes the parameters to a temporary CSV-format file. It then issues a system call to use the Java installation on your machine to run the simulation with the parameters file and the output database specified by db.path. For this to work, you must have a properly installed version of Java (version 1.8.x or higher) that can be run from any directory by issuing the command 'java'. Consult the Oracle Java installation instructions for more details.

Value

TRUE if the run completed and results were written to the output database successfully; FALSE otherwise.

Examples

SPECIFY INPUTS
record <- 1
data(site)
data(structure)
data(flora)
data(traits)
base.params <- paramBuilder(site, structure, flora, traits, record)

RUN THE MODEL AND LOAD RESULTS
Specify the name of the input file, name the sqLite database that it will write to, and whether you want each 
model run to overwrite the last (db.recreate = TRUE), or append to it.
The model will first check that Java is up to date, then print "TRUE" if it could run the input file

ffm_run(base.params, db.path = "out.db", db.recreate = TRUE)
res<-ffm_db_load("out.db")


pzylstra/frame_r documentation built on Nov. 12, 2023, 1:55 a.m.