join_keys: Manage relationships between datasets using 'join_keys'

In teal.data: Data Model for 'teal' Applications

Manage relationships between datasets using join_keys

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

...	optional, either teal_data or join_keys object to extract join_keys or any number of join_key_set objects to create join_keys or nothing to create an empty join_keys
x	(join_keys) empty object to set the new relationship pairs. x is typically an object of join_keys class. When called with the join_keys(x) or join_keys(x) <- value then it can also take a supported class (teal_data, join_keys)
i, j	indices specifying elements to extract or replace. Index should be a a character vector, but it can also take numeric, logical, NULL or missing.
directed	(logical(1)) Flag that indicates whether it should create a parent-child relationship between the datasets. TRUE (default) dataset_1 is the parent of dataset_2; FALSE when the relationship is undirected.
value	For ⁠x[i, j, directed = TRUE)] <- value⁠ (named/unnamed character) Column mapping between datasets. For join_keys(x) <- value: (join_key_set or list of join_key_set) relationship pairs to add to join_keys list. [i, j, directed = TRUE)]: R:i,%20j,%20directed%20=%20TRUE)

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[datanames]: Returns a subset of the join_keys object for given datanames, including parent datanames and symmetric mirror keys between datanames 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)

teal.data documentation built on May 29, 2024, 8:03 a.m.