str
Compactly Display the Structure of an Arbitrary R Object
Compactly display the internal structure of an R object, a
diagnostic function and an alternative to summary
(and to some extent, dput
). Ideally, only one line for
each ‘basic’ structure is displayed. It is especially well suited
to compactly display the (abbreviated) contents of (possibly nested)
lists. The idea is to give reasonable output for any R
object. It calls args
for (non-primitive) function objects.
strOptions()
is a convenience function for setting
options(str = .)
, see the examples.
- Keywords
- utilities, print, documentation
Usage
str(object, …)# S3 method for data.frame
str(object, …)
# S3 method for default
str(object, max.level = NA,
vec.len = strO$vec.len, digits.d = strO$digits.d,
nchar.max = 128, give.attr = TRUE,
drop.deparse.attr = strO$drop.deparse.attr,
give.head = TRUE, give.length = give.head,
width = getOption("width"), nest.lev = 0,
indent.str = paste(rep.int(" ", max(0, nest.lev + 1)),
collapse = ".."),
comp.str = "$ ", no.list = FALSE, envir = baseenv(),
strict.width = strO$strict.width,
formatNum = strO$formatNum, list.len = 99, …)
strOptions(strict.width = "no", digits.d = 3, vec.len = 4,
drop.deparse.attr = TRUE,
formatNum = function(x, ...)
format(x, trim = TRUE, drop0trailing = TRUE, ...))
Arguments
- object
any R object about which you want to have some information.
- max.level
maximal level of nesting which is applied for displaying nested structures, e.g., a list containing sub lists. Default NA: Display all nesting levels.
- vec.len
numeric (>= 0) indicating how many ‘first few’ elements are displayed of each vector. The number is multiplied by different factors (from .5 to 3) depending on the kind of vector. Defaults to the
vec.len
component of option"str"
(seeoptions
) which defaults to 4.- digits.d
number of digits for numerical components (as for
print
). Defaults to thedigits.d
component of option"str"
which defaults to 3.- nchar.max
maximal number of characters to show for
character
strings. Longer strings are truncated, seelongch
example below.- give.attr
logical; if
TRUE
(default), show attributes as sub structures.- drop.deparse.attr
logical; if
TRUE
(default),deparse(control = <S>)
will not have"showAttributes"
in<S>
. Used to be hard coded toFALSE
and hence can be set viastrOptions()
for back compatibility.- give.length
logical; if
TRUE
(default), indicate length (as[1:…]
).- give.head
logical; if
TRUE
(default), give (possibly abbreviated) mode/class and length (as<type>[1:…]
).- width
the page width to be used. The default is the currently active
options("width")
; note that this has only a weak effect, unlessstrict.width
is not"no"
.- nest.lev
current nesting level in the recursive calls to
str
.- indent.str
the indentation string to use.
- comp.str
string to be used for separating list components.
- no.list
logical; if true, no ‘list of …’ nor the class are printed.
- envir
the environment to be used for promise (see
delayedAssign
) objects only.- strict.width
string indicating if the
width
argument's specification should be followed strictly, one of the valuesc("no", "cut", "wrap")
, which can be abbreviated. Defaults to thestrict.width
component of option"str"
(seeoptions
) which defaults to"no"
for back compatibility reasons;"wrap"
usesstrwrap(*, width = width)
whereas"cut"
cuts directly towidth
. Note that a smallvec.length
may be better than settingstrict.width = "wrap"
.- formatNum
a function such as
format
for formatting numeric vectors. It defaults to theformatNum
component of option"str"
, see “Usage” ofstrOptions()
above, which is almost back compatible to R <= 2.7.x, however, usingformatC
may be slightly better.- list.len
numeric; maximum number of list elements to display within a level.
- …
potential further arguments (required for Method/Generic reasons).
Value
str
does not return anything, for efficiency reasons.
The obvious side effect is output to the terminal.
See Also
ls.str
for listing objects with their structure;
summary
, args
.
Examples
library(utils)
# NOT RUN {
require(stats); require(grDevices); require(graphics)
## The following examples show some of 'str' capabilities
str(1:12)
str(ls)
str(args) #- more useful than args(args) !
str(freeny)
str(str)
str(.Machine, digits.d = 20) # extra digits for identification of binary numbers
str( lsfit(1:9, 1:9))
str( lsfit(1:9, 1:9), max.level = 1)
str( lsfit(1:9, 1:9), width = 60, strict.width = "cut")
str( lsfit(1:9, 1:9), width = 60, strict.width = "wrap")
op <- options(); str(op) # save first;
# otherwise internal options() is used.
need.dev <-
!exists(".Device") || is.null(.Device) || .Device == "null device"
{ if(need.dev) postscript()
str(par())
if(need.dev) graphics.off()
}
ch <- letters[1:12]; is.na(ch) <- 3:5
str(ch) # character NA's
str(list(a = "A", L = as.list(1:100)), list.len = 9)
## ------------
## " .. [list output truncated] "
## Long strings, 'nchar.max'; 'strict.width' :
nchar(longch <- paste(rep(letters,100), collapse = ""))
str(longch)
str(longch, nchar.max = 52)
str(longch, strict.width = "wrap")
## Multibyte characters in strings (in multibyte locales):
oloc <- Sys.getlocale("LC_CTYPE")
mbyte.lc <- if(.Platform$OS.type == "windows")
"English_United States.28605" else "en_GB.UTF-8"
try(Sys.setlocale("LC_CTYPE", mbyte.lc))
## Truncation behavior (<-> correct width measurement) for "long" non-ASCII:
idx <- c(65313:65338, 65345:65350)
fwch <- intToUtf8(idx) # full width character string: each has width 2
ch <- strtrim(paste(LETTERS, collapse="._"), 64)
(ncc <- c(c.ch = nchar(ch), w.ch = nchar(ch, "w"),
c.fw = nchar(fwch), w.fw = nchar(fwch, "w")))
stopifnot(unname(ncc) == c(64,64, 32, 64))
## nchar.max: 1st line needs an increase of 2 in order to see 1 (in UTF-8!):
invisible(lapply(60:66, function(N) str(fwch, nchar.max = N)))
invisible(lapply(60:66, function(N) str( ch , nchar.max = N))) # "1 is 1" here
## revert locale to previous:
Sys.setlocale("LC_CTYPE", oloc)
## Settings for narrow transcript :
op <- options(width = 60,
str = strOptions(strict.width = "wrap"))
str(lsfit(1:9,1:9))
str(options())
## reset to previous:
options(op)
# }
# NOT RUN {
str(quote( { A+B; list(C, D) } ))
# }
# NOT RUN {
<!-- % package attaching/detaching only when needed: -->
# }
# NOT RUN {
## S4 classes :
require(stats4)
x <- 0:10; y <- c(26, 17, 13, 12, 20, 5, 9, 8, 5, 4, 8)
ll <- function(ymax = 15, xh = 6)
-sum(dpois(y, lambda=ymax/(1+x/xh), log=TRUE))
fit <- mle(ll)
str(fit)
# }