### Approximate String Matching Examples

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Demonstration of afind, grabl, and extract functions using text vectors.

```R
texts = c("When I grow up, I want to be"
       , "one of the harvesters of the sea"
       , "I think before my days are gone"
       , "I want to be a fisherman")
patterns = c("fish", "gone","to be")

afind(texts, patterns, method="running_cosine", q=3)

grabl(texts,"grew", maxDist=1)
extract(texts, "harvested", maxDist=3)
```

--------------------------------

### Perform Approximate String Matching

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Examples demonstrating how to find the nearest matches in a lookup table using amatch and ain with various distance constraints.

```R
# lets see which sci-fi heroes are stringdistantly nearest
amatch("leia",c("uhura","leela"),maxDist=5)

# we can restrict the search
amatch("leia",c("uhura","leela"),maxDist=1)

# we can match each value in the find vector against values in the lookup table:
amatch(c("leia","uhura"),c("ripley","leela","scully","trinity"),maxDist=2)

# setting nomatch returns a different value when no match is found
amatch("leia",c("uhura","leela"),maxDist=1,nomatch=0)

# this is always true if maxDist is Inf
ain("leia",c("uhura","leela"),maxDist=Inf)

# Let's look in a neighbourhood of maximum 2 typo's (by default, the OSA algorithm is used)
ain("leia",c("uhura","leela"), maxDist=2)
```

--------------------------------

### Calculate String Similarity (Default Method)

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Calculates string similarity using the default optimal string alignment method. Ensure the stringdist package is installed and loaded.

```r
# Calculate the similarity using the default method of optimal string alignment
stringsim("ca", "abc")
```

--------------------------------

### Calculate String Distances with stringdist

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Compute string distances between character vectors. The example shows distances between 'g\'day\' and other strings.

```R
stringdist(c("g'day"),c("hi","hallo","ola"))
```

--------------------------------

### POST /phonetic

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Translates strings to phonetic codes where similar sounding strings get similar or equal codes.

```APIDOC
## POST /phonetic

### Description
Translates strings to phonetic codes. Similar sounding strings should get similar or equal codes.

### Method
POST

### Endpoint
/phonetic

### Parameters
#### Request Body
- **x** (character) - Required - A character vector whose elements are phonetically encoded.
- **method** (string) - Optional - Name of the algorithm used (default: "soundex").
- **useBytes** (boolean) - Optional - Perform byte-wise comparison.

### Response
#### Success Response (200)
- **codes** (string[]) - The resulting phonetic codes.
```

--------------------------------

### Get Q-gram Counts for Integer Sequences

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Use seq_qgrams to generate a matrix of q-gram profiles for integer sequences. Missing values are treated as any other number. This function is useful for comparing sequence overlap based on n-grams.

```R
seq_qgrams(x = 1:3, y=2:4,q=2)
```

```R
seq_qgrams(1:3,c(1,NA,2),NA_integer_)
```

--------------------------------

### Open stringdist C/C++ API Vignette

Source: https://cran.r-project.org/web/packages/stringdist/readme/README.html

Opens the vignette detailing the C/C++ API for the stringdist package. This is useful for developers looking to integrate stringdist functionality into other R packages.

```R
vignette("stringdist_C-Cpp_api", package="stringdist")
```

--------------------------------

### String Distance Metrics Overview

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

This section provides a detailed description of each supported string distance metric, including their mathematical definitions and specific use cases.

```APIDOC
## String Distance Metrics

This document outlines the various string distance metrics available in the stringdist package. These metrics are useful for comparing the similarity or dissimilarity between two strings.

### Hamming Distance

- **Description**: Counts the number of character substitutions required to transform one string into another. If strings have different lengths, the distance is infinite.
- **Method**: `method='hamming'`

### Levenshtein Distance

- **Description**: Calculates the minimum number of single-character edits (insertions, deletions, or substitutions) required to change one word into the other. Equivalent to R's native `adist` function.
- **Method**: `method='lv'`

### Optimal String Alignment (OSA) Distance

- **Description**: Similar to Levenshtein distance, but also allows for the transposition of two adjacent characters. Each substring can only be edited once.
- **Method**: `method='osa'`

### Full Damerau-Levenshtein Distance

- **Description**: An extension of the Optimal String Alignment distance that allows for multiple edits on substrings, including transpositions.
- **Method**: `method='dl'`

### Longest Common Substring (LCS) Distance

- **Description**: The distance is defined as the number of unpaired characters after finding the longest common substring. It's equivalent to an edit distance allowing only deletions and insertions with weight one.
- **Method**: `method='lcs'`

### Q-gram Distance

- **Description**: Computes the distance based on the counts of q-gram occurrences in strings. The distance is the sum of absolute differences of q-gram counts. Returns `Inf` if `q` is larger than the length of any string.
- **Method**: `method='qgram'`

### Cosine Distance

- **Description**: Calculated using the cosine similarity formula: `1 - (x . y) / (||x|| ||y||)`, where `x` and `y` are vectors of q-gram counts.
- **Method**: `method='cosine'`

### Jaccard Distance

- **Description**: Measures dissimilarity between sets of q-grams. Calculated as `1 - |X intersect Y| / |X union Y|`, where `X` and `Y` are sets of unique q-grams.
- **Method**: `method='jaccard'`

### Jaro Distance

- **Description**: A measure of similarity between two strings, ranging from 0 (exact match) to 1 (completely dissimilar). It considers matching characters and transpositions.
- **Method**: `method='jw'`, `p=0`

### Jaro-Winkler Distance

- **Description**: An extension of the Jaro distance that gives more favorable ratings to strings that match from the beginning for a set prefix length.
- **Method**: `method='jw'`, `0 < p <= 0.25`

### Soundex Distance

- **Description**: Compares strings based on their Soundex phonetic codes. The distance is 0 if codes match, otherwise 1. Only meaningful for a-z and A-Z characters.
- **Method**: `method='soundex'`

### Running Cosine Distance

- **Description**: An optimized implementation of cosine distance for fuzzy text search, particularly useful for sliding window comparisons.
- **Method**: `running_cosine`
```

--------------------------------

### Create a dist Object with stringdistmatrix

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Generate a 'dist' object containing pairwise string distances, suitable for use with clustering algorithms like hclust.

```R
stringdistmatrix(c("foo","bar","boo","baz"))
```

--------------------------------

### phonetic - Soundex Algorithm

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Implements the Soundex algorithm for phonetic matching. Note that it's primarily designed for English alphabet characters (a-z, A-Z). Non-printable or non-ASCII characters may lead to system-dependent results and warnings.

```APIDOC
## phonetic - Soundex Algorithm

### Description
Calculates phonetic codes for strings using the Soundex algorithm. Only the Soundex algorithm is currently implemented. Soundex coding is meaningful for characters in the ranges a-z and A-Z. Coding of strings with non-printable or non-ASCII characters may be system-dependent and should not be trusted. A warning is emitted if such characters are encountered.

### Value
Returns a character vector of the same length as the input vector, containing Soundex codes. Output characters are in the system's native encoding.

### References
The implemented Soundex algorithm is used by the National Archives, differing slightly from the original patent by R.C. Russell.

### See Also
`printable_ascii`

### Examples
```R
# The following examples are from The Art of Computer Programming (part III, p. 395)
# (Note that our algorithm is specified different from the one in TACP, see references.)
phonetic(c('Euler','Gauss','Hilbert','Knuth','Lloyd','Lukasiewicz','Wachs'),method='soundex')
```
```

--------------------------------

### Approximate String Matching Equivalents

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Definitions for amatch and ain functions, which serve as approximate equivalents to R's match and %in%.

```R
amatch(
  x,
  table,
  nomatch = NA_integer_,
  matchNA = TRUE,
  method = c("osa", "lv", "dl", "hamming", "lcs", "qgram", "cosine", "jaccard", "jw",
    "soundex"),
  useBytes = FALSE,
  weight = c(d = 1, i = 1, s = 1, t = 1),
  maxDist = 0.1,
  q = 1,
  p = 0,
  bt = 0,
  nthread = getOption("sd_num_thread")
)

ain(x, table, ...)
```

--------------------------------

### Function Signatures for Approximate String Matching

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Definitions for afind, grab, grabl, and extract functions.

```R
afind(
  x,
  pattern,
  window = NULL,
  value = TRUE,
  method = c("osa", "lv", "dl", "hamming", "lcs", "qgram", "cosine", "running_cosine",
    "jaccard", "jw", "soundex"),
  useBytes = FALSE,
  weight = c(d = 1, i = 1, s = 1, t = 1),
  q = 1,
  p = 0,
  bt = 0,
  nthread = getOption("sd_num_thread")
)

grab(x, pattern, maxDist = Inf, value = FALSE, ...)

grabl(x, pattern, maxDist = Inf, ...)

extract(x, pattern, maxDist = Inf, ...)
```

--------------------------------

### seq_qgrams

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Generates a table of q-gram counts for integer sequences.

```APIDOC
## seq_qgrams

### Description
Get a table of q-gram counts for integer sequences.

### Usage
```R
seq_qgrams(..., .list = NULL, q = 1L)
```

### Arguments
- **...** (any) - Any number of (named) arguments that will be coerced with `as.integer`.
- **.list** (list) - Will be concatenated with the `...` argument(s). Useful for adding integer vectors named 'q'.
- **q** (integer) - The size of q-gramming.

### Value
A `matrix` containing q-gram profiles. Columns 1 to `q` contain the encountered q-grams. The ensuing (named) columns contain the q-gram counts per vector. Missing values in integer sequences are treated as any other number.

### See Also
`seq_dist`, `seq_amatch`

### Examples
```R
# compare the 2-gram overlap between sequences 1:3 and 2:4
seq_qgrams(x = 1:3, y=2:4,q=2)

# behavior when NA's are present.
seq_qgrams(1:3,c(1,NA,2),NA_integer_)
```
```

--------------------------------

### seq_amatch and seq_ain - Approximate Matching for Integer Sequences

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Functions for finding approximate matches between sequences of integers or numeric vectors. Supports various distance methods and customizable matching parameters.

```APIDOC
## seq_amatch and seq_ain - Approximate Matching for Integer Sequences

### Description
For a `list` of integer vectors `x`, find the closest matches in a `list` of integer or numeric vectors in `table.`

### Usage
```R
seq_amatch(
  x,
  table,
  nomatch = NA_integer_,
  matchNA = TRUE,
  method = c("osa", "lv", "dl", "hamming", "lcs", "qgram", "cosine", "jaccard", "jw"),
  weight = c(d = 1, i = 1, s = 1, t = 1),
  maxDist = 0.1,
  q = 1,
  p = 0,
  bt = 0,
  nthread = getOption("sd_num_thread")
)

seq_ain(x, table, ...)
```
```

--------------------------------

### Approximate String Matching Equivalents

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Functions that provide approximate string matching equivalents of R's native `match` and `%in%`.

```APIDOC
## amatch

### Description
Approximate string matching equivalents of R's native `match`. Finds the closest match for each element of `x` in `table` based on a specified distance metric.

### Method
`amatch`

### Endpoint
N/A (R function)

### Parameters
#### Arguments
- **x** (character vector) - strings to search in
- **table** (character vector) - strings to match against
- **nomatch** (numeric, optional) - Value to return when no match is found. Defaults to NA_integer_.
- **matchNA** (logical, optional) - If TRUE, NA values in `x` will match NA in `table`. Defaults to TRUE.
- **method** (character, optional) - Matching algorithm to use. See `stringdist-metrics`. Defaults to 'osa'.
- **useBytes** (logical, optional) - Perform byte-wise comparison. See `stringdist-encoding`. Defaults to FALSE.
- **weight** (numeric, optional) - Penalty weights for deletion, insertion, substitution, and transposition for 'osa', 'dl', or 'jw' methods. Ignored for other methods.
- **maxDist** (numeric, optional) - Maximum allowed distance for a match. Defaults to 0.1.
- **q** (integer, optional) - q-gram size, only when method is 'qgram', 'jaccard', or 'cosine'. Defaults to 1.
- **p** (numeric, optional) - Winkler's prefix parameter for Jaro-Winkler distance, with 0 <= p <= 0.25. Only when method is 'jw'. Defaults to 0.
- **bt** (numeric, optional) - Winkler's boost threshold. Applies only to method='jw' and p>0. Defaults to 0.
- **nthread** (integer, optional) - Number of threads used by the underlying C-code. Defaults to option("sd_num_thread").

### Value
An integer vector indicating the index of the closest match in `table` for each element of `x`.

## ain

### Description
Approximate string matching equivalent of R's `%in%`. Checks if elements of `x` are approximately present in `table`.

### Method
`ain`

### Endpoint
N/A (R function)

### Parameters
#### Arguments
- **x** (character vector) - strings to search in
- **table** (character vector) - strings to match against
- **...** - Passed to `amatch`.

### Value
A logical vector indicating whether each element of `x` is approximately found in `table`.

```

--------------------------------

### qgrams - Q-gram Counts

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Generates a table of q-gram counts from character vectors. Supports byte-wise q-grams and options for naming columns.

```APIDOC
## qgrams - Q-gram Counts

### Description
Get a table of qgram counts from one or more character vectors.

### Usage
```R
qgrams(..., .list = NULL, q = 1L, useBytes = FALSE, useNames = !useBytes)
```

### Arguments
`...` | any number of (named) arguments, that will be coerced to character with `as.character`.
`.list` | Will be concatenated with the `...` argument(s). Useful for adding character vectors named `'q'` or `'useNames'`.
`q` | size of q-gram, must be non-negative.
`useBytes` | Determine byte-wise qgrams. `useBytes=TRUE` is faster but may yield different results depending on character encoding. For `ASCII` it is identical. See also `stringdist` under Encoding issues.
`useNames` | Add q-grams as column names. If `useBytes=useNames=TRUE`, the q-byte sequences are represented as 2 hexadecimal numbers per byte, separated by a vertical bar (`|`).

### Value
A table with `qqq`-gram counts. Detected `qqq`-grams are column names and the argument names as row names. If no argument names were provided, they will be generated.

### Details
The input is converted to `character`. If `useBytes=TRUE`, each element is converted to `utf8` and then to `integer` as in `stringdist`. Next,the data is passed to the underlying routine. Strings with less than `q` characters and elements containing `NA` are skipped. Using `q=0` therefore counts the number of empty strings `""` occuring in each argument.

### See Also
`stringdist`, `amatch`

### Examples
```R
qgrams('hello world',q=3)

# q-grams are counted uniquely over a character vector
qgrams(rep('hello world',2),q=3)

# to count them separately, do something like
x <- c('hello', 'world')
lapply(x,qgrams, q=3)

# output rows may be named, and you can pass any number of character vectors
x <- "I will not buy this record, it is scratched"
y <- "My hovercraft is full of eels"
z <- c("this", "is", "a", "dead","parrot")
qgrams(A = x, B = y, C = z,q=2)

# a tonque twister, showing the effects of useBytes and useNames
x <- "peter piper picked a peck of pickled peppers"
qgrams(x, q=2) 
qgrams(x, q=2, useNames=FALSE) 
qgrams(x, q=2, useBytes=TRUE)
qgrams(x, q=2, useBytes=TRUE, useNames=TRUE)
```
```

--------------------------------

### Calculate String Similarity (Jaro-Winkler Method)

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Calculates string similarity using the Jaro-Winkler method. The 'p' argument is passed directly to the stringdist function for fine-tuning the Jaro-Winkler calculation.

```r
# Calculate the similarity using the Jaro-Winkler method
# The p argument is passed on to stringdist
stringsim('MARTHA','MATHRA',method='jw', p=0.1)
```

--------------------------------

### Handle Missing Values in Sequence Comparison

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Demonstrates how missing values (NA_integer_) are handled in sequence similarity calculations. Missing values are treated as ordinary numbers during comparison.

```R
# note how missing values are handled (L2 is recycled over L1)
L1 <- list(c(1L,NA_integer_,3L),2:4,NA_integer_)
L2 <- list(1:3)
seq_sim(L1,L2)

```

--------------------------------

### Translate Strings to Phonetic Codes

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Usage syntax for the phonetic function to translate strings into phonetic codes.

```R
phonetic(x, method = c("soundex"), useBytes = FALSE)
```

--------------------------------

### Approximate String Matching Functions

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Functions for finding approximate matches of patterns within strings, including options for different distance metrics and return values.

```APIDOC
## afind

### Description
Finds approximate matches of patterns within a character vector using various string distance metrics.

### Method
`afind`

### Endpoint
N/A (R function)

### Parameters
#### Arguments
- **x** (character vector) - strings to search in
- **pattern** (character vector) - strings to find (not a regular expression)
- **window** (numeric, optional) - width of moving window
- **value** (logical, optional) - toggle return matrix with matched strings. Defaults to TRUE.
- **method** (character, optional) - Matching algorithm to use. See `stringdist-metrics`. Defaults to 'osa'.
- **useBytes** (logical, optional) - Perform byte-wise comparison. See `stringdist-encoding`. Defaults to FALSE.
- **weight** (numeric, optional) - Penalty weights for deletion, insertion, substitution, and transposition for 'osa', 'dl', or 'jw' methods. Ignored for other methods.
- **q** (integer, optional) - q-gram size, only when method is 'qgram', 'jaccard', or 'cosine'. Defaults to 1.
- **p** (numeric, optional) - Winkler's prefix parameter for Jaro-Winkler distance, with 0 <= p <= 0.25. Only when method is 'jw'. Defaults to 0.
- **bt** (numeric, optional) - Winkler's boost threshold. Applies only to method='jw' and p>0. Defaults to 0.
- **nthread** (integer, optional) - Number of threads used by the underlying C-code. Defaults to option("sd_num_thread").

### Details
Matching is case-sensitive. Both `x` and `pattern` are converted to `UTF-8` prior to search, unless `useBytes=TRUE`. Code is parallelized over the `x` variable.

### Value
A list of three matrices (location, distance, match) with `length(x)` rows and `length(pattern)` columns.

### Request Example
```R
texts = c("When I grow up, I want to be", "one of the harvesters of the sea", "I think before my days are gone", "I want to be a fisherman")
patterns = c("fish", "gone","to be")
afind(texts, patterns, method="running_cosine", q=3)
```

## grab

### Description
Approximate string matching function that resembles base R's `grep`. Returns indices of elements in `x` that match `pattern` within `maxDist`.

### Method
`grab`

### Endpoint
N/A (R function)

### Parameters
#### Arguments
- **x** (character vector) - strings to search in
- **pattern** (character string) - string to find (not a regular expression). Must be a single string.
- **maxDist** (numeric, optional) - Only windows with distance <= maxDist are considered a match. Defaults to Inf.
- **value** (logical, optional) - If TRUE, returns the matched values instead of indices. Defaults to FALSE.
- **...** - Passed to `afind`.

### Value
An integer vector indicating in which elements of `x` a match was found with a distance <= maxDist. If `value=TRUE`, returns the matched values.

### Request Example
```R
texts = c("When I grow up, I want to be", "one of the harvesters of the sea", "I think before my days are gone", "I want to be a fisherman")
grabl(texts,"grew", maxDist=1)
```

## grabl

### Description
Approximate string matching function that resembles base R's `grepl`. Returns a logical vector indicating which elements of `x` match `pattern` within `maxDist`.

### Method
`grabl`

### Endpoint
N/A (R function)

### Parameters
#### Arguments
- **x** (character vector) - strings to search in
- **pattern** (character string) - string to find (not a regular expression). Must be a single string.
- **maxDist** (numeric, optional) - Only windows with distance <= maxDist are considered a match. Defaults to Inf.
- **...** - Passed to `afind`.

### Value
A logical vector indicating in which elements of `x` a match was found with a distance <= maxDist.

### Request Example
```R
texts = c("When I grow up, I want to be", "one of the harvesters of the sea", "I think before my days are gone", "I want to be a fisherman")
grabl(texts,"grew", maxDist=1)
```

## extract

### Description
Extracts approximate matches of a pattern from strings. Returns a character matrix containing the best matching window for each element of `x` and `pattern`.

### Method
`extract`

### Endpoint
N/A (R function)

### Parameters
#### Arguments
- **x** (character vector) - strings to search in
- **pattern** (character string) - string to find (not a regular expression). Must be a single string.
- **maxDist** (numeric, optional) - Only windows with distance <= maxDist are considered a match. Defaults to Inf.
- **...** - Passed to `afind`.

### Value
A character matrix with `length(x)` rows and `length(pattern)` columns. If a match is found, the element contains the match; otherwise, it is set to `NA`.

### Request Example
```R
texts = c("When I grow up, I want to be", "one of the harvesters of the sea", "I think before my days are gone", "I want to be a fisherman")
extract(texts, "harvested", maxDist=3)
```

### Running cosine distance
This algorithm gains efficiency by using that two consecutive windows have a large overlap in their q-gram profiles. It gives the same result as the `
```

--------------------------------

### POST /ain

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Checks if an element of x approximately matches an element in table.

```APIDOC
## POST /ain

### Description
Returns a logical vector indicating whether an element of x approximately matches an element in table. Defined as amatch(x, table, nomatch=0, ...) > 0.

### Method
POST

### Endpoint
/ain

### Parameters
#### Request Body
- **x** (character/list) - Required - Elements to be checked.
- **table** (character/list) - Required - Lookup table for matching.
- **...** (any) - Optional - Parameters to pass to amatch.

### Response
#### Success Response (200)
- **matches** (boolean[]) - A logical vector indicating match status.
```

--------------------------------

### Approximate Matching of Integer Sequences

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Use seq_amatch to find the closest match of integer sequences in a lookup table. Input vectors are converted to integers, truncating numeric values. NA values are handled according to base::match behavior by default.

```R
x <- list(1:3,c(3:1),c(1L,3L,4L))
table <- list(
  c(5L,3L,1L,2L)
  ,1:4
)
seq_amatch(x,table,maxDist=2)
```

```R
# behaviour with missings
seq_amatch(list(c(1L,NA_integer_,3L),NA_integer_), list(1:3),maxDist=1)
```

```R
# Match sentences based on word order. Note: words must match exactly or they
# are treated as completely different.
#
# For this example you need to have the 'hashr' package installed.
x <- "Mary had a little lamb"
x.words <- strsplit(x,"[[:blank:]]+")
x.int <- hashr::hash(x.words)
table <- c("a little lamb had Mary",
           "had Mary a little lamb")
table.int <- hashr::hash(strsplit(table,"[[:blank:]]+"))
seq_amatch(x.int,table.int,maxDist=3)
```

--------------------------------

### Phonetic Encoding with Soundex

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Applies the Soundex phonetic algorithm to a character vector. Only meaningful for a-z and A-Z characters; non-ASCII or non-printable characters may produce system-dependent results and warnings.

```R
phonetic(c('Euler','Gauss','Hilbert','Knuth','Lloyd','Lukasiewicz','Wachs'),method='soundex')
```

--------------------------------

### Approximate String Matching with amatch

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Use amatch to find the closest match for strings within a specified maximum distance. Returns NA if no match is found within the threshold.

```R
amatch(c("hello","g'day"),c("hi","hallo","ola"),maxDist=2)
```

--------------------------------

### Compute Distances Between Integer Sequences with seq_dist

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Calculate distances between sequences represented as integer vectors stored in a list. The shorter first argument is recycled.

```R
seq_dist( list(c(1L,1L,2L)), list(c(1L,2L,1L),c(2L,3L,1L,2L)) )
```

--------------------------------

### Compute String Distance Matrix

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Computes a matrix of pairwise string distances. Can return a 'dist' object if only one argument is provided, or a matrix if two are provided. Supports various distance methods.

```R
# computing a 'dist' object
d <- stringdistmatrix(c('foo','bar','boo','baz'))
# try plot(hclust(d))

```

```R
# The following gives a matrix
stringdistmatrix(c("foo","bar","boo"),c("baz","buz"))

```

```R
# stringdistmatrix gives the distance matrix (by default for optimal string alignment):
stringdist(c('a','b','c'),c('a','c'))

```

--------------------------------

### Compute Distance Metrics

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Functions to compute pairwise distances or distance matrices between integer sequences.

```APIDOC
## seq_dist / seq_distmatrix

### Description
seq_dist computes pairwise string distances between elements of a and b. seq_distmatrix computes the distance matrix with rows according to a and columns according to b.

### Parameters
#### Request Body
- **a** (list/integer/numeric) - Required - First set of sequences.
- **b** (list/integer/numeric) - Required - Second set of sequences.
- **method** (string) - Optional - Distance metric (osa, lv, dl, hamming, lcs, qgram, cosine, jaccard, jw).
- **weight** (numeric) - Optional - Penalty weights for operations.
- **q** (integer) - Optional - q-gram size.
- **p** (numeric) - Optional - Winkler's prefix parameter.
- **bt** (numeric) - Optional - Winkler's boost threshold.
- **useNames** (string) - Optional - Whether to use names in the output matrix.
- **nthread** (integer) - Optional - Number of threads for parallelization.
```

--------------------------------

### POST /amatch

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Finds the position of the closest match of elements in x within a lookup table based on string distance metrics.

```APIDOC
## POST /amatch

### Description
Returns the position of the closest match of x in table. When multiple matches with the same smallest distance metric exist, the first one is returned.

### Method
POST

### Endpoint
/amatch

### Parameters
#### Request Body
- **x** (character/list) - Required - Elements to be approximately matched.
- **table** (character/list) - Required - Lookup table for matching.
- **nomatch** (integer) - Optional - The value to be returned when no match is found.
- **matchNA** (boolean) - Optional - Should NA's be matched? Default is TRUE.
- **method** (string) - Optional - Matching algorithm to use.
- **useBytes** (boolean) - Optional - Perform byte-wise comparison.
- **weight** (numeric) - Optional - Penalty weights for deletion, insertion, substitution, and transposition.
- **maxDist** (numeric) - Optional - Maximum distance allowed for a match.
- **q** (integer) - Optional - q-gram size.
- **p** (numeric) - Optional - Winkler's prefix parameter.
- **bt** (numeric) - Optional - Winkler's boost threshold.
- **nthread** (integer) - Optional - Number of threads used by the underlying C-code.

### Response
#### Success Response (200)
- **position** (integer) - The index of the closest match in the table.
```

--------------------------------

### stringsimmatrix Function

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Calculates a similarity matrix for input strings.

```APIDOC
## stringsimmatrix

### Description
Works similarly to stringsim but returns a similarity matrix instead of a vector, equivalent to stringdistmatrix.

### Response
- **matrix** (matrix) - A matrix of similarity scores between 0 and 1.
```

--------------------------------

### Approximate Matching of Integer Sequences

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Functions for finding the closest match of sequences in a lookup table or checking for approximate inclusion.

```APIDOC
## seq_amatch / seq_ain

### Description
seq_amatch returns the position of the closest match of x in table. seq_ain returns a logical vector indicating whether an element of x approximately matches an element in table.

### Parameters
#### Request Body
- **x** (list/integer/numeric) - Required - Vector(s) to be approximately matched.
- **table** (list/integer/numeric) - Required - Lookup table for matching.
- **nomatch** (integer) - Optional - Value returned when no match is found.
- **matchNA** (logical) - Optional - Whether NA values should be matched.
- **method** (string) - Optional - Matching algorithm to use.
- **weight** (numeric) - Optional - Penalty weights for operations.
- **maxDist** (numeric) - Optional - Maximum distance for a match to be considered.
- **q** (integer) - Optional - q-gram size.
- **p** (numeric) - Optional - Winkler's prefix parameter.
- **bt** (numeric) - Optional - Winkler's boost threshold.
- **nthread** (integer) - Optional - Number of threads for parallelization.
```

--------------------------------

### seq_sim

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Computes similarity scores between sequences of integers using various methods.

```APIDOC
## seq_sim

### Description
Compute similarity scores between sequences of integers.

### Usage
```R
seq_sim(
  a,
  b,
  method = c("osa", "lv", "dl", "hamming", "lcs", "qgram", "cosine", "jaccard", "jw"),
  q = 1,
  ...
)
```

### Arguments
- **a** (list of integer vectors) - Target sequences.
- **b** (list of integer vectors) - Source sequences. Optional for `seq_distmatrix`.
- **method** (string) - Method for distance calculation. The default is "osa", see `stringdist-metrics`.
- **q** (integer) - Size of the q-gram; must be nonnegative. Only applies to `method='qgram'`, `'jaccard'` or `'cosine'`.
- **...** (any) - additional arguments are passed on to `seq_dist`.
```

--------------------------------

### Calculate Soundex distance

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Computes distance based on Soundex phonetic codes.

```R
stringdist('Euler','Gauss',method='soundex')
```

```R
stringdist('Euler','Ellery',method='soundex')
```

--------------------------------

### POST /stringdist

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Computes pairwise string distances between elements of two vectors, recycling the shorter vector.

```APIDOC
## POST /stringdist

### Description
Computes pairwise string distances between elements of 'a' and 'b'. The argument with fewer elements is recycled to match the length of the longer one.

### Method
POST

### Endpoint
/stringdist

### Parameters
#### Request Body
- **a** (array) - Required - Target strings to compare.
- **b** (array) - Required - Source strings to compare.
- **method** (string) - Optional - Distance calculation method (e.g., "osa", "lv", "dl", "hamming", "lcs", "qgram", "cosine", "jaccard", "jw", "soundex").
- **weight** (array) - Optional - Penalty weights for deletion, insertion, substitution, and transposition.
- **q** (number) - Optional - Size of the q-gram.
- **p** (number) - Optional - Prefix factor for Jaro-Winkler distance.
- **bt** (number) - Optional - Winkler's boost threshold.

### Response
#### Success Response (200)
- **distances** (array) - A numeric vector of string distances.
```

--------------------------------

### Count Q-gram Frequencies

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Generates a table of q-gram counts from character vectors. Can count byte-wise q-grams for speed, potentially affecting results based on encoding. Q-grams are counted uniquely over a vector unless processed individually.

```R
qgrams('hello world',q=3)
```

```R
# q-grams are counted uniquely over a character vector
qgrams(rep('hello world',2),q=3)
```

```R
# to count them separately, do something like
x <- c('hello', 'world')
lapply(x,qgrams, q=3)
```

```R
# output rows may be named, and you can pass any number of character vectors
x <- "I will not buy this record, it is scratched"
y <- "My hovercraft is full of eels"
z <- c("this", "is", "a", "dead","parrot")
qgrams(A = x, B = y, C = z,q=2)
```

```R
# a tonque twister, showing the effects of useBytes and useNames
x <- "peter piper picked a peck of pickled peppers"
qgrams(x, q=2)
```

```R
qgrams(x, q=2, useNames=FALSE)
```

```R
qgrams(x, q=2, useBytes=TRUE)
```

```R
qgrams(x, q=2, useBytes=TRUE, useNames=TRUE)
```

--------------------------------

### POST /stringdistmatrix

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Computes a string distance matrix between two vectors or a distance object for a single vector.

```APIDOC
## POST /stringdistmatrix

### Description
Computes the string distance matrix with rows according to 'a' and columns according to 'b'. If only 'a' is provided, returns a distance object.

### Method
POST

### Endpoint
/stringdistmatrix

### Parameters
#### Request Body
- **a** (array) - Required - Target strings.
- **b** (array) - Optional - Source strings.
- **method** (string) - Optional - Distance calculation method.
- **useNames** (string) - Optional - Whether to use input vectors as row/column names ("none", "strings", "names").

### Response
#### Success Response (200)
- **matrix** (array) - A matrix of string distances or a dist object.
```

--------------------------------

### Calculate q-gram distance

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Computes distance based on the difference between occurrences of q consecutive characters.

```R
stringdist('abc','cba',method='qgram',q=1)
```

```R
stringdist('abc','cba',method='qgram',q=2)
```

--------------------------------

### Compute Similarity Scores Between Integer Sequences

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

The seq_sim function computes similarity scores between lists of integer vectors using various methods. Additional arguments can be passed to seq_dist.

```R
seq_sim(
  a,
  b,
  method = c("osa", "lv", "dl", "hamming", "lcs", "qgram", "cosine", "jaccard", "jw"),
  q = 1,
  ...
)
```

--------------------------------

### Compute Pairwise String Distances

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

seq_dist computes pairwise string distances between elements of two vectors using specified methods and weights. seq_distmatrix computes the full distance matrix.

```R
seq_dist(
  a,
  b,
  method = c("osa", "lv", "dl", "hamming", "lcs", "qgram", "cosine", "jaccard", "jw"),
  weight = c(d = 1, i = 1, s = 1, t = 1),
  q = 1,
  p = 0,
  bt = 0,
  nthread = getOption("sd_num_thread")
)
```

```R
seq_distmatrix(
  a,
  b,
  method = c("osa", "lv", "dl", "hamming", "lcs", "qgram", "cosine", "jaccard", "jw"),
  weight = c(d = 1, i = 1, s = 1, t = 1),
  q = 1,
  p = 0,
  bt = 0,
  useNames = c("names", "none"),
  nthread = getOption("sd_num_thread")
)
```

--------------------------------

### stringsim Function

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Calculates the similarity between two strings or vectors of strings.

```APIDOC
## stringsim

### Description
Returns a vector of similarity scores between 0 and 1. 1 indicates perfect similarity (distance 0), while 0 indicates complete dissimilarity.

### Parameters
- **a** (string/vector) - Required - First string or vector of strings.
- **b** (string/vector) - Required - Second string or vector of strings.
- **method** (string) - Optional - The distance method used (e.g., 'jw' for Jaro-Winkler).
- **p** (numeric) - Optional - Scaling factor for Jaro-Winkler method.

### Request Example
stringsim('MARTHA', 'MATHRA', method='jw', p=0.1)

### Response
- **similarity** (numeric) - A value between 0 and 1.
```

--------------------------------

### seq_dist and seq_distmatrix

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Calculates pairwise distances between sequences of integers. seq_dist returns a numeric vector of distances, while seq_distmatrix returns a distance matrix.

```APIDOC
## seq_dist and seq_distmatrix

### Description
Calculates pairwise distances between sequences of integers. `seq_dist` returns a numeric vector of distances, while `seq_distmatrix` returns a distance matrix.

### Method
Various distance metrics are supported, including 'osa', 'lv', 'dl', 'hamming', 'lcs', 'qgram', 'cosine', 'jaccard', and 'jw'.

### Arguments
- **a** (list of integer or numeric vectors) - Target sequences. Will be converted with `as.integer`.
- **b** (list of integer or numeric vectors) - Source sequences. Optional for `seq_distmatrix`. Will be converted with `as.integer`.
- **method** (string) - Distance metric. See `stringdist-metrics`.
- **weight** (numeric vector) - Penalty weights for specific methods ('osa', 'dl', 'lv', 'jw').
- **q** (integer) - Size of the q-gram. Only applies to methods 'qgram', 'jaccard', or 'cosine'. Must be nonnegative.
- **p** (numeric) - Prefix factor for Jaro-Winkler distance. Valid range is `0 <= p <= 0.25`.
- **bt** (numeric) - Winkler's boost threshold. Only applies to method 'jw' and `p > 0`.
- **nthread** (integer) - Maximum number of threads to use.
- **useNames** (boolean) - Whether to label the output matrix with `names(a)` and `names(b)`.

### Value
- `seq_dist`: A numeric vector with pairwise distances.
- `seq_distmatrix`: A `dist` object (if `b` is missing) or a distance matrix.

### Notes
Input vectors are converted with `as.integer`, causing truncation for numeric vectors. NA values in sequences are treated as integers.

### Examples
```R
# Distances between lists of integer vectors
a <- list(c(102L, 107L))
b <- list(c(102L,111L,111L),c(102L,111L,111L))
seq_dist(a,b)

# Distance matrix
a <- lapply(c("foo","bar","baz"),utf8ToInt)
seq_distmatrix(a)

# Handling NA values
a <- list(NA_integer_,c(102L, 107L))
b <- list(c(102L,111L,111L),c(102L,111L,NA_integer_))
seq_dist(a,b)

# Example using hash package (requires installation)
# a <- "Mary had a little lamb"
# a.words <- strsplit(a,"[[:blank:]]+")
# a.int <- hashr::hash(a.words)
# b <- c("a little lamb had Mary", "had Mary a little lamb")
# b.int <- hashr::hash(strsplit(b,"[[:blank:]]+"))
# seq_dist(a.int,b.int)
```
```

--------------------------------

### Calculate Pairwise Distances Between Integer Sequences

Source: https://cran.r-project.org/web/packages/stringdist/refman/stringdist.html

Use seq_dist to compute pairwise distances between lists of integer vectors. Input vectors are converted to integers, truncating numeric values. NA values in sequences are treated as integers.

```R
a <- list(c(102L, 107L))                        # fu
b <- list(c(102L,111L,111L),c(102L,111L,111L))  # foo, fo
seq_dist(a,b)
```

```R
a <- lapply(c("foo","bar","baz"),utf8ToInt)
seq_distmatrix(a)
```

```R
a <- list(NA_integer_,c(102L, 107L))
b <- list(c(102L,111L,111L),c(102L,111L,NA_integer_))  
seq_dist(a,b)
```

```R
a <- "Mary had a little lamb"
a.words <- strsplit(a,"[[:blank:]]+")
a.int <- hashr::hash(a.words)
b <- c("a little lamb had Mary",
           "had Mary a little lamb")
b.int <- hashr::hash(strsplit(b,"[[:blank:]]+"))
seq_dist(a.int,b.int)
```