stRoke/vignettes/ds2dd.Rmd

---
title: "ds2dd"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{ds2dd}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(stRoke)
```

# Easy data set to data base workflow

This function can be used as a simple tool for creating at data base metadata file for REDCap (called a DataDictionary) based on a given data set file.

## Step 1 - Load your data set

Here we'll use the sample TALOS dataset included with the package.

```{r}
data("talos")
ds <- talos
# As the data set lacks an ID column, one is added
ds$id <- seq_len(nrow(ds))
```

## Step 2 - Create the DataDictionary

```{r}
datadictionary <- ds2dd(ds,record.id = "id",include.column.names = TRUE)
```

Now 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.

The function will transform column names to lower case and substitute spaces for underscores. The output is a list with the DataDictionary and a vector of new column names for the dataset to fit the meta data.

## 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(datadictionary$DataDictionary,"datadictionary.csv")
```

### Upload with `REDCapR`

```{r eval=FALSE}
REDCapR::redcap_metadata_write(
  datadictionary$DataDictionary,
  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}
# new column names are applied
colnames(ds) <- datadictionary$`Column names`

REDCapR::redcap_write(
  ds,
  redcap_uri = keyring::key_get("DB_URI"),
  token = keyring::key_get("DB_TOKEN")
)
```