diff --git a/DESCRIPTION b/DESCRIPTION index 0710c59..66e12b3 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -19,7 +19,7 @@ Imports: Remotes: github::rjdverse/rjd3toolkit SystemRequirements: Java (>= 17) -License: EUPL +License: EUPL | file LICENSE URL: https://github.com/rjdverse/rjd3bench, https://rjdverse.github.io/rjd3bench/ LazyData: TRUE diff --git a/R/adl.R b/R/adl.R index 0a82cad..4443e92 100644 --- a/R/adl.R +++ b/R/adl.R @@ -1,4 +1,4 @@ -#' Title +#' Temporal disaggregation of a time series with ADL models #' #' @param series #' @param constant diff --git a/R/benchmark.R b/R/benchmark.R index a37690e..5c9381e 100644 --- a/R/benchmark.R +++ b/R/benchmark.R @@ -3,20 +3,26 @@ NULL #' Benchmarking by means of the Denton method. #' -#' Denton method relies on the principle of movement preservation. There exist -#' a few variants corresponding to different definitions of movement -#' preservation: additive first difference (AFD), proportional first difference -#' (PFD), additive second difference (ASD), proportional second difference -#' (PSD), etc. The default and most widely adopted is the Denton PFD method. -#' -#' @param s Disaggregated series. If not NULL, it must be the same class as t. -#' @param t Aggregation constraint. Mandatory. it must be either an object of class ts or a numeric vector. +#' Denton method relies on the principle of movement preservation. There exist a +#' few variants corresponding to different definitions of movement preservation: +#' additive first difference (AFD), proportional first difference (PFD), +#' additive second difference (ASD), proportional second difference (PSD), etc. +#' The default and most widely used is the Denton PFD method. +#' +#' @param s Preliminary series. If not NULL, it must be the same class as t. +#' @param t Aggregation constraint. Mandatory. it must be either an object of +#' class ts or a numeric vector. #' @param d Integer. Differencing order. \code{1L} by default -#' @param mul Multiplicative or additive benchmarking. Multiplicative by default -#' @param nfreq Integer. Annual frequency of the disaggregated variable. Used if no disaggregated series is provided. -#' @param modified Modified (TRUE) or unmodified (FALSE) Denton. Modified by default -#' @param conversion Conversion rule. Usually "Sum" or "Average". Sum by default. -#' @param obsposition Integer. Position of the observation in the aggregated period (only used with "UserDefined" conversion) +#' @param mul Multiplicative or additive benchmarking. Multiplicative by +#' default. +#' @param nfreq Integer. Annual frequency of the disaggregated variable. Used if +#' no disaggregated series is provided. +#' @param modified Modified (\code{TRUE}) or unmodified (\code{FALSE}) Denton. +#' Modified by default. +#' @param conversion Conversion rule. Usually "Sum" or "Average". Sum by +#' default. +#' @param obsposition Integer. Position of the observation in the aggregated +#' period (only used with "UserDefined" conversion). #' @return The benchmarked series is returned #' #' @export @@ -26,13 +32,12 @@ NULL #' # denton PFD without high frequency series #' y1 <- rjd3bench::denton(t = Y, nfreq = 4) #' -#' # denton ASD -#' x1 <- y1+rnorm(n = length(y1), mean = 0, sd = 10) -#' y2 <- rjd3bench::denton(s = x1, t = Y, d = 2, mul = FALSE) +#' # denton PFD with high frequency series +#' x <- y1 + rnorm(n = length(y1), mean = 0, sd = 10) +#' y2 <- rjd3bench::denton(s = x, t = Y) #' -#' # denton PFD used for temporal disaggregation -#' x2 <- ts(qna_data$TURN_Q_data[,"TURN_INDEX_FF"], frequency = 4, start = c(2009,1)) -#' y3 <- rjd3bench::denton(s = x2, t = Y) +#' # denton ASD +#' y3 <- rjd3bench::denton(s = x, t = Y, d = 2, mul = FALSE) #' denton <- function(s = NULL, t, d = 1L, mul = TRUE, nfreq = 4L, modified = TRUE, conversion = c("Sum", "Average", "Last", "First", "UserDefined"), @@ -55,36 +60,55 @@ denton <- function(s = NULL, t, d = 1L, mul = TRUE, nfreq = 4L, modified = TRUE, #' Benchmarking following the growth rate preservation principle. #' -#' This method corresponds to the method of Cauley and Trager, using the solution -#' proposed by Di Fonzo and Marini. +#' GRP is a method which explicitly preserves the period-to-period growth rates +#' of the preliminary series. It corresponds to the method of Cauley and Trager +#' (1981), using the solution proposed by Di Fonzo and Marini (2011). BFGS is +#' used as line-search algorithm for the reduced unconstrained minimization +#' problem. #' -#' @param s Disaggregated series. Mandatory. It must be a ts object. +#' @param s Preliminary series. Mandatory. It must be a ts object. #' @param t Aggregation constraint. Mandatory. It must be a ts object. -#' @param conversion Conversion rule. Usually "Sum" or "Average". Sum by default. -#' @param obsposition Integer. Position of the observation in the aggregated period (only used with "UserDefined" conversion) -#' @param eps -#' @param iter Integer. -#' @param denton +#' @param conversion Conversion rule. "Sum" by default. +#' @param obsposition Integer. Position of the observation in the aggregated period +#' (only used with "UserDefined" conversion) +#' @param eps Numeric. Defines the convergence precision. BFGS algorithm +#' is run until the reduction in the objective is within this eps value +#' (1e-12 is the default) or until the maximum number of iterations is hit. +#' @param iter Integer. Maximum number of iterations in BFGS algorithm (500 is +#' the default). +#' @param dentoninitialization indicate whether the series benchmarked via +#' modified Denton PFD is used as starting values of the GRP optimization +#' procedure (TRUE/FALSE, TRUE by default). If FALSE, the average benchmark is +#' used for flow variables (e.g. t/4 for quarterly series with annual +#' constraints and conversion = 'Sum'), or the benchmark for stock variables. +#' +#' @return The benchmarked series is returned +#' @references Causey, B., and Trager, M.L. (1981). Derivation of Solution to +#' the Benchmarking Problem: Trend Revision. Unpublished research notes, U.S. +#' Census Bureau, Washington D.C. Available as an appendix in Bozik and Otto +#' (1988). +#' +#' Di Fonzo, T., and Marini, M. (2011). A Newton's Method for Benchmarking +#' Time Series according to a Growth Rates Preservation Principle. *IMF +#' WP/11/179*. #' -#' @return #' @export #' #' @examples #' data("qna_data") -#' Y <- ts(qna_data$B1G_Y_data[,"B1G_FF"], frequency = 1, start = c(2009,1)) -#' x <- ts(qna_data$TURN_Q_data[,"TURN_INDEX_FF"], frequency = 4, start = c(2009,1)) -#' y <- rjd3bench::grp(s = x, t = Y) +#' Y <- ts(qna_data$B1G_Y_data[, "B1G_FF"], frequency = 1, start = c(2009, 1)) +#' x <- rjd3bench::denton(t = Y, nfreq = 4) + rnorm(n = length(Y) * 4, mean = 0, sd = 10) +#' y_grp <- rjd3bench::grp(s = x, t = Y) #' grp <- function(s, t, - conversion = c("Sum", "Average", "Last", "First", "UserDefined"), - obsposition = 1L, eps = 1e-12, iter = 500L, denton = TRUE) { + conversion=c("Sum", "Average", "Last", "First", "UserDefined"), + obsposition=1, eps=1e-12, iter=500, dentoninitialization=TRUE){ conversion <- match.arg(conversion) - jd_s <- rjd3toolkit::.r2jd_tsdata(s) jd_t <- rjd3toolkit::.r2jd_tsdata(t) jd_rslt <- .jcall("jdplus/benchmarking/base/r/Benchmarking", "Ljdplus/toolkit/base/api/timeseries/TsData;", "grp", - jd_s, jd_t, conversion, as.integer(obsposition), eps, as.integer(iter), as.logical(denton)) + jd_s, jd_t, conversion, as.integer(obsposition), eps, as.integer(iter), as.logical(dentoninitialization)) rjd3toolkit::.jd2r_tsdata(jd_rslt) } @@ -105,7 +129,7 @@ grp <- function(s, t, #' @param conversion Conversion rule. Usually "Sum" or "Average". Sum by default. #' @param obsposition Integer. Postion of the observation in the aggregated period (only used with "UserDefined" conversion) #' -#' @return +#' @return The benchmarked series is returned #' @export #' #' @examples diff --git a/R/mbdenton.R b/R/mbdenton.R index e7e351b..3cd9c92 100644 --- a/R/mbdenton.R +++ b/R/mbdenton.R @@ -1,27 +1,37 @@ #' @include utils.R NULL -#' Temporal disaggregation of a time series by model-based Denton proportional method +#' Temporal disaggregation of a time series by model-based Denton proportional +#' method #' #' Denton proportional method can be expressed as a statistical model in a State #' space representation (see documentation for the definition of states). This #' approach is interesting as it allows more flexibility in the model such as #' the inclusion of outliers (level shift in the Benchmark to Indicator ratio) -#' that could otherwise induce unintended wave effects with standard Denton method. -#' Outliers and their intensity are defined by changing the value of the +#' that could otherwise induce unintended wave effects with standard Denton +#' method. Outliers and their intensity are defined by changing the value of the #' 'innovation variances'. #' -#' @param series Aggregation constraint. Mandatory. It must be either an object of class ts or a numeric vector. -#' @param indicator High-frequency indicator. Mandatory. It must be of same class as series -#' @param differencing Integer. Not implemented yet. Keep it equals to 1 (Denton PFD method). -#' @param conversion Conversion rule. Usually "Sum" or "Average". Sum by default. -#' @param conversion.obsposition Integer. Position of the observation in the aggregated period (only used with "UserDefined" conversion) -#' @param outliers a list of structured definition of the outlier periods and their intensity. The period must be submitted -#' first in the format YYYY-MM-DD and enclosed in quotation marks. This must be followed by an equal sign and -#' the intensity of the outlier, defined as the relative value of the 'innovation variances' (1 = normal situation) -#' @param fixedBIratios a list of structured definition of the periods where the BI ratios must be fixed. The period must be -#' submitted first in the format YYYY-MM-DD and enclosed in quotation marks. This must be followed by an -#' equal sign and the value of the BI ratio. +#' @param series Aggregation constraint. Mandatory. It must be either an object +#' of class ts or a numeric vector. +#' @param indicator High-frequency indicator. Mandatory. It must be of same +#' class as series +#' @param differencing Integer. Not implemented yet. Keep it equals to 1 (Denton +#' PFD method). +#' @param conversion Conversion rule. Usually "Sum" or "Average". Sum by +#' default. +#' @param conversion.obsposition Integer. Position of the observation in the +#' aggregated period (only used with "UserDefined" conversion) +#' @param outliers a list of structured definition of the outlier periods and +#' their intensity. The period must be submitted first in the format +#' YYYY-MM-DD and enclosed in quotation marks. This must be followed by an +#' equal sign and the intensity of the outlier, defined as the relative value +#' of the 'innovation variances' (1= normal situation) +#' @param fixedBIratios a list of structured definition of the periods where the +#' BI ratios must be fixed. The period must be submitted first in the format +#' YYYY-MM-DD and enclosed in quotation marks. This must be followed by an +#' equal sign and the value of the BI ratio. +#' #' @return an object of class 'JD3MBDenton' #' @export #' @@ -38,7 +48,9 @@ NULL #' x <- ts(qna_data$TURN_Q_data[,"TURN_INDEX_FF"], frequency = 4, start = c(2009,1)) #' #' td1 <- rjd3bench::denton_modelbased(Y, x) -#' td2 <- rjd3bench::denton_modelbased(Y, x, outliers = list("2020-04-01" = 100), fixedBIratios = list("2021-04-01" = 39.0)) +#' td2 <- rjd3bench::denton_modelbased(Y, x, +#' outliers = list("2020-04-01" = 100), +#' fixedBIratios = list("2021-04-01" = 39.0)) #' #' bi1 <- td1$estimation$biratio #' bi2 <- td2$estimation$biratio @@ -100,8 +112,8 @@ denton_modelbased <- function( #' Print function for object of class JD3MBDenton #' #' @param x an object of class JD3MBDenton +#' @param \dots further arguments passed to or from other methods. #' -#' @return #' @export #' #' @examples @@ -125,8 +137,8 @@ print.JD3MBDenton <- function(x, ...) { #' Summary function for object of class JD3MBDenton #' #' @param object an object of class JD3MBDenton +#' @param \dots further arguments passed to or from other methods. #' -#' @return #' @export #' #' @examples diff --git a/R/tempdisagg.R b/R/tempdisagg.R index bbef336..3fa4e3c 100644 --- a/R/tempdisagg.R +++ b/R/tempdisagg.R @@ -170,8 +170,8 @@ temporaldisaggregationI <- function(series, indicator, #' Print function for object of class JD3TempDisagg #' #' @param x an object of class JD3TempDisagg +#' @param \dots further arguments passed to or from other methods. #' -#' @return #' @export #' #' @examples @@ -195,8 +195,8 @@ print.JD3TempDisagg <- function(x, ...) { #' Print function for object of class JD3TempDisaggI #' #' @param x an object of class JD3TempDisaggI +#' @param \dots further arguments passed to or from other methods. #' -#' @return #' @export #' #' @examples @@ -221,8 +221,8 @@ print.JD3TempDisaggI <- function(x, ...) { #' Summary function for object of class JD3TempDisagg #' #' @param object an object of class JD3TempDisagg +#' @param \dots further arguments passed to or from other methods. #' -#' @return #' @export #' #' @examples @@ -238,8 +238,8 @@ summary.JD3TempDisagg <- function(object, ...) { #' Summary function for object of class JD3AdlDisagg #' #' @param object an object of class JD3AdlDisagg +#' @param \dots further arguments passed to or from other methods. #' -#' @return #' @export #' #' @examples @@ -287,8 +287,8 @@ summary_disagg <- function(object) { #' Summary function for object of class JD3TempDisaggI #' #' @param object an object of class JD3TempDisaggI +#' @param \dots further arguments passed to or from other methods. #' -#' @return #' @export #' #' @examples diff --git a/man/adl_disaggregation.Rd b/man/adl_disaggregation.Rd index 6a90007..1aaf5ca 100644 --- a/man/adl_disaggregation.Rd +++ b/man/adl_disaggregation.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/adl.R \name{adl_disaggregation} \alias{adl_disaggregation} -\title{Title} +\title{Temporal disaggregation of a time series with ADL models} \usage{ adl_disaggregation( series, @@ -21,7 +21,7 @@ adl_disaggregation( \item{xar}{} } \description{ -Title +Temporal disaggregation of a time series with ADL models } \examples{ # qna data, fernandez with/without quarterly indicator diff --git a/man/cubicspline.Rd b/man/cubicspline.Rd index 5631c7a..145d29f 100644 --- a/man/cubicspline.Rd +++ b/man/cubicspline.Rd @@ -23,6 +23,9 @@ cubicspline( \item{obsposition}{Integer. Postion of the observation in the aggregated period (only used with "UserDefined" conversion)} } +\value{ +The benchmarked series is returned +} \description{ Cubic splines are piecewise cubic functions that are linked together in a way to guarantee smoothness at data points. Additivity constraints are diff --git a/man/denton.Rd b/man/denton.Rd index 20d961b..4ba137a 100644 --- a/man/denton.Rd +++ b/man/denton.Rd @@ -16,31 +16,37 @@ denton( ) } \arguments{ -\item{s}{Disaggregated series. If not NULL, it must be the same class as t.} +\item{s}{Preliminary series. If not NULL, it must be the same class as t.} -\item{t}{Aggregation constraint. Mandatory. it must be either an object of class ts or a numeric vector.} +\item{t}{Aggregation constraint. Mandatory. it must be either an object of +class ts or a numeric vector.} \item{d}{Integer. Differencing order. \code{1L} by default} -\item{mul}{Multiplicative or additive benchmarking. Multiplicative by default} +\item{mul}{Multiplicative or additive benchmarking. Multiplicative by +default.} -\item{nfreq}{Integer. Annual frequency of the disaggregated variable. Used if no disaggregated series is provided.} +\item{nfreq}{Integer. Annual frequency of the disaggregated variable. Used if +no disaggregated series is provided.} -\item{modified}{Modified (TRUE) or unmodified (FALSE) Denton. Modified by default} +\item{modified}{Modified (\code{TRUE}) or unmodified (\code{FALSE}) Denton. +Modified by default.} -\item{conversion}{Conversion rule. Usually "Sum" or "Average". Sum by default.} +\item{conversion}{Conversion rule. Usually "Sum" or "Average". Sum by +default.} -\item{obsposition}{Integer. Position of the observation in the aggregated period (only used with "UserDefined" conversion)} +\item{obsposition}{Integer. Position of the observation in the aggregated +period (only used with "UserDefined" conversion).} } \value{ The benchmarked series is returned } \description{ -Denton method relies on the principle of movement preservation. There exist -a few variants corresponding to different definitions of movement -preservation: additive first difference (AFD), proportional first difference -(PFD), additive second difference (ASD), proportional second difference -(PSD), etc. The default and most widely adopted is the Denton PFD method. +Denton method relies on the principle of movement preservation. There exist a +few variants corresponding to different definitions of movement preservation: +additive first difference (AFD), proportional first difference (PFD), +additive second difference (ASD), proportional second difference (PSD), etc. +The default and most widely used is the Denton PFD method. } \examples{ Y <- ts(qna_data$B1G_Y_data$B1G_FF, frequency = 1, start = c(2009,1)) @@ -48,12 +54,11 @@ Y <- ts(qna_data$B1G_Y_data$B1G_FF, frequency = 1, start = c(2009,1)) # denton PFD without high frequency series y1 <- rjd3bench::denton(t = Y, nfreq = 4) -# denton ASD -x1 <- y1+rnorm(n = length(y1), mean = 0, sd = 10) -y2 <- rjd3bench::denton(s = x1, t = Y, d = 2, mul = FALSE) +# denton PFD with high frequency series +x <- y1 + rnorm(n = length(y1), mean = 0, sd = 10) +y2 <- rjd3bench::denton(s = x, t = Y) -# denton PFD used for temporal disaggregation -x2 <- ts(qna_data$TURN_Q_data[,"TURN_INDEX_FF"], frequency = 4, start = c(2009,1)) -y3 <- rjd3bench::denton(s = x2, t = Y) +# denton ASD +y3 <- rjd3bench::denton(s = x, t = Y, d = 2, mul = FALSE) } diff --git a/man/denton_modelbased.Rd b/man/denton_modelbased.Rd index 130cad7..ffb0d93 100644 --- a/man/denton_modelbased.Rd +++ b/man/denton_modelbased.Rd @@ -2,7 +2,8 @@ % Please edit documentation in R/mbdenton.R \name{denton_modelbased} \alias{denton_modelbased} -\title{Temporal disaggregation of a time series by model-based Denton proportional method} +\title{Temporal disaggregation of a time series by model-based Denton proportional +method} \usage{ denton_modelbased( series, @@ -15,22 +16,30 @@ denton_modelbased( ) } \arguments{ -\item{series}{Aggregation constraint. Mandatory. It must be either an object of class ts or a numeric vector.} +\item{series}{Aggregation constraint. Mandatory. It must be either an object +of class ts or a numeric vector.} -\item{indicator}{High-frequency indicator. Mandatory. It must be of same class as series} +\item{indicator}{High-frequency indicator. Mandatory. It must be of same +class as series} -\item{differencing}{Integer. Not implemented yet. Keep it equals to 1 (Denton PFD method).} +\item{differencing}{Integer. Not implemented yet. Keep it equals to 1 (Denton +PFD method).} -\item{conversion}{Conversion rule. Usually "Sum" or "Average". Sum by default.} +\item{conversion}{Conversion rule. Usually "Sum" or "Average". Sum by +default.} -\item{conversion.obsposition}{Integer. Position of the observation in the aggregated period (only used with "UserDefined" conversion)} +\item{conversion.obsposition}{Integer. Position of the observation in the +aggregated period (only used with "UserDefined" conversion)} -\item{outliers}{a list of structured definition of the outlier periods and their intensity. The period must be submitted -first in the format YYYY-MM-DD and enclosed in quotation marks. This must be followed by an equal sign and -the intensity of the outlier, defined as the relative value of the 'innovation variances' (1 = normal situation)} +\item{outliers}{a list of structured definition of the outlier periods and +their intensity. The period must be submitted first in the format +YYYY-MM-DD and enclosed in quotation marks. This must be followed by an +equal sign and the intensity of the outlier, defined as the relative value +of the 'innovation variances' (1= normal situation)} -\item{fixedBIratios}{a list of structured definition of the periods where the BI ratios must be fixed. The period must be -submitted first in the format YYYY-MM-DD and enclosed in quotation marks. This must be followed by an +\item{fixedBIratios}{a list of structured definition of the periods where the +BI ratios must be fixed. The period must be submitted first in the format +YYYY-MM-DD and enclosed in quotation marks. This must be followed by an equal sign and the value of the BI ratio.} } \value{ @@ -41,8 +50,8 @@ Denton proportional method can be expressed as a statistical model in a State space representation (see documentation for the definition of states). This approach is interesting as it allows more flexibility in the model such as the inclusion of outliers (level shift in the Benchmark to Indicator ratio) -that could otherwise induce unintended wave effects with standard Denton method. -Outliers and their intensity are defined by changing the value of the +that could otherwise induce unintended wave effects with standard Denton +method. Outliers and their intensity are defined by changing the value of the 'innovation variances'. } \examples{ @@ -58,7 +67,9 @@ Y <- ts(qna_data$B1G_Y_data[,"B1G_FF"], frequency = 1, start = c(2009,1)) x <- ts(qna_data$TURN_Q_data[,"TURN_INDEX_FF"], frequency = 4, start = c(2009,1)) td1 <- rjd3bench::denton_modelbased(Y, x) -td2 <- rjd3bench::denton_modelbased(Y, x, outliers = list("2020-04-01" = 100), fixedBIratios = list("2021-04-01" = 39.0)) +td2 <- rjd3bench::denton_modelbased(Y, x, + outliers = list("2020-04-01" = 100), + fixedBIratios = list("2021-04-01" = 39.0)) bi1 <- td1$estimation$biratio bi2 <- td2$estimation$biratio diff --git a/man/grp.Rd b/man/grp.Rd index b5e25dc..42e13ed 100644 --- a/man/grp.Rd +++ b/man/grp.Rd @@ -8,33 +8,59 @@ grp( s, t, conversion = c("Sum", "Average", "Last", "First", "UserDefined"), - obsposition = 1L, + obsposition = 1, eps = 1e-12, - iter = 500L, - denton = TRUE + iter = 500, + dentoninitialization = TRUE ) } \arguments{ -\item{s}{Disaggregated series. Mandatory. It must be a ts object.} +\item{s}{Preliminary series. Mandatory. It must be a ts object.} \item{t}{Aggregation constraint. Mandatory. It must be a ts object.} -\item{conversion}{Conversion rule. Usually "Sum" or "Average". Sum by default.} +\item{conversion}{Conversion rule. "Sum" by default.} -\item{obsposition}{Integer. Position of the observation in the aggregated period (only used with "UserDefined" conversion)} +\item{obsposition}{Integer. Position of the observation in the aggregated period +(only used with "UserDefined" conversion)} -\item{iter}{Integer.} +\item{eps}{Numeric. Defines the convergence precision. BFGS algorithm +is run until the reduction in the objective is within this eps value +(1e-12 is the default) or until the maximum number of iterations is hit.} -\item{denton}{} +\item{iter}{Integer. Maximum number of iterations in BFGS algorithm (500 is +the default).} + +\item{dentoninitialization}{indicate whether the series benchmarked via +modified Denton PFD is used as starting values of the GRP optimization +procedure (TRUE/FALSE, TRUE by default). If FALSE, the average benchmark is +used for flow variables (e.g. t/4 for quarterly series with annual +constraints and conversion = 'Sum'), or the benchmark for stock variables.} +} +\value{ +The benchmarked series is returned } \description{ -This method corresponds to the method of Cauley and Trager, using the solution -proposed by Di Fonzo and Marini. +GRP is a method which explicitly preserves the period-to-period growth rates +of the preliminary series. It corresponds to the method of Cauley and Trager +(1981), using the solution proposed by Di Fonzo and Marini (2011). BFGS is +used as line-search algorithm for the reduced unconstrained minimization +problem. } \examples{ data("qna_data") -Y <- ts(qna_data$B1G_Y_data[,"B1G_FF"], frequency = 1, start = c(2009,1)) -x <- ts(qna_data$TURN_Q_data[,"TURN_INDEX_FF"], frequency = 4, start = c(2009,1)) -y <- rjd3bench::grp(s = x, t = Y) +Y <- ts(qna_data$B1G_Y_data[, "B1G_FF"], frequency = 1, start = c(2009, 1)) +x <- rjd3bench::denton(t = Y, nfreq = 4) + rnorm(n = length(Y) * 4, mean = 0, sd = 10) +y_grp <- rjd3bench::grp(s = x, t = Y) + +} +\references{ +Causey, B., and Trager, M.L. (1981). Derivation of Solution to + the Benchmarking Problem: Trend Revision. Unpublished research notes, U.S. + Census Bureau, Washington D.C. Available as an appendix in Bozik and Otto + (1988). + Di Fonzo, T., and Marini, M. (2011). A Newton's Method for Benchmarking + Time Series according to a Growth Rates Preservation Principle. *IMF + WP/11/179*. } diff --git a/man/print.JD3MBDenton.Rd b/man/print.JD3MBDenton.Rd index ae8d216..1870705 100644 --- a/man/print.JD3MBDenton.Rd +++ b/man/print.JD3MBDenton.Rd @@ -8,6 +8,8 @@ } \arguments{ \item{x}{an object of class JD3MBDenton} + +\item{\dots}{further arguments passed to or from other methods.} } \description{ Print function for object of class JD3MBDenton diff --git a/man/print.JD3TempDisagg.Rd b/man/print.JD3TempDisagg.Rd index 08ec4e2..9cf3374 100644 --- a/man/print.JD3TempDisagg.Rd +++ b/man/print.JD3TempDisagg.Rd @@ -8,6 +8,8 @@ } \arguments{ \item{x}{an object of class JD3TempDisagg} + +\item{\dots}{further arguments passed to or from other methods.} } \description{ Print function for object of class JD3TempDisagg diff --git a/man/print.JD3TempDisaggI.Rd b/man/print.JD3TempDisaggI.Rd index b759184..9a58d33 100644 --- a/man/print.JD3TempDisaggI.Rd +++ b/man/print.JD3TempDisaggI.Rd @@ -8,6 +8,8 @@ } \arguments{ \item{x}{an object of class JD3TempDisaggI} + +\item{\dots}{further arguments passed to or from other methods.} } \description{ Print function for object of class JD3TempDisaggI diff --git a/man/summary.JD3AdlDisagg.Rd b/man/summary.JD3AdlDisagg.Rd index fa87745..b9761fd 100644 --- a/man/summary.JD3AdlDisagg.Rd +++ b/man/summary.JD3AdlDisagg.Rd @@ -8,6 +8,8 @@ } \arguments{ \item{object}{an object of class JD3AdlDisagg} + +\item{\dots}{further arguments passed to or from other methods.} } \description{ Summary function for object of class JD3AdlDisagg diff --git a/man/summary.JD3MBDenton.Rd b/man/summary.JD3MBDenton.Rd index 81803cf..203c28d 100644 --- a/man/summary.JD3MBDenton.Rd +++ b/man/summary.JD3MBDenton.Rd @@ -8,6 +8,8 @@ } \arguments{ \item{object}{an object of class JD3MBDenton} + +\item{\dots}{further arguments passed to or from other methods.} } \description{ Summary function for object of class JD3MBDenton diff --git a/man/summary.JD3TempDisagg.Rd b/man/summary.JD3TempDisagg.Rd index 7587045..e7400a7 100644 --- a/man/summary.JD3TempDisagg.Rd +++ b/man/summary.JD3TempDisagg.Rd @@ -8,6 +8,8 @@ } \arguments{ \item{object}{an object of class JD3TempDisagg} + +\item{\dots}{further arguments passed to or from other methods.} } \description{ Summary function for object of class JD3TempDisagg diff --git a/man/summary.JD3TempDisaggI.Rd b/man/summary.JD3TempDisaggI.Rd index b1cea42..c106edc 100644 --- a/man/summary.JD3TempDisaggI.Rd +++ b/man/summary.JD3TempDisaggI.Rd @@ -8,6 +8,8 @@ } \arguments{ \item{object}{an object of class JD3TempDisaggI} + +\item{\dots}{further arguments passed to or from other methods.} } \description{ Summary function for object of class JD3TempDisaggI diff --git a/vignettes/rjd3bench.Rmd b/vignettes/rjd3bench.Rmd index cc70ee3..93fd6a9 100644 --- a/vignettes/rjd3bench.Rmd +++ b/vignettes/rjd3bench.Rmd @@ -11,13 +11,17 @@ vignette: > %\VignetteIndexEntry{Temporal disaggregation and Benchmarking methods based on JDemetra+ v3.x} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} -abstract: The package **rjd3bench** provides a variety of methods for temporal disaggregation, benchmarking, reconciliation and calendarization. It is part of the interface to 'JDemetra+ 3.0' Seasonal adjustement software. Methods of temporal disaggregation and benchmarking are used to derive high frequency time series from low frequency time series with or without the help of high frequency information. Consistency of the high frequency series with the low frequency series can be achieved by either the sum, the average, the first or last value or any other user-defined conversion mode. In addition to temporal constraints, reconciliation methods deals with contemporaneous consistency while adjusting multiple time series. Finally, calendarization method can be used when time series data do not coincide with calendar periods. +abstract: The package rjd3bench provides a variety of methods for temporal disaggregation, benchmarking, reconciliation and calendarization. It is part of the interface to 'JDemetra+ 3.0' Seasonal adjustement software. Methods of temporal disaggregation and benchmarking are used to derive high frequency time series from low frequency time series with or without the help of high frequency information. Consistency of the high frequency series with the low frequency series can be achieved by either the sum, the average, the first or last value or any other user-defined conversion mode. In addition to temporal constraints, reconciliation methods deals with contemporaneous consistency while adjusting multiple time series. Finally, calendarization method can be used when time series data do not coincide with calendar periods. +compress_html: + clippings: all + blanklines: true --- -```{r setup vignette, include = FALSE} +```{r setup_vignette, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, eval = FALSE, + echo = TRUE, comment = "#>" ) ``` @@ -25,130 +29,191 @@ knitr::opts_chunk$set( # Introduction -The methods implemented in the package **rjd3bench** intend to bridge the gap when there is a lack of high frequency time series or when there are temporal and/or contemporaneous inconsistencies between the high frequency series and the corresponding low frequency series, the latter being the benchmark. Although this can be an issue in any fields of research dealing with time series, methods of temporal disaggregation, benchmarking, reconciliation and calendarization are mostly used in official statistics, especially in the production of macroeconomic statistics. For example, National Accounts are often compiled according to two frequencies of production: annual series, the low frequency data, based on precise and detailed sources and quarterly series, the high frequency data, which usually rely on less accurate sources but give information on a timelier basis. The use of temporal disaggregation, benchmarking, reconciliation or calendarization methods allow to achieve consistency between annual and quarterly national accounts over time. +The methods implemented in the package rjd3bench intend to bridge the gap when there is a lack of high frequency time series or when there are temporal and/or contemporaneous inconsistencies between the high frequency series and the corresponding low frequency series. Although this can be an issue in any fields of research dealing with time series, methods of temporal disaggregation, benchmarking, reconciliation and calendarization are often encountered in the production of official statistics. For example, National Accounts are often compiled according to two frequencies of production: annual series, the low frequency data, based on precise and detailed sources and quarterly series, the high frequency data, which usually rely on less accurate sources but give information on a timelier basis. In such case, the use of temporal disaggregation, benchmarking, and/or reconciliation method can be used to achieve consistency between annual and quarterly national accounts over time. -The package is an R interface to the highly efficient algorithms and modeling developed in the official 'JDemetra+ 3.0' Seasonal adjustement software. It provides a wide variety of methods and intend to include those suggested in the *ESS guidelines on temporal disaggregation, benchmarking and reconciliation (Eurostat, 2018)*. +The package rjd3bench is an R interface to the highly efficient algorithms and modeling developed in the official 'JDemetra+ 3.0' Seasonal adjustement software. It provides a wide variety of methods, included those suggested in the *ESS guidelines on temporal disaggregation, benchmarking and reconciliation (Eurostat, 2018)*. -# Data +# Set-up & Data -We illustrate the various methods using two sets of time series: +We illustrate the various methods using two datasets: -* The **retail** data set contains monthly figures over retail activity of various categories of goods and services from 1992 to 2010. -* The **qna_data** contains a list of two data sets. The first data set 'B1G_Y_data' includes three annual benchmark series which are the Belgian annual value added on the period 2009-2020 in chemical industry (CE), construction (FF) and transport services (HH). The second data set 'TURN_Q_data' includes the corresponding quarterly indicators which are (modified) production indicators derived from VAT statistics and covering the period 2009Q1-2021Q4. +* The *retail* dataset contains monthly figures over retail activity of various categories of goods and services from 1992 to 2010. +* The *qna_data* is a list of two datasets. The first data set 'B1G_Y_data' includes three annual benchmark series which are the Belgian annual value added on the period 2009-2020 in chemical industry (CE), construction (FF) and transport services (HH). The second data set 'TURN_Q_data' includes the corresponding quarterly indicators which are (modified) production indicators derived from VAT statistics and covering the period 2009Q1-2021Q4. -```{r data, echo = TRUE, eval = FALSE} -library("rjd3toolkit") # for **retail** data -data("qna_data") +```{r} +library("rjd3bench") +retail <- rjd3toolkit::retail +qna_data <- rjd3bench::qna_data ``` -# Application of methods -```{r package loading, echo = TRUE, eval = FALSE} -library("rjd3bench") -``` +# Temporal disaggregation methods + +## Chow-Lin, Fernandez and Litterman + +Eurostat (2018) recommends the use of regression-based models for the purpose of temporal disaggregation. Among them, we retrieve the Chow-Lin method and its variants Fernandez and Litterman. -## Temporal disaggregation +Let $Y_T$, $T=1,...,m$, and $x_t$, $t=1,...,n$, be, respectively the observed low frequency benchmark and the high-frequency indicator of an unknown high frequency variable $y_t$. Chow-Lin, Fernandez and Litterman can be all expressed with the same equation, but with different models for the error term: +$$ +y_t = x_t\beta+u_t +$$ +where -### Chow-Lin, Fernandez and Litterman regression methods +$u_t = \phi u_{t-1} + \epsilon_t$, with $|\phi| < 1$ (Chow-Lin), -Eurostat (2018) recommends the use of regression-based models for the purpose of temporal disaggregation. Among them, Chow-Lin method and its variants proposed by Fernandez and Litterman are largely used in practice. Those can be called through the **temporaldisaggregation()** function in the **rjd3bench** package. +$u_t = u_{t-1} + \epsilon_t$ (Fernandez), -Here is an example of code to use Fernandez variant as method to disaggregate annual value added in construction sector using a quarterly production index as indicator. -```{r chow_lin example, echo = TRUE, eval = FALSE} -Y <- ts(qna_data$B1G_Y_data[, "B1G_FF"], frequency = 1L, start = c(2009L, 1L)) -x <- ts(qna_data$TURN_Q_data[, "TURN_INDEX_FF"], frequency = 4L, start = c(2009L, 1L)) -td_cl <- rjd3bench::temporaldisaggregation(Y, indicators = x, model = "Rw") -y_cl <- td_cl$estimation$disagg # the disaggregated series -``` +$u_t = u_{t-1} + \phi(\Delta u_{t-1}) + \epsilon_t$, with $|\phi| < 1$ (Litterman) -The variable *td_cl* is of class **'JD3TempDisagg'** and contains the most important information about the regression including the estimates of model coefficients and their covariance matrix, the decomposition of the disaggregated series and information about the likelihood. There exist a specific print(), summary() and plot() functions for objects of class **'JD3TempDisagg'**. print() shows the fitted model, summary() also shows extra information about the model and the likelihood. plot() displays the decomposition of the disaggregated series between regression and the smoothing effect. +While $x_t$ is observed in high frequency, $y_t$ is only observed in low frequency, and therefore the number of effective observations to estimate the parameters are the number of observations in the low-frequency benchmark. +Regression-based methods can be called with the `temporaldisaggregation()` function. +```{r} +# Example: Use of Fernandez variant to disaggregate annual value added in construction sector using a quarterly indicator +Y <- ts(qna_data$B1G_Y_data[, "B1G_FF"], frequency=1, start=c(2009, 1)) +x <- ts(qna_data$TURN_Q_data[, "TURN_INDEX_FF"], frequency=4, start=c(2009, 1)) +td_fern <- rjd3bench::temporaldisaggregation(Y, indicators=x, model = "Rw") -```{r chow_lin example cont, echo = TRUE, eval = FALSE, fig.width=6} -summary(td_cl) # example of call to summary() -plot(td_cl) +y_fern <- td_fern$estimation$disagg # the disaggregated series +summary(td_fern) +plot(td_fern) ``` -### Model-based Denton +The output of the `temporaldisaggregation()` function contains the most important information about the regression including the estimates of model coefficients and their covariance matrix, the decomposition of the disaggregated series and information about the residuals. The print(), summary() and plot() functions can also be applied on the output object. The plot() function displays the decomposition of the disaggregated series between regression and smoothing effect. + + +## Model-based Denton Denton method and variants are usually expressed in mathematical terms as a constrained minimization problem. For example, the widely used Denton proportional first difference (PFD) method is usually expressed as follows: $$ min_{y_t}\sum^n_{t=2}\biggl[\frac{y_t}{x_t}-\frac{y_{t-1}}{x_{t-1}}\biggr]^2 $$ -subject to the temporal constraint +subject to the temporal constraint (flow variables) $$ -\sum_{t} y_t = Y_y +\sum_{t} y_t = Y_T $$ -where $y_t$ is the value of the estimate of the high frequency series at period t, $x_t$ is the value of the high frequency indicator at period t and $Y_y$ is the value of the annual low frequency series (the benchmark series) at period y. +where $y_t$ is the value of the estimate of the high frequency series at period t, $x_t$ is the value of the high frequency indicator at period t and $Y_T$ is the value of the low frequency series (i.e. the benchmark series) at period T. Equivalently, the Denton PFD method can also be expressed as a statistical model considering the following state space representation + $$ \begin{aligned} y_t &= \beta_t x_t \\ \beta_{t+1} &= \beta_t + \varepsilon_t \qquad \varepsilon_t \sim {\sf NID}(0, \sigma^2_{\varepsilon}) \end{aligned} $$ -where the annual constraint are taken care of by considering a cumulated series $y^c_t$ instead of the original series $y_t$. Hence, the last high frequency period (for example, the last quarter of the year) is observed and corresponds to the value of the benchmark. The value of the other periods are initially defined as missing and estimated by maximum likelihood. -This alternative representation of Denton PFD method is interesting as it allows more flexibility in the model such as the inclusion of outliers (level shift in the Benchmark to Indicator ratio) - that could otherwise induce unintended wave effects - and the possibility to fix the BI ratio (and therefore also the disaggregated) at some specific periods. Outliers and their intensity are defined by changing the value of the 'innovation variances'. Following the principle of movement preservation inherent to Denton, the model-based Denton PFD method constitutes an interesting alternative for temporal disaggregation, giving a thorough analysis of the data (and the Benchmark-to-Indicator (BI) ratio in particular) and a clear strategy for extrapolation. +where the temporal constraints are taken care of by considering a cumulated series $y^c_t$ instead of the original series $y_t$. Hence, the last high frequency period (for example, the last quarter of the year) is observed and corresponds to the value of the benchmark. The value of the other periods are initially defined as missing and estimated by maximum likelihood. + + +This alternative representation of Denton PFD method is interesting as it allows more flexibility. We might now include outliers - namely, level shift(s) in the Benchmark to Indicator ratio - that could otherwise induce undesirable wave effects. Outliers and their intensity are defined by changing the value of the innovation variances. There is also the possibility to freeze the disaggregated series at some specific period(s) or prior a certain date by fixing the high-frequency BI ratio(s). Following the principle of movement preservation inherent to Denton, the model-based Denton PFD method constitutes an interesting alternative for both temporal disaggregation and benchmarking. Here is a [link](https://www.youtube.com/watch?v=PC0tj2jMcuU) to a presentation on the subject which include some comparison with the regression-based methods for temporal disaggregation. + +The model-base Denton method can be applied with the `denton_modelbased()` function. +```{r} +# Example: Use of model-based Denton for temporal disaggregation +Y <- ts(qna_data$B1G_Y_data[, "B1G_FF"], frequency=1, start=c(2009, 1)) +x <- ts(qna_data$TURN_Q_data[, "TURN_INDEX_FF"], frequency=4, start=c(2009, 1)) +td_mbd <- rjd3bench::denton_modelbased(Y, x, outliers = list("2020-01-01"=100, "2020-04-01"=100)) -Model-based denton can be called through the **denton.modelbased()** function. Here is an example of code to apply it to the same data as before. -```{r mb_denton example, echo = TRUE, eval = FALSE} -td_mbd <- rjd3bench::denton_modelbased(Y, x, outliers = list("2020-01-01" = 100., "2020-04-01" = 100.)) y_mbd <- td_mbd$estimation$disagg plot(td_mbd) ``` -The variable *td_mbd* is of class **'JD3MBDenton'** and contains information about the disaggregated series and the BI ratio as well as their respecting errors making it possible to construct confidence intervals (see plot() function). There exist a specific print(), summary() and plot() functions for objects of class **'JD3MBDenton'**. print() shows the output available, summary() also shows extra information about the model and the likelihood. plot() displays the disaggregated series and the BI ratio together with their respective 95% confidence interval. +The output of the `denton_modelbased()` function contains information about the disaggregated series and the BI ratio as well as their respecting errors making it possible to construct confidence intervals. The print(), summary() and plot() functions can also be applied on the output object.The plot() function displays the disaggregated series and the BI ratio together with their respective 95% confidence interval. + +## Autoregressive Distributed Lag (ADL) Models -## Benchmarking +(Upcoming content) -### Denton method -Denton method relies on the principle of movement preservation. There exist a few variants corresponding to different definitions of movement -preservation: additive first difference (AFD), proportional first difference (PFD), additive second difference (ASD), proportional second difference (PSD), etc. The different variants can be called through the **denton()** function in the **rjd3bench** package. +# Benchmarking methods -Here are a few examples using the table 'B1G_Y_data' from **qna_data**: -```{r denton example, echo = TRUE, eval = FALSE} -Y <- ts(qna_data$B1G_Y_data[, "B1G_HH"], frequency = 1L, start = c(2009L, 1L)) +## Denton -y_d1 <- rjd3bench::denton(t = Y, nfreq = 4L) # example of denton PFD without high frequency series +Denton methods relies on the principle of movement preservation. There exist several variants corresponding to different definitions of movement preservation: additive first difference (AFD), proportional first difference (PFD), additive second difference (ASD), proportional second difference (PSD). + +The most widely used is the Denton PFD variant. Let $Y_T$, $T=1,...,m$, and $x_t$, $t=1,...,n$, be, respectively the temporal benchmarks and the high-frequency preliminary values of an unknown target variable $y_t$. The objective function of the Denton PFD method is as follows (considering the small modification suggested by Cholette to deal with the starting conditions of the problem): +$$ +min_{y_t}\sum^n_{t=2}\biggl[\frac{y_t}{x_t}-\frac{y_{t-1}}{x_{t-1}}\biggr]^2 +$$ +This objective function is minimized subject to the temporal aggregation constraints $\sum_{t\epsilon T}=Y_T$, $T=1,...,m$ (flows variables). In other words, the benchmarked series is estimated in such a way that the "Benchmark-to-Indicator" ratio $\frac{y_t}{x_t}$ remains as smooth as possible, which is often of key interest in benchmarking. -x <- y_d1 + rnorm(n = length(y_d1), mean = 0., sd = 10.) -y_d2 <- rjd3bench::denton(s = x, t = Y, d = 2L, mul = FALSE) # example of denton ASD. Note that the default is d=1 and mul=T corresponding to denton PFD +In the literature (see for example Di Fonzo and Marini, 2011), Denton PFD is generally considered as a good approximation of the [GRP method](#grp), meaning that it preserves the period-to-period growth rates of the preliminary series. It is also argued that in many applications, Denton PFD is more appropriate than GRP method as it deals with a linear problem which is computationally easier, and does not suffer from the issues related to time irreversibility and singular objective function when $y_t$ approaches 0 (see Daalmans et al, 2018). + +Denton methods can be called with the `denton()` function. +```{r} +# Example: use Denton method for benchmarking +Y <- ts(qna_data$B1G_Y_data[, "B1G_HH"], frequency=1, start=c(2009, 1)) + +y_den0 <- rjd3bench::denton(t=Y, nfreq=4) # denton PFD without high frequency series + +x <- y_den0 + rnorm(n=length(y_den0), mean=0, sd=10) +y_den1 <- rjd3bench::denton(s=x, t=Y) # denton PFD (= the default) +y_den2 <- rjd3bench::denton(s=x, t=Y, d=2, mul=FALSE) # denton ASD ``` -The **denton()** function returns the high frequency series benchmarked with denton method. +The `denton()` function returns the benchmarked high frequency series. + +## Growth rate preservation (GRP) {#grp} + +GRP explicitly preserves the period-to-period growth rates of the preliminary series. + +Let $Y_T$, $T=1,...,m$, and $x_t$, $t=1,...,n$, be, respectively the temporal benchmarks and the high-frequency preliminary values of an unknown target variable $y_t$. Cauley and Trager(1981) consider the following objective function: + +$$ +f(x) = \sum_{t=2}^{n}\left(\frac{y_t}{y_{t-1}} - \frac{x_t}{x_{t-1}}\right)^2 +$$ +and look for values $y_t^*$, $t=1,...,n$, which minimize it subject to the temporal aggregation constraints $\sum_{t\epsilon T}=Y_T$, $T=1,...,m$ (flows variables). In other words, the benchmarked series is estimated in such a way that its temporal dynamics; as expressed by the growth rates $\frac{y_t^*}{y_{t-1}^*}$, $t=2,...,n$, be "as close as possible" to the temporal dynamics of the preliminary series, where the "distance" from the preliminary growth rates $\frac{x_t}{x_{t-1}}$ is given by the sum of the squared differences. (Di Fonzo, Marini, 2011) + +The objective function considered by Cauley and Trager is a natural measure of the movement of a time series and as one would expect, it is usually slightly better than the Denton PFD method at preserving the movement of the series (Di Fonzo, Marini, 2011). However, unlike the Denton PFD method which deals with a linear problem, GRP solves a more difficult nonlinear problem. Furthermore, the GRP method suffers from a couple of drawbacks, which are time irreversibility and potential singularities in the objective function when $y_{t-1}$ approaches to 0, which could lead to undesirable results (see Daalmans et al, 2018). -### Growth rate preservation (GRP) method +The GRP method, corresponding to the method of Cauley and Trager, using the solution proposed by Di Fonzo and Marini (2011), can be called with the `grp()` function. -This method corresponds to the method of Cauley and Trager, using the solution proposed by Di Fonzo and Marini. It can be called through the **grp()** function. +```{r} +# Example: use GRP method for benchmarking +Y <- ts(qna_data$B1G_Y_data[, "B1G_HH"], frequency=1, start=c(2009, 1)) +y_den0 <- rjd3bench::denton(t=Y, nfreq=4) +x <- y_den0 + rnorm(n=length(y_den0), mean=0, sd=10) -Here is an example on how to use it: -```{r grp example, echo = TRUE, eval = FALSE} -y_grp <- rjd3bench::grp(s = x, t = Y) +y_grp <- rjd3bench::grp(s=x, t=Y) ``` -The **grp()** function returns the high frequency series benchmarked with grp method. +The `grp()` function returns the high frequency series benchmarked with the GRP method. -### Cubic splines +## Cubic splines Cubic splines are piecewise cubic functions that are linked together in a way to guarantee smoothness at data points. Additivity constraints are added for benchmarking purpose and sub-period estimates are derived from each spline. When a sub-period indicator (or disaggregated series) is used, cubic splines are no longer drawn based on the low frequency data but the Benchmark-to-Indicator (BI ratio) is the one being smoothed. Sub-period estimates are then simply the product between the smoothed high frequency BI ratio and the indicator. -The method can be called through the **cubicspline()** function. Here are a few examples on how to use it: -```{r cubicspline example, echo = TRUE, eval = FALSE} -y_cs1 <- rjd3bench::cubicspline(t = Y, nfreq = 4L) # example of cubic spline without high frequency series (smoothing) +The method can be called through the `cubicspline()` function. Here are a few examples on how to use it: +```{r} +y_cs1 <- rjd3bench::cubicspline(t = Y, nfreq = 4) # example of cubic spline without high frequency series (smoothing) x <- y_cs1 + rnorm(n = length(y_cs1), mean = 0., sd = 10.) y_cs2 <- rjd3bench::cubicspline(s = x, t = Y) # example of cubic spline with a high frequency series to benchmark ``` -The **cubicspline()** function returns the high frequency series benchmarked with cubic spline method. +The `cubicspline()` function returns the high frequency series benchmarked with cubic spline method. + +## Cholette method + +(Upcoming content) + +# Reconciliation and multivariate temporal disaggregation + +## Multivariate Cholette + +(Upcoming content) + +# Calendarization + +(Upcoming content) + +# References -### Cholette method +Causey, B., and Trager, M.L. (1981). Derivation of Solution to the Benchmarking Problem: Trend Revision. Unpublished research notes, U.S. Census Bureau, Washington D.C. Available as an appendix in Bozik and Otto (1988). -## Reconciliation and multivariate temporal disaggregation +Chamberlin, G. (2010). Temporal disaggregation. *ONS Economic & Labour Market Review*. -### Multivariate Cholette +Di Fonzo, T., and Marini, M. (2011). A Newton's Method for Benchmarking Time Series according to a Growth Rates Preservation Principle. *IMF WP/11/179*. -## Calendarization +Daalmans, J., Di Fonzo, T., Mushkudiani, N., Bikker, R. (2018). Growth Rates Preservation (GRP) temporal benchmarking: Drawbacks and alternative solutions. *Survey Methodology, June 2018 Vol.44, No.1, pp. 43-60 Statistics Canada, Catalogue No. 12-001-X*.