Author: Michael Kammer
Date: 2024-12-03

# simdata: Technical documentation

#### Michael Kammer

#### 2024-12-03

# 1 Introduction

This document is intended to elaborate on the inner workings of the `simdata` package, for users who may wish to extend it for their purposes.

The `simdata` package is based on a very simple idea:

- the `simdesign` S3 class, and any concrete subclass implemented by the user, which provides a data generating mechanism, and stores all necessary data to simulate data from the data generating mechanism
- the `simulate_data` method for the `simdesign` class, which actually implements drawing from the data generating mechanism

Both key functionalities can be embellished by further features to adapt to the task of interest. How to do this is presented in the `Demo` vignette of the package. The package further provides some utilities around the core functionality, to assist in simulation tasks, but which are not essential to the usage of the package.

# 2 `simdesign` S3 class

The main class of this package is the `simdesign` S3 class. It is a list with class attribute `simdesign` and entries as defined in the documentation of the `simdesign` class.

## 2.1 Subclassing `simdesign`

A template for a constructor implementing a subclass for a specific simulation design is given by:

    # constructor takes any number of arguments arg1, arg2, and so on
    # and it must use the elipsis ... as final argument
    new_simdesign <- function(arg1, arg2, ...) {

        # define generator function in one argument
        generator = function(n) {
            # implement data generating mechanism
            # make use of any argument passed to the new_simdesign constructor
            # make sure it returns a two-dimensional array
        }

        # setup simdesign subclass
        # make sure to pass generator function and ...
        # all other information passed is optional
        dsgn = simdesign(
            generator = generator,
            arg1 = arg1,
            arg2 = arg2,
            ...
        )

        # extend the class attribute
        class(dsgn) = c("binomial_simdesign", class(dsgn))

        # return the object
        dsgn
    }

Examples for actual implementations are provided in the `Demo` vignette of this package.

# 3 Simulation of data

## 3.1 `simulate_data` method

The data generation in the `simulate_data` method follows a simple recipe. In principle, the method can be used without a `simdesign` object, but here we assume they are used together. In the following graphic, circular shapes denote functions.

1. Data is drawn from an initial distribution using the `generator` field (a function object) of the `simdesign` class.
   - Relevant input: the function stored in the `generator` field of the `simdesign`class, `n_obs` (number of observations), any further argument passed to `simulate_data` which is not specified in the documentation
   - Output: initial generated dataset `Z`
2. The initial data `Z` is transformed by one or several functions which are applied to the dataset.
   - Relevant input: `Z`, function stored in the `transform_initial` field of the `simdesign` class (can be implemented by using a `function_list`, see documentation of this package)
   - Default: `base::identity` is used to return the dataset `Z` unchanged
   - Output: final generated dataset `X`
3. Optional: the final data `X` can be post-processed before further usage.
   - Relevant input: `X`, functions stored in the `process_final` field of the `simdesign` object
   - Default: `base::identity` is used to return the dataset `X` unchanged
   - Output: post-processed dataset `X'`.

The final output of the method is a dataset (a matrix or data.frame depending on the data generating mechanism) which can be used in further analysis steps.

### 3.1.1 Implemented methods

`simulate_data` is a S3 method, which implements

- `simulate_data.default`: the default method doing all the actual work
- `simulate_data.simdesign`: calls `simulate_data.default` with appropriate parameters as stored in the `simdesign` object; the intended way to use this function

## 3.2 `simulate_data_conditional` function

Data can be simulated to conform to specific user-specified constraints. These constraints are implemented through a rejection function applied to a simulated dataset. Only datasets for which the function returns FALSE (i.e. not rejected) are returned. This is implemented by repeatedly calling `simulate_data` to obtain new instances of datasets from the data generating mechanism, either until the rejection function accepts the dataset, or until a maximum number of iterations was conducted. This process is depicted in the following diagram, in which circular shaps denote functions.

# 4 R session information

    ## R version 4.4.0 (2024-04-24 ucrt)
    ## Platform: x86_64-w64-mingw32/x64
    ## Running under: Windows 10 x64 (build 17763)
    ##
    ## Matrix products: default
    ##
    ##
    ## locale:
    ## [1] LC_COLLATE=C                    LC_CTYPE=German_Austria.1252
    ## [3] LC_MONETARY=German_Austria.1252 LC_NUMERIC=C
    ## [5] LC_TIME=German_Austria.1252
    ##
    ## time zone: Europe/Vienna
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] parallel  stats     graphics  grDevices utils     datasets  methods
    ## [8] base
    ##
    ## other attached packages:
    ##  [1] ggcorrplot_0.1.4.1  patchwork_1.2.0     dplyr_1.1.4
    ##  [4] fitdistrplus_1.1-11 survival_3.7-0      MASS_7.3-60.2
    ##  [7] doRNG_1.8.6         rngtools_1.5.2      doParallel_1.0.17
    ## [10] iterators_1.0.14    foreach_1.5.2       knitr_1.46
    ## [13] GGally_2.2.1        reshape2_1.4.4      ggplot2_3.5.1
    ## [16] simdata_0.4.1
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] sass_0.4.9         utf8_1.2.4         generics_0.1.3     tidyr_1.3.1
    ##  [5] NHANES_2.1.0       lattice_0.22-6     stringi_1.8.4      digest_0.6.35
    ##  [9] magrittr_2.0.3     evaluate_0.23      grid_4.4.0         RColorBrewer_1.1-3
    ## [13] mvtnorm_1.2-4      fastmap_1.2.0      Matrix_1.7-0       plyr_1.8.9
    ## [17] jsonlite_1.8.8     purrr_1.0.2        fansi_1.0.6        viridisLite_0.4.2
    ## [21] scales_1.3.0       codetools_0.2-20   jquerylib_0.1.4    cli_3.6.2
    ## [25] rlang_1.1.3        splines_4.4.0      munsell_0.5.1      withr_3.0.0
    ## [29] cachem_1.1.0       yaml_2.3.8         tools_4.4.0        colorspace_2.1-0
    ## [33] ggstats_0.6.0      vctrs_0.6.5        R6_2.5.1           lifecycle_1.0.4
    ## [37] stringr_1.5.1      pkgconfig_2.0.3    pillar_1.9.0       bslib_0.7.0
    ## [41] gtable_0.3.5       glue_1.7.0         Rcpp_1.0.12        highr_0.10
    ## [45] xfun_0.44          tibble_3.2.1       tidyselect_1.2.1   rstudioapi_0.16.0
    ## [49] farver_2.1.2       igraph_2.0.3       htmltools_0.5.8.1  rmarkdown_2.27
    ## [53] labeling_0.4.3     compiler_4.4.0