Skip to contents

# Split REDCap repeating instruments table into multiple tables

Source: `R/REDCap_split.r`
`REDCap_split.Rd`

This will take output from a REDCap export and split it into a base table and child tables for each repeating instrument. Metadata is used to determine which fields should be included in each resultant table.

## Usage

    REDCap_split(
      records,
      metadata,
      primary_table_name = "",
      forms = c("repeating", "all")
    )

## Arguments

records

  Exported project records. May be a `data.frame`, `response`, or `character` vector containing JSON from an API call.

metadata

  Project metadata (the data dictionary). May be a `data.frame`, `response`, or `character` vector containing JSON from an API call.

primary_table_name

  Name given to the list element for the primary output table. Ignored if `forms = 'all'`.

forms

  Indicate whether to create separate tables for repeating instruments only or for all forms.

## Value

A list of `"data.frame"`s. The number of tables will differ depending on the `forms` option selected.

- `'repeating'`: one base table and one or more tables for each repeating instrument.

- `'all'`: a data.frame for each instrument, regardless of whether it is a repeating instrument or not.

## Author

Paul W. Egeler

## Examples

    if (FALSE) { # \dontrun{
    # Using an API call -------------------------------------------------------

    library(RCurl)

    # Get the records
    records <- postForm(
      uri = api_url, # Supply your site-specific URI
      token = api_token, # Supply your own API token
      content = "record",
      format = "json",
      returnFormat = "json"
    )

    # Get the metadata
    metadata <- postForm(
      uri = api_url, # Supply your site-specific URI
      token = api_token, # Supply your own API token
      content = "metadata",
      format = "json"
    )

    # Convert exported JSON strings into a list of data.frames
    REDCapCAST::REDCap_split(records, metadata)

    # Using a raw data export -------------------------------------------------

    # Get the records
    records <- read.csv("/path/to/data/ExampleProject_DATA_2018-06-03_1700.csv")

    # Get the metadata
    metadata <- read.csv(
      "/path/to/data/ExampleProject_DataDictionary_2018-06-03.csv"
    )

    # Split the tables
    REDCapCAST::REDCap_split(records, metadata)

    # In conjunction with the R export script ---------------------------------

    # You must set the working directory first since the REDCap data export
    # script contains relative file references.
    old <- getwd()
    setwd("/path/to/data/")

    # Run the data export script supplied by REDCap.
    # This will create a data.frame of your records called 'data'
    source("ExampleProject_R_2018-06-03_1700.r")

    # Get the metadatan
    metadata <- read.csv("ExampleProject_DataDictionary_2018-06-03.csv")

    # Split the tables
    REDCapCAST::REDCap_split(data, metadata)
    setwd(old)
    } # }