All LSH classes implement Serializable + added an example of serialization...

Author: tdebatty

README.md

@@ -5,6 +5,10 @@ A Java implementation of Locality Sensitive Hashing (LSH).
 
 Locality Sensitive Hashing (LSH) is a family of hashing methods that tent to produce the same hash (or signature) for similar items. There exist different LSH functions, that each correspond to a similarity metric. For example, the MinHash algorithm is designed for Jaccard similarity (the relative number of elements that two sets have in common). For cosine similarity, the traditional LSH algorithm used is Random Projection, but others exist, like Super-Bit, that deliver better resutls.
 
+LSH functions have two main use cases:
+* Compute the signature of large input vectors. These signatures can be used to quickly estimate the similarity between vectors.
+* With a given number of buekcts, bin similar vectors together.
+
 This library implements Locality Sensitive Hashing (LSH), as described in Leskovec, Rajaraman & Ullman (2014), "Mining of Massive Datasets", Cambridge University Press.
 
 Are currently implemented:
@@ -24,7 +28,6 @@ Using maven:
 
 Or see the [releases](https://github.com/tdebatty/java-LSH/releases) page.
 
-
 ##MinHash
 
 MinHash is a hashing scheme that tents to produce similar signatures for sets that have a high Jaccard similarity.
@@ -385,3 +388,87 @@ public class MyApp {
 ```
 
 [Read Javadoc...](http://api123.web-d.be/api/java-LSH/head/index.html)
+
+## Serialization
+
+As the parameters of the hashing function are randomly initialized when the LSH object is instantiated:
+* two LSH objects will produce different hashes and signatures for the same input vector;
+* two executions of your program will produce different hashes and signatures for the same input vector;
+* the signatures produced by two different LSH objects can not be used to estimate the similarity between vectors.
+
+The solution is to serialize you LSH object so you an reuse it:
+
+```java
+import info.debatty.java.lsh.LSHMinHash;
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.ObjectInputStream;
+import java.io.ObjectOutputStream;
+import java.util.Random;
+
+public class SerializeExample {
+
+    public static void main(String[] args)
+            throws IOException, ClassNotFoundException {
+
+        // Create a single random boolean vector
+        int n = 100;
+        double sparsity = 0.75;
+        boolean[] vector = new boolean[n];
+        Random rand = new Random();
+        for (int j = 0; j < n; j++) {
+            vector[j] = rand.nextDouble() > sparsity;
+        }
+
+        // Create and configure LSH
+        int stages = 2;
+        int buckets = 10;
+        LSHMinHash lsh = new LSHMinHash(stages, buckets, n);
+        println(lsh.hash(vector));
+
+        // Create another LSH object
+        // as the parameters of the hashing function are randomly initialized
+        // these two LSH objects will produce different hashes for the same
+        // input vector!
+        LSHMinHash other_lsh = new LSHMinHash(stages, buckets, n);
+        println(other_lsh.hash(vector));
+
+        // Moreover, signatures produced by different LSH objects cannot
+        // be used to compute estimated similarity!
+        // The solution is to serialize and save the object, so it can be
+        // reused later...
+        File tempfile = File.createTempFile("lshobject", ".ser");
+        FileOutputStream fout = new FileOutputStream(tempfile);
+        ObjectOutputStream oos = new ObjectOutputStream(fout);
+        oos.writeObject(lsh);
+        oos.close();
+        System.out.println(
+                "LSH object serialized to " + tempfile.getAbsolutePath());
+
+        FileInputStream fin = new FileInputStream(tempfile);
+        ObjectInputStream ois = new ObjectInputStream(fin);
+        LSHMinHash saved_lsh = (LSHMinHash) ois.readObject();
+        println(saved_lsh.hash(vector));
+    }
+
+    static void println(int[] array) {
+        System.out.print("[");
+        for (int v : array) {
+            System.out.print("" + v + " ");
+        }
+        System.out.println("]");
+    }
+}
+```
+
+Will produce something like:
+```
+[5 5 ]
+[3 1 ]
+LSH object serialized to /tmp/lshobject5903174677942358274.ser
+[5 5 ]
+```
+
+[Check the examples](https://github.com/tdebatty/java-LSH/tree/master/src/main/java/info/debatty/java/lsh/examples) or [read Javadoc](http://api123.io/api/java-LSH/head/index.html)

src/main/java/info/debatty/java/lsh/LSH.java

@@ -1,13 +1,15 @@
 package info.debatty.java.lsh;
 
+import java.io.Serializable;
+
 /**
  * Implementation of Locality Sensitive Hashing (LSH) principle, as described in
  * Leskovec, Rajaraman & Ullman (2014), "Mining of Massive Datasets", 
  * Cambridge University Press.
  * 
  * @author Thibault Debatty http://www.debatty.info
  */
-public abstract class LSH {
+public abstract class LSH implements Serializable {
 
     protected static final long LARGE_PRIME =  433494437;
 

src/main/java/info/debatty/java/lsh/MinHash.java

@@ -1,5 +1,6 @@
 package info.debatty.java.lsh;
 
+import java.io.Serializable;
 import java.security.InvalidParameterException;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -25,7 +26,7 @@
  *
  * @author Thibault Debatty http://www.debatty.info
  */
-public class MinHash {
+public class MinHash implements Serializable {
 
     public static double JaccardIndex(Set<Integer> s1, Set<Integer> s2) {
         Set<Integer> intersection = new HashSet<Integer>(s1);

src/main/java/info/debatty/java/lsh/examples/SerializeExample.java

@@ -0,0 +1,96 @@
+/*
+ * The MIT License
+ *
+ * Copyright 2015 Thibault Debatty.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package info.debatty.java.lsh.examples;
+
+import info.debatty.java.lsh.LSHMinHash;
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.ObjectInputStream;
+import java.io.ObjectOutputStream;
+import java.util.Random;
+
+/**
+ *
+ * @author Thibault Debatty
+ */
+public class SerializeExample {
+
+    /**
+     * @param args the command line arguments
+     * @throws java.io.IOException
+     * @throws java.lang.ClassNotFoundException
+     */
+    public static void main(String[] args)
+            throws IOException, ClassNotFoundException {
+
+        // Create a single random boolean vector
+        int n = 100;
+        double sparsity = 0.75;
+        boolean[] vector = new boolean[n];
+        Random rand = new Random();
+        for (int j = 0; j < n; j++) {
+            vector[j] = rand.nextDouble() > sparsity;
+        }
+
+        // Create and configure LSH
+        int stages = 2;
+        int buckets = 10;
+        LSHMinHash lsh = new LSHMinHash(stages, buckets, n);
+        println(lsh.hash(vector));
+
+        // Create another LSH object
+        // as the parameters of the hashing function are randomly initialized
+        // these two LSH objects will produce different hashes for the same
+        // input vector!
+        LSHMinHash other_lsh = new LSHMinHash(stages, buckets, n);
+        println(other_lsh.hash(vector));
+
+        // Moreover, signatures produced by different LSH objects cannot
+        // be used to compute estimated similarity!
+        // The solution is to serialize and save the object, so it can be
+        // reused later...
+        File tempfile = File.createTempFile("lshobject", ".ser");
+        FileOutputStream fout = new FileOutputStream(tempfile);
+        ObjectOutputStream oos = new ObjectOutputStream(fout);
+        oos.writeObject(lsh);
+        oos.close();
+        System.out.println(
+                "LSH object serialized to " + tempfile.getAbsolutePath());
+
+        FileInputStream fin = new FileInputStream(tempfile);
+        ObjectInputStream ois = new ObjectInputStream(fin);
+        LSHMinHash saved_lsh = (LSHMinHash) ois.readObject();
+        println(saved_lsh.hash(vector));
+    }
+
+    static void println(int[] array) {
+        System.out.print("[");
+        for (int v : array) {
+            System.out.print("" + v + " ");
+        }
+        System.out.println("]");
+    }
+}