Every tibble returned by cvm_fetch(), cvm_versions() and the
other public fetchers has the S3 class cvm_tbl, a subclass of
tibble::tibble(), and carries seven provenance attributes:
source ("mirror" or "cvm"), fetched_at (a POSIXct
timestamp), group, dataset, table, package_version and
release (the GitHub release the rows were read from when
source = "mirror": mirror-<group>-<dataset>-snapshot-<date>, the
dated snapshot resolved by cvm_release_get(), or the -latest tag
for a release older than the snapshots; NA for source = "cvm").
print() shows them above the tibble; read one with
attr(x, "source").
The class and the attributes travel with the data through these operations:
dplyr verbs on one table:
filter(),mutate(),select(),arrange(),slice(),rename(),distinct(),relocate(),count(),group_by(),ungroup()andsummarise()(the summary of a CVM table keeps the provenance of that table).Base subsetting:
x[i, ],x[, j],x[j],x$col <- value,head(),tail(),subset(),unique().Joins where the
cvm_tblis the first argument (left_join(x, y)and friends): the result keeps the provenance ofx, the table whose rows it describes.rbind()andvctrs::vec_rbind()of two or morecvm_tblobjects. Attributes equal in every input survive; asource,group,dataset,tableorpackage_versionthat differs between inputs becomes"mixed", andfetched_atkeeps the oldest timestamp, so the combined tibble never claims a single origin it does not have.dplyr::bind_rows()of two or morecvm_tblobjects keeps the class but, by dplyr's rule for every data frame subclass, stamps the provenance of the first input on the result, even when the other inputs came from another source or table. Userbind()orvctrs::vec_rbind()when the inputs may differ.
They are dropped, by design, when the result is no longer a CVM
table: pull(), x[[j]] and x$col return vectors;
bind_rows() or a join whose first argument is a plain tibble, and
rbind() or vctrs::vec_rbind() with a plain tibble among the
inputs, return a plain tibble; bind_rows() of a cvm_tbl and a plain
tibble follows dplyr's rule and keeps the first input's class, so
the provenance then describes only the rows that came from the
cvm_tbl; tidyr::pivot_longer(), tidyr::pivot_wider(),
rowwise(), tibble::as_tibble() and as.data.frame() return
the type they promise.
Value
This topic documents a class, not a function. A cvm_tbl is
a tibble::tibble() whose class vector starts with "cvm_tbl" and
which carries the seven provenance attributes listed above; the
methods documented here return a cvm_tbl whenever the result is
still a CVM table, and the type the generic promises otherwise.
See also
cvm_fetch() for the fetcher that creates these tibbles.
Other utilities:
cnpj_clean(),
cnpj_format(),
cnpj_lookup()
Examples
x <- readRDS(system.file(
"extdata", "vignette-data", "cad_companhias_sample.rds",
package = "cvmdata"
))
attr(x, "dataset")
#> [1] "cad"
if (requireNamespace("dplyr", quietly = TRUE)) {
y <- dplyr::filter(x, sit == "ATIVO")
attr(y, "dataset")
z <- dplyr::count(dplyr::group_by(x, sit))
class(z)
}
#> [1] "cvm_tbl" "grouped_df" "tbl_df" "tbl" "data.frame"