Property drawminorticklabel for drawing the label for each minor tick n positions away from a major tick

- has no effect for category/multicategory/log axes
- has no effect if tickformat frequency incompatible with minor tick frequency

Author: my-tien

src/constants/numerical.js

@@ -37,7 +37,7 @@ module.exports = {
     ONEHOUR: 3600000,
     ONEMIN: 60000,
     ONESEC: 1000,
-
+    ONEMICROSEC: 0.001,
     /*
      * For fast conversion btwn world calendars and epoch ms, the Julian Day Number
      * of the unix epoch. From calendars.instance().newDate(1970, 1, 1).toJD()

src/plots/cartesian/axes.js

@@ -31,6 +31,7 @@ var HALFDAY = ONEDAY / 2;
 var ONEHOUR = constants.ONEHOUR;
 var ONEMIN = constants.ONEMIN;
 var ONESEC = constants.ONESEC;
+var ONEMICROSEC = constants.ONEMICROSEC;
 var MINUS_SIGN = constants.MINUS_SIGN;
 var BADNUM = constants.BADNUM;
 
@@ -908,7 +909,7 @@ axes.calcTicks = function calcTicks(ax, opts) {
     var calendar = ax.calendar;
     var ticklabelstep = ax.ticklabelstep;
     var isPeriod = ax.ticklabelmode === 'period';
-
+    var drawMinorTickLabel = ax.drawminorticklabel;
     var rng = Lib.simpleMap(ax.range, ax.r2l, undefined, undefined, opts);
     var axrev = (rng[1] < rng[0]);
     var minRange = Math.min(rng[0], rng[1]);
@@ -921,6 +922,9 @@ axes.calcTicks = function calcTicks(ax, opts) {
 
     var tickVals = [];
     var minorTickVals = [];
+    // all ticks for which labels are drawn which is not necessarily the major ticks when
+    // `drawminorticklabel` is set.
+    var labelTickVals = [];
 
     var hasMinor = ax.minor && (ax.minor.ticks || ax.minor.showgrid);
 
@@ -1075,6 +1079,47 @@ axes.calcTicks = function calcTicks(ax, opts) {
         }
     }
 
+    // check if drawMinorTickLabel makes sense, otherwise ignore it
+    if(!minorTickVals || minorTickVals.length < 2) {
+        drawMinorTickLabel = false;
+    } else {
+        var diff = minorTickVals[1].value - minorTickVals[0].value;
+        if(!periodCompatibleWithTickformat(diff, ax.tickformat)) {
+            drawMinorTickLabel = false;
+        }
+    }
+    // Determine for which ticks to draw labels
+    if(!drawMinorTickLabel) {
+        labelTickVals = tickVals;
+    } else {
+        // Collect and sort all major and minor ticks, to find the minor ticks `drawMinorTickLabel`
+        // steps away from each major tick. For those minor ticks we want to draw the label.
+
+        var allTickVals = tickVals.concat(minorTickVals);
+        if(isPeriod && tickVals.length) {
+            // first major tick was just added for period handling
+            allTickVals = allTickVals.slice(1);
+        }
+        allTickVals =
+            allTickVals
+            .sort(function(a, b) { return a.value - b.value; })
+            .filter(function(tick, index, self) {
+                return index === 0 || tick.value !== self[index - 1].value;
+            });
+
+        var majorTickIndices =
+            allTickVals
+            .map(function(item, index) { return item.minor === undefined ? index : null; })
+            .filter(function(index) { return index !== null; });
+
+        majorTickIndices.forEach(function(majorIdx) {
+            var minorIdx = majorIdx + drawMinorTickLabel;
+            if(minorIdx >= 0 && minorIdx < allTickVals.length) {
+                labelTickVals.push(allTickVals[minorIdx]);
+            }
+        });
+    }
+
     if(hasMinor) {
         var canOverlap =
             (ax.minor.ticks === 'inside' && ax.ticks === 'outside') ||
@@ -1108,7 +1153,7 @@ axes.calcTicks = function calcTicks(ax, opts) {
         }
     }
 
-    if(isPeriod) positionPeriodTicks(tickVals, ax, ax._definedDelta);
+    if(isPeriod) positionPeriodTicks(labelTickVals, ax, ax._definedDelta);
 
     var i;
     if(ax.rangebreaks) {
@@ -1166,38 +1211,44 @@ axes.calcTicks = function calcTicks(ax, opts) {
 
     tickVals = tickVals.concat(minorTickVals);
 
-    var t, p;
+    function setTickLabel(ax, tickVal) {
+        var t = axes.tickText(
+            ax,
+            tickVal.value,
+            false, // hover
+            tickVal.simpleLabel // noSuffixPrefix
+        );
+        var p = tickVal.periodX;
+        if(p !== undefined) {
+            t.periodX = p;
+            if(p > maxRange || p < minRange) { // hide label if outside the range
+                if(p > maxRange) t.periodX = maxRange;
+                if(p < minRange) t.periodX = minRange;
+
+                hideLabel(t);
+            }
+        }
+        return t;
+    }
+
+    var t;
     for(i = 0; i < tickVals.length; i++) {
         var _minor = tickVals[i].minor;
         var _value = tickVals[i].value;
 
         if(_minor) {
-            minorTicks.push({
-                x: _value,
-                minor: true
-            });
+            if(drawMinorTickLabel && labelTickVals.indexOf(tickVals[i]) !== -1) {
+                t = setTickLabel(ax, tickVals[i]);
+            } else {
+                t = { x: _value };
+            }
+            t.minor = true;
+            minorTicks.push(t);
         } else {
             lastVisibleHead = ax._prevDateHead;
-
-            t = axes.tickText(
-                ax,
-                _value,
-                false, // hover
-                tickVals[i].simpleLabel // noSuffixPrefix
-            );
-
-            p = tickVals[i].periodX;
-            if(p !== undefined) {
-                t.periodX = p;
-                if(p > maxRange || p < minRange) { // hide label if outside the range
-                    if(p > maxRange) t.periodX = maxRange;
-                    if(p < minRange) t.periodX = minRange;
-
-                    hideLabel(t);
-                }
-            }
-
-            if(tickVals[i].skipLabel) {
+            t = setTickLabel(ax, tickVals[i]);
+            if(tickVals[i].skipLabel ||
+                drawMinorTickLabel && labelTickVals.indexOf(tickVals[i]) === -1) {
                 hideLabel(t);
             }
 
@@ -4523,3 +4574,38 @@ function setShiftVal(ax, axShifts) {
         axShifts[ax.overlaying][ax.side] :
         (ax.shift || 0);
 }
+
+/**
+ * Checks if the given period is at least the period described by the tickformat or larger. If that
+ * is the case, they are compatible, because then the tickformat can be used to describe the period.
+ * E.g. it doesn't make sense to put a year label on a period spanning only a month.
+ * @param {number} period in ms
+ * @param {string} tickformat
+ * @returns {boolean}
+ */
+function periodCompatibleWithTickformat(period, tickformat) {
+    if(/%f/.test(tickformat)) {
+        if(period < ONEMICROSEC) return false;
+    } else if(/%L/.test(tickformat)) {
+        if(period < 1) return false;
+    } else if(/%[SX]/.test(tickformat)) {
+        if(period < ONESEC) return false;
+    } else if(/%M/.test(tickformat)) {
+        if(period < ONEMIN) return false;
+    } else if(/%[HI]/.test(tickformat)) {
+        if(period < ONEHOUR) return false;
+    } else if(/%p/.test(tickformat)) {
+        if(period < HALFDAY) return false;
+    } else if(/%[Aadejuwx]/.test(tickformat)) {
+        if(period < ONEDAY) return false;
+    } else if(/%[UVW]/.test(tickformat)) {
+        if(period < ONEWEEK) return false;
+    } else if(/%[Bbm]/.test(tickformat)) {
+        if(period < ONEMINMONTH) return false;
+    } else if(/%[q]/.test(tickformat)) {
+        if(period < ONEMINQUARTER) return false;
+    } else if(/%[Yy]/.test(tickformat)) {
+        if(period < ONEMINYEAR) return false;
+    }
+    return true;
+}

src/plots/cartesian/axis_defaults.js

@@ -59,6 +59,10 @@ module.exports = function handleAxisDefaults(containerIn, containerOut, coerce,
         }
     }
 
+    if(axType !== 'category' && axType !== 'multicategory' && axType !== 'log') {
+        coerce('drawminorticklabel');
+    }
+
     var ticklabelposition = '';
     if(!options.noTicklabelposition || axType === 'multicategory') {
         ticklabelposition = Lib.coerce(containerIn, containerOut, {

src/plots/cartesian/layout_attributes.js

@@ -698,6 +698,15 @@ module.exports = {
             'In other cases the default is *hide past div*.'
         ].join(' ')
     },
+    drawminorticklabel: {
+        valType: 'integer',
+        editType: 'calc',
+        description: [
+            'Instead of drawing the major tick label, draw the label for the minor tick',
+            'that is n positions away from the major tick. E.g. to always draw the label for the',
+            'minor tick before each major tick, choose `drawminorticklabel` -1'
+        ].join(' ')
+    },
     mirror: {
         valType: 'enumerated',
         values: [true, 'ticks', false, 'all', 'allticks'],

test/plot-schema.json

@@ -14097,6 +14097,11 @@
      ],
      "valType": "info_array"
     },
+    "drawminorticklabel": {
+     "description": "Instead of drawing the major tick label, draw the label for the minor tick that is n positions away from the major tick. E.g. to always draw the label for the minor tick before each major tick, choose `drawminorticklabel` -1",
+     "editType": "calc",
+     "valType": "integer"
+    },
     "dtick": {
      "description": "Sets the step in-between ticks on this axis. Use with `tick0`. Must be a positive number, or special strings available to *log* and *date* axes. If the axis `type` is *log*, then ticks are set every 10^(n*dtick) where n is the tick number. For example, to set a tick mark at 1, 10, 100, 1000, ... set dtick to 1. To set tick marks at 1, 100, 10000, ... set dtick to 2. To set tick marks at 1, 5, 25, 125, 625, 3125, ... set dtick to log_10(5), or 0.69897000433. *log* has several special values; *L<f>*, where `f` is a positive number, gives ticks linearly spaced in value (but not position). For example `tick0` = 0.1, `dtick` = *L0.5* will put ticks at 0.1, 0.6, 1.1, 1.6 etc. To show powers of 10 plus small digits between, use *D1* (all digits) or *D2* (only 2 and 5). `tick0` is ignored for *D1* and *D2*. If the axis `type` is *date*, then you must convert the time to milliseconds. For example, to set the interval between ticks to one day, set `dtick` to 86400000.0. *date* also has special values *M<n>* gives ticks spaced by a number of months. `n` must be a positive integer. To set ticks on the 15th of every third month, set `tick0` to *2000-01-15* and `dtick` to *M3*. To set ticks every 4 years, set `dtick` to *M48*",
      "editType": "ticks",
@@ -15723,6 +15728,11 @@
      ],
      "valType": "info_array"
     },
+    "drawminorticklabel": {
+     "description": "Instead of drawing the major tick label, draw the label for the minor tick that is n positions away from the major tick. E.g. to always draw the label for the minor tick before each major tick, choose `drawminorticklabel` -1",
+     "editType": "calc",
+     "valType": "integer"
+    },
     "dtick": {
      "description": "Sets the step in-between ticks on this axis. Use with `tick0`. Must be a positive number, or special strings available to *log* and *date* axes. If the axis `type` is *log*, then ticks are set every 10^(n*dtick) where n is the tick number. For example, to set a tick mark at 1, 10, 100, 1000, ... set dtick to 1. To set tick marks at 1, 100, 10000, ... set dtick to 2. To set tick marks at 1, 5, 25, 125, 625, 3125, ... set dtick to log_10(5), or 0.69897000433. *log* has several special values; *L<f>*, where `f` is a positive number, gives ticks linearly spaced in value (but not position). For example `tick0` = 0.1, `dtick` = *L0.5* will put ticks at 0.1, 0.6, 1.1, 1.6 etc. To show powers of 10 plus small digits between, use *D1* (all digits) or *D2* (only 2 and 5). `tick0` is ignored for *D1* and *D2*. If the axis `type` is *date*, then you must convert the time to milliseconds. For example, to set the interval between ticks to one day, set `dtick` to 86400000.0. *date* also has special values *M<n>* gives ticks spaced by a number of months. `n` must be a positive integer. To set ticks on the 15th of every third month, set `tick0` to *2000-01-15* and `dtick` to *M3*. To set ticks every 4 years, set `dtick` to *M48*",
      "editType": "ticks",