Running simulations in skeleSim

In skeleSim: Genetic Simulation Engine

This vignette focuses on what happens when you push the "Run Simulation" button on the Actions tab.

Setting up and running simulations are asynchronous activities

Simulations, particularly forward-time simulations, are time consuming. skeleSimGUI() was designed so that while a simulation is running, a user can edit the same simulation parameters to set up a new run, open or create a completely different simulation parameter set, or visualize the results of a previously run simulation.

Each simulation runs in its own independent R session

This asynchrony is achieved by spawning a new R process for each simulation. In addition, skeleSimGUI() does not wait for the newly spawned process to finish. While this prevents the interface from halting during simulations, it does require the user to look for output files in the "root simulation directory".

File inputs and outputs

The newly spawned R process executes in the "root simulation directory" specified on the Actions tab. During a simulation, working files are written to a subdirectory specified on the general parameters tab. Changing this subdirectory tab allows a user to launch as many simulations as their computer can accommodate and the different simulations will not write over each other's files. The input, output, and R code that uses and produces them is saved to the "root simulation directory".

File names

the filename prefix format for all skeleSim files produced during simulation has the following format: 'title.date.hhmm.ms' where 'title' is specified on the general configuration tab and the rest are calculated from the system clock.

• The R file has the prefix above with ".script.R" appended. It contains an R script to run this particular simulation
• The input parameter file has ".params.rdata" appended
• Simulation results are stored in a file with ".skeleSim.out.rdata"
• log files should be stored in a file with .Rout as an extension

R script

The R script is a self-contained R script that loads the appropriate libraries, loads data runs a simulation and analysis and then saves the results. Here is an example. The comments have been added to provide clarity. The skelesim class saved in the input and output files is called 'ssClass'

library(skeleSim)  
getwd()
setwd('/home/astrand/tmp') # this is the "root simulation directory" set on the actions tab
getwd()
load('title.20160413.1623.1182.params.rdata') #input data
ls()
ssClass <- runSim(ssClass) #simulate and analyze
save(ssClass, file = 'title.20160413.1623.1182.skeleSim.out.rdata') #save the output

input file

The input file is an R binary format file that contains a skeleSim class object. This file is usually created by the skeleSimGUI() interface, but any process that creates a valid object could create this file.

output file

The output file has the exact same structure as the input file. Some slots that are NULL in a newly created input file have results in them, most importantly the slot "analysis.results" which contains 3 dimensional arrays that hold results of summary statistics calculations per simulation rep.

Using the output

The output file can be read into the skeleSimGUI() and the results can be visualized. Furthermore, this also reads simulation parameters into a skeleSimGUI() session where they can be altered and a new simulation run.

Running a simulation 'by hand'

Once skeleSimGUI() runs a simulation the relevant R script like the one above is available on disk. All the user has to do is source it into an R session and the simulation will run again.

source('title.20160413.1623.1182.script.R')

An alternative would be to load the params file by hand and run the simulation:

load('title.20160413.1623.1182.params.rdata')
ssClass <- runSim(ssClass) #run simulation.  now results are stored in [e-mail]

Troubleshooting

Common problems include:

1. Not specifying the root simulation directory Depending on the operating system, your results will appear in some form of your home directory which might be an unexpected location

2. Simulation not completing Because it is happening in the simulator softwares, this one is much more difficult to resolve. You know there is a problem when no output file appears in the simulation directory. An obvious first step to troubleshoot is to check te log file. Second, source the R script into a running R session and look for error messages. In addition, the simulation subdirectory might include information on what happened. You can also use the "save input files for each scenario" button on the actions tab. This will create an input file for a simulator and you may be able to run that file and look for errors.

skeleSim documentation built on May 2, 2019, 5:16 a.m.