NumPy - Creating Datetime Arrays

---

---

Datetime Arrays in NumPy

Datetime arrays are arrays that hold date and time values. NumPy provides the datetime64 and timedelta64 data types for handling dates and times with a wide range of precision.

The "datetime64" type represents dates and times, while "timedelta64" represents differences between dates or times.

Creating Datetime Arrays

In NumPy, we can create datetime arrrays using the array() function and the datetime64() function −

Using the np.array() Function

You can create a datetime array by specifying date strings or timestamps with the numpy.array() function. You need to specify the dtype as datetime64 to ensure that the array elements are treated as datetime objects.

Following is the syntax −

numpy.array(object, dtype=None, copy=True, order='K', subok=False, ndmin=0)

Where,

• object: This is the input data (e.g., list, tuple, or other array-like objects) that you want to convert into a NumPy array.
• dtype: Specifies the desired data type of the array elements. If not provided, NumPy will infer the data type from the input data.
• copy: If True, the function will create a copy of the input data. If False, a copy is made only if necessary.
• order: Specifies the memory layout order. 'C' is for row-major (C-style) order, 'F' is for column-major (Fortran-style) order, and 'A' or 'K' can be used for automatic order selection.
• subok: If True, subclasses of ndarray are passed-through; if False, the returned array will be forced to be a base-class ndarray.
• ndmin: Specifies the minimum number of dimensions that the resulting array should have. If necessary, new axes are added to the left of the shape.

Example

In the following example, we are converting a list of date strings into a NumPy array by passing the "dtype" parameter to the array() function −

import numpy as np

# Creating a datetime array using date strings
dates = np.array(['2024-08-01', '2024-08-15', '2024-09-01'], dtype='datetime64')

print("Datetime Array:\n", dates)

Following is the output obtained −

Datetime Array:
 ['2024-08-01' '2024-08-15' '2024-09-01']

Using the np.datetime64() Function

The datetime64() function in NumPy is used to create arrays of dates and times. This function provides a way to work with date and time data, enabling operations on time series data. The "datetime64" data type allows for date and time precision down to the "nanosecond" level.

Following is the syntax −

numpy.datetime64(datetime_string, unit)

Where,

• datetime_string: It is a string representing the date and/or time. The format of this string must match the unit specified.
• unit (optional): It specifies the time unit (e.g., Y, M, D, h, m, s, ms, us, ns). The unit defines the precision of the date and time representation.

Example

Here, we create individual datetime objects and retrieve an array of "datetime64" objects created from specified dates −

import numpy as np

# Creating individual datetime objects
date1 = np.datetime64('2024-08-01')
date2 = np.datetime64('2024-08-15')

# Creating an array of datetime objects
dates = np.array([date1, date2, np.datetime64('2024-09-01')])

print("Datetime Array:\n", dates)

This will produce the following result −

Datetime Array:
['2024-08-01' '2024-08-15' '2024-09-01']

Creating Datetime Arrays with Specific Frequencies

Creating datetime arrays with specific frequencies in NumPy allows you to generate sequences of dates or times that follow a regular interval, such as daily, monthly, hourly, etc.

In NumPy, you can create datetime arrays with specific frequencies using the np.arange() or np.linspace() functions in combination with datetime64 data types. These functions allow you to generate evenly spaced datetime values between a start and end date or time.

Using the np.arange() Function

The np.arange() function is used to create datetime arrays with a specified frequency. The key parameters include the start date or time, the end date or time, and the step (frequency) between consecutive datetime values. Following is the syntax −

numpy.arange(start, stop, step, dtype='datetime64')

Where,

• start: It is the starting date or time in datetime64 format.
• stop: It is the ending date or time (exclusive) in datetime64 format.
• step: It is the frequency or interval between consecutive dates/times, specified using timedelta64.
• dtype: It is the data type, which should be 'datetime64'.

Example

In the example below, we are creating an array of dates from "August 1, 2024" to "August 10, 2024", with a daily frequency −

import numpy as np

# Creating a daily datetime array
dates = np.arange('2024-08-01', '2024-08-11', dtype='datetime64[D]')
print("Daily Datetime Array:", dates)

Following is the output of the above code −

Daily Datetime Array: ['2024-08-01' '2024-08-02' '2024-08-03' '2024-08-04' '2024-08-05'
 '2024-08-06' '2024-08-07' '2024-08-08' '2024-08-09' '2024-08-10']

Using the np.linspace() Function

While np.arange() function is commonly used for creating datetime arrays with specific frequencies, np.linspace()function can also be used when you want to specify the number of points between two datetime values rather than the interval. Following is the syntax −

numpy.linspace(start, stop, num, dtype='datetime64')

Where,

• start: It is the starting datetime value "datetime64" format.
• stop: It is the ending datetime value "datetime64" format.
• num: It is the number of datetime values to generate between start and stop.
• dtype: It is the data type, which should be 'datetime64'.

Example

In this example, we are creating a datetime array with 5 evenly spaced datetime values between the start and end dates −

import numpy as np

# Convert start and end dates to datetime64
start_date = np.datetime64('2024-08-01')
end_date = np.datetime64('2024-08-10')

# Calculate the difference in days between start and end
date_range = np.arange(start_date, end_date + np.timedelta64(1, 'D'))

# Use linspace on the integer values of dates
datetimes = np.linspace(0, len(date_range)-1, num=5, dtype=int)

# Map back to the original date range
datetime_array = start_date + datetimes.astype('timedelta64[D]')

print("Datetime Array with 5 Points:", datetime_array)

The output obtained is as shown below −

Datetime Array with 5 Points: ['2024-08-01' '2024-08-03' '2024-08-05' '2024-08-07' '2024-08-10']

Creating Time Arrays

Creating time arrays in NumPy involves generating sequences of time-related values, such as hours, minutes, or seconds, similar to how you would create arrays of dates.

In NumPy, you can create time arrays using the datetime64 and timedelta64 data types. While "datetime64" is used for absolute points in time (such as a specific date and time), "timedelta64" represents a duration (such as hours or minutes). By combining these types, you can create arrays of time values that represent specific moments or intervals.

Example

The following example produces a time array starting at midnight and ending at noon, with each element representing a specific hour −

import numpy as np

# Define the start and end times
start_time = np.datetime64('2024-08-01T00:00')
end_time = np.datetime64('2024-08-01T12:00')

# Create an array of hourly intervals
time_array = np.arange(start_time, end_time, np.timedelta64(1, 'h'))

print("Time Array:", time_array)

After executing the above code, we get the following output −

Time Array: 
['2024-08-01T00:00' '2024-08-01T01:00' '2024-08-01T02:00'
 '2024-08-01T03:00' '2024-08-01T04:00' '2024-08-01T05:00'
 '2024-08-01T06:00' '2024-08-01T07:00' '2024-08-01T08:00'
 '2024-08-01T09:00' '2024-08-01T10:00' '2024-08-01T11:00']

Combining Date and Time

Combining date and time involves creating a "datetime64" object that consists of both the date and the specific time of day.

You can create a datetime64 array by specifying the date and time in a single string, or by combining separate date and time arrays using NumPy's vectorized operations.

Example

In this example, we create an array where each element represents a specific date and time −

import numpy as np

# Creating datetime arrays with date and time
datetimes = np.array([np.datetime64('2024-08-01T08:00:00'), 
                      np.datetime64('2024-08-02T12:30:00'), 
                      np.datetime64('2024-08-03T16:45:00')])

print("Datetime Array with Date and Time:\n", datetimes)

The result produced is as follows −

Datetime Array with Date and Time:
 ['2024-08-01T08:00:00' '2024-08-02T12:30:00' '2024-08-03T16:45:00']