R: Return the First or Last Parts of an Object

head {utils} | R Documentation

## Return the First or Last Parts of an Object

### Description

Returns the first or last parts of a vector, matrix, table, data frame or function. Since `head()` and `tail()` are generic functions, 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

`x` | an object
`n` | an integer vector of length up to `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 `n[i]` includes the first/last `n[i]` indices in that dimension, while a negative value excludes the last/first `abs(n[i])`, including all remaining indices. `NA` or non-specified values (when `length(n) < length(dim(x))`) select all indices in that dimension. Must contain at least one non-missing value.
`keepnums` | in each dimension, if no names in that dimension are present, create them using the indices included in that dimension. Ignored if `dim(x)` is `NULL` or its length 1.
`addrownums` | deprecated - `keepnums` should be used instead. Taken as the value of `keepnums` if it is explicitly set when `keepnums` is not.
`...` | arguments to be passed to or from other methods.

### Details

For vector/array based objects, `head()` (`tail()`) returns a subset of the same dimensionality as `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. `head.matrix()` and `tail.matrix()` are exported.

The default and array(/matrix) methods for `head()` and `tail()` are quite general. They will work as is for any class which has a `dim()` method, a `length()` method (only required if `dim()` returns `NULL`), and a `[` method (that accepts the `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 `x` is an array(/matrix) of dimensionality two and more, `tail()` will add dimnames similar to how they would appear in a full printing of `x` for all dimensions `k` where `n[k]` is specified and non-missing and `dimnames(x)[[k]]` (or `dimnames(x)` itself) is `NULL`. Specifically, the form of the added dimnames will vary for different dimensions as follows:

`k=1` (rows):

  `"[n,]"` (right justified with whitespace padding)

`k=2` (columns):

  `"[,n]"` (with no whitespace padding)

`k>2` (higher dims):

  `"n"`, i.e., the indices as character values

Setting `keepnums = FALSE` suppresses this behaviour.

As `data.frame` subsetting (‘indexing’) keeps `attributes`, so do the `head()` and `tail()` methods for data frames.

### Value

An object (usually) like `x` but generally smaller. Hence, for `array`s, the result corresponds to `x[.., drop=FALSE]`. For `ftable` objects `x`, a transformed `format(x)`.

### Note

For array inputs the output of `tail` when `keepnums` is `TRUE`, any dimnames vectors added for dimensions `>2` are the original numeric indices in that dimension as character vectors. This means that, e.g., for 3-dimensional array `arr`, `tail(arr, c(2,2,-1))[ , , 2]` and `tail(arr, c(2,2,-1))[ , , "2"]` may both be valid but have completely different meanings.

### Author(s)

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
    })

[Package utils version 4.0.5 Index]