R: Return First or Last n Elements of A Data Object

first {xts} | R Documentation

## Return First or Last n Elements of A Data Object

### Description

A generic function to return the first or last elements or rows of a vector or two-dimensional data object.

A more advanced subsetting is available for zoo objects with indexes inheriting from POSIXt or Date classes.

### Usage

    first(x,...)
    last(x,...)

    ## Default S3 method:
    first(x,n=1,keep=FALSE,...)

    ## Default S3 method:
    last(x,n=1,keep=FALSE,...)

    ## S3 method for class 'xts'
    first(x,n=1,keep=FALSE,...)

    ## S3 method for class 'xts'
    last(x,n=1,keep=FALSE,...)

### Arguments

`x` | 1 or 2 dimensional data object
`n` | number of periods to return
`keep` | should removed values be kept?
`...` | additional args - unused

### Details

Provides the ability to identify the first or last `n` rows or observations of a data set. The generic method behaves much like `head` and `tail` from base, except by default only the first or last observation will be returned.

The more useful method for the xts class allows for time based subsetting, given an xtsible object.

`n` may be either a numeric value, indicating the number of observations to return - forward from `first`, or backwards from `last`, or it may be a character string describing the number and type of periods to return.

`n` may be positive or negative, in either numeric or character contexts. When positive it will return the result expected - e.g. `last(X,'1 month')` will return the last month's data. If negative, all data will be returned except for the last month. It is important to note that this is not the same as calling `first(X,'1 month')` or `first(X,'-1 month')`. All 4 variations return different subsets of data and have distinct purposes.

If `n` is a character string, it must be of the form ‘n period.type’ or ‘period.type’, where `n` is a numeric value (defaults to 1 if not provided) describing the number of `period.types` to move forward (first) or back (last).

For example, to return the last 3 weeks of a time oriented zoo object, one could call `last(X,'3 weeks')`. Valid period.types are: secs, seconds, mins, minutes, hours, days, weeks, months, quarters, and years.

It is possible to use any frequency specification (secs, mins, days, ...) for the period.type portion of the string, even if the original data is in a higher frequency. This makes it possible to return the last ‘2 months’ of data from an oject that has a daily periodicity.

It should be noted that it is only possible to extract data with methods equal to or less than the frequency of the original data set. Attempting otherwise will result in error.

Requesting more data than is in the original data object will produce a warning advising as such, and the object returned will simply be the original data.

### Value

A subset of elements/rows of the original data.

### Author(s)

Jeffrey A. Ryan

### Examples

    first(1:100)
    last(1:100)

    data(LakeHuron)
    first(LakeHuron,10)
    last(LakeHuron)

    x <- xts(1:100, Sys.Date()+1:100)
    first(x, 10)
    first(x, '1 day')
    first(x, '4 days')
    first(x, 'month')
    last(x, '2 months')
    last(x, '6 weeks')

[Package xts version 0.10-1 Index]