gseries (version 3.0.2)

stack_tsDF: Stack time series data

Description

Convert a multivariate time series data frame (see ts_to_tsDF()) for the benchmarking functions (benchmarking() and stock_benchmarking()) into a stacked (tall) data frame with four variables (columns):

• one (1) for the series name

• two (2) for the data point identification (year and period)

• one (1) for the data point value

Missing (NA) series values are not included in the output stacked data frame by default. Specify argument keep_NA = TRUE in order to keep them.

This function is useful when intending to use the by argument (BY-group processing mode) of the benchmarking functions in order to benchmark multiple series in a single function call.

Usage

stack_tsDF(
  ts_df,
  ser_cName = "series",
  yr_cName = "year",
  per_cName = "period",
  val_cName = "value",
  keep_NA = FALSE
)

Value

The function returns a data frame with four variables:

• Series name, type character (see argument ser_cName)

• Data point year, type numeric (see argument yr_cName)

• Data point period, type numeric (see argument per_cName)

• Data point value, type numeric (see argument val_cName)

Note: the function returns a "data.frame" object than can be explicitly coerced to another type of object with the appropriate as*() function (e.g., tibble::as_tibble() would coerce it to a tibble).

Arguments

ts_df

(mandatory)

Data frame (object of class "data.frame") that contains the multivariate time series data to be stacked.

ser_cName

(optional)

String specifying the name of the character variable (column) in the output stacked data frame that will contain the series names (name of the time series variables in the input multivariate time series data frame). This variable can then be used as the BY-group variable (argument by) with the benchmarking functions.

Default value is ser_cName = "series".

yr_cName, per_cName

(optional)

Strings specifying the name of the numeric variables (columns) in the input multivariate time series data frame that contain the data point year and period (cycle) identifiers. These variables are transferred to the output stacked data frame with the same variable names.

Default values are yr_cName = "year" and per_cName = "period".

val_cName

(optional)

String specifying the name of the numeric variable (column) in the output stacked data frame that will contain the data point values.

Default value is val_cName = "value".

keep_NA

(optional)

Logical argument specifying whether NA time series values in the input multivariate time series data frame should be kept in the output stacked data frame.

Default value is keep_NA = FALSE.

See Also

unstack_tsDF() stack_bmkDF() ts_to_tsDF() benchmarking() stock_benchmarking()

Examples

# Create a data frame with 2 quarterly indicators series
# (with missing values for the last 2 quarters)
my_indicators <- ts_to_tsDF(ts(data.frame(ser1 = c(1:5 *  10, NA, NA),
                                          ser2 = c(1:5 * 100, NA, NA)), 
                               start = c(2019, 1), frequency = 4))
my_indicators


# Stack the indicator series ...

# discarding `NA` values in the output stacked data frame (default behavior)
stack_tsDF(my_indicators)

# keeping `NA` values in the output stacked data frame
stack_tsDF(my_indicators, keep_NA = TRUE)

# using custom variable (column) names
stack_tsDF(my_indicators, ser_cName = "ser_name", val_cName = "ser_val")