DateTime Arrays

🕐 NumPy DateTime Arrays: Your Time Machine!

The Story of Timekeeping

Imagine you have a magical calendar that can remember every birthday, every holiday, and every special moment—not just one, but millions of them at once! That’s what NumPy DateTime arrays do. They’re like super-powered calendars for your computer.

📅 What Are DateTime Arrays?

Think of a regular list of dates like sticky notes on a fridge. NumPy DateTime arrays are like having a digital assistant that organizes all those dates perfectly and can answer questions about them in the blink of an eye!

Creating Your First DateTime Array

import numpy as np

# One special date
birthday = np.datetime64('2024-06-15')
print(birthday)
# Output: 2024-06-15

# Many dates at once!
holidays = np.array([
    '2024-01-01',
    '2024-07-04',
    '2024-12-25'
], dtype='datetime64')
print(holidays)

What just happened? 🎉

• We told NumPy “these are dates, not just text”
• NumPy now understands them as points in time

🔢 Different Levels of Detail

Just like a clock can show hours, minutes, or seconds, NumPy can track time at different levels:

# Year only
year = np.datetime64('2024', 'Y')

# Down to the second
exact_moment = np.datetime64(
    '2024-06-15T14:30:45', 's'
)

🧮 DateTime Arithmetic: Math with Time!

Here’s where the magic happens! What if you could add days to a date or find out how many days between two events?

The Timedelta: Your Time-Adding Tool

A timedelta is like a “chunk of time” you can add or subtract.

import numpy as np

# Today's date
today = np.datetime64('2024-06-15')

# Add 7 days (one week!)
next_week = today + np.timedelta64(7, 'D')
print(next_week)
# Output: 2024-06-22

# Add 2 months
two_months = today + np.timedelta64(2, 'M')
print(two_months)
# Output: 2024-08

Real-Life Example: Countdown to Vacation! 🏖️

# When does school end?
school_ends = np.datetime64('2024-06-01')

# When does vacation start?
vacation = np.datetime64('2024-06-15')

# How many days to wait?
days_left = vacation - school_ends
print(days_left)
# Output: 14 days

📊 Working with Many Dates

NumPy shines when handling lots of dates at once!

Creating Date Ranges

# Every day in June 2024
june_days = np.arange(
    '2024-06-01',
    '2024-07-01',
    dtype='datetime64[D]'
)
print(f"June has {len(june_days)} days!")
# Output: June has 30 days!

Finding Differences Between Many Dates

# Project deadlines
deadlines = np.array([
    '2024-06-10',
    '2024-06-20',
    '2024-06-30'
], dtype='datetime64')

# Today
today = np.datetime64('2024-06-05')

# Days until each deadline
days_remaining = deadlines - today
print(days_remaining)
# Output: [5 days, 15 days, 25 days]

🎯 Common Timedelta Units

graph LR
    A["timedelta64"] --> B["Years - Y"]
    A --> C["Months - M"]
    A --> D["Weeks - W"]
    A --> E["Days - D"]
    A --> F["Hours - h"]
    A --> G["Minutes - m"]
    A --> H["Seconds - s"]

Quick Examples

# Add 3 weeks
np.timedelta64(3, 'W')

# Subtract 48 hours
np.timedelta64(-48, 'h')

# Add 90 minutes
np.timedelta64(90, 'm')

🎂 Putting It All Together: Birthday Calculator

Let’s build something fun! A program that calculates how old someone is:

import numpy as np

# Birth date
birth = np.datetime64('2015-03-20')

# Today
today = np.datetime64('2024-06-15')

# Age in days
age_days = today - birth
print(f"You are {age_days} old!")

# Convert to years (approximately)
days_int = age_days.astype('int')
age_years = days_int // 365
print(f"That's about {age_years} years!")

Output:

You are 3375 days old!
That's about 9 years!

💡 Pro Tips

1. Comparing Dates is Easy!

date1 = np.datetime64('2024-06-15')
date2 = np.datetime64('2024-12-25')

print(date1 < date2)  # True
print(date1 == date2) # False

2. Find Min and Max Dates

events = np.array([
    '2024-03-15',
    '2024-01-20',
    '2024-06-10'
], dtype='datetime64')

earliest = np.min(events)
latest = np.max(events)
print(f"First: {earliest}")
print(f"Last: {latest}")

3. Sorting Dates

sorted_events = np.sort(events)
print(sorted_events)
# Output: ['2024-01-20' '2024-03-15'
#          '2024-06-10']

🌟 Why This Matters

DateTime arrays help you:

• 📈 Track stock prices over time
• 🏃 Analyze workout schedules
• 🌡️ Study weather patterns
• 📧 Manage email timestamps
• 🎮 Log game events

You now have a superpower: the ability to manipulate time in your programs! Well, at least the representation of time. 😄

🎯 Quick Reference

Remember: Just like a calendar helps you plan your week, NumPy DateTime arrays help your programs plan with millions of dates at once. That’s pretty cool! 🚀