Add Jaccard Similarity (TheAlgorithms#419)

Author: Kalkwst

Algorithms.Tests/Strings/Similarity/JaccardDistanceTests.cs

@@ -0,0 +1,36 @@
+using System;
+using Algorithms.Strings.Similarity;
+using FluentAssertions;
+using NUnit.Framework;
+
+namespace Algorithms.Tests.Strings.Similarity;
+
+public class JaccardDistanceTests
+{
+    private readonly JaccardDistance jaccard = new JaccardDistance();
+    private readonly double precision = 0.0001;
+
+    [TestCase("left", null)]
+    [TestCase(null, "right")]
+    [TestCase(null, null)]
+    public void Calculate_WhenStringsAreNull_ThrowsArgumentNullException(string left, string right)
+    {
+        Action action = () => jaccard.Calculate(left, right);
+        action.Should().Throw<ArgumentNullException>();
+    }
+
+
+    [TestCase("", "", 0.0d)]
+    [TestCase("left", "", 1.0d)]
+    [TestCase("", "right", 1.0d)]
+    [TestCase("frog", "fog", 0.25d)]
+    [TestCase("fly", "ant", 1.0d)]
+    [TestCase("elephant", "hippo", 0.777777d)]
+    [TestCase("ABC Corporation", "ABC Corp", 0.36363d)]
+    public void Calculate_WhenProvidedWithStrings_CalculatesCorrectDistance(string left, string right, double expected)
+    {
+        var distance = jaccard.Calculate(left, right);
+
+        distance.Should().BeApproximately(expected, precision);
+    }
+}

Algorithms.Tests/Strings/Similarity/JaccardSimilarityTests.cs

@@ -0,0 +1,35 @@
+using System;
+using Algorithms.Strings.Similarity;
+using FluentAssertions;
+using NUnit.Framework;
+
+namespace Algorithms.Tests.Strings.Similarity;
+
+public class JaccardSimilarityTests
+{
+    private readonly JaccardSimilarity jaccard = new JaccardSimilarity();
+    private readonly double precision = 0.0001;
+
+    [TestCase("left", null)]
+    [TestCase(null, "right")]
+    [TestCase(null, null)]
+    public void Calculate_WhenStringsAreNull_ThrowsArgumentNullException(string left, string right)
+    {
+        Action action = () => jaccard.Calculate(left, right);
+        action.Should().Throw<ArgumentNullException>();
+    }
+
+    [TestCase("", "", 1.0d)]
+    [TestCase("left", "", 0.0d)]
+    [TestCase("", "right", 0.0d)]
+    [TestCase("frog", "fog", 0.75d)]
+    [TestCase("fly", "ant", 0.0d)]
+    [TestCase("elephant", "hippo", 0.22222d)]
+    [TestCase("ABC Corporation", "ABC Corp", 0.636363d)]
+    public void Calculate_WhenProvidedWithStrings_CalculatesTheCorrectDistance(string left, string right, double expected)
+    {
+        var similarity = jaccard.Calculate(left, right);
+
+        similarity.Should().BeApproximately(expected, precision);
+    }
+}

Algorithms/Strings/Similarity/JaccardDistance.cs

@@ -0,0 +1,48 @@
+namespace Algorithms.Strings.Similarity;
+
+/// <summary>
+///  <para>
+/// Jaccard distance is a measure of two sets of data are. It is calculated by subtracting the Jaccard similarity
+/// coefficient from 1, or, equivalently by dividing the difference of the sizes of the union and intersection of two sets
+/// by the size of the union.
+/// </para>
+/// <para>
+/// For example, suppose we have two sets of words:
+/// <list type="bullet">
+/// <item>
+/// A = {apple, banana, cherry, date}
+/// </item>
+/// <item>
+/// B = {banana, cherry, elderberry, fig}
+/// </item>
+/// </list>
+/// </para>
+/// <para>
+/// The number of common elements in both sets is 2 (banana and cherry). The number of elements in either set is 6
+/// (apple, banana, cherry, date, elderberry, fig).
+/// </para>
+/// <para>
+/// The Jaccard similarity coefficient is 2 / 6 = 0.333333 or 33.333% similarity.
+/// </para>
+/// <para>
+/// The Jaccard distance is 1 - 0.33333 = 0.66667. This means that the two sets are about 67% different.
+/// </para>
+/// <para>
+/// Jaccard distance is commonly used to calculate a matrix of clustering and multidimensional scaling of sample tests.
+/// </para>
+/// </summary>
+public class JaccardDistance
+{
+    private readonly JaccardSimilarity jaccardSimilarity = new();
+
+    /// <summary>
+    /// Calculate the Jaccard distance between to strings.
+    /// </summary>
+    /// <param name="left">The first string.</param>
+    /// <param name="right">The second string.</param>
+    /// <returns>The Jaccard distance.</returns>
+    public double Calculate(string left, string right)
+    {
+        return 1.0 - jaccardSimilarity.Calculate(left, right);
+    }
+}

Algorithms/Strings/Similarity/JaccardSimilarity.cs

@@ -0,0 +1,98 @@
+using System;
+using System.Collections.Generic;
+
+namespace Algorithms.Strings.Similarity;
+
+/// <summary>
+///  <para>
+/// Jaccard similarity is a statistic that measures how similar two sets of data are. It is calculated by dividing
+/// the number of common elements in both sets by the number of elements in either set. More formally, it is the
+/// quotient of the division of the size of the size of the intersection divided by the size of the union of two sets.
+/// </para>
+/// <para>
+/// The result is a value between 0 and 1, where 0 means no similarity and 1 means perfect similarity.
+/// </para>
+/// <para>
+/// For example, suppose we have two sets of words:
+/// <list type="bullet">
+/// <item>
+/// A = {apple, banana, cherry, date}
+/// </item>
+/// <item>
+/// B = {banana, cherry, elderberry, fig}
+/// </item>
+/// </list>
+/// </para>
+/// <para>
+/// The number of common elements in both sets is 2 (banana and cherry). The number of elements in either set is 6
+/// (apple, banana, cherry, date, elderberry, fig).
+/// </para>
+/// <para>
+/// The Jaccard similarity coefficient is 2 / 6 = 0.333333 or 33.333% similarity.
+/// </para>
+/// </summary>
+public class JaccardSimilarity
+{
+    /// <summary>
+    /// Calculates the Jaccard similarity coefficient between two strings.
+    /// </summary>
+    /// <param name="left">The first string to compare.</param>
+    /// <param name="right">The second string to compare.</param>
+    /// <returns>A double value between 0 and 1 that represents the similarity of the two strings.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when either the input is null.</exception>
+    /// <remarks>
+    /// This method uses a HashSet to represent the sets of characters in the input strings.
+    /// </remarks>
+    public double Calculate(string left, string right)
+    {
+        // Validate the input strings before proceeding.
+        ValidateInput(left, right);
+
+        // Get the lengths of the input strings.
+        var leftLength = left.Length;
+        var rightLength = right.Length;
+
+        // If both strings are empty, return 1.0 as the similarity coefficient.
+        if (leftLength == 0 && rightLength == 0)
+        {
+            return 1.0d;
+        }
+
+        // If either string is empty, return 0.0 as the similarity coefficient.
+        if (leftLength == 0 || rightLength == 0)
+        {
+            return 0.0d;
+        }
+
+        // Get the unique characters in each string.
+        var leftSet = new HashSet<char>(left);
+        var rightSet = new HashSet<char>(right);
+
+        // Get the union of the two strings.
+        var unionSet = new HashSet<char>(leftSet);
+        foreach (var c in rightSet)
+        {
+            unionSet.Add(c);
+        }
+
+        // Calculate the intersection size of the two strings.
+        var intersectionSize = leftSet.Count + rightSet.Count - unionSet.Count;
+
+        // Return the Jaccard similarity coefficient as the ratio of intersection to union.
+        return 1.0d * intersectionSize / unionSet.Count;
+    }
+
+    /// <summary>
+    /// Validates the input strings and throws an exception if either is null.
+    /// </summary>
+    /// <param name="left">The first string to validate.</param>
+    /// <param name="right">The second string to validate.</param>
+    private void ValidateInput(string left, string right)
+    {
+        if (left == null || right == null)
+        {
+            var paramName = left == null ? nameof(left) : nameof(right);
+            throw new ArgumentNullException(paramName, "Input cannot be null");
+        }
+    }
+}

README.md

@@ -178,6 +178,9 @@ find more than one implementation for the same objective but using different alg
     * [A019434 Fermat Primes](./Algorithms/Sequences/FermatPrimesSequence.cs)
     * [A181391 Van Eck's](./Algorithms/Sequences/VanEcksSequence.cs)
   * [String](./Algorithms/Strings)
+    * [Similarity](./Algorithms/Strings/Similarity/)
+      * [Jaccard Similarity](./Algorithms/Strings/Similarity/JaccardSimilarity.cs)
+      * [Jaccard Distance](./Algorithms/Strings/Similarity/JaccardDistance.cs)
     * [Longest Consecutive Character](./Algorithms/Strings/GeneralStringAlgorithms.cs)
     * [Naive String Search](./Algorithms/Strings/NaiveStringSearch.cs)
     * [Rabin Karp](./Algorithms/Strings/RabinKarp.cs)