floor_date

floor_date(idx, unit='D', engine='pandas')

Robust date flooring.

The floor_date function takes a pandas Series of dates and returns a new Series with the dates rounded down to the specified unit. It’s more robust than the pandas floor function, which does weird things with irregular frequencies like Month which are actually regular.

Parameters

Name	Type	Description	Default
`idx`	pd.Series or pd.DatetimeIndex	The `idx` parameter is a pandas Series or pandas DatetimeIndex object that contains datetime values. It represents the dates that you want to round down.	required
`unit`	str	The `unit` parameter in the `floor_date` function is a string that specifies the time unit to which the dates in the `idx` series should be rounded down. It has a default value of “D”, which stands for day. Other possible values for the `unit` parameter could be.	`'D'`
`engine`	str	The `engine` parameter is used to specify the engine to use for calculating the floor datetime. It can be either “pandas” or “polars”. - The default value is “pandas”. - When “polars”, the function will internally use the `polars` library for calculating the floor datetime. This can be faster than using “pandas” for large datasets.	`'pandas'`

Returns

Type	Description
pd.Series	The `floor_date` function returns a pandas Series object containing datetime64[ns] values.

Examples

import pytimetk as tk
import pandas as pd

dates = pd.date_range("2020-01-01", "2020-01-10", freq="1H")
dates

DatetimeIndex(['2020-01-01 00:00:00', '2020-01-01 01:00:00',
               '2020-01-01 02:00:00', '2020-01-01 03:00:00',
               '2020-01-01 04:00:00', '2020-01-01 05:00:00',
               '2020-01-01 06:00:00', '2020-01-01 07:00:00',
               '2020-01-01 08:00:00', '2020-01-01 09:00:00',
               ...
               '2020-01-09 15:00:00', '2020-01-09 16:00:00',
               '2020-01-09 17:00:00', '2020-01-09 18:00:00',
               '2020-01-09 19:00:00', '2020-01-09 20:00:00',
               '2020-01-09 21:00:00', '2020-01-09 22:00:00',
               '2020-01-09 23:00:00', '2020-01-10 00:00:00'],
              dtype='datetime64[ns]', length=217, freq='H')

# Pandas fails to floor Month
# dates.floor("M") # ValueError: <MonthEnd> is a non-fixed frequency

# floor_date works as expected
tk.floor_date(dates, unit="M", engine='pandas')

0     2020-01-01
1     2020-01-01
2     2020-01-01
3     2020-01-01
4     2020-01-01
         ...    
212   2020-01-01
213   2020-01-01
214   2020-01-01
215   2020-01-01
216   2020-01-01
Name: idx, Length: 217, dtype: datetime64[ns]