polars.Series.dt.offset_by#

Series.dt.offset_by(by: str) → Series[source]#

Offset this date by a relative time offset.

This differs from pl.col("foo") + timedelta in that it can take months and leap years into account. Note that only a single minus sign is allowed in the by string, as the first character.

Parameters:
by

The offset is dictated by the following string language:

  • 1ns (1 nanosecond)

  • 1us (1 microsecond)

  • 1ms (1 millisecond)

  • 1s (1 second)

  • 1m (1 minute)

  • 1h (1 hour)

  • 1d (1 day)

  • 1w (1 week)

  • 1mo (1 calendar month)

  • 1q (1 calendar quarter)

  • 1y (1 calendar year)

  • 1i (1 index count)

Suffix with “_saturating” to indicate that dates too large for their month should saturate at the largest date (e.g. 2022-02-29 -> 2022-02-28) instead of erroring.

Returns:
Date/Datetime expression

Examples

>>> from datetime import datetime
>>> dates = pl.date_range(
...     datetime(2000, 1, 1), datetime(2005, 1, 1), "1y", eager=True
... )
>>> dates
shape: (6,)
Series: 'date' [datetime[μs]]
[
        2000-01-01 00:00:00
        2001-01-01 00:00:00
        2002-01-01 00:00:00
        2003-01-01 00:00:00
        2004-01-01 00:00:00
        2005-01-01 00:00:00
]
>>> dates.dt.offset_by("1y").alias("date_plus_1y")
shape: (6,)
Series: 'date_plus_1y' [datetime[μs]]
[
        2001-01-01 00:00:00
        2002-01-01 00:00:00
        2003-01-01 00:00:00
        2004-01-01 00:00:00
        2005-01-01 00:00:00
        2006-01-01 00:00:00
]
>>> dates.dt.offset_by("-1y2mo").alias("date_minus_1y_2mon")
shape: (6,)
Series: 'date_minus_1y_2mon' [datetime[μs]]
[
        1998-11-01 00:00:00
        1999-11-01 00:00:00
        2000-11-01 00:00:00
        2001-11-01 00:00:00
        2002-11-01 00:00:00
        2003-11-01 00:00:00
]

To get to the end of each month, combine with truncate:

>>> dates.dt.truncate("1mo").dt.offset_by("1mo").dt.offset_by("-1d")
shape: (6,)
Series: 'date' [datetime[μs]]
[
        2000-01-31 00:00:00
        2001-01-31 00:00:00
        2002-01-31 00:00:00
        2003-01-31 00:00:00
        2004-01-31 00:00:00
        2005-01-31 00:00:00
]