TarsosLSH is a Java library implementing Locality-sensitive Hashing (LSH), a practical nearest neighbour search algorithm for multidimensional vectors that operates in sublinear time. It supports several Locality Sensitive Hashing (LSH) families: the Euclidean hash family (L2), city block hash family (L1) and cosine hash family. The library tries to hit the sweet spot between being capable enough to get real tasks done, and compact enough to serve as a demonstration on how LSH works.
Head over to the TarsosLSH release repository and download the latest TarsosLSH library. Consult the TarsosLSH API documentation. If you, for some reason, want to build from source, you need Apache Ant and git installed on your system. The following commands fetch the source and build the library and example jars:
git clone https://JorenSix@github.com/JorenSix/TarsosLSH.git
cd TarsosLSH/build
ant #Builds the core TarsosLSH library
ant javadoc #build the API documentation
The fastest way to get something on your screen is executing this on your command line: java - jar TarsosLSH.jar
this lets LSH run on a random data set. The full reference of the command line application is included below:
Name TarsosLSH: finds the nearest neighbours in a data set quickly, using LSH. Synopsis java - jar TarsosLSH.jar [options] dataset.txt queries.txt Description Tries to find nearest neighbours for each vector in the query file, using Euclidean (L2) distance by default. Both dataset.txt and queries.txt have a similar format: an optional identifier for the vector and a list of N coordinates (which should be doubles). [Identifier] coord1 coord2 ... coordN [Identifier] coord1 coord2 ... coordN For an example data set with two elements and 4 dimensions: Hans 12 24 18.5 -45.6 Jane 13 19 -12.0 49.8 Options are: -f cos|l1|l2 Defines the hash family to use: l1 City block hash family (L1) l2 Euclidean hash family(L2) cos Cosine distance hash family -r radius Defines the radius in which near neighbours should be found. Should be a double. By default a reasonable radius is determined automatically. -h n_hashes An integer that determines the number of hashes to use. By default 4, 32 for the cosine hash family. -t n_tables An integer that determines the number of hash tables, each with n_hashes, to use. By default 4. -n n_neighbours Number of neighbours in the neighbourhood, defaults to 3. -b Benchmark the settings. --help Prints this helpful message. Examples Search for nearest neighbours using the l2 hash family with a radius of 500 and utilizing 5 hash tables, each with 3 hashes. java - jar TarsosLSH.jar -f l2 -r 500 -h 3 -t 5 dataset.txt queries.txt
The source tree is divided in three directories:
src
contains the source files of the core DSP libraries.test
contains unit tests for some of the DSP functionality.build
contains ANT build files. Either to build Java documentation or runnable JAR-files for the example applications.This section includes a links to resources used to implement this library.