updateWorksetParameter {openMpp}R Documentation

Update parameters working set with new values and value notes

Description

Update parameters working set with new values and value notes

Usage

updateWorksetParameter(dbCon, defRs, worksetId, ...)

Arguments

dbCon

database connection

defRs

model definition: database rows describing model input parameters and output tables

worksetId

id of parameters working set, must be positive integer

...

list of parameters value and value notes.

Each element is also a list of $name, $subCount, $subId, $value, $txt:

  • $name parameter name (character)

  • $subCount (optional) number of parameter sub-values, default: 1

  • subId (optional) parameter sub-value id, default: 0

  • $value (optional) parameter value it can be scalar value. vector or data frame size of $value must be equal to production of dimension sizes if data frame then it must have $dim0, $dim1,..., $value columns and each column length is equal to production of dimension sizes

  • $txt (optional) workset parameter text: data frame with $lang = language code and $note = value notes

Details

That call allow you to update input parameter value and value notes in specific workset.

Parameter(s) can have can have multiple sub-values (by default only one value, no sub-values). If parameter have multiple sub-values then you can specify sub-value id as $subId (default =0).

Workset is a working set of model parameters and can be a full set, which include values of all model parameters or subset and include only some parameters.

Each model must have "default" workset. Default workset is a first workset of the model with set_id = min(set_id) for that model. Default workset always include ALL model parameters (it is a full set).

If you want to create new workset as a full set of model parameters then you must pass ALL model parameters into createWorkset through ... argument list.

If you already have result of model run in your database and want to modify only some input parameters (subset) then call createWorksetBasedOnRun in order to create workset using parameters from previous model run and supply some new values.

You can create subset of model parameters ONLY based on existing run results. Otherwise you have to pass ALL (full set) of parameters in order to create workset.

Each workset has unique set id (positive integer) and unique name. To find set id by name use getWorksetIdByName call.

Working set must be not read-only in order to update parameters by updateWorksetParameter. And working set must be read-only to run the model, so, typically you want to wrap updateWorksetParameter by setReadonlyDefaultWorkset or setReadonlyWorkset calls.

You must use getModel function in order to find model definition defRs.

Value

Return id of working set or 0L on error

Note

To run examples you must have modelOne database modelOne.sqlite in current directory

Author(s)

amc1999

References

OpenM++ documentation: https://github.com/openmpp/openmpp.github.io/wiki

See Also

getModel getDefaultWorksetId getWorksetIdByName createWorkset createWorksetBasedOnRun copyWorksetParameterFromRun setReadonlyWorkset setReadonlyDefaultWorkset

Examples

  #
  # update sub-value =0 of
  #   age by sex parameter double[4, 2] 
  #
  
  # age by sex parameter value and notes
  ageSex <- list(
    name = "ageSex",  # parameter name
    subId = 0L,       # sub-value =0 (first sub-value or parameter have no sub-values)
    value = c(
      10,
      rep(c(1, 2, 3), times = 2),
      20
    ),
    txt = data.frame(
      lang = c("EN", "FR"),
      note = c(
        "age by sex value notes", # EN value notes
        NA                        # NA == no FR value notes 
      ),
      stringsAsFactors = FALSE
    )
  )
  
  theDb <- dbConnect(RSQLite::SQLite(), "modelOne.sqlite", synchronous = "full")
  invisible(dbGetQuery(theDb, "PRAGMA busy_timeout = 86400")) # recommended
  
  # get model by name: use such call if you have only one version of the model
  defRs <- getModel(theDb, "modelOne")
  
  # reset read-only status of workset  
  setId <- 4L
  if (setReadonlyWorkset(theDb, defRs, FALSE, setId) <= 0L) {
    stop("workset not found: ", setId, " for model: ", defRs$modelDic$model_name, " ", defRs$modelDic$model_digest)
  }
  
  # update parameter ageSex with new value and value notes
  updateWorksetParameter(theDb, defRs, setId, ageSex)
  
  # make workset read-only in order to run the model
  setReadonlyWorkset(theDb, defRs, TRUE, setId)
  
  dbDisconnect(theDb)
  #
  # you can run the model now with new ageSex parameter value
  #
[Package openMpp version 0.8.6 Index]