---
title: "Overview of the phonics Package"
author: "James P. Howard, II"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Overview of the phonics Package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

The ``phonics`` package for R is designed to provide a variety of
phonetic indexing algorithms in common and not-so-common use today.  The
algorithms generally reduce a string to a symbolic representation
approximating the sound made by pronouncing the string.  They can be
used to match names, words, and as a proxy for assorted string distance
algorithms.

# Basic Usage 

Every encoder accepts a character vector and returns one code per input.
Match Rating Approach (MRA) additionally has a comparison stage. For example,
`soundex()` and `refinedSoundex()` encode a vector directly.

```{r basic-examples}
library("phonics")

x1 <- "Catherine"
x2 <- "Kathryn"
x3 <- "Katrina"
x4 <- "William"

x <- c(x1, x2, x3, x4)

soundex(x1)
soundex(x2)
soundex(x)

refinedSoundex(x1)
refinedSoundex(x2)
```

Both functions accept a `maxCodeLen` that limits the length of the returned
code. All encoders except `mra_encode()` expose this bound. Cologne preserves
its historical unbounded output by default (`maxCodeLen = NULL`); an explicit
bound truncates it like the other encoders.

Beyond soundex, additional algorithms are available, as shown in the
following table.

| Algorithm                                             | Function Name |
|:------------------------------------------------------|:--------------|
| Caverphone 1 and 2                                    | `caverphone()` |
| Cologne Phonetic                                      | `cologne()` |
| Lein Name Coding                                      | `lein()` |
| Match Rating Approach                                 | `mra_encode()`, `mra_compare()` |
| Metaphone                                             | `metaphone()` |
| Original and USDA Modified NYSIIS                     | `nysiis()` |
| Oxford Name Compression Algorithm                     | `onca()` |
| Phonex                                                | `phonex()` |
| Roger Root Name Coding Procedure                      | `rogerroot()` |
| Soundex and Apache Refined Soundex                    | `soundex()`, `refinedSoundex()` |
| Census Modified Statistics Canada                     | `statcan()` |

## Input and output contracts

Input is converted to a common case before encoding. With the default
`clean = TRUE`, an input containing characters outside an encoder's supported
alphabet produces a warning and an `NA` result. With `clean = FALSE`, those
characters are discarded before encoding. `NA` values remain `NA`, empty
strings remain empty, and vector order is preserved.

The encoders implement different published normalization domains. In
particular, Cologne accepts German umlauts and eszett, Phonex accepts their
German equivalents, and Census Modified Statistics Canada normalizes its
documented French letters.
 
# Match Rating Approach

Unlike other algorithms described here, MRA is a two-stage algorithm
with separate encoding and comparison routines.  For instance, the
results of Soundex on two different strings can be directly compared to
test for equality:

```{r soundex-test-example}
soundex(x1) == soundex(x2)
soundex(x2) == soundex(x3)
```

However, the MRA encoding algorithm may return different encodings for
similar strings that should match.  So the second stage, for comparison,
is used to compare to MRA-encoded strings. The encoding algorithm is
provided by `mra_encode` and the comparison algorithm is provided by
`mra_compare`.

```{r mra-example}
(mra1 = mra_encode("Katherine"))
(mra2 = mra_encode("Catherine"))
(mra3 = mra_encode("Katarina"))

mra_compare(mra1, mra2)
mra_compare(mra1, mra3)
mra_compare(mra2, mra3)
```

The required similarity threshold gets smaller as the combined encoded length
increases. The comparison removes aligned characters from left to right and
then right to left, and scores the unmatched characters in the longer
remainder.

# Summary

This vignette has outlined the `phonics` package for R. Included in this
package are several English-, German-, and French-language suitable
algorithms for phonetically reducing names and strings.  These can be
used for comparison and indexing, as well as later record linkage.