Skip to contents

Join tidymatrix with another data frame

Source: R/joins.R
joins.Rd

These functions are tidymatrix methods for dplyr's join functions. They join the row_data or col_data (depending on which is active) with an external data.frame, and appropriately update the matrix dimensions.

Usage

# S3 method for class 'tidymatrix'
left_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = NULL
)

# S3 method for class 'tidymatrix'
right_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = NULL
)

# S3 method for class 'tidymatrix'
inner_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = NULL
)

# S3 method for class 'tidymatrix'
full_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = NULL
)

# S3 method for class 'tidymatrix'
semi_join(x, y, by = NULL, copy = FALSE, ...)

# S3 method for class 'tidymatrix'
anti_join(x, y, by = NULL, copy = FALSE, ...)

Arguments

x

A tidymatrix object

y

A data frame or tibble to join with

by

A character vector of variables to join by. If NULL, uses all variables that appear in both tables.

copy

If y is not a data frame or tibble, this controls whether to copy it or not.

suffix

If there are non-joined duplicate variables in x and y, these suffixes will be added to disambiguate them.

...

Additional arguments passed to the corresponding dplyr join function

keep

Control which join keys to preserve in the output (see left_join).

Value

A tidymatrix object with joined metadata and updated matrix

Details

Joins work on the active dimension (rows or columns). Use activate() to specify which metadata to join.

When joins add new rows/columns (e.g., right_join, full_join), the matrix is expanded with NA values for the new entries.

When joins remove rows/columns (e.g., inner_join, semi_join, anti_join), the matrix is subset accordingly.

All joins invalidate stored analyses, as the matrix dimensions may have changed.

Examples

library(dplyr)

# Create example tidymatrix
mat <- matrix(rnorm(50), nrow = 10, ncol = 5)
row_data <- data.frame(gene_id = paste0("Gene_", 1:10))
col_data <- data.frame(sample_id = paste0("Sample_", 1:5))
tm <- tidymatrix(mat, row_data, col_data)

# Create external annotation data
annotations <- data.frame(
  gene_id = paste0("Gene_", c(1:8, 15:17)),
  pathway = sample(c("A", "B"), 11, replace = TRUE)
)

# Left join - keep all genes from tidymatrix
tm_left <- tm |>
  activate(rows) |>
  left_join(annotations, by = "gene_id")

# Inner join - keep only matching genes
tm_inner <- tm |>
  activate(rows) |>
  inner_join(annotations, by = "gene_id")

# Full join - keep all genes from both
tm_full <- tm |>
  activate(rows) |>
  full_join(annotations, by = "gene_id")