track.rebuild {trackObjs} | R Documentation |
Rebuild database information (the file map, and/or the object summary) for objects in an active tracking environment, or for saved objects in a tracking directory.
track.rebuild(pos = 1, envir = as.environment(pos), dir = NULL, fix = FALSE, level=c("missing", "all"), trust=c("unspecified", "environment", "db"), verbose=1, RDataSuffix=NULL, dry.run=TRUE, replace.wd=TRUE, use.file.times=TRUE)
pos |
The position of the environment to which the tracking database to rebuild is linked (for active tracking databases. |
envir |
The tracked environment for which to rebuild the tracking database (for active tracking databases. |
dir |
The directory where the tracking database is stored (for tracking databases not currently active. |
fix |
If TRUE , try to fix various problems such as
illegal file names by renaming files or moving unusable
RData files to a 'quarantine' directory. If fix=TRUE and
dry.run=TRUE , changes will be reported but not made. |
level |
If "missing" , rebuild only missing information, if
"all" , rebuild information for all objects. |
trust |
When rebuilding an active tracking database, and there are conflicts between the data in the environment versus that in files, which should be trusted? |
verbose |
Controls number of messages about progress |
RDataSuffix |
What suffix should be used for RData files? (Usually worked out automatically.) |
dry.run |
If TRUE , no data objects in R or files on disk
are changed: the return value is a list containing the rebuilt file map and
the rebuilt object summary. If FALSE , objects in R
environments and files on disk can be changed. The default is
TRUE to guard against changing things when it would have been
better not to have changed things, but this default may change in future. |
replace.wd |
If TRUE , file paths in diagnostic output are
printed starting with "./" where possible – this makes comparisons
of test output more portable. |
use.file.times |
If TRUE , file creation, modification and
access times are used for objects that were not found in
existing summary objects. If FALSE , the current time is
used, which can be useful for testing purposes. |
The file map and/or the object summary are rebuilt. If
level=="all"
, all RData files will be read, which could take a
long time if there are many files. If level=="missing"
, RData
files will be read only where there is missing information.
If there are incompatible RData files in the directory (e.g., illegal
or duplicated object names, or multiple objects), track.rebuild
will stop with an
error unless fix==TRUE
, in which case the incompatible
RData files will either be renamed or moved to a quarantine
subdirectory. In the case of duplicated object names, the second
object encountered will be moved.
The value returned is a list with between two and four components:
fileMap |
The mapping from object names to files (excluding the suffix) |
summary |
The dataframe that summarizes objects |
unsaved |
(optional) The names of variables that are not saved to disk. This component is only present if it is non-empty. |
masked |
(optinal) The names of tracked variables that are masked by other variables in the tracked environment. This component is only present if it is non-empty. |
The returned value is visible if dry.run=TRUE
and invisible otherwise.
Tony Plate <tplate@acm.org>
Overview and design of the trackObjs
package.
# Rebuild a damaged tracking database library(trackObjs) unlink("tmp1", recursive=TRUE) # build a tracking dir populated with some variables track.start("tmp1") track(x <- 33) track(X <- array(1:24, dim=2:4)) track(Y <- list(a=1:3,b=2)) X[2] <- -1 track(abc <- "def") track(def <- list(1,2,3)) invisible(Y); invisible(abc); invisible(abc); invisible(abc) track.summary() track.stop() # damage the database (remove the filemap) unlink("tmp1/filemap.txt") # and rebuild track.rebuild(dir="tmp1", verbose=2, dry.run=FALSE, fix=TRUE) track.start("tmp1") track.summary() track.status() track.stop() unlink("tmp1", recursive=TRUE)