N = histcounts (T) bins the datetimes in T, chosen automatically, and returns the number of elements in each bin. T is treated as T(:) and NaT elements are excluded.

N = histcounts (T, nbins) and N = histcounts (T, edges) bin by count and by explicit datetime edges respectively.

'BinWidth' takes a scalar duration or calendarDuration and, as an Octave extension, any of the unit names listed for discretize; MATLAB accepts only the two classes here and requires 'BinMethod' for a named unit. The two spellings give identical results, so histcounts (T, 'BinWidth', 'day') is simply another way of writing histcounts (T, 'BinMethod', 'day') – and note that neither is the same as 'BinWidth', days (1), for the reason given below. 'BinLimits' takes a two-element datetime, and 'BinEdges' a datetime vector. 'BinMethod' accepts 'auto', 'scott', 'fd', 'sturges' and 'sqrt', and any of the named calendar units listed for discretize, but not 'integers', which has no meaning for a datetime.

'Normalization' accepts 'count', 'cumcount', 'probability', 'percentage' and 'cdf'. 'countdensity' and 'pdf' are not accepted, since a density per unit time has no meaning here.

As for discretize, a named unit or a calendarDuration width begins at local midnight and so varies in length across a daylight-saving transition, while a duration width is a fixed span of elapsed time whatever its length, and an empty T anchors the edges on the epoch rather than on the current clock as MATLAB does. The same paragraph on named units also applies: where a zone shifts by less than one bin unit, an element landing mid-unit past the transition gets a bin of its own, so N always sums to the number of finite elements. MATLAB can leave such an element out of every bin, and its counts then sum to less.

A bin width below a second carries a little noise in its edges. An instant is counted in seconds from 1970 and so runs to about 1.7e9, where a double resolves to some 2e-7 of a second; a width of, say, 0.4 s therefore lands its edges within a few hundred nanoseconds of the exact grid rather than on it. The opening edge is exact, the drift is in the step, and it is a limit of the representation rather than of the placement.

See also: discretize, histcounts

Source Code: datetime