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 |

`keepnums` |
in each dimension, if no names in that dimension are
present, create them using the indices included in that dimension.
Ignored if |

`addrownums` |
deprecated - |

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

*utils*version 4.4.1 Index]