Adding data to row/colData

[RiboRings]

Hi!

Recently I came across a potential utility for the SE package. If you see utility in this usage, I would be happy to develop it further and contribute to the SE package.

Packages such as ALDEx2 and Maaslin3 for differential abundance analysis do not return SE objects but rather a data.frame of statistical results. Since I wanted to integrate these results with rowTree and other information contained in the SE to make comprehensive plots, I repeatedly found myself adding the results to the rowData:

### After running differential abundance analysis

# Add feature IDs to results rownames
rownames(maaslin3_res) <- maaslin3_res$feature
# Match results rows to tse rows
tax.order <- match(rownames(tse), rownames(maaslin3_res))
# Add results to rowData
rowData(tse) <- cbind(rowData(tse), maaslin3_abund[tax.order, ])

I ended up writing a function for this as I needed it multiple times in the analysis:

# Add feature IDs to results rownames
rownames(maaslin3_res) <- maaslin3_res$feature
# Add results to rowData
tse <- addToRowData(tse, maaslin3_res)

This is a simple draft of the function:

addToRowData <- function(x, y, suffix = ""){
  rowData(x) <- .add_to_side(x, y, 1L, suffix)
  return(x)
}

addToColData <- function(x, y, suffix = ""){
  colData(x) <- .add_to_side(x, y, 2L, suffix)
  return(x)
}

.add_to_side <- function(x, y, by, suffix){
    FUN <- switch(by, rowData, colData)
    df <- as.data.frame(FUN(x))
    names(y) <- paste(names(y), suffix, sep = ".")
    row.order <- match(rownames(df), rownames(y))
    new.y <- cbind(df, y[row.order, , drop = FALSE])
    return(new.y)
}

[vjcitn]

Thanks for this. We'll discuss in core.

[hpages]

Both addToRowData() and addToColData() rely on a "left join" operation that is based on the rownames of the 2 objects to join.

Note that we have combineCols() in S4Vectors that takes care of shuffling the rows of the right object to align them with the rows of the left object based on the rownames. It also takes care of filling unmatched rows with NAs:

library(S4Vectors)
df1 <- DataFrame(aa=letters[1:5], bb=runif(5), row.names=c("Z", LETTERS[1:4]))
df2 <- data.frame(cc=1:6, dd=letters[21:26], row.names=LETTERS[7:2])
combineCols(df1, df2)
# DataFrame with 8 rows and 4 columns
#            aa        bb        cc          dd
#   <character> <numeric> <integer> <character>
# Z           a  0.286446        NA          NA
# A           b  0.965458        NA          NA
# B           c  0.498872         6           z
# C           d  0.523173         5           y
# D           e  0.737400         4           x
# G          NA        NA         1           u
# F          NA        NA         2           v
# E          NA        NA         3           w

However, this is not a left join because it keeps all the rows.

If we had a left join based on the row names, then you could do:

rownames(maaslin3_res) <- maaslin3_res$feature
rowData(tse) <- leftJoin(rowData(tse), maaslin3_abund)

which is already significantly simpler than your original code. It also remains quite clear about what the code is doing.

IMO something like addToRowData(tse, maaslin3_res) lacks readability because there are many ways to "add" data. An important question here is how the new data gets combined/merged to the existing data. In other words, addToRowData(tse, maaslin3_res) maybe is trying to pack a little bit too much.

So perhaps we could start with providing a left join operation based on the row names? Then we can decide if that's good enough or not?

[RiboRings]

Thanks for sharing your suggestion!

That all sounds pretty fair to me. If possible, I would also provide a suffix argument to keep colnames unique, similar to the dplyr joining functions:

left_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = NULL
)

This would help, for instance, when combining results from different differential abundance methods with sometimes identical colnames.