DateTime Fundamentals

DateTime Fundamentals in Pandas: Your Time-Traveling Toolkit 🕰️

Analogy: Think of datetime in Pandas like a super-smart calendar that not only knows what day it is, but can also tell you the hour, minute, second — and even do math with time!

The Story Begins…

Imagine you’re a detective investigating when events happened. You have a list of timestamps, and you need to answer questions like:

• “What day of the week did this happen?”
• “Was this in the morning or evening?”
• “How many days between these two events?”

Pandas gives you a magic magnifying glass called the dt accessor to inspect and manipulate dates and times with ease!

1. The DateTime Accessor: dt

What Is It?

The dt accessor is like a special key that unlocks all the secrets hidden inside a datetime column.

Simple Example:

import pandas as pd

# Create a Series with dates
dates = pd.Series(pd.to_datetime([
    '2024-03-15 14:30:00',
    '2024-07-04 09:15:00',
    '2024-12-25 18:45:00'
]))

# Use dt to peek inside!
print(dates.dt.year)
# Output: [2024, 2024, 2024]

Why Does This Matter?

Without dt, your dates are just text. With dt, you can ask questions about them!

graph TD
    A["DateTime Column"] --> B[".dt accessor"]
    B --> C["Year"]
    B --> D["Month"]
    B --> E["Day"]
    B --> F["Hour"]
    B --> G["And More!"]

2. Extracting DateTime Components

The Detective’s Toolkit

Just like taking apart a clock to see its gears, you can extract any part of a datetime.

All the pieces you can extract:

Real Example:

date = pd.Series(pd.to_datetime(['2024-03-15']))

print(date.dt.year[0])       # 2024
print(date.dt.month[0])      # 3
print(date.dt.day[0])        # 15
print(date.dt.day_name()[0]) # 'Friday'

Think of It Like This:

A birthday cake has layers. The dt accessor lets you taste each layer separately — the year frosting, the month sponge, the day filling!

3. DateTime Period Extraction

Grouping Time Into Buckets

Sometimes you don’t need the exact second. You need to know: “Which quarter of the year?” or “Which week?”

Period Properties:

Example:

dates = pd.Series(pd.to_datetime([
    '2024-01-15',  # Q1
    '2024-05-20',  # Q2
    '2024-09-10',  # Q3
    '2024-11-25'   # Q4
]))

print(dates.dt.quarter)
# Output: [1, 2, 3, 4]

print(dates.dt.dayofyear)
# Output: [15, 141, 254, 330]

Real-World Use:

“How many sales did we make in Q3?” — Period extraction makes this question easy to answer!

4. DateTime Boundary Checks

Is It the Start or End?

Pandas can check if a date is at the beginning or end of a time period. This is super useful for reports!

Boundary Properties:

Example:

dates = pd.Series(pd.to_datetime([
    '2024-01-01',  # Year start
    '2024-03-31',  # Quarter end
    '2024-06-15',  # Regular day
    '2024-12-31'   # Year end
]))

print(dates.dt.is_year_start)
# Output: [True, False, False, False]

print(dates.dt.is_quarter_end)
# Output: [False, True, False, True]

Why This Rocks:

Need to filter only month-end reports? One line of code:

df[df['date'].dt.is_month_end]

5. DatetimeIndex: The Supercharged Index

What’s Special About It?

When your DataFrame’s index is made of dates, magical things happen!

Creating a DatetimeIndex:

# Method 1: From a list
dates = pd.DatetimeIndex([
    '2024-01-01',
    '2024-01-02',
    '2024-01-03'
])

# Method 2: From a column
df = pd.DataFrame({
    'date': pd.to_datetime(['2024-01-01', '2024-01-02']),
    'value': [100, 200]
})
df = df.set_index('date')

The Magic Powers:

# Select all data from January 2024
df.loc['2024-01']

# Select a specific date
df.loc['2024-01-15']

# Select a date range
df.loc['2024-01-01':'2024-01-31']

graph TD
    A["DatetimeIndex"] --> B["Slice by Year"]
    A --> C["Slice by Month"]
    A --> D["Slice by Date Range"]
    A --> E["Time-based Resampling"]

6. Creating Date Ranges

Need 100 Dates? No Problem!

The pd.date_range() function is like a date factory. Tell it what you want, and it produces dates!

Basic Syntax:

pd.date_range(
    start='2024-01-01',
    end='2024-01-10'
)

Different Ways to Create Ranges:

# 7 consecutive days
pd.date_range(start='2024-01-01', periods=7)

# Every Monday in January
pd.date_range(
    start='2024-01-01',
    end='2024-01-31',
    freq='W-MON'
)

# First day of each month
pd.date_range(
    start='2024-01-01',
    periods=12,
    freq='MS'
)

# Every 6 hours
pd.date_range(
    start='2024-01-01',
    periods=8,
    freq='6H'
)

Frequency Codes Cheat Sheet:

7. Timedelta Operations: Math With Time

Adding and Subtracting Time

A Timedelta is a duration — how long something takes, or the gap between two moments.

Creating Timedeltas:

# Different ways to create
delta1 = pd.Timedelta(days=5)
delta2 = pd.Timedelta('2 hours 30 minutes')
delta3 = pd.Timedelta(weeks=2)

Time Math in Action:

date = pd.Timestamp('2024-03-15')

# Add 10 days
future = date + pd.Timedelta(days=10)
# Result: 2024-03-25

# Subtract 2 weeks
past = date - pd.Timedelta(weeks=2)
# Result: 2024-03-01

# Calculate difference between dates
date1 = pd.Timestamp('2024-01-01')
date2 = pd.Timestamp('2024-03-15')
diff = date2 - date1
print(diff.days)  # 74 days

With a DataFrame:

df = pd.DataFrame({
    'start': pd.to_datetime(['2024-01-01', '2024-02-15']),
    'end': pd.to_datetime(['2024-01-10', '2024-03-01'])
})

# Calculate duration
df['duration'] = df['end'] - df['start']
# Output: [9 days, 15 days]

# Add processing time
df['deadline'] = df['end'] + pd.Timedelta(days=7)

graph TD
    A["Date 1"] -->|subtract| B["Timedelta"]
    C["Date 2"] -->|subtract| B
    B --> D["Duration in days/hours/etc"]

    E["Date"] -->|+ Timedelta| F["Future Date"]
    E -->|– Timedelta| G["Past Date"]

Putting It All Together

Here’s a complete example showing everything working together:

import pandas as pd

# Create sample data
df = pd.DataFrame({
    'event': ['Meeting', 'Launch', 'Review'],
    'timestamp': pd.to_datetime([
        '2024-03-15 09:00:00',
        '2024-06-30 14:30:00',
        '2024-12-31 17:00:00'
    ])
})

# Extract components
df['year'] = df['timestamp'].dt.year
df['month'] = df['timestamp'].dt.month_name()
df['quarter'] = df['timestamp'].dt.quarter
df['is_quarter_end'] = df['timestamp'].dt.is_quarter_end

# Add 30 days follow-up
df['follow_up'] = df['timestamp'] + pd.Timedelta(days=30)

print(df)

Key Takeaways

1. dt accessor = Your key to unlock datetime secrets
2. Extract components = Pull out year, month, day, hour, etc.
3. Period extraction = Get quarters, weeks, day of year
4. Boundary checks = Is it month start/end, year start/end?
5. DatetimeIndex = Makes slicing by date super easy
6. pd.date_range() = Factory for creating date sequences
7. Timedelta = Do math with time (add/subtract days, hours, etc.)

Remember: Time is just another type of data. With Pandas datetime tools, you become a time wizard — able to slice, extract, compare, and calculate with dates as easily as with numbers!

🎉 You’re now ready to wrangle any datetime data that comes your way!