🔍 Code Extractor

Validates whether a 1D array has regular (uniform) sampling by checking if the variation in consecutive differences is within a specified relative tolerance of the minimum sampling step.

Purpose

This function is used to determine if data points in a 1D array are uniformly spaced, which is important for time series analysis, signal processing, and numerical methods that assume regular sampling intervals. It checks if the maximum deviation between sampling steps is within an acceptable tolerance relative to the smallest step size.

Source Code

def validate_regular_sampling(values, rtol=10e-6):
    """
    Validates regular sampling of a 1D array ensuring that the difference
    in sampling steps is at most rtol times the smallest sampling step.
    Returns a boolean indicating whether the sampling is regular.
    """
    diffs = np.diff(values)
    return (len(diffs) < 1) or abs(diffs.min()-diffs.max()) < abs(diffs.min()*rtol)

Parameters

Parameter Details

values: A 1D array-like object (numpy array, list, pandas Series, etc.) containing numerical values to be checked for regular sampling. The function computes differences between consecutive elements to assess uniformity.

rtol: Relative tolerance parameter (default: 10e-6, which equals 1e-5). Defines the acceptable relative variation in sampling steps. The sampling is considered regular if abs(diffs.min() - diffs.max()) < abs(diffs.min() * rtol). Note: The default value in the code (10e-6) differs from the docstring (1e-05), though they are mathematically equivalent.

Return Value

Returns a boolean value: True if the sampling is regular (uniform) within the specified tolerance, or if there are fewer than 2 elements (making regularity trivially true). False if the variation in sampling steps exceeds the tolerance threshold.

Dependencies

• numpy

Required Imports

import numpy as np

Usage Example

import numpy as np

def validate_regular_sampling(values, rtol=10e-6):
    diffs = np.diff(values)
    return (len(diffs) < 1) or abs(diffs.min()-diffs.max()) < abs(diffs.min()*rtol)

# Example 1: Regular sampling
regular_data = np.array([0.0, 1.0, 2.0, 3.0, 4.0])
print(validate_regular_sampling(regular_data))  # True

# Example 2: Nearly regular sampling (within tolerance)
nearly_regular = np.array([0.0, 1.0, 2.00001, 3.0, 4.0])
print(validate_regular_sampling(nearly_regular))  # True

# Example 3: Irregular sampling
irregular_data = np.array([0.0, 1.0, 2.5, 3.0, 5.0])
print(validate_regular_sampling(irregular_data))  # False

# Example 4: Custom tolerance
print(validate_regular_sampling(nearly_regular, rtol=1e-10))  # False (stricter tolerance)

# Example 5: Edge case - single element or empty
print(validate_regular_sampling(np.array([1.0])))  # True
print(validate_regular_sampling(np.array([])))  # True

Best Practices

• Ensure input values are numeric and convertible to a numpy array
• Be aware that the default rtol value in the code (10e-6) is 1e-5, not 1e-6
• The function returns True for arrays with 0 or 1 elements, which may need special handling in your application
• For very small sampling steps, consider adjusting rtol to avoid false negatives due to floating-point precision issues
• The function uses absolute value of diffs.min() in the tolerance calculation, which could cause issues if the minimum difference is negative or zero
• Consider validating that the input array is sorted before calling this function, as it assumes consecutive elements represent sequential samples
• For large arrays, this function is efficient (O(n)) as it only computes differences once

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function bound_range 46.1% similar

  Computes a bounding range and density from evenly spaced samples, extending the range by half the density on each side and detecting if values are inverted.

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

• function is_float 45.7% similar

  A type-checking utility function that determines whether a given object is a floating-point scalar value, supporting both Python's native float type and NumPy floating-point types.

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

• function find_range 45.2% similar

  Robustly computes the minimum and maximum values from a collection, with fallback mechanisms for edge cases and support for extending the range with soft bounds.

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

• function isnumeric 43.8% 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

• function isnat 43.1% similar

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

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