R: Fast (Grouped, Weighted) Mean for Matrix-Like Objects

fmean {collapse} | R Documentation

## Fast (Grouped, Weighted) Mean for Matrix-Like Objects

### Description

`fmean` is a generic function that computes the (column-wise) mean of `x`, (optionally) grouped by `g` and/or weighted by `w`. The `TRA` argument can further be used to transform `x` using its (grouped, weighted) mean.

### Usage

    fmean(x, ...)

    ## Default S3 method:
    fmean(x, g = NULL, w = NULL, TRA = NULL, na.rm = TRUE,
          use.g.names = TRUE, nthreads = 1L, ...)

    ## S3 method for class 'matrix'
    fmean(x, g = NULL, w = NULL, TRA = NULL, na.rm = TRUE,
          use.g.names = TRUE, drop = TRUE, nthreads = 1L, ...)

    ## S3 method for class 'data.frame'
    fmean(x, g = NULL, w = NULL, TRA = NULL, na.rm = TRUE,
          use.g.names = TRUE, drop = TRUE, nthreads = 1L, ...)

    ## S3 method for class 'grouped_df'
    fmean(x, w = NULL, TRA = NULL, na.rm = TRUE,
          use.g.names = FALSE, keep.group_vars = TRUE,
          keep.w = TRUE, nthreads = 1L, ...)

### 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`.
`w` | a numeric vector of (non-negative) weights, may contain missing values.
`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.
`nthreads` | integer. The number of threads to utilize. See Details of `fsum`.
`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.
`keep.w` | grouped_df method: Logical. Retain summed weighting variable after computation (if contained in `grouped_df`).
`...` | 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

The weighted mean is computed as `sum(x * w) / sum(w)`. If `na.rm = TRUE`, missing values will be removed from both `x` and `w` i.e. utilizing only `x[complete.cases(x,w)]` and `w[complete.cases(x,w)]`.

For further computational details see `fsum`, which works equivalently.

### Value

The (`w` weighted) mean of `x`, grouped by `g`, or (if `TRA` is used) `x` transformed by its (grouped, weighted) mean.

### See Also

`fmedian`, `fmode`, Fast Statistical Functions, Collapse Overview

### Examples

    ## default vector method
    mpg <- mtcars$mpg
    fmean(mpg)                         # Simple mean
    fmean(mpg, w = mtcars$hp)          # Weighted mean: Weighted by hp
    fmean(mpg, TRA = "-")              # Simple transformation: demeaning (See also ?W)
    fmean(mpg, mtcars$cyl)             # Grouped mean
    fmean(mpg, mtcars[8:9])            # another grouped mean.
    g <- GRP(mtcars[c(2,8:9)])
    fmean(mpg, g)                      # Pre-computing groups speeds up the computation
    fmean(mpg, g, mtcars$hp)           # Grouped weighted mean
    fmean(mpg, g, TRA = "-")           # Demeaning by group
    fmean(mpg, g, mtcars$hp, "-")      # Group-demeaning using weighted group means

    ## data.frame method
    fmean(mtcars)
    fmean(mtcars, g)
    fmean(fgroup_by(mtcars, cyl, vs, am))  # Another way of doing it..
    head(fmean(mtcars, g, TRA = "-"))      # etc..

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

    ## method for grouped data frames - created with dplyr::group_by or fgroup_by
    library(dplyr)
    mtcars %>% group_by(cyl,vs,am) %>% fmean()         # Ordinary
    mtcars %>% group_by(cyl,vs,am) %>% fmean(hp)       # Weighted
    mtcars %>% group_by(cyl,vs,am) %>% fmean(hp, "-")  # Weighted Transform
    mtcars %>% group_by(cyl,vs,am) %>%
               select(mpg,hp) %>% fmean(hp, "-")      # Only mpg

    mtcars %>% fgroup_by(cyl,vs,am) %>%                # Equivalent and faster !
               fselect(mpg,hp) %>% fmean(hp, "-")

[Package collapse version 1.8.6 Index]