Date and Time Utilities

The pyinterp.dateutils module provides a set of utility functions for working with dates and times in NumPy arrays. These functions are designed to be fast and efficient, making it easy to perform common date and time calculations.

This example will walk you through the various functions available in the pyinterp.dateutils module.

Generating Sample Data

First, let’s create a set of random dates that we can use to demonstrate the functionality of the dateutils module.

import datetime
import random

import numpy

import pyinterp


def make_date(samples=10):
    """Generates random dates."""
    epoch = datetime.datetime(1970, 1, 1)
    delta = datetime.datetime.now() - datetime.datetime(1970, 1, 1)

    pydates = [epoch + random.random() * delta for _ in range(samples)]
    npdates = numpy.array(pydates).astype('datetime64[ns]')

    return npdates


dates = make_date()
print('Sample dates:')
print(dates)

Sample dates:
['2001-09-09T07:06:12.219069000' '2006-07-10T12:24:25.938311000'
 '1974-07-13T03:58:57.805171000' '1995-01-27T08:45:12.972766000'
 '2003-08-16T16:55:15.008058000' '1977-05-25T01:23:14.237655000'
 '1982-09-06T14:33:17.143426000' '2016-12-29T01:58:20.724200000'
 '2019-08-29T04:00:21.355532000' '1987-04-25T16:20:21.370392000']

Extracting Date Components

You can extract the date components (year, month, and day) from a NumPy array of dates using the pyinterp.dateutils.date function. This returns a structured NumPy array.

date_components = pyinterp.dateutils.date(dates)
print('\\nDate components:')
print(date_components)

\nDate components:
[(2001,  9,  9) (2006,  7, 10) (1974,  7, 13) (1995,  1, 27)
 (2003,  8, 16) (1977,  5, 25) (1982,  9,  6) (2016, 12, 29)
 (2019,  8, 29) (1987,  4, 25)]

Extracting Time Components

Similarly, you can extract the time components (hour, minute, and second) using the pyinterp.dateutils.time function.

time_components = pyinterp.dateutils.time(dates)
print('\\nTime components:')
print(time_components)

\nTime components:
[( 7,  6, 12) (12, 24, 25) ( 3, 58, 57) ( 8, 45, 12) (16, 55, 15)
 ( 1, 23, 14) (14, 33, 17) ( 1, 58, 20) ( 4,  0, 21) (16, 20, 21)]

ISO Calendar Information

The pyinterp.dateutils.isocalendar function returns the ISO calendar information (year, week number, and weekday) for each date.

iso_calendar = pyinterp.dateutils.isocalendar(dates)
print('\\nISO calendar:')
print(iso_calendar)

\nISO calendar:
[(2001, 36, 7) (2006, 28, 1) (1974, 28, 6) (1995,  4, 5) (2003, 33, 6)
 (1977, 21, 3) (1982, 36, 1) (2016, 52, 4) (2019, 35, 4) (1987, 17, 6)]

Weekday

You can get the day of the week (where Sunday is 0 and Saturday is 6) using the pyinterp.dateutils.weekday function.

weekday = pyinterp.dateutils.weekday(dates)
print('\\nWeekday (Sunday=0):')
print(weekday)

\nWeekday (Sunday=0):
[0 1 6 5 6 3 1 4 4 6]

Time Since January 1st

The pyinterp.dateutils.timedelta_since_january function calculates the time difference between each date and the first day of its corresponding year.

timedelta = pyinterp.dateutils.timedelta_since_january(dates)
print('\\nTime since January 1st:')
print(timedelta)

\nTime since January 1st:
[21711972219069000 16460665938311000 16689537805171000  2277912972766000
 19673715008058000 12446594237655000 21479597143426000 31370300724200000
 20750421355532000  9908421370392000]

Converting to datetime Objects

Finally, you can convert a NumPy array of dates to an array of Python’s native datetime.datetime objects using the pyinterp.dateutils.datetime function.

datetime_objects = pyinterp.dateutils.datetime(dates)
print('\\nDatetime objects:')
print(datetime_objects)

\nDatetime objects:
[datetime.datetime(2001, 9, 9, 7, 6, 12, 219069)
 datetime.datetime(2006, 7, 10, 12, 24, 25, 938311)
 datetime.datetime(1974, 7, 13, 3, 58, 57, 805171)
 datetime.datetime(1995, 1, 27, 8, 45, 12, 972766)
 datetime.datetime(2003, 8, 16, 16, 55, 15, 8058)
 datetime.datetime(1977, 5, 25, 1, 23, 14, 237655)
 datetime.datetime(1982, 9, 6, 14, 33, 17, 143426)
 datetime.datetime(2016, 12, 29, 1, 58, 20, 724200)
 datetime.datetime(2019, 8, 29, 4, 0, 21, 355532)
 datetime.datetime(1987, 4, 25, 16, 20, 21, 370392)]