Debugging

Debugging with SpaDES

Eliot J. B. McIntire and Alex M. Chubaty Updated October 5, 2020

Debugging in R and SpaDES can work in several ways. These include the core of R and RStudio tools, as well as several options that are SpaDES specific.

Built-in R and RStudio default traceback and error inspector.

• See debugging with RStudio.

Simulation debugging using browser()

Insert a browser() call anywhere in your module, which allows you to step through your module code. See ?browser for more on this. This allows the user to enter directly into the module code as it is running. After inserting a browser() call, remember to save the R script and rerun the simInit( ) call so that R knows about the browser() call that has been added.

See also ?SpaDES.core::restartSpades for speeding up this type of debugging.

Simulation debugging using the debug argument

The spades function takes an argument, debug. See ?spades. Currently, this can take several values, specifically, logical, character, list of logical or characters.

This approach is useful during spades() calls but (obviously) not during simInit().

debug = TRUE

This will output to the console some current event details as it is executing. This is relatively fast and has little impact on simulation speed. This can be helpful when trying to identify where in the bug is located in the simulaion event chain.

spades(mySim, debug = TRUE)

debug = functionName

If a function is passed to debug, then it will be applied to the simList. So, any simList accessor, such as 'time', 'objects' etc. will be output as each event is executed.

spades(mySim, debug = 'objects')

debug = "simList"

This will output the entire simList as each event is executed.

debug = "character string with a ( somewhere (indicating it includes a function call)"

This will be evaluated by the R interpreter, inside a context where there access to the simList, using the name sim.

spades(mySim, debug = "paste0('Time: ', time(sim), ', Number of Events so far: ', NROW(completed(sim)))")

debug = moduleName or debug = eventType

The code will enter into a browser (i.e., break into the code) allowing interactive work every time that module or event is called. Furthermore, with clever use of the interactive tools in Rstudio in the debugger mode (e.g., you can advance one line at a time, or enter into deeper functions, etc.), or just using the key shortcuts (see ?browser).

Example: spades(mySim, debug = "caribouModule") # module debugging -- will do all events within the "caribouModule" Example: spades(mySim, debug = "init") # event debugging -- will do all modules with an "init" event

spades(mySim, debug = "wolfAlps")

# Then use keyboard shortcuts:
#  n for next line
#  s for step into a function
#  Enter for repeat previous keyboard shortcut

See also https://spades-core.predictiveecology.org/reference/spades.html#debug for additional debug options and how to log simulation outputs to file.