NumPy - Time Zone Handling

Time Zone Handling in NumPy

Time zone handling in NumPy allows you to manage datetime data across different time zones. This is important when working with global time-based data, such as stock market timestamps, weather data, or international events, where time zone conversions are required for accurate analysis.

While NumPy doesn't have built-in support for time zones like some other libraries (e.g., 'pytz' or 'pandas'), it does allow you to work with datetime objects, and you can use external libraries like 'pytz' for time zone conversion.

NumPy's datetime64 objects are timezone-naive, meaning they don't store time zone information, but you can manually adjust them using compatible tools.

Handling Time Zones with 'datetime64'

By default, the 'datetime64' objects in NumPy are time zone-naive, which means they don't store time zone information. If you need to handle time zones explicitly, you need to combine NumPy with libraries like 'pytz' or 'timezone' from the 'datetime' module in Python.

To convert time zones or handle time zone-aware datetime data, you can use external tools in combination with NumPy arrays to manage the conversion and alignment of datetimes across different time zones.

Example

In the following example, we will combine NumPy with the 'pytz' library to handle time zone conversions. First, we will create a datetime array using NumPy and then adjust the datetime to a different time zone −

import numpy as np
import pytz
from datetime import datetime

# Define a datetime array
dates = np.array(['2024-01-01T12:00', '2024-01-02T12:00'], dtype='datetime64[m]')

# Convert to Python datetime objects
# Use astype('O') to convert datetime64 to datetime object
dt_objects = [d.item() for d in dates]

# Define the timezone using pytz
timezone = pytz.timezone('US/Eastern')

# Convert each datetime to the new time zone
localized_dates = [timezone.localize(dt) for dt in dt_objects]

# Print the localized times
for date in localized_dates:
   print(date.strftime('%Y-%m-%d %H:%M:%S %Z%z'))

The output will display the datetime values converted to the Eastern Time Zone (ET) −

2024-01-01 12:00:00 EST-0500
2024-01-02 12:00:00 EST-0500

Converting Between Time Zones

When working with datetime data, converting between time zones is often necessary. This can be done using external libraries like 'pytz'. After creating a time zone-aware datetime object, you can easily convert it to another time zone by using the astimezone() method.

Example

In the following example, we will first convert a datetime object to Eastern Standard Time (EST), and then convert it to Pacific Standard Time (PST) −

import pytz
from datetime import datetime

# Create a datetime object
dt = datetime(2024, 1, 1, 12, 0, 0)

# Define the timezone (Eastern Time Zone)
eastern = pytz.timezone('US/Eastern')

# Localize the datetime to Eastern Time
localized_dt = eastern.localize(dt)

# Convert to Pacific Time Zone
pacific = pytz.timezone('US/Pacific')
pacific_dt = localized_dt.astimezone(pacific)

print("Eastern Time: ", localized_dt.strftime('%Y-%m-%d %H:%M:%S %Z%z'))
print("Pacific Time: ", pacific_dt.strftime('%Y-%m-%d %H:%M:%S %Z%z'))

After executing the above code, you will get the following output −

Eastern Time:  2024-01-01 12:00:00 EST-0500
Pacific Time:  2024-01-01 09:00:00 PST-0800

Aligning Time Zones in Data

When working with multiple time zones in data, it is important to align datetime data across different time zones. You may need to convert all datetimes to a common time zone (e.g., UTC) to ensure accurate comparisons and calculations.

You can align time zone-aware datetimes to a common time zone by converting each datetime object to that time zone. This can be done using the same 'pytz' library or the 'datetime' module for adjustments.

Example

In this example, we will align two datetime objects from different time zones to UTC −

import pytz
from datetime import datetime

# Create two datetime objects in different time zones
dt1 = datetime(2024, 1, 1, 12, 0, 0, tzinfo=pytz.timezone('US/Eastern'))
dt2 = datetime(2024, 1, 1, 12, 0, 0, tzinfo=pytz.timezone('US/Pacific'))

# Convert both datetimes to UTC
dt1_utc = dt1.astimezone(pytz.utc)
dt2_utc = dt2.astimezone(pytz.utc)

# Print both datetime objects in UTC
print("Eastern to UTC: ", dt1_utc.strftime('%Y-%m-%d %H:%M:%S %Z%z'))
print("Pacific to UTC: ", dt2_utc.strftime('%Y-%m-%d %H:%M:%S %Z%z'))

The output will show both datetimes aligned to UTC −

Eastern to UTC:  2024-01-01 16:56:00 UTC+0000
Pacific to UTC:  2024-01-01 19:53:00 UTC+0000