# Get Started with sims

sims is an R package to generate datasets from JAGS or R code for use in simulation studies.

## Simulating as `nlists` Objects

By default, `sims_simulate()` returns the simulated datasets in the form of an nlists object.

    library(sims)
    set.seed(10)
    sims_simulate("a <- runif(1)", nsims = 2L)
    #> $a
    #> [1] 0.2213763
    #>
    #> an nlists object of 2 nlist objects each with 1 numeric element

## Saving as `.rds` Files

If, however, `save = TRUE` then each nlist object is saved as an `.rds` file in `path`.

    set.seed(10)
    sims_simulate("a <- runif(1)", nsims = 2L, save = TRUE, path = tempdir(), exists = NA)
    #> [1] TRUE
    sims_data_files(tempdir())
    #> [1] "data0000001.rds" "data0000002.rds"

### Importing `.rds` Files

The datasets in the `.rds` files can be imported as an `nlists` object using `sims_data()`.

    sims_data(tempdir())
    #> $a
    #> [1] 0.2213763
    #>
    #> an nlists object of 2 nlist objects each with 1 numeric element

### Adding `.rds` Files

The values including the `.Random.seed` (not printed) that were used to generate the datasets are saved in `.sims_args.rds` which can be imported using `sims_info()`.

    sims_info(tempdir())[1:5]
    #> $code
    #> [1] "a <- runif(1)"
    #>
    #> $constants
    #> an nlist object with 0 numeric elements
    #>
    #> $parameters
    #> an nlist object with 0 numeric elements
    #>
    #> $monitor
    #> [1] "a"
    #>
    #> $nsims
    #> [1] 2

The fact that the arguments to `sims_simulate()` are saved to file allows additional `.rds` datasets to be generated using `sims_add()`.

    sims_add(tempdir(), nsims = 3L)
    #> [1] "data0000003.rds" "data0000004.rds" "data0000005.rds"
    sims_data_files(tempdir())
    #> [1] "data0000001.rds" "data0000002.rds" "data0000003.rds" "data0000004.rds"
    #> [5] "data0000005.rds"

### Copying `.rds` Files

If the user wishes to duplicate the datasets then they can either regenerate them by specifying a different path but the same seed (using `set.seed()`). Alternatively, they can copy the existing `.sims.rds` and datasets files to a new directory using `sims_copy()`

    sims_copy(path_from = tempdir(), path_to = paste0(tempdir(), "_copy"))
    #> [1] "data0000001.rds" "data0000002.rds" "data0000003.rds" "data0000004.rds"
    #> [5] "data0000005.rds"

### Checking `.rds` Files

A user can check that all the datasets specified in `.sims.rds` are present using `sims_check()`.

    sims_check(path = paste0(tempdir(), "_copy"))

    file.remove(file.path(paste0(tempdir(), "_copy"), "data0000005.rds"))
    #> [1] TRUE

    sims_check(path = paste0(tempdir(), "_copy"))
    #> Error:
    #> ! Number of data files (4) does not match number of simulations (5).

## Parallelization

Parallelization is implemented using the future package.

To use all available cores on the local machine simply execute the following code before calling `sims_simulate()`.

    library(future)
    plan(multisession)

    set.seed(10)
    sims_simulate("a <- runif(1)", nsims = 2L)
    #> $a
    #> [1] 0.2213763
    #>
    #> an nlists object of 2 nlist objects each with 1 numeric element

## Progress

Progress is reported using the progressr package as follows.

    library(progressr)
    with_progress(sims_simulate("a <- runif(1)", nsims = 1000L))
    #> $a
    #> [1] 0.5248719
    #>
    #> an nlists object of 1000 nlist objects each with 1 numeric element