Add collision_probability to the LSHFunction API, and add documentation for it. We now use this function in place of single_hash_collision_probability in order to compute the probability of a collision between a pair of inputs, as well as to compute the probability that multiple inputs simultaneously collide. This fixes issue #6.

Author: kernelmethod

docs/src/full_api.md

@@ -8,6 +8,7 @@ lsh_family
 hashtype
 n_hashes
 similarity
+collision_probability
 index_hash
 query_hash
 SymmetricLSHFunction

docs/src/lshfunction_api.md

@@ -120,4 +120,40 @@ julia> typeof(hashes[1]) == hashtype(hashfn)
 true
 ```
 
+- [`collision_probability`](@ref): returns the probability of collision for two inputs with a given similarity. For instance, the probability that a single MinHash hash function causes a collision between inputs `A` and `B` is equal to [`jaccard(A,B)`](@ref jaccard):
+
+  ```jldoctest; setup = :(using LSH)
+  julia> hashfn = MinHash();
+
+  julia> A = Set(["a", "b", "c"]);
+
+  julia> B = Set(["b", "c", "d"]);
+
+  julia> collision_probability(hashfn, A, B) ==
+         collision_probability(hashfn, jaccard(A,B)) ==
+         jaccard(A,B)
+  true
+  ```
+
+  We often want to compute the probability that not just one hash collides, but that multiple hashes collide simultaneously. You can calculate this using the `n_hashes` keyword argument. If left unspecified, then [`collision_probability`](@ref) will use [`n_hashes(hashfn)`](@ref n_hashes) hash functions to compute the probability.
+
+  ```jldoctest; setup = :(using LSH)
+  julia> hashfn = MinHash(5);
+
+  julia> A = Set(["a", "b", "c"]);
+
+  julia> B = Set(["b", "c", "d"]);
+
+  julia> collision_probability(hashfn, A, B) ==
+         collision_probability(hashfn, A, B; n_hashes=5) ==
+         collision_probability(hashfn, A, B; n_hashes=1)^5
+  true
+
+  julia> sim = jaccard(A,B);
+
+  julia> collision_probability(hashfn, sim) ==
+         collision_probability(hashfn, sim; n_hashes=5) ==
+         collision_probability(hashfn, sim; n_hashes=1)^5
+  true
+  ```
 

src/LSH.jl

@@ -48,6 +48,6 @@ export SimHash, L1Hash, L2Hash, MIPSHash, SignALSH, MinHash,
 
 # Helper / utility functions for LSHFunctions
 export index_hash, query_hash, n_hashes, hashtype, similarity, lsh_family,
-       embedded_similarity
+       embedded_similarity, collision_probability
 
 end # module

src/LSHBase.jl

@@ -57,6 +57,136 @@ macro register_similarity! end
 function LSHFunction end
 function lsh_family end
 
+@doc """
+    collision_probability(hashfn::H, sim;
+                          n_hashes::Union{Symbol,Integer}=:auto) where {H <: LSHFunction}
+
+Compute the probability of hash collision between two inputs with similarity `sim` for an [`LSHFunction`](@ref) of type `H`. This function returns the probability that `n_hashes` hashes simultaneously collide.
+
+# Arguments
+- `hashfn::LSHFunction`: the `LSHFunction` for which we want to compute the probability of collision.
+- `sim`: a similarity (or vector of similarities), computed using the similarity function returned by `similarity(hashfn)`.
+
+# Keyword arguments
+- `n_hashes::Union{Symbol,Integer}` (default: `:auto`): the number of hash functions to use to compute the probability of collision. If the probability that a single hash collides is ``p``, then the probability that `n_hashes` hashes simultaneously collide is
+
+  ```math
+  p^{\\text{n_hashes}}
+  ```
+
+  As a result, `collision_probability(hashfn, sim; n_hashes=N)` is the same as `collision_probability(hashfn, sim; n_hashes=1).^N`. If `n_hashes = :auto` then this function will select the number of hashes to be `n_hashes(hashfn)` (using the [`n_hashes`](@ref) function from the [`LSHFunction`](@ref) API).
+
+# Examples
+The probability that a single MinHash hash function causes a hash collision between inputs `A` and `B` is equal to `jaccard(A,B)`:
+
+```jldoctest; setup = :(using LSH)
+julia> hashfn = MinHash();
+
+julia> A = Set(["a", "b", "c"]);
+
+julia> B = Set(["b", "c", "d"]);
+
+julia> jaccard(A,B)
+0.5
+
+julia> collision_probability(hashfn, jaccard(A,B); n_hashes=1)
+0.5
+```
+
+If our [`MinHash`](@ref) struct keeps track of `N` hash functions simultaneously, then the probability of collision is `jaccard(A,B)^N`:
+
+```jldoctest; setup = :(using LSH)
+julia> hashfn = MinHash(10);
+
+julia> A = Set(["a", "b", "c"]);
+
+julia> B = Set(["b", "c", "d"]);
+
+julia> collision_probability(hashfn, jaccard(A,B)) ==
+       collision_probability(hashfn, jaccard(A,B); n_hashes=10) ==
+       collision_probability(hashfn, jaccard(A,B); n_hashes=1)^10
+true
+```
+
+See also: [`n_hashes`](@ref), [`similarity`](@ref)
+"""
+@generated function collision_probability(hashfn::LSHFunction, sim;
+                                          n_hashes::Union{Symbol,Integer} = :auto)
+
+    error_msg = :("n_hashes must be :auto or a positive Integer" |>
+                  ErrorException |>
+                  throw)
+
+    n_hashes = begin
+        if n_hashes <: Symbol
+            quote
+                if n_hashes != :auto
+                    $error_msg
+                end
+
+                n_hashes = _n_hashes(hashfn)
+            end
+        else
+            quote
+                if n_hashes ≤ 0
+                    $error_msg
+                end
+                nh = n_hashes
+            end
+        end
+    end
+
+    quote
+        $n_hashes
+        single_hash_collision_probability(hashfn, sim).^n_hashes
+    end
+end
+
+@doc """
+    collision_probability(hashfn::LSHFunction, x, y;
+                          n_hashes::Union{Symbol,Integer} = :auto)
+
+Computes the probability of a hash collision between two inputs `x` and `y` for a given hash function `hashfn`. This is the same as calling
+
+    collision_probability(hashfn, similarity(hashfn)(x,y); n_hashes=n_hashes)
+
+# Examples
+The following snippet computes the probability of collision between two sets `A` and `B` for a single MinHash. For MinHash, this probability is just equal to the Jaccard similarity between `A` and `B`.
+
+```jldoctest; setup = :(using LSH)
+julia> hashfn = MinHash();
+
+julia> A = Set(["a", "b", "c"]);
+
+julia> B = Set(["a", "b", "c"]);
+
+julia> similarity(hashfn) == jaccard
+true
+
+julia> collision_probability(hashfn, A, B) ==
+       collision_probability(hashfn, jaccard(A,B)) ==
+       jaccard(A,B)
+true
+```
+
+We can use the `n_hashes` argument to specify the probability that `n_hashes` MinHash hash functions simultaneously collide. If left unspecified, then we'll simply use `n_hashes(hashfn)` as the number of hash functions:
+
+```jldoctest; setup = :(using LSH)
+julia> hashfn = MinHash(10);
+
+julia> A = Set(["a", "b", "c"]);
+
+julia> B = Set(["a", "b", "c"]);
+
+julia> collision_probability(hashfn, A, B) ==
+       collision_probability(hashfn, A, B; n_hashes=10) ==
+       collision_probability(hashfn, A, B; n_hashes=1)^10
+true
+```
+"""
+collision_probability(hashfn::LSHFunction, A, B; kws...) =
+    collision_probability(hashfn, similarity(hashfn)(A,B); kws...)
+
 #=
 The following functions must be defined for all LSHFunction subtypes
 =#
@@ -129,6 +259,19 @@ julia> length(hashes)
 """
 function n_hashes end
 
+# Alias for n_hashes that's occasionally useful when we need to process
+# variables that are named n_hashes
+const _n_hashes = n_hashes
+
+# The function
+#
+#       single_hash_collision_probability(hashfn::H, sim)
+#
+# must be implemented for every subtype H of LSHFunction. Note that users don't
+# access this function directly; instead, they use the collision_probability
+# function exported by the LSH API.
+function single_hash_collision_probability end
+
 #========================
 SymmetricLSHFunction API
 ========================#

src/function_hashing/chebhash.jl

@@ -83,8 +83,8 @@ hashtype(hashfn::ChebHash) =
     hashtype(hashfn.discrete_hashfn)
 
 # TODO: this may not be true
-single_hash_collision_probability(hashfn::ChebHash, args...; kws...) =
-    single_hash_collision_probability(hashfn.discrete_hashfn, args...; kws...)
+collision_probability(hashfn::ChebHash, args...; kws...) =
+    collision_probability(hashfn.discrete_hashfn, args...; kws...)
 
 #===============
 Hash computation

src/function_hashing/monte_carlo.jl

@@ -82,8 +82,8 @@ n_hashes(hashfn::MonteCarloHash) =
     n_hashes(hashfn.discrete_hashfn)
 
 # TODO: this may not be true
-single_hash_collision_probability(hashfn::MonteCarloHash, args...; kws...) =
-    single_hash_collision_probability(hashfn.discrete_hashfn, args...; kws...)
+collision_probability(hashfn::MonteCarloHash, args...; kws...) =
+    collision_probability(hashfn.discrete_hashfn, args...; kws...)
 
 #========================
 SymmetricLSHFunction API compliance

src/hashes/lphash.jl

@@ -183,18 +183,20 @@ LSHFunction and SymmetricLSHFunction API compliance
 n_hashes(h::LpHash) = length(h.shift)
 hashtype(::LpHash) = Int32
 
-# See Section 3.2 of the reference
+# See Section 3.2 of the reference paper
 function single_hash_collision_probability(hashfn::LpHash, sim::Real)
+    ### Compute the collision probability for a single hash function
     distr, r = hashfn.distr, hashfn.r
-    integral, err = quadgk(x -> pdf(distr, x/sim) * (1 - x/r), 0, r, rtol=1e-5)
-    integral /= sim
+    integral, err = quadgk(x -> pdf(distr, x/sim) * (1 - x/r),
+                           0, r, rtol=1e-5)
+    integral = integral ./ sim
 
     # Note that from the reference for the L^p LSH family, we're supposed to
-    # integrate over the p.d.f. for the _absolute value_ of the underlying random
-    # variable, rather than the raw p.d.f.. Luckily, all of the distributions we
-    # have to deal with here are symmetric and centered at zero, so all we have
-    # to do is multiply the integral by two.
-    integral *= 2
+    # integrate over the p.d.f. for the _absolute value_ of the underlying
+    # random variable, rather than the raw p.d.f. Luckily, all of the
+    # distributions we have to deal with here are symmetric and centered at
+    # zero, so all we have to do is multiply the integral by two.
+    single_hash_prob = integral .* 2
 end
 
 function similarity(hashfn::LpHash)

src/hashes/simhash.jl

@@ -117,7 +117,8 @@ LSHFunction and SymmetricLSHFunction API compliance
 hashtype(::SimHash) = Bool
 n_hashes(hashfn::SimHash) = size(hashfn.coeff, 2)
 similarity(::SimHash) = cossim
-single_hash_collision_probability(::SimHash, sim::Real) = (1 - acos(sim) / π)
+single_hash_collision_probability(::SimHash, sim::Real) =
+    @. (1 - acos(sim) / π)
 
 ### Hash computation
 

src/similarities.jl

@@ -395,8 +395,8 @@ Compute the order-``p`` Wasserstein distance between two probability distributio
 - `p::Real`: the order of Wasserstein distance to compute.
 """
 function wasserstein_1d(f, g, p::Real)
-    # For one-dimensional probability distributions, the Wasserstein distance has the
-    # closed form
+    # For one-dimensional probability distributions, the Wasserstein distance has
+    # the closed form
     #
     #       ∫_0^1 |F^{-1}(x) - G^{-1}(x)|^p dx
     #

test/function_hashing/test_chebhash.jl

@@ -72,7 +72,7 @@ Tests
 
             sim = cossim(f, g, interval)
             hf, hg = hashfn(f), hashfn(g)
-            prob = LSH.single_hash_collision_probability(hashfn, sim)
+            prob = collision_probability(hashfn, sim; n_hashes=1)
 
             prob - 0.05 ≤ mean(hf .== hg) ≤ prob + 0.05
         end
@@ -123,7 +123,7 @@ Tests
 
             sim = L2(f, g, interval)
             hf, hg = hashfn(f), hashfn(g)
-            prob = LSH.single_hash_collision_probability(hashfn, sim)
+            prob = collision_probability(hashfn, sim; n_hashes=1)
 
             prob - 0.05 ≤ mean(hf .== hg) ≤ prob + 0.05
         end