runModel: Run a model of a StoX project

In StoXProject/RstoxFramework: The Engine of StoX

Run a model of a StoX project

Description

This function runs and returns output from a model of a StoX project.

Usage

runModel(
  projectPath,
  modelName,
  processes = NULL,
  startProcess = 1,
  endProcess = Inf,
  drop.datatype = TRUE,
  unlistDepth2 = FALSE,
  run = TRUE,
  save = TRUE,
  force.save = FALSE,
  force.restart = FALSE,
  replaceDataList = list(),
  replaceArgsList = list(),
  prependProcessList = list(),
  fileOutput = NULL,
  setUseProcessDataToTRUE = TRUE,
  purge.processData = FALSE,
  returnModelData = TRUE,
  try = TRUE,
  close = FALSE,
  msg = TRUE,
  ...
)

Arguments

projectPath	The path to the StoX project, i.e., the folder of the project with the sub folders "input", "output" and "process". Can possibly be the path to a file inside the project folder.
modelName	The name of the model (possible values are "baseline", "analysis" and "report").
processes	The name of the processes.
startProcess	The process index, name or ID at which to start the model run.
endProcess	The process index, name or ID at which to stop the model run.
drop.datatype	Logical: If TRUE, drop the top level of the output list if it has length 1 and that single element is named by the datatype name.
unlistDepth2	Logical: Related to drop.datatype, but setting this to TRUE unlists output data that are nested in 2 levels, such as output from ReadBiotic, which outputs a set of tables for each input file. Using unlistDepth2 = TRUE puts all these tables in one list, and uses the concatenation of the file names and the table name separated by underscore. This is how it is displayed in the StoX GUI when selecting "View output".
run	Logical: If TRUE run the model.
save	Logical: If TRUE save the project after running.
force.save	If no changes are made to the project, force save anyway. Overrides the save option.
force.restart	Logical: If TRUE restart the model before running.
replaceDataList	A list named by the processes to replace output data for. See runProcess.
replaceArgsList	A list of replaceArgs holding parameters to replace in the function call, named by the processes to modify.
prependProcessList	A list of values used in prependProcess, named by the processes to prepend a process to.
fileOutput	Logical: If TRUE save the output as a text file (or other format specified by the class or attributes of the output). If NULL (defafult) use the corresponding parameter of the process.
setUseProcessDataToTRUE	Logical: If TRUE set the UseProcessData function parameter to TRUE in the process memory after execution, if the process is a ProcessData process.
purge.processData	Logical: If TRUE replace process data entirely.
returnModelData	Logical: If TRUE return the output of the model runs. Can also be given as a string vector holding the names of the models to return data from. If TRUE, the specific models to return data from (across models) can be given by processes.
try	Logical: If FALSE do not run the process in a tryCatch. Set this to FALSE when debugging, as the tryCatch masks the errors in the traceback.
close	Logical: If TRUE close the project after running and getting the output.
msg	Logical: If FALSE no messages are printed to console (except possibly for extremely important ones).
...	Arguments passed on to openProject, closeProject and runProcesses.

Value

A list of model output.

Examples

## Not run: 
# Open and run the sandeel test project:
tmp <- tempdir()
sandeelZip <- system.file("testresources", "sandeel_20.zip", package = "RstoxFramework")
unzip(sandeelZip, exdir = tmp)
projectPath <- file.path(tmp, "sandeel_20")
d1 <- runModel(projectPath, modelName = "baseline")

# Define depth dependent acoustic target strength, and rerun:
process <- getProcess(
  projectPath = projectPath, 
  modelName = "baseline", 
  processName = "DefineAcousticTargetStrength"
)
newAcousticTargetStrengthTable <- process$functionParameters$AcousticTargetStrengthTable
# Add the depth dependence:
newAcousticTargetStrengthTable$DepthExponent = -2.3

replaceArgsList <- list(
  DefineAcousticTargetStrength = list(
    UseProcessData = FALSE, # Needed to override the existing process data
    AcousticTargetStrengthModel = "LengthAndDepthDependent", 
    AcousticTargetStrengthTable = newAcousticTargetStrengthTable
  )
)
d2 <- RstoxFramework::runModel(
  projectPath, 
  modelName = "baseline", 
  replaceArgsList = replaceArgsList
)

# Show the change in the output:
all.equal(d1, d2)
# The difference is larger at larger depths:
plot(
  d1$Abundance$Data$MinLayerDepth, 
  d1$Abundance$Data$Abundance  /  d2$Abundance$Data$Abundance
)

## End(Not run)

StoXProject/RstoxFramework documentation built on Oct. 17, 2023, 1:24 p.m.