https://github.com/atorus-research/datasetjson
Read and write CDISC Dataset JSON files
https://github.com/atorus-research/datasetjson
cdisc dataset-json rstats rstats-package
Last synced: 11 months ago
JSON representation
Read and write CDISC Dataset JSON files
- Host: GitHub
- URL: https://github.com/atorus-research/datasetjson
- Owner: atorus-research
- License: apache-2.0
- Created: 2023-09-04T18:51:25.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-12-19T15:58:10.000Z (over 2 years ago)
- Last Synced: 2023-12-19T16:06:14.562Z (over 2 years ago)
- Topics: cdisc, dataset-json, rstats, rstats-package
- Language: R
- Homepage: https://atorus-research.github.io/datasetjson/
- Size: 7.43 MB
- Stars: 8
- Watchers: 0
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE.md
Awesome Lists containing this project
README
---
output: github_document
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(datasetjson)
```
# **datasetjson** 
[
](https://app.codecov.io/gh/atorus-research/datasetjson)
[
](https://github.com/atorus-research/datasetjson/blob/main/LICENSE.md)
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
Welcome to **datasetjson**. **datasetjson** is an R package built to read and write [CDISC Dataset JSON](https://www.cdisc.org/standards/data-exchange/dataset-json) formatted datasets.
If you're stumbling into the world of Dataset JSON, you might be wondering "Why JSON?", as many have asked this question. We highly recommend you take a pit stop to read [this blog post](https://swhume.github.io/why-json-for-datasets) by Sam Hume one of the creators of the Dataset JSON standard.
As always, we welcome your feedback. If you spot a bug, would like to see a new feature, or if any documentation is unclear - submit an issue through GitHub right [here](https://github.com/atorus-research/datasetjson/issues).
# Installation
You can install **datasetjson** with:
```{r install, eval=FALSE}
# Install from CRAN:
install.packages("datasetjson")
# Or install the development version:
devtools::install_github("https://github.com/atorus-research/datasetjson.git", ref="dev")
```
# Using **datasetjson**
**datasetjson** works by allowing you to take a data frame and apply the necessary attributes required for the CDISC Dataset JSON. The goal is to make this experience simple. Before you can write a Dataset JSON file to disk, you first need to build the Dataset JSON object. An example call looks like this:
```{r sample_call}
ds_json <- dataset_json(
head(iris, 5),
file_oid = "/some/path",
last_modified = "2023-02-15T10:23:15",
originator = "Some Org",
sys = "source system",
sys_version = "1.0",
study = "SOMESTUDY",
metadata_version = "MDV.MSGv2.0.SDTMIG.3.3.SDTM.1.7",
metadata_ref = "some/define.xml",
item_oid = "IG.IRIS",
name = "IRIS",
dataset_label = "Iris",
columns = iris_items
)
```
To attach necessary metadata (that can't be inferred by the input dataframe or at time of write) to the `datasetjson` object, you can use a variety of setter functions:
```{r setters}
ds_json <- dataset_json(
head(iris, 5),
item_oid = "IG.IRIS",
name = "IRIS",
dataset_label = "Iris",
columns = iris_items
) |>
set_file_oid("/some/path") |>
set_last_modified("2025-01-21T13:34:50") |>
set_originator("Some Org") |>
set_source_system("source system", "1.0") |>
set_study_oid("SOMESTUDY") |>
set_metadata_ref("some/define.xml") |>
set_metadata_version("MDV.MSGv2.0.SDTMIG.3.3.SDTM.1.7")
```
Once the `datasetjson` object is prepared with the necessary metadata, you can use `write_dataset_json()` to write the file to disk.
```{r write_disk, eval=FALSE}
write_dataset_json(ds_json, file = "./iris.json")
```
Or if you don't provide a file path, the JSON text will return directly.
```{r write_print}
js_text <- write_dataset_json(ds_json, pretty=TRUE)
cat(js_text)
```
To read a Dataset JSON file, you can use `read_dataset_json()`. You can either provide the path to a JSON file, or if you already have the JSON text loaded into a character string, you can provide that directly.
```{r read}
dat <- read_dataset_json(js_text)
dat
```
The data frame that's returned is enriched with attributes available in the Dataset JSON format. For example, opening the dataframe within the RStudio IDE will present the variable labels. All the other metadata contained within the Dataset JSON file is attached as attributes to the resulting dataframe.
```{r dataframe_attributes}
print(attr(dat, 'dbLastModifiedDateTime'))
print(attr(dat, 'fileOID'))
```
This package currently supports Dataset JSON Version 1.1.0. Support for Version 1.0.0 has been dropped, as version 1.1.0 is intended to be the first stable version of the standard.
# [
](https://www.cdisc.org/)
## Acknowledgements
Thank you to Ben Straub and Eric Simms (GSK) for help and input during the original CDISC Dataset JSON hackathon that motivated this work.