siuba.experimental.datetime

floor_date, ceil_date

siuba.experimental.datetime.floor_date(x, unit='S')
siuba.experimental.datetime.floor_date(__data: siuba.siu.Symbolic, *args, **kwargs)
siuba.experimental.datetime.floor_date(__data: siuba.siu.Call, *args, **kwargs)
siuba.experimental.datetime.floor_date(x: abc.DatetimeType, unit='S')
siuba.experimental.datetime.floor_date(x: abc.PeriodType, unit='S')
siuba.experimental.datetime.floor_date(x: pandas.core.series.Series, *args, **kwargs)

floor_date and ceil_date return dates rounded to nearest specified unit.

Parameters

  • x – a DatetimeIndex, PeriodIndex, or their underlying arrays or elements.

  • units – a date or time unit for rounding (eg. “MS” rounds down or up to the start of a month)

Note

For a full list of units run the following:

::

from pandas.tseries.offsets import prefix_mapping

Common time units include seconds (S), minute (T), hour (H), week (W). Some date units are month end (M), month start (MS), year start (AS)

The main feature of floor_date is that it works on things like Months, which is not supported in the floor method.

>>> import pandas as pd
>>> a_date = "2020-02-02 02:02:02"
>>> dti = pd.DatetimeIndex([a_date])
>>> dti.floor("MS")
Traceback (most recent call last):
...
ValueError: <MonthBegin> is a non-fixed frequency

Month start will always go to the first day of a month.

>>> floor_date(dti, "MS")
DatetimeIndex(['2020-02-01'], dtype='datetime64[ns]', freq=None)

>>> ceil_date(dti, "MS")
DatetimeIndex(['2020-03-01'], dtype='datetime64[ns]', freq=None)

On the other hand, here is month end.

>>> floor_date(dti, "M")
DatetimeIndex(['2020-01-31'], dtype='datetime64[ns]', freq=None)

>>> ceil_date(dti, "M")
DatetimeIndex(['2020-02-29'], dtype='datetime64[ns]', freq=None)

It also works on things supported by the Series.dt.floor method, like hours.

>>> floor_date(dti, "H")
DatetimeIndex(['2020-02-02 02:00:00'], dtype='datetime64[ns]', freq=None)

You can also use it on other types, like a PeriodIndex

>>> per = pd.PeriodIndex([a_date], freq = "S")
>>> floor_date(per, "M")
PeriodIndex(['2020-02'], dtype='period[M]', freq='M')