Summary Information About R Objects

Returns data class, storage mode, mode, typeof, dimensions, and size information for R objects from the specified environment. When invoked with no argument at the top-level prompt, objects.summary shows what data sets and functions a user has defined in the current session. When invoked with no argument inside a function, objects.summary returns the information for the function's local variables: this can be useful in conjunction with browser.

Usage

objects.summary(where, all.objects = FALSE, pattern, names. = NULL,
    what = getOption("osum.information", default = c("data.class", "storage.mode",
        "mode", "typeof", "extent", "object.size")),
    all.classes = FALSE, data.class. = NULL, storage.mode. = NULL, mode. = NULL,
    typeof. = NULL, filter., order., reverse = FALSE)

Arguments

where

which environment to use in listing the available objects. Defaults to the current environment. This argument can specify the environment in any form; see the ‘Details’ section.

all.objects

a logical value. If TRUE, information for all objects is returned. If FALSE, the information about objects whose names begin with a . is omitted. Default: FALSE

pattern

an optional regular expression. Only names matching pattern are returned. glob2rx can be used to convert wildcard patterns to regular expressions.

names.

an optional character vector naming objects to summarize. Default: NULL

what

character vector specifying what information to return. This can be any subset of c("data.class", "storage.mode", "mode", "typeof", "extent", "object.size"), in any order. The default is to return all six types of information, in the order shown. what is subject to partial matching, that is, only enough initial letters of each string element are needed to guarantee unique recognition.

all.classes

logical flag specifying whether the entire class vector of an object or just the first element should be used, both in selection based on argument data.class and in the returned summary. This has bearing only on objects with a class attribute. By default only the first class element is used.

data.class.

character vector of data classes (see data.class). Selects objects belonging to one of the named data classes. If all.classes=TRUE, each element of an object's class attribute is considered, not just the first.

storage.mode.

character vector of storage modes (see storage.mode). Selects objects with one of the named storage modes.

mode.

character vector of modes (see mode). Selects objects with one of the named modes.

typeof.

character vector of types (see typeof). Selects objects with one of the named types.

filter.

logical expression indicating elements (rows) to keep: missing values are taken as false. Note that the expression will be evaluated in the data frame with object attributes, so columns should be referred to (by name) as variables in the expression (see the examples). This argument is crafted after the select argument of the base subset function.

order.

expression involving (unquoted) attributes names, controlling the sort order of the object entries (printed as rows) in the summary. For example, order=object.size means sort the objects on the increasing values of the object.size component of the summary. order=c(data.class, -object.size) means sort the objects alphabetically by data.class, and then the decreasing values of the object.size. If order is omitted, the entries are sorted alphabetically by object name. This argument is crafted after the arguments to the base order function.

The attribute names to be used in filter and order expressions must be fully specified (no partial matching possible).

reverse

logical flag: if TRUE, the final sort order is reversed, even if this order depends on object names (this is different from the original S-PLUS function). Default: FALSE

Value

An object of (S3) class "objects.summary", which inherits from class "data.frame". Its components (printed as columns) are those specified in argument what. Each component contains one type of information for all selected objects. They are at most the following:

data.class: a factor (if all.classes=FALSE), or a list of character vectors (if all.classes=TRUE) containing the data class information. This is defined as in the function data.class, with the exception that when all.classes=TRUE, the summary will contain the entire class attribute for each object which has one, whereas function data.class returns only the first element of this vector.
storage.mode: a factor giving the storage mode information, as returned by function storage.mode.
mode: a factor giving the mode information, as returned by function mode.
typeof: a factor giving the R internal type or storage mode information, as returned by function typeof.
extent: a list, each of whose components is a numeric vector giving the dimension of an object, or its length if it is dimensionless.
object.size: a numeric vector giving the object sizes in bytes, as returned by function object.size.

The purpose of the dedicated class objects.summary is only to provide customized print and summary methods.

Details

The where argument can specify the environment from which object names are taken in one of several forms: as an integer (the position in the search list); as the character string name of an element in the search list; or as an explicit environment (including using sys.frame to access the currently active function calls). By default, the environment of the call to objects.summary is used.

Unless an explicit environment is provided, the where argument should designate an element of the search list. However, if it is a character of the form "package:pkg_name" and if the package named "pkg_name" is installed, it is silently loaded, its objects retrieved, and then it is unloaded when the function exits. Depending on the time it takes to load the package, the execution might be slower than getting the information about an attached package.

It is possible to use the attributes that are not returned (not listed in what) in the filter and order expressions.

References

TIBCO Spotfire S+® 8.2 Function Guide, November 2010, TIBCO Software Inc.

Examples

.Ob <- 1
a <- letters[1:5]
x <- rnorm(20)
i <- 1:10
l <- list(a = a, i = i, x = x)
df <- iris
arr <- iris3
myfunc <- function() {ls()}
objects.summary()
#>        data.class storage.mode      mode    typeof     extent object.size
#> a       character    character character character          5         376
#> arr         array       double   numeric    double 50 x 4 x 3        5816
#> df     data.frame         list      list      list    150 x 5        7256
#> i         numeric      integer   numeric   integer         10          96
#> l            list         list      list      list          3        1120
#> myfunc   function     function  function   closure          1        4272
#> x         numeric       double   numeric    double         20         208
objects.summary(pattern = "O")
#> [1] data.class   storage.mode mode         typeof       extent      
#> [6] object.size 
#> <0 rows> (or 0-length row.names)
objects.summary(pattern = "O", all.objects = TRUE)
#>     data.class storage.mode    mode typeof extent object.size
#> .Ob    numeric       double numeric double      1          56

objects.summary(mode = "function")
#>        data.class storage.mode     mode  typeof extent object.size
#> myfunc   function     function function closure      1        4272
objects.summary("package:grDevices", filter = mode != "function")
#>             data.class storage.mode      mode    typeof extent object.size
#> Hershey           list         list      list      list      3        2024
#> blues9       character    character character character      9         680
#> colorspaces       list         list      list      list      6      478024
objects.summary("package:datasets", all.classes = TRUE,
    filter = sapply(data.class, length) > 1)
#>                         data.class storage.mode    mode typeof   extent
#> CO2                   nfnGroup....         list    list   list   84 x 5
#> ChickWeight           nfnGroup....         list    list   list  578 x 4
#> DNase                 nfnGroup....         list    list   list  176 x 3
#> EuStockMarkets        mts, ts,....       double numeric double 1860 x 4
#> Indometh              nfnGroup....         list    list   list   66 x 3
#> Loblolly              nfnGroup....         list    list   list   84 x 3
#> Orange                nfnGroup....         list    list   list   35 x 3
#> Seatbelts             mts, ts,....       double numeric double  192 x 8
#> Theoph                nfnGroup....         list    list   list  132 x 5
#> USPersonalExpenditure matrix, ....       double numeric double    5 x 5
#> VADeaths              matrix, ....       double numeric double    5 x 4
#> WorldPhones           matrix, ....       double numeric double    7 x 7
#> euro.cross            matrix, ....       double numeric double  11 x 11
#> freeny.x              matrix, ....       double numeric double   39 x 4
#> stack.x               matrix, ....       double numeric double   21 x 3
#> state.x77             matrix, ....       double numeric double   50 x 8
#> volcano               matrix, ....       double numeric double  87 x 61
#>                       object.size
#> CO2                          9976
#> ChickWeight                 22696
#> DNase                        8256
#> EuStockMarkets              60824
#> Indometh                     5904
#> Loblolly                    12120
#> Orange                       5232
#> Seatbelts                   13872
#> Theoph                      10000
#> USPersonalExpenditure        1448
#> VADeaths                     1264
#> WorldPhones                  1800
#> euro.cross                   2944
#> freeny.x                     2008
#> stack.x                      1168
#> state.x77                    7672
#> volcano                     42672
# shows an empty list because inside myfunc no variables are defined
myfunc <- function() {objects.summary()}
myfunc()
#> [1] data.class   storage.mode mode         typeof       extent      
#> [6] object.size 
#> <0 rows> (or 0-length row.names)

# define a local variable inside myfunc
myfunc <- function() {y <- 1; objects.summary()}
myfunc()                # shows "y"
#>   data.class storage.mode    mode typeof extent object.size
#> y    numeric       double numeric double      1          56