scale_x_datetime ¶

Date-time position scale x.

Values are date-times (datetime, date, numpy and polars date-time columns) or milliseconds since the Unix epoch. Breaks fall on calendar boundaries (whole hours, days, Mondays, months, years) and are labelled by their spacing ("%b %e", "%Y", ...). Axes of date-time columns get this scale without asking for it. Labels are in UTC.

Parameters:

• name (str, default: None ) –

  Axis title (labs(x=...) takes precedence).

• breaks (list, default: None ) –

  Fixed break positions (date-times or epoch milliseconds).

• break_width (str, default: None ) –

  Fixed distance between breaks, as "<count> <unit>" with a unit of ms, sec, min, hour, day, week, month or year (plurals allowed), e.g. "2 weeks".

• labels (list of str or dict, default: None ) –

  One label per break (a dict maps breaks to labels). Ignored without breaks, as in lets-plot.

• format (str, default: None ) –

  Date-time label pattern ("%d.%m.%y", "%b %Y", "{%H:%M}"). labels take precedence.

• limits (list, default: None ) –

  [low, high] as date-times; None leaves a side free.

• expand (list, default: None ) –

  [multiplicative] or [multiplicative, additive] expansion; the additive part is in milliseconds.

• lablim (int | None, default: None ) –

  As in lets-plot; not drawn yet (ggrust warns).

• na_value (int | None, default: None ) –

  As in lets-plot; not drawn yet (ggrust warns).

• position (int | None, default: None ) –

  As in lets-plot; not drawn yet (ggrust warns).

Returns:

• FeatureSpec –

  Scale specification.

Examples:

>>> import datetime
>>> from ggrust import *
>>> days = [datetime.date(2024, 1, 1) + datetime.timedelta(days=d) for d in range(60)]
>>> data = {"day": days, "visitors": [100 + (d % 7) * 12 for d in range(60)]}
>>> plot = (
...     ggplot(data, aes("day", "visitors"))
...     + geom_line()
...     + scale_x_datetime(break_width="2 weeks", format="%d %b")
... )