fix: properly support utc timeunits

Author: haldenl

examples/specs/bar_yearmonth_custom_format.vl.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
-  "description": "Temperature in Seattle as a bar chart with yearmonth time unit.",
+  "description": "Custom time format on x-axis.",
   "data": {"url": "data/seattle-temps.csv"},
   "mark": "bar",
   "encoding": {

examples/specs/line_timeunit_transform.vl.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
-  "description": "Google's stock price over time. Used to demonstrate the time unit transform.",
+  "description": "Time unit transform.",
   "data": {"url": "data/seattle-weather.csv"},
   "mark": "line",
   "transform": [{

examples/specs/time_output_utc_scale.vl.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
-  "description": "Google's stock price over time.",
+  "description": "Using utc scale with local time input.",
   "data": {
     "values": [
       {"date": "Sun, 01 Jan 2012 23:00:00", "price": 150},

examples/specs/time_output_utc_timeunit.vl.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
-  "description": "Google's stock price over time.",
+  "description": "Using utc timeunit with local time input.",
   "data": {
     "values": [
       {"date": "Sun, 01 Jan 2012 23:00:00", "price": 150},

examples/specs/time_parse_local.vl.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
-  "description": "Google's stock price over time.",
+  "description": "Non-ISO time strings are parsed as local time.",
   "data": {
     "values": [
       {"date": "10 Oct 2011 22:48:00"},

examples/specs/time_parse_utc_format.vl.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
-  "description": "Google's stock price over time.",
+  "description": "Using format parse to parsing of input time data as utc time.",
   "data": {
     "values": [
       {"date": "10 Oct 2011 22:48:00"},

site/docs/transform/timeunit.md

@@ -120,7 +120,7 @@ To parse data in local time or UTC time, there are three cases:
 
 ### Output
 
-By default, Vega-Lite will output data in local time (even when input is parsed as UTC time). To output data in UTC time, we need to specify either a UTC time unit or scale:
+By default, Vega-Lite will output data in local time (even when input is parsed as UTC time). To output data in UTC time, we can specify either a UTC time unit or scale:
 
 1. UTC time unit when input data is in local time.
 
@@ -129,5 +129,3 @@ By default, Vega-Lite will output data in local time (even when input is parsed
 2. UTC scale type when you have input data in UTC time.
 
 <span class="vl-example" data-name="time_output_utc_scale"></span>
-
-Do **not** use UTC time unit and the UTC scale type at the same time since that will cause Vega-Lite to shift the output time twice.

src/compile/data/timeunit.ts

@@ -1,7 +1,7 @@
 import {TimeUnitTransform as VgTimeUnitTransform} from 'vega';
 import {getSecondaryRangeChannel} from '../../channel';
 import {hasBand, vgField} from '../../channeldef';
-import {getTimeUnitParts} from '../../timeunit';
+import {getTimeUnitParts, isUTCTimeUnit} from '../../timeunit';
 import {TimeUnitTransform} from '../../transform';
 import {Dict, duplicate, hash, keys, vals} from '../../util';
 import {isUnitModel, ModelWithField} from '../model';
@@ -101,6 +101,7 @@ export class TimeUnitNode extends DataFlowNode {
         field,
         type: 'timeunit',
         units: getTimeUnitParts(timeUnit),
+        ...(isUTCTimeUnit(timeUnit) ? {timezone: 'utc'} : {}),
         as: [as, `${as}_end`]
       });
     }

src/compile/scale/type.ts

@@ -5,6 +5,7 @@ import * as log from '../../log';
 import {Mark} from '../../mark';
 import {channelSupportScaleType, Scale, ScaleType, scaleTypeSupportDataType} from '../../scale';
 import * as util from '../../util';
+import {isUTCTimeUnit} from '../../timeunit';
 
 export type RangeType = 'continuous' | 'discrete' | 'flexible' | undefined;
 
@@ -77,6 +78,8 @@ function defaultType(channel: Channel, fieldDef: TypedFieldDef<string>, mark: Ma
         log.warn(log.message.discreteChannelCannotEncode(channel, 'temporal'));
         // TODO: consider using quantize (equivalent to binning) once we have it
         return 'ordinal';
+      } else if (fieldDef.timeUnit && isUTCTimeUnit(fieldDef.timeUnit)) {
+        return 'utc';
       }
       return 'time';
 

src/timeunit.ts

@@ -329,7 +329,7 @@ export function formatExpression(timeUnit: TimeUnit, field: string, isUTCScale:
   // We only use utcFormat for utc scale
   // For utc time units, the data is already converted as a part of timeUnit transform.
   // Thus, utc time units should use timeFormat to avoid shifting the time twice.
-  if (isUTCScale) {
+  if (isUTCScale || isUTCTimeUnit(timeUnit)) {
     return `utcFormat(${field}, ${timeUnitSpecifierExpr})`;
   } else {
     return `timeFormat(${field}, ${timeUnitSpecifierExpr})`;

test/compile/data/timeunit.test.ts

@@ -14,7 +14,7 @@ function assembleFromTransform(t: TimeUnitTransform) {
 
 describe('compile/data/timeunit', () => {
   describe('parseUnit', () => {
-    it('should return a dictionary of a formula transform for point', () => {
+    it('should return a timeunit transform for point', () => {
       const model = parseUnitModel({
         data: {values: []},
         mark: 'point',
@@ -33,7 +33,7 @@ describe('compile/data/timeunit', () => {
       ]);
     });
 
-    it('should return a dictionary of formula transforms for bar', () => {
+    it('should return a unit transforms for bar', () => {
       const model = parseUnitModel({
         data: {values: []},
         mark: 'bar',
@@ -52,7 +52,7 @@ describe('compile/data/timeunit', () => {
       ]);
     });
 
-    it('should return a dictionary of formula transform from transform array', () => {
+    it('should return a timeunit transform from transform array', () => {
       const t: TimeUnitTransform = {field: 'date', as: 'month_date', timeUnit: 'month'};
 
       expect(assembleFromTransform(t)).toEqual([
@@ -64,6 +64,20 @@ describe('compile/data/timeunit', () => {
         }
       ]);
     });
+
+    it('should return a timeunit transform with timezone for utc units', () => {
+      const t: TimeUnitTransform = {field: 'date', as: 'utcmonth_date', timeUnit: 'utcmonth'};
+
+      expect(assembleFromTransform(t)).toEqual([
+        {
+          type: 'timeunit',
+          field: 'date',
+          timezone: 'utc',
+          as: ['utcmonth_date', 'utcmonth_date_end'],
+          units: ['month']
+        }
+      ]);
+    });
   });
 
   describe('hash', () => {

test/compile/scale/type.test.ts

@@ -3,7 +3,7 @@ import {scaleType} from '../../../src/compile/scale/type';
 import * as log from '../../../src/log';
 import {BAR, PRIMITIVE_MARKS, RULE} from '../../../src/mark';
 import {ScaleType} from '../../../src/scale';
-import {TIMEUNITS} from '../../../src/timeunit';
+import {TIMEUNITS, isUTCTimeUnit} from '../../../src/timeunit';
 import {NOMINAL, ORDINAL} from '../../../src/type';
 import * as util from '../../../src/util';
 import {RECT} from './../../../src/mark';
@@ -140,11 +140,17 @@ describe('compile/scale', () => {
         })
       );
 
-      it('should return time for all time units.', () => {
-        for (const timeUnit of TIMEUNITS) {
+      it('should return time for all non-utc time units.', () => {
+        for (const timeUnit of TIMEUNITS.filter(t => !isUTCTimeUnit(t))) {
           expect(scaleType({}, Y, {type: 'temporal', timeUnit: timeUnit}, 'point')).toEqual(ScaleType.TIME);
         }
       });
+
+      it('should return utc for all utc time units.', () => {
+        for (const timeUnit of TIMEUNITS.filter(t => isUTCTimeUnit(t))) {
+          expect(scaleType({}, Y, {type: 'temporal', timeUnit: timeUnit}, 'point')).toEqual(ScaleType.UTC);
+        }
+      });
     });
     describe('quantitative', () => {
       it('should return linear scale for quantitative color field by default.', () => {
@@ -209,6 +215,12 @@ describe('compile/scale', () => {
         );
       });
 
+      it('should return utc scale type if data type is temporal and specified scale type is utc', () => {
+        expect(scaleType({type: ScaleType.UTC}, 'x', {type: 'temporal', timeUnit: 'year'}, 'point')).toEqual(
+          ScaleType.UTC
+        );
+      });
+
       it('should return default scale type if data type is quantative but scale type do not support quantative', () => {
         expect(scaleType({type: ScaleType.TIME}, 'color', {type: 'quantitative'}, 'point')).toEqual(ScaleType.LINEAR);
       });