Merge SE objects into single SE object.

Merge SE objects into single SE object.

mergeSEs(x, y, ...)

# S4 method for class 'SimpleList,missing'
mergeSEs(
  x,
  y,
  assay.type = assay_name,
  assay_name = "counts",
  join = "full",
  missing.values = missing_values,
  missing_values = NA,
  collapse.cols = collapse_samples,
  collapse_samples = FALSE,
  collapse.rows = collapse_features,
  collapse_features = TRUE,
  ...
)

# S4 method for class 'SummarizedExperiment,SummarizedExperiment'
mergeSEs(x, y, ...)

# S4 method for class 'list,missing'
mergeSEs(x, y, ...)

Arguments

x

TreeSummarizedExperiment.

y

a SummarizedExperiment object when x is a SummarizedExperiment object. Must be missing when x is a list.

...

optional arguments (not used).

assay.type

Character scalar. Specifies the name of assay used in calculation. (Default: "counts")

assay_name

Deprecated. Use assay.type instead.

join

Character scalar. A value for selecting the joining method. Must be 'full', 'inner', 'left', or 'right'. 'left' and 'right' are disabled when more than two objects are being merged. (Default: "full")

missing.values

NA, 0 or Character scalar. Specifies the notation of missing values. (By default: NA)

missing_values

Deprecated. Use missing.values instead.

collapse.cols

Logical scalar. Determines whether to collapse identically named samples to one. (Default: FALSE)

collapse_samples

Deprecated. Use collapse.cols instead.

collapse.rows

Logical scalar. Determines whether to collapse features that have identical names and taxonomy to one. (Default: TRUE)

collapse_features

Deprecated. Use collapse.rows instead.

Value

A single SummarizedExperiment object.

Details

This function merges multiple SummarizedExperiment objects. It combines assays, rowData, colData, and metadata so that the output includes each unique row and column. The merging is done based on rownames and colnames.

Rows are matched based on rownames and taxonomy ranks of rowData, i.e., rows are interpreted as equal if they have the same name and taxonomy (unless collapse.rows = FALSE). Rows that have the same name but differently annotated taxonomy are kept as separate rows. To merge data at certain taxonomy level, agglomerate the objects first with agglomerateByRank. Duplicated names within an object are made unique. For samples, collapsing is disabled by default meaning that equally named samples that are stored in different objects are interpreted as unique. Collapsing can be enabled with collapse.cols = TRUE when equally named samples describe the same sample. Equally named rows or columns that are not collapsed are made unique with make.unique. When the same value is found from multiple objects, the value from the first object is used. If equally named rowData or colData variables have different classes, they are combined as character. Taxonomy rank columns of rowData are matched case-insensitively, e.g., "genus" and "Genus".

If, for example, all rows are not shared with individual objects, there are missing values in assays. The notation of missing can be specified with the missing.values argument.

If input consists of TreeSummarizedExperiment objects, also referenceSeq, rowTree, and colTree are preserved if possible. Reference sequences are merged if a sequence is available for every row. Trees are not merged; a tree is added only if a single input tree includes all the rows (or columns) of the merged data. Otherwise, the tree is dropped with a warning.

Compared to cbind and rbind mergeSEs allows more freely merging since cbind and rbind expect that rows and columns are matching, respectively.

You can choose joining methods from 'full', 'inner', 'left', and 'right'. In all the methods, all the samples are included in the result object. However, with different methods, it is possible to choose which rows are included.

• full – all unique features

• inner – all shared features

• left – all the features of the first object

• right – all the features of the second object

The output depends on the input. If the input contains SummarizedExperiment object, then the output will be SummarizedExperiment. When all the input objects belong to TreeSummarizedExperiment, the output will be TreeSummarizedExperiment.

See also

• TreeSummarizedExperiment::cbind

• TreeSummarizedExperiment::rbind

• full_join

• inner_join

• left_join

• right_join

Examples

data(GlobalPatterns)
data(esophagus)
data(enterotype)

# Take only subsets so that it wont take so long
tse1 <- GlobalPatterns[1:100, ]
tse2 <- esophagus
tse3 <- enterotype[1:100, ]

# Merge two TreeSEs
tse <- mergeSEs(tse1, tse2)
#> Warning: rowTree is dropped since none of the input trees includes all the rows. Trees are not merged.

# Merge a list of TreeSEs
list <- SimpleList(tse1, tse2, tse3)
tse <- mergeSEs(list, assay.type = "counts", missing.values = 0)
#> Warning: rowTree is dropped since none of the input trees includes all the rows. Trees are not merged.
tse
#> class: TreeSummarizedExperiment 
#> dim: 258 309 
#> metadata(0):
#> assays(1): counts
#> rownames(258): 549322 522457 ... Providencia Salmonella
#> rowData names(7): Kingdom Phylum ... Genus Species
#> colnames(309): CL3 CC1 ... TS98_V2 TS99.2_V2
#> colData names(16): X.SampleID Primer ... Age ClinicalStatus
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> rowLinks: NULL
#> rowTree: NULL
#> colLinks: NULL
#> colTree: NULL

# With 'join', it is possible to specify the merging method. Subsets are used
# here just to show the functionality
tse_temp <- mergeSEs(tse[1:10, 1:10], tse[5:100, 11:20], join = "left")
tse_temp
#> class: TreeSummarizedExperiment 
#> dim: 10 20 
#> metadata(0):
#> assays(1): counts
#> rownames(10): 549322 522457 ... 255340 144887
#> rowData names(7): Kingdom Phylum ... Genus Species
#> colnames(20): CL3 CC1 ... TRRsed1 TRRsed2
#> colData names(16): X.SampleID Primer ... Age ClinicalStatus
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> rowLinks: NULL
#> rowTree: NULL
#> colLinks: NULL
#> colTree: NULL

# If your objects contain samples that describe one and same sample,
# you can collapse equally named samples to one by specifying 'collapse.cols'
tse_temp <- mergeSEs(list(tse[1:10, 1], tse[1:20, 1], tse[1:5, 1]),
                       collapse.cols = TRUE,
                       join = "inner")
tse_temp
#> class: TreeSummarizedExperiment 
#> dim: 5 1 
#> metadata(0):
#> assays(1): counts
#> rownames(5): 549322 522457 951 244423 586076
#> rowData names(7): Kingdom Phylum ... Genus Species
#> colnames(1): CL3
#> colData names(16): X.SampleID Primer ... Age ClinicalStatus
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> rowLinks: NULL
#> rowTree: NULL
#> colLinks: NULL
#> colTree: NULL

# Merge all available assays
tse <- transformAssay(tse, method="relabundance")
#> Warning: result contains NaN, perhaps due to impossible mathematical
#>                  operation
ts1 <- transformAssay(tse1, method="relabundance")
tse_temp <- mergeSEs(tse, tse1, assay.type = assayNames(tse))
#> Warning: The following assay(s) was not found from all the objects so it is dropped from the output: 'relabundance'
#> Warning: rowTree is dropped since none of the input trees includes all the rows. Trees are not merged.