Skip to main content

Python NumPy: How to Check for NaT (Not a Time) Values in Arrays

When working with date and time data in NumPy, especially after conversions or operations that might result in invalid or missing time information, you'll encounter NaT (Not a Time). NaT is NumPy's equivalent of NaN (Not a Number) specifically for datetime64 and timedelta64 data types. Identifying these NaT values is crucial for data cleaning, error handling, and ensuring the integrity of time-series analyses.

This guide will comprehensively demonstrate how to check for NaT values in NumPy arrays, primarily using the numpy.isnat() function. We'll also explore a more general approach using pandas.isnull() if you're working in an environment with Pandas, and a simpler string comparison method for individual scalar checks.

Understanding NaT (Not a Time) in NumPy​

NaT stands for "Not a Time" and is the missing value marker used in NumPy for arrays of datetime64 or timedelta64 data types. It's analogous to np.nan for floating-point numbers. You might encounter NaT when:

  • Parsing date/time strings that are invalid or can not be converted (e.g., an attempt to create np.datetime64('invalid-date-string') or from operations like pd.to_datetime(..., errors='coerce') if using Pandas to create the array).
  • Operations on datetimes result in an undefined time.
  • An array is explicitly initialized with np.datetime64('NaT').

It's important to distinguish NaT from np.nan (which is for floats) and Python's None.

The numpy.isnat(x) function tests element-wise if a value (or elements in an array) is NaT and returns a boolean or a boolean array. This function is specifically designed for NumPy's datetime64 and timedelta64 types.

Checking a Single Scalar Value for NaT​

import numpy as np

# Create a NaT value
nat_value = np.datetime64('NaT')
print(f"Value: {nat_value}")
print(f"Type of value: {type(nat_value)}")

# ✅ Check if the scalar is NaT
is_value_nat = np.isnat(nat_value)
print(f"Is the value NaT? {is_value_nat}")

if np.isnat(nat_value):
    print("This confirms the value is NaT.")
else:
    print("This value is NOT NaT.")

# Check a valid datetime64 value
valid_datetime = np.datetime64('2025-01-15')
print(f"Is '{valid_datetime}' NaT? {np.isnat(valid_datetime)}")

Output:

Value: NaT
Type of value: <class 'numpy.datetime64'>
Is the value NaT? True
This confirms the value is NaT.
Is '2025-01-15' NaT? False

Checking an Entire NumPy Array for NaT (Element-wise)​

If you pass a NumPy array (of datetime64 or timedelta64 dtype) to np.isnat(), it performs an element-wise check.

import numpy as np

# Create an array with datetime64 dtype, including NaT values
# It's good practice to specify a unit for NaT in an array context if mixed with valid dates
datetime_series = np.array([
    '2025-01-01', '2025-02-15', 'NaT', '2025-04-10', 'NaT'
], dtype='datetime64[D]') # 'D' for day precision

print("Original datetime64 array:")
print(datetime_series)

# ✅ Check the array for NaT values element-wise
nat_mask = np.isnat(datetime_series)
print("Boolean mask indicating NaT positions:")
print(nat_mask)

Output:

Original datetime64 array:
['2025-01-01' '2025-02-15'        'NaT' '2025-04-10'        'NaT']
Boolean mask indicating NaT positions:
[False False  True False  True]

The result nat_mask is a boolean array of the same shape as datetime_series, with True where the original element was NaT.

Important Note: np.isnat() and Pandas NaT​

The numpy.isnat() function is tailored for NumPy's datetime64 and timedelta64 NaT representations. It will raise a TypeError if you attempt to pass a pandas.NaT object directly to it.

import numpy as np
import pandas as pd # For pd.NaT

try:
    # ⛔️ TypeError: ufunc 'isnat' is only defined for datetime and timedelta.
    print(f"Attempting np.isnat(pd.NaT): {np.isnat(pd.NaT)}")
except TypeError as e:
    print(f"Error when using np.isnat() with pd.NaT: {e}")

Output:

Error when using np.isnat() with pd.NaT: ufunc 'isnat' is only defined for np.datetime64 and np.timedelta64.

If your workflow involves potential pd.NaT values, using pandas.isnull() (Method 2) is a more robust cross-library solution.

Method 2: Using pandas.isnull() (or pd.isna()) (Versatile for NumPy and Pandas NaT)​

If you have Pandas available in your environment, pandas.isnull() (or its identical alias pandas.isna()) provides a more general way to detect various types of missing values, including NaT from both NumPy and Pandas, np.nan, and Python's None.

First, ensure Pandas is installed (if not already):

pip install pandas numpy

Checking a Single NumPy NaT Value​

import numpy as np
import pandas as pd

numpy_nat_value = np.datetime64('NaT')

# ✅ Using pd.isnull() for a NumPy NaT
is_numpy_nat_via_pandas = pd.isnull(numpy_nat_value)
print(f"Is NumPy NaT '{numpy_nat_value}' considered null by Pandas? {is_numpy_nat_via_pandas}")

if pd.isnull(numpy_nat_value):
    print("Pandas correctly identifies the NumPy NaT value as missing.")

Output:

Is NumPy NaT 'NaT' considered null by Pandas? True
Pandas correctly identifies the NumPy NaT value as missing.

Checking a NumPy Array for NaT Values​

pd.isnull() also operates element-wise on NumPy arrays.

import numpy as np
import pandas as pd

# datetime_series from above
datetime_series = np.array([
    '2025-01-01', '2025-02-15', 'NaT', '2025-04-10', 'NaT'
], dtype='datetime64[D]') # 'D' for day precision

# ✅ Using pd.isnull() on a NumPy datetime64 array
nat_mask_pandas = pd.isnull(datetime_series)
print("Boolean mask from pd.isnull() indicating NaT/missing positions:")
print(nat_mask_pandas)

Output:

Boolean mask from pd.isnull() indicating NaT/missing positions:
[False False  True False  True]

Compatibility with Pandas pd.NaT​

The key advantage of pd.isnull() or pd.isna() is their ability to correctly identify both NumPy's np.datetime64('NaT') and Pandas' own pd.NaT as missing/NaT.

import numpy as np
import pandas as pd

print(f"pd.isnull(np.datetime64('NaT')): {pd.isnull(np.datetime64('NaT'))}")
print(f"pd.isnull(pd.NaT): {pd.isnull(pd.NaT)}")

# Using the alias isna()
print(f"pd.isna(np.datetime64('NaT')): {pd.isna(np.datetime64('NaT'))}")
print(f"pd.isna(pd.NaT): {pd.isna(pd.NaT)}")

Output:

pd.isnull(np.datetime64('NaT')): True
pd.isnull(pd.NaT): True
pd.isna(np.datetime64('NaT')): True
pd.isna(pd.NaT): True

Method 3: Checking by Converting to String (for Scalar Values Only)​

For a single NumPy datetime64('NaT') scalar value, converting it to a string using str() will result in the literal string "NaT". This can be used for a basic check, but it's generally less robust and not suitable for arrays or for pd.NaT.

import numpy as np

nat_value_scalar = np.datetime64('NaT')
valid_datetime_scalar = np.datetime64('2025-01-15')

# ✅ Check by string conversion
if str(nat_value_scalar) == 'NaT':
    print(f"The string representation of '{nat_value_scalar}' is 'NaT', indicating it's a NaT value.")
else:
    print(f"The string representation of '{nat_value_scalar}' is not 'NaT'.")

print(f"String representation of valid_datetime_scalar: '{str(valid_datetime_scalar)}'")
if str(valid_datetime_scalar) == 'NaT':
    print("This should not print for a valid date.") # Does not print

Output:

The string representation of 'NaT' is 'NaT', indicating it's a NaT value.
String representation of valid_datetime_scalar: '2025-01-15'

Limitations of this method:

  • It's only practical for individual scalar NumPy datetime64 values.
  • It relies on the specific string representation, which could be less safe than type-aware functions if other objects also stringify to "NaT".
  • It does not work for pd.NaT (which stringifies differently or might require different handling).

Conclusion​

Identifying NaT (Not a Time) values is crucial for accurate date and time data processing in Python.

  • For operations purely within NumPy using datetime64 or timedelta64 arrays and scalars, the numpy.isnat() function is the direct and intended tool.
  • If your workflow involves both NumPy and Pandas time objects, or if you need a general missing data checker, pandas.isnull() (or pandas.isna()) is the more versatile and recommended approach due to its ability to correctly handle NaT from both libraries, as well as np.nan and None.
  • Checking by string conversion (str(value) == 'NaT') is a limited technique best reserved for quick checks of single NumPy datetime64('NaT') scalars and is not a general solution.

Using the appropriate function (np.isnat() or pd.isnull()) will enable you to reliably detect NaT values and build robust conditional logic in your time-series data applications.

Table of Contents