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 numpy

import pyinterp


def make_date(samples: int = 10) -> numpy.ndarray:
    """Generate random dates between 1970 and 2025."""
    generator = numpy.random.default_rng(0)
    epoch = numpy.datetime64("1970-01-01", "ns")
    delta = numpy.datetime64("2025-01-01", "ns") - epoch

    offsets = generator.random(samples) * delta.astype("int64")
    return epoch + offsets.astype("timedelta64[ns]")


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

Sample dates:
['2005-01-12T22:09:36.282300160' '1984-11-02T17:53:13.298126528'
 '1972-04-03T02:48:39.371404184' '1970-11-29T00:34:05.099458452'
 '2014-09-24T18:51:36.169425152' '2020-03-15T08:19:22.822937856'
 '2003-05-14T16:56:46.987026048' '2010-02-14T20:33:14.135691776'
 '1999-11-25T21:10:43.986623232' '2021-06-06T16:04:41.215222016']

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 tuple of three NumPy arrays: the years, the months and the days.

date_components = pyinterp.dateutils.date(dates)
print("Date components:")
print(date_components)

Date components:
(array([2005, 1984, 1972, 1970, 2014, 2020, 2003, 2010, 1999, 2021],
      dtype=int32), array([ 1, 11,  4, 11,  9,  3,  5,  2, 11,  6], dtype=uint8), array([12,  2,  3, 29, 24, 15, 14, 14, 25,  6], dtype=uint8))

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("Time components:")
print(time_components)

Time components:
(array([22, 17,  2,  0, 18,  8, 16, 20, 21, 16], dtype=uint8), array([ 9, 53, 48, 34, 51, 19, 56, 33, 10,  4], dtype=uint8), array([36, 13, 39,  5, 36, 22, 46, 14, 43, 41], dtype=uint8))

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("ISO calendar:")
print(iso_calendar)

ISO calendar:
(array([2005, 1984, 1972, 1970, 2014, 2020, 2003, 2010, 1999, 2021],
      dtype=int32), array([ 2, 44, 14, 48, 39, 11, 20,  6, 47, 22], dtype=uint8), array([3, 5, 1, 7, 3, 7, 3, 7, 4, 7], dtype=uint8))

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("Weekday (Sunday=0):")
print(weekday)

Weekday (Sunday=0):
[3 5 1 0 3 0 3 0 4 0]

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("Time since January 1st:")
print(timedelta)

Time since January 1st:
[ 1030176282300160 26502793298126528  8045319371404184 28686845099458452
 23050296169425152  6423562822937856 11552206987026048  3875594135691776
 28415443986623232 13536281215222016]