Python Pandas - Create a time interval and use Timestamps as the bounds

To create a time interval with Timestamps as bounds, use pandas.Interval combined with pandas.Timestamp. This allows you to define precise time ranges for data analysis and filtering operations.

Basic Time Interval Creation

First, import pandas and create a time interval using timestamps ?

import pandas as pd

# Create a time interval with timestamp bounds
interval = pd.Interval(
    pd.Timestamp('2020-01-01 00:00:00'), 
    pd.Timestamp('2021-01-01 00:00:00'), 
    closed='left'
)

print("Time Interval:")
print(interval)
print("\nInterval Length:")
print(interval.length)

Time Interval:
[2020-01-01, 2021-01-01)

Interval Length:
366 days 00:00:00

Understanding the Closed Parameter

The closed parameter determines which endpoint is included in the interval ?

import pandas as pd

start = pd.Timestamp('2023-01-01')
end = pd.Timestamp('2023-01-02')

# Left-closed interval [start, end)
left_closed = pd.Interval(start, end, closed='left')
print("Left-closed:", left_closed)

# Right-closed interval (start, end]
right_closed = pd.Interval(start, end, closed='right')
print("Right-closed:", right_closed)

# Both endpoints included [start, end]
both_closed = pd.Interval(start, end, closed='both')
print("Both closed:", both_closed)

# Neither endpoint included (start, end)
neither_closed = pd.Interval(start, end, closed='neither')
print("Neither closed:", neither_closed)

Left-closed: [2023-01-01, 2023-01-02)
Right-closed: (2023-01-01, 2023-01-02]
Both closed: [2023-01-01, 2023-01-02]
Neither closed: (2023-01-01, 2023-01-02)

Practical Applications

Time intervals are useful for checking if timestamps fall within specific ranges ?

import pandas as pd

# Create a quarterly interval
q1_2023 = pd.Interval(
    pd.Timestamp('2023-01-01'), 
    pd.Timestamp('2023-04-01'), 
    closed='left'
)

# Test timestamps
test_dates = [
    pd.Timestamp('2022-12-31'),
    pd.Timestamp('2023-01-01'),
    pd.Timestamp('2023-02-15'),
    pd.Timestamp('2023-04-01')
]

print("Q1 2023 Interval:", q1_2023)
print("\nTesting timestamps:")
for date in test_dates:
    is_in_interval = date in q1_2023
    print(f"{date.strftime('%Y-%m-%d')}: {'Inside' if is_in_interval else 'Outside'}")

Q1 2023 Interval: [2023-01-01, 2023-04-01)

Testing timestamps:
2022-12-31: Outside
2023-01-01: Inside
2023-02-15: Inside
2023-04-01: Outside

Interval Properties

Time intervals provide useful properties for analysis ?

import pandas as pd

interval = pd.Interval(
    pd.Timestamp('2023-06-01 09:00:00'), 
    pd.Timestamp('2023-06-01 17:00:00'), 
    closed='both'
)

print("Interval:", interval)
print("Left bound:", interval.left)
print("Right bound:", interval.right)
print("Length:", interval.length)
print("Is empty:", interval.is_empty)
print("Closed type:", interval.closed)

Interval: [2023-06-01 09:00:00, 2023-06-01 17:00:00]
Left bound: 2023-06-01 09:00:00
Right bound: 2023-06-01 17:00:00
Length: 0 days 08:00:00
Is empty: False
Closed type: both

Conclusion

Use pd.Interval with pd.Timestamp to create precise time ranges. The closed parameter controls endpoint inclusion, making it perfect for time-based filtering and analysis operations.