├── .DS_Store
├── Readme.md
└── tsne.js


/.DS_Store:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/karpathy/tsnejs/13ece5d7e751a5180a59ca396013e800e1059c20/.DS_Store


--------------------------------------------------------------------------------
/Readme.md:
--------------------------------------------------------------------------------
 1 | 
 2 | # tSNEJS
 3 | 
 4 | tSNEJS is an implementation of t-SNE visualization algorithm in Javascript. 
 5 | 
 6 | t-SNE is a visualization algorithm that embeds things in 2 or 3 dimensions. If you have some data and you can measure their pairwise differences, t-SNE visualization can help you identify clusters in your data. See example below.
 7 | 
 8 | ## Online demo
 9 | The main project website has a [live example](http://cs.stanford.edu/people/karpathy/tsnejs/) and more description.
10 | 
11 | There is also the [t-SNE CSV demo](http://cs.stanford.edu/people/karpathy/tsnejs/csvdemo.html) that allows you to simply paste CSV data into a textbox and tSNEJS computes and visualizes the embedding on the fly (no coding needed).
12 | 
13 | ## Research Paper
14 | The algorithm was originally described in this paper:
15 | 
16 |     L.J.P. van der Maaten and G.E. Hinton.
17 |     Visualizing High-Dimensional Data Using t-SNE. Journal of Machine Learning Research
18 |     9(Nov):2579-2605, 2008.
19 | 
20 | You can find the PDF [here](http://jmlr.csail.mit.edu/papers/volume9/vandermaaten08a/vandermaaten08a.pdf).
21 | 
22 | ## Example code
23 | Import tsne.js into your document: `<script src="tsne.js"></script>`
24 | And then here is some example code:
25 | 
26 | ```javascript
27 | 
28 | var opt = {}
29 | opt.epsilon = 10; // epsilon is learning rate (10 = default)
30 | opt.perplexity = 30; // roughly how many neighbors each point influences (30 = default)
31 | opt.dim = 2; // dimensionality of the embedding (2 = default)
32 | 
33 | var tsne = new tsnejs.tSNE(opt); // create a tSNE instance
34 | 
35 | // initialize data. Here we have 3 points and some example pairwise dissimilarities
36 | var dists = [[1.0, 0.1, 0.2], [0.1, 1.0, 0.3], [0.2, 0.1, 1.0]];
37 | tsne.initDataDist(dists);
38 | 
39 | for(var k = 0; k < 500; k++) {
40 |   tsne.step(); // every time you call this, solution gets better
41 | }
42 | 
43 | var Y = tsne.getSolution(); // Y is an array of 2-D points that you can plot
44 | ```
45 | 
46 | The data can be passed to tSNEJS as a set of high-dimensional points using the `tsne.initDataRaw(X)` function, where X is an array of arrays (high-dimensional points that need to be embedded). The algorithm computes the Gaussian kernel over these points and then finds the appropriate embedding.
47 | 
48 | ## Web Demos
49 | There are two web interfaces to this library that we are aware of:
50 | 
51 | - By Andrej, [here](http://cs.stanford.edu/people/karpathy/tsnejs/csvdemo.html).
52 | - By Laurens, [here](http://homepage.tudelft.nl/19j49/tsnejs/), which takes data in different format and can also use Google Spreadsheet input.
53 | 
54 | ## About
55 | Send questions to [@karpathy](https://twitter.com/karpathy).
56 | 
57 | ## License
58 | 
59 | MIT
60 | 
61 | 


--------------------------------------------------------------------------------
/tsne.js:
--------------------------------------------------------------------------------
  1 | // create main global object
  2 | var tsnejs = tsnejs || { REVISION: 'ALPHA' };
  3 | 
  4 | (function(global) {
  5 |   "use strict";
  6 | 
  7 |   // utility function
  8 |   var assert = function(condition, message) {
  9 |     if (!condition) { throw message || "Assertion failed"; }
 10 |   }
 11 | 
 12 |   // syntax sugar
 13 |   var getopt = function(opt, field, defaultval) {
 14 |     if(opt.hasOwnProperty(field)) {
 15 |       return opt[field];
 16 |     } else {
 17 |       return defaultval;
 18 |     }
 19 |   }
 20 | 
 21 |   // return 0 mean unit standard deviation random number
 22 |   var return_v = false;
 23 |   var v_val = 0.0;
 24 |   var gaussRandom = function() {
 25 |     if(return_v) { 
 26 |       return_v = false;
 27 |       return v_val; 
 28 |     }
 29 |     var u = 2*Math.random()-1;
 30 |     var v = 2*Math.random()-1;
 31 |     var r = u*u + v*v;
 32 |     if(r == 0 || r > 1) return gaussRandom();
 33 |     var c = Math.sqrt(-2*Math.log(r)/r);
 34 |     v_val = v*c; // cache this for next function call for efficiency
 35 |     return_v = true;
 36 |     return u*c;
 37 |   }
 38 | 
 39 |   // return random normal number
 40 |   var randn = function(mu, std){ return mu+gaussRandom()*std; }
 41 | 
 42 |   // utilitity that creates contiguous vector of zeros of size n
 43 |   var zeros = function(n) {
 44 |     if(typeof(n)==='undefined' || isNaN(n)) { return []; }
 45 |     if(typeof ArrayBuffer === 'undefined') {
 46 |       // lacking browser support
 47 |       var arr = new Array(n);
 48 |       for(var i=0;i<n;i++) { arr[i]= 0; }
 49 |       return arr;
 50 |     } else {
 51 |       return new Float64Array(n); // typed arrays are faster
 52 |     }
 53 |   }
 54 | 
 55 |   // utility that returns 2d array filled with random numbers
 56 |   // or with value s, if provided
 57 |   var randn2d = function(n,d,s) {
 58 |     var uses = typeof s !== 'undefined';
 59 |     var x = [];
 60 |     for(var i=0;i<n;i++) {
 61 |       var xhere = [];
 62 |       for(var j=0;j<d;j++) { 
 63 |         if(uses) {
 64 |           xhere.push(s); 
 65 |         } else {
 66 |           xhere.push(randn(0.0, 1e-4)); 
 67 |         }
 68 |       }
 69 |       x.push(xhere);
 70 |     }
 71 |     return x;
 72 |   }
 73 | 
 74 |   // compute L2 distance between two vectors
 75 |   var L2 = function(x1, x2) {
 76 |     var D = x1.length;
 77 |     var d = 0;
 78 |     for(var i=0;i<D;i++) { 
 79 |       var x1i = x1[i];
 80 |       var x2i = x2[i];
 81 |       d += (x1i-x2i)*(x1i-x2i);
 82 |     }
 83 |     return d;
 84 |   }
 85 | 
 86 |   // compute pairwise distance in all vectors in X
 87 |   var xtod = function(X) {
 88 |     var N = X.length;
 89 |     var dist = zeros(N * N); // allocate contiguous array
 90 |     for(var i=0;i<N;i++) {
 91 |       for(var j=i+1;j<N;j++) {
 92 |         var d = L2(X[i], X[j]);
 93 |         dist[i*N+j] = d;
 94 |         dist[j*N+i] = d;
 95 |       }
 96 |     }
 97 |     return dist;
 98 |   }
 99 | 
100 |   // compute (p_{i|j} + p_{j|i})/(2n)
101 |   var d2p = function(D, perplexity, tol) {
102 |     var Nf = Math.sqrt(D.length); // this better be an integer
103 |     var N = Math.floor(Nf);
104 |     assert(N === Nf, "D should have square number of elements.");
105 |     var Htarget = Math.log(perplexity); // target entropy of distribution
106 |     var P = zeros(N * N); // temporary probability matrix
107 | 
108 |     var prow = zeros(N); // a temporary storage compartment
109 |     for(var i=0;i<N;i++) {
110 |       var betamin = -Infinity;
111 |       var betamax = Infinity;
112 |       var beta = 1; // initial value of precision
113 |       var done = false;
114 |       var maxtries = 50;
115 | 
116 |       // perform binary search to find a suitable precision beta
117 |       // so that the entropy of the distribution is appropriate
118 |       var num = 0;
119 |       while(!done) {
120 |         //debugger;
121 | 
122 |         // compute entropy and kernel row with beta precision
123 |         var psum = 0.0;
124 |         for(var j=0;j<N;j++) {
125 |           var pj = Math.exp(- D[i*N+j] * beta);
126 |           if(i===j) { pj = 0; } // we dont care about diagonals
127 |           prow[j] = pj;
128 |           psum += pj;
129 |         }
130 |         // normalize p and compute entropy
131 |         var Hhere = 0.0;
132 |         for(var j=0;j<N;j++) {
133 |           if(psum == 0) {
134 |              var pj = 0;
135 |           } else {
136 |              var pj = prow[j] / psum;
137 |           }
138 |           prow[j] = pj;
139 |           if(pj > 1e-7) Hhere -= pj * Math.log(pj);
140 |         }
141 | 
142 |         // adjust beta based on result
143 |         if(Hhere > Htarget) {
144 |           // entropy was too high (distribution too diffuse)
145 |           // so we need to increase the precision for more peaky distribution
146 |           betamin = beta; // move up the bounds
147 |           if(betamax === Infinity) { beta = beta * 2; }
148 |           else { beta = (beta + betamax) / 2; }
149 | 
150 |         } else {
151 |           // converse case. make distrubtion less peaky
152 |           betamax = beta;
153 |           if(betamin === -Infinity) { beta = beta / 2; }
154 |           else { beta = (beta + betamin) / 2; }
155 |         }
156 | 
157 |         // stopping conditions: too many tries or got a good precision
158 |         num++;
159 |         if(Math.abs(Hhere - Htarget) < tol) { done = true; }
160 |         if(num >= maxtries) { done = true; }
161 |       }
162 | 
163 |       // console.log('data point ' + i + ' gets precision ' + beta + ' after ' + num + ' binary search steps.');
164 |       // copy over the final prow to P at row i
165 |       for(var j=0;j<N;j++) { P[i*N+j] = prow[j]; }
166 | 
167 |     } // end loop over examples i
168 | 
169 |     // symmetrize P and normalize it to sum to 1 over all ij
170 |     var Pout = zeros(N * N);
171 |     var N2 = N*2;
172 |     for(var i=0;i<N;i++) {
173 |       for(var j=0;j<N;j++) {
174 |         Pout[i*N+j] = Math.max((P[i*N+j] + P[j*N+i])/N2, 1e-100);
175 |       }
176 |     }
177 | 
178 |     return Pout;
179 |   }
180 | 
181 |   // helper function
182 |   function sign(x) { return x > 0 ? 1 : x < 0 ? -1 : 0; }
183 | 
184 |   var tSNE = function(opt) {
185 |     var opt = opt || {};
186 |     this.perplexity = getopt(opt, "perplexity", 30); // effective number of nearest neighbors
187 |     this.dim = getopt(opt, "dim", 2); // by default 2-D tSNE
188 |     this.epsilon = getopt(opt, "epsilon", 10); // learning rate
189 | 
190 |     this.iter = 0;
191 |   }
192 | 
193 |   tSNE.prototype = {
194 | 
195 |     // this function takes a set of high-dimensional points
196 |     // and creates matrix P from them using gaussian kernel
197 |     initDataRaw: function(X) {
198 |       var N = X.length;
199 |       var D = X[0].length;
200 |       assert(N > 0, " X is empty? You must have some data!");
201 |       assert(D > 0, " X[0] is empty? Where is the data?");
202 |       var dists = xtod(X); // convert X to distances using gaussian kernel
203 |       this.P = d2p(dists, this.perplexity, 1e-4); // attach to object
204 |       this.N = N; // back up the size of the dataset
205 |       this.initSolution(); // refresh this
206 |     },
207 | 
208 |     // this function takes a given distance matrix and creates
209 |     // matrix P from them.
210 |     // D is assumed to be provided as a list of lists, and should be symmetric
211 |     initDataDist: function(D) {
212 |       var N = D.length;
213 |       assert(N > 0, " X is empty? You must have some data!");
214 |       // convert D to a (fast) typed array version
215 |       var dists = zeros(N * N); // allocate contiguous array
216 |       for(var i=0;i<N;i++) {
217 |         for(var j=i+1;j<N;j++) {
218 |           var d = D[i][j];
219 |           dists[i*N+j] = d;
220 |           dists[j*N+i] = d;
221 |         }
222 |       }
223 |       this.P = d2p(dists, this.perplexity, 1e-4);
224 |       this.N = N;
225 |       this.initSolution(); // refresh this
226 |     },
227 | 
228 |     // (re)initializes the solution to random
229 |     initSolution: function() {
230 |       // generate random solution to t-SNE
231 |       this.Y = randn2d(this.N, this.dim); // the solution
232 |       this.gains = randn2d(this.N, this.dim, 1.0); // step gains to accelerate progress in unchanging directions
233 |       this.ystep = randn2d(this.N, this.dim, 0.0); // momentum accumulator
234 |       this.iter = 0;
235 |     },
236 | 
237 |     // return pointer to current solution
238 |     getSolution: function() {
239 |       return this.Y;
240 |     },
241 | 
242 |     // perform a single step of optimization to improve the embedding
243 |     step: function() {
244 |       this.iter += 1;
245 |       var N = this.N;
246 | 
247 |       var cg = this.costGrad(this.Y); // evaluate gradient
248 |       var cost = cg.cost;
249 |       var grad = cg.grad;
250 | 
251 |       // perform gradient step
252 |       var ymean = zeros(this.dim);
253 |       for(var i=0;i<N;i++) {
254 |         for(var d=0;d<this.dim;d++) {
255 |           var gid = grad[i][d];
256 |           var sid = this.ystep[i][d];
257 |           var gainid = this.gains[i][d];
258 | 
259 |           // compute gain update
260 |           var newgain = sign(gid) === sign(sid) ? gainid * 0.8 : gainid + 0.2;
261 |           if(newgain < 0.01) newgain = 0.01; // clamp
262 |           this.gains[i][d] = newgain; // store for next turn
263 | 
264 |           // compute momentum step direction
265 |           var momval = this.iter < 250 ? 0.5 : 0.8;
266 |           var newsid = momval * sid - this.epsilon * newgain * grad[i][d];
267 |           this.ystep[i][d] = newsid; // remember the step we took
268 | 
269 |           // step!
270 |           this.Y[i][d] += newsid; 
271 | 
272 |           ymean[d] += this.Y[i][d]; // accumulate mean so that we can center later
273 |         }
274 |       }
275 | 
276 |       // reproject Y to be zero mean
277 |       for(var i=0;i<N;i++) {
278 |         for(var d=0;d<this.dim;d++) {
279 |           this.Y[i][d] -= ymean[d]/N;
280 |         }
281 |       }
282 | 
283 |       //if(this.iter%100===0) console.log('iter ' + this.iter + ', cost: ' + cost);
284 |       return cost; // return current cost
285 |     },
286 | 
287 |     // for debugging: gradient check
288 |     debugGrad: function() {
289 |       var N = this.N;
290 | 
291 |       var cg = this.costGrad(this.Y); // evaluate gradient
292 |       var cost = cg.cost;
293 |       var grad = cg.grad;
294 | 
295 |       var e = 1e-5;
296 |       for(var i=0;i<N;i++) {
297 |         for(var d=0;d<this.dim;d++) {
298 |           var yold = this.Y[i][d];
299 | 
300 |           this.Y[i][d] = yold + e;
301 |           var cg0 = this.costGrad(this.Y);
302 | 
303 |           this.Y[i][d] = yold - e;
304 |           var cg1 = this.costGrad(this.Y);
305 |           
306 |           var analytic = grad[i][d];
307 |           var numerical = (cg0.cost - cg1.cost) / ( 2 * e );
308 |           console.log(i + ',' + d + ': gradcheck analytic: ' + analytic + ' vs. numerical: ' + numerical);
309 | 
310 |           this.Y[i][d] = yold;
311 |         }
312 |       }
313 |     },
314 | 
315 |     // return cost and gradient, given an arrangement
316 |     costGrad: function(Y) {
317 |       var N = this.N;
318 |       var dim = this.dim; // dim of output space
319 |       var P = this.P;
320 | 
321 |       var pmul = this.iter < 100 ? 4 : 1; // trick that helps with local optima
322 | 
323 |       // compute current Q distribution, unnormalized first
324 |       var Qu = zeros(N * N);
325 |       var qsum = 0.0;
326 |       for(var i=0;i<N;i++) {
327 |         for(var j=i+1;j<N;j++) {
328 |           var dsum = 0.0;
329 |           for(var d=0;d<dim;d++) {
330 |             var dhere = Y[i][d] - Y[j][d];
331 |             dsum += dhere * dhere;
332 |           }
333 |           var qu = 1.0 / (1.0 + dsum); // Student t-distribution
334 |           Qu[i*N+j] = qu;
335 |           Qu[j*N+i] = qu;
336 |           qsum += 2 * qu;
337 |         }
338 |       }
339 |       // normalize Q distribution to sum to 1
340 |       var NN = N*N;
341 |       var Q = zeros(NN);
342 |       for(var q=0;q<NN;q++) { Q[q] = Math.max(Qu[q] / qsum, 1e-100); }
343 | 
344 |       var cost = 0.0;
345 |       var grad = [];
346 |       for(var i=0;i<N;i++) {
347 |         var gsum = new Array(dim); // init grad for point i
348 |         for(var d=0;d<dim;d++) { gsum[d] = 0.0; }
349 |         for(var j=0;j<N;j++) {
350 |           cost += - P[i*N+j] * Math.log(Q[i*N+j]); // accumulate cost (the non-constant portion at least...)
351 |           var premult = 4 * (pmul * P[i*N+j] - Q[i*N+j]) * Qu[i*N+j];
352 |           for(var d=0;d<dim;d++) {
353 |             gsum[d] += premult * (Y[i][d] - Y[j][d]);
354 |           }
355 |         }
356 |         grad.push(gsum);
357 |       }
358 | 
359 |       return {cost: cost, grad: grad};
360 |     }
361 |   }
362 | 
363 |   global.tSNE = tSNE; // export tSNE class
364 | })(tsnejs);
365 | 
366 | 
367 | // export the library to window, or to module in nodejs
368 | (function(lib) {
369 |   "use strict";
370 |   if (typeof module === "undefined" || typeof module.exports === "undefined") {
371 |     window.tsnejs = lib; // in ordinary browser attach library to window
372 |   } else {
373 |     module.exports = lib; // in nodejs
374 |   }
375 | })(tsnejs);
376 | 


--------------------------------------------------------------------------------