gseries (version 3.0.2)

ts_to_bmkDF: Convert a "ts" object to a benchmarks data frame

Description

Convert a "ts" (or "mts") object into a benchmarks data frame for the benchmarking functions with five or more variables (columns):

• four (4) for the benchmark coverage

• one (1) for each benchmark time series

For discrete benchmarks (anchor points covering a single period of the indicator series, e.g., end of year stocks), specify discrete_flag = TRUE and alignment = "b", "e" or "m".

Usage

ts_to_bmkDF(
  in_ts,
  ind_frequency,
  discrete_flag = FALSE,
  alignment = "b",
  bmk_interval_start = 1,
  startYr_cName = "startYear",
  startPer_cName = "startPeriod",
  endYr_cName = "endYear",
  endPer_cName = "endPeriod",
  val_cName = "value"
)

Value

The function returns a data frame with five or more variables:

• Benchmark coverage starting year, type numeric (see argument startYr_cName)

• Benchmark coverage starting period (cycle), type numeric (see argument startPer_cName)

• Benchmark coverage ending year, type numeric (see argument endtYr_cName)

• Benchmark coverage ending period (cycle), type numeric (see argument endPer_cName)

• One ("ts" object) or many ("mts" object) benchmark data variable(s), 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

in_ts

(mandatory)

Time series (object of class "ts" or "mts") to be converted.

ind_frequency

(mandatory)

Integer specifying the frequency of the indicator (high frequency) series for which the benchmarks (low frequency series) are related to. The frequency of a time series corresponds to the maximum number of periods in a year (e.g., 12 for a monthly data, 4 for a quarterly data, 1 for annual data).

discrete_flag

(optional)

Logical argument specifying whether the benchmarks correspond to discrete values (anchor points covering a single period of the indicator series, e.g., end of year stocks) or not. discrete_flag = FALSE defines non-discrete benchmarks, i.e., benchmarks that cover several periods of the indicator series (e.g. annual benchmarks cover 4 quarters or 12 months, quarterly benchmarks cover 3 months, etc.).

Default value is discrete_flag = FALSE.

alignment

(optional)

Character identifying the alignment of discrete benchmarks (argument discrete_flag = TRUE) in the benchmark (low frequency series) interval coverage window:

• alignment = "b": beginning of the benchmark interval window (first period)

• alignment = "e": end of the benchmark interval window (last period)

• alignment = "m": middle of the benchmark interval window (middle period)

This argument has no effect for non-discrete benchmarks (discrete_flag = FALSE).

Default value is alignment = "b".

bmk_interval_start

(optional)

Integer in the [1 .. ind_frequency] interval specifying the period (cycle) of the indicator (high frequency) series at which the benchmark (low frequency series) interval window starts. E.g., annual benchmarks corresponding to fiscal years defined from April to March of the following year would be specified with bmk_interval_start = 4 for a monthly indicator series (ind_frequency = 12) and bmk_interval_start = 2 for a quarterly indicator series (ind_frequency = 4).

Default value is bmk_interval_start = 1.

startYr_cName, startPer_cName, endYr_cName, endPer_cName

(optional)

Strings specifying the name of the numeric variables (columns) in the output data frame that will define the benchmarks coverage, i.e., the starting and ending year and period (cycle) identifiers.

Default values are startYr_cName = "startYear", startPer_cName = "startPeriod" endYr_cName = "endYear" and endPer_cName = "endPeriod".

val_cName

(optional)

String specifying the name of the numeric variable (column) in the output data frame that will contain the benchmark values. This argument has no effect for "mts" objects (benchmark variable names are automatically inherited from the "mts" object).

Default value is val_cName = "value".

See Also

ts_to_tsDF() stack_bmkDF() benchmarking() stock_benchmarking() time_values_conv

Examples

# Annual and quarterly time series
my_ann_ts <- ts(1:5 * 100, start = 2019, frequency = 1)
my_ann_ts
my_qtr_ts <- ts(my_ann_ts, frequency = 4)
my_qtr_ts


# Annual benchmarks for a monthly indicator series
ts_to_bmkDF(my_ann_ts, ind_frequency = 12)

# Annual benchmarks for a quarterly indicator series
ts_to_bmkDF(my_ann_ts, ind_frequency = 4)

# Quarterly benchmarks for a monthly indicator series
ts_to_bmkDF(my_qtr_ts, ind_frequency = 12)

# Start of year stocks for a quarterly indicator series
ts_to_bmkDF(my_ann_ts, ind_frequency = 4, 
            discrete_flag = TRUE)

# End of quarter stocks for a monthly indicator series
ts_to_bmkDF(my_qtr_ts, ind_frequency = 12, 
            discrete_flag = TRUE, alignment = "e")

# April to March annual benchmarks for a ...
# ... monthly indicator series
ts_to_bmkDF(my_ann_ts, ind_frequency = 12, 
            bmk_interval_start = 4)
# ... quarterly indicator series
ts_to_bmkDF(my_ann_ts, ind_frequency = 4, 
            bmk_interval_start = 2)

# End-of-year (April to March) stocks for a ...
# ... monthly indicator series
ts_to_bmkDF(my_ann_ts, ind_frequency = 12, 
            discrete_flag = TRUE, alignment = "e", bmk_interval_start = 4)
# ... quarterly indicator series
ts_to_bmkDF(my_ann_ts, ind_frequency = 4,
            discrete_flag = TRUE, alignment = "e", bmk_interval_start = 2)

# Custom name for the benchmark data variable (column)
ts_to_bmkDF(my_ann_ts, ind_frequency = 12,
            val_cName = "bmk_val")

# Multiple time series: argument `val_cName` ignored
# (the "mts" object column names are always used)
ts_to_bmkDF(ts.union(ser1 = my_ann_ts, ser2 = my_ann_ts / 10), ind_frequency = 12,
            val_cName = "useless_column_name")