docs: mention sim_discrete_event() throughout package documentation

feat: more tests for sim_discrete_event()

Author: RobinDenz1

R/input_checks.r

@@ -623,6 +623,15 @@ check_inputs_sim_discrete_time <- function(n_sim, dag, t0_sort_dag,
     stopifnot("'save_states' must be either 'last', 'all' or 'at_t'." =
                 is.element(save_states, c("last", "all", "at_t")))
   }
+
+  # no next_time nodes allowed
+  types <- vapply(tx_nodes, FUN=function(x){x$type_str},
+                  FUN.VALUE=character(1))
+  if ("next_time" %in% types) {
+    stop("Nodes of type='next_time' are not allowed in sim_discrete_time()",
+         ". Use sim_discrete_event() instead or re-define the DAG.",
+         call.=FALSE)
+  }
 }
 
 ## checking the inputs of the node_time_to_event function
@@ -885,7 +894,7 @@ check_inputs_sim_discrete_event <- function(dag, n_sim, t0_sort_dag,
     names_args <- names(t0_transform_args)
     if (!all(names_args %in% names_fun)) {
       stop("The following arguments are in 't0_transform_args' but are",
-           " not define in 't0_transform_fun': ",
+           " not defined in 't0_transform_fun': ",
            paste0(names_args[!names_args %in% names_fun], collapse=","),
            call.=FALSE)
     }

R/sim_discrete_event.r

@@ -4,6 +4,7 @@
 #' @importFrom data.table copy
 #' @importFrom data.table melt.data.table
 #' @importFrom data.table merge.data.table
+#' @importFrom data.table as.data.table
 #' @importFrom data.table setkey
 #' @importFrom data.table rbindlist
 #' @importFrom data.table fifelse
@@ -78,7 +79,7 @@ sim_discrete_event <- function(dag, n_sim=NULL, t0_sort_dag=FALSE,
                          check_inputs=check_inputs)
     data[, .id := seq(1, n_sim)]
   } else {
-    data <- data.table::setDT(t0_data)
+    data <- as.data.table(t0_data)
     n_sim <- nrow(data)
     data[, .id := seq(1, n_sim)]
   }
@@ -209,7 +210,6 @@ sim_discrete_event <- function(dag, n_sim=NULL, t0_sort_dag=FALSE,
     out[[length(out) + 1]] <- data[!duplicated(data$.id), cnames, with=FALSE]
 
     # remove rows that no longer need to be updated
-
     data <- data[!(is.infinite(.event_duration) & .is_new_event==TRUE) &
                  !(is.infinite(.immunity_duration) & .is_new_change==TRUE) &
                  .time < max_t]
@@ -349,7 +349,7 @@ timecuts <- function(n, rate, l, cuts) {
 }
 
 ## this function efficiently either sets the covariate values to TRUE if
-## a new event occured or sets them back to FALSE if needed
+## a new event occurred or sets them back to FALSE if needed
 set_cols_to_value <- function(data, .value, type, var_names, allow_ties) {
 
   .is_new_event <- .kind <- .id <- .is_new_change <- .time <-

R/sim_n_datasets.r

@@ -13,6 +13,25 @@ sim_n_datasets <- function(dag, n_sim, n_repeats, n_cores=1,
                               data_format_args=data_format_args,
                               progressbar=progressbar)
 
+  # select which function should be used
+  if (length(dag$tx_nodes) > 0) {
+    types <- vapply(dag$tx_nodes, FUN=function(x){x$type_str},
+                    FUN.VALUE=character(1))
+    if ("next_time" %in% types) {
+      sim <- "DES"
+    } else {
+      sim <- "DTS"
+    }
+  } else {
+    sim <- "DAG"
+  }
+
+  if (sim=="DES" & data_format %in% c("long", "wide")) {
+    warning("Only the 'start_stop' format is supported with discrete-event",
+            " simulations. No data transformation was carried out.",
+            call.=FALSE)
+  }
+
   # without parallel processing
   if (n_cores==1) {
 
@@ -21,7 +40,7 @@ sim_n_datasets <- function(dag, n_sim, n_repeats, n_cores=1,
     for (i in seq_len(n_repeats)) {
       out[[i]] <- generate_one_dataset(dag=dag, data_format=data_format,
                                        data_format_args=data_format_args,
-                                       n_sim=n_sim, ...)
+                                       n_sim=n_sim, sim=sim, ...)
     }
 
   # with parallel processing
@@ -69,7 +88,7 @@ sim_n_datasets <- function(dag, n_sim, n_repeats, n_cores=1,
 
       generate_one_dataset(dag=dag, data_format=data_format,
                            data_format_args=data_format_args,
-                           n_sim=n_sim, ...)
+                           n_sim=n_sim, sim=sim, ...)
     }
     on.exit(close(pb))
     on.exit(parallel::stopCluster(cl))
@@ -81,23 +100,28 @@ sim_n_datasets <- function(dag, n_sim, n_repeats, n_cores=1,
 ## generate one dataset using either the sim_from_dag() or the
 ## sim_discrete_time() function and optionally format it
 generate_one_dataset <- function(dag, data_format, data_format_args, n_sim,
-                                 ...) {
+                                 sim, ...) {
 
   # simulate the dataset
-  if (length(dag$tx_nodes) > 0) {
+  if (sim=="DTS") {
     dat <- sim_discrete_time(dag=dag, n_sim=n_sim, ...)
+  } else if (sim=="DES") {
+    dat <- sim_discrete_event(dag=dag, n_sim=n_sim, ...)
   } else {
     dat <- sim_from_dag(dag=dag, n_sim=n_sim, ...)
   }
 
   # transform it, if specified
   if (data_format %in% c("start_stop", "long", "wide") &&
-      length(dag$tx_nodes) > 0) {
+      sim=="DTS") {
 
     data_format_args$to <- data_format
     data_format_args$sim <- dat
     dat <- do.call("sim2data", args=data_format_args)
 
+  } else if (data_format %in% c("start_stop", "long", "wide") &&
+             sim=="DES") {
+    # do nothing
   } else if (data_format != "raw") {
     data_format_args$data <- dat
     dat <- do.call(data_format, args=data_format_args)

TODOs.txt

@@ -8,14 +8,12 @@ sim_discrete_event:
 
     General:
 	- write Vignette
-	- update documentation throughout the package
-	- add this function to sim_n_datasets()
 
     missing features:
 	- allow formula
 	- allow network dependencies
 	- change how .event_count works, to allow the amount of previous events to influence other events
-	- remove_not_at_risk argument
+	- add remove_not_at_risk argument
 	- allow internal other distr_fun (cox, aft models, ...)
 
 ####### New Features: #######

man/node.Rd

@@ -6,7 +6,7 @@
 Create a node object for a \code{DAG}
 }
 \description{
-These functions should be used in conjunction with the \code{\link{empty_dag}} function to create \code{DAG} objects, which can then be used to simulate data using the \code{\link{sim_from_dag}} function or the \code{\link{sim_discrete_time}} function.
+These functions should be used in conjunction with the \code{\link{empty_dag}} function to create \code{DAG} objects, which can then be used to simulate data using the \code{\link{sim_from_dag}}, \code{\link{sim_discrete_time}} or \code{\link{sim_discrete_event}} functions.
 }
 \usage{
 node(name, type, parents=NULL, formula=NULL, ...)
@@ -32,28 +32,29 @@ Further named arguments needed to specify the node. Those can be parameters of d
 }
 \details{
 
-To generate data using the \code{\link{sim_from_dag}} function or the \code{\link{sim_discrete_time}} function, it is required to create a \code{DAG} object first. This object needs to contain information about the causal structure of the data (e.g. which variable causes which variable) and the specific structural equations for each variable (information about causal coefficients, type of distribution etc.). In this package, the \code{node} and/or \code{node_td} function is used in conjunction with the \code{\link{empty_dag}} function to create this object.
+To generate data using the \code{\link{sim_from_dag}}, \code{\link{sim_discrete_time}} or \code{\link{sim_discrete_event}} functions, it is required to create a \code{DAG} object first. This object needs to contain information about the causal structure of the data (e.g. which variable causes which variable) and the specific structural equations for each variable (information about causal coefficients, type of distribution etc.). In this package, the \code{node} and/or \code{node_td} functions are used in conjunction with the \code{\link{empty_dag}} function to create this object.
 
 This works by first initializing an empty \code{DAG} using the \code{\link{empty_dag}} function and then adding multiple calls to the \code{node} and/or \code{node_td} functions to it using a simple \code{+}, where each call to \code{node} and/or \code{node_td} adds information about a single node that should be generated. Multiple examples are given below.
 
 In each call to \code{node} or \code{node_td} the user needs to indicate what the node should be called (\code{name}), which function should be used to generate the node (\code{type}), whether the node has any parents and if so which (\code{parents}) and any additional arguments needed to actually call the data-generating function of this node later passed to the three-dot syntax (\code{...}).
 
 \strong{\emph{\code{node} vs. \code{node_td}}}:
 
-By calling \code{node} you are indicating that this node is a time-fixed variable which should only be generated once. By using \code{node_td} you are indicating that it is a time-dependent node, which will be updated at each step in time when using a discrete-time simulation.
+By calling \code{node} you are indicating that this node is a time-fixed variable which should only be generated once. By using \code{node_td} you are indicating that it is a time-dependent node, which will be updated at each step in time when using a discrete-time simulation, or at event changes in discrete-event simulations.
 
-\code{node_td} should only be used if you are planning to perform a discrete-time simulation with the \code{\link{sim_discrete_time}} function. \code{DAG} objects including time-dependent nodes may not be used in the \code{\link{sim_from_dag}} function.
+\code{node_td} should only be used if you are planning to perform a discrete-time or discrete-event simulation with the \code{\link{sim_discrete_time}} or \code{\link{sim_discrete_event}} functions. \code{DAG} objects including time-dependent nodes may not be used in the \code{\link{sim_from_dag}} function.
 
 \strong{\emph{Implemented Root Node Types}}:
 
 Any function can be used to generate root nodes. The only requirement is that the function has at least one named argument called \code{n} which controls the length of the resulting vector. For example, the user could specify a node of type \code{"rnorm"} to create a normally distributed node with no parents. The argument \code{n} will be set internally, but any additional arguments can be specified using the \code{...} syntax. In the \code{type="rnorm"} example, the user could set the mean and standard deviation using \code{node(name="example", type="rnorm", mean=10, sd=5)}.
 
-For convenience, this package additionally includes four custom root-node functions:
+For convenience, this package additionally includes five custom root-node functions:
 
 \itemize{
   \item{"\link[=rbernoulli]{rbernoulli}": Draws randomly from a bernoulli distribution.}
   \item{"\link[=rcategorical]{rcategorical}": Draws randomly from any discrete probability density function.}
   \item{"\link[=rsample]{rsample}": Draws random samples from a given vector.}
+  \item{"\link[=rtexp]{rtexp}": Draws random values from a left-truncated exponential distribution.}
   \item{"\link[=rconstant]{rconstant}": Used to set a variable to a constant value.}
 }
 
@@ -89,6 +90,7 @@ Currently, the following node types are implemented directly for convenience to
 \itemize{
   \item{"\link[=node_time_to_event]{time_to_event}": A node based on repeatedly checking whether an event occurs at each point in time.}
   \item{"\link[=node_competing_events]{competing_events}": A node based on repeatedly checking whether one of multiple mutually exclusive events occurs at each point in time.}
+  \item{"\link[=node_next_time]{next_time}": A node that draws the time of the next event in discrete-event simulation.}
 }
 
 However, the user may also use any of the child node types in a \code{node_td} call directly. For custom time-dependent node types, please consult the associated vignette.
@@ -105,7 +107,7 @@ If the data generated by a child node is categorical (such as when using \code{n
 
 The name DAG (directed \strong{acyclic} graph) implies that cycles are not allowed. This means that if you start from any node and only follow the arrows in the direction they are pointing, there should be no way to get back to your original node. This is necessary both theoretically and for practical reasons if we are dealing with static DAGs created using the \code{node} function. If the user attempts to generate data from a static cyclic graph using the \code{\link{sim_from_dag}} function, an error will be produced.
 
-However, in the realm of discrete-time simulations, cyclic causal structures are perfectly reasonable. A variable \eqn{A} at \eqn{t = 1} may influence a variable \eqn{B} at \eqn{t = 2}, which in turn may influence variable \eqn{A} at \eqn{t = 3} again. Therefore, when using the \code{node_td} function to simulate time-dependent data using the \code{\link{sim_discrete_time}} function, cyclic structures are allowed to be present and no error will be produced.
+However, in the realm of discrete-time or discrete-event simulations, cyclic causal structures are perfectly reasonable. A variable \eqn{A} at \eqn{t = 1} may influence a variable \eqn{B} at \eqn{t = 2}, which in turn may influence variable \eqn{A} at \eqn{t = 3} again. Therefore, when using the \code{node_td} function to simulate time-dependent data using the \code{\link{sim_discrete_time}} or \code{\link{sim_discrete_event}} function, cyclic structures are allowed to be present and no error will be produced.
 
 }
 \note{

man/simDAG.Rd

@@ -12,9 +12,9 @@ This package aims to give a comprehensive framework to simulate static and longi
 
 \strong{\emph{What features are included in this package?}}
 
-This package includes two main simulation functions: the \code{\link{sim_from_dag}} function, which can be used to simulate data from a previously defined causal DAG and node information and the \code{\link{sim_discrete_time}} function, which implements a framework to conduct discrete-time simulations. The former is very easy to use, but cannot deal with time-varying variable easily. The latter is a little more difficult to use (usually requiring the user to write some functions himself), but allows the simulation of arbitrarily complex longitudinal data.
+This package includes three main simulation functions: the \code{\link{sim_from_dag}} function, which can be used to simulate data from a previously defined causal DAG and node information, the \code{\link{sim_discrete_time}} function, which implements a framework to conduct discrete-time simulations and the \code{\link{sim_discrete_event}} function for discrete-event simulations. The former is very easy to use, but cannot deal with time-varying variable easily. The latter two are a little more difficult to use (usually requiring the user to write some functions himself), but allow the simulation of arbitrarily complex longitudinal data in discrete and continuous time.
 
-Through a collection of implemented node types, this package allows the user to generate data with a mix of binary, categorical, count and time-to-event data. The \code{\link{sim_discrete_time}} function additionally enables the user to generate time-to-event data with, if desired, a mix of competing events, recurrent events, time-varying variables that influence each other and any types of censoring.
+Through a collection of implemented node types, this package allows the user to generate data with a mix of binary, categorical, count and time-to-event data. The \code{\link{sim_discrete_time}} and \code{\link{sim_discrete_event}} functions additionally enable the user to generate time-to-event data with, if desired, a mix of competing events, recurrent events, time-varying variables that influence each other and any types of censoring.
 
 The package also includes a few functions to transform resulting data into multiple formats, to augment existing DAGs, to plot DAGs and to plot a flow-chart of the data generation process.
 
@@ -26,15 +26,15 @@ Users should start by defining a \code{DAG} object using the \code{\link{empty_d
 
 \strong{\emph{When should I use \code{sim_from_dag} and when \code{sim_discrete_time}?}}
 
-If you want to simulate data that is easily described using a standard DAG without time-varying variables, you should use the \code{\link{sim_from_dag}} function. If the DAG includes time-varying variables, but you only want to consider a few points in time and can easily describe the relations between those manually, you can still use the \code{\link{sim_from_dag}} function. If you want more complex data with time-varying variables, particularly with time-to-event outcomes, you should consider using the \code{\link{sim_discrete_time}} function.
+If you want to simulate data that is easily described using a standard DAG without time-varying variables, you should use the \code{\link{sim_from_dag}} function. If the DAG includes time-varying variables, but you only want to consider a few points in time and can easily describe the relations between those manually, you can still use the \code{\link{sim_from_dag}} function. If you want more complex data with time-varying variables, particularly with time-to-event outcomes, you should consider using the \code{\link{sim_discrete_time}} or \code{\link{sim_discrete_event}} functions.
 
 \strong{\emph{What features are missing from this package?}}
 
 The package currently only implements some possible child nodes. In the future we would like to implement more child node types, such as more complex survival time models and extending the already existing support for multilevel modeling to other node types.
 
 \strong{\emph{Why should I use this package instead of the \pkg{simcausal} package?}}
 
-The \pkg{simcausal} package was a big inspiration for this package. In contrast to it, however, it allows quite a bit more flexibility. A big difference is that this package includes a comprehensive framework for discrete-time simulations and the \pkg{simcausal} package does not.
+The \pkg{simcausal} package was a big inspiration for this package. In contrast to it, however, it allows quite a bit more flexibility. A big difference is that this package includes a comprehensive framework for discrete-time and discrete-event simulations and the \pkg{simcausal} package does not.
 
 \strong{\emph{Where can I get more information?}}
 
@@ -52,9 +52,9 @@ The documentation pages contain a lot of information, relevant examples and some
 
 A separate (already peer-reviewed) article about this package has been provisionally accepted in the \emph{Journal of Statistical Software}. The preprint version of this article is available on arXiv (Denz and Timmesfeld 2025).
 
-\strong{\emph{I have a problem using the \code{sim_discrete_time} function}}
+\strong{\emph{I have a problem using the \code{sim_discrete_time} or \code{sim_discrete_event} function}}
 
-The \code{\link{sim_discrete_time}} function can become difficult to use depending on what kind of data the user wants to generate. For this reason we put in extra effort to make the documentation and examples as clear and helpful as possible. Please consult the relevant documentation pages and the vignettes before contacting the authors directly with programming related questions that are not clearly bugs in the code.
+The \code{\link{sim_discrete_time}} and \code{\link{sim_discrete_event}} functions can become difficult to use depending on what kind of data the user wants to generate. For this reason we put in extra effort to make the documentation and examples as clear and helpful as possible. Please consult the relevant documentation pages and the vignettes before contacting the authors directly with programming related questions that are not clearly bugs in the code.
 
 \strong{\emph{I want to suggest a new feature / I want to report a bug. Where can I do this?}}
 

man/sim_discrete_event.Rd

@@ -2,7 +2,7 @@
 \alias{sim_discrete_event}
 
 \title{
-Simulate Data from a \code{DAG} with Time-Dependent Variables using Discrete-Event Simulation
+Simulate Data from a \code{DAG} with Time-Dependent Variables in Continuous Time
 }
 \description{
 EXPERIMENTAL: Similar to \code{\link{sim_discrete_time}}, this function allows users to generate complex data with time-varying variables from a \code{DAG} defined using \code{\link{node}} and \code{\link{node_td}} calls. In contrast to \code{\link{sim_discrete_time}}, time is modelled as a continuous variable using a discrete-event simulation approach. See details.