parSim: Parallel Simulator

In parSim: Parallel Simulator

Parallel Simulator

Description

The function parSim takes a set of conditions and an R base::expression and returns a base::data.frame with simulation results. The parSim function is based on dplyr::dplyr functions for handling the results, and the parabar::parabar package for handling parallelization and progress tracking.

Usage

parSim(
    ...,
    expression,
    replications = 1,
    reps,
    exclude = NULL,
    export = NULL,
    packages = NULL,
    write = FALSE,
    name,
    nCores = 1,
    progress = TRUE,
    env = parent.frame()
)

Arguments

...	Any number of R vectors representing the simulation conditions. For example, if you want to vary the sample size between ⁠{100, 250, 1000}⁠ and a regression slope between ⁠{0, 0.5, 1}⁠, you can assign the first two arguments as sample_size = c(100, 250, 1000) and beta = c(0, 0.5, 1).
expression	An R expression that uses the simulation conditions as variable names. For example, if the ... arguments are used to define sample_size = c(100, 250, 1000), then, within the context of expression, you can access the sample_size variable, which may hold a value of 100, 250, or 1000 depending on the simulation condition. The expression must collect and output the results as a named base::list or a base::data.frame. See the the Examples section for more details.
replications	An integer representing the number of times each condition will be replicated. Please ensure that an adequate number of simulations is used (i.e., the more the better). Defaults to 1.
reps	Deprecated alternative to 'replications'
exclude	A list of logical calls indicating the simulation conditions to exclude cases, written as formula. For example, exclude = sample_size == 100 | beta == 0 will exclude all cases where sample_size is equal to 100 or beta is equal to 0. Similarly, exclude = sample_size == 100 & beta == 0 will exclude all cases where sample_size is equal to 100 and beta is equal to 0. Defaults to NULL (i.e., no simulation conditions are excluded).
export	A character string containing the names of the objects to be exported to the parallel backend. This argument is only relevant when using parallel execution (i.e., nCores > 1). Defaults to NULL (i.e., indicating that no objects are to be exported).
packages	A character vector containing the names of the packages to be loaded on the parallel backend. For example packages = c("bootnet", "qgraph"). This argument is only relevant when using parallel execution (i.e., nCores > 1). Defaults to NULL (i.e., indicating that no packages are to be loaded).
write	Logical, should the results be written to a file? If write = TRUE and name is not provided, results are saved to a temporary file (i.e., created using base::tempfile). If write = TRUE and name is provided, results are saved to name.txt. If write = FALSE the results are not saved. Upon saving the results, a message is printed to the console indicating the location of the saved file. Defaults to FALSE.
name	A character string specifying the base name of the file to save the results to (a .txt extension is appended automatically). Only used when write = TRUE.
nCores	An integer value indicating the number of cores to use for parallel execution. Setting this argument to 1 implies that the simulation conditions are run sequentially. Using a value greater than 1 implies that the simulation conditions are run in parallel using a parabar::parabar backend with the specified number of cores. Defaults to 1.
progress	A logical value indicating whether to show a progress bar while running the simulation. Defaults to TRUE.
env	The environment from which to export variables specified in the export argument. Defaults to parent.frame() (i.e., the caller's environment). This is relevant when calling parSim from within a function, where variables to export may not be in the global environment.

Details

The R base::expression should use object names assigned as conditions, and should return a named list with single values, or a base::data.frame. If you want to output more than one row of results per condition, you may return a base::data.frame with multiple rows. When running the simulation conditions in parallel, note that all packages needed should be loaded via the packages argument and all external objects used within the expression should be exported via the export argument.

Value

The parSim function returns a base::data.frame with the results of every iteration as a row.

See Also

bootnet::bootnet, parabar::par_lapply, and parabar::configure_bar.

Examples

# Determine a function to evaluate for each simulation condition.
bias <- function(x, y) {
    # Perform some computation.
    result <- abs(x - y)

    # Return the result.
    return(result)
}

# Run the simulation.
results <- parSim(
    # The simulation conditions.
    sample_size = c(50, 100, 250),
    beta = c(0, 0.5, 1),
    sigma = c(0.25, 0.5, 1),

    # The expression to evaluate for each simulation condition.
    expression = {
        # Generate the data.
        x <- rnorm(sample_size)
        y <- beta * x + rnorm(sample_size, sigma)

        # Fit the model.
        fit <- lm(y ~ x)

        # Compute the relevant quantities.
        beta_estimate <- coef(fit)[2]
        r_squared <- summary(fit)$r.squared
        bias <- bias(beta, beta_estimate)

        # Return in a compatible format.
        list(
            beta_estimate = beta_estimate,
            r_squared = r_squared,
            bias = bias
        )
    },

    # The number of replications.
    replications = 10,

    # The conditions to exclude.
    exclude = sample_size == 50 | beta <= 0.5,

    # The variables to export.
    export = c("bias"),

    # No packages are required for export.
    packages = NULL,

    # Do not save the results.
    write = FALSE,

    # Execute the simulation on a single core.
    nCores = 1,

    # Show the progress bar.
    progress = TRUE
)

# Print the head of the results.
head(results)


# Configure the progress bar.
configure_bar(
    type = "modern",
    format = "[:bar] [:percent] [:elapsed]",
    show_after = 0.15
)

# Run the simulation again with more cores and the updated progress bar.
results <- parSim(
    # The simulation conditions.
    sample_size = c(50, 100, 250),
    beta = c(0, 0.5, 1),
    sigma = c(0.25, 0.5, 1),

    # The expression to evaluate for each simulation condition.
    expression = {
        # Generate the data.
        x <- rnorm(sample_size)
        y <- beta * x + rnorm(sample_size, sigma)

        # Fit the model.
        fit <- lm(y ~ x)

        # Compute the relevant quantities.
        beta_estimate <- coef(fit)[2]
        r_squared <- summary(fit)$r.squared
        bias <- bias(beta, beta_estimate)

        # Return in a compatible format.
        list(
            beta_estimate = beta_estimate,
            r_squared = r_squared,
            bias = bias
        )
    },

    # The number of replications.
    replications = 1000,

    # The conditions to exclude.
    exclude = sample_size == 50 | beta <= 0.5,

    # The variables to export.
    export = c("bias"),

    # No packages are required for export.
    packages = NULL,

    # Save the results to a temporary file.
    write = TRUE,

    # Execute the simulation in parallel.
    nCores = 2,

    # Show the progress bar.
    progress = TRUE
)

# Print the tail of the results.
tail(results)

parSim documentation built on Feb. 26, 2026, 5:06 p.m.