frictionless-r/README.Rmd at v2 · frictionlessdata/frictionless-r · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# frictionless

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/frictionless)](https://CRAN.R-project.org/package=frictionless)
[![CRAN checks](https://badges.cranchecks.info/worst/frictionless.svg)](https://cran.r-project.org/web/checks/check_results_frictionless.html)
[![R-CMD-check](https://github.com/frictionlessdata/frictionless-r/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/frictionlessdata/frictionless-r/actions/workflows/R-CMD-check.yaml)
[![codecov](https://codecov.io/gh/frictionlessdata/frictionless-r/branch/main/graph/badge.svg)](https://app.codecov.io/gh/frictionlessdata/frictionless-r/)
[![repo status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![rOpenSci](https://badges.ropensci.org/495_status.svg)](https://github.com/ropensci/software-review/issues/495)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5815355.svg)](https://doi.org/10.5281/zenodo.5815355)
<!-- badges: end -->

frictionless is an R package to read and write Frictionless Data Packages. A [Data Package](https://specs.frictionlessdata.io/data-package/) is a simple container format and standard to describe and package a collection of (tabular) data. It is typically used to publish [FAIR](https://www.go-fair.org/fair-principles/) and open datasets.

To get started, see:

- [Get started](https://docs.ropensci.org/frictionless/articles/frictionless.html): an introduction to the package's main functionalities.
- [Function reference](https://docs.ropensci.org/frictionless/reference/index.html): overview of all functions.
- [Standard implementation](https://docs.ropensci.org/frictionless/articles/index.html): how frictionless implements the Data Package standard.

**frictionless currently implements [Data Package v1](https://specs.frictionlessdata.io/).** Our goal is to support [Data Package v2](https://datapackage.org/) as well.

## Installation

Install the released version of frictionless from CRAN:

``` r
install.packages("frictionless")
```

Or install the development version from [GitHub](https://github.com/)
with:

``` r
# install.packages("pak")
pak::pak("frictionlessdata/frictionless-r")
```

## Usage

With frictionless you can **read** data from a Data Package (local or remote) into your R environment. Here we read bird GPS tracking data from a Data Package published on [Zenodo](https://doi.org/10.5281/zenodo.10053702):

```{r read_example}
library(frictionless)

# Read the datapackage.json file
# This gives you access to all Data Resources of the Data Package without
# reading them, which is convenient and fast.
package <- read_package("https://zenodo.org/records/10053702/files/datapackage.json")

package

# List resources
resource_names(package)

# Read data from the resource "gps"
# This will return a single data frame, even though the data are split over
# multiple zipped CSV files.
read_resource(package, "gps")
```

You can also create your own Data Package, add data and **write** it to disk:

```{r write_example}
# Create a Data Package and add the "iris" data frame as a resource
my_package <-
  create_package() |>
  add_resource(resource_name = "iris", data = iris)

my_package

# Write the Data Package to disk
my_package |>
  write_package("my_directory")
```

```{r, include = FALSE}
unlink("my_directory", recursive = TRUE)
```

For more functionality, see [get started](https://docs.ropensci.org/frictionless/articles/frictionless.html) or the [function reference](https://docs.ropensci.org/frictionless/reference/index.html).

## frictionless vs datapackage.r

[datapackage.r](https://github.com/frictionlessdata/datapackage-r) is an alternative R package to work with Data Packages. It has an object-oriented design and offers validation.

frictionless on the other hand allows you to quickly read and write Data Packages to and from data frames, getting out of the way for the rest of your analysis. It is designed to be lightweight, follows [tidyverse](https://tidyverse.org/) principles and supports piping. Its validation functionality is limited to what is needed for reading and writing, see [frictionless-py](https://github.com/frictionlessdata/frictionless-py) for extensive validation.

## Meta

- We welcome [contributions](https://docs.ropensci.org/frictionless/CONTRIBUTING.html) including bug reports.
- License: MIT
- Get citation information for frictionless in R with `citation("frictionless")`.
- Please note that this project is released with a [Contributor Code of Conduct](https://docs.ropensci.org/frictionless/CODE_OF_CONDUCT.html). By participating in this project you agree to abide by its terms.