R: Fast (Grouped) Maxima and Minima for Matrix-Like Objects

fmin-fmax {collapse} | R Documentation

## Fast (Grouped) Maxima and Minima for Matrix-Like Objects

### Description

`fmax` and `fmin` are generic functions that compute the (column-wise) maximum and minimum value of all values in `x`, (optionally) grouped by `g`. The `TRA` argument can further be used to transform `x` using its (grouped) maximum or minimum value.

### Usage

    fmax(x, ...)
    fmin(x, ...)

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

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

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

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

### Arguments

`x` | a numeric 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. Skip missing values in `x`. Defaults to `TRUE` and implemented at very little computational cost. If `na.rm = FALSE` a `NA` is returned when encountered.
`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.

### Details

Missing-value removal as controlled by the `na.rm` argument is done at no extra cost since in C++ any logical comparison involving `NA` or `NaN` evaluates to `FALSE`. Large performance gains can nevertheless be achieved in the presence of missing values if `na.rm = FALSE`, since then the corresponding computation is terminated once a `NA` is encountered and `NA` is returned (unlike `max` and `min` which just run through without any checks).

For further computational details see `fsum`.

### Value

`fmax` returns the maximum value of `x`, grouped by `g`, or (if `TRA` is used) `x` transformed by its (grouped) maximum value. Analogous, `fmin` returns the minimum value ...

### See Also

Fast Statistical Functions, Collapse Overview

### Examples

    ## default vector method
    mpg <- mtcars$mpg
    fmax(mpg)                         # Maximum value
    fmin(mpg)                         # Minimum value (all examples below use fmax but apply to fmin)
    fmax(mpg, TRA = "%")              # Simple transformation: Take percentage of maximum value
    fmax(mpg, mtcars$cyl)             # Grouped maximum value
    fmax(mpg, mtcars[c(2,8:9)])       # More groups..
    g <- GRP(mtcars, ~ cyl + vs + am) # Precomputing groups gives more speed !
    fmax(mpg, g)
    fmax(mpg, g, TRA = "%")           # Groupwise percentage of maximum value
    fmax(mpg, g, TRA = "replace")     # Groupwise replace by maximum value

    ## data.frame method
    fmax(mtcars)
    head(fmax(mtcars, TRA = "%"))
    fmax(mtcars, g)
    fmax(mtcars, g, use.g.names = FALSE) # No row-names generated

    ## matrix method
    m <- qM(mtcars)
    fmax(m)
    head(fmax(m, TRA = "%"))
    fmax(m, g) # etc..

    ## method for grouped data frames - created with dplyr::group_by or fgroup_by
    library(dplyr)
    mtcars %>% group_by(cyl,vs,am) %>% fmax()
    mtcars %>% group_by(cyl,vs,am) %>% fmax("%")
    mtcars %>% group_by(cyl,vs,am) %>% select(mpg) %>% fmax()

[Package collapse version 1.8.6 Index]