# python-string-similarity
**Python3.5 implementation of [tdebatty/java-string-similarity](https://github.com/tdebatty/java-string-similarity)**
A library implementing different string similarity and distance measures. A dozen of algorithms (including Levenshtein edit distance and sibblings, Jaro-Winkler, Longest Common Subsequence, cosine similarity etc.) are currently implemented. Check the summary table below for the complete list...
* [Download](#download)
* [Overview](#overview)
* [Normalized, metric, similarity and distance](#normalized-metric-similarity-and-distance)
* [Shingles (n-gram) based similarity and distance](#shingles-n-gram-based-similarity-and-distance)
* [Levenshtein](#levenshtein)
* [Normalized Levenshtein](#normalized-levenshtein)
* [Weighted Levenshtein](#weighted-levenshtein)
* [Damerau-Levenshtein](#damerau-levenshtein)
* [Optimal String Alignment](#optimal-string-alignment)
* [Jaro-Winkler](#jaro-winkler)
* [Longest Common Subsequence](#longest-common-subsequence)
* [Metric Longest Common Subsequence](#metric-longest-common-subsequence)
* [N-Gram](#n-gram)
* [Shingle (n-gram) based algorithms](#shingle-n-gram-based-algorithms)
* [Q-Gram](#shingle-n-gram-based-algorithms)
* [Cosine similarity](#shingle-n-gram-based-algorithms)
* [Jaccard index](#shingle-n-gram-based-algorithms)
* [Sorensen-Dice coefficient](#shingle-n-gram-based-algorithms)
* [Experimental](#experimental)
* [SIFT4](#sift4)
* [Users](#users)
## Download
From pypi:
```bash
pip install strsim
```
or clone this repository:
```bash
git clone https://github.com/luozhouyang/python-string-similarity
cd python-string-similarity
pip install -r requirements.txt
```
## Overview
The main characteristics of each implemented algorithm are presented below. The "cost" column gives an estimation of the computational cost to compute the similarity between two strings of length m and n respectively.
| | | Normalized? | Metric? | Type | Cost | Typical usage |
| -------- |------- |------------- |-------- | ------ | ---- | --- |
| [Levenshtein](#levenshtein) |distance | No | Yes | | O(m*n) <sup>1</sup> | |
| [Normalized Levenshtein](#normalized-levenshtein) |distance<br>similarity | Yes | No | | O(m*n) <sup>1</sup> | |
| [Weighted Levenshtein](#weighted-levenshtein) |distance | No | No | | O(m*n) <sup>1</sup> | OCR |
| [Damerau-Levenshtein](#damerau-levenshtein) <sup>3</sup> |distance | No | Yes | | O(m*n) <sup>1</sup> | |
| [Optimal String Alignment](#optimal-string-alignment) <sup>3</sup> |distance | No | No | | O(m*n) <sup>1</sup> | |
| [Jaro-Winkler](#jaro-winkler) |similarity<br>distance | Yes | No | | O(m*n) | typo correction |
| [Longest Common Subsequence](#longest-common-subsequence) |distance | No | No | | O(m*n) <sup>1,2</sup> | diff utility, GIT reconciliation |
| [Metric Longest Common Subsequence](#metric-longest-common-subsequence) |distance | Yes | Yes | | O(m*n) <sup>1,2</sup> | |
| [N-Gram](#n-gram) |distance | Yes | No | | O(m*n) | |
| [Q-Gram](#q-gram) |distance | No | No | Profile | O(m+n) | |
| [Cosine similarity](#cosine-similarity) |similarity<br>distance | Yes | No | Profile | O(m+n) | |
| [Jaccard index](#jaccard-index) |similarity<br>distance | Yes | Yes | Set | O(m+n) | |
| [Sorensen-Dice coefficient](#sorensen-dice-coefficient) |similarity<br>distance | Yes | No | Set | O(m+n) | |
[1] In this library, Levenshtein edit distance, LCS distance and their sibblings are computed using the **dynamic programming** method, which has a cost O(m.n). For Levenshtein distance, the algorithm is sometimes called **Wagner-Fischer algorithm** ("The string-to-string correction problem", 1974). The original algorithm uses a matrix of size m x n to store the Levenshtein distance between string prefixes.
If the alphabet is finite, it is possible to use the **method of four russians** (Arlazarov et al. "On economic construction of the transitive closure of a directed graph", 1970) to speedup computation. This was published by Masek in 1980 ("A Faster Algorithm Computing String Edit Distances"). This method splits the matrix in blocks of size t x t. Each possible block is precomputed to produce a lookup table. This lookup table can then be used to compute the string similarity (or distance) in O(nm/t). Usually, t is choosen as log(m) if m > n. The resulting computation cost is thus O(mn/log(m)). This method has not been implemented (yet).
[2] In "Length of Maximal Common Subsequences", K.S. Larsen proposed an algorithm that computes the length of LCS in time O(log(m).log(n)). But the algorithm has a memory requirement O(m.n²) and was thus not implemented here.
[3] There are two variants of Damerau-Levenshtein string distance: Damerau-Levenshtein with adjacent transpositions (also sometimes called unrestricted Damerau–Levenshtein distance) and Optimal String Alignment (also sometimes called restricted edit distance). For Optimal String Alignment, no substring can be edited more than once.
## Normalized, metric, similarity and distance
Although the topic might seem simple, a lot of different algorithms exist to measure text similarity or distance. Therefore the library defines some interfaces to categorize them.
### (Normalized) similarity and distance
- StringSimilarity : Implementing algorithms define a similarity between strings (0 means strings are completely different).
- NormalizedStringSimilarity : Implementing algorithms define a similarity between 0.0 and 1.0, like Jaro-Winkler for example.
- StringDistance : Implementing algorithms define a distance between strings (0 means strings are identical), like Levenshtein for example. The maximum distance value depends on the algorithm.
- NormalizedStringDistance : This interface extends StringDistance. For implementing classes, the computed distance value is between 0.0 and 1.0. NormalizedLevenshtein is an example of NormalizedStringDistance.
Generally, algorithms that implement NormalizedStringSimilarity also implement NormalizedStringDistance, and similarity = 1 - distance. But there are a few exceptions, like N-Gram similarity and distance (Kondrak)...
### Metric distances
The MetricStringDistance interface : A few of the distances are actually metric distances, which means that verify the triangle inequality d(x, y) <= d(x,z) + d(z,y). For example, Levenshtein is a metric distance, but NormalizedLevenshtein is not.
A lot of nearest-neighbor search algorithms and indexing structures rely on the triangle inequality.
## Shingles (n-gram) based similarity and distance
A few algorithms work by converting strings into sets of n-grams (sequences of n characters, also sometimes called k-shingles). The similarity or distance between the strings is then the similarity or distance between the sets.
Some of them, like jaccard, consider strings as sets of shingles, and don't consider the number of occurences of each shingle. Others, like cosine similarity, work using what is sometimes called the profile of the strings, which takes into account the number of occurences of each shingle.
For these algorithms, another use case is possible when dealing with large datasets:
1. compute the set or profile representation of all the strings
2. compute the similarity between sets or profiles
## Levenshtein
The Levenshtein distance between two words is the minimum number of single-character edits (insertions, deletions or substitutions) required to change one word into the other.
It is a metric string distance. This implementation uses dynamic programming (Wagner–Fischer algorithm), with only 2 rows of data. The space requirement is thus O(m) and the algorithm runs in O(m.n).
```python
from similarity.levenshtein import Levenshtein
levenshtein = Levenshtein()
print(levenshtein.distance('My string', 'My $string'))
print(levenshtein.distance('My string', 'My $string'))
print(levenshtein.distance('My string', 'My $string'))
```
## Normalized Levenshtein
This distance is computed as levenshtein distance divided by the length of the longest string. The resulting value is always in the interval [0.0 1.0] but it is not a metric anymore!
The similarity is computed as 1 - normalized distance.
```python
from similarity.normalized_levenshtein import NormalizedLevenshtein
normalized_levenshtein = NormalizedLevenshtein()
print(normalized_levenshtein.distance('My string', 'My $string'))
print(normalized_levenshtein.distance('My string', 'My $string'))
print(normalized_levenshtein.distance('My string', 'My $string'))
print(normalized_levenshtein.similarity('My string', 'My $string'))
print(normalized_levenshtein.similarity('My string', 'My $string'))
print(normalized_levenshtein.similarity('My string', 'My $string'))
```
## Weighted Levenshtein
An implementation of Levenshtein that allows to define different weights for different character substitutions.
This algorithm is usually used for optical character recognition (OCR) applications. For OCR, the cost of substituting P and R is lower then the cost of substituting P and M for example because because from and OCR point of view P is similar to R.
It can also be used for keyboard typing auto-correction. Here the cost of substituting E and R is lower for example because these are located next to each other on an AZERTY or QWERTY keyboard. Hence the probability that the user mistyped the characters is higher.
```python
from similarity.weighted_levenshtein import WeightedLevenshtein
from similarity.weighted_levenshtein import CharacterSubstitutionInterface
class CharacterSubstitution(CharacterSubstitutionInterface):
def cost(self, c0, c1):
if c0=='t' and c1=='r':
return 0.5
return 1.0
weighted_levenshtein = WeightedLevenshtein(CharacterSubstitution())
print(weighted_levenshtein.distance('String1', 'String2'))
```
## Damerau-Levenshtein
Similar to Levenshtein, Damerau-Levenshtein distance with transposition (also sometimes calls unrestricted Damerau-Levenshtein distance) is the minimum number of operations needed to transform one string into the other, where an operation is defined as an insertion, deletion, or substitution of a single character, or a **transposition of two adjacent characters**.
It does respect triangle inequality, and is thus a metric distance.
This is not to be confused with the optimal string alignment distance, which is an extension where no substring can be edited more than once.
```python
from similarity.damerau import Damerau
damerau = Damerau()
print(damerau.distance('ABCDEF', 'ABDCEF'))
print(damerau.distance('ABCDEF', 'BACDFE'))
print(damerau.distance('ABCDEF', 'ABCDE'))
print(damerau.distance('ABCDEF', 'BCDEF'))
print(damerau.distance('ABCDEF', 'ABCGDEF'))
print(damerau.distance('ABCDEF', 'POIU'))
```
Will produce:
```
1.0
2.0
1.0
1.0
1.0
6.0
```
## Optimal String Alignment
The Optimal String Alignment variant of Damerau–Levenshtein (sometimes called the restricted edit distance) computes the number of edit operations needed to make the strings equal under the condition that **no substring is edited more than once**, whereas the true Damerau–Levenshtein presents no such restriction.
The difference from the algorithm for Levenshtein distance is the addition of one recurrence for the transposition operations.
Note that for the optimal string alignment distance, the triangle inequality does not hold and so it is not a true metric.
```python
from similarity.optimal_string_alignment import OptimalStringAlignment
optimal_string_alignment = OptimalStringAlignment()
print(optimal_string_alignment.distance('CA', 'ABC'))
```
Will produce:
```
3.0
```
## Jaro-Winkler
Jaro-Winkler is a string edit distance that was developed in the area of record linkage (duplicate detection) (Winkler, 1990). The Jaro–Winkler distance metric is designed and best suited for short strings such as person names, and to detect typos.
Jaro-Winkler computes the similarity between 2 strings, and the returned value lies in the interval [0.0, 1.0].
It is (roughly) a variation of Damerau-Levenshtein, where the substitution of 2 close characters is considered less important then the substitution of 2 characters that a far from each other.
The distance is computed as 1 - Jaro-Winkler similarity.
```python
from similarity.jarowinkler import JaroWinkler
jarowinkler = JaroWinkler()
print(jarowinkler.similarity('My string', 'My tsring'))
print(jarowinkler.similarity('My string', 'My ntrisg'))
```
will produce:
```
0.9740740740740741
0.8962962962962963
```
## Longest Common Subsequence
The longest common subsequence (LCS) problem consists in finding the longest subsequence common to two (or more) sequences. It differs from problems of finding common substrings: unlike substrings, subsequences are not required to occupy consecutive positions within the original sequences.
It is used by the diff utility, by Git for reconciling multiple changes, etc.
The LCS distance between strings X (of length n) and Y (of length m) is n + m - 2 |LCS(X, Y)|
min = 0
max = n + m
LCS distance is equivalent to Levenshtein distance when only insertion and deletion is allowed (no substitution), or when the cost of the substitution is the double of the cost of an insertion or deletion.
This class implements the dynamic programming approach, which has a space requirement O(m.n), and computation cost O(m.n).
In "Length of Maximal Common Subsequences", K.S. Larsen proposed an algorithm that computes the length of LCS in time O(log(m).log(n)). But the algorithm has a memory requirement O(m.n²) and was thus not implemented here.
```python
from similarity.longest_common_subsequence import LongestCommonSubsequence
lcs = LongestCommonSubsequence()
# Will produce 4.0
print(lcs.distance('AGCAT', 'GAC'))
# Will produce 1.0
print(lcs.distance('AGCAT', 'AGCT'))
```
## Metric Longest Common Subsequence
Distance metric based on Longest Common Subsequence, from the notes "An LCS-based string metric" by Daniel Bakkelund.
http://heim.ifi.uio.no/~danielry/StringMetric.pdf
The distance is computed as 1 - |LCS(s1, s2)| / max(|s1|, |s2|)
```python
from similarity.metric_lcs import MetricLCS
metric_lcs = MetricLCS()
s1 = 'ABCDEFG'
s2 = 'ABCDEFHJKL'
# LCS: ABCDEF => length = 6
# longest = s2 => length = 10
# => 1 - 6/10 = 0.4
print(metric_lcs.distance(s1, s2))
# LCS: ABDF => length = 4
# longest = ABDEF => length = 5
# => 1 - 4 / 5 = 0.2
print(metric_lcs.distance('ABDEF', 'ABDIF'))
```
will produce:
```
0.4
0.19999999999999996
```
## N-Gram
Normalized N-Gram distance as defined by Kondrak, "N-Gram Similarity and Distance", String Processing and Information Retrieval, Lecture Notes in Computer Science Volume 3772, 2005, pp 115-126.
http://webdocs.cs.ualberta.ca/~kondrak/papers/spire05.pdf
The algorithm uses affixing with special character '\n' to increase the weight of first characters. The normalization is achieved by dividing the total similarity score the original length of the longest word.
In the paper, Kondrak also defines a similarity measure, which is not implemented (yet).
```python
from similarity.ngram import NGram
twogram = NGram(2)
print(twogram.distance('ABCD', 'ABTUIO'))
s1 = 'Adobe CreativeSuite 5 Master Collection from cheap 4zp'
s2 = 'Adobe CreativeSuite 5 Master Collection from cheap d1x'
fourgram = NGram(4)
print(fourgram.distance(s1, s2))
```
## Shingle (n-gram) based algorithms
A few algorithms work by converting strings into sets of n-grams (sequences of n characters, also sometimes called k-shingles). The similarity or distance between the strings is then the similarity or distance between the sets.
The cost for computing these similarities and distances is mainly domnitated by k-shingling (converting the strings into sequences of k characters). Therefore there are typically two use cases for these algorithms:
Directly compute the distance between strings:
```python
from similarity.qgram import QGram
qgram = QGram(2)
print(qgram.distance('ABCD', 'ABCE'))
```
Or, for large datasets, pre-compute the profile of all strings. The similarity can then be computed between profiles:
```python
from similarity.cosine import Cosine
cosine = Cosine(2)
s0 = 'My first string'
s1 = 'My other string...'
p0 = cosine.get_profile(s0)
p1 = cosine.get_profile(s1)
print(cosine.similarity_profiles(p0, p1))
```
Pay attention, this only works if the same KShingling object is used to parse all input strings !
### Q-Gram
Q-gram distance, as defined by Ukkonen in "Approximate string-matching with q-grams and maximal matches"
http://www.sciencedirect.com/science/article/pii/0304397592901434
The distance between two strings is defined as the L1 norm of the difference of their profiles (the number of occurences of each n-gram): SUM( |V1_i - V2_i| ). Q-gram distance is a lower bound on Levenshtein distance, but can be computed in O(m + n), where Levenshtein requires O(m.n)
### Cosine similarity
The similarity between the two strings is the cosine of the angle between these two vectors representation, and is computed as V1 . V2 / (|V1| * |V2|)
Distance is computed as 1 - cosine similarity.
### Jaccard index
Like Q-Gram distance, the input strings are first converted into sets of n-grams (sequences of n characters, also called k-shingles), but this time the cardinality of each n-gram is not taken into account. Each input string is simply a set of n-grams. The Jaccard index is then computed as |V1 inter V2| / |V1 union V2|.
Distance is computed as 1 - similarity.
Jaccard index is a metric distance.
### Sorensen-Dice coefficient
Similar to Jaccard index, but this time the similarity is computed as 2 * |V1 inter V2| / (|V1| + |V2|).
Distance is computed as 1 - similarity.
## Experimental
### SIFT4
SIFT4 is a general purpose string distance algorithm inspired by JaroWinkler and Longest Common Subsequence. It was developed to produce a distance measure that matches as close as possible to the human perception of string distance. Hence it takes into account elements like character substitution, character distance, longest common subsequence etc. It was developed using experimental testing, and without theoretical background.
**Not implemented yet**
## Users
* [StringSimilarity.NET](https://github.com/feature23/StringSimilarity.NET) a .NET port of java-string-similarity
Use java-string-similarity in your project and want it to be mentioned here? Don't hesitate to drop me a line!
Raw data
{
"_id": null,
"home_page": "https://github.com/luozhouyang/python-string-similarity",
"name": "strsim",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "ZhouYang Luo",
"author_email": "stupidme.me.lzy@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/04/11/4788bfa6ea590f5542a37e3897822255b81b47ee9bf324bc8b54c608e948/strsim-0.0.3.tar.gz",
"platform": "",
"description": "# python-string-similarity\n**Python3.5 implementation of [tdebatty/java-string-similarity](https://github.com/tdebatty/java-string-similarity)**\n\n\nA library implementing different string similarity and distance measures. A dozen of algorithms (including Levenshtein edit distance and sibblings, Jaro-Winkler, Longest Common Subsequence, cosine similarity etc.) are currently implemented. Check the summary table below for the complete list...\n\n* [Download](#download)\n* [Overview](#overview)\n* [Normalized, metric, similarity and distance](#normalized-metric-similarity-and-distance)\n* [Shingles (n-gram) based similarity and distance](#shingles-n-gram-based-similarity-and-distance)\n* [Levenshtein](#levenshtein)\n* [Normalized Levenshtein](#normalized-levenshtein)\n* [Weighted Levenshtein](#weighted-levenshtein)\n* [Damerau-Levenshtein](#damerau-levenshtein)\n* [Optimal String Alignment](#optimal-string-alignment)\n* [Jaro-Winkler](#jaro-winkler)\n* [Longest Common Subsequence](#longest-common-subsequence)\n* [Metric Longest Common Subsequence](#metric-longest-common-subsequence)\n* [N-Gram](#n-gram)\n* [Shingle (n-gram) based algorithms](#shingle-n-gram-based-algorithms)\n * [Q-Gram](#shingle-n-gram-based-algorithms)\n * [Cosine similarity](#shingle-n-gram-based-algorithms)\n * [Jaccard index](#shingle-n-gram-based-algorithms)\n * [Sorensen-Dice coefficient](#shingle-n-gram-based-algorithms)\n* [Experimental](#experimental)\n * [SIFT4](#sift4)\n* [Users](#users)\n\n\n## Download\n\nFrom pypi:\n\n```bash\npip install strsim\n```\n\nor clone this repository:\n\n```bash\ngit clone https://github.com/luozhouyang/python-string-similarity\ncd python-string-similarity\npip install -r requirements.txt\n```\n\n## Overview\n\nThe main characteristics of each implemented algorithm are presented below. The \"cost\" column gives an estimation of the computational cost to compute the similarity between two strings of length m and n respectively.\n\n| \t\t\t\t\t\t\t\t\t| \t\t\t\t\t\t| Normalized? \t| Metric?\t| Type | Cost | Typical usage |\n| --------\t\t\t\t\t|-------\t\t\t|-------------\t|-------- | ------ | ---- | --- |\n| [Levenshtein](#levenshtein)\t\t|distance \t\t\t\t| No \t\t\t| Yes \t\t| | O(m*n) <sup>1</sup> | |\n| [Normalized Levenshtein](#normalized-levenshtein)\t|distance<br>similarity\t| Yes \t\t\t| No \t\t| \t | O(m*n) <sup>1</sup> | |\n| [Weighted Levenshtein](#weighted-levenshtein)\t\t|distance \t\t\t\t| No \t\t\t| No \t\t| \t | O(m*n) <sup>1</sup> | OCR |\n| [Damerau-Levenshtein](#damerau-levenshtein) <sup>3</sup> \t|distance \t\t\t\t| No \t\t\t| Yes \t\t| \t | O(m*n) <sup>1</sup> | |\n| [Optimal String Alignment](#optimal-string-alignment) <sup>3</sup> |distance | No \t\t\t| No \t\t| \t | O(m*n) <sup>1</sup> | |\n| [Jaro-Winkler](#jaro-winkler) \t\t|similarity<br>distance\t| Yes \t\t\t| No \t\t| \t | O(m*n) | typo correction |\n| [Longest Common Subsequence](#longest-common-subsequence) \t\t|distance \t\t\t\t| No \t\t\t| No \t\t| \t | O(m*n) <sup>1,2</sup> | diff utility, GIT reconciliation |\n| [Metric Longest Common Subsequence](#metric-longest-common-subsequence) |distance \t\t\t| Yes \t\t\t| Yes \t\t| \t | O(m*n) <sup>1,2</sup> | |\n| [N-Gram](#n-gram)\t \t\t\t\t|distance\t\t\t\t| Yes \t\t\t| No \t\t| \t | O(m*n) | |\n| [Q-Gram](#q-gram) \t\t\t\t|distance \t\t\t \t| No \t\t\t| No \t\t| Profile | O(m+n) | |\n| [Cosine similarity](#cosine-similarity) \t\t\t\t|similarity<br>distance | Yes \t\t\t| No \t\t| Profile | O(m+n) | |\n| [Jaccard index](#jaccard-index)\t\t\t\t|similarity<br>distance | Yes \t\t\t| Yes \t\t| Set\t | O(m+n) | |\n| [Sorensen-Dice coefficient](#sorensen-dice-coefficient) \t|similarity<br>distance | Yes \t\t\t| No \t\t| Set\t | O(m+n) | |\n\n[1] In this library, Levenshtein edit distance, LCS distance and their sibblings are computed using the **dynamic programming** method, which has a cost O(m.n). For Levenshtein distance, the algorithm is sometimes called **Wagner-Fischer algorithm** (\"The string-to-string correction problem\", 1974). The original algorithm uses a matrix of size m x n to store the Levenshtein distance between string prefixes.\n\nIf the alphabet is finite, it is possible to use the **method of four russians** (Arlazarov et al. \"On economic construction of the transitive closure of a directed graph\", 1970) to speedup computation. This was published by Masek in 1980 (\"A Faster Algorithm Computing String Edit Distances\"). This method splits the matrix in blocks of size t x t. Each possible block is precomputed to produce a lookup table. This lookup table can then be used to compute the string similarity (or distance) in O(nm/t). Usually, t is choosen as log(m) if m > n. The resulting computation cost is thus O(mn/log(m)). This method has not been implemented (yet).\n\n[2] In \"Length of Maximal Common Subsequences\", K.S. Larsen proposed an algorithm that computes the length of LCS in time O(log(m).log(n)). But the algorithm has a memory requirement O(m.n\u00b2) and was thus not implemented here.\n\n[3] There are two variants of Damerau-Levenshtein string distance: Damerau-Levenshtein with adjacent transpositions (also sometimes called unrestricted Damerau\u2013Levenshtein distance) and Optimal String Alignment (also sometimes called restricted edit distance). For Optimal String Alignment, no substring can be edited more than once.\n\n## Normalized, metric, similarity and distance\nAlthough the topic might seem simple, a lot of different algorithms exist to measure text similarity or distance. Therefore the library defines some interfaces to categorize them.\n\n### (Normalized) similarity and distance\n\n- StringSimilarity : Implementing algorithms define a similarity between strings (0 means strings are completely different).\n- NormalizedStringSimilarity : Implementing algorithms define a similarity between 0.0 and 1.0, like Jaro-Winkler for example.\n- StringDistance : Implementing algorithms define a distance between strings (0 means strings are identical), like Levenshtein for example. The maximum distance value depends on the algorithm.\n- NormalizedStringDistance : This interface extends StringDistance. For implementing classes, the computed distance value is between 0.0 and 1.0. NormalizedLevenshtein is an example of NormalizedStringDistance.\n\nGenerally, algorithms that implement NormalizedStringSimilarity also implement NormalizedStringDistance, and similarity = 1 - distance. But there are a few exceptions, like N-Gram similarity and distance (Kondrak)...\n\n### Metric distances\nThe MetricStringDistance interface : A few of the distances are actually metric distances, which means that verify the triangle inequality d(x, y) <= d(x,z) + d(z,y). For example, Levenshtein is a metric distance, but NormalizedLevenshtein is not.\n\nA lot of nearest-neighbor search algorithms and indexing structures rely on the triangle inequality. \n\n## Shingles (n-gram) based similarity and distance\nA few algorithms work by converting strings into sets of n-grams (sequences of n characters, also sometimes called k-shingles). The similarity or distance between the strings is then the similarity or distance between the sets.\n\nSome of them, like jaccard, consider strings as sets of shingles, and don't consider the number of occurences of each shingle. Others, like cosine similarity, work using what is sometimes called the profile of the strings, which takes into account the number of occurences of each shingle.\n\nFor these algorithms, another use case is possible when dealing with large datasets:\n1. compute the set or profile representation of all the strings\n2. compute the similarity between sets or profiles\n\n## Levenshtein\nThe Levenshtein distance between two words is the minimum number of single-character edits (insertions, deletions or substitutions) required to change one word into the other.\n\nIt is a metric string distance. This implementation uses dynamic programming (Wagner\u2013Fischer algorithm), with only 2 rows of data. The space requirement is thus O(m) and the algorithm runs in O(m.n).\n\n```python\nfrom similarity.levenshtein import Levenshtein\n\nlevenshtein = Levenshtein()\nprint(levenshtein.distance('My string', 'My $string'))\nprint(levenshtein.distance('My string', 'My $string'))\nprint(levenshtein.distance('My string', 'My $string'))\n\n``` \n\n\n## Normalized Levenshtein\nThis distance is computed as levenshtein distance divided by the length of the longest string. The resulting value is always in the interval [0.0 1.0] but it is not a metric anymore!\n\nThe similarity is computed as 1 - normalized distance.\n\n```python\nfrom similarity.normalized_levenshtein import NormalizedLevenshtein\n\nnormalized_levenshtein = NormalizedLevenshtein()\nprint(normalized_levenshtein.distance('My string', 'My $string'))\nprint(normalized_levenshtein.distance('My string', 'My $string'))\nprint(normalized_levenshtein.distance('My string', 'My $string'))\n\nprint(normalized_levenshtein.similarity('My string', 'My $string'))\nprint(normalized_levenshtein.similarity('My string', 'My $string'))\nprint(normalized_levenshtein.similarity('My string', 'My $string'))\n\n``` \n\n## Weighted Levenshtein\nAn implementation of Levenshtein that allows to define different weights for different character substitutions.\n\nThis algorithm is usually used for optical character recognition (OCR) applications. For OCR, the cost of substituting P and R is lower then the cost of substituting P and M for example because because from and OCR point of view P is similar to R.\n\nIt can also be used for keyboard typing auto-correction. Here the cost of substituting E and R is lower for example because these are located next to each other on an AZERTY or QWERTY keyboard. Hence the probability that the user mistyped the characters is higher.\n\n```python\nfrom similarity.weighted_levenshtein import WeightedLevenshtein\nfrom similarity.weighted_levenshtein import CharacterSubstitutionInterface\n\nclass CharacterSubstitution(CharacterSubstitutionInterface):\n def cost(self, c0, c1):\n if c0=='t' and c1=='r':\n return 0.5\n return 1.0\n\nweighted_levenshtein = WeightedLevenshtein(CharacterSubstitution())\nprint(weighted_levenshtein.distance('String1', 'String2'))\n\n```\n\n## Damerau-Levenshtein\nSimilar to Levenshtein, Damerau-Levenshtein distance with transposition (also sometimes calls unrestricted Damerau-Levenshtein distance) is the minimum number of operations needed to transform one string into the other, where an operation is defined as an insertion, deletion, or substitution of a single character, or a **transposition of two adjacent characters**.\n\nIt does respect triangle inequality, and is thus a metric distance.\n\nThis is not to be confused with the optimal string alignment distance, which is an extension where no substring can be edited more than once.\n\n```python\nfrom similarity.damerau import Damerau\n\ndamerau = Damerau()\nprint(damerau.distance('ABCDEF', 'ABDCEF'))\nprint(damerau.distance('ABCDEF', 'BACDFE'))\nprint(damerau.distance('ABCDEF', 'ABCDE'))\nprint(damerau.distance('ABCDEF', 'BCDEF'))\nprint(damerau.distance('ABCDEF', 'ABCGDEF'))\nprint(damerau.distance('ABCDEF', 'POIU'))\n\n```\n\nWill produce:\n\n```\n1.0\n2.0\n1.0\n1.0\n1.0\n6.0\n```\n\n## Optimal String Alignment\nThe Optimal String Alignment variant of Damerau\u2013Levenshtein (sometimes called the restricted edit distance) computes the number of edit operations needed to make the strings equal under the condition that **no substring is edited more than once**, whereas the true Damerau\u2013Levenshtein presents no such restriction.\nThe difference from the algorithm for Levenshtein distance is the addition of one recurrence for the transposition operations.\n\nNote that for the optimal string alignment distance, the triangle inequality does not hold and so it is not a true metric.\n\n```python\nfrom similarity.optimal_string_alignment import OptimalStringAlignment\n\noptimal_string_alignment = OptimalStringAlignment()\nprint(optimal_string_alignment.distance('CA', 'ABC'))\n\n```\n\nWill produce:\n\n```\n3.0\n```\n\n## Jaro-Winkler\nJaro-Winkler is a string edit distance that was developed in the area of record linkage (duplicate detection) (Winkler, 1990). The Jaro\u2013Winkler distance metric is designed and best suited for short strings such as person names, and to detect typos.\n\nJaro-Winkler computes the similarity between 2 strings, and the returned value lies in the interval [0.0, 1.0].\nIt is (roughly) a variation of Damerau-Levenshtein, where the substitution of 2 close characters is considered less important then the substitution of 2 characters that a far from each other.\n\nThe distance is computed as 1 - Jaro-Winkler similarity.\n\n```python\nfrom similarity.jarowinkler import JaroWinkler\n\njarowinkler = JaroWinkler()\nprint(jarowinkler.similarity('My string', 'My tsring'))\nprint(jarowinkler.similarity('My string', 'My ntrisg'))\n\n```\n\nwill produce:\n\n```\n0.9740740740740741\n0.8962962962962963\n```\n\n## Longest Common Subsequence\n\nThe longest common subsequence (LCS) problem consists in finding the longest subsequence common to two (or more) sequences. It differs from problems of finding common substrings: unlike substrings, subsequences are not required to occupy consecutive positions within the original sequences.\n\nIt is used by the diff utility, by Git for reconciling multiple changes, etc.\n\nThe LCS distance between strings X (of length n) and Y (of length m) is n + m - 2 |LCS(X, Y)|\nmin = 0\nmax = n + m\n\nLCS distance is equivalent to Levenshtein distance when only insertion and deletion is allowed (no substitution), or when the cost of the substitution is the double of the cost of an insertion or deletion.\n\nThis class implements the dynamic programming approach, which has a space requirement O(m.n), and computation cost O(m.n).\n\nIn \"Length of Maximal Common Subsequences\", K.S. Larsen proposed an algorithm that computes the length of LCS in time O(log(m).log(n)). But the algorithm has a memory requirement O(m.n\u00b2) and was thus not implemented here.\n\n```python\nfrom similarity.longest_common_subsequence import LongestCommonSubsequence\n\nlcs = LongestCommonSubsequence()\n# Will produce 4.0\nprint(lcs.distance('AGCAT', 'GAC'))\n# Will produce 1.0\nprint(lcs.distance('AGCAT', 'AGCT'))\n\n```\n\n## Metric Longest Common Subsequence\nDistance metric based on Longest Common Subsequence, from the notes \"An LCS-based string metric\" by Daniel Bakkelund.\nhttp://heim.ifi.uio.no/~danielry/StringMetric.pdf\n\nThe distance is computed as 1 - |LCS(s1, s2)| / max(|s1|, |s2|) \n\n```python\nfrom similarity.metric_lcs import MetricLCS\n\nmetric_lcs = MetricLCS()\ns1 = 'ABCDEFG'\ns2 = 'ABCDEFHJKL'\n\n# LCS: ABCDEF => length = 6\n# longest = s2 => length = 10\n# => 1 - 6/10 = 0.4\nprint(metric_lcs.distance(s1, s2))\n\n# LCS: ABDF => length = 4\n# longest = ABDEF => length = 5\n# => 1 - 4 / 5 = 0.2\nprint(metric_lcs.distance('ABDEF', 'ABDIF'))\n\n``` \n\nwill produce:\n\n```\n0.4\n0.19999999999999996\n```\n\n\n## N-Gram\n\nNormalized N-Gram distance as defined by Kondrak, \"N-Gram Similarity and Distance\", String Processing and Information Retrieval, Lecture Notes in Computer Science Volume 3772, 2005, pp 115-126.\n\nhttp://webdocs.cs.ualberta.ca/~kondrak/papers/spire05.pdf\n\nThe algorithm uses affixing with special character '\\n' to increase the weight of first characters. The normalization is achieved by dividing the total similarity score the original length of the longest word.\n\nIn the paper, Kondrak also defines a similarity measure, which is not implemented (yet).\n\n```python\nfrom similarity.ngram import NGram\n\ntwogram = NGram(2)\nprint(twogram.distance('ABCD', 'ABTUIO'))\n\ns1 = 'Adobe CreativeSuite 5 Master Collection from cheap 4zp'\ns2 = 'Adobe CreativeSuite 5 Master Collection from cheap d1x'\nfourgram = NGram(4)\nprint(fourgram.distance(s1, s2))\n\n```\n\n## Shingle (n-gram) based algorithms\nA few algorithms work by converting strings into sets of n-grams (sequences of n characters, also sometimes called k-shingles). The similarity or distance between the strings is then the similarity or distance between the sets.\n\nThe cost for computing these similarities and distances is mainly domnitated by k-shingling (converting the strings into sequences of k characters). Therefore there are typically two use cases for these algorithms:\n\nDirectly compute the distance between strings:\n\n```python\nfrom similarity.qgram import QGram\n\nqgram = QGram(2)\nprint(qgram.distance('ABCD', 'ABCE'))\n\n``` \n\nOr, for large datasets, pre-compute the profile of all strings. The similarity can then be computed between profiles:\n\n```python\nfrom similarity.cosine import Cosine\n\ncosine = Cosine(2)\ns0 = 'My first string'\ns1 = 'My other string...'\np0 = cosine.get_profile(s0)\np1 = cosine.get_profile(s1)\nprint(cosine.similarity_profiles(p0, p1))\n\n```\n\nPay attention, this only works if the same KShingling object is used to parse all input strings !\n\n\n### Q-Gram\nQ-gram distance, as defined by Ukkonen in \"Approximate string-matching with q-grams and maximal matches\"\nhttp://www.sciencedirect.com/science/article/pii/0304397592901434\n\nThe distance between two strings is defined as the L1 norm of the difference of their profiles (the number of occurences of each n-gram): SUM( |V1_i - V2_i| ). Q-gram distance is a lower bound on Levenshtein distance, but can be computed in O(m + n), where Levenshtein requires O(m.n)\n\n\n### Cosine similarity\nThe similarity between the two strings is the cosine of the angle between these two vectors representation, and is computed as V1 . V2 / (|V1| * |V2|)\n\nDistance is computed as 1 - cosine similarity.\n\n### Jaccard index\nLike Q-Gram distance, the input strings are first converted into sets of n-grams (sequences of n characters, also called k-shingles), but this time the cardinality of each n-gram is not taken into account. Each input string is simply a set of n-grams. The Jaccard index is then computed as |V1 inter V2| / |V1 union V2|.\n\nDistance is computed as 1 - similarity.\nJaccard index is a metric distance.\n\n### Sorensen-Dice coefficient\nSimilar to Jaccard index, but this time the similarity is computed as 2 * |V1 inter V2| / (|V1| + |V2|).\n\nDistance is computed as 1 - similarity.\n\n## Experimental\n\n### SIFT4\nSIFT4 is a general purpose string distance algorithm inspired by JaroWinkler and Longest Common Subsequence. It was developed to produce a distance measure that matches as close as possible to the human perception of string distance. Hence it takes into account elements like character substitution, character distance, longest common subsequence etc. It was developed using experimental testing, and without theoretical background.\n\n**Not implemented yet**\n\n\n\n## Users\n* [StringSimilarity.NET](https://github.com/feature23/StringSimilarity.NET) a .NET port of java-string-similarity\n\nUse java-string-similarity in your project and want it to be mentioned here? Don't hesitate to drop me a line!\n\n\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A library implementing different string similarity and distance measures",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/luozhouyang/python-string-similarity"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0d9514e5dea00c3bc73e5962261442957ee3691de8d51c97909ba7b2f46bf584",
"md5": "8b999d66e897f852d05731ed818e4420",
"sha256": "e5cf287392f906f0c6338dba8173ba9a05d8c3c173a74082c91220421d64d9fc"
},
"downloads": -1,
"filename": "strsim-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b999d66e897f852d05731ed818e4420",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 42360,
"upload_time": "2018-07-13T11:13:01",
"upload_time_iso_8601": "2018-07-13T11:13:01.377509Z",
"url": "https://files.pythonhosted.org/packages/0d/95/14e5dea00c3bc73e5962261442957ee3691de8d51c97909ba7b2f46bf584/strsim-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "04114788bfa6ea590f5542a37e3897822255b81b47ee9bf324bc8b54c608e948",
"md5": "3d49e3c17600372197c17af6f4e64545",
"sha256": "250cf1f698eceb00856cb368a417790d5f951bdc6329a799d89c6f6b85e41bcb"
},
"downloads": -1,
"filename": "strsim-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "3d49e3c17600372197c17af6f4e64545",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14747,
"upload_time": "2018-07-13T11:13:03",
"upload_time_iso_8601": "2018-07-13T11:13:03.023035Z",
"url": "https://files.pythonhosted.org/packages/04/11/4788bfa6ea590f5542a37e3897822255b81b47ee9bf324bc8b54c608e948/strsim-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2018-07-13 11:13:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "luozhouyang",
"github_project": "python-string-similarity",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "strsim"
}
JSON
