R: Class 'modelBaseClass'

modelBaseClass-class {nimble} | R Documentation

## Class `modelBaseClass`

### Description

This class underlies all NIMBLE model objects: both R model objects created from the return value of nimbleModel(), and compiled model objects. The model object contains a variety of member functions, for providing information about the model structure, setting or querying properties of the model, or accessing various internal components of the model. These member functions of the modelBaseClass are commonly used in the body of the `setup` function argument to nimbleFunction(), to aid in preparation of node vectors, nimbleFunctionLists, and other runtime inputs. See documentation for `nimbleModel` for details of creating an R model object.

### Methods

`check()`

  Checks for errors in model specification and for missing values that prevent use of calculate/simulate on any nodes

`checkBasics()`

  Checks for size/dimension mismatches and for presence of NAs in model variables (the latter is not an error but a note of this is given to the user)

`checkConjugacy(nodeVector, restrictLink = NULL)`

  Determines whether or not the input nodes appear in conjugate relationships

  Arguments:

  nodeVector: A character vector specifying one or more node or variable names. If omitted, all stochastic non-data nodes are checked for conjugacy.

  Details: The return value is a named list, with an element corresponding to each conjugate node. The list names are the conjugate node names, and list elements are the control list arguments required by the corresponding MCMC conjugate sampler functions. If no model nodes are conjugate, an empty list is returned.

`expandNodeNames(nodes, env = parent.frame(), returnScalarComponents = FALSE, returnType = "names", sort = FALSE, unique = TRUE)`

  Takes a vector of names of nodes or variables and returns the unique and expanded names in the model, i.e. 'x' expands to 'x[1]', 'x[2]', ...

  Arguments:

  nodes: a vector of names of nodes (or variables) to be expanded. Alternatively, can be a vector of integer graph IDs, but this use is intended only for advanced users

  returnScalarComponents: should multivariate nodes (i.e. dmnorm or dmulti) be broken up into scalar components?

  returnType: return type. Options are 'names' (character vector) or 'ids' (graph IDs)

  sort: should names be topologically sorted before being returned?

  unique: should names be the unique names or should original ordering of nodes (after expansion of any variable names into node names) be preserved

`getCode()`

  Return the code for a model after , processing if-then-else statements,

  expanding macros, and replacing some

  keywords (e.g. nimStep for step) to

  avoid R ambiguity.

`getDependencies(nodes, omit = character(), self = TRUE, determOnly = FALSE, stochOnly = FALSE, includeData = TRUE, dataOnly = FALSE, includeRHSonly = FALSE, downstream = FALSE, returnType = "names", returnScalarComponents = FALSE)`

  Returns a character vector of the nodes dependent upon the input argument nodes, sorted topologically according to the model graph. Aditional input arguments provide flexibility in the values returned.

  Arguments:

  nodes: Character vector of node names, with index blocks allowed, and/or variable names, the dependents of which will be returned.

  omit: Character vector of node names, which will be omitted from the nodes returned. In addition, dependent nodes subsequent to these omitted nodes will not be returned. The omitted nodes argument serves to stop the downward search within the hierarchical model struture, and excludes the specified node.

  self: Logical argument specifying whether to include the input argument nodes in the return vector of dependent nodes. Default is TRUE.

  determOnly: Logical argument specifying whether to return only deterministic nodes. Default is FALSE.

  stochOnly: Logical argument specifying whether to return only stochastic nodes. Default is FALSE.

  includeData: Logical argument specifying whether to include 'data' nodes (set via the member method setData). Default is TRUE.

  dataOnly: Logical argument specifying whether to return only 'data' nodes. Default is FALSE.

  includeRHSonly: Logical argument specifying whether to include right-hand-side-only nodes (model nodes which never appear on the left-hand-side of ~ or <- in the model code). These nodes are neither stochastic nor deterministic, but instead function as variable inputs to the model. Default is FALSE.

  downstream: Logical argument specifying whether the downward search through the model hierarchical structure should continue beyond the first and subsequent stochastic nodes encountered, hence returning all nodes downstream of the input nodes. Default is FALSE.

  returnType: Character argument specific type object returned. Options are 'names' (returns character vector) and 'ids' (returns numeric graph IDs for model)

  returnScalar Componenets: Logical argument specifying whether multivariate nodes should return full node name (i.e. 'x[1:2]') or should break down into scalar componenets (i.e. 'x[1]' and 'x[2]')

  Details: The downward search for dependent nodes propagates through deterministic nodes, but by default will halt at the first level of stochastic nodes encountered.

`getDependenciesList(returnNames = TRUE, sort = TRUE)`

  Returns a list of all neighbor relationships. Each list element gives the one-step dependencies of one vertex, and the element name is the vertex label (integer ID or character node name)

  Arguments:

  returnNames: If TRUE (default), list names and element contents are returns as character node names, e.g. 'x[1]'. If FALSE, everything is returned using graph IDs, which are unique integer labels for each node.

  sort: If TRUE (default), each list element is returned in topologically sorted order. If FALSE, they are returned in arbitrary order.

  Details: This provides a fairly raw representation of the graph (model) structure that may be useful for inspecting what NIMBLE has created from model code.

`getDimension(node, params = NULL, valueOnly = is.null(params) && !includeParams, includeParams = !is.null(params))`

  Determines the dimension of the value and/or parameters of the node

  Arguments:

  node: A character vector specifying a single node

  params: an optional character vector of names of parameters for which dimensions are desired (possibly including 'value' and alternate parameters)

  valueOnly: a logical indicating whether to only return the dimension of the value of the node

  includeParams: a logical indicating whether to return dimensions of parameters. If TRUE and 'params' is NULL then dimensions of all parameters, including the dimension of the value of the node, are returned

  Details: The return value is a numeric vector with an element for each parameter/value requested.

`getDistribution(nodes)`

  Returns the names of the distributions for the requested node or nodes

  Arguments:

  nodes: A character vector specifying one or more node or variable names.

  Details: The return value is a character vector with an element for each node indicated in the input. Note that variable names are expanded to their constituent node names, so the length of the output may be longer than that of the input.

`getDownstream(...)`

  Identical to getDependencies(..., downstream = TRUE)

  Details: See documentation for member method getDependencies.

`getNodeNames(determOnly = FALSE, stochOnly = FALSE, includeData = TRUE, dataOnly = FALSE, includeRHSonly = FALSE, topOnly = FALSE, latentOnly = FALSE, endOnly = FALSE, returnType = "names", returnScalarComponents = FALSE)`

  Returns a character vector of all node names in the model, in topologically sorted order. A variety of logical arguments allow for flexible subsetting of all model nodes.

  Arguments:

  determOnly: Logical argument specifying whether to return only deterministic nodes. Default is FALSE.

  stochOnly: Logical argument specifying whether to return only stochastic nodes. Default is FALSE.

  includeData: Logical argument specifying whether to include 'data' nodes (set via the member method setData). Default is TRUE.

  dataOnly: Logical argument specifying whether to return only 'data' nodes. Default is FALSE.

  includeRHSonly: Logical argument specifying whether to include right-hand-side-only nodes (model nodes which never appear on the left-hand-side of ~ or <- in the model code). Default is FALSE.

  topOnly: Logical argument specifying whether to return only top-level nodes from the hierarchical model structure.

  latentOnly: Logical argument specifying whether to return only latent (mid-level) nodes from the hierarchical model structure.

  endOnly: Logical argument specifying whether to return only end nodes from the hierarchical model structure.

  returnType: Character argument specific type object returned. Options are 'names' (returns character vector) and 'ids' (returns numeric graph IDs for model)

  returnScalar Componenets: Logical argument specifying whether multivariate nodes should return full node name (i.e. 'x[1:2]') or should break down into scalar componenets (i.e. 'x[1]' and 'x[2]')

  Details: Multiple logical input arguments may be used simultaneously. For example, model$getNodeNames(endOnly = TRUE, dataOnly = TRUE) will return all end-level nodes from the model which are designated as 'data'.

`getVarNames(includeLogProb = FALSE, nodes)`

  Returns the names of all variables in a model, optionally including the logProb variables

  Arguments:

  logProb: Logical argument specifying whether or not to include the logProb variables. Default is FALSE.

  nodes: An optional character vector supplying a subset of nodes for which to extract the variable names and return the unique set of variable names

`initializeInfo()`

  Provides more detailed information on which model nodes are not initialized.

`isBinary(nodes)`

  Determines whether one or more nodes represent binary random variables

  Arguments:

  nodes: A character vector specifying one or more node or variable names.

  Details: The return value is a character vector with an element for each node indicated in the input. Note that variable names are expanded to their constituent node names, so the length of the output may be longer than that of the input.

`isData(nodes)`

  Returns a vector of logical TRUE / FALSE values, corresponding to the 'data' flags of the input node names.

  Arguments:

  nodes: A character vector of node or variable names.

  Details: The variable or node names specified is expanded into a vector of model node names. A logical vector is returned, indicating whether each model node has been flagged as containing 'data'.

`isDeterm(nodes)`

  Determines whether one or more nodes are deterministic

  Arguments:

  nodes: A character vector specifying one or more node or variable names.

  Details: The return value is a character vector with an element for each node indicated in the input. Note that variable names are expanded to their constituent node names, so the length of the output may be longer than that of the input.

`isDiscrete(nodes)`

  Determines whether one or more nodes represent discrete random variables

  Arguments:

  nodes: A character vector specifying one or more node or variable names.

  Details: The return value is a character vector with an element for each node indicated in the input. Note that variable names are expanded to their constituent node names, so the length of the output may be longer than that of the input.

`isEndNode(nodes)`

  Determines whether one or more nodes are end nodes (nodes with no stochastic dependences)

  Arguments:

  nodes: A character vector specifying one or more node or variable names.

  Details: The return value is logical vector with an element for each node indicated in the input. Note that variable names are expanded to their constituent node names, so the length of the output may be longer than that of the input.

`isMultivariate(nodes)`

  Determines whether one or more nodes represent multivariate nodes

  Arguments:

  nodes: A character vector specifying one or more node or variable names.

  Details: The return value is a logical vector with an element for each node indicated in the input. Note that variable names are expanded to their constituent node names, so the length of the output may be longer than that of the input.

`isStoch(nodes)`

  Determines whether one or more nodes are stochastic

  Arguments:

  nodes: A character vector specifying one or more node or variable names.

  Details: The return value is a character vector with an element for each node indicated in the input. Note that variable names are expanded to their constituent node names, so the length of the output may be longer than that of the input.

`isTruncated(nodes)`

  Determines whether one or more nodes are truncated

  Arguments:

  nodes: A character vector specifying one or more node or variable names.

  Details: The return value is a character vector with an element for each node indicated in the input. Note that variable names are expanded to their constituent nodes names, so the length of the output may be longer than that of the input

`isUnivariate(nodes)`

  Determines whether one or more nodes represent univariate random variables

  Arguments:

  nodes: A character vector specifying one or more node or variable names.

  Details: The return value is a character vector with an element for each node indicated in the input. Note that variable names are expanded to their constituent nodes names, so the length of the output may be longer than that of the input

`newModel(data = NULL, inits = NULL, modelName = character(), replicate = FALSE, check = getNimbleOption("checkModel"), calculate = TRUE)`

  Returns a new R model object, with the same model definiton (as defined from the original model code) as the existing model object.

  Arguments:

  data: A named list specifying data nodes and values, for use in the newly returned model. If not provided, the data argument from the creation of the original R model object will be used.

  inits: A named list specifying initial values, for use in the newly returned model. If not provided, the inits argument from the creation of the original R model object will be used.

  modelName: An optional character string, used to set the internal name of the model object. If provided, this name will propagate throughout the generated C++ code, serving to improve readability.

  replicate: Logical specifying whether to replicate all current values and data flags from the current model in the new model. If TRUE, then the data and inits arguments are not used. Default value is FALSE.

  check: A logical indicating whether to check the model object for missing or invalid values. Default is given by the NIMBLE option 'checkModel', see help on 'nimbleOptions' for details.

  calculate: A logical indicating whether to run 'calculate' on the model; this will calculate all deterministic nodes and logProbability values given the current state of all nodes. Default is TRUE. For large models, one might want to disable this, but note that deterministic nodes, including nodes introduced into the model by NIMBLE, may be NA.

  Details: The newly created model object will be identical to the original model in terms of structure and functionality, but entirely distinct in terms of the internal values.

`resetData()`

  Resets the 'data' property of ALL model nodes to FALSE. Subsequent to this call, the model will have no nodes flagged as 'data'.

`setData(..., warnAboutMissingNames = TRUE)`

  Sets the 'data' flag for specified nodes to TRUE, and also sets the value of these nodes to the value provided. This is the exclusive method for specifying 'data' nodes in a model object. When a 'data' argument is provided to 'nimbleModel()', it uses this method to set the data nodes.

  Arguments:

  ...: Arguments may be provided as named elements with numeric values or as character names of model variables. These may be provided in a single list, a single character vector, or as multiple arguments. When a named element with a numeric value is provided, the size and dimension must match the corresponding model variable. This value will be copied to the model variable and any non-NA elements will be marked as data. When a character name is provided, the value of that variable in the model is not changed but any currently non-NA values are marked as data. Examples: setData('x', y = 1:10) will mark both x and y as data and will set the value of y to 1:10. setData(list('x', y = 1:10)) is equivalent. setData(c('x','y')) or setData('x','y') will mark both x and y as data.

  Details: If a provided value (or the current value in the model when only a name is specified) contains some NA values, then the model nodes corresponding to these NAs will not have their value set, and will not be designated as 'data'. Only model nodes corresponding to numeric values in the argument list elements will be designated as data. Designating a deterministic model node as 'data' will result in an error. Designating part of a multivariate node as 'data' and part as non-data (NA) will result in an error; multivariate nodes must be entirely data, or entirely non-data.

`setInits(inits)`

  Sets initial values (or more generally, any named list of value elements) into the model

  Arguments:

  inits: A named list. The names of list elements must correspond to model variable names. The elements of the list must be of class numeric, with size and dimension each matching the corresponding model variable.

`topologicallySortNodes(nodes, returnType = "names")`

  Sorts the input list of node names according to the topological dependence ordering of the model structure.

  Arguments:

  nodes: A character vector of node or variable names, which is to be topologically sorted. Alternatively can be a numeric vector of graphIDs

  returnType: character vector indicating return type. Choices are "names" or "ids"

  Details: This function merely reorders its input argument. This may be inportany prior to calls such as simulate(model, nodes) or calculate(model, nodes), to enforce that the operation is performed in topological order.

### Author(s)

Daniel Turek

### See Also

`initializeModel`

### Examples

    code <- nimbleCode({
        mu ~ dnorm(0, 1)
        x[1] ~ dnorm(mu, 1)
        x[2] ~ dnorm(mu, 1)
    })
    Rmodel <- nimbleModel(code)
    modelVars <- Rmodel$getVarNames()   ## returns 'mu' and 'x'
    modelNodes <- Rmodel$getNodeNames()   ## returns 'mu', 'x[1]' and 'x[2]'
    Rmodel$resetData()
    Rmodel$setData(list(x = c(1.2, NA)))   ## flags only 'x[1]' node as data
    Rmodel$isData(c('mu', 'x[1]', 'x[2]'))   ## returns c(FALSE, TRUE, FALSE)

[Package nimble version 0.9.1 Index]