collapse (version 1.6.5)

fcumsum: 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, …)
# S3 method for default
fcumsum(x, g = NULL, o = NULL, na.rm = TRUE, fill = FALSE, check.o = TRUE, …)
# S3 method for matrix
fcumsum(x, g = NULL, o = NULL, na.rm = TRUE, fill = FALSE, check.o = TRUE, …)
# S3 method for data.frame
fcumsum(x, g = NULL, o = NULL, na.rm = TRUE, fill = FALSE, check.o = TRUE, …)
# Methods for compatibility with plm:
# S3 method for pseries
fcumsum(x, na.rm = TRUE, fill = FALSE, …)
# S3 method for pdata.frame
fcumsum(x, na.rm = TRUE, fill = FALSE, …)
# Methods for grouped data frame / compatibility with dplyr:
# S3 method for 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 too). 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.

Value

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

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.

See Also

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

Examples

# NOT RUN {
## Non-grouped
fcumsum(AirPassengers)
# }
# NOT RUN {
fcumsum(EuStockMarkets) |> head()
# }
# NOT RUN {
fcumsum(mtcars)

# Non-grouped but ordered
o <- order(rnorm(nrow(EuStockMarkets)))
all.equal(copyAttrib(fcumsum(EuStockMarkets[o, ], o = o)[order(o), ], EuStockMarkets),
          fcumsum(EuStockMarkets))
# }
# NOT RUN {
## Grouped
with(wlddev, fcumsum(PCGDP, iso3c)) |> head()

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