This function adds metadata variables from a given data frame to an object, aligning the data with existing molecular variables.

addMetaDataMol(
  object,
  meta_var_df,
  var_names = NULL,
  assay_name = activeAssay(object),
  na_warn = TRUE,
  overwrite = FALSE
)

Arguments

object

An object of class SPATA2 or, in case of S4 generics, objects of classes for which a method has been defined.

meta_var_df

A data frame containing new metadata variables to be added. This data frame must contain a column named molecule which is used as the key for merging. Other columns should represent the metadata variables to be added.

var_names

A character vector specifying which columns from meta_var_df should be added as metadata variables. If NULL, all columns except molecule and <assay_name> will be added. Default is NULL.

assay_name

Only relevant if the SPATA2 object contains more than one assay: Denotes the assay of interest and thus the molecular modality to use. Defaults to the active assay as set by activateAssay().

na_warn

Logical value indicating whether to issue warnings if NAs are introduced in the new metadata variables. Default is TRUE.

overwrite

Logical value. Must be TRUE to allow overwriting.

Value

The updated input object, containing the added, removed or computed results.

Details

The input meta_var_df must satisfy the following requirements:

  • It must be a data frame.

  • It must contain a column named molecule, which will be used as the key for merging the metadata variables with the existing molecular observations.

  • Any other columns can represent the metadata variables to be added. These columns must not be named "molecule" or the value of assay_name.

  • The columns specified in var_names must be present in meta_var_df.

The function checks for the existence of the specified metadata variables in the object. If overwrite is FALSE, it ensures that no existing variables are overwritten. If NAs are introduced in the new metadata variables, warnings will be issued if na_warn is TRUE.