Return the First or Last Parts of an Object

Description

Returns the first or last parts of a vector, matrix, table, data frameor function. Sincehead() andtail() are genericfunctions, they may also have been extended to other classes.

Usage

head(x, ...)## Default S3 method:head(x, n = 6L, ...)## S3 method for class 'matrix'head(x, n = 6L, ...) # is exported as head.matrix()## NB: The methods for 'data.frame' and 'array'  are identical to the 'matrix' one## S3 method for class 'ftable'head(x, n = 6L, ...)## S3 method for class 'function'head(x, n = 6L, ...)tail(x, ...)## Default S3 method:tail(x, n = 6L, keepnums = FALSE, addrownums, ...)## S3 method for class 'matrix'tail(x, n = 6L, keepnums = TRUE, addrownums, ...) # exported as tail.matrix()## NB: The methods for 'data.frame', 'array', and 'table'##     are identical to the  'matrix'  one## S3 method for class 'ftable'tail(x, n = 6L, keepnums = FALSE, addrownums, ...)## S3 method for class 'function'tail(x, n = 6L, ...)

Arguments

Details

For vector/array based objects,head() (tail()) returnsa subset of the same dimensionality asx, usually ofthe same class. For historical reasons, by default they select thefirst (last) 6 indices in the first dimension ("rows") or along thelength of a non-dimensioned vector, and the full extent (all indices)in any remaining dimensions.head.matrix() andtail.matrix() are exported.

The default and array(/matrix) methods forhead() andtail() are quite general. They will work as is for any classwhich has adim() method, alength() method (onlyrequired ifdim() returnsNULL), and a[ method(that accepts thedrop argument and can subset in alldimensions in the dimensioned case).

For functions, the lines of the deparsed function are returned ascharacter strings.

Whenx is an array(/matrix) of dimensionality two and more,tail() will add dimnames similar to how they would appear in afull printing ofx for all dimensionsk wheren[k] is specified and non-missing anddimnames(x)[[k]](ordimnames(x) itself) isNULL. Specifically, theform of the added dimnames will vary for different dimensions as follows:

k=1 (rows):

"[n,]" (right justified withwhitespace padding)

k=2 (columns):

"[,n]" (withno whitespacepadding)

k>2 (higher dims):

"n", i.e., the indices ascharacter values

Settingkeepnums = FALSE suppresses this behaviour.

Asdata.frame subsetting (‘indexing’) keepsattributes, so do thehead() andtail()methods for data frames.

Value

An object (usually) likex but generally smaller. Hence, forarrays, the result corresponds tox[.., drop=FALSE].Forftable objectsx, a transformedformat(x).

Note

For array inputs the output oftail whenkeepnums isTRUE,any dimnames vectors added for dimensions>2 are the originalnumeric indices in that dimensionas character vectors. Thismeans that, e.g., for 3-dimensional arrayarr,tail(arr, c(2,2,-1))[ , , 2] andtail(arr, c(2,2,-1))[ , , "2"] may both be valid but havecompletely different meanings.

Author(s)

Patrick Burns, improved and corrected by R-Core. Negative argumentadded 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 strippeda3d <- iris3 ; dimnames(a3d) <- NULLtail(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 functionhead(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})