Add possibility to define custom tickformat per zoom levels

[apalchys]

We have a requirement to use custom tick format at some zoom level. For example:
I want to add "Year" postfix for years but keep default formatting for other zoom levels.

I prepared a PR to add possibility to pass not only string but also a configuration object to axis tickformat. Since it is my first PR I did it in my fork as per the guideline
apalchys#1

@rreusser / @etpinard could you please review?

[etpinard]

This sounds like a nice solution for #1812

[etpinard]

Related:

• how to enable auto-formatting for time axis on zoom events with custom date-time format? #1513
• Toggle subsampling of tick labels when tickmode="array" #1779
• [feature]: different handlers for customizability (ticktextHandler) #1658
• Support specifying a function for tickformat #1464

[apalchys]

Based on @etpinard feedback here apalchys#1 (comment), I suggested the following change:

Add a new field which sets a tick format for defined span.

tickformatstops: [{
  span:  number | string, 
  value: string //tick format string
}]

I doubt about naming - any improvements are welcome.
Here are examples how it will work for different axis types:

//linear
tickformatstops: [{
  span: 10,
  value: '.2%'
}, {
  span: 100,
  value: '.1%'
}]

//date
tickformatstops: [{
  span: 'year',
  value: '%Y year'
}, {
  span: 86400000, // in ms
  value: '%e %b'
}]

//log
tickformatstops: [{
  span: 1,
  value: '.1'
}, {
  span: 2,
  value: '.0'
}]

//category
tickformatstops: [{
  span: 6,  //number of visible ticks ?
  value: '.1'
}]

[apalchys]

@etpinard @alexcjohnson @rreusser if you don't have objections/comments, I am starting work on the implementation.

[etpinard]

@apalchys It's probably best to wait for us to reach a consensus. Sorry if things are slow, but it's the middle of summer and this ticket isn't a high priority.

[alexcjohnson]

I like the concept!

Trying to pin down exactly what span really means - is it the biggest dtick to use this format with? The smallest? The "closest"? In principle we could also base this on Math.abs(range[1] - range[0]) rather than dtick as our internal autorounding does, though the goal of this is really to distinguish ticks from each other so dtick seems more appropriate. Otherwise you could get a situation where you change the number of ticks and suddenly you get multiple identical labels. But also, it occurs to me it might be more useful to have:

tickformatstops: [{
  min:  number, // optional: minimum span to use this format
  max: number, // optional: maximum span to use this format
  value: string // tick format string
}]

And then we take the first format that satisfies the min/max criteria, falling back on default formatting if none match. That way you could do things like:

tickformatstops: [{max: 100, value: '.2f'}, {value: 'e'}]

which would mean '.2f' if dtick <= 100, otherwise 'e'
Or:

tickformatstops: [{min: 1, max: 100, value: '.2f'}]

which would mean '.2f' for dtick between 1 and 100, otherwise use default formatting.

Now, as to number vs number|string for spans - first lets assume this is only for date axes, we might use it with log axes to talk about the linear span vs the exponent span but... that opens all sorts of cans of worms! For dates: we want something that can be specified granularly, ie not just "year" but 2 years, 5 years, 31.52 years... dtick already supports 'M<n>' for n months which also handles years (make n a multiple of 12 - see caveat in #1241 for world calendars). This is the only one we really need for dtick, since months (and years) are nonuniform so you can't specify them as milliseconds. For the purposes here it seems like we should support at least the 'M<n>' format to correspond with dtick but we'll have to convert to approximate numbers anyway to tell which is bigger, probably like I do in https://github.com/plotly/plotly.js/pull/1944/files#diff-e02f19bac6aa5dbda7a48a07b3ad45fdR327

The question then is whether we support more than we do for dtick. Non-integer months? Other prefixes for years, weeks, days, hours, minutes, seconds? My gut reaction would be no, not at first, but we can make a later PR that adds this support for both tickformatstops and dtick simultaneously. These other codes are not necessary to get the effect you want, they're just conveniences so you don't have to write out 1000 * 60 * 60 * 24 * 7 to get a week, for example.

[etpinard]

I like the idea of optional min and max attributes, but I would vote for

tickformatstops: [{
  range:  [/* 2-item array */],
  value: string // tick format string
}]

where null items in range would do the same as omitting min or max in @alexcjohnson 's #1946 (comment) - similar to what's proposed in #1876

[alexcjohnson]

range - love it.
Another good call by @etpinard - aka the-one-who-remembers-every-idea-anyone-has-ever-had-about-plotlyjs 🌟 🥇 🌟

[apalchys]

tickformatstops: [{
  range:  [/* 2-item array */],
  value: string // tick format string
}]

just confirm: range is an 2-item array of spans (dticks), right?

[alexcjohnson]

just confirm: range is an 2-item array of spans (dticks), right?

Yes. I suppose that could be confusing though if it's named range, people might think it should look like a range - should it be called dtickrange?

@apalchys I think we're agreed on the structure anyway - so go for it, looking forward to this!