This function makes it easy to add additional file info (iso_get_file_info) to isofile objects and data frames by a single left_join or multiple sequential left_join operations. The function provides a detailed summary of the information that was added unless quiet = TRUE. Note that one-to-many joins are not permitted (and will fail with an informative error) since this would lead to likely unintended data duplication in the isofiles. However, one-to-one and many-to-one joins are fully supported and should cover all needed use cases for this function. Also note that for each join, only the new_file_info rows that have defined non-NA, non-empty ("") values in all join_by columns will be considered for the join and that only new_file_info columns that do NOT already exist in ANY file information will be added. For changing the values of existing file information, please use iso_mutate_file_info instead.

# S3 method for iso_file_list
iso_add_file_info(iso_files, new_file_info, ..., quiet = default(quiet))

# S3 method for data.frame
iso_add_file_info(df, new_file_info, ..., quiet = default(quiet))

iso_add_file_info(...)

Arguments

iso_files

collection of iso_file objects

new_file_info

data frame with new file information to add to the isofiles

...

each parameter specifies a set of join_by column(s) to add the new_file_info to the existing file information. The provided parameters are applied sequentially. At least one must be specified.

quiet

whether to display (quiet=FALSE) or silence (quiet = TRUE) information messages. Set parameter to overwrite global defaults for this function or set global defaults with calls to iso_turn_info_messages_on and iso_turn_info_messages_off

df

a data frame of iso files data retrieved by any of the data retrieval functions (e.g. iso_get_file_info, iso_get_raw_data, etc.

Value

the original iso files or data frame with the new file info added in.

Details

Single left_join: this is the most common use of this function and basically a simple left join operation (with some additional safety checks). Specify a single join_by in the ..., such as e.g. c("file_id") to add additional file information joining by the file_id column.

Multiple sequential left_join: this use case is for applying a set of increasingly more specific join_by rules. For example, ... = c("Identifier 1", "Identifier 2"), c("file_id") would serve to first add one set of new file information for all isofiles based on their Identifier 1 and Identifier 2 columns and then overwrite the new information with more specific details for a subset of isofiles based on their file_id column, all based on a single overview new_file_info data frame. Basically, each set of join_by conditions specified in ... must describe a valid left_join join_by parameter to merge the new_file_info with the existing file info. Each set of new_file_info data can overwrite the previous join_by matches such that the last set of join_by column(s) provided in ... will overwrite all previous matches for which it applies, even if they have already been a match for a previous column.