Skip to content

Commit

Permalink
Avoid use of "pkg" + link to package as {pkg}
Browse files Browse the repository at this point in the history
  • Loading branch information
peterdesmet committed Aug 23, 2024
1 parent 5491f26 commit adfdf39
Show file tree
Hide file tree
Showing 4 changed files with 19 additions and 27 deletions.
2 changes: 1 addition & 1 deletion vignettes/data-package.Rmd
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ invalid_package$resources <- NULL
check_package(invalid_package)
```

You can manipulate the package list, but frictionless does not provide functions to do that. Use [purrr](https://purrr.tidyverse.org/) or base R instead (see `vignette("frictionless")`). Note however that some functions (e.g. `unclass()` or `append()`) removes the custom class, creating an invalid package. You can fix this by calling `create_package()` on your package.
You can manipulate the package list, but frictionless does not provide functions to do that. Use `{purrr}` or base R instead (see `vignette("frictionless")`). Note however that some functions (e.g. `unclass()` or `append()`) removes the custom class, creating an invalid package. You can fix this by calling `create_package()` on your package.

Most functions have `package` as their first argument and return package. This allows you to **pipe the functions**:

Expand Down
24 changes: 9 additions & 15 deletions vignettes/frictionless.Rmd
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,11 @@ vignette: >

## What is a Data Package?

A [Data Package](https://specs.frictionlessdata.io/data-package/) is a simple container format to describe and package a collection of (tabular) data. It is typically used to publish FAIR and open datasets. In this tutorial we will show you how to read, create, edit and write Data Packages with the **R pkg frictionless**.

**package** vs **pkg**: in the Frictionless Data community `package` refers to a Data Package, while in R that is a software package. In this tutorial we will use `pkg` to refer to the latter.
A [Data Package](https://specs.frictionlessdata.io/data-package/) is a simple container format to describe and package a collection of (tabular) data. It is typically used to publish FAIR and open datasets. In this tutorial we will show you how to read, create, edit and write Data Packages with the **frictionless**.

## Read a Data Package

Load the frictionless pkg with:
Load frictionless with:


``` r
Expand Down Expand Up @@ -111,7 +109,7 @@ gps

The data frame contains all GPS records, even though the actual data were split over [multiple CSV zipped files](https://zenodo.org/records/10053702#files-heading). `read_resource()` assigned the column names and types based on the Table Schema that was defined for that resource, not the headers of the CSV file.

You can also read data from a local (e.g. downloaded) Data Package. In fact, there is one included in the frictionless pkg, let's read that one from disk:
You can also read data from a local (e.g. downloaded) Data Package. In fact, there is one included in frictionless, let's read that one from disk:


``` r
Expand Down Expand Up @@ -144,7 +142,7 @@ Data from the `media` was not stored in a CSV file, but directly in the `data` p

Data Package is a good format to technically describe your data, e.g. if you are planning to deposit it on research repository. It also goes a long way meeting [FAIR principles](https://www.go-fair.org/fair-principles/).

The frictionless pkg assumes your data are stored as a data frame or CSV files. Let's use the built-in dataset `iris` as your data frame:
Frictionless assumes your data are stored as a data frame or CSV files. Let's use the built-in dataset `iris` as your data frame:


``` r
Expand Down Expand Up @@ -261,7 +259,7 @@ str(iris_schema$fields[[1]])
#> $ description: chr "Sepal length in cm."
```

Since schema is a list, you can use the `purrr` pkg to edit multiple elements at once:
Since schema is a list, you can use `{purrr}` to edit multiple elements at once:


``` r
Expand Down Expand Up @@ -340,10 +338,6 @@ my_package <-
data = c(path_1, path_2),
delim = "\t"
)
#> Error in `purrr::map_chr()` at frictionless-r/R/add_resource.R:132:5:
#> ℹ In index: 1.
#> Caused by error in `check_path()`:
#> ! Can't find file at ''.
```

Your Data Package now contains 2 resources, but you can add metadata properties as well (see the [Data Package documentation](https://specs.frictionlessdata.io/data-package/#metadata) for an overview). Since it is a list, you can use `append()` to insert properties at the desired place. Let's add `name` as first and `title` as second property:
Expand All @@ -369,20 +363,20 @@ Now that you have created your Data Package, you can write it to a directory of
write_package(my_package, "my_directory")
```

The directory will contain four files: the descriptor `datapackage.json`, one CSV file containing the data for the resource `iris` and two CSV files containing the data for the resource `observations`.
The directory will contain four files: the descriptor `datapackage.json`, one CSV file containing the data for the resource `iris` and two TSV files containing the data for the resource `observations`.


``` r
list.files("my_directory")
#> [1] "datapackage.json" "iris.csv"
#> [1] "datapackage.json" "iris.csv" "observations_1.tsv" "observations_2.tsv"
```



The frictionless pkg does not provide functionality to deposit your Data Package on a research repository such as [Zenodo](https://zenodo.org), but here are some tips:
Frictionless does not provide functionality to deposit your Data Package on a research repository such as [Zenodo](https://zenodo.org), but here are some tips:

1. Validate your Data Package before depositing. You can do this in Python with the [Frictionless Framework](https://github.com/frictionlessdata/frictionless-py) using `frictionless validate datapackage.json`.
2. Use `compress = TRUE` in `write_package()` to reduce the size of the deposit. It will zip the individual CSV files, not the entire Data Package. That way, users still have direct access to the `datapackage.json` file. See [this example](https://zenodo.org/records/10053702#files-heading).
3. Only describe the technical aspects of your dataset in `datapackage.json` (fields, units, the dataset identifier in `id`). Authors, methodology, license, etc. are better described in the metadata fields the research repository provides.

We also recommend having a look at the rOpenSci [`deposits`](https://docs.ropensci.org/deposits/) pkg, which provides a universal interface to deposit and access data in a research repository. It uses the frictionless pkg under the hood.
We also recommend having a look at `{deposits}`, which provides a universal interface to deposit and access data in a research repository. It uses frictionless under the hood.
18 changes: 8 additions & 10 deletions vignettes/frictionless.Rmd.orig
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,11 @@ knitr::opts_chunk$set(

## What is a Data Package?

A [Data Package](https://specs.frictionlessdata.io/data-package/) is a simple container format to describe and package a collection of (tabular) data. It is typically used to publish FAIR and open datasets. In this tutorial we will show you how to read, create, edit and write Data Packages with the **R pkg frictionless**.

**package** vs **pkg**: in the Frictionless Data community `package` refers to a Data Package, while in R that is a software package. In this tutorial we will use `pkg` to refer to the latter.
A [Data Package](https://specs.frictionlessdata.io/data-package/) is a simple container format to describe and package a collection of (tabular) data. It is typically used to publish FAIR and open datasets. In this tutorial we will show you how to read, create, edit and write Data Packages with the **frictionless**.

## Read a Data Package

Load the frictionless pkg with:
Load frictionless with:

```{r setup}
library(frictionless)
Expand Down Expand Up @@ -62,7 +60,7 @@ gps

The data frame contains all GPS records, even though the actual data were split over [multiple CSV zipped files](https://zenodo.org/records/10053702#files-heading). `read_resource()` assigned the column names and types based on the Table Schema that was defined for that resource, not the headers of the CSV file.

You can also read data from a local (e.g. downloaded) Data Package. In fact, there is one included in the frictionless pkg, let's read that one from disk:
You can also read data from a local (e.g. downloaded) Data Package. In fact, there is one included in frictionless, let's read that one from disk:

```{r}
local_package <- read_package(
Expand All @@ -80,7 +78,7 @@ Data from the `media` was not stored in a CSV file, but directly in the `data` p

Data Package is a good format to technically describe your data, e.g. if you are planning to deposit it on research repository. It also goes a long way meeting [FAIR principles](https://www.go-fair.org/fair-principles/).

The frictionless pkg assumes your data are stored as a data frame or CSV files. Let's use the built-in dataset `iris` as your data frame:
Frictionless assumes your data are stored as a data frame or CSV files. Let's use the built-in dataset `iris` as your data frame:

```{r}
# Show content of the data frame "iris"
Expand Down Expand Up @@ -132,7 +130,7 @@ iris_schema$fields[[1]]$description <- "Sepal length in cm."
str(iris_schema$fields[[1]])
```

Since schema is a list, you can use the `purrr` pkg to edit multiple elements at once:
Since schema is a list, you can use `{purrr}` to edit multiple elements at once:

```{r}
# Remove description for first field
Expand Down Expand Up @@ -207,7 +205,7 @@ Now that you have created your Data Package, you can write it to a directory of
write_package(my_package, "my_directory")
```

The directory will contain four files: the descriptor `datapackage.json`, one CSV file containing the data for the resource `iris` and two CSV files containing the data for the resource `observations`.
The directory will contain four files: the descriptor `datapackage.json`, one CSV file containing the data for the resource `iris` and two TSV files containing the data for the resource `observations`.

```{r}
list.files("my_directory")
Expand All @@ -217,10 +215,10 @@ list.files("my_directory")
unlink("my_directory", recursive = TRUE)
```

The frictionless pkg does not provide functionality to deposit your Data Package on a research repository such as [Zenodo](https://zenodo.org), but here are some tips:
Frictionless does not provide functionality to deposit your Data Package on a research repository such as [Zenodo](https://zenodo.org), but here are some tips:

1. Validate your Data Package before depositing. You can do this in Python with the [Frictionless Framework](https://github.com/frictionlessdata/frictionless-py) using `frictionless validate datapackage.json`.
2. Use `compress = TRUE` in `write_package()` to reduce the size of the deposit. It will zip the individual CSV files, not the entire Data Package. That way, users still have direct access to the `datapackage.json` file. See [this example](https://zenodo.org/records/10053702#files-heading).
3. Only describe the technical aspects of your dataset in `datapackage.json` (fields, units, the dataset identifier in `id`). Authors, methodology, license, etc. are better described in the metadata fields the research repository provides.

We also recommend having a look at the rOpenSci [`deposits`](https://docs.ropensci.org/deposits/) pkg, which provides a universal interface to deposit and access data in a research repository. It uses the frictionless pkg under the hood.
We also recommend having a look at `{deposits}`, which provides a universal interface to deposit and access data in a research repository. It uses frictionless under the hood.
2 changes: 1 addition & 1 deletion vignettes/table-schema.Rmd
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ levels(observations$life_stage)

### Manipulate

A schema is a list which you can manipulate, but frictionless does not provide functions to do that. Use [purrr](https://purrr.tidyverse.org/) or base R instead (see `vignette("frictionless")`). You do not have to start a schema from scratch though: use `get_schema()` (see above) or `create_schema()` instead.
A schema is a list which you can manipulate, but frictionless does not provide functions to do that. Use `{purrr}` or base R instead (see `vignette("frictionless")`). You do not have to start a schema from scratch though: use `get_schema()` (see above) or `create_schema()` instead.

`create_schema()` creates a schema from a data frame and defines the `name`, `type` (and if a factor `constraints$enum`) for each field:

Expand Down

0 comments on commit adfdf39

Please sign in to comment.