Skip to content

Commit 999d73b

Browse files
kernelmethodkernelmethod
committed
Place API reference onto its own page.
Squashed commit of the following: commit ab0b60f Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com> Date: Fri Jan 17 20:32:00 2020 -0700 Export wasserstein*_1d from the module so that it's recorded in the similarity function API reference. commit 9703d6f Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com> Date: Fri Jan 17 20:28:20 2020 -0700 Add documentation for LSHBase.jl. commit 4ef713c Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com> Date: Fri Jan 17 19:41:47 2020 -0700 Move API reference out of similarity function pages. commit 08855b5 Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com> Date: Fri Jan 17 19:41:28 2020 -0700 Add abstract L1Hash and L2Hash types so that lsh_family(ℓ1) and lsh_family(ℓ2) can return concrete types. This also makes it easier to refer to the hash functions in the documentation. commit 8205c41 Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com> Date: Fri Jan 17 19:31:39 2020 -0700 Move API reference to a separate page. commit d993bc0 Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com> Date: Fri Jan 17 19:00:18 2020 -0700 Rename the docstring subsections of each similarity function's page to 'API reference'. commit 12b9b73 Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com> Date: Fri Jan 17 18:58:04 2020 -0700 Add 'under construction' notices to the pages for each of the similarity functions. commit d88cd77 Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com> Date: Fri Jan 17 18:55:46 2020 -0700 Improve formatting of the available similarities listed in the docstrings for LSHFunction and similarity(). commit de278d6 Author: kernelmethod <17100608+kernelmethod@users.noreply.github.com> Date: Fri Jan 17 18:50:42 2020 -0700 Fix missing docstrings for LSHFunction() and similarity().
1 parent cc257b0 commit 999d73b

File tree

12 files changed

+176
-110
lines changed

12 files changed

+176
-110
lines changed

‎docs/make.jl

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ makedocs(
1919
"Jaccard similarity" => joinpath("similarities", "jaccard.md"),
2020
"Inner product similarity" => joinpath("similarities", "inner_prod.md")],
2121
"Performance tips" => "performance.md",
22+
"API reference" => "full_api.md",
2223
]
2324
)
2425

‎docs/src/full_api.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# API reference
2+
3+
## LSHFunction API
4+
5+
```@docs
6+
LSHFunction
7+
lsh_family
8+
hashtype
9+
n_hashes
10+
similarity
11+
index_hash
12+
query_hash
13+
SymmetricLSHFunction
14+
AsymmetricLSHFunction
15+
```
16+
17+
## Hash functions
18+
19+
```@docs
20+
SimHash
21+
MinHash
22+
L1Hash
23+
L2Hash
24+
SignALSH
25+
MIPSHash
26+
```
27+
28+
## Similarity functions
29+
30+
```@autodocs
31+
Modules = [LSH]
32+
Private = false
33+
Pages = ["similarities.jl"]
34+
```
35+
36+
## Private interface
37+
38+
```@autodocs
39+
Modules = [LSH]
40+
Public = false
41+
```

‎docs/src/lshfunction_api.md

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,3 @@
22

33
!!! warning "Under construction"
44
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/LSH.jl/pulls); otherwise, please check back later.
5-
6-
## API reference
7-
8-
```@docs
9-
LSHFunction
10-
lsh_family
11-
```

‎docs/src/similarities/cosine.md

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,5 @@
11
# Cosine similarity
22

3-
## SimHash
3+
!!! warning "Under construction"
4+
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/LSH.jl/pulls); otherwise, please check back later.
45

5-
```@docs
6-
SimHash
7-
```
8-
9-
## Utilities
10-
11-
```@docs
12-
cossim
13-
```

‎docs/src/similarities/inner_prod.md

Lines changed: 2 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,4 @@
11
# Inner product similarity
22

3-
## SignALSH
4-
5-
```@docs
6-
SignALSH
7-
```
8-
9-
## MIPSHash
10-
11-
```@docs
12-
MIPSHash
13-
```
14-
15-
## Utilities
16-
17-
```@docs
18-
inner_prod(::AbstractVector, ::AbstractVector)
19-
```
3+
!!! warning "Under construction"
4+
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/LSH.jl/pulls); otherwise, please check back later.

‎docs/src/similarities/jaccard.md

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,4 @@
11
# Jaccard similarity
22

3-
## MinHash
4-
5-
```@docs
6-
MinHash
7-
```
8-
9-
## Utilities
10-
11-
```@docs
12-
jaccard
13-
```
3+
!!! warning "Under construction"
4+
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/LSH.jl/pulls); otherwise, please check back later.

‎docs/src/similarities/lp_distance.md

Lines changed: 2 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,4 @@
11
# ``\ell^p`` distance
22

3-
## L1Hash and L2Hash
4-
5-
```@docs
6-
L1Hash
7-
L2Hash
8-
```
9-
10-
## Utility functions
11-
12-
```@docs
13-
ℓp
14-
ℓp_norm
15-
Lp(::AbstractVector{T}, ::AbstractVector, ::Real) where T
16-
Lp_norm(::AbstractVector, ::Real)
17-
```
3+
!!! warning "Under construction"
4+
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/LSH.jl/pulls); otherwise, please check back later.

‎src/LSH.jl

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,13 @@ Hash tables for LSHFunctions
4545

4646
# Similarity functions, norms, inner products
4747
export cossim, inner_prod, ℓ1, ℓ2, ℓp, L1, L2, Lp, ℓ1_norm, ℓ2_norm,
48-
ℓp_norm, L1_norm, L2_norm, Lp_norm, jaccard
48+
ℓp_norm, L1_norm, L2_norm, Lp_norm, jaccard, wasserstein_1d,
49+
wasserstein1_1d, wasserstein2_1d
4950

5051
# Hash functions
5152
export SimHash, L1Hash, L2Hash, MIPSHash, SignALSH, MinHash,
52-
LSHFunction, MonteCarloHash, ChebHash
53+
LSHFunction, MonteCarloHash, ChebHash, SymmetricLSHFunction,
54+
AsymmetricLSHFunction
5355

5456
# Helper / utility functions for LSHFunctions
5557
export index_hash, query_hash, n_hashes, hashtype, similarity, lsh_family,

‎src/LSHBase.jl

Lines changed: 111 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,23 @@ Abstract typedefs
2222
========================#
2323

2424
abstract type LSHFunction end
25+
26+
@doc """
27+
abstract type SymmetricLSHFunction <: LSHFunction end
28+
29+
A symmetric locality-sensitive hashing function. A `SymmetricLSHFunction` uses the same hash function to insert items into a hash table as well as query the table for collisions. If `hashfn` is a `SymmetricLSHFunction`, you can compute the hash for an input `x` as `hashfn(x)`.
30+
31+
See also: [`AsymmetricLSHFunction`](@ref)
32+
"""
2533
abstract type SymmetricLSHFunction <: LSHFunction end
34+
35+
@doc """
36+
abstract type AsymmetricLSHFunction <: LSHFunction end
37+
38+
An asymmetric locality-sensitive hashing function. An `AsymmetricLSHFunction` uses one hash function to insert items into a hash table, and a different hash function to query the table for collisions. If `hashfn` is an `AsymmetricLSHFunction`, you can compute the indexing hash for an input `x` with `index_hash(hashfn,x)`, and the querying hash with `query_hash(hashfn,x)`.
39+
40+
See also: [`SymmetricLSHFunction`](@ref)
41+
"""
2642
abstract type AsymmetricLSHFunction <: LSHFunction end
2743

2844
#========================
@@ -44,21 +60,96 @@ function lsh_family end
4460
#=
4561
The following functions must be defined for all LSHFunction subtypes
4662
=#
63+
64+
@doc """
65+
similarity(hashfn::LSHFunction)
66+
67+
Returns the similarity function that `hashfn` hashes on.
68+
69+
# Arguments
70+
- `hashfn::AbstractLSHFunction`: the hash function whose similarity we would like to retrieve.
71+
72+
# Examples
73+
```jldoctest; setup = :(using LSH)
74+
julia> hashfn = LSHFunction(cossim);
75+
76+
julia> similarity(hashfn) == cossim
77+
true
78+
79+
julia> hashfn = LSHFunction(ℓ1);
80+
81+
julia> similarity(hashfn) == ℓ1
82+
true
83+
```
84+
"""
85+
function similarity end
86+
87+
@doc """
88+
hashtype(hashfn::LSHFunction)
89+
90+
Returns the type of hash generated by a hash function.
91+
92+
# Examples
93+
```jldoctest; setup = :(using LSH)
94+
julia> hashfn = LSHFunction(cossim);
95+
96+
julia> hashtype(hashfn)
97+
Bool
98+
99+
julia> hashfn = LSHFunction(ℓ1);
100+
101+
julia> hashtype(hashfn)
102+
Int32
103+
```
104+
"""
47105
function hashtype end
106+
107+
@doc """
108+
n_hashes(hashfn::LSHFunction)
109+
110+
Return the number of hashes computed by `hashfn`.
111+
112+
# Examples
113+
```jldoctest; setup = :(using LSH)
114+
julia> hashfn = SimHash();
115+
116+
julia> n_hashes(hashfn)
117+
$(DEFAULT_N_HASHES)
118+
119+
julia> hashfn = SimHash(12);
120+
121+
julia> n_hashes(hashfn)
122+
12
123+
```
124+
"""
48125
function n_hashes end
49-
function similarity end
50126

51127
#========================
52128
SymmetricLSHFunction API
53129
========================#
54130

55-
index_hash(h :: SymmetricLSHFunction, x) = h(x)
56-
query_hash(h :: SymmetricLSHFunction, x) = h(x)
131+
@doc """
132+
index_hash(hashfn::SymmetricLSHFunction, x)
133+
134+
Identical to calling `hashfn(x)`.
135+
136+
See also: [`query_hash`](@ref), [`SymmetricLSHFunction`](@ref)
137+
"""
138+
index_hash(hashfn::SymmetricLSHFunction, x) = hashfn(x)
139+
140+
@doc """
141+
query_hash(hashfn::SymmetricLSHFunction, x)
142+
143+
Identical to calling `hashfn(x)`.
144+
145+
See also: [`index_hash`](@ref), [`SymmetricLSHFunction`](@ref)
146+
"""
147+
query_hash(hashfn::SymmetricLSHFunction, x) = hashfn(x)
57148

58149
#=
59150
The following functions must be defined for all SymmetricLSHFunction subtypes
60151
=#
61-
function (:: SymmetricLSHFunction) end
152+
function (::SymmetricLSHFunction) end
62153

63154
#========================
64155
Abstract typedefs
@@ -67,7 +158,23 @@ Abstract typedefs
67158
#=
68159
The following functions must be defined for all AsymmetricLSHFunction subtypes
69160
=#
161+
162+
@doc """
163+
index_hash(hashfn::AsymmetricLSHFunction, x)
164+
165+
Computes the indexing hash (the hash used to insert items into the hash table) for an `AsymmetricLSHFunction` with input `x`.
166+
167+
See also: [`query_hash`](@ref), [`AsymmetricLSHFunction`](@ref)
168+
"""
70169
function index_hash end
170+
171+
@doc """
172+
query_hash(hashfn::AsymmetricLSHFunction, x)
173+
174+
Computes the querying hash (the hash used to query for items in the hash table) for an `AsymmetricLSHFunction` with input `x`.
175+
176+
See also: [`index_hash`](@ref), [`AsymmetricLSHFunction`](@ref)
177+
"""
71178
function query_hash end
72179

73180
#========================

‎src/hashes/lphash.jl

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,9 @@ mutable struct LpHash{T <: Union{Float32,Float64}, D} <: SymmetricLSHFunction
5050
resize_pow2 :: Bool
5151
end
5252

53+
abstract type L1Hash <: SymmetricLSHFunction end
54+
abstract type L2Hash <: SymmetricLSHFunction end
55+
5356
### External LpHash constructors
5457

5558
function LpHash{T}(n_hashes::Integer = DEFAULT_N_HASHES;

0 commit comments

Comments
 (0)