prov.annotate.on: Controlling Provenance Detail

In ProvTools/RDataTracker: Provenance Collector for R

Description

prov.annotate.on enables provenance collection for specific functions.

prov.annotate.off disables provenance collection for specified functions.

prov.set.detail sets the level of detail for the provenance to be collected.

prov.get.detail returns the current level of provenance detail.

prov.clear.detail clears the current value of provenance detail. The level of detail is then determined by parameters of prov.run or prov.init.

Usage

prov.annotate.on(fnames.on = NULL)

prov.annotate.off(fnames.off = NULL)

prov.set.detail(detail.level)

prov.get.detail()

prov.clear.detail()

Arguments

fnames.on	a list of one or more function names passed in as strings.
fnames.off	a list of one or more function names passed in as strings.
detail.level	level of detail to set (0-3)

Details

To allow provenance to be collected inside functions initially, the user calls prov.init or prov.run with TRUE for the annotate.inside.functions parameter. This results in provenance being collected inside all functions.

To get finer control over which functions are annotated, the user can call prov.annotate.on and prov.annotate.off. In prov.annotate.on, the user passes in a list of function names that should be annotated. Functions not listed are not annotated. If the user passes in NULL, all functions are annotated.

prov.annotate.on can be called multiple times. Each call adds more names to the list of annotated functions, continuing to annotate the previous functions in the list.

In prov.annotate.off, the user passes in a list of function names that should not be annotated. Functions not listed are not annotated. If the user passes in NULL, all functions are annotated.

prov.annotate.off can be called multiple times. Each call adds more names to the list of unannotated functions.

The level of detail of provenance can be set using the annotate.inside.functions, max.loops and snapshot.size parameters of prov.run and prov.init. It can also be set using prov.set.detail, which will impact the future executions of prov.run and prov.init. The detail level can take on the following values:
0 = no internal provenance, no snapshots (the prov.init and prov.run defaults).
1 = provenance inside functions and if-statements and 1 iteration of each loop, snapshots limited to 10k each.
2 = provenance inside functions and if-statements and up to 10 iterations of each loop, snapshots limited to 100k each.
3 = provenance inside functions and if-statements and all iterations of each loop, complete snapshots.

Value

prov.get.detail returns the current level of provenance detail (0-3). Returns NULL if prov.set.detail was not previously called, or has been cleared.

See Also

prov.init and prov.run

Examples

prov.set.detail(1)
prov.init()
prov.annotate.on("f")
prov.annotate.off("g")
f <- function (x) {
  if (x < 0) return (0)
  else return (x - 1)
}
g <- function (x) {
  return (x - 1)
}
f (3)
g (-3)
prov.quit()

ProvTools/RDataTracker documentation built on May 9, 2019, 3:29 a.m.