Period positioning for Cartesian traces

src/plots/cartesian/align_period.js

@@ -0,0 +1,69 @@
+/**
+* Copyright 2012-2020, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+'use strict';
+
+var isNumeric = require('fast-isnumeric');
+var ms2DateTime = require('../../lib').ms2DateTime;
+var ONEDAY = require('../../constants/numerical').ONEDAY;
+
+module.exports = function alignPeriod(trace, ax, axLetter, vals) {
+    var alignment = trace[axLetter + 'periodalignment'];
+    if(!alignment || alignment === 'start') return vals;
+
+    var dynamic = false;
+    var period = trace[axLetter + 'period'];
+    if(isNumeric(period)) {
+        period = +period; // milliseconds
+        if(period <= 0) return vals;
+    } else if(typeof period === 'string' && period.charAt(0) === 'M') {
+        var v = +(period.substring(1));
+        if(v > 0 && Math.round(v) === v) period = v; // positive integer months
+        else return vals;
+
+        dynamic = true;
+    }
+
+    if(period > 0) {
+        var ratio = (alignment === 'end') ? 1 : 0.5;
+
+        var len = vals.length;
+        for(var i = 0; i < len; i++) {
+            var delta;
+
+            if(dynamic) {
+                var dateStr = ms2DateTime(vals[i], 0, ax.calendar);
+                var d = new Date(dateStr);
+                var year = d.getFullYear();
+                var month = d.getMonth() + 1;
+
+                var totalDaysInMonths = 0;
+                for(var k = 0; k < period; k++) {
+                    month += 1;
+                    if(month > 12) {
+                        month = 1;
+                        year++;
+                    }
+
+                    var monthDays = (
+                        new Date(year, month, 0)
+                    ).getDate();
+
+                    totalDaysInMonths += monthDays;
+                }
+
+                delta = ONEDAY * totalDaysInMonths; // convert to ms
+            } else {
+                delta = period;
+            }
+
+            vals[i] += ratio * delta;
+        }
+    }
+    return vals;
+};

src/plots/cartesian/axes.js

@@ -1334,6 +1334,10 @@ function formatDate(ax, out, hover, extraPrecision) {
     var tr = ax._tickround;
     var fmt = (hover && ax.hoverformat) || axes.getTickFormat(ax);
 
+    if(ax.ticklabelmode === 'period') {
+        extraPrecision = false;
+    }
+
     if(extraPrecision) {
         // second or sub-second precision: extra always shows max digits.
         // for other fields, extra precision just adds one field.

src/plots/cartesian/set_convert.js

@@ -30,6 +30,7 @@ var ONEMIN = numConstants.ONEMIN;
 var ONESEC = numConstants.ONESEC;
 
 var axisIds = require('./axis_ids');
+var alignPeriod = require('./align_period');
 
 var constants = require('./constants');
 var HOUR_PATTERN = constants.HOUR_PATTERN;
@@ -847,6 +848,10 @@ module.exports = function setConvert(ax, fullLayout) {
             }
         }
 
+        if(axType === 'date') {
+            arrayOut = alignPeriod(trace, ax, axLetter, arrayOut);
+        }
+
         return arrayOut;
     };
 

src/traces/bar/attributes.js

@@ -59,6 +59,11 @@ module.exports = {
     y0: scatterAttrs.y0,
     dy: scatterAttrs.dy,
 
+    xperiod: scatterAttrs.xperiod,
+    yperiod: scatterAttrs.yperiod,
+    xperiodalignment: scatterAttrs.xperiodalignment,
+    yperiodalignment: scatterAttrs.yperiodalignment,
+
     text: scatterAttrs.text,
     texttemplate: texttemplateAttrs({editType: 'plot'}, {
         keys: constants.eventDataKeys

src/traces/bar/defaults.js

@@ -13,6 +13,7 @@ var Color = require('../../components/color');
 var Registry = require('../../registry');
 
 var handleXYDefaults = require('../scatter/xy_defaults');
+var handlePeriodDefaults = require('../scatter/period_defaults');
 var handleStyleDefaults = require('./style_defaults');
 var getAxisGroup = require('../../plots/cartesian/axis_ids').getAxisGroup;
 var attributes = require('./attributes');
@@ -30,6 +31,8 @@ function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
         return;
     }
 
+    handlePeriodDefaults(traceIn, traceOut, layout, coerce);
+
     coerce('orientation', (traceOut.x && !traceOut.y) ? 'h' : 'v');
     coerce('base');
     coerce('offset');

src/traces/box/attributes.js

@@ -76,6 +76,11 @@ module.exports = {
         ].join(' ')
     },
 
+    xperiod: scatterAttrs.xperiod,
+    yperiod: scatterAttrs.yperiod,
+    xperiodalignment: scatterAttrs.xperiodalignment,
+    yperiodalignment: scatterAttrs.yperiodalignment,
+
     name: {
         valType: 'string',
         role: 'info',

src/traces/box/defaults.js

@@ -11,6 +11,7 @@
 var Lib = require('../../lib');
 var Registry = require('../../registry');
 var Color = require('../../components/color');
+var handlePeriodDefaults = require('../scatter/period_defaults');
 var handleGroupingDefaults = require('../bar/defaults').handleGroupingDefaults;
 var autoType = require('../../plots/cartesian/axis_autotype');
 var attributes = require('./attributes');
@@ -23,6 +24,8 @@ function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
     handleSampleDefaults(traceIn, traceOut, coerce, layout);
     if(traceOut.visible === false) return;
 
+    handlePeriodDefaults(traceIn, traceOut, layout, coerce);
+
     var hasPreCompStats = traceOut._hasPreCompStats;
 
     if(hasPreCompStats) {

src/traces/candlestick/attributes.js

@@ -27,6 +27,9 @@ function directionAttrs(lineColorDefault) {
 }
 
 module.exports = {
+    xperiod: OHLCattrs.xperiod,
+    xperiodalignment: OHLCattrs.xperiodalignment,
+
     x: OHLCattrs.x,
     open: OHLCattrs.open,
     high: OHLCattrs.high,

src/traces/candlestick/defaults.js

@@ -12,6 +12,7 @@
 var Lib = require('../../lib');
 var Color = require('../../components/color');
 var handleOHLC = require('../ohlc/ohlc_defaults');
+var handlePeriodDefaults = require('../scatter/period_defaults');
 var attributes = require('./attributes');
 
 module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
@@ -25,6 +26,8 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
         return;
     }
 
+    handlePeriodDefaults(traceIn, traceOut, layout, coerce, {x: true});
+
     coerce('line.width');
 
     handleDirection(traceIn, traceOut, coerce, 'increasing');

src/traces/contour/attributes.js

@@ -31,6 +31,12 @@ module.exports = extendFlat({
     y: heatmapAttrs.y,
     y0: heatmapAttrs.y0,
     dy: heatmapAttrs.dy,
+
+    xperiod: heatmapAttrs.xperiod,
+    yperiod: heatmapAttrs.yperiod,
+    xperiodalignment: heatmapAttrs.xperiodalignment,
+    yperiodalignment: heatmapAttrs.yperiodalignment,
+
     text: heatmapAttrs.text,
     hovertext: heatmapAttrs.hovertext,
     transpose: heatmapAttrs.transpose,

src/traces/contour/defaults.js

@@ -11,6 +11,7 @@
 var Lib = require('../../lib');
 
 var handleXYZDefaults = require('../heatmap/xyz_defaults');
+var handlePeriodDefaults = require('../scatter/period_defaults');
 var handleConstraintDefaults = require('./constraint_defaults');
 var handleContoursDefaults = require('./contours_defaults');
 var handleStyleDefaults = require('./style_defaults');
@@ -32,6 +33,8 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
         return;
     }
 
+    handlePeriodDefaults(traceIn, traceOut, layout, coerce);
+
     coerce('text');
     coerce('hovertext');
     coerce('hovertemplate');

src/traces/funnel/attributes.js

@@ -25,6 +25,11 @@ module.exports = {
     y0: barAttrs.y0,
     dy: barAttrs.dy,
 
+    xperiod: barAttrs.xperiod,
+    yperiod: barAttrs.yperiod,
+    xperiodalignment: barAttrs.xperiodalignment,
+    yperiodalignment: barAttrs.yperiodalignment,
+
     hovertext: barAttrs.hovertext,
     hovertemplate: hovertemplateAttrs({}, {
         keys: constants.eventDataKeys

src/traces/funnel/defaults.js

@@ -13,6 +13,7 @@ var Lib = require('../../lib');
 var handleGroupingDefaults = require('../bar/defaults').handleGroupingDefaults;
 var handleText = require('../bar/defaults').handleText;
 var handleXYDefaults = require('../scatter/xy_defaults');
+var handlePeriodDefaults = require('../scatter/period_defaults');
 var attributes = require('./attributes');
 var Color = require('../../components/color');
 
@@ -27,6 +28,8 @@ function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
         return;
     }
 
+    handlePeriodDefaults(traceIn, traceOut, layout, coerce);
+
     coerce('orientation', (traceOut.y && !traceOut.x) ? 'v' : 'h');
     coerce('offset');
     coerce('width');

src/traces/heatmap/attributes.js

@@ -29,6 +29,11 @@ module.exports = extendFlat({
     y0: extendFlat({}, scatterAttrs.y0, {impliedEdits: {ytype: 'scaled'}}),
     dy: extendFlat({}, scatterAttrs.dy, {impliedEdits: {ytype: 'scaled'}}),
 
+    xperiod: extendFlat({}, scatterAttrs.xperiod, {impliedEdits: {xtype: 'scaled'}}),
+    yperiod: extendFlat({}, scatterAttrs.yperiod, {impliedEdits: {ytype: 'scaled'}}),
+    xperiodalignment: extendFlat({}, scatterAttrs.xperiodalignment, {impliedEdits: {xtype: 'scaled'}}),
+    yperiodalignment: extendFlat({}, scatterAttrs.yperiodalignment, {impliedEdits: {ytype: 'scaled'}}),
+
     text: {
         valType: 'data_array',
         editType: 'calc',

src/traces/heatmap/defaults.js

@@ -12,6 +12,7 @@
 var Lib = require('../../lib');
 
 var handleXYZDefaults = require('./xyz_defaults');
+var handlePeriodDefaults = require('../scatter/period_defaults');
 var handleStyleDefaults = require('./style_defaults');
 var colorscaleDefaults = require('../../components/colorscale/defaults');
 var attributes = require('./attributes');
@@ -28,6 +29,8 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
         return;
     }
 
+    handlePeriodDefaults(traceIn, traceOut, layout, coerce);
+
     coerce('text');
     coerce('hovertext');
     coerce('hovertemplate');

src/traces/histogram/attributes.js

@@ -30,6 +30,11 @@ module.exports = {
         ].join(' ')
     },
 
+    xperiod: barAttrs.xperiod,
+    yperiod: barAttrs.yperiod,
+    xperiodalignment: barAttrs.xperiodalignment,
+    yperiodalignment: barAttrs.yperiodalignment,
+
     text: extendFlat({}, barAttrs.text, {
         description: [
             'Sets hover text elements associated with each bar.',

src/traces/histogram/defaults.js

@@ -12,6 +12,7 @@ var Registry = require('../../registry');
 var Lib = require('../../lib');
 var Color = require('../../components/color');
 
+var handlePeriodDefaults = require('../scatter/period_defaults');
 var handleStyleDefaults = require('../bar/style_defaults');
 var attributes = require('./attributes');
 
@@ -46,6 +47,8 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
         return;
     }
 
+    handlePeriodDefaults(traceIn, traceOut, layout, coerce);
+
     traceOut._length = len;
 
     var handleCalendarDefaults = Registry.getComponentMethod('calendars', 'handleTraceDefaults');

src/traces/histogram2d/attributes.js

@@ -22,6 +22,11 @@ module.exports = extendFlat(
         x: histogramAttrs.x,
         y: histogramAttrs.y,
 
+        xperiod: histogramAttrs.xperiod,
+        yperiod: histogramAttrs.yperiod,
+        xperiodalignment: histogramAttrs.xperiodalignment,
+        yperiodalignment: histogramAttrs.yperiodalignment,
+
         z: {
             valType: 'data_array',
             editType: 'calc',

src/traces/histogram2d/defaults.js

@@ -11,6 +11,7 @@
 
 var Lib = require('../../lib');
 
+var handlePeriodDefaults = require('../scatter/period_defaults');
 var handleSampleDefaults = require('./sample_defaults');
 var handleStyleDefaults = require('../heatmap/style_defaults');
 var colorscaleDefaults = require('../../components/colorscale/defaults');
@@ -25,6 +26,8 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     handleSampleDefaults(traceIn, traceOut, coerce, layout);
     if(traceOut.visible === false) return;
 
+    handlePeriodDefaults(traceIn, traceOut, layout, coerce);
+
     handleStyleDefaults(traceIn, traceOut, coerce, layout);
     colorscaleDefaults(traceIn, traceOut, layout, coerce, {prefix: '', cLetter: 'z'});
     coerce('hovertemplate');

src/traces/histogram2dcontour/attributes.js

@@ -15,6 +15,11 @@ var colorScaleAttrs = require('../../components/colorscale/attributes');
 var extendFlat = require('../../lib/extend').extendFlat;
 
 module.exports = extendFlat({
+    xperiod: histogram2dAttrs.xperiod,
+    yperiod: histogram2dAttrs.yperiod,
+    xperiodalignment: histogram2dAttrs.xperiodalignment,
+    yperiodalignment: histogram2dAttrs.yperiodalignment,
+
     x: histogram2dAttrs.x,
     y: histogram2dAttrs.y,
     z: histogram2dAttrs.z,

src/traces/histogram2dcontour/defaults.js

@@ -11,6 +11,7 @@
 
 var Lib = require('../../lib');
 
+var handlePeriodDefaults = require('../scatter/period_defaults');
 var handleSampleDefaults = require('../histogram2d/sample_defaults');
 var handleContoursDefaults = require('../contour/contours_defaults');
 var handleStyleDefaults = require('../contour/style_defaults');
@@ -29,6 +30,8 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     handleSampleDefaults(traceIn, traceOut, coerce, layout);
     if(traceOut.visible === false) return;
 
+    handlePeriodDefaults(traceIn, traceOut, layout, coerce);
+
     handleContoursDefaults(traceIn, traceOut, coerce, coerce2);
     handleStyleDefaults(traceIn, traceOut, coerce, layout);
     coerce('hovertemplate');

src/traces/ohlc/attributes.js

@@ -34,6 +34,9 @@ function directionAttrs(lineColorDefault) {
 
 module.exports = {
 
+    xperiod: scatterAttrs.xperiod,
+    xperiodalignment: scatterAttrs.xperiodalignment,
+
     x: {
         valType: 'data_array',
         editType: 'calc+clearAxisTypes',

src/traces/ohlc/defaults.js

@@ -11,6 +11,7 @@
 
 var Lib = require('../../lib');
 var handleOHLC = require('./ohlc_defaults');
+var handlePeriodDefaults = require('../scatter/period_defaults');
 var attributes = require('./attributes');
 
 module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout) {
@@ -24,6 +25,8 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
         return;
     }
 
+    handlePeriodDefaults(traceIn, traceOut, layout, coerce, {x: true});
+
     coerce('line.width');
     coerce('line.dash');