gs.build_proc_grps {gseries} | R Documentation |
Build reconciliation processing groups
Description
(version française: https://StatCan.github.io/gensol-gseries/fr/reference/gs.build_proc_grps.html)
This function builds the processing groups data frame for reconciliation problems. It is used internally by
tsraking_driver()
and tsbalancing()
.
Usage
gs.build_proc_grps(
ts_yr_vec,
ts_per_vec,
n_per,
ts_freq,
temporal_grp_periodicity,
temporal_grp_start
)
Arguments
ts_yr_vec |
(mandatory) Vector of the time series year (time unit) values (see |
ts_per_vec |
(mandatory) Vector of the time series period (cycle) values (see |
n_per |
(mandatory) Time series length (number of periods). |
ts_freq |
(mandatory) Time series frequency (see |
temporal_grp_periodicity |
(mandatory) Number of periods in temporal groups. |
temporal_grp_start |
(mandatory) First period of temporal groups. |
Value
A data frame with the following variables (columns):
-
grp
: integer vector identifying the processing group (1:<number-of-groups>
). -
beg_per
: integer vector identifying the first period of the processing group. -
end_per
: integer vector identifying the last period of the processing group. -
complete_grp
: logical vector indicating if the processing group corresponds to a complete temporal group.
Processing groups
The set of periods of a given reconciliation (raking or balancing) problem is called a processing group and either corresponds to:
a single period with period-by-period processing or, when preserving temporal totals, for the individual periods of an incomplete temporal group (e.g., an incomplete year)
or the set of periods of a complete temporal group (e.g., a complete year) when preserving temporal totals.
The total number of processing groups (total number of reconciliation problems) depends on the set of
periods in the input time series object (argument in_ts
) and on the value of arguments
temporal_grp_periodicity
and temporal_grp_start
.
Common scenarios include temporal_grp_periodicity = 1
(default) for period-by period processing without
temporal total preservation and temporal_grp_periodicity = frequency(in_ts)
for the preservation of annual
totals (calendar years by default). Argument temporal_grp_start
allows the specification of other types of
(non-calendar) years. E.g., fiscal years starting on April correspond to temporal_grp_start = 4
with monthly
data and temporal_grp_start = 2
with quarterly data. Preserving quarterly totals with monthly data would
correspond to temporal_grp_periodicity = 3
.
By default, temporal groups covering more than a year (i.e., corresponding to temporal_grp_periodicity > frequency(in_ts)
start on a
year that is a multiple of
ceiling(temporal_grp_periodicity / frequency(in_ts))
. E.g., biennial groups corresponding to temporal_grp_periodicity = 2 * frequency(in_ts)
start on an even year by default. This behaviour can be changed with argument temporal_grp_start
. E.g., the
preservation of biennial totals starting on an odd year instead of an even year (default) corresponds to
temporal_grp_start = frequency(in_ts) + 1
(along with temporal_grp_periodicity = 2 * frequency(in_ts)
).
See the gs.build_proc_grps()
Examples for common processing group scenarios.
See Also
tsraking_driver()
tsbalancing()
time_values_conv
Examples
#######
# Preliminary setup
# Dummy monthly and quarterly time series (2.5 years long)
mth_ts <- ts(rep(NA, 30), start = c(2019, 1), frequency = 12)
mth_ts
qtr_ts <- ts(rep(NA, 10), start = c(2019, 1), frequency = 4)
qtr_ts
# Summarized time series info
ts_info <- function(ts, sep = "-") {
list(y = gs.time2year(ts), # years
p = gs.time2per(ts), # periods
n = length(ts), # length
f = frequency(ts), # frequency
l = gs.time2str(ts, sep)) # labels
}
mth_info <- ts_info(mth_ts)
qtr_info <- ts_info(qtr_ts, sep = "q")
# Function to add a description label for the processing group
add_desc <- function(grp_df, lab_vec, word) {
grp_df$description <- ifelse(grp_df$complete_grp,
paste0("--- ", grp_df$end_per - grp_df$beg_per + 1, " ", word, "s: ",
lab_vec[grp_df$beg_per], " to ",
lab_vec[grp_df$end_per], " --- "),
paste0("--- 1 ", word, ": ", lab_vec[grp_df$beg_per], " ---"))
grp_df
}
#######
# Common processing group scenarios for monthly data
# 0- Month-by-month processing (every single month is a processing group)
mth_grps0 <- gs.build_proc_grps(mth_info$y, mth_info$p, mth_info$n, mth_info$f,
temporal_grp_periodicity = 1,
temporal_grp_start = 1)
tmp <- add_desc(mth_grps0, mth_info$l, "month")
head(tmp)
tail(tmp)
# Temporal groups corresponding to ...
# 1- calendar years
mth_grps1 <- gs.build_proc_grps(mth_info$y, mth_info$p, mth_info$n, mth_info$f,
temporal_grp_periodicity = 12,
temporal_grp_start = 1)
add_desc(mth_grps1, mth_info$l, "month")
# 2- fiscal years starting on April
mth_grps2 <- gs.build_proc_grps(mth_info$y, mth_info$p, mth_info$n, mth_info$f,
temporal_grp_periodicity = 12,
temporal_grp_start = 4)
add_desc(mth_grps2, mth_info$l, "month")
# 3- regular quarters (starting on Jan, Apr, Jul and Oct)
mth_grps3 <- gs.build_proc_grps(mth_info$y, mth_info$p, mth_info$n, mth_info$f,
temporal_grp_periodicity = 3,
temporal_grp_start = 1)
add_desc(mth_grps3, mth_info$l, "month")
# 4- quarters shifted by one month (starting on Feb, May, Aug and Nov)
mth_grps4 <- gs.build_proc_grps(mth_info$y, mth_info$p, mth_info$n, mth_info$f,
temporal_grp_periodicity = 3,
temporal_grp_start = 2)
add_desc(mth_grps4, mth_info$l, "month")
#######
# Common processing group scenarios for quarterly data
# 0- Quarter-by-quarter processing (every single quarter is a processing group)
qtr_grps0 <- gs.build_proc_grps(qtr_info$y, qtr_info$p, qtr_info$n, qtr_info$f,
temporal_grp_periodicity = 1,
temporal_grp_start = 1)
add_desc(qtr_grps0, qtr_info$l, "quarter")
# Temporal groups corresponding to ...
# 1- calendar years
qtr_grps1 <- gs.build_proc_grps(qtr_info$y, qtr_info$p, qtr_info$n, qtr_info$f,
temporal_grp_periodicity = 4,
temporal_grp_start = 1)
add_desc(qtr_grps1, qtr_info$l, "quarter")
# 2- fiscal years starting on April (2nd quarter)
qtr_grps2 <- gs.build_proc_grps(qtr_info$y, qtr_info$p, qtr_info$n, qtr_info$f,
temporal_grp_periodicity = 4,
temporal_grp_start = 2)
add_desc(qtr_grps2, qtr_info$l, "quarter")