Title: Frictionless Standards
Version: 0.5.2
Description: A "tabular-data-resource" (https://specs.frictionlessdata.io/tabular-data-resource/) is a simple format to describe a singular tabular data resource such as a CSV file. It includes support both for metadata such as author and title and a schema to describe the data, for example the types of the fields/columns in the data. Create a tabular-data-resource by providing a data.frame and specifying metadata. Write and read tabular-data-resources to and from disk.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.2
Imports: cli, purrr, vroom, S7 (≥ 0.1.1), tibble, tidyselect, yaml, dplyr, rlang
Suggests: testthat (≥ 3.0.0), withr, fs, knitr, rmarkdown, curl
Config/testthat/edition: 3
Config/testthat/parallel: true
URL: https://github.com/cole-brokamp/fr, https://cole-brokamp.github.io/fr/
BugReports: https://github.com/cole-brokamp/fr/issues
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2024-11-07 19:00:24 UTC; cole
Author: Cole Brokamp ORCID iD [aut, cre, cph], Tomasz Kalinowski [ctb]
Maintainer: Cole Brokamp <cole@colebrokamp.com>
Repository: CRAN
Date/Publication: 2024-11-07 19:10:02 UTC

About the fr package

Description

fr provides functions and objects to reproducibly create and track changes to metadata alongside code that creates the data. This prevents a disconnect between data and metadata, but also allows for computing on the metadata to create richer documentation. The fr package provides fr_tdr, fr_schema, and fr_field objects to provide a representation of the Frictionless Tabular Data Resource standards in R.

A fr_tdr, or frictionless tabular data resource, object encapsulates data and metadata by building on top of the data.frame and has a list of data resource-specific metadata properties (e.g., name, description). one of which is a fr_schema (Frictionless Schema) object. One of these is a fr_schema object, which is a list of table-specific metadata properties. One of these is a list of fr_field objects, which is a list #' field- (or column-) specific metadata properties (e.g., name, type, constraints)

Normal usage will only require using as_fr_tdr() to create a fr_tdr object based on a data.frame or tibble.

Author(s)

Maintainer: Cole Brokamp cole@colebrokamp.com (ORCID) [copyright holder]

Other contributors:

See Also

Useful links:

Coerce a fr_tdr object into a data frame

Description

Equivalent to as.data.frame(); directly using tibble::as_tibble() also works because its input is first coerced with as.data.frame()

Usage

as_data_frame(x, ...)

Arguments

x

a fr_tdr object

...

ignored

Value

a data frame

Examples

as_fr_tdr(mtcars, name = "mtcars") |>
  as_data_frame()

Coerce character, factor, numeric, logical, and Date vectors into fr_field objects

Description

The supported classes of R objects are converted to the corresponding frictionless type:

R class fr type
character() string
factor() string (with enum(constraints = levels(x)))
numeric(), integer() number
logical() boolean
Date date

Usage

as_fr_field(x, ...)

Arguments

x

a character, factor, numeric, integer, logical, or Date vector

...

<dynamic-dots> required (name) and optional (title, description) field descriptors)

Value

a fr_field object

Examples

as_fr_field(1:10, "example_integer") # -> frictionless number
as_fr_field((1:10) * 0.1, "example_double") # -> frictionless number
as_fr_field(letters, "example_character") # -> frictionless string
as_fr_field(factor(letters), "example_factor") # -> frictionless string with enum constraints
as_fr_field(c(TRUE, FALSE, TRUE), "example_logical") # -> frictionless boolean
as_fr_field(as.Date(c("2023-04-23", "2004-12-31")), "example_date") # -> frictionless date

Coerce a data frame into a fr_tdr object

Description

Coerce a data frame into a fr_tdr object

Usage

as_fr_tdr(x, ...)

Arguments

x

a data.frame

...

<dynamic-dots> required (name) and optional tabular-data-resource properties (e.g., path, version, title, homepage, description)

Details

Use the .template argument to provide a template fr_tdr object from which table-specific (i.e. "name", "version", "title", "homepage", "description") and field-specific metadata will be copied; note that all metadata provided in ... will be ignored if this argument is provided

Value

a fr_tdr object

Examples

as_fr_tdr(mtcars, name = "mtcars")
S7::prop(as_fr_tdr(mtcars, name = "mtcars"), "schema")

Coerce a fr_tdr object into a list

Description

equivalent to as.list()

Usage

as_list(x, ...)

Arguments

x

a fr_tdr object

...

ignored

Value

a list representing the frictionless metadata descriptor

Examples

as_fr_tdr(mtcars, name = "mtcars") |>
  as_list()

dplyr methods for fr_tdr objects

Description

Some basic dplyr functions are re-implemented here for for fr_tdr objects. The input is converted with as.data.frame() before being passed to the dplyr function. The resulting tibble object is converted back into a fr_tdr object, matching table- and field-specific metadata where possible by using as_fr_tdr() and specifying the .template argument.  

dplyr fr
mutate() fr_mutate()
rename() fr_rename()
select() fr_select()
filter() fr_filter()
summarise() fr_summarise()
arrange() fr_arrange()

Usage

fr_mutate(x, ...)

fr_rename(x, ...)

fr_select(x, ...)

fr_filter(x, ...)

fr_summarize(x, ...)

fr_arrange(x, ...)

Arguments

x

a fr_tdr object

...

passed to the underlying dplyr function

Value

a fr_tdr object

Examples

read_fr_tdr(fs::path_package("fr", "hamilton_poverty_2020")) |>
  fr_mutate(next_year = year + 1) |>
  fr_rename(new_year = next_year) |>
  fr_select(-new_year) |>
  fr_filter(fraction_poverty > 0.1) |>
  fr_summarize(median_poverty_fraction = median(fraction_poverty)) |>
  fr_arrange(median_poverty_fraction)

Test if an object is a fr_field object

Description

Test if an object is a fr_field object

Usage

is_fr_field(x)

Arguments

x

an object to test

Value

TRUE if object is a fr_field object, FALSE otherwise

Examples

is_fr_field(letters)
is_fr_field(as_fr_field(letters, "letters"))

read a tabular-data-resource into R

Description

read a tabular-data-resource into R

Usage

read_fr_tdr(file)

Arguments

file

Either a path to a file, a connection, or literal data (either a single string or a raw vector). file can also be a character vector containing multiple filepaths or a list containing multiple connections.

Files ending in .gz, .bz2, .xz, or .zip will be automatically uncompressed. Files starting with ⁠http://⁠, ⁠https://⁠, ⁠ftp://⁠, or ⁠ftps://⁠ will be automatically downloaded. Remote gz files can also be automatically downloaded and decompressed.

Literal data is most useful for examples and tests. To be recognised as literal data, wrap the input with I().

Details

A file path (or url) representing a folder that contains a "tabular-data-resource.yaml" can be used in file.

Value

a fr_tdr object

Examples

read_fr_tdr(fs::path_package("fr", "hamilton_poverty_2020"))

add or update field-specific metadata in a fr_tdr object

Description

add or update field-specific metadata in a fr_tdr object

Usage

update_field(x, field, ...)

Arguments

x

a fr_tdr object

field

character name of field in x to update

...

table schema field descriptors (e.g., title, description)

Value

an fr_tdr object containing the updated field

Examples

my_mtcars <-
  mtcars |>
  as_fr_tdr(name = "mtcars") |>
  update_field("mpg", title = "Miles Per Gallon")

S7::prop(my_mtcars, "schema")

write a fr_tdr object to disk

Description

The name property of the fr_tdr object is used to write a frictionless tabular-data-resource to disk. For example, if name = "my_data", then a folder named my_data would be created with (1) my_data.csv and (2) tabular-data-resource.yaml.

Usage

write_fr_tdr(x, dir)

Arguments

x

a fr_tdr object to write to disk

dir

path to directory where tabular-data-resource folder will be created

Value

x (invisibly)