Python Pandas - Snap time stamps in DateTimeIndex to nearest occurring frequency

To snap time stamps in DateTimeIndex to nearest occurring frequency, use the DateTimeIndex.snap() method. This method rounds timestamps to the nearest frequency boundary, such as month-end, week-start, or any other valid frequency.

Syntax

DateTimeIndex.snap(freq)

Parameters

• freq: A frequency string (e.g., 'M' for month-end, 'W' for week, 'D' for day)

Basic Example

Let's create a DateTimeIndex and snap timestamps to the nearest month-end ?

import pandas as pd

# Create DatetimeIndex with period 6 and frequency as D i.e. day
# The timezone is Australia/Adelaide
datetimeindex = pd.date_range('2021-10-20 02:30:50', periods=6, tz='Australia/Adelaide', freq='D')

# Display DateTimeIndex
print("DateTimeIndex...")
print(datetimeindex)

# Display DateTimeIndex frequency
print("\nDateTimeIndex frequency:")
print(datetimeindex.freq)

# Snap time stamps to nearest occurring month-end
print("\nSnap time stamps to nearest month-end:")
snapped = datetimeindex.snap(freq='M')
print(snapped)

DateTimeIndex...
DatetimeIndex(['2021-10-20 02:30:50+10:30', '2021-10-21 02:30:50+10:30',
               '2021-10-22 02:30:50+10:30', '2021-10-23 02:30:50+10:30',
               '2021-10-24 02:30:50+10:30', '2021-10-25 02:30:50+10:30'],
              dtype='datetime64[ns, Australia/Adelaide]', freq='D')

DateTimeIndex frequency:
<Day>

Snap time stamps to nearest month-end:
DatetimeIndex(['2021-10-31 02:30:50+10:30', '2021-10-31 02:30:50+10:30',
               '2021-10-31 02:30:50+10:30', '2021-10-31 02:30:50+10:30',
               '2021-10-31 02:30:50+10:30', '2021-10-31 02:30:50+10:30'],
              dtype='datetime64[ns, Australia/Adelaide]', freq=None)

Different Frequency Examples

You can snap to different frequencies like week-start or business day-end ?

import pandas as pd

# Create a DateTimeIndex with irregular timestamps
timestamps = pd.DatetimeIndex(['2021-10-20 14:30:25', '2021-10-22 09:15:40', '2021-10-25 16:45:10'])

print("Original timestamps:")
print(timestamps)

# Snap to week-start (Monday)
print("\nSnap to week-start:")
print(timestamps.snap(freq='W-MON'))

# Snap to business day-end
print("\nSnap to business day-end:")
print(timestamps.snap(freq='B'))

Original timestamps:
DatetimeIndex(['2021-10-20 14:30:25', '2021-10-22 09:15:40',
               '2021-10-25 16:45:10'],
              dtype='datetime64[ns]', freq=None)

Snap to week-start:
DatetimeIndex(['2021-10-18 14:30:25', '2021-10-25 09:15:40',
               '2021-10-25 16:45:10'],
              dtype='datetime64[ns]', freq=None)

Snap to business day-end:
DatetimeIndex(['2021-10-20 14:30:25', '2021-10-22 09:15:40',
               '2021-10-25 16:45:10'],
              dtype='datetime64[ns]', freq=None)

Key Points

• The snap() method preserves the time component while adjusting the date
• Common frequencies: 'M' (month-end), 'MS' (month-start), 'W' (week), 'D' (day)
• The original timezone information is preserved in the result
• After snapping, the frequency attribute becomes None

Conclusion

The snap() method is useful for aligning timestamps to specific frequency boundaries like month-end or week-start. It preserves time components while adjusting dates to the nearest occurrence of the specified frequency.