Package 'teal.data'

Description

Function is a wrapper around teal_data() and guesses join_keys for given datasets whose names match ADAM datasets names.

Usage

cdisc_data(
  ...,
  join_keys = teal.data::default_cdisc_join_keys[names(rlang::list2(...))],
  code = character(0)
)

Arguments

Details

This function checks if there were keys added to all data sets.

Value

A teal_data object.

Examples

data <- cdisc_data(
  join_keys = join_keys(
    join_key("ADSL", "ADTTE", c("STUDYID" = "STUDYID", "USUBJID" = "USUBJID"))
  )
)

data <- within(data, {
  ADSL <- example_cdisc_data("ADSL")
  ADTTE <- example_cdisc_data("ADTTE")
})

Description

Get or set variable labels in a data.frame.

Usage

col_labels(x, fill = FALSE)

col_labels(x) <- value

col_relabel(x, ...)

Arguments

Details

Variable labels can be stored as a label attribute set on individual variables. These functions get or set this attribute, either on all (col_labels) or some variables (col_relabel).

Value

For col_labels, named character vector of variable labels, the names being the corresponding variable names. If the label attribute is missing, the vector elements will be the variable names themselves if fill = TRUE and NA if fill = FALSE.

For ⁠col_labels<-⁠ and col_relabel, copy of x with variable labels modified.

Source

These functions were taken from formatters package, to reduce the complexity of the dependency tree and rewritten.

Examples

x <- iris
col_labels(x)
col_labels(x) <- paste("label for", names(iris))
col_labels(x)
y <- col_relabel(x, Sepal.Length = "Sepal Length of iris flower")
col_labels(y)

Description

These represent primary and foreign keys for joining CDISC datasets.

Usage

default_cdisc_join_keys

Format

An object of class join_keys (inherits from list) of length 19.

Source

internal. See data-raw/cdisc_datasets.yaml and data-raw/data.R for details.

See Also

join_keys()

Examples

default_cdisc_join_keys
default_cdisc_join_keys[c("ADSL", "ADAE")] # Subset for ADSL and ADAE

Description

Retrieves example CDISC datasets for use in examples and testing.

Usage

example_cdisc_data(
  dataname = c("ADSL", "ADAE", "ADLB", "ADCM", "ADEX", "ADRS", "ADTR", "ADTTE", "ADVS")
)

Arguments

Details

This function returns a dummy dataset and should only be used within teal.data. Note that the datasets are not created and maintained in teal.data, they are retrieved from random.cdisc.data package.

Value

A CDISC dataset as a data.frame.

Description

Retrieve code from teal_data object.

Usage

## S4 method for signature 'teal_data'
get_code(
  object,
  deparse = TRUE,
  names = NULL,
  datanames = lifecycle::deprecated(),
  ...
)

Arguments

Details

Retrieve code stored in ⁠@code⁠, which (in principle) can be used to recreate all objects found in the environment (⁠@.xData⁠). Use names to limit the code to one or more of the datasets enumerated in the environment.

Value

Either a character string or an expression. If names is used to request a specific dataset, only code that creates that dataset (not code that uses it) is returned. Otherwise, all contents of ⁠@code⁠.

Extracting dataset-specific code

When names is specified, the code returned will be limited to the lines needed to create the requested datasets. The code stored in the ⁠@code⁠ slot is analyzed statically to determine which lines the datasets of interest depend upon. The analysis works well when objects are created with standard infix assignment operators (see ?assignOps) but it can fail in some situations.

Consider the following examples:

Case 1: Usual assignments.

data <- teal_data() |>
  within({
    foo <- function(x) {
      x + 1
    }
    x <- 0
    y <- foo(x)
  })
get_code(data, names = "y")

x has no dependencies, so get_code(data, names = "x") will return only the second call.
y depends on x and foo, so get_code(data, names = "y") will contain all three calls.

Case 2: Some objects are created by a function's side effects.

data <- teal_data() |>
  within({
    foo <- function() {
      x <<- x + 1
    }
    x <- 0
    foo()
    y <- x
  })
get_code(data, names = "y")

Here, y depends on x but x is modified by foo as a side effect (not by reassignment) and so get_code(data, names = "y") will not return the foo() call.
To overcome this limitation, code dependencies can be specified manually. Lines where side effects occur can be flagged by adding "⁠# @linksto <object name>⁠" at the end.
Note that within evaluates code passed to expr as is and comments are ignored. In order to include comments in code one must use the eval_code function instead.

data <- teal_data() |>
  eval_code("
    foo <- function() {
      x <<- x + 1
    }
    x <- 0
    foo() # @linksto x
    y <- x
  ")
get_code(data, names = "y")

Now the foo() call will be properly included in the code required to recreate y.

Note that two functions that create objects as side effects, assign and data, are handled automatically.

Here are known cases where manual tagging is necessary:

• non-standard assignment operators, e.g. ⁠%<>%⁠

• objects used as conditions in if statements: ⁠if (<condition>)⁠

• objects used to iterate over in for loops: ⁠for(i in <sequence>)⁠

• creating and evaluating language objects, e.g. ⁠eval(<call>)⁠

Examples

tdata1 <- teal_data()
tdata1 <- within(tdata1, {
  a <- 1
  b <- a^5
  c <- list(x = 2)
})
get_code(tdata1)
get_code(tdata1, names = "a")
get_code(tdata1, names = "b")

tdata2 <- teal_data(x1 = iris, code = "x1 <- iris")
get_code(tdata2)
get_code(verify(tdata2))

Description

Create a relationship between two datasets, dataset_1 and dataset_2. By default, this function establishes a directed relationship with dataset_1 as the parent. If dataset_2 is not specified, the function creates a primary key for dataset_1.

Usage

join_key(dataset_1, dataset_2 = dataset_1, keys, directed = TRUE)

Arguments

Value

object of class join_key_set to be passed into join_keys function.

See Also

join_keys(), parents()

Examples

join_key("d1", "d2", c("A"))
join_key("d1", "d2", c("A" = "B"))
join_key("d1", "d2", c("A" = "B", "C"))

Description

Facilitates the creation and retrieval of relationships between datasets. join_keys class extends list and contains keys connecting pairs of datasets. Each element of the list contains keys for specific dataset. Each dataset can have a relationship with itself (primary key) and with other datasets.

Note that join_keys list is symmetrical and assumes a default direction, that is: when keys are set between ds1 and ds2, it defines ds1 as the parent in a parent-child relationship and the mapping is automatically mirrored between ds2 and ds1.

Usage

## Constructor, getter and setter
join_keys(...)

## Default S3 method:
join_keys(...)

## S3 method for class 'join_keys'
join_keys(...)

## S3 method for class 'teal_data'
join_keys(...)

## S3 method for class 'join_keys'
x[i, j]

## S3 replacement method for class 'join_keys'
x[i, j, directed = TRUE] <- value

## S3 method for class 'join_keys'
c(...)

## S3 method for class 'join_key_set'
c(...)

join_keys(x) <- value

## S3 replacement method for class 'join_keys'
join_keys(x) <- value

## S3 replacement method for class 'teal_data'
join_keys(x) <- value

## S3 method for class 'join_keys'
format(x, ...)

## S3 method for class 'join_keys'
print(x, ...)

Arguments

Value

join_keys object.

Methods (by class)

• join_keys(): Returns an empty join_keys object when called without arguments.

• join_keys(join_keys): Returns itself.

• join_keys(teal_data): Returns the join_keys object contained in teal_data object.

• join_keys(...): Creates a new object with one or more join_key_set parameters.

Functions

• x[names]: Returns a subset of the join_keys object for given names, including parent names and symmetric mirror keys between names in the result.

• x[i, j]: Returns join keys between datasets i and j, including implicit keys inferred from their relationship with a parent.

• x[i, j] <- value: Assignment of a key to pair ⁠(i, j)⁠.

• x[i] <- value: This (without j parameter) is not a supported operation for join_keys.

• join_keys(x)[i, j] <- value: Assignment to join_keys object stored in x, such as a teal_data object or join_keys object itself.

• join_keys(x) <- value: Assignment of the join_keys in object with value. value needs to be an object of class join_keys or join_key_set.

See Also

join_key() for creating join_keys_set, parents() for parent operations, teal_data() for teal_data constructor and default_cdisc_join_keys for default CDISC keys.

Examples

# Creating a new join keys ----

jk <- join_keys(
  join_key("ds1", "ds1", "pk1"),
  join_key("ds2", "ds2", "pk2"),
  join_key("ds3", "ds3", "pk3"),
  join_key("ds1", "ds2", c(pk1 = "pk2")),
  join_key("ds1", "ds3", c(pk1 = "pk3"))
)

jk

# Getter for join_keys ---

jk["ds1", "ds2"]

# Subsetting join_keys ----

jk["ds1"]
jk[1:2]
jk[c("ds1", "ds2")]

# Setting a new primary key ---

jk["ds4", "ds4"] <- "pk4"
jk["ds5", "ds5"] <- "pk5"

# Setting a single relationship pair ---

jk["ds1", "ds4"] <- c("pk1" = "pk4")

# Removing a key ---

jk["ds5", "ds5"] <- NULL
# Merging multiple `join_keys` objects ---

jk_merged <- c(
  jk,
  join_keys(
    join_key("ds4", keys = c("pk4", "pk4_2")),
    join_key("ds3", "ds4", c(pk3 = "pk4_2"))
  )
)
# note: merge can be performed with both join_keys and join_key_set

jk_merged <- c(
  jk_merged,
  join_key("ds5", keys = "pk5"),
  join_key("ds1", "ds5", c(pk1 = "pk5"))
)
# Assigning keys via join_keys(x)[i, j] <- value ----

obj <- join_keys()
# or
obj <- teal_data()

join_keys(obj)["ds1", "ds1"] <- "pk1"
join_keys(obj)["ds2", "ds2"] <- "pk2"
join_keys(obj)["ds3", "ds3"] <- "pk3"
join_keys(obj)["ds1", "ds2"] <- c(pk1 = "pk2")
join_keys(obj)["ds1", "ds3"] <- c(pk1 = "pk3")

identical(jk, join_keys(obj))
# Setter for join_keys within teal_data ----

td <- teal_data()
join_keys(td) <- jk

join_keys(td)["ds1", "ds2"] <- "new_key"
join_keys(td) <- c(join_keys(td), join_keys(join_key("ds3", "ds2", "key3")))
join_keys(td)

Description

Functions to get the names of a teal_data object. The names are obtained from the objects listed in the qenv environment.

Usage

## S3 method for class 'teal_data'
names(x)

Arguments

Details

Objects named with a . (dot) prefix will be ignored and not returned. To get the names of all objects, use ls(x, all.names = TRUE), however, it will not group the names by the join_keys topological structure.

In order to rename objects in the teal_data object, use base R functions (see examples).

Value

A character vector of names.

Examples

td <- teal_data(iris = iris)
td <- within(td, mtcars <- mtcars)
names(td)

# hidden objects with dot-prefix
td <- within(td, .CO2 <- CO2)
names(td) # '.CO2' will not be returned

# rename objects
td <- teal_data(iris = iris)
td <- within(td, {
  new_iris <- iris
  rm(iris)
})
names(td) # only 'new_iris' will be returned

Description

The names of a join_keys object

Usage

## S3 replacement method for class 'join_keys'
names(x) <- value

Arguments

Description

parents() facilitates the creation of dependencies between datasets by assigning a parent-child relationship.

Usage

parents(x)

## S3 method for class 'join_keys'
parents(x)

## S3 method for class 'teal_data'
parents(x)

parents(x) <- value

## S3 replacement method for class 'join_keys'
parents(x) <- value

## S3 replacement method for class 'teal_data'
parents(x) <- value

parent(x, dataset_name)

Arguments

Details

Each element is defined by a list element, where list("child" = "parent").

Value

a list of character representing the parents.

For parent(x, dataset_name) returns NULL if parent does not exist.

Methods (by class)

• parents(join_keys): Retrieves parents of join_keys object.

• parents(teal_data): Retrieves parents of join_keys inside teal_data object.

Functions

• parents(x) <- value: Assignment of parents in join_keys object.

• parents(join_keys) <- value: Assignment of parents of join_keys object.

• parents(teal_data) <- value: Assignment of parents of join_keys inside teal_data object.

• parent(): Getter for individual parent.

See Also

join_keys()

Examples

# Get parents of join_keys ---

jk <- default_cdisc_join_keys["ADEX"]
parents(jk)
# Get parents of join_keys inside teal_data object ---

td <- teal_data(
  ADSL = rADSL,
  ADTTE = rADTTE,
  ADRS = rADRS,
  join_keys = default_cdisc_join_keys[c("ADSL", "ADTTE", "ADRS")]
)
parents(td)
# Assignment of parents ---

jk <- join_keys(
  join_key("ds1", "ds2", "id"),
  join_key("ds5", "ds6", "id"),
  join_key("ds7", "ds6", "id")
)

parents(jk) <- list(ds2 = "ds1")

# Setting individual parent-child relationship

parents(jk)["ds6"] <- "ds5"
parents(jk)["ds7"] <- "ds6"
# Assignment of parents of join_keys inside teal_data object ---

parents(td) <- list("ADTTE" = "ADSL") # replace existing
parents(td)["ADRS"] <- "ADSL" # add new parent
# Get individual parent ---

parent(jk, "ds2")
parent(td, "ADTTE")

Description

This package contains random datasets that are used for testing purposes in the teal.data package:

• rADSL Random subject-level analysis dataset

• rADAE: Random adverse events analysis dataset

• rADCM: Random concomitant medications analysis dataset

• rADEX: Random response analysis dataset

• rADLB: Random laboratory data analysis dataset

• rADRS: Random response analysis dataset

• rADTR: Random tumor response analysis dataset

• rADTTE: Random time to event analysis dataset

• rADVS: Random vital signs analysis dataset

Usage

rADSL

rADAE

rADCM

rADEX

rADLB

rADRS

rADTR

rADTTE

rADVS

Format

• rADSL: An object of class tbl_df (inherits from tbl, data.frame) with 400 rows and 55 columns.

• rADAE: An object of class tbl_df (inherits from tbl, data.frame) with 1934 rows and 92 columns.

• rADCM: An object of class tbl_df (inherits from tbl, data.frame) with 3685 rows and 83 columns.

• rADEX: An object of class tbl_df (inherits from tbl, data.frame) with 6400 rows and 79 columns.

• rADLB: An object of class tbl_df (inherits from tbl, data.frame) with 8400 rows and 102 columns.

• rADRS: An object of class tbl_df (inherits from tbl, data.frame) with 3200 rows and 65 columns.

• rADTR: An object of class tbl_df (inherits from tbl, data.frame) with 2800 rows and 76 columns.

• rADTTE: An object of class tbl_df (inherits from tbl, data.frame) with 2000 rows and 67 columns.

• rADVS: An object of class tbl_df (inherits from tbl, data.frame) with 16800 rows and 87 columns.

Source

• rADSL: random.cdisc.data::cadsl

• rADAE: random.cdisc.data::cadae

• rADCM: random.cdisc.data::cadcm

• rADEX: random.cdisc.data::cadex

• rADLB: random.cdisc.data::cadlb

• rADRS: random.cdisc.data::cadrs

• rADTR: random.cdisc.data::cadtr

• rADTTE: random.cdisc.data::cadtte

• rADVS: random.cdisc.data::cadvs

Description

Prints teal_data object.

Usage

## S4 method for signature 'teal_data'
show(object)

Arguments

Value

Input teal_data object.

Examples

teal_data()
teal_data(x = iris, code = "x = iris")
verify(teal_data(x = iris, code = "x = iris"))

Description

Initializes a data for teal application.

Usage

teal_data(..., join_keys = teal.data::join_keys(), code = character(0))

## S3 method for class 'teal_data'
x[names]

Arguments

Details

A teal_data is meant to be used for reproducibility purposes. The class inherits from teal.code::qenv and we encourage to get familiar with teal.code first. teal_data has following characteristics:

• It inherits from the environment and methods such as $, get(), ls(), as.list(), parent.env() work out of the box.

• teal_data is a locked environment, and data modification is only possible through the teal.code::eval_code() and within.qenv() functions.

• It stores metadata about the code used to create the data (see get_code()).

• It supports slicing (see teal.code::subset-qenv)

• Is immutable which means that each code evaluation does not modify the original teal_data environment directly.

• It maintains information about relationships between datasets (see join_keys()).

Value

A teal_data object.

Subsetting

x[names] subsets objects in teal_data environment and limit the code to the necessary needed to build limited objects.

See Also

teal.code::eval_code, get_code(), join_keys(), names.teal_data()

Examples

teal_data(x1 = iris, x2 = mtcars)


# Subsetting
data <- teal_data()
data <- eval_code(data, "a <- 1;b<-2")
data["a"]
data[c("a", "b")]

join_keys(data) <- join_keys(join_key("a", "b", "x"))
join_keys(data["a"]) # should show empty keys
join_keys(data["b"])
join_keys(data)["a"] # should show empty keys
join_keys(data)["b"]

Description

Checks whether code in teal_data object reproduces the stored objects.

Usage

verify(x)

Arguments

Details

If objects created by code in the ⁠@code⁠ slot of x are all_equal to the contents of the environment (⁠@.xData⁠ slot), the function updates the ⁠@verified⁠ slot to TRUE in the returned teal_data object. Once verified, the slot will always be set to TRUE. If the ⁠@code⁠ fails to recreate objects in teal_data's environment, an error is raised.

Value

Input teal_data object or error.

Examples

tdata1 <- teal_data()
tdata1 <- within(tdata1, {
  a <- 1
  b <- a^5
  c <- list(x = 2)
})
verify(tdata1)

tdata2 <- teal_data(x1 = iris, code = "x1 <- iris")
verify(tdata2)
verify(tdata2)@verified
tdata2@verified

tdata3 <- teal_data()
tdata3 <- within(tdata3, {
  stop("error")
})
try(verify(tdata3)) # fails


a <- 1
b <- a + 2
c <- list(x = 2)
d <- 5
tdata4 <- teal_data(
  a = a, b = b, c = c, d = d,
  code = "a <- 1
          b <- a
          c <- list(x = 2)
          e <- 1"
)
tdata4
## Not run: 
verify(tdata4) # fails

## End(Not run)