Merge pull request #16 from dillondaudert/v0.3.0-dev

V0.3.0

Author: dillondaudert

.appveyor.yml

@@ -1,6 +1,6 @@
 environment:
   matrix:
-  - julia_version: 1
+  - julia_version: 1.3
   - julia_version: nightly
 
 platform:

.gitignore

@@ -5,3 +5,5 @@ deps/deps.jl
 Manifest.toml
 
 .ipynb_checkpoints
+*.swp
+docs/build/

.travis.yml

@@ -1,19 +1,32 @@
 language: julia
-os: 
+notifications:
+  email: false
+os:
   - linux
   - osx
-
+  - windows
+before_script:
+  - git config --global user.name Tester
+  - git config --global user.email te@st.er
 julia:
-  - 1.0
-  - 1.2
+  - 1.3
   - nightly
-
-script: 
-  - julia -e 'import Pkg; Pkg.build(); Pkg.test(; coverage=true)'
-
+script: travis_wait julia --project -e 'using Pkg; Pkg.test(; coverage=true)'
+matrix:
+  fast_finish: true
+  allow_failures:
+    - julia: nightly
 codecov: true
 coveralls: true
-
 after_success:
   - julia -e 'import Pkg; Pkg.add("Coverage"); using Coverage; Codecov.submit(process_folder())'
   - julia -e 'import Pkg; Pkg.add("Coverage"); using Coverage; Coveralls.submit(process_folder())'
+
+jobs:
+  include:
+    - stage: "Documentation"
+      julia: 1.3
+      os: linux
+      script:
+        - julia --project=docs/ docs/make.jl
+      after_success: skip

Project.toml

@@ -1,21 +1,26 @@
 name = "NearestNeighborDescent"
 uuid = "dd2c4c9e-a32f-5b2f-b342-08c2f244fce8"
 authors = ["Dillon Daudert <dillongdaudert@gmail.com>"]
-version = "0.2.1"
+version = "0.3.0"
 
 [deps]
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"
+LightGraphs = "093fc24a-ae57-5d10-9952-331d41423f4d"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 
 [compat]
-
-Distances = "0.8"
 DataStructures = "0.15, 0.17"
-julia = "1.0"
+Distances = "0.8"
+LightGraphs = "1.3"
+Reexport = "0.2"
+julia = "1.3"
 
 [extras]
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test"]
+test = ["Test", "Statistics"]

README.md

@@ -1,7 +1,8 @@
 # NearestNeighborDescent.jl
 
-[![Build Status](https://travis-ci.com/dillondaudert/NearestNeighborDescent.jl.svg?branch=master)](https://travis-ci.com/dillondaudert/NearestNeighborDescent.jl) [![Build status](https://ci.appveyor.com/api/projects/status/lr49p9vxkr8a3uv0?svg=true)](https://ci.appveyor.com/project/dillondaudert/nearestneighbordescent-jl)
- [![codecov](https://codecov.io/gh/dillondaudert/NearestNeighborDescent.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/dillondaudert/NearestNeighborDescent.jl) [![Coverage Status](https://coveralls.io/repos/github/dillondaudert/NearestNeighborDescent.jl/badge.svg?branch=master)](https://coveralls.io/github/dillondaudert/NearestNeighborDescent.jl?branch=master)
+| **Documentation** | **Build Status** |
+|:-----------------:|:----------------:|
+| [![][docs-stable-img]][docs-stable-url] [![][docs-dev-img]][docs-dev-url] | [![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] [![][codecov-img]][codecov-url] [![][coveralls-img]][coveralls-url] |
 
 A Julia implementation of Nearest Neighbor Descent.
 
@@ -20,67 +21,54 @@ NNDescent is based on the heuristic argument that *a neighbor of a neighbor is a
 given a list of approximate nearest neighbors to a point, we can improve that list by exploring the neighbors of each
 point in the list. The algorithm is in essence the repeated application of this principle.
 
-
-## Usage
-The `DescentGraph` constructor builds the approximate kNN graph:
-```jl
-DescentGraph(data, n_neighbors, metric; max_iters, sample_rate, precision)
+## Installation
+```julia
+]add NearestNeighborDescent
 ```
-- `data`: The set of points to build the tree from. This must be of type
-`Vector{V}`, where `V <: AbstractVector` **or** `AbstractMatrix`.
-- `n_neighbors`: An integer specifies the number of neighbors to find
-- `metric`: Any metric `M` where `M <: SemiMetric` from the Distances.jl package. Default is `Euclidean()`.
-
-The performance of NN Descent can be tuned with several keyword arguments.
-- `max_iters`: This controls the maximum number of iterations to search for
-neighbors. Default is `10`.
-- `sample_rate`: The algorithm performs a local join around the candidate
-neighbors of each point during execution. The sample rate is the likelihood
-that each candidate be included in the local join for an iteration. Default is
-`1.`.
-- `precision`: This argument roughly corresponds to the fraction of true
-nearest neighbors that will be missed by the algorithm. Default `.001`.
-
-The k-nearest neighbors can be accessed through the `indices` and `distances`
-attributes. These are both `KxN` matrices containing ids and distances to each
-point's neighbors, respectively, where `K = n_neighbors` and `N = length(data)`.
-
-Example:
-```jl
-using NearestNeighborDescent
-data = [rand(10) for _ in 1:1000]
-# OR data = rand(10, 1000)
-n_neighbors = 5
 
-# nn descent search
-graph = DescentGraph(data, n_neighbors)
+## Basic Usage
+
+Approximate kNN graph construction on a dataset:
 
-# access point i's jth nearest neighbor:
-graph.indices[j, i]
-graph.distances[j, i]
+```julia
+using NearestNeighborDescent
+using Distances
+data = [rand(20) for _ in 1:1000]
+n_neighbors = 10
+metric = Euclidean()
+graph = nndescent(data, n_neighbors, metric)
 ```
 
-Once constructed, the `DescentGraph` can be used to find the nearest
-neighbors to new points. This is done via the `search` method:
-```jl
-search(graph, queries, n_neighbors, queue_size) -> indices, distances
+The approximate KNNs of the original dataset can be retrieved from the resulting graph with
+```julia
+# return the approximate knns as KxN matrices of indexes and distances, where
+# indices[j, i] and distances[j, i] are the index of and distance to node i's jth
+# nearest neighbor, respectively.
+indices, distances = knn_matrices(graph)
 ```
-- `graph`: An instance of `DescentGraph`
-- `queries`: A vector of new data points of type `Vector{V}` or `AbstractMatrix`. 
-Note that the dimensionality of the queries should match that of the data used to 
-originally construct the graph.
-- `n_neighbors`: The number of neighbors to find for each query. This does
-*not* have to be the same as the number used to construct `graph`.
-- `queue_size`: Each query maintains a heap of candidate neighbors.
-`queue_size` controls the maximum number of candidates as a multiple of
-`n_neighbors`. Default is `1.`.
-
-Similar to `DescentGraph`, this returns two matrices for the indices and
-distances to the nearest neighbors of each query.
-
-Example:
-```jl
-queries = [rand(10) for _ in 1:100]
-# OR queries = rand(10, 100)
-idxs, dists = search(knngraph, queries, 4)
+
+To find the approximate neighbors for new points with respect to an already constructed graph:
+
+```julia
+queries = [rand(20) for _ in 1:20]
+n_neighbors = 5
+indices, distances = search(graph, queries, n_neighbors)
 ```
+
+[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
+[docs-stable-url]: https://dillondaudert.github.io/NearestNeighborDescent.jl/stable
+
+[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
+[docs-dev-url]: https://dillondaudert.github.io/NearestNeighborDescent.jl/dev
+
+[travis-img]: https://travis-ci.com/dillondaudert/NearestNeighborDescent.jl.svg?branch=master
+[travis-url]: https://travis-ci.com/dillondaudert/NearestNeighborDescent.jl
+
+[appveyor-img]: https://ci.appveyor.com/api/projects/status/lr49p9vxkr8a3uv0?svg=true
+[appveyor-url]: https://ci.appveyor.com/project/dillondaudert/nearestneighbordescent-jl
+
+[codecov-img]: https://codecov.io/gh/dillondaudert/NearestNeighborDescent.jl/branch/master/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/dillondaudert/NearestNeighborDescent.jl
+
+[coveralls-img]: https://coveralls.io/repos/github/dillondaudert/NearestNeighborDescent.jl/badge.svg?branch=master
+[coveralls-url]: https://coveralls.io/github/dillondaudert/NearestNeighborDescent.jl?branch=master