diff --git a/README.md b/README.md index c014dd7..f62f82d 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,11 @@ experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](h # REDCapCAST package -REDCap Castellated data handling when using repeated instruments. +REDCap database casting and handling of castellated data when using repeated instruments and longitudinal projects. This package is a fork of [pegeler/REDCapRITS](https://github.com/pegeler/REDCapRITS). The REDCapRITS represents great and extensive work to handle castellated REDCap data in different programming languages. This fork is purely minded on R usage and includes a few implementations of the main `REDCap_split` function. -The main goal for this project was to allow for a "minimal data" approach by allowing to filter records, instruments and variables in the export to only download data needed. I think this approach is desireable for handling sensitive, clinical data. No similar functionality is available from similar tools (like `REDCapR` or `REDCapTidieR`). Please refer to [REDCap-Tools](https://redcap-tools.github.io/) for other great tools. +THis package is very much to be seen as an attempt at a REDCap-R foundry for handling both the transition from dataset/variable list to database and the other way, from REDCap database to a tidy dataset. The goal was also to allow for a "minimal data" approach by allowing to filter records, instruments and variables in the export to only download data needed. I think this approach is desireable for handling sensitive, clinical data. No similar functionality is available from similar tools (like `REDCapR` or `REDCapTidieR`). Please refer to [REDCap-Tools](https://redcap-tools.github.io/) for other great tools. ## Use and immprovements @@ -30,8 +30,7 @@ This package is primarily relevant for working with longitudinal projects and/or * `easy_redcap()`: combines secure API key storage with the `keyring`-package, focused data retrieval and optional widening. This is the recommended approach for easy data access and analysis. - -Compared to the original `REDCapRITS`, all matching functions are improved to accept column naming of REDCap data from manual download or API export. +... ## Future diff --git a/vignettes/Database creation.Rmd b/vignettes/Database creation.Rmd new file mode 100644 index 0000000..088fa8b --- /dev/null +++ b/vignettes/Database creation.Rmd @@ -0,0 +1,81 @@ +--- +title: "Database casting" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Database casting} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) +``` + +```{r setup} +library(REDCapCAST) +``` + +# Easy data set to data base workflow + +THe first iteration of a dataset to data dictionary function is the `ds2dd()`, which creates a very basic data dictionary with all variables stored as text. This is sufficient for just storing old datasets/spreadsheets securely in REDCap. + +```{r} +mtcars |> + dplyr::mutate(record_id = seq_len(dplyr::n())) |> + ds2dd() +``` + +The more advanced `ds2dd_detailed()` is a natural development. It will try to apply the most common data classes for data validation and will assume that the first column is the id number. It outputs a list with the dataset with modified variable names to comply with REDCap naming conventions and a data dictionary. + +The dataset should be correctly formatted for the data dictionary to preserve as much information as possible. + +```{r} +dd_ls <- mtcars |> + dplyr::mutate(record_id = seq_len(dplyr::n())) |> + dplyr::select(record_id, dplyr::everything()) |> + ds2dd_detailed() +dd_ls |> str() +``` + +Additional specifications to the DataDictionary can be made manually, or it can be uploaded and modified manually in the graphical user interface on the web page. + +## Step 3 - Meta data upload + +Now the DataDictionary can be exported as a spreadsheet and uploaded or it can be uploaded using the `REDCapR` package (only projects with "Development" status). + +Use one of the two approaches below: + +### Manual upload + +```{r eval=FALSE} +write.csv(dd_ls$meta, "datadictionary.csv") +``` + +### Upload with `REDCapR` + +```{r eval=FALSE} +REDCapR::redcap_metadata_write( + dd_ls$meta, + redcap_uri = keyring::key_get("DB_URI"), + token = keyring::key_get("DB_TOKEN") +) +``` + +In the ["REDCap R Handbook"](https://agdamsbo.github.io/redcap-r-handbook/) more is written on interfacing with REDCap in R using the `library(keyring)`to store credentials in [chapter 1.1](https://agdamsbo.github.io/redcap-r-handbook/access.html#sec-getting-access). + +## Step 4 - Data upload + +The same two options are available for data upload as meta data upload: manual or through `REDCapR`. + +Only the latter is shown here. + +```{r eval=FALSE} +REDCapR::redcap_write( + dd_ls$data, + redcap_uri = keyring::key_get("DB_URI"), + token = keyring::key_get("DB_TOKEN") +) +``` diff --git a/vignettes/Shiny casting.Rmd b/vignettes/Shiny casting.Rmd new file mode 100644 index 0000000..c2c1629 --- /dev/null +++ b/vignettes/Shiny casting.Rmd @@ -0,0 +1,30 @@ +--- +title: "Introduction" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Introduction} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) +``` + +```{r setup} +library(REDCapCAST) +``` + +To make the easiest possible transistion from spreadsheet/dataset to REDCap, I have created a small Shiny app, which adds a graphical interface to the casting of a data dictionary and data upload. Install the package and run the app as follows: + +```{r} +require(REDCapCAST) +shiny_cast() +``` + +The app will launch in a new window and the interface should be fairly self-explanatory. +The app only provides the most basic functionality, but might be extended in the future. +