Update docs.

Author: kernelmethod

docs/src/lshfunction_api.md

@@ -4,7 +4,7 @@
     This section is currently being developed. If you're interested in helping write this section, feel free to [open a pull request](https://github.com/kernelmethod/LSHFunctions.jl/pulls); otherwise, please check back later.
 
 ## LSHFunction
-The `LSH` module exposes a relatively easy interface for constructing new hash functions. Namely, you call [`LSHFunction`](@ref) with 
+The `LSHFunctions` module exposes a relatively easy interface for constructing new hash functions. Namely, you call [`LSHFunction`](@ref) with 
 
 - the similarity function you want to use;
 - the number of hash functions you want to generate; and
@@ -77,48 +77,48 @@ LSHFunctions.jl provides a few common utility functions that you can use across
 
 - [`n_hashes`](@ref): returns the number of hash functions computed by an [`LSHFunction`](@ref).
 
-```jldoctest; setup = :(using LSHFunctions)
-julia> hashfn = LSHFunction(jaccard);
+  ```jldoctest; setup = :(using LSHFunctions)
+  julia> hashfn = LSHFunction(jaccard);
 
-julia> n_hashes(hashfn)
-1
+  julia> n_hashes(hashfn)
+  1
 
-julia> hashfn = LSHFunction(jaccard, 10);
+  julia> hashfn = LSHFunction(jaccard, 10);
 
-julia> n_hashes(hashfn)
-10
+  julia> n_hashes(hashfn)
+  10
 
-julia> hashes = hashfn(randn(50));
+  julia> hashes = hashfn(randn(50));
 
-julia> length(hashes)
-10
-```
+  julia> length(hashes)
+  10
+  ```
 
 - [`similarity`](@ref): returns the similarity function for which the input [`LSHFunction`](@ref) is locality-sensitive:
 
-```jldoctest; setup = :(using LSHFunctions)
-julia> hashfn = LSHFunction(cossim);
+  ```jldoctest; setup = :(using LSHFunctions)
+  julia> hashfn = LSHFunction(cossim);
 
-julia> similarity(hashfn)
-cossim (generic function with 2 methods)
-```
+  julia> similarity(hashfn)
+  cossim (generic function with 2 methods)
+  ```
 
 - [`hashtype`](@ref): returns the type of hash computed by the input hash function. Note that in practice `hashfn(x)` (or [`index_hash(hashfn,x)`](@ref) and [`query_hash(hashfn,x)`](@ref) for an [`AsymmetricLSHFunction`](@ref)) will return an array of hashes, one for each hash function you generated. [`hashtype`](@ref) is the data type of each element of `hashfn(x)`.
 
-```jldoctest; setup = :(using LSHFunctions)
-julia> hashfn = LSHFunction(cossim, 5);
+  ```jldoctest; setup = :(using LSHFunctions)
+  julia> hashfn = LSHFunction(cossim, 5);
 
-julia> hashtype(hashfn)
-Bool
+  julia> hashtype(hashfn)
+  Bool
 
-julia> hashes = hashfn(rand(100));
+  julia> hashes = hashfn(rand(100));
 
-julia> typeof(hashes)
-BitArray{1}
+  julia> typeof(hashes)
+  BitArray{1}
 
-julia> typeof(hashes[1]) == hashtype(hashfn)
-true
-```
+  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):
 

docs/src/similarities/jaccard.md

@@ -2,3 +2,74 @@
 
 !!! warning "Under construction"
     This section is currently being developed. If you're interested in helping write this section, feel free to [open a pull request](https://github.com/kernelmethod/LSHFunctions.jl/pulls); otherwise, please check back later.
+
+## Definition
+*Jaccard similarity* is a statistic that measures the amount of overlap between two sets. It is defined as
+
+```math
+J(A,B) = \frac{|A \cap B|}{|A \cup B|}
+```
+
+``J(A,B)`` is bounded by ``0 \le J(A,B) \le 1``, with values close to 1 indicating high similarity and values close to 0 indicating low similarity.
+
+You can calculate Jaccard similarity with the LSHFunctions package by calling [`jaccard`](@ref):
+
+```jldoctest
+julia> using LSHFunctions;
+
+julia> A = Set([1, 2, 3]); B = Set([2, 3, 4]);
+
+julia> jaccard(A,B) ==
+       length(A ∩ B) / length(A ∪ B) ==
+       0.5
+true
+```
+
+## MinHash
+*MinHash*[^Broder97] is a hash function for Jaccard similarity. It takes as input a set, and returns as output a `UInt32` or a `UInt64`. To sample a function from the MinHash LSH family, simply call [`MinHash`](@ref) with the number of hash functions you want to generate:
+
+```jldoctest; setup = :(using LSHFunctions, Random; Random.seed!(0))
+julia> hashfn = MinHash(5);
+
+julia> n_hashes(hashfn)
+5
+
+julia> hashtype(hashfn)
+UInt64
+
+julia> A = Set([1, 2, 3]);
+
+julia> hashfn(A)
+5-element Array{UInt64,1}:
+ 0x21be0e591a3b69ea
+ 0x19c5f638a776ab3c
+ 0x63c12fd5d2f073ab
+ 0x5c6b11e538a36352
+ 0x129ef927e80a1b39
+```
+
+The probability of a collision for an individual hash between sets ``A`` and ``B`` is just equal to their Jaccard similarity, i.e.
+
+```math
+Pr[h(A) = h(B)] = J(A,B)
+```
+
+```@eval
+using PyPlot, LSHFunctions;
+fig = figure();
+hashfn = MinHash();
+x = range(0, 1; length=1024);
+y = collision_probability(hashfn, x; n_hashes=1);
+
+plot(x, y)
+title("Probability of hash collision for MinHash")
+xlabel(raw"$J(A,B)$")
+ylabel(raw"$Pr[h(x) = h(y)]$")
+
+savefig("minhash_collision_probability.svg")
+```
+
+![Probability of collision for MinHash](minhash_collision_probability.svg)
+
+## Footnotes
+[^Broder97]: Broder, A. *On the resemblance and containment of documents*. Compression and Complexity of Sequences: Proceedings, Positano, Amalfitan Coast, Salerno, Italy, June 11-13, 1997. doi:10.1109/SEQUEN.1997.666900.