R/idata_set.R

In mrgsolve: Simulate from ODE-Based Models

# Copyright (C) 2013 - 2026  Metrum Research Group
#
# This file is part of mrgsolve.
#
# mrgsolve is free software: you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 2 of the License, or
# (at your option) any later version.
#
# mrgsolve is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with mrgsolve.  If not, see <http://www.gnu.org/licenses/>.



#' Select a idata set for simulation
#' 
#' The individual data set (`idata_set`) is a data frame with one 
#' row for each individual in a population, specifying parameters and 
#' other individual-level data.
#'
#' @param x model object.
#' @param data a data set that can be coerced to data.frame.
#' @param ... not used; `idata_set()` accepts no other arguments.
#' 
#' @details
#' The `idata_set` is a data frame that specifies individual-level 
#' data for the problem. An `ID` column is required and there 
#' can be no more than one row in the data frame for each individual.  
#' 
#' In most cases, the columns in the `idata_set` have the same names
#' as parameters in the [param()] list.  When this is the case, 
#' the parameter set is updated as the simulation proceeds once at the 
#' start of each individual.  The `idata_set` can also be used to 
#' set initial conditions for each individual: for a compartment called
#' `CMT`, make a column in `idata_set` called `CMT_0` and 
#' make the value the desired initial value for that compartment.  Note that 
#' this initial condition will be overridden if you also set the `CMT_0` 
#' in `$MAIN` (`$PK`).
#' 
#' The most common application of `idata_set` is to specify a population
#' or batch of simulations to do.  We commonly use `idata_set` with an 
#' event object (see [ev()]).  In that case, the event gets applied
#' to each individual in the `idata_set`.  
#' 
#' It is also possible to provide both a `data_set` and a `idata_set`.  
#' In this case, the `idata_set` is used as a parameter lookup for `IDs`
#' found in the `data_set`.  Remember in this case, it is the `data_set`
#' (not the `idata_set`) that determines the number of individuals in the
#' simulation.
#' 
#' An error will be generated if any parameter columns in the 
#' input idata set contain `NA`.  
#' 
#' @examples
#' mod <- house()
#' 
#' data(exidata)
#' 
#' exidata
#' 
#' mod %>% 
#'   idata_set(exidata) %>% 
#'   ev(amt = 100) %>%
#'   mrgsim()
#' 
#' mod %>% ev(amt = 100) %>% mrgsim(idata = exidata) 
#' 
#' @seealso [data_set()], [ev()]
#' 
#' @md
#' @export
setGeneric("idata_set", function(x, data, ...) {
  standardGeneric("idata_set")
})

#' @rdname idata_set
#' @export
setMethod("idata_set", c("mrgmod", "data.frame"), function(x, data, ...) {
  if(...length() > 0L) {
    abort("`idata_set` no longer accepts arguments other than `x` and `data`.")
  }
  x@args[["idata"]] <- as.data.frame(data)
  return(x)
})

#' @rdname idata_set
#' @export
setMethod("idata_set",c("mrgmod", "ANY"), function(x, data, ...) {
  return(idata_set(x, as.data.frame(data), ...))
})