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 linedebug.variable
shows all values that a variable took on
during the execution of the scriptdebug.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
.
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 variablevalue
The value of the variable, possibly
abbreviatedcontainer
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.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 queriedscript.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")
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.
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.
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")
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.
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
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)
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
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 panelnotes
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 ifThe 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)