| % File src/library/utils/man/head.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2020 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{head} |
| \title{Return the First or Last Parts of an Object} |
| \alias{head} |
| \alias{head.data.frame} |
| \alias{head.default} |
| \alias{head.function} |
| \alias{head.ftable} |
| \alias{head.matrix} |
| \alias{tail} |
| \alias{tail.data.frame} |
| \alias{tail.default} |
| \alias{tail.function} |
| \alias{tail.ftable} |
| \alias{tail.table} |
| \alias{tail.matrix} |
| \alias{tail.array} |
| \description{ |
| Returns the first or last parts of a vector, matrix, table, data frame |
| or function. Since \code{head()} and \code{tail()} are generic |
| functions, they may also have been extended to other classes. |
| } |
| \usage{ |
| head(x, \dots) |
| \method{head}{default}(x, n = 6L, \dots) |
| % head.matrix(x, n = 6L, \dots) # <-- gives NOTE, even though exported |
| \method{head}{matrix}(x, n = 6L, \dots) # is exported as head.matrix() |
| ## NB: The methods for 'data.frame' and 'array' are identical to the 'matrix' one |
| |
| \method{head}{ftable}(x, n = 6L, \dots) |
| \method{head}{function}(x, n = 6L, \dots) |
| |
| |
| tail(x, \dots) |
| \method{tail}{default}(x, n = 6L, keepnums = FALSE, addrownums, \dots) |
| \method{tail}{matrix}(x, n = 6L, keepnums = TRUE, addrownums, \dots) # exported as tail.matrix() |
| ## NB: The methods for 'data.frame', 'array', and 'table' |
| ## are identical to the 'matrix' one |
| |
| \method{tail}{ftable}(x, n = 6L, keepnums = FALSE, addrownums, \dots) |
| \method{tail}{function}(x, n = 6L, \dots) |
| } |
| \arguments{ |
| \item{x}{an object} |
| \item{n}{an integer vector of length up to \code{dim(x)} (or 1, |
| for non-dimensioned objects). Values specify the indices to be |
| selected in the corresponding dimension (or along the length) of the |
| object. A positive value of \code{n[i]} includes the first/last |
| \code{n[i]} indices in that dimension, while a negative value |
| excludes the last/first \code{abs(n[i])}, including all remaining |
| indices. \code{NA} or non-specified values (when \code{length(n) < |
| length(dim(x))}) select all indices in that dimension. Must |
| contain at least one non-missing value.} |
| \item{keepnums}{in each dimension, if no names in that dimension are |
| present, create them using the indices included in that dimension. |
| Ignored if \code{dim(x)} is \code{NULL} or its length 1.} |
| \item{addrownums}{deprecated - \code{keepnums} should be used |
| instead. Taken as the value of \code{keepnums} if it is explicitly |
| set when \code{keepnums} is not.} |
| \item{\dots}{arguments to be passed to or from other methods.} |
| } |
| \details{ |
| For vector/array based objects, \code{head()} (\code{tail()}) returns |
| a subset of the same dimensionality as \code{x}, usually of |
| the same class. For historical reasons, by default they select the |
| first (last) 6 indices in the first dimension ("rows") or along the |
| length of a non-dimensioned vector, and the full extent (all indices) |
| in any remaining dimensions. \code{head.matrix()} and |
| \code{tail.matrix()} are exported. |
| |
| The default and array(/matrix) methods for \code{head()} and |
| \code{tail()} are quite general. They will work as is for any class |
| which has a \code{dim()} method, a \code{length()} method (only |
| required if \code{dim()} returns \code{NULL}), and a \code{[} method |
| (that accepts the \code{drop} argument and can subset in all |
| dimensions in the dimensioned case). |
| |
| For functions, the lines of the deparsed function are returned as |
| character strings. |
| |
| When \code{x} is an array(/matrix) of dimensionality two and more, |
| \code{tail()} will add dimnames similar to how they would appear in a |
| full printing of \code{x} for all dimensions \code{k} where |
| \code{n[k]} is specified and non-missing and \code{dimnames(x)[[k]]} |
| (or \code{dimnames(x)} itself) is \code{NULL}. Specifically, the |
| form of the added dimnames will vary for different dimensions as follows: |
| \describe{ |
| \item{\code{k=1} (rows): }{\code{"[n,]"} (right justified with |
| whitespace padding)} |
| \item{\code{k=2} (columns): }{\code{"[,n]"} (with \emph{no} whitespace |
| padding)} |
| \item{\code{k>2} (higher dims): }{\code{"n"}, i.e., the indices as |
| \emph{character} values} |
| } |
| Setting \code{keepnums = FALSE} suppresses this behaviour. |
| |
| As \code{\link{data.frame}} subsetting (\sQuote{indexing}) keeps |
| \code{\link{attributes}}, so do the \code{head()} and \code{tail()} |
| methods for data frames. |
| } |
| \value{ |
| An object (usually) like \code{x} but generally smaller. Hence, for |
| \code{\link{array}}s, the result corresponds to \code{x[.., drop=FALSE]}. |
| For \code{\link{ftable}} objects \code{x}, a transformed \code{format(x)}. |
| } |
| \note{ |
| For array inputs the output of \code{tail} when \code{keepnums} is \code{TRUE}, |
| any dimnames vectors added for dimensions \code{>2} are the original |
| numeric indices in that dimension \emph{as character vectors}. This |
| means that, e.g., for 3-dimensional array \code{arr}, |
| \code{tail(arr, c(2,2,-1))[ , , 2]} and |
| \code{tail(arr, c(2,2,-1))[ , , "2"]} may both be valid but have |
| completely different meanings. |
| } |
| |
| \author{ |
| Patrick Burns, improved and corrected by R-Core. Negative argument |
| added by Vincent Goulet. Multi-dimension support added by Gabriel Becker. |
| } |
| |
| \examples{ |
| head(letters) |
| head(letters, n = -6L) |
| |
| head(freeny.x, n = 10L) |
| head(freeny.y) |
| |
| head(iris3) |
| head(iris3, c(6L, 2L)) |
| head(iris3, c(6L, -1L, 2L)) |
| |
| tail(letters) |
| tail(letters, n = -6L) |
| |
| tail(freeny.x) |
| ## the bottom-right "corner" : |
| tail(freeny.x, n = c(4, 2)) |
| tail(freeny.y) |
| |
| tail(iris3) |
| tail(iris3, c(6L, 2L)) |
| tail(iris3, c(6L, -1L, 2L)) |
| |
| ## iris with dimnames stripped |
| a3d <- iris3 ; dimnames(a3d) <- NULL |
| tail(a3d, c(6, -1, 2)) # keepnums = TRUE is default here! |
| tail(a3d, c(6, -1, 2), keepnums = FALSE) |
| |
| ## data frame w/ a (non-standard) attribute: |
| treeS <- structure(trees, foo = "bar") |
| (n <- nrow(treeS)) |
| stopifnot(exprs = { # attribute is kept |
| identical(htS <- head(treeS), treeS[1:6, ]) |
| identical(attr(htS, "foo") , "bar") |
| identical(tlS <- tail(treeS), treeS[(n-5):n, ]) |
| ## BUT if I use "useAttrib(.)", this is *not* ok, when n is of length 2: |
| ## --- because [i,j]-indexing of data frames *also* drops "other" attributes .. |
| identical(tail(treeS, 3:2), treeS[(n-2):n, 2:3] ) |
| }) |
| |
| tail(library) # last lines of function |
| |
| head(stats::ftable(Titanic)) |
| |
| ## 1d-array (with named dim) : |
| a1 <- array(1:7, 7); names(dim(a1)) <- "O2" |
| stopifnot(exprs = { |
| identical( tail(a1, 10), a1) |
| identical( head(a1, 10), a1) |
| identical( head(a1, 1), a1 [1 , drop=FALSE] ) # was a1[1] in R <= 3.6.x |
| identical( tail(a1, 2), a1[6:7]) |
| identical( tail(a1, 1), a1 [7 , drop=FALSE] ) # was a1[7] in R <= 3.6.x |
| }) |
| } |
| \keyword{manip} |