Time scales¶

detroit.scale_time() → ScaleTime¶

detroit.scale_time(range_vals: list[T]) → ScaleTime

detroit.scale_time(domain: list[datetime], range_vals: list[T]) → ScaleTime

Builds a new time scale with the specified domain and range, the default interpolator and clamping disabled

Parameters:

domain (list[datetime]) – Array of datetime
range_vals (list[T]) – Array of values

Returns:

Scale object

Return type:

ScaleTime

Examples

>>> from datetime import datetime
>>> scale = d3.scale_time([datetime(2000, 1, 1), datetime(2000, 1, 2)], [0, 960])
>>> for x in range(24 + 1):
...     x = datetime(2000, 1, 1) + x * hour
...     print(x, scale(x))
...
...
2000-01-01 00:00:00 0.0
2000-01-01 01:00:00 40.0
2000-01-01 02:00:00 80.0
2000-01-01 03:00:00 120.0
2000-01-01 04:00:00 160.0
2000-01-01 05:00:00 200.0
2000-01-01 06:00:00 240.0
2000-01-01 07:00:00 280.0
2000-01-01 08:00:00 320.0
2000-01-01 09:00:00 360.0
2000-01-01 10:00:00 400.0
2000-01-01 11:00:00 440.0
2000-01-01 12:00:00 480.0
2000-01-01 13:00:00 520.0
2000-01-01 14:00:00 560.0
2000-01-01 15:00:00 600.0
2000-01-01 16:00:00 640.0
2000-01-01 17:00:00 680.0
2000-01-01 18:00:00 720.0
2000-01-01 19:00:00 760.0
2000-01-01 20:00:00 800.0
2000-01-01 21:00:00 840.0
2000-01-01 22:00:00 880.0
2000-01-01 23:00:00 920.0
2000-01-02 00:00:00 960.0

class detroit.scale.time.ScaleTime(ticks: Callable, tick_interval: Callable, year: Callable, month: Callable, week: Callable, day: Callable, hour: Callable, minute: Callable, second: Callable)¶

Time scales are a variant of linear scales that have a temporal domain: domain values are coerced to dates rather than numbers, and invert likewise returns a date. Time scales implement ticks based on calendar intervals, taking the pain out of generating axes for temporal domains.

Parameters:

ticks (Callable) – Ticks function
tick_interval (Callable) – Tick interval function
year (Callable) – Year time function
month (Callable) – Month time function
week (Callable) – Week time function
day (Callable) – Day time function
hour (Callable) – Hour time function
minute (Callable) – Minute time function
second (Callable) – Second time function

__call__(x: int | float | datetime) → T¶

Given a value from the domain, returns the corresponding value from the range.

Parameters:: x (int | float) – Input value
Returns:: Corresponding value from the range
Return type:: T

invert(y: T) → datetime¶

Given a value from the range, returns the corresponding value from the domain. Inversion is useful for interaction, say to determine the data value corresponding to the position of the mouse.

Parameters:: y (T) – Input value
Returns:: Corresponding value from the domain
Return type:: datetime

set_domain(domain)¶

Sets the scale’s domain to the specified array of numbers.

Parameters:: domain (list[Number] | list[datetime]) – Domain
Returns:: Itself
Return type:: Transformer[T]

set_range(range_vals)¶

Sets the scale’s range to the specified array of values

Parameters:: range_vals (list[T]) – Range values
Returns:: Itself
Return type:: Transformer[T]

set_range_round(range_vals: list[T]) → Transformer¶

Sets the scale’s range to the specified array of values and sets scale’s interpolator to interpolate_round.

Parameters:: range_vals (list[T]) – Range values
Returns:: Itself
Return type:: Transformer

set_clamp(clamp: bool) → Transformer¶

Enables or disables clamping.

Parameters:: clamp (bool) – Clamp value
Returns:: Itself
Return type:: Transformer

set_interpolate(interpolate: Callable[[T, T], Callable[[float], T]]) → Transformer[T]¶

Sets the scale’s range interpolator factory.

Parameters:: interpolate (Callable[[T, T], Callable[[float], T]]) – Interpolate function
Returns:: Itself
Return type:: Transformer[T]

set_unknown(unknown: Any) → Transformer¶

Sets the output value of the scale for undefined or NaN input values.

Parameters:: unknown (Any) – Unknown value
Returns:: Itself
Return type:: Transformer

ticks(count: int | None = None) → list[datetime]¶

Returns representative dates from the scale’s domain.

Parameters:: count (int | None) – Count may be specified to affect how many ticks are generated. If count is not specified, it defaults to 10.
Returns:: The returned tick values are uniformly-spaced (mostly), have sensible values (such as every day at midnight), and are guaranteed to be within the extent of the domain. Ticks are often used to display reference lines, or tick marks, in conjunction with the visualized data.
Return type:: list[datetime]

tick_format(_: int = 0, specifier: str | None = None) → Callable[[str], str]¶

Returns a formatter function suitable for displaying a tick value, automatically computing the appropriate precision based on the fixed interval between tick values. The specified count should have the same value as the count that is used to generate the tick values.

Parameters:

_ (int) – Count parameter, not used in this function, only exists for generic signature method
specifier (str | None) – Specifier

Returns:

Tick format function which returns a string

Return type:

Formatter[str]

nice(interval: Callable | list[datetime] | None = None) → ScaleTime¶

This method typically modifies the scale’s domain, and may only extend the bounds to the nearest round value.

Parameters:: interval (Callable | list[datetime] | None) – Argument which allows greater control over the step size used to extend the bounds, guaranteeing that the returned ticks will exactly cover the domain.
Returns:: Itself
Return type:: ScaleTime