Repository: vega/vega-lite (ts)

Issue:
Rename Generated “raw” and “aggregate” tables.
Currently Vega-lite produces up to two data tables in the output Vega specification.

- source data table (`raw`) — the original data table, augmented by derived fields (binning, timeUnit conversion, and the planned calculated field – #451) and filtered.   

- summary table (`aggregate`)  – the additional table, produced by adding Vega’s aggregate transform. 

### TODO

`raw` is a rather confusing name since the table is augmented with derived fields and filtered.  
Maybe `source` is a better name, because it is a source table for other part of the spec. 

`aggregate` table should be renamed to `summary` for consistency as we plan to rename `aggregate` property to `summarize`- 

Pull request:
Rename data tables
- raw => source
- aggregate => summary

fixes #587

Patch:
diff --git a/.jshintrc b/.jshintrc
index f29284dbc..d04f332fe 100644
--- a/.jshintrc
+++ b/.jshintrc
@@ -8,7 +8,7 @@
   "browser": true,
   "quotmark": "single",
   "predef": [
-    "AGGREGATE", "RAW", "STACKED", "INDEX",
+    "SUMMARY", "SOURCE", "STACKED", "INDEX",
     "X", "Y", "ROW", "COL", "SIZE", "SHAPE", "COLOR", "TEXT", "DETAIL",
     "O", "Q", "T", "N"],
   "globalstrict": true
diff --git a/src/Encoding.js b/src/Encoding.js
index 3fe614c2a..de71b395d 100644
--- a/src/Encoding.js
+++ b/src/Encoding.js
@@ -258,7 +258,7 @@ module.exports = (function() {
   };
 
   proto.dataTable = function() {
-    return this.isAggregate() ? AGGREGATE : RAW;
+    return this.isAggregate() ? SUMMARY : SOURCE;
   };
 
   Encoding.isAggregate = function(spec) {
diff --git a/src/compiler/data.js b/src/compiler/data.js
index de6b9a95d..617720e60 100644
--- a/src/compiler/data.js
+++ b/src/compiler/data.js
@@ -13,16 +13,16 @@ var vlEncDef = require('../encdef'),
  *
  * @param  {Encoding} encoding
  * @return {Array} Array of Vega data.
- *                 This always includes a "raw" data table.
+ *                 This always includes a "source" data table.
  *                 If the encoding contains aggregate value, this will also create
  *                 aggregate table as well.
  */
 function data(encoding) {
-  var def = [data.raw(encoding)];
+  var def = [data.source(encoding)];
 
-  var aggregate = data.aggregate(encoding);
+  var aggregate = data.summary(encoding);
   if (aggregate) {
-    def.push(data.aggregate(encoding));
+    def.push(data.summary(encoding));
   }
 
   // TODO add "having" filter here
@@ -39,29 +39,29 @@ function data(encoding) {
   return def;
 }
 
-data.raw = function(encoding) {
-  var raw = {name: RAW};
+data.source = function(encoding) {
+  var source = {name: SOURCE};
 
   // Data source (url or inline)
   if (encoding.hasValues()) {
-    raw.values = encoding.data().values;
-    raw.format = {type: 'json'};
+    source.values = encoding.data().values;
+    source.format = {type: 'json'};
   } else {
-    raw.url = encoding.data().url;
-    raw.format = {type: encoding.data().formatType};
+    source.url = encoding.data().url;
+    source.format = {type: encoding.data().formatType};
   }
 
   // Set data's format.parse if needed
-  var parse = data.raw.formatParse(encoding);
+  var parse = data.source.formatParse(encoding);
   if (parse) {
-    raw.format.parse = parse;
+    source.format.parse = parse;
   }
 
-  raw.transform = data.raw.transform(encoding);
-  return raw;
+  source.transform = data.source.transform(encoding);
+  return source;
 };
 
-data.raw.formatParse = function(encoding) {
+data.source.formatParse = function(encoding) {
   var parse;
 
   encoding.forEach(function(encDef) {
@@ -79,21 +79,21 @@ data.raw.formatParse = function(encoding) {
 };
 
 /**
- * Generate Vega transforms for the raw data table.  This can include
+ * Generate Vega transforms for the source data table.  This can include
  * transforms for time unit, binning and filtering.
  */
-data.raw.transform = function(encoding) {
+data.source.transform = function(encoding) {
   // null filter comes first so transforms are not performed on null values
   // time and bin should come before filter so we can filter by time and bin
-  return data.raw.transform.nullFilter(encoding).concat(
-    data.raw.transform.formula(encoding),
-    data.raw.transform.time(encoding),
-    data.raw.transform.bin(encoding),
-    data.raw.transform.filter(encoding)
+  return data.source.transform.nullFilter(encoding).concat(
+    data.source.transform.formula(encoding),
+    data.source.transform.time(encoding),
+    data.source.transform.bin(encoding),
+    data.source.transform.filter(encoding)
   );
 };
 
-data.raw.transform.time = function(encoding) {
+data.source.transform.time = function(encoding) {
   return encoding.reduce(function(transform, encDef, encType) {
     if (encDef.type === T && encDef.timeUnit) {
       var fieldRef = encoding.fieldRef(encType, {nofn: true, datum: true});
@@ -108,7 +108,7 @@ data.raw.transform.time = function(encoding) {
   }, []);
 };
 
-data.raw.transform.bin = function(encoding) {
+data.source.transform.bin = function(encoding) {
   return encoding.reduce(function(transform, encDef, encType) {
     if (encoding.bin(encType)) {
       transform.push({
@@ -134,7 +134,7 @@ data.raw.transform.bin = function(encoding) {
 /**
  * @return {Array} An array that might contain a filter transform for filtering null value based on filterNul config
  */
-data.raw.transform.nullFilter = function(encoding) {
+data.source.transform.nullFilter = function(encoding) {
   var filteredFields = util.reduce(encoding.fields(),
     function(filteredFields, fieldList, fieldName) {
       if (fieldName === '*') return filteredFields; //count
@@ -158,7 +158,7 @@ data.raw.transform.nullFilter = function(encoding) {
     }] : [];
 };
 
-data.raw.transform.filter = function(encoding) {
+data.source.transform.filter = function(encoding) {
   var filter = encoding.data().filter;
   return filter ? [{
       type: 'filter',
@@ -166,7 +166,7 @@ data.raw.transform.filter = function(encoding) {
   }] : [];
 };
 
-data.raw.transform.formula = function(encoding) {
+data.source.transform.formula = function(encoding) {
   var formulas = encoding.data().formulas;
   if (formulas === undefined) {
     return [];
@@ -179,7 +179,7 @@ data.raw.transform.formula = function(encoding) {
   }, []);
 };
 
-data.aggregate = function(encoding) {
+data.summary = function(encoding) {
   /* dict set for dimensions */
   var dims = {};
 
@@ -222,8 +222,8 @@ data.aggregate = function(encoding) {
 
   if (hasAggregate) {
     return {
-      name: AGGREGATE,
-      source: RAW,
+      name: SUMMARY,
+      source: SOURCE,
       transform: [{
         type: 'aggregate',
         groupby: groupby,
diff --git a/src/compiler/scale.js b/src/compiler/scale.js
index a538801ff..c82c03e43 100644
--- a/src/compiler/scale.js
+++ b/src/compiler/scale.js
@@ -86,7 +86,7 @@ scale.domain = function (encoding, name, type, facet) {
 
   if (useRawDomain) { // useRawDomain - only Q/T
     return {
-      data: RAW,
+      data: SOURCE,
       field: encoding.fieldRef(name, {noAggregate:true})
     };
   } else if (encDef.bin) { // bin -- need to merge both bin_start and bin_end
@@ -99,9 +99,9 @@ scale.domain = function (encoding, name, type, facet) {
     };
   } else if (sort) { // have sort -- only for ordinal
     return {
-      // If sort by aggregation of a specified sort field, we need to use RAW table,
+      // If sort by aggregation of a specified sort field, we need to use SOURCE table,
       // so we can aggregate values for the scale independently from the main aggregation.
-      data: sort.op ? RAW : encoding.dataTable(),
+      data: sort.op ? SOURCE : encoding.dataTable(),
       field: encoding.fieldRef(name),
       sort: sort
     };
diff --git a/src/globals.js b/src/globals.js
index 328e4ae2e..a8ab77b89 100644
--- a/src/globals.js
+++ b/src/globals.js
@@ -3,8 +3,8 @@
 // declare global constant
 var g = global || window;
 
-g.AGGREGATE = 'aggregate';
-g.RAW = 'raw';
+g.SUMMARY = 'summary';
+g.SOURCE = 'source';
 g.STACKED = 'stacked';
 g.INDEX = 'index';
 
diff --git a/src/schema/schema.js b/src/schema/schema.js
index 3881d6c5b..e76689746 100644
--- a/src/schema/schema.js
+++ b/src/schema/schema.js
@@ -171,7 +171,7 @@ var typicalScaleMixin = {
     useRawDomain: {
       type: 'boolean',
       default: undefined,
-      description: 'Uses the raw data range as scale domain instead of ' +
+      description: 'Uses the source data range as scale domain instead of ' +
                    'aggregated data for aggregate axis. ' +
                    'This option does not work with sum or count aggregate' +
                    'as they might have a substantially larger scale range.' +
@@ -851,7 +851,7 @@ var config = {
     useRawDomain: {
       type: 'boolean',
       default: false,
-      description: 'Use the raw data range as scale domain instead of ' +
+      description: 'Use the source data range as scale domain instead of ' +
                    'aggregated data for aggregate axis. ' +
                    'This option does not work with sum or count aggregate' +
                    'as they might have a substantially larger scale range.' +


Test patch:
diff --git a/test/.jshintrc b/test/.jshintrc
index a8b0621a6..635e85d6b 100644
--- a/test/.jshintrc
+++ b/test/.jshintrc
@@ -1,6 +1,6 @@
 {
   "predef": ["_",
-    "AGGREGATE", "RAW", "STACKED", "INDEX",
+    "SUMMARY", "SOURCE", "STACKED", "INDEX",
     "X", "Y", "ROW", "COL", "SIZE", "SHAPE", "COLOR", "TEXT", "DETAIL",
     "O", "Q", "T", "N"],
   "mocha": true,
diff --git a/test/compiler/data.spec.js b/test/compiler/data.spec.js
index 168f3bad5..216c80929 100644
--- a/test/compiler/data.spec.js
+++ b/test/compiler/data.spec.js
@@ -32,9 +32,9 @@ describe('data', function () {
     it('should contains one table', function() {
       expect(_data.length).to.equal(1);
     });
-    it('should have filter non-positive in raw', function() {
-      var rawTransform = _data[0].transform;
-      expect(rawTransform[rawTransform.length - 1]).to.eql({
+    it('should have filter non-positive in source', function() {
+      var sourceTransform = _data[0].transform;
+      expect(sourceTransform[sourceTransform.length - 1]).to.eql({
         type: 'filter',
         test: 'datum.b > 0'
       });
@@ -42,7 +42,7 @@ describe('data', function () {
   });
 });
 
-describe('data.raw', function() {
+describe('data.source', function() {
   describe('with explicit values', function() {
     var encoding = Encoding.fromSpec({
       data: {
@@ -50,15 +50,15 @@ describe('data.raw', function() {
       }
     });
 
-    var raw = data.raw(encoding, {});
+    var source = data.source(encoding, {});
 
     it('should have values', function() {
-      expect(raw.name).to.equal('raw');
-      expect(raw.values).to.deep.equal([{a: 1, b:2, c:3}, {a: 4, b:5, c:6}]);
+      expect(source.name).to.equal('source');
+      expect(source.values).to.deep.equal([{a: 1, b:2, c:3}, {a: 4, b:5, c:6}]);
     });
 
-    it('should have raw.format', function(){
-      expect(raw.format).to.eql({type: 'json'});
+    it('should have source.format', function(){
+      expect(source.format).to.eql({type: 'json'});
     });
   });
 
@@ -69,14 +69,14 @@ describe('data.raw', function() {
         }
       });
 
-    var raw = data.raw(encoding);
+    var source = data.source(encoding);
 
     it('should have format json', function() {
-      expect(raw.name).to.equal('raw');
-      expect(raw.format.type).to.equal('json');
+      expect(source.name).to.equal('source');
+      expect(source.format.type).to.equal('json');
     });
     it('should have correct url', function() {
-      expect(raw.url).to.equal('http://foo.bar');
+      expect(source.url).to.equal('http://foo.bar');
     });
   });
 
@@ -90,8 +90,8 @@ describe('data.raw', function() {
           }
         });
 
-      var raw = data.raw(encoding);
-      expect(raw.format.parse).to.eql({
+      var source = data.source(encoding);
+      expect(source.format.parse).to.eql({
         'a': 'date',
         'b': 'number'
       });
@@ -115,7 +115,7 @@ describe('data.raw', function() {
 
     describe('bin', function() {
       it('should add bin transform', function() {
-        var transform = data.raw.transform.bin(encoding);
+        var transform = data.source.transform.bin(encoding);
 
         expect(transform[0]).to.eql({
           type: 'bin',
@@ -138,7 +138,7 @@ describe('data.raw', function() {
 
       it('should add filterNull for Q and T by default', function () {
         var encoding = Encoding.fromSpec(spec);
-        expect(data.raw.transform.nullFilter(encoding))
+        expect(data.source.transform.nullFilter(encoding))
           .to.eql([{
             type: 'filter',
             test: 'datum.T!==null && datum.Q!==null'
@@ -151,7 +151,7 @@ describe('data.raw', function() {
             filterNull: {O: true}
           }
         });
-        expect(data.raw.transform.nullFilter(encoding))
+        expect(data.source.transform.nullFilter(encoding))
           .to.eql([{
             type: 'filter',
             test:'datum.T!==null && datum.Q!==null && datum.O!==null'
@@ -162,7 +162,7 @@ describe('data.raw', function() {
 
     describe('filter', function () {
       it('should return array that contains a filter transform', function () {
-        expect(data.raw.transform.filter(encoding))
+        expect(data.source.transform.filter(encoding))
           .to.eql([{
             type: 'filter',
             test: 'datum.a > datum.b && datum.c === datum.d'
@@ -172,7 +172,7 @@ describe('data.raw', function() {
 
     describe('time', function() {
       it('should add formula transform', function() {
-        var transform = data.raw.transform.time(encoding);
+        var transform = data.source.transform.time(encoding);
         expect(transform[0]).to.eql({
           type: 'formula',
           field: 'year_a',
@@ -182,7 +182,7 @@ describe('data.raw', function() {
     });
 
     it('should have null filter, timeUnit, bin then filter', function () {
-      var transform = data.raw.transform(encoding);
+      var transform = data.source.transform(encoding);
       expect(transform[0].type).to.eql('filter');
       expect(transform[1].type).to.eql('formula');
       expect(transform[2].type).to.eql('bin');
@@ -194,7 +194,7 @@ describe('data.raw', function() {
 });
 
 
-describe('data.aggregated', function () {
+describe('data.summary', function () {
   it('should return correct aggregation', function() {
     var encoding = Encoding.fromSpec({
         encoding: {
@@ -211,10 +211,10 @@ describe('data.aggregated', function () {
         }
       });
 
-    var aggregated = data.aggregate(encoding);
+    var aggregated = data.summary(encoding);
     expect(aggregated ).to.eql({
-      "name": AGGREGATE,
-      "source": "raw",
+      "name": SUMMARY,
+      "source": "source",
       "transform": [{
         "type": "aggregate",
         "groupby": ["origin"],
diff --git a/test/compiler/scale.spec.js b/test/compiler/scale.spec.js
index 75ff8cb32..cd3dcb10d 100644
--- a/test/compiler/scale.spec.js
+++ b/test/compiler/scale.spec.js
@@ -65,7 +65,7 @@ describe('vl.compile.scale', function() {
           }), 'y', 'ordinal', {origin: {min: -5, max:48}}, {});
 
           expect(domain).to.eql({
-            data: RAW,
+            data: SOURCE,
             field: ['bin_origin_start', 'bin_origin_end']
           });
         });
@@ -83,7 +83,7 @@ describe('vl.compile.scale', function() {
             }
           }), 'y', 'linear', {}, {});
 
-          expect(domain.data).to.eql(RAW);
+          expect(domain.data).to.eql(SOURCE);
         });
 
       it('should return the aggregate domain for sum Q',
@@ -99,7 +99,7 @@ describe('vl.compile.scale', function() {
             }
           }), 'y', 'linear', {}, {});
 
-          expect(domain.data).to.eql(AGGREGATE);
+          expect(domain.data).to.eql(SUMMARY);
         });
 
 
@@ -115,7 +115,7 @@ describe('vl.compile.scale', function() {
             }
           }), 'y', 'linear', {}, {});
 
-          expect(domain.data).to.eql(AGGREGATE);
+          expect(domain.data).to.eql(SUMMARY);
         });
     });
 
@@ -132,7 +132,7 @@ describe('vl.compile.scale', function() {
             }
           }), 'y', 'time', {}, {});
 
-          expect(domain.data).to.eql(RAW);
+          expect(domain.data).to.eql(SOURCE);
         });
 
       it('should return the raw domain if useRawDomain is true for year T',
@@ -148,7 +148,7 @@ describe('vl.compile.scale', function() {
             }
           }), 'y', 'ordinal', {}, {});
 
-          expect(domain.data).to.eql(RAW);
+          expect(domain.data).to.eql(SOURCE);
           expect(domain.field.indexOf('year')).to.gt(-1);
         });
 
@@ -180,7 +180,7 @@ describe('vl.compile.scale', function() {
 
         expect(vlscale.domain(encoding, 'y', 'ordinal'))
           .to.eql({
-            data: RAW,
+            data: SOURCE,
             field: 'origin',
             sort: sortDef
           });
@@ -195,7 +195,7 @@ describe('vl.compile.scale', function() {
 
         expect(vlscale.domain(encoding, 'y', 'ordinal'))
           .to.eql({
-            data: RAW,
+            data: SOURCE,
             field: 'origin',
             sort: true
           });
diff --git a/test/compiler/stack.spec.js b/test/compiler/stack.spec.js
index a3e6db2d9..77962e266 100644
--- a/test/compiler/stack.spec.js
+++ b/test/compiler/stack.spec.js
@@ -31,7 +31,7 @@ describe('vl.compile.stack()', function () {
       var vgSpec = compile(fixtures.binX, stats);
 
       var tableData = vgSpec.data.filter(function(data) {
-        return data.name === 'aggregate';
+        return data.name === SUMMARY;
       });
       expect(tableData.length).to.equal(1);
 
@@ -56,7 +56,7 @@ describe('vl.compile.stack()', function () {
       var vgSpec = compile(fixtures.binY, stats);
 
       var tableData = vgSpec.data.filter(function(data) {
-        return data.name === 'aggregate';
+        return data.name === SUMMARY;
       });
       expect(tableData.length).to.equal(1);
 
@@ -75,9 +75,5 @@ describe('vl.compile.stack()', function () {
       expect(stackedAggrTransform.groupby[0]).to.equal('bin_Cost__Total_$_start');
     });
   });
-
-
-
-
 });