Add comments

src/interpolation/interpBruteForce.js

@@ -1,9 +1,20 @@
 import {pointOnCircle, takeSampleFrom} from "./helpers";
 import {placeNearToNearestNeighbour} from "./interpCommon";
 
+/**
+ * Perform interpolation where the nearest neighbour is found by brute-force.
+ * For each point to be interpolated:
+ * - Phase 1: find a nearest beighbour by comparing high-d distance against
+              each point already in the graph.
+ * - Phase 2 and 3 are passed onto placeNearToNearestNeighbour
+ * @param  {list} sampleSet      - nodes already plotted on the 2D graph
+ * @param  {list} remainderSet   - nodes to be interpolated onto the graph
+ * @param  {function} distanceFn - f(nodex, nodey) that calculate high-dimensional
+ *                                 distance between 2 nodes
+ * @param  {number} endingIts    - for phase 3, how many iterations to refine the
+ *                                 placement of each interpolated point
+ */
 export default function(sampleSet, remainderSet, distanceFn) {
-  // var distance = calculateEuclideanDistance;
-  // console.log("Brute-force");
   let sampleSubset = takeSampleFrom(sampleSet, Math.sqrt(sampleSet.length)).sample;
 
   for (let node of remainderSet) {

src/interpolation/interpolationPivots.js

@@ -1,6 +1,27 @@
 import {pointOnCircle, takeSampleFrom} from "./helpers";
 import {placeNearToNearestNeighbour} from "./interpCommon";
 
+/**
+ * Perform interpolation where the near neighbour is estimated by pivot-based searching.
+ * - Pre-processing: assign random samples as pivots,
+ *                   put the others in each pivot's bucket.
+ *                   ie. non-pivot sample X may be in
+ *                   - bucket 3 of pivot A,
+ *                   - bucket 1 of pivot B,
+ *                   - bucket 5 of pivot C,
+ *                   all at the same time
+ * For each point to be interpolated:
+ * - Phase 1: for each pivot: compare distance against the pivot
+ *                            compare against other points in the same bucket of that pivot
+ *            note down the nearest neighbour found
+ * - Phase 2 and 3 are passed onto placeNearToNearestNeighbour
+ * @param  {list} sampleSet      - nodes already plotted on the 2D graph
+ * @param  {list} remainderSet   - nodes to be interpolated onto the graph
+ * @param  {function} distanceFn - f(nodex, nodey) that calculate high-dimensional
+ *                                 distance between 2 nodes
+ * @param  {number} endingIts    - for phase 3, how many iterations to refine the
+ *                                 placement of each interpolated point
+ */
 export default function(sampleSet, remainderSet, numPivots, distanceFn) {
   // Pivot based parent finding
   let numBuckets = Math.floor(Math.sqrt(sampleSet.length));
@@ -18,7 +39,7 @@ export default function(sampleSet, remainderSet, numPivots, distanceFn) {
 
   // Pre-calculate distance between each non-pivot sample to each pivot
   // At the same time, determine the bucket width for each pivot based on furthest non-pivot sample
-  let distCache = []; // [ For each non-pivot Sample:[For each Pivot: distance] ]
+  let distCache = []; // [ For each non-pivot sample:[For each Pivot: distance] ]
   let bucketWidths = []; // [ For each Pivot: width of each bucket ]
 
   for (let i = 0; i < nonPivotSamples.length; i++)
@@ -37,7 +58,6 @@ export default function(sampleSet, remainderSet, numPivots, distanceFn) {
 
     bucketWidths.push(maxDist / numBuckets);
   }
-  // ---------------------------------------------------------------------
 
   // Put samples (pivot not included) into buckets
   for (let j = 0; j < numPivots; j++) {
@@ -53,6 +73,7 @@ export default function(sampleSet, remainderSet, numPivots, distanceFn) {
       pivotsBuckets[j][bucketNumber].push(sample);
     }
   }
+  // ---------------------------------------------------------------------
 
 
   let sampleSubset = takeSampleFrom(sampleSet, Math.sqrt(sampleSet.length)).sample;