multimatch: Match rows of one dataframe to another using multiple columns

In mvbutils: General utilities, workspace organization, code and doc editing, live package maintenance, etc

Match rows of one dataframe to another using multiple columns

Description

Like match, but for more than one variable at a time— and geared specifically to dataframes (or matrices). NA values match only to NAs.

So useful that I've finally moved it from secret package handy2 into package mvbutils, and added documentation.

Any factor fields (which I hardly ever use; characters are just Better) will be matched based on the strings they display as, so that (eg) arbitrary re-orderings levels won't matter.

Usage

multimatch(df1, df2, nomatch = NA, char.force = FALSE, force.same.cols = TRUE)

Arguments

df1, df2	two dataframes. Unless you set force.same.cols=FALSE, column-order is assumed to be the same in both, and a mismatched number of columns will trigger an error.
nomatch	like in match
char.force	?convert all columns to character before checking? Usually doesn't matter; if it does, TRUE is probably the safer, but historically the default is FALSE
force.same.cols	Perhaps a misleading name... set to FALSE if you want multimatch to use only columns whose name exists in both dataframes, and to re-order columns if necessary so that the names match. Usually the non-default FALSE is better!

Details

multimatch works by constructing a single numeric composite for each row in df1 and df2, based on multiplying numbers of distinct values across columns. This could potentially overflow, or give inaccurate results, if the number of columns and distinct values is very large. So, don't use multimatch in that situation...

Value

A numeric vector, one element per row in df1, showing which row in df2 it matches to, or nomatch if none do.

See Also

match

Examples

xx <- data.frame(
    animal= cq( cat, dog, cat), colour= cq( blue, blue, pink), size= 1:3,
    royalty= cq( high, low, high))
yy <- data.frame(
    animal= cq( dog, dog, cat), colour= cq( red, blue, pink), size= 1:3,
    loyalty=cq( high, high, low)) # note the spelling!
multimatch( xx, yy)
# NA NA NA
multimatch( xx[,1:3], yy[,1:3])  # ignore 4th col
# NA 2 3
multimatch( xx, yy, force=FALSE) # auto-drop loyalty & royalty (different names)
# NA 2 3
try( multimatch( xx[,1:2], yy[,1:3]))
# <error>: num of cols
try( multimatch( xx[,1:2], yy[,1:3], force=FALSE))
# all good
multimatch( as.matrix( xx[,1:3]), as.matrix( yy[,1:3])) # matrices OK too
# NA 2 3

mvbutils documentation built on May 25, 2026, 5:09 p.m.