Skip to contents

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() and summarise() (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_tbl is the first argument (left_join(x, y) and friends): the result keeps the provenance of x, the table whose rows it describes.

  • rbind() and vctrs::vec_rbind() of two or more cvm_tbl objects. Attributes equal in every input survive; a source, group, dataset, table or package_version that differs between inputs becomes "mixed", and fetched_at keeps the oldest timestamp, so the combined tibble never claims a single origin it does not have.

  • dplyr::bind_rows() of two or more cvm_tbl objects 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. Use rbind() or vctrs::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"