Vintages data classes and their validation

reviser stores vintages in two S3 classes that sit on top of a tibble and record what the columns mean. Both are produced by the package's own constructors; you normally do not create them by hand.

tbl_pubdate

Vintages identified by publication date, as returned by vintages_wide(), vintages_long() and get_revisions().

tbl_release

Vintages identified by release number, as returned by get_first_release(), get_nth_release(), get_latest_release(), get_fixed_release() and get_releases_by_date().

validate_vintages() checks that an object conforms to the contract below. This is useful after manipulating a vintages object with external tools, which can leave the class attribute in place while breaking the assumptions the methods rely on.

Usage

validate_vintages(x)

Arguments

x

An object of class tbl_pubdate or tbl_release.

Value

x, invisibly, if it is valid. Otherwise an error describing the first problem found.

Data contract

Every object of either class has a time column of dates and may carry an optional id column identifying the series. Beyond that, each class has two permitted layouts:

long

A key column (pub_date for tbl_pubdate, release for tbl_release) together with a value column.

wide

One column per vintage. For tbl_pubdate the column names are publication dates in %Y-%m-%d form; for tbl_release they are release labels matching release or final.

Columns must be atomic and scalar-valued; list columns are not permitted. The two classes are not mutually exclusive: a long release table carries both a release and a pub_date column and holds both classes.

Methods

Both classes support print(), summary() and plot(). The plot methods dispatch to plot_vintages(), which remains available for direct use when you want to pass its arguments explicitly. print() uses a pillar header that reports the layout, the number of periods and the number of vintages.

See also

Other helpers: print.tbl_pubdate(), print.tbl_release(), summary.tbl_pubdate(), summary.tbl_release(), tbl_sum.tbl_pubdate(), tbl_sum.tbl_release(), vintages_long(), vintages_wide()

Examples

df <- dplyr::filter(reviser::gdp, id == "US")

releases <- get_nth_release(df, n = 0:3)
validate_vintages(releases)

# A malformed time column is rejected
broken <- releases
broken$time <- as.character(broken$time)
broken$time[1] <- "not a date"
try(validate_vintages(broken))
#> Error in validate_vintages(broken) : 
#>   The 'time' column must contain dates in '%Y-%m-%d' format.

# So is a class attribute that contradicts the columns
mislabelled <- vintages_wide(df)$US
class(mislabelled) <- c("tbl_release", class(mislabelled))
try(validate_vintages(mislabelled))
#> Error in validate_vintages(mislabelled) : 
#>   Object is classed as 'tbl_release', so it must have a 'release' column (long format) or release labels as column names (wide format).