update grp and denton doc

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

R/adl.R

@@ -1,4 +1,4 @@
-#' Title
+#' Temporal disaggregation of a time series with ADL models
 #'
 #' @param series
 #' @param constant

R/benchmark.R

@@ -3,36 +3,41 @@ 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.
-#' @param d Differencing order. 1 by default
-#' @param mul Multiplicative or additive benchmarking. Multiplicative by default
-#' @param nfreq 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 Position of the observation in the aggregated period (only used with "UserDefined" conversion)
+#' 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 Differencing order. 1 by default.
+#' @param mul Multiplicative or additive benchmarking. Multiplicative by
+#'   default.
+#' @param nfreq 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 Position of the observation in the aggregated period (only
+#'   used with "UserDefined" conversion).
 #' @return The benchmarked series is returned
 #'
 #' @export
 #' @examples
-#' Y<-ts(qna_data$B1G_Y_data$B1G_FF, frequency=1, start=c(2009,1))
+#' 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)
+#' 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=1, mul=TRUE, nfreq=4, modified=TRUE,
                  conversion=c("Sum", "Average", "Last", "First", "UserDefined"),
@@ -55,36 +60,56 @@ denton<-function(s=NULL, t, d=1, mul=TRUE, nfreq=4, 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 Postion of the observation in the aggregated period (only used with "UserDefined" conversion)
-#' @param eps
-#' @param iter
-#' @param denton
+#' @param conversion Conversion rule. "Sum" by default.
+#' @param obsposition 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=1, eps=1e-12, iter=500, denton=TRUE){
+              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 +130,7 @@ grp<-function(s, t,
 #' @param conversion Conversion rule. Usually "Sum" or "Average". Sum by default.
 #' @param obsposition Postion of the observation in the aggregated period (only used with "UserDefined" conversion)
 #'
-#' @return
+#' @return The benchmarked series is returned
 #' @export
 #'
 #' @examples

R/mbdenton.R

@@ -1,27 +1,36 @@
 #' @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 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 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 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 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 +47,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
@@ -91,14 +102,15 @@ denton_modelbased<-function(series, indicator, differencing=1, conversion=c("Sum
 #' 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
 #' Y<-rjd3toolkit::aggregate(rjd3toolkit::retail$RetailSalesTotal, 1)
 #' x<-rjd3toolkit::aggregate(rjd3toolkit::retail$FoodAndBeverageStores, 4)
-#' td<-rjd3bench::denton_modelbased(Y, x, outliers = list("2000-01-01"=100, "2005-07-01"=100))
+#' td<-rjd3bench::denton_modelbased(Y, x,
+#'                                  outliers = list("2000-01-01"=100, "2005-07-01"=100))
 #' print(td)
 #'
 print.JD3MBDenton<-function(x, ...){
@@ -116,14 +128,15 @@ 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
 #' Y<-rjd3toolkit::aggregate(rjd3toolkit::retail$RetailSalesTotal, 1)
 #' x<-rjd3toolkit::aggregate(rjd3toolkit::retail$FoodAndBeverageStores, 4)
-#' td<-rjd3bench::denton_modelbased(Y, x, outliers = list("2000-01-01"=100, "2005-07-01"=100))
+#' td<-rjd3bench::denton_modelbased(Y, x,
+#'                                  outliers = list("2000-01-01"=100, "2005-07-01"=100))
 #' summary(td)
 #'
 summary.JD3MBDenton<-function(object, ...){

R/tempdisagg.R

@@ -167,8 +167,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
@@ -192,8 +192,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
@@ -218,8 +218,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
@@ -235,8 +235,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
@@ -284,8 +284,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