---
title: "Fuzzy Matching"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Fuzzy Matching}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(fedmatch)
library(data.table)
```

# Intro

Fuzzy matching is an essential part of the matching process. After trying all the name cleaning that you can with `clean_strings`, you have gotten the 'low hanging fruit' of your match, and now you need to move on to non-exact matches. `merge_plus` has a built-in setting for this called 'fuzzy' matching. It lets you match on strings that are similar, but not exactly the same.

# Fuzzy matching theory

The basic idea behind fuzzy matching is to compute a numerical 'distance' between every potential string comparison, and then for each string in data set 1, pick the 'closest' string in data set 2. One can also specify a threshold such that every match is of a certain quality. The concept of 'distance' can be defined in several methods, explained below. Each method will define a similarity $s$, $0 \leq s \leq 1$ , such that higher values will mean the strings are more similar, and a corresponding distance $d = 1 - s$.

## Jaro-Winkler

The most common method of matching strings with `fedmatch` uses the Jaro-Winkler string distance. The Jaro similarity is defined as

$$s_j = \begin{cases} 0 &  \text{if } m = 0 \\ \frac{1}{3} \left(\frac{m}{|s_1|} + \frac{m}{|s_2|} + \frac{m - t}{m} \right) & \text{otherwise} \end{cases}$$

where $|s_i|$ is the length of the $i$th string, $m$ is the number of characters that match, and $t$ is the number of transpositions (the number of letters to be interchanged to place them in the proper order.) For example, if $s_1$ is "abcd" and $s_2$ is "acbd", then the number of transpositions is 1, the matching characters are 4, and the similarity is $\frac{1}{3}\left( 1 + 1 + \frac{3}{4} \right) \approx .917$.

Winkler's modification to this similarity is to weight the start of the strings more heavily. Thus, if the strings share a common prefix, the similarity will be higher. The Jaro-Winkler similarity is

$$s_w = s_j + l p (1-s_j),$$

where $l$ is the shared prefix length (up to four characters, so $0 \leq l \leq 4$ ), and $p$ is just user-defined constant, $0 < p \leq .25$, that defines how heavily to weight the shared prefix. $p=.1$ is the default used by `fedmatch`.

## Weighted Jaccard Similarity

Another string distance metric is called the Jaccard Similarity. If $A$ is the set of letters in one string, and $B$ is the set of letters in another string, then the Jaccard similarity $J$ is defined as

$$J = \frac{A \bigcap B}{A \bigcup B}.$$

Thus, if the two strings share all of the same letters, then the distance is 0, or the similarity is 1.

We take one step further and innovate to create a new measure of string distance, which we call the *Weighted Jaccard* distance. Rather than looking at the sets of letters in each string, we look at the set of words in each string. Then, we construct a corpus of all of the words in the two columns to be matched and compute the log inverse frequency for each word:

$$w_i = \log \left( \frac{N}{n_i} \right), $$
where $N$ is the total number of unique words in the sample, and $n_i$ is the number of occurrences of word $i$ in the sample.

For example, the word 'Corporation' appears frequently in the names of companies in common data sets, and so its log inverse frequency would be low. But, the word 'Apple' probably only appears in a few company names out of the many thousands in the data, so its log inverse frequency score would be high.

 If these logged inverse frequencies are called $w$, then the Weighted Jaccard similarity is computed as

$$ J_i = \frac{ \sum_j w_j,  j \in A \bigcap B}{ \sum_k w_k, k \in A \bigcup B} $$ 

Thus, if the two strings share many words that are uniquely identifying in the corpus, the Weighted Jaccard similarity will be higher. We have found this method of matching is able to pick up many more matches when used in conjunction with the Jaro-Winkler distance. To our knowledge, such a Weighted Jaccard method has never been used before, and is one of the key innovations that makes `fedmatch` unique.\

## Other similarity metrics

Because fedmatch uses `stringdist::amatch` for all other options, one can use any of the similarity metrics listed in the documentation for that function in fedmatch.

# Using fuzzy matching in fedmatch

## Basic Syntax

As shown in the 'Intro to fedmatch' vignette, the basic syntax of using fuzzy match is just the same as exact matching, but changing the 'match_type' argument in `merge_plus`:

```{r}
fuzzy_result <- merge_plus(data1 = corp_data1, 
                          data2 = corp_data2,
                          by.x = "Company",
                          by.y = "Name", match_type = "fuzzy", 
                          unique_key_1 = "unique_key_1",
                          unique_key_2 = "unique_key_2")
print(fuzzy_result$matches)
```

Note that 'Bershire Hathaway' matched to 'Bershire Hataway,' which makes sense - the names are only off by one character. All of the settings of fuzzy matching are controlled in the 'fuzzy_settings' argument of `merge_plus`, and these settings can be easily modified with the function `build_fuzzy_settings`. `build_fuzzy_settings` returns a list that is properly formatted for `merge_plus`.The options and their defaults are: 

- `method` , default "jw", determines the string distance metric to use.
- `p` , default 0.1, is a numeric vector of length 1, that determines the factor $p$ in the Jaro-Winkler string distance. Only used if `method == "jw"`.
- maxDist, default 0.05, is a numeric vector of length 1 that determines the maximum allowable string distance that qualifies as a match.
- matchNA, default `FALSE`, is a boolean to determine whether to count NAs as a match (see `stringdist::amatch` for details.)
- nthread, number of threads to use in the underlying C code. If using any method besides "wgt_jaccard", uses `stringdist::amatch' to parallelize. If using "wgt_jaccard", instead uses built in C++ code to parallelize.

## The order of which is data1 and which is data2 matters!

The behavior of `fuzzy_match` is such that you can get different results from swapping data1 and data2. This is because `fuzzy_match` answers the question: "for each observation in data1, which observation is closest in data2 (while being closest than the maxDist)?" This can result in duplicate observations from data2, as shown in the simple example below:
```{r}
dummy_data1 <- data.table(id1 = 1:2,
                            name = "abd")
dummy_data2 <- data.table(id2 = 1,
                            name = "abc")
result1 <- fedmatch::merge_plus(
    data1 = dummy_data1,
    match_type = "fuzzy",
    data2 = dummy_data2, by.x = "name", by.y = "name",
    unique_key_1 = "id1", unique_key_2 = "id2",
    suffixes = c("_1", "_2"), fuzzy_settings = build_fuzzy_settings(maxDist = .5))
print(result1$matches)
```

Note how we have two observations of the id2 '1', because each of these observations is the closest in the data to the observations in data1 (and they are closer together than the maxDist specified). Now, if we flip the datasets:

```{r}
result1 <- fedmatch::merge_plus(
    data1 = dummy_data2,
    match_type = "fuzzy",
    data2 = dummy_data1, by.x = "name", by.y = "name",
    unique_key_1 = "id2", unique_key_2 = "id1",
    suffixes = c("_1", "_2"), fuzzy_settings = build_fuzzy_settings(maxDist = .5))
print(result1$matches)
```

We only get 1 observation, because in the case of ties, `fuzzy_match` will simply pick the first observation. 

## An example - weighted Jaccard match

### Weighted Jaccard Match
```{r}
wgt_jaccard_match <- merge_plus(data1 = corp_data1, 
                          data2 = corp_data2,
                          by.x = "Company",
                          by.y = "Name", match_type = "fuzzy", 
                          fuzzy_settings = build_fuzzy_settings(method = "wgt_jaccard", nthread = 2,
                                                                maxDist = .5),
                          unique_key_1 = "unique_key_1",
                          unique_key_2 = "unique_key_2")
print(wgt_jaccard_match)
```

