add srr roclets; some other improvements

Author: marcburri

DESCRIPTION

@@ -26,6 +26,7 @@ Imports:
     magrittr,
     dplyr,
     tidyr,
+    pillar,
     ggplot2,
     car,
     sandwich,

NAMESPACE

@@ -17,6 +17,8 @@ S3method(summary,lst_efficient)
 S3method(summary,revision_summary)
 S3method(summary,tbl_pubdate)
 S3method(summary,tbl_release)
+S3method(tbl_sum,tbl_pubdate)
+S3method(tbl_sum,tbl_release)
 export(colors_reviser)
 export(diagnose)
 export(get_days_to_release)
@@ -43,3 +45,4 @@ importFrom(calculus,"%mx%")
 importFrom(calculus,"%prod%")
 importFrom(calculus,"%sum%")
 importFrom(magrittr,"%>%")
+importFrom(pillar,tbl_sum)

R/graphs.R

@@ -314,6 +314,8 @@ plot_vintages <- function(
 #' @param ... Additional arguments passed to plot_vintages.
 #'
 #' @return A ggplot2 object.
+#' @srrstats {TS5.0} Implements default plot methods for implemented class system
+#' @srrstats {TS4.2} Explicitly documents the type and class of return values
 #' @method plot tbl_pubdate
 #' @family revision graphs
 #' @export
@@ -327,6 +329,8 @@ plot.tbl_pubdate <- function(x, ...) {
 #' @param ... Additional arguments passed to plot_vintages.
 #'
 #' @return A ggplot2 object.
+#' @srrstats {TS5.0} Implements default plot methods for implemented class system
+#' @srrstats {TS4.2} Explicitly documents the type and class of return values
 #' @method plot tbl_release
 #' @family revision graphs
 #' @export
@@ -340,6 +344,12 @@ plot.tbl_release <- function(x, ...) {
 #' @param state String. The name of the state to visualize.
 #' @param type String. Type of estimate: "filtered" or "smoothed".
 #' @param ... Additional arguments passed to theme_reviser.
+#' @srrstats {G1.4a} Internal function documented with @noRd tag
+#' @srrstats {TS5.0} Implements plot methods for class system
+#' @srrstats {TS5.7} Includes model (input) values in plot with forecast (output) values (in-sample vs out-of-sample)
+#' @srrstats {TS5.8} Provides clear visual distinction between model and forecast values (different colors/samples)
+#' @srrstats {TS5.6} Indicates distributional limits (confidence intervals) on plot by default
+#' @return ggplot object
 #'
 #' @keywords internal
 #' @noRd

R/jvn.R

@@ -46,6 +46,44 @@
 #'   \item{bic}{Bayesian Information Criterion}
 #'   \item{data}{Input data}
 #' }
+#' 
+#' @srrstats {G1.0} Primary reference: Jacobs & Van Norden (2011)
+#' @srrstats {G1.1} First implementation in R of the Jacobs-Van Norden state-space model
+#' @srrstats {G1.3} Statistical terminology clearly defined (news, noise, spillovers)
+#' @srrstats {G2.0} Input assertions on lengths (e, h, ar_order must be single values)
+#' @srrstats {G2.0a} Documents expectations on input lengths in parameter descriptions
+#' @srrstats {G2.1} Input type assertions (checks for list, numeric types)
+#' @srrstats {G2.1a} Documents data type expectations for all inputs
+#' @srrstats {G2.2} Restricts multivariate input to univariate parameters (e, h, ar_order)
+#' @srrstats {G2.3a} Uses match.arg() equivalent for method parameter validation
+#' @srrstats {G2.3b} Documents case-sensitivity requirements
+#' @srrstats {G2.4} Type conversion mechanisms (round() for ar_order)
+#' @srrstats {G2.4a} Explicit conversion to integer via round()
+#' @srrstats {G2.7} Accepts multiple tabular forms (matrix, data.frame, list)
+#' @srrstats {G2.8} Pre-processing routines (vintages_check, vintages_wide)
+#' @srrstats {G2.9} Diagnostic messages for type conversions (suppressWarnings)
+#' @srrstats {G2.10} Consistent column extraction behavior
+#' @srrstats {G2.13} Checks for missing data (complete.cases in init_params)
+#' @srrstats {G2.14} Options for handling missing data (implicit via KFAS)
+#' @srrstats {G2.15} Never assumes non-missingness
+#' @srrstats {G3.0} Numerical stability considerations (epsilon parameter)
+#' @srrstats {G5.2} Error and warning behavior tested
+#' @srrstats {TS1.0} Uses explicit time series class systems
+#' @srrstats {TS1.1} Documents types/classes of input data
+#' @srrstats {TS1.2} Validation routines for input classes (vintages_check)
+#' @srrstats {TS1.3} Pre-processing to validate and transform input (vintages_wide)
+#' @srrstats {TS1.4} Maintains time/date components of input data
+#' @srrstats {TS1.5} Ensures strict ordering of time index
+#' @srrstats {TS1.6} Catches ordering violations in pre-processing
+#' @srrstats {TS1.8} Explicit about monthly time intervals (frequency calculation)
+#' @srrstats {TS2.0} Handles explicit vs implicit missing values
+#' @srrstats {TS2.1} Options for handling missing data
+#' @srrstats {TS4.0b} Returns unique class-defined format (jvn_model)
+#' @srrstats {TS4.2} Explicitly documents return value types/classes
+#' @srrstats {TS4.3} Return values include time scales
+#' @srrstats {TS4.6b} Forecasting returns first- and second-order moments
+#' @srrstats {TS4.6c} Error indication for forecast estimates (confidence intervals)
+#' @srrstats {TS4.7c} Distinguishes model vs forecast values (sample column)
 #'
 #' @references Jacobs, Jan P.A.M. and Van Norden, Simon, "Modeling Data
 #' Revisions: Measurement Error and Dynamics of 'True' Values", Journal of
@@ -783,6 +821,11 @@ jvn_nowcast <- function(
 #'
 #' Constructs the state-space matrices Z, T, R, H, Q according to the
 #' Jacobs & Van Norden (2011) specification.
+#' 
+#' @srrstats {G1.4a} Internal function documented with @noRd tag
+#' @srrstats {G2.0} Input assertions on parameter dimensions
+#' @srrstats {G2.1} Type checking for parameters
+#' @srrstats {G3.0} Numerical stability in matrix construction
 #'
 #' @keywords internal
 #' @noRd
@@ -977,6 +1020,9 @@ jvn_matrices <- function(
 
 
 #' Update Model Matrices with Estimated Parameters
+#' @srrstats {G1.4a} Internal function documented with @noRd tag
+#' @srrstats {G2.1} Parameter type validation
+#' @srrstats {G3.0} Numerical operations with appropriate precision
 #' @keywords internal
 #' @noRd
 jvn_update_matrices <- function(model_struct, params) {
@@ -1043,6 +1089,9 @@ jvn_update_matrices <- function(model_struct, params) {
 
 
 #' Negative Log-Likelihood Function
+#' @srrstats {G1.4a} Internal function documented with @noRd tag
+#' @srrstats {G2.15} Handles missing values appropriately
+#' @srrstats {G3.0} Numerical stability in likelihood calculation
 #' @keywords internal
 #' @noRd
 jvn_negloglik <- function(params, model_struct, data, transform_se = TRUE) {
@@ -1434,6 +1483,13 @@ print.jvn_model <- function(x, ...) {
 #' @param state String. The name of the state to visualize.
 #' @param type String. Type of estimate to plot: "filtered" or "smoothed".
 #' @param ... Additional arguments passed to theme_reviser.
+#' 
+#' @srrstats {TS5.0} Implements default plot methods for class system
+#' @srrstats {TS5.1} Time axis labeling (delegates to base method)
+#' @srrstats {TS5.2} Time on horizontal axis (delegates to base method)
+#' @srrstats {TS5.6} Distributional limits shown (confidence intervals)
+#' @srrstats {TS5.7} Includes model and forecast values in plot
+#' @srrstats {TS5.8} Visual distinction between model and forecast values
 #'
 #' @return A ggplot2 object visualizing the specified state estimates.
 #' @examples

R/kk.R

@@ -101,6 +101,8 @@
 #' @srrstats {TS4.6} Time Series Software which implements or otherwise
 #' enables forecasting should return either:
 #' @srrstats {TS4.6b} filtered/forecasted point estimates
+#' @srrstats {TS4.6c} Error indication for forecast estimates (confidence intervals)
+#' @srrstats {TS4.7c} Distinguishes model vs forecast values (sample column)
 #' @srrstats {TS4.7} forecast values and models separately returned
 #' @srrstats {TS4.7a} only forecast values returned
 #' @srrstats {TS4.7b} forecast values and models separately returned
@@ -1398,6 +1400,7 @@ kk_ols_estim <- function(equations, data, model = "KK") {
 #'
 #' @srrstats {G2.4b} convert via via `as.numeric()`
 #' @srrstats {G2.4c} convert via via `as.character()`
+#' @srrstats {G3.0} Uses epsilon for numerical stability (epsilon parameter)
 #'
 #' @examples
 #' # Example 1: Kishor-Koenig model with character matrices
@@ -1609,7 +1612,7 @@ kk_matrices <- function(e, model, params = NULL, type = "numeric") {
 #'     \item{\code{Q}}{The state noise covariance matrix.}
 #'     \item{\code{R}}{The control matrix.}
 #'   }
-#'
+#' @srrstats {G3.0} Numerical stability with epsilon parameter
 #' @details The state space model is represented by the following equations:
 #'
 #' **State Equation:**

R/reviser-package.R

@@ -17,6 +17,7 @@ utils::globalVariables(c(
 #' @importFrom KFAS SSModel SSMcustom
 #' @importFrom magrittr %>%
 #' @importFrom calculus %mx% %diff% %sum% %prod%
+#' @importFrom pillar tbl_sum
 #' @srrstats {G1.4} roxygen2 is used for all documentation.
 #' @srrstats {G1.4a} All internal functions are also documented
 NULL

R/revisions.R

@@ -1396,6 +1396,37 @@ print.revision_summary <- function(x, interpretation = TRUE, digits = 3, ...) {
 #' @param ... Additional arguments (not used).
 #'
 #' @return A tibble with diagnostic results.
+#' @examples
+#' # Example usage with revision analysis results
+#' df <- dplyr::select(
+#'   get_nth_release(
+#'     na.omit(
+#'       tsbox::ts_pc(
+#'         dplyr::filter(reviser::gdp, id == "US")
+#'       )
+#'     ),
+#'     n = 0:3
+#'   ),
+#'   -"pub_date"
+#' )
+#'
+#' final_release <- dplyr::select(
+#'   get_nth_release(
+#'     na.omit(
+#'       tsbox::ts_pc(
+#'         dplyr::filter(reviser::gdp, id == "US")
+#'       )
+#'     ),
+#'     n = "latest"
+#'   ),
+#'   -"pub_date"
+#' )
+#'
+#' # Get revision analysis results
+#' results <- get_revision_analysis(df, final_release, degree = 5)
+#' 
+#' # Diagnose revision quality
+#' diagnose(results)
 #' @family revision analysis
 #' @export
 diagnose.revision_summary <- function(object, alpha = 0.05, ...) {
@@ -1651,7 +1682,7 @@ diagnose.revision_summary <- function(object, alpha = 0.05, ...) {
 
     # Print for this group
     cat(group_id, ":\n")
-    print(diagnostics, row.names = FALSE)
+    print(diagnostics)
     cat("\n")
 
     # Store results
@@ -1699,6 +1730,39 @@ diagnose.revision_summary <- function(object, alpha = 0.05, ...) {
 #' @param ... Additional arguments passed to methods.
 #'
 #' @return Method-specific diagnostic output.
+#' 
+#' @examples
+#' # Example usage with revision analysis results
+#' df <- dplyr::select(
+#'   get_nth_release(
+#'     na.omit(
+#'       tsbox::ts_pc(
+#'         dplyr::filter(reviser::gdp, id == "US")
+#'       )
+#'     ),
+#'     n = 0:3
+#'   ),
+#'   -"pub_date"
+#' )
+#'
+#' final_release <- dplyr::select(
+#'   get_nth_release(
+#'     na.omit(
+#'       tsbox::ts_pc(
+#'         dplyr::filter(reviser::gdp, id == "US")
+#'       )
+#'     ),
+#'     n = "latest"
+#'   ),
+#'   -"pub_date"
+#' )
+#'
+#' # Get revision analysis results
+#' results <- get_revision_analysis(df, final_release, degree = 5)
+#' 
+#' # Diagnose revision quality
+#' diagnose(results)
+#' 
 #' @family revision analysis
 #' @export
 diagnose <- function(object, ...) {
@@ -1714,6 +1778,37 @@ diagnose <- function(object, ...) {
 #' @return The function returns the input \code{object} invisibly.
 #' @method summary revision_summary
 #' @family revision analysis
+#' @examples
+#' # Example usage with revision analysis results
+#' df <- dplyr::select(
+#'   get_nth_release(
+#'     na.omit(
+#'       tsbox::ts_pc(
+#'         dplyr::filter(reviser::gdp, id == "US")
+#'       )
+#'     ),
+#'     n = 0:3
+#'   ),
+#'   -"pub_date"
+#' )
+#'
+#' final_release <- dplyr::select(
+#'   get_nth_release(
+#'     na.omit(
+#'       tsbox::ts_pc(
+#'         dplyr::filter(reviser::gdp, id == "US")
+#'       )
+#'     ),
+#'     n = "latest"
+#'   ),
+#'   -"pub_date"
+#' )
+#'
+#' # Get revision analysis results
+#' results <- get_revision_analysis(df, final_release, degree = 5)
+#' 
+#' # Summarize revision quality
+#' summary(results)
 #' @export
 summary.revision_summary <- function(object, interpretation = TRUE, ...) {
   print.revision_summary(object, interpretation = interpretation, ...)

R/srr-stats-standards.R

@@ -24,15 +24,12 @@ NULL
 #' @srrstatsNA {G2.5}
 #' @srrstatsNA {G2.14c}
 #' @srrstatsNA {G2.16}
-#' @srrstatsNA {G3.0}
 #' @srrstatsNA {G4.0}
 #' @srrstatsNA {G5.0}
 #' @srrstatsNA {G5.1}
 #' @srrstatsNA {G5.3}
 #' @srrstatsNA {G5.4b}
 #' @srrstatsNA {G5.4c}
-#' @srrstatsNA {G5.5}
-#' @srrstatsNA {G5.6}
 #' @srrstatsNA {G5.6a}
 #' @srrstatsNA {G5.6b}
 #' @srrstatsNA {G5.7}
@@ -64,11 +61,6 @@ NULL
 #' @srrstatsNA {TS4.5b}
 #' @srrstatsNA {TS4.5c}
 #' @srrstatsNA {TS4.6a}
-#' @srrstatsNA {TS4.6c}
-#' @srrstatsNA {TS4.7c}
 #' @srrstatsNA {TS5.4}
-#' @srrstatsNA {TS5.6}
-#' @srrstatsNA {TS5.7}
-#' @srrstatsNA {TS5.8}
 #' @noRd
 NULL