Pandas dt.floor()

import pandas as pd

# create a series of datetime objects
datetime_series = pd.Series([
    pd.Timestamp('2023-01-01 15:23:35'),
    pd.Timestamp('2023-01-02 16:45:00'),
    pd.Timestamp('2023-01-03 17:10:30')
])

# use dt.floor() to round down to the nearest hour
floored_series = datetime_series.dt.floor('H')

print(floored_series)

'''
Output

0   2023-01-01 15:00:00
1   2023-01-02 16:00:00
2   2023-01-03 17:00:00
dtype: datetime64[ns]

'''

dt.floor() Syntax

The syntax of the dt.floor() method in Pandas is:

Series.dt.floor(freq)

dt.floor() Argument

The dt.floor() method takes following argument:

• freq - specifies the frequency level to which we want to round down.

Note: Common values the freq argument takes include D for day, H for hour, T or min for minute, etc.

dt.floor() Return Value

The dt.floor() method returns a new Series where each datetime object is rounded down to the nearest frequency specified in the argument.

Example 1: Round Down to Nearest Day

import pandas as pd

# create a Series of pd.Timestamp objects
timestamps = pd.Series([
    pd.Timestamp('2023-03-15 11:45:30'),
    pd.Timestamp('2023-03-16 23:59:59'),
    pd.Timestamp('2023-03-17 00:01:00')
])

# use dt.floor() to round down to the nearest day
floored_timestamps = timestamps.dt.floor('D')

print(floored_timestamps)

Output

0   2023-03-15
1   2023-03-16
2   2023-03-17
dtype: datetime64[ns]

In the above example, the timestamps Series contains three pd.Timestamp objects with times within different days.

When applying dt.floor('D'), each timestamp is rounded down to the start of its respective day.

Hence the output shows that each timestamp in timestamps has been rounded down to the midnight of the day it belongs to, effectively normalizing the time component to 00:00:00.

Example 2: Round Down to Nearest Hour

import pandas as pd

# create a Series of pd.Timestamp objects
timestamps = pd.Series([
    pd.Timestamp('2023-03-15 11:45:30'),
    pd.Timestamp('2023-03-15 22:59:59'),
    pd.Timestamp('2023-03-15 00:01:00')
])

# use dt.floor() to round down to the nearest hour
floored_timestamps = timestamps.dt.floor('H')

print(floored_timestamps)

Output

0   2023-03-15 11:00:00
1   2023-03-15 22:00:00
2   2023-03-15 00:00:00
dtype: datetime64[ns]

Here, by applying dt.floor('H'), each timestamp is rounded down to the start of the hour it falls in.

Example 3: Round Down to Nearest Minute

import pandas as pd

# create a Series of pd.Timestamp objects
timestamps = pd.Series([
    pd.Timestamp('2023-03-15 11:45:59'),  
    pd.Timestamp('2023-03-15 22:00:01'), 
    pd.Timestamp('2023-03-15 00:59:30')   
])

# use dt.floor() to round down to the nearest minute
floored_timestamps = timestamps.dt.floor('T')  

print(floored_timestamps)

Output

0   2023-03-15 11:45:00
1   2023-03-15 22:00:00
2   2023-03-15 00:59:00
dtype: datetime64[ns]

In this example, the dt.floor('T') method is used to round down to the nearest minute.

Note: We can also use min as dt.floor('min'), the output is the same.

Example 4: Round Down to Nearest Second

import pandas as pd

# create a Series of pd.Timestamp objects
timestamps = pd.Series([
    
    # timestamps with milliseconds
    pd.Timestamp('2023-03-15 11:45:30.123'),  
    pd.Timestamp('2023-03-15 22:00:00.987'),
    pd.Timestamp('2023-03-15 00:59:59.500')
])

# use dt.floor() to round down to the nearest second
floored_timestamps = timestamps.dt.floor('S')

print(floored_timestamps)

Output

0   2023-03-15 11:45:30
1   2023-03-15 22:00:00
2   2023-03-15 00:59:59
dtype: datetime64[ns]

In the above example, the timestamps Series contains pd.Timestamp objects that include milliseconds.

Then applying dt.floor('S') rounds down each timestamp to the nearest second, effectively truncating the milliseconds.