t1read {table1}

Read and augment data with extended metadata attributes

Description

Read and augment data with extended metadata attributes

Usage

t1read(data, metadata = NULL, read.fun = read.csv, ..., escape.html = TRUE)

Arguments

data

Either a file name (character) or a data.frame. If a file name it will be read using the function read.fun.

metadata

Either a file name (character) or a list. If a file name it will be read using the function read_yaml (so it should be a file the contains valid YAML text), and a list results. See Details regarding the list contents.

read.fun

A function to read files. It should accept a file name as its first argument and return a data.frame.

...

Further optional arguments, passed to read.fun.

escape.html

Logical. Should strings (labels, units) be converted to valid HTML by escaping special symbols?

Details

The metadata list may contain the following 3 named elements (other elements are ignored):

• labels: a named list, with names corresponding to columns in data and values the associated label attribute.

• units: a named list, with names corresponding to columns in data and values the associated units attribute.

• categoricals: a named list, with names corresponding to columns in data and values are themselves lists, used to convert the column to a factor: the list names are the levels, and the values are the associated labels. The names can also be omitted if the goal is just to specify the order of the factor levels.

Value

A data.frame (as returned by read.fun).

Examples

# Simulate some data
set.seed(123)
data <- expand.grid(sex=0:1, cohort=1:3)[rep(1:6, times=c(7, 9, 21, 22, 11, 14)),]
data$age <- runif(nrow(data), 18, 80)
data$agecat <- 1*(data$age >= 65)
data$wgt <- rnorm(nrow(data), 75, 15)

metadata <- list(
  labels=list(
    cohort = "Cohort",
    sex = "Sex",
    age = "Age",
    agecat  = "Age category",
    wgt = "Weight"),
  units=list(
    age = "years",
    wgt = "kg"),
  categoricals=list(
    cohort = list(
      `1` = "Cohort A",
      `2` = "Cohort B",
      `3` = "Cohort C"),
    sex = list(
      `0` = "Female",
      `1` = "Male"),
    agecat = list(
      `0` = "< 65",
      `1` = "\U{2265} 65")))

 data <- t1read(data, metadata)
 table1(~ sex + age + agecat + wgt | cohort, data=data)