R: Fast (Grouped, Ordered) Cumulative Sum for Matrix-Like...

fcumsum {collapse} | R Documentation

## Fast (Grouped, Ordered) Cumulative Sum for Matrix-Like Objects

### Description

`fcumsum` is a generic function that computes the (column-wise) cumulative sum of `x`, (optionally) grouped by `g` and/or ordered by `o`. Several options to deal with missing values are provided.

### Usage

    fcumsum(x, ...)

    ## Default S3 method:
    fcumsum(x, g = NULL, o = NULL, na.rm = TRUE, fill = FALSE, check.o = TRUE, ...)

    ## S3 method for class 'matrix'
    fcumsum(x, g = NULL, o = NULL, na.rm = TRUE, fill = FALSE, check.o = TRUE, ...)

    ## S3 method for class 'data.frame'
    fcumsum(x, g = NULL, o = NULL, na.rm = TRUE, fill = FALSE, check.o = TRUE, ...)

    # Methods for compatibility with plm:

    ## S3 method for class 'pseries'
    fcumsum(x, na.rm = TRUE, fill = FALSE, ...)

    ## S3 method for class 'pdata.frame'
    fcumsum(x, na.rm = TRUE, fill = FALSE, ...)

    # Methods for grouped data frame / compatibility with dplyr:

    ## S3 method for class 'grouped_df'
    fcumsum(x, o = NULL, na.rm = TRUE, fill = FALSE, check.o = TRUE, keep.ids = TRUE, ...)

### Arguments

`x` | a vector / time series, matrix, data frame, panel series (`plm::pseries`), panel data frame (`plm::pdata.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`.
`o` | a vector or list of vectors providing the order in which the elements of `x` are cumulatively summed. Will be passed to `radixorderv` unless `check.o = FALSE`.
`na.rm` | logical. Skip missing values in `x`. Defaults to `TRUE` and implemented at very little computational cost.
`fill` | if `na.rm = TRUE`, setting `fill = TRUE` will overwrite missing values with the previous value of the cumulative sum, starting from 0.
`check.o` | logical. Programmers option: `FALSE` prevents passing `o` to `radixorderv`, requiring `o` to be a valid ordering vector that is integer typed with each element in the range `[1, length(x)]`. This gives some extra speed, but will terminate R if any element of `o` is too large or too small.
`keep.ids` | pdata.frame / grouped_df methods: Logical. Drop all identifiers from the output (which includes all grouping variables and variables passed to`o`). Note: For grouped / panel data frames identifiers are dropped, but the 'groups' / 'index' attributes are kept.
`...` | arguments to be passed to or from other methods.

### Details

If `na.rm = FALSE`, `fcumsum` works like `cumsum` and propagates missing values. The default `na.rm = TRUE` skips missing values and computes the cumulative sum on the non-missing values. Missing values are kept. If `fill = TRUE`, missing values are replaced with the previous value of the cumulative sum (starting from 0), computed on the non-missing values.

By default the cumulative sum is computed in the order in which elements appear in `x`. If `o` is provided, the cumulative sum is computed in the order given by `radixorderv(o)`, without the need to first sort `x`. This applies as well if groups are used (`g`), in which the cumulative sum is computed separately in each group.

The pseries and pdata.frame methods assume that the last factor in the `plm::index` is the time-variable and the rest are grouping variables. The time-variable is passed to `radixorderv` and used for ordered computation, so that cumulative sums are accurately computed regardless of whether the panel-data is ordered or balanced.

`fcumsum` explicitly supports integers. Integers in R are bounded at bounded at +-2,147,483,647, and an integer overflow error will be provided if the cumulative sum (within any group) exceeds +-2,147,483,647.

### Value

the cumulative sum of values in `x`, (optionally) grouped by `g` and/or ordered by `o`. See Details and Examples.

### See Also

`fdiff`, `fgrowth`, Time Series and Panel Series, Collapse Overview

### Examples

    ## Non-grouped
    fcumsum(AirPassengers)
    head(fcumsum(EuStockMarkets))
    fcumsum(mtcars)

    # Non-grouped but ordered
    o <- order(rnorm(nrow(EuStockMarkets)))
    all.equal(copyAttrib(fcumsum(EuStockMarkets[o, ], o = o)[order(o), ], EuStockMarkets),
              fcumsum(EuStockMarkets))

    ## Grouped
    head(with(wlddev, fcumsum(PCGDP, iso3c)))

    ## Grouped and ordered
    head(with(wlddev, fcumsum(PCGDP, iso3c, year)))
    head(with(wlddev, fcumsum(PCGDP, iso3c, year, fill = TRUE)))

[Package collapse version 1.7.6 Index]