Left join data onto a qseaSet sample table

Extends dplyr::left_join() to merge a data frame into a qseaSet's sampleTable. Useful for adding annotations or metadata to samples.

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

Arguments

x

qseaSet. A qseaSet object whose sampleTable will receive additional columns.

y

data.frame. A data frame or tibble to join onto the sampleTable.

by

character() or named character(). Join keys, as in dplyr::left_join(). For qseaSets, the safest choice is by = "sample_name". Default: NULL (all common variables between x@sampleTable and y).

copy

logical(1). For remote backends only. If TRUE, copies y into the same data source as x. Ignored for in-memory data frames. Default: FALSE.

suffix

character(2). Suffixes appended to overlapping non-join column names from x and y. Default: c(".x", ".y").

keep

logical(1) or NULL. If TRUE, keeps join keys from both x and y. If FALSE, only keys from x are kept. Default: NULL (deferred to dplyr::left_join() behaviour).

...

Additional arguments passed to dplyr::left_join(), e.g. relationship = "one-to-one" (dplyr >= 1.1). Default: none.

Value

A qseaSet object with its sampleTable updated:

• existing rows preserved,

• additional columns from y merged by sample name or other keys,

• duplicate column names disambiguated with suffix.

See also

qsea::getSampleTable() to view metadata, mutate.qseaSet(), filter.qseaSet() for other dplyr verbs, dplyr::left_join() for join semantics.

Examples

data(exampleTumourNormal, package = "mesa")

# Join 'patient' (y) to 'sample_name' (x)
newData <- tibble::tibble(
    patient = c("Colon1", "Colon2", "Lung1", "Lung3"),
    new = 1:4
)
exampleTumourNormal %>%
    left_join(newData, by = c("sample_name" = "patient")) %>%
    qsea::getSampleTable()
#>          sample_name    group patient        type tumour tissue age gender
#> Colon1_N    Colon1_N Colon1_N  Colon1 NormalColon Normal  Colon  80      F
#> Colon1_T    Colon1_T Colon1_T  Colon1         CRC Tumour  Colon  80      F
#> Colon2_N    Colon2_N Colon2_N  Colon2 NormalColon Normal  Colon  67      F
#> Colon2_T    Colon2_T Colon2_T  Colon2         CRC Tumour  Colon  67      F
#> Lung1_N      Lung1_N  Lung1_N   Lung1  NormalLung Normal   Lung  64      F
#> Lung1_T      Lung1_T  Lung1_T   Lung1        LUAD Tumour   Lung  64      F
#> Lung2_N      Lung2_N  Lung2_N   Lung2  NormalLung Normal   Lung  71      F
#> Lung2_T      Lung2_T  Lung2_T   Lung2        LUSC Tumour   Lung  71      F
#> Lung3_N      Lung3_N  Lung3_N   Lung3  NormalLung Normal   Lung  72      M
#> Lung3_T      Lung3_T  Lung3_T   Lung3        LUAD Tumour   Lung  72      M
#>          stage new
#> Colon1_N  <NA>  NA
#> Colon1_T   III  NA
#> Colon2_N  <NA>  NA
#> Colon2_T    IV  NA
#> Lung1_N   <NA>  NA
#> Lung1_T    IIA  NA
#> Lung2_N   <NA>  NA
#> Lung2_T     IA  NA
#> Lung3_N   <NA>  NA
#> Lung3_T     IB  NA