Time¶

Generation of time ticks¶

detroit.time_ticks(start: datetime, stop: datetime, count: int) → list[datetime]¶

Returns an array of approximately count dates at regular intervals between start and stop (inclusive).

Parameters:

start (datetime) – Start date
stop (datetime) – Stop date
count (int) – Count

Returns:

Array of approximated dates

Return type:

list[datetime]

Examples

If you give rounded datetime (for example, day times starting and finishing at 00:00:00), the function iterates over days.

>>> from datetime import datetime
>>> start = datetime(2011, 1, 1, 0, 0, 0)
>>> stop = datetime(2011, 1, 5, 0, 0, 0)
>>> count = 4
>>> dates = d3.time_ticks(start, stop, count)
>>> type(dates)
<class 'list'>
>>> for d in dates:
...     print(d)
...
...
2011-01-01 00:00:00
2011-01-02 00:00:00
2011-01-03 00:00:00
2011-01-04 00:00:00
2011-01-05 00:00:00

However, if you give specific datetime, the function rounds dates based on the time delta between stop and start and returns count dates.

>>> from datetime import datetime
>>> start = datetime(2011, 1, 1, 12, 0, 0)
>>> stop = datetime(2011, 1, 5, 12, 0, 0)
>>> count = 4
>>> dates = d3.time_ticks(start, stop, count)
>>> type(dates)
<class 'list'>
>>> for d in dates:
...     print(d)
...
...
2011-01-02 00:00:00
2011-01-03 00:00:00
2011-01-04 00:00:00
2011-01-05 00:00:00

As you can see, the closest date to 2011-01-01 12:00:00 is 2011-01-02 00:00:00. The function starts from this date and iterates count times.

class detroit.time.ticks.Ticker(year: Callable, month: Callable, week: Callable, day: Callable, hour: Callable, minute: Callable)¶

Tick generator

Parameters:

year (Callable) – Year interval function
month (Callable) – Month interval function
week (Callable) – Week interval function
day (Callable) – Day interval function
hour (Callable) – Hour interval function
minute (Callable) – Minute interval function

ticks(start: datetime, stop: datetime, count: int) → list[datetime]¶

Returns an array of approximately count dates at regular intervals between start and stop (inclusive).

Parameters:

start (datetime) – Start date
stop (datetime) – Stop date
count (int) – Count

Returns:

Array of approximated dates

Return type:

list[datetime]

Examples

If you give rounded datetime (for example, day times starting and finishing at 00:00:00), the function iterates over days.

>>> from datetime import datetime
>>> start = datetime(2011, 1, 1, 0, 0, 0)
>>> stop = datetime(2011, 1, 5, 0, 0, 0)
>>> count = 4
>>> dates = d3.time_ticks(start, stop, count)
>>> type(dates)
<class 'list'>
>>> for d in dates:
...     print(d)
...
...
2011-01-01 00:00:00
2011-01-02 00:00:00
2011-01-03 00:00:00
2011-01-04 00:00:00
2011-01-05 00:00:00

However, if you give specific datetime, the function rounds dates based on the time delta between stop and start and returns count dates.

>>> from datetime import datetime
>>> start = datetime(2011, 1, 1, 12, 0, 0)
>>> stop = datetime(2011, 1, 5, 12, 0, 0)
>>> count = 4
>>> dates = d3.time_ticks(start, stop, count)
>>> type(dates)
<class 'list'>
>>> for d in dates:
...     print(d)
...
...
2011-01-02 00:00:00
2011-01-03 00:00:00
2011-01-04 00:00:00
2011-01-05 00:00:00

As you can see, the closest date to 2011-01-01 12:00:00 is 2011-01-02 00:00:00. The function starts from this date and iterates count times.

tick_interval(start: datetime, stop: datetime, count: int) → TimeInterval¶

Returns the time interval that would be used by d3.time_ticks given the same arguments

Parameters:

start (datetime) – Start date
stop (datetime) – Stop date
count (int) – Count

Returns:

Time interval chosen used by d3.time_ticks

Return type:

TimeInterval

Manipulation of date times segmented by time unit¶

The following classes are all derived by TimeInterval class. Each of them is defined for a specific time unit. For example, the function d3.time_day helps to manipulate dates only based on days by truncating inputs as day time or by generating day times.

detroit.time_millisecond(date: datetime | None = None) → datetime¶: Milliseconds in local time

detroit.time_second(date: datetime | None = None) → datetime¶: Seconds in local time; 1,000 milliseconds

detroit.time_day(date: datetime | None = None) → datetime¶: Days in local time; typically 24 hours

detroit.time_hour(date: datetime | None = None) → datetime¶: Hours in local time; 60 minutes

detroit.time_minute(date: datetime | None = None) → datetime¶: Minutes in local time; 60 seconds

detroit.time_month(date: datetime | None = None) → datetime¶: Months in local time; ranges from 28 days to 31 days

detroit.time_year(date: datetime | None = None) → datetime¶: Years in local time; ranges from 365 days to 366 days

detroit.time_week(date: datetime | None = None) → datetime¶: Weeks in local time; typically 7 days

detroit.time_sunday(date: datetime | None = None) → datetime¶: Weeks in local time; typically 7 days

detroit.time_monday(date: datetime | None = None) → datetime¶: Weeks in local time; typically 7 days

detroit.time_tuesday(date: datetime | None = None) → datetime¶: Weeks in local time; typically 7 days

detroit.time_wednesday(date: datetime | None = None) → datetime¶: Weeks in local time; typically 7 days

detroit.time_thursday(date: datetime | None = None) → datetime¶: Weeks in local time; typically 7 days

detroit.time_friday(date: datetime | None = None) → datetime¶: Weeks in local time; typically 7 days

detroit.time_saturday(date: datetime | None = None) → datetime¶: Weeks in local time; typically 7 days

class detroit.time.interval.TimeInterval¶

__call__(date: datetime | None = None) → datetime¶

Applies a floor operation on the input. If the input is None, the input is replaced by the current date.

Parameters:: date (datetime | None) – Date
Returns:: Date
Return type:: datetime

Examples

>>> from datetime import datetime
>>> d3.time_day(datetime(2010, 1, 1, 12, 0))
datetime.datetime(2010, 1, 1, 0, 0)

interval(date: datetime | None = None) → datetime¶

Same as __call__

Parameters:: date (datetime | None) – Date
Returns:: Date
Return type:: datetime

Examples

>>> from datetime import datetime
>>> d3.time_day.interval(datetime(2010, 1, 1, 12, 0))
datetime.datetime(2010, 1, 1, 0, 0)

every(step: int) → TimeInterval¶

Returns a filtered view of this interval representing every stepth date. The meaning of step is dependent on this interval’s parent interval as defined by the field function.

Parameters:: step (int) – Step
Returns:: Modified class with new floor and offset methods
Return type:: TimeFilter

Examples

>>> from datetime import datetime
>>> every = d3.time_day.every(3)
>>> r = every.range(datetime(2010, 1, 1), datetime(2010, 1, 8))
>>> for d in r:
...     print(d)
...
...
2010-01-01 00:00:00
2010-01-04 00:00:00
2010-01-07 00:00:00

ceil(date: datetime) → datetime¶

Returns a new date representing the earliest interval boundary date after or equal to date.

Parameters:: date (datetime) – Date
Returns:: Ceiled date
Return type:: datetime

Examples

>>> from datetime import datetime
>>> d3.time_day.ceil(datetime(2010, 1, 1, 12, 0))
datetime.datetime(2010, 1, 2, 0, 0)

round(date: datetime) → datetime¶

Returns a new date representing the closest interval boundary date to date.

Parameters:: date (datetime) – Date
Returns:: Rounded date
Return type:: datetime

Examples

>>> from datetime import datetime
>>> d3.time_day.round(datetime(2010, 1, 1, 12, 0))
datetime.datetime(2010, 1, 2, 0, 0)
>>> d3.time_day.round(datetime(2010, 1, 1, 1, 0))
datetime.datetime(2010, 1, 1, 0, 0)

range(start: datetime, stop: datetime, step: int = 1) → list[datetime]¶

Returns an array of dates representing every interval boundary after or equal to start (inclusive) and before stop (exclusive).

Parameters:

start (datetime) – Start date
stop (datetime) – Stop date
step (int) – Step

Returns:

Range of dates

Return type:

list[datetime]

Examples

>>> from datetime import datetime
>>> r = d3.time_day.range(datetime(2010, 1, 1), datetime(2010, 1, 5), step=1)
>>> for d in r:
...     print(d)
...
...
2010-01-01 00:00:00
2010-01-02 00:00:00
2010-01-03 00:00:00
2010-01-04 00:00:00
>>> r = d3.time_day.range(datetime(2010, 1, 1), datetime(2010, 1, 5), step=2)
>>> for d in r:
...     print(d)
...
...
2010-01-01 00:00:00
2010-01-03 00:00:00

classmethod filter(test: Callable[[datetime], bool]) → TimeInterval¶

Returns a new interval that is a filtered subset of this interval using the specified test function.

Parameters:: test (Callable[[datetime], bool]) – Function which returns True if and only if the specified date should be considered part of the interval
Returns:: Modified class with new floor and :code`offset` function.
Return type:: TimeFilter

A common method to these classes is count. For example, it counts the number of days for time_day():

>>> from datetime import datetime
>>> d3.time_day.count(datetime(2008, 1, 1), datetime(2008, 12, 31))
365