R: Fast (Grouped) First and Last Value for Matrix-Like Objects

ffirst-flast {collapse} | R Documentation

## Fast (Grouped) First and Last Value for Matrix-Like Objects

### Description

`ffirst` and `flast` are S3 generic functions that (column-wise) returns the first and last values in `x`, (optionally) grouped by `g`. The `TRA` argument can further be used to transform `x` using its (groupwise) first and last values.

### Usage

    ffirst(x, ...)
    flast(x, ...)

    ## Default S3 method:
    ffirst(x, g = NULL, TRA = NULL, na.rm = TRUE,
           use.g.names = TRUE, ...)
    ## Default S3 method:
    flast(x, g = NULL, TRA = NULL, na.rm = TRUE,
          use.g.names = TRUE, ...)

    ## S3 method for class 'matrix'
    ffirst(x, g = NULL, TRA = NULL, na.rm = TRUE,
           use.g.names = TRUE, drop = TRUE, ...)
    ## S3 method for class 'matrix'
    flast(x, g = NULL, TRA = NULL, na.rm = TRUE,
          use.g.names = TRUE, drop = TRUE, ...)

    ## S3 method for class 'data.frame'
    ffirst(x, g = NULL, TRA = NULL, na.rm = TRUE,
           use.g.names = TRUE, drop = TRUE, ...)
    ## S3 method for class 'data.frame'
    flast(x, g = NULL, TRA = NULL, na.rm = TRUE,
          use.g.names = TRUE, drop = TRUE, ...)

    ## S3 method for class 'grouped_df'
    ffirst(x, TRA = NULL, na.rm = TRUE,
           use.g.names = FALSE, keep.group_vars = TRUE, ...)
    ## S3 method for class 'grouped_df'
    flast(x, TRA = NULL, na.rm = TRUE,
          use.g.names = FALSE, keep.group_vars = TRUE, ...)

### Arguments

`x` | a vector, matrix, data frame or grouped data frame (class 'grouped_df').
`g` | a factor, `GRP` object, atomic vector (internally converted to factor) or a list of vectors / factors (internally converted to a `GRP` object) used to group `x`.
`TRA` | an integer or quoted operator indicating the transformation to perform: 0 - "replace_NA" | 1 - "replace_fill" | 2 - "replace" | 3 - "-" | 4 - "-+" | 5 - "/" | 6 - "%" | 7 - "+" | 8 - "*" | 9 - "%%" | 10 - "-%%". See `TRA`.
`na.rm` | logical. `TRUE` skips missing values and returns the first / last non-missing value i.e. if the first (1) / last (n) value is `NA`, take the second (2) / second-to-last (n-1) value etc..
`use.g.names` | logical. Make group-names and add to the result as names (default method) or row-names (matrix and data frame methods). No row-names are generated for data.table's.
`drop` | matrix and data.frame method: Logical. `TRUE` drops dimensions and returns an atomic vector if `g = NULL` and `TRA = NULL`.
`keep.group_vars` | grouped_df method: Logical. `FALSE` removes grouping variables after computation.
`...` | arguments to be passed to or from other methods. If `TRA` is used, passing `set = TRUE` will transform data by reference and return the result invisibly.

### Value

`ffirst` returns the first value in `x`, grouped by `g`, or (if `TRA` is used) `x` transformed by its first value, grouped by `g`. Similarly `flast` returns the last value in `x`, ...

### Note

Both functions are significantly faster if `na.rm = FALSE`, particularly `ffirst` which can take direct advantage of the 'group.starts' elements in `GRP` objects.

### See Also

Fast Statistical Functions, Collapse Overview

### Examples

    ## default vector method
    ffirst(airquality$Ozone)                   # Simple first value
    ffirst(airquality$Ozone, airquality$Month) # Grouped first value
    ffirst(airquality$Ozone, airquality$Month,
           na.rm = FALSE)                      # Grouped first, but without skipping initial NA's

    ## data.frame method
    ffirst(airquality)
    ffirst(airquality, airquality$Month)
    ffirst(airquality, airquality$Month, na.rm = FALSE) # Again first Ozone measurement in month 6 is NA

    ## matrix method
    aqm <- qM(airquality)
    ffirst(aqm)
    ffirst(aqm, airquality$Month) # etc..

    ## method for grouped data frames - created with dplyr::group_by or fgroup_by
    library(dplyr)
    airquality %>% group_by(Month) %>% ffirst()
    airquality %>% group_by(Month) %>% select(Ozone) %>% ffirst(na.rm = FALSE)

    # Note: All examples generalize to flast.

[Package collapse version 1.8.6 Index]