🔍 Code Extractor

Checks if a value is NaT (Not-a-Time), a special marker for missing or invalid datetime/timedelta values in NumPy and pandas.

Purpose

This function provides a unified interface to detect NaT values across different datetime-like types including NumPy datetime64/timedelta64, pandas NaT, and pandas datetime/timedelta types. It handles version compatibility for NumPy (pre and post 1.13) and provides fallback logic for different data structures. This is useful when working with temporal data that may contain missing values.

Source Code

def isnat(val):
    """
    Checks if the value is a NaT. Should only be called on datetimelike objects.
    """
    if (isinstance(val, (np.datetime64, np.timedelta64)) or
        (isinstance(val, np.ndarray) and val.dtype.kind == 'M')):
        if numpy_version >= LooseVersion('1.13'):
            return np.isnat(val)
        else:
            return val.view('i8') == nat_as_integer
    elif pd and val is pd.NaT:
        return True
    elif pd and isinstance(val, pandas_datetime_types+pandas_timedelta_types):
        return pd.isna(val)
    else:
        return False

Parameters

Parameter Details

val: A datetimelike object to check for NaT status. Expected types include np.datetime64, np.timedelta64, numpy arrays with datetime dtype, pandas NaT, pandas datetime types, or pandas timedelta types. Should only be called on temporal/datetimelike objects.

Return Value

Returns a boolean value: True if the input value is NaT (Not-a-Time), False otherwise. For numpy arrays with datetime dtype, returns the result of np.isnat() which may be an array of booleans.

Dependencies

• numpy
• pandas
• packaging

Required Imports

import numpy as np
import pandas as pd
from packaging.version import Version as LooseVersion

Conditional/Optional Imports

These imports are only needed under specific conditions:

import pandas as pd

Usage Example

import numpy as np
import pandas as pd
from packaging.version import Version as LooseVersion

# Setup required module variables
numpy_version = LooseVersion(np.__version__)
nat_as_integer = np.datetime64('NaT').view('i8')
pandas_datetime_types = (pd.Timestamp,)
pandas_timedelta_types = (pd.Timedelta,)

# Example usage
nat_value = np.datetime64('NaT')
result = isnat(nat_value)  # Returns True

valid_date = np.datetime64('2023-01-01')
result2 = isnat(valid_date)  # Returns False

pandas_nat = pd.NaT
result3 = isnat(pandas_nat)  # Returns True

timestamp = pd.Timestamp('2023-01-01')
result4 = isnat(timestamp)  # Returns False

Best Practices

• Only call this function on datetimelike objects as stated in the docstring; behavior on non-temporal types may be unpredictable
• Ensure module-level variables (numpy_version, nat_as_integer, pandas_datetime_types, pandas_timedelta_types) are properly initialized before using this function
• Be aware that for numpy arrays with datetime dtype, this may return an array of booleans rather than a single boolean
• This function handles backward compatibility with NumPy < 1.13, but modern code should use NumPy >= 1.13 for better performance
• The function checks for pandas availability (pd) before accessing pandas-specific types, making it somewhat resilient to missing pandas installation

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function isdatetime 70.1% similar

  Determines whether a given value (array or scalar) is a recognized datetime type, checking both NumPy datetime64 arrays and Python datetime objects.

  From: /tf/active/vicechatdev/patches/util.py

• function is_nan 65.1% similar

  A type-safe utility function that checks whether a given value is NaN (Not a Number), handling arbitrary types without raising exceptions.

  From: /tf/active/vicechatdev/patches/util.py

• function isscalar 60.4% similar

  Checks if a value is a scalar type, None, or a datetime-related type.

  From: /tf/active/vicechatdev/patches/util.py

• function isfinite 58.3% similar

  Extended version of numpy.isfinite that handles additional data types including None, strings, datetime objects, masked arrays, and dask arrays.

  From: /tf/active/vicechatdev/patches/util.py

• function isnumeric 55.9% similar

  Determines whether a given value can be converted to a numeric type (int or float), excluding strings and boolean types.

  From: /tf/active/vicechatdev/patches/util.py