Return a summary of the basic properties of tracked objects

Share:

Description

Return a summary of the basic properties of tracked objects: name, class, size, dimensions (if any), and creation, modification and access times.

Usage

1
2
3
4
5
track.summary(expr, pos = 1, envir = as.environment(pos), list = NULL, pattern = NULL,
        glob = NULL, all.names = FALSE,
        times = track.options("summaryTimes", envir=envir)[[1]],
        access = track.options("summaryAccess", envir=envir)[[1]],
        size=TRUE, cache=FALSE, full=FALSE)

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 summarize

pattern

: A regular expression specifying variable names to summarize

glob

: A regular expression specifying variable names to summarize

all.names

: should names beginning with a period be included (like all.names in ls)

times

: An integer 0..3 specifying how many time columns to return (in order of: modify, create, access)

access

: An integer 0..3 specifying how many access-count columns to return for each writes and accesses (0=none, 1=total, 2=prior and current session, 3=prior, current session and total)

size

: (logical) include the size column? (The values in this column are system dependent, so make it easy to exclude so that test output is constant across systems.)

cache

: (logical) include the cache column?

full

: (logical) include all the optional columns?

Details

Returns part or all of the cached summary data. There is one row per object. Only tracked objects appear in the summary.

Value

The value returned is a dataframe that summarizes the specified objects. This function does not create any output itself – the auto-printing of the returned value is the visible output. The data frame has one row for each object (rownames are the object names) and some of the following columns:

class:

(character) from class() (if class(obj) has more than one component, all components are appended separated by commas, if class(obj) returns a zero-length result, the value is "?")

mode:

(character) from mode()

extent:

(character) from dim() or length(), with double brackets if the object is a list (will contain "(error)" if dim(obj) causes an error)

length:

(integer) from length() (will be NA if length(obj) causes an error)

size:

(integer) from object.size()

cache:

(character): Indicates whether the objected should always be kept cached. Possible values are

yes, no:

Automatically determined from track.options("alwaysCache") (object names) or track.options("alwaysCacheClass") (object classes); re-evaluated when object changes

fixedyes, fixedno:

Always do this; don't re-evaluate when object changes. This is intended to allow manually setting this for each object if desired, but as of version 1.0.9 no way for the user to do this safely has been provided.

modified:

most recent modification time

created:

time object created

read:

most recent modification time

A:

(logical) Accuracy of times: TRUE if object summary has been maintained since object was first tracked; FALSE if the object summary was lost at some point and then recreated

ES:

(integer) sessions alive

SR:

(integer) num reads this session

SW:

(integer) num writes this session

PR:

(integer) total reads prior to this session

PW:

(integer) total writes prior to this session

TR:

(integer) total reads

TW:

(integer) total writes

Which columns are present depends on the arguments times, access, and size.

The reason for the class column containing all classes of the object separated by commas is that extracting the most informative class label is not simple, for example, the class of an object returned by glm() is c("glm", "lm") (most informative first), while the class of an object returned by Sys.time() is c("POSIXt", "POSIXct") (most informative last).

Note

The object summary data is maintained in an object called .trackingSummary kept in the tracking environment. It is not visible on the search path.

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
##############################################################
# 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(), 'rdatadir11'))
x <- 33
X <- array(1:24, dim=2:4)
Y <- list(a=1:3,b=2)
X[2] <- -1
y1 <- 2
y2 <- 3
track.summary()
track.summary(time=0, access=1, size=FALSE)
track.summary(X)
track.summary(list=c("x", "X"))
track.summary(pattern="[xX]")
# Would normally not call track.stop(), but do so here to clean up after
# running this example.
track.stop(pos=1, keepVars=TRUE)