Using provenance to view variable values

During debugging, a programmer commonly wants to know the values of variables used in the program. Typically, the programmer either inserts print statements or sets breakpoints in order to view the variable values. When debugging with provenance, the user can instead look up the values in the recorded provenance without rerunning the program.

The provDebugR package offers several functions that allow examining variables values:

  • debug.line shows the values of variables used and set on a specific line.
  • debug.state shows the values of all variables immediately following execution of a specific line
  • debug.variable shows all values that a variable took on during the execution of the script
  • debug.view uses the view panel to display variable values, which is more convenient for larger values like data frames.

These functions may be called only after initialising the debugger using either prov.debug, prov.debug.run, or prov.debug.file.

debug.line

For each line number queried, debug.line returns a data frame containing information about the data that the procedure in that line inputs and outputs.

Each data frame contains the following columns:

  • name The name of the variable
  • value The value of the variable, possibly abbreviated
  • container The type of the container of the data, such as list, data frame, etc.
  • dimension The size of the container.
  • type The data type(s) contained within the container.

Usage

The function signature for debug.line is:

debug.line(..., script.num = 1, all = FALSE)

The parameters of this function are:

  • ... The line numbers to be queried
  • script.num The script numbers to be queried. Defaults to script number 1 (main script). If script.num == "all", the main script and all sourced scripts will be queried.
  • all If TRUE, the inputs and outputs for all lines in all scripts will be returned.

In the case of multiple queries, only 1 script number may be queried per function call.

For example:

prov.debug.run("myScript.R")
debug.line(5)
debug.line(all = TRUE)
debug.line(5, 10, script.num = 2)
debug.line(3, script.num = "all")

Example

Let myScript.R be the following:

x <- 1:3
y <- c("a", "b", "c")
xy <- data.frame(x, y, stringsAsFactors = FALSE)
x

The result for debug.line(3) is:

Results for:
  startLine scriptNum scriptName                                             code
1         3         1 myScript.R xy <- data.frame(x, y, stringsAsFactors = FALSE)

$`1`
$`1`$input
  name       value container dimension      type
1    x       1 2 3    vector         3   integer
2    y "a" "b" "c"    vector         3 character

$`1`$output
  name     value  container dimension               type
1   xy Row 1 1 a data_frame       3,2 integer, character

Variables x and y are listed in the ‘input’ table as they are used in the procedure.

Variable xy is listed in the ‘output’ as the result from the procedure is assigned to that variable.

If the line has only inputs or outputs, an NA will be put in the place of the data frame with no data nodes listed.

If multiple lines are queried, the results for each line will be bound into a list.

debug.state

For each queried line, debug.state returns a data frame showing the state at that line, after it has been executed.

Each data frame contains the following columns:

  • name The name of each variable.
  • value The value of each variable.
  • container The type of the container of each variable.
  • dimension The size of the container.
  • type The data type(s) contained within the container.
  • scriptNum The script number associated where the variable was assigned the value.
  • scriptName The name of the script in which the variable was assigned the value.
  • startLine The line number in which the variable was assigned the value.

If no paramters are given, debug.state will return the state at the end of execution.

Usage

The function signature for debug.state is:

debug.state(..., script.num = 1)

The parameters of this function are:

  • ... The line numbers to be queried.
  • script.num The script number of the queried line numbers. This is ignored if no line numbers are given. If script.num == "all", the main script and all sourced scripts will be queried. Defaults to script number 1 (the main script).

For example:

prov.debug.run("myScript.R")
debug.state()
debug.state(5)
debug.state(10, 20, script.num = 2)
debug.state(5, script.num = "all")

Examples

Let myScript.R be the following:

a <- "one"
a <- 2L

b <- 3L
b <- "four"

When there are no parameters, debug.state returns the state at the end of execution.

Therefore, the result for debug.state() is:

State at the end of execution:
$`1`
  name  value container dimension      type scriptNum scriptName startLine
1    a      2    vector         1   integer         1 myScript.R         2
2    b "four"    vector         1 character         1 myScript.R         5

When a line number is passed in, debug.state returns the state after the queried line has been executed.

For example, the result for debug.state(4) is:

Results for:
  startLine scriptNum
1         4         1

$`1`
  name value container dimension    type scriptNum scriptName startLine
1    a     2    vector         1 integer         1 myScript.R         2
2    b     3    vector         1 integer         1 myScript.R         4

When multiple lines are queried, the results for each line are bound into a list.

debug.variable

For each variable queried, debug.variable returns a data frame containing a row for each time that the variable is assigned.

The data frame contains the following columns: * value The value of the variable. * container The type of the container of the variable. * dimension The size of the container. * type The data type(s) contained within the container. * scriptNum The script number where the assignment occurred * scriptName The name of the script where the assignment occurred * startLine The line number where the assignment occurred * code The line of code that did the assignment

Usage

The function signature for debug.variable is:

debug.variable(..., val.type = "all", script.num = "all", all = FALSE)

The parameters of this function are:

  • ... The variable names to be queried.
  • val.type If not “all”, this filters the results to contain only instances where the valType (container or type) has the queried type.
  • script.num The script number of the queried variables. Defaults to “all”.
  • all If TRUE, results for all variables of the specified script will be returned.

Only 1 script number and/or valType may be queried per function call.

For example:

prov.debug.run("myScript.R")
debug.variable(x)
debug.variable(all = TRUE)
debug.variable("a", b, "x", val.type = "logical")
debug.variable("a", "b", x, script.num = 3)

Example

Let myScript.R be the following:

a <- "one"
a <- "two"
a <- 1L
a <- 2L

b <- 3L
b <- 4L
b <- "five"

The result for debug.variable("a") is:

$a
  value container dimension      type scriptNum scriptName startLine       code
1 "one"    vector         1 character         1 myScript.R         1 a <- "one"
2 "two"    vector         1 character         1 myScript.R         2 a <- "two"
3     1    vector         1   integer         1 myScript.R         3    a <- 1L
4     2    vector         1   integer         1 myScript.R         4    a <- 2L

debug.view

debug.view displays the contents of each file or variable queried. For snapshots or files with the file extension of .csv or .txt, the data will be loaded into the debugger environment before it is viewed. Otherwise, the data will be viewed using the system’s default program for that type of file.

Additionally, a data frame showing what the function has opened will be returned, which contains the following columns:

  • name The name of the variable or file being viewed.
  • startLine The line number where the variable was assigned, or the file was read or written.
  • scriptNum The script number where the variable was assigned, or the file was read or written.
  • scriptName The name of the script where the variable was assigned, or the file was read or written.
  • title The title of the variable or file as it appears in the view panel
  • notes Will display PARTIAL if the variable is a snapshot representing a partial value, such as part of a data frame. See the documentation on rdtLite to learn more about snapshots. It will also indicate if
    a file is not found. NA indicates there are no special notes.

Usage

The function signature for debug.view is:

debug.view(..., start.line = "all", script.num = "all")

The parameters of this function are: * ... The variable names or file names to be queried. If omitted, all variables and files are displayed. * start.line The line number of the queried variables or files. * script.num The script number of the queried variables or files.

For example:

prov.debug.run("myScript.R")
debug.view()
debug.view(x)
debug.view("x", y, start.line = 5, script.num = 2)