xpose.xtras (version 0.2.2)

left_join_x: Backfill missing variables via a left join

Description

<dplyr::left_join> wrapper for xpose_data (and, by inheritance, xp_xtras) objects. Unlike a plain left_join(), a column present in both x and y (other than the join keys) is not duplicated with .x/.y suffixes: missing (NA) values already in x are backfilled from the matching value in y, while non-missing values already in x are left untouched. This makes it straightforward to backfill a variable (or set of variables) that is only partially recorded, from a second data source keyed on the same join variable(s) (e.g. ID).

left_join_x() accepts xpose_data/xp_xtras objects directly, with an additional .problem argument restricting which problem(s) the join is applied to.

left_join() without _x is defined as an S3 method on xpose_data, so that the usual <dplyr::left_join> generic dispatches here automatically (xp_xtras objects are handled the same way, via class inheritance).

Usage

left_join_x(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = NULL,
  .problem = NULL
)
# S3 method for xpose_data
left_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = NULL,
  .problem = NULL
)

Value

An updated xpose_data/xp_xtras object.

Arguments

x

An xpose_data or xp_xtras object.

y

A data frame (or another object coercible to one) to join in.

by

Join specification, as in <dplyr::left_join>. If NULL, a natural join is performed using variables common to x and y.

copy

If x and y are not from the same source and copy = TRUE, y is copied to bring it into the same source as x. See <dplyr::left_join>.

suffix

Suffixes used internally to disambiguate a column shared by x and y before it is backfilled into a single column; not visible in the result.

...

Other parameters passed onto <dplyr::left_join>.

keep

Passed to <dplyr::left_join>. Note that duplicate join key columns (keep = TRUE) are backfilled together like any other shared column, rather than kept separate.

.problem

The problem number(s) to which the join will be applied. Uses all problems if NULL.

Examples

# Some subjects are missing an APGR score in the base dataset
xpdb_missing <- pheno_base %>%
  mutate_x(APGR = dplyr::if_else(ID %in% c("1", "2"), NA, APGR))

# A separate table with the (complete) values, keyed on ID
apgr_lookup <- xpose::get_data(pheno_base, quiet = TRUE) %>%
  dplyr::distinct(ID, APGR)

# Existing APGR values are kept; only the missing ones are filled in
left_join_x(xpdb_missing, apgr_lookup, by = "ID")