track.manage: Manage how objects are handled in a tracking session

Description Usage Arguments Details Value Author(s) See Also Examples

Description

Functions to start and stop tracking objects, remove them, load objects from RData files, and manage cached and saved copies of objects. These functions should not be needed in plain vanilla use of the track package.

For an introduction to the track package, see Overview (?track.intro).

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
track(expr, pos = 1, envir = as.environment(pos), list = NULL,
        pattern = NULL, glob = NULL, exclude = TRUE)
track.assign(x, value, pos = 1, envir = as.environment(pos), flush = TRUE)
untrack(expr, pos = 1, envir = as.environment(pos), list = NULL,
        pattern = NULL, glob = NULL, all = FALSE, keep.in.db = FALSE)
track.remove(expr, pos = 1, envir = as.environment(pos), list = NULL,
        pattern = NULL, glob = NULL, all = FALSE, force = TRUE)
track.save(expr, pos = 1, envir = as.environment(pos), list = NULL,
        pattern = NULL, glob = NULL,
        all = missing(expr) && missing(list) && missing(pattern) && missing(glob))
track.resave(expr, pos = 1, envir = as.environment(pos), list = NULL,
        pattern = NULL, glob = NULL,
        all = missing(expr) && missing(list) && missing(pattern) && missing(glob))
track.flush(expr, pos = 1, envir = as.environment(pos), list = NULL,
        pattern = NULL, glob = NULL,
        all = missing(expr) && missing(list) && missing(pattern) && missing(glob),
        force = FALSE)
track.forget(expr, pos = 1, envir = as.environment(pos), list = NULL,
        pattern = NULL, glob = NULL, all = FALSE)
track.load(files, pos = 1, envir = as.environment(pos), list = NULL,
        pattern = NULL, glob = NULL, cache = FALSE, clobber = FALSE,
        time.of.file = TRUE, warn = TRUE)

Arguments

expr

An unquoted variable name

pos

The search path position of the environment being tracked (default is 1 for the global environment)

envir

The environment being tracked. This is an alternate way (to the use of pos=) of specifying the environment being tracked, but should be rarely needed.

list

A character vector of variable names to operate upon

pattern

A regular expression specifying variable names to operate upon

glob

A regular expression specifying variable names to operate upon

all

If TRUE, operate upon all elegible variables. The default is FALSE for functions that can change data, and TRUE for functions that merely control whether data is in memory or file or both.

exclude

Controls exclusion of particular variables by pattern matching against a vector of regular expressions in the autoTrackExcludePattern option value. If exclude==TRUE (the default), exclude variables that match. If exclude==FALSE, ignore the exclusion patterns.

keep.in.db

If TRUE, the variable is left in the tracking database, though the link to it is broken (it becomes masked)

files

A vector of names of RData files (any file saved by save())

cache

TRUE or FALSE indicating whether to keep the tracked object cached in memory

clobber

TRUE or FALSE indicating whether to overwrite existing objects of the same name

force

If TRUE, for track.remove remove orphaned tracked variables; for track.flush flush out variables that would normally be kept in cache.

time.of.file

If TRUE, use the access times on the file to populate the access time fields in the tracking summary.

warn

If TRUE, issue warnings about object not acted upon.

x

A variable name, as a character vector of length 1

value

The value to assign

flush

Logical value, specifying whether to flush the assigned object out of memory

Details

These functions are executed for their side effects:

The variables to be acted upon are specified either in expr (a variable name, unquoted) or list (character vector containing names of variables), or by regular expression pattern or shell pattern glob. If no specification is given, all variables are acted upon.

Value

The value returned from these functions is invisible and typically contains the names of objects acted upon.

track:

a character vector containing the names of objects added to the tracking environment

untrack, track.remove, track.save, track.flush, track.forget, track.rescan:

a character vector containing the names of objects in the tracking environment that were acted upon

track.load:

a list with two components:

  • loaded: names of objects that were loaded from file

  • skipped: names of objects in file that were not loaded

Author(s)

Tony Plate <tplate@acm.org>

See Also

Overview and design of the track package.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
##############################################################
# Warning: running this example will cause variables currently
# in the R global environment to be written to .RData files
# in a tracking database on the filesystem under R's temporary
# directory, and will cause the variables to be removed temporarily
# from the R global environment.
# It is recommended to run this example with a fresh R session
# with no important variables in the global environment.
##############################################################

library(track)
track.start(dir=file.path(tempdir(), 'rdatadir5'))
x <- 33
X <- array(1:24, dim=2:4)
Y <- list(a=1:3,b=2)
X[2] <- -1
track.summary(time=0, access=1, size=FALSE)
y1 <- 2
y2 <- 3
z1 <- 4
z2 <- 5
z3 <- 6
untracked()
track.summary(time=0, access=1, size=FALSE)
ls(all=TRUE)
track.stop(pos=1)
ls(all=TRUE)
a <- 7
b <- 8
save(list=c("a", "b"), file=file.path(tempdir(), "ab.rda"))
remove(list=c("a", "b"))
track.start(dir=file.path(tempdir(), 'rdatadir5'))
track.summary(time=0, access=1, size=FALSE)
track.load(file.path(tempdir(), "ab.rda"))
track.summary(time=0, access=1, size=FALSE)
track.status()
# Would normally not call track.stop(), but do so here to clean up after
# running this example.
track.stop(pos=1, keepVars=TRUE)

track documentation built on May 2, 2019, 10:22 a.m.