Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/r-lib/cereal
Serialize vctrs objects to JSON 🥣
https://github.com/r-lib/cereal
Last synced: about 1 month ago
JSON representation
Serialize vctrs objects to JSON 🥣
- Host: GitHub
- URL: https://github.com/r-lib/cereal
- Owner: r-lib
- License: other
- Created: 2023-05-22T15:36:57.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-06-09T14:56:25.000Z (over 1 year ago)
- Last Synced: 2024-09-24T12:48:44.413Z (3 months ago)
- Language: R
- Homepage: https://r-lib.github.io/cereal/
- Size: 884 KB
- Stars: 25
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - r-lib/cereal - Serialize vctrs objects to JSON 🥣 (R)
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# cereal 🥣
[](https://github.com/r-lib/cereal/actions/workflows/R-CMD-check.yaml)
[](https://CRAN.R-project.org/package=cereal)
[](https://app.codecov.io/gh/r-lib/cereal?branch=main)
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
The goal of cereal is to provide methods to [serialize](https://en.wikipedia.org/wiki/Serialization) objects from [vctrs](https://vctrs.r-lib.org/) to [JSON](https://en.wikipedia.org/wiki/JSON), as well as back from JSON to vctrs objects.
## Installation
You can install the released version of vetiver from
[CRAN](https://CRAN.R-project.org) with:
``` r
install.packages("cereal")
```
You can install the development version of cereal from [GitHub](https://github.com/) with:
``` r
# install.packages("pak")
pak::pak("r-lib/cereal")
```
## Example
A data frame is a rectangular collection of variables (in the columns) and observations (in the rows). Each variable is a vector of one data type, like factor or datetime:
```{r example}
df <- tibble::tibble(
a = c(1.2, 2.3, 3.4),
b = 2L:4L,
c = Sys.Date() + 0:2,
d = as.POSIXct("2019-01-01", tz = "America/New_York") + 100:102,
e = sample(letters, 3),
f = factor(c("blue", "blue", "green"), levels = c("blue", "green", "red")),
g = ordered(c("small", "large", "medium"), levels = c("small", "medium", "large"))
)
df
```
The vctrs package has a [concept of a **vector prototype**](https://vctrs.r-lib.org/articles/type-size.html) which captures the metadata associated with a vector without keeping any of the data itself.
```{r cars}
vctrs::vec_ptype(df)
```
The information stored in such a vector prototype includes, for example, the levels of a factor and the timezone for a datetime. This can be useful or important information when deploying code or models, such as when using [vetiver](https://vetiver.rstudio.com/). We could store this vector prototype as an R binary object saved as an `.rds` file, but with cereal, you can store this vector prototype in plain text as JSON:
```{r}
library(cereal)
json <- cereal_to_json(df)
json
```
Storing prototype information as JSON (rather than a binary file) means it can be used as plain-text metadata for a model.
You can also convert from JSON back to the original prototype:
```{r}
cereal_from_json(json)
```
For an approach to this same task using Python, [see Pydantic's `model.json()`](https://docs.pydantic.dev/latest/usage/exporting_models/#modeljson).
## Contributing
- This project is released with a [Contributor Code of Conduct](https://www.contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.
- If you think you have encountered a bug, please [submit an issue](https://github.com/r-lib/cereal/issues).
- Either way, learn how to create and share a [reprex](https://reprex.tidyverse.org/articles/articles/learn-reprex.html) (a minimal, reproducible example), to clearly communicate about your code.