Binning temporal data using the built-in _hours_ interval forces interval boundaries to start at midnight

[mwaibel-go]

Consider the following plot invocation. Every hour there’s an event and I’m trying to bin them in intervals of 11 hours each.

Plot.plot({
  color: { legend: true, transform: null },
  marks: [
    Plot.barY(
      Array.from({length: 48}, (_, i) => (new Date(2026, 7, 1 + Math.floor(i / 24), i%24))),
      Plot.binY({fill: 'count'}, {y: { interval: '11 hours'}})
    )
  ]
})

I expected each bin to be the same size (maybe expect the very last one). Instead each day is individually divided into two bins of size 11 hours and one bin of size 2 hours.

The same happens for every interval of which 24 hours isn’t an integer multiple (i.e., 5, 7, 9, …).

This might be related to #2450

[mwaibel-go]

I believe I found the root cause or at least a related bug:

Plot.timeInterval('65 minutes').floor(new Date())
Plot.timeInterval('65 minutes').ceil(new Date())

These two are 60 minutes apart, even though the interval’s intervalDuration is 3900000 (= 65 minutes).

More relevant to the example in the issue description,

Plot.timeInterval('11 hours').ceil(new Date(2026, 7, 1, 23))

is the next midnight.

This seems to be ultimately caused by the “statelessness” of the interval functions (floor, ceil, offset, etc.) They don’t know what their “zero value” should be and thus assume that it’s midnight. When binning with these strange time increments, this assumption doesn’t hold. (Though even with this explanation I don’t understand why the ceil function gets clamped at midnight.)

In order to provide the intended result, each bin would need to know the starting point of the first bin. This should probably be derived from the corresponding scale domain. Then it could correctly add increments of the specified duration until it finds its own extent.

Of course, these calculations could also be performed by the user who would then provide either a custom interval implementation or pre-computed thresholds. So I’m not sure if this bug needs fixing at all. However, I do believe that this behaviour at least warrants a documentation update. I was very surprised by Plot.timeInterval('65 minutes').ceil(new Date()).

Just for completeness’s sake:

timeInterval('90 seconds').ceil(new Date('2026-07-03T05:05:05Z')).toISOString()
// "2026-07-03T05:06:00.000Z" – seconds intervals align and clamp at the minute
 timeInterval('90 minutes').ceil(new Date('2026-07-03T05:05:05Z')).toISOString()
// "2026-07-03T06:00:00.000Z" – minute intervals align and clamp at the hour
 timeInterval('25 hours').ceil(new Date('2026-07-03T05:05:05Z')).toISOString()
// "2026-07-03T22:00:00.000Z" – hour intervals align and clamp at the day
 timeInterval('33 days').ceil(new Date('2026-07-03T05:05:05Z')).toISOString()
// "2026-07-03T22:00:00.000Z" – day intervals align and clamp at the month

// I have no clue what’s going on with weeks
timeInterval('1 weeks').ceil(new Date('2026-07-03T05:05:05Z')).toISOString()
// "2026-07-04T22:00:00.000Z"
timeInterval('2 weeks').ceil(new Date('2026-07-03T05:05:05Z')).toISOString()
// "2026-07-11T22:00:00.000Z"
timeInterval('3 weeks').ceil(new Date('2026-07-03T05:05:05Z')).toISOString()
// "2026-07-04T22:00:00.000Z"

timeInterval('2 months').ceil(new Date('2026-07-03T05:05:05Z')).toISOString()
// "2026-08-31T22:00:00.000Z" – month intervals align and clamp at the months

timeInterval('2 years').ceil(new Date('2026-07-03T05:05:05Z')).toISOString()
// "2027-12-31T23:00:00.000Z" – year intervals align and clamp at the years