🔍 Code Extractor

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.

Purpose

This function is designed to calculate the bounds and density of data samples (typically for image or grid data) where samples are assumed to be evenly distributed. It handles edge cases like empty arrays, datetime types, zero/infinite densities, and automatically detects if the data is in descending order. The density is rounded to machine precision for numerical stability.

Source Code

def bound_range(vals, density, time_unit='us'):
    """
    Computes a bounding range and density from a number of samples
    assumed to be evenly spaced. Density is rounded to machine precision
    using significant digits reported by sys.float_info.dig.
    """
    if not len(vals):
        return(np.nan, np.nan, density, False)
    low, high = vals.min(), vals.max()
    invert = False
    if len(vals) > 1 and vals[0] > vals[1]:
        invert = True
    if not density:
        with warnings.catch_warnings():
            warnings.filterwarnings('ignore', r'invalid value encountered in double_scalars')
            full_precision_density = compute_density(low, high, len(vals)-1)
            with np.errstate(over='ignore'):
                density = round(full_precision_density, sys.float_info.dig)
        if density == 0 or density == np.inf:
            density = full_precision_density
    if density == 0:
        raise ValueError('Could not determine Image density, ensure it has a non-zero range.')
    halfd = 0.5/density
    if isinstance(low, datetime_types):
        halfd = np.timedelta64(int(round(halfd)), time_unit)
    return low-halfd, high+halfd, density, invert

Parameters

Parameter Details

vals: Array-like collection of numeric or datetime values assumed to be evenly spaced. Can be a numpy array, pandas series, or similar. Should have at least one element. Used to compute min/max bounds and determine if values are inverted (descending order).

density: Pre-computed density value (samples per unit). If provided as a non-zero value, it will be used directly. If 0, None, or False, the function will compute density automatically using compute_density(). Represents the number of samples per unit distance.

time_unit: String specifying the time unit for datetime adjustments. Default is 'us' (microseconds). Used when vals contains datetime types to create appropriate timedelta offsets. Valid values include standard numpy timedelta units like 'us', 'ms', 's', 'D', etc.

Return Value

Returns a tuple of four values: (low_bound, high_bound, density, invert). low_bound is the minimum value minus half-density offset; high_bound is the maximum value plus half-density offset; density is the computed or validated density value; invert is a boolean indicating if the original values were in descending order (True if vals[0] > vals[1]). If vals is empty, returns (np.nan, np.nan, density, False).

Dependencies

• numpy
• sys
• warnings

Required Imports

import numpy as np
import sys
import warnings

Conditional/Optional Imports

These imports are only needed under specific conditions:

from datetime import datetime, date, time (or similar datetime_types)

compute_density function

Usage Example

import numpy as np
import sys
import warnings

# Assuming compute_density and datetime_types are defined
def compute_density(low, high, count):
    return count / (high - low) if high != low else 0

datetime_types = ()

# Example 1: Regular numeric array
vals = np.array([0, 1, 2, 3, 4, 5])
low, high, density, inverted = bound_range(vals, density=0)
print(f"Bounds: [{low}, {high}], Density: {density}, Inverted: {inverted}")
# Output: Bounds: [-0.1, 5.1], Density: 1.0, Inverted: False

# Example 2: With pre-computed density
vals = np.array([10, 20, 30, 40])
low, high, density, inverted = bound_range(vals, density=0.1)
print(f"Bounds: [{low}, {high}], Density: {density}")
# Output: Bounds: [5.0, 45.0], Density: 0.1

# Example 3: Inverted (descending) values
vals = np.array([100, 90, 80, 70])
low, high, density, inverted = bound_range(vals, density=0)
print(f"Inverted: {inverted}")
# Output: Inverted: True

# Example 4: Empty array
vals = np.array([])
low, high, density, inverted = bound_range(vals, density=1.0)
print(f"Empty result: {low}, {high}, {density}, {inverted}")
# Output: Empty result: nan, nan, 1.0, False

Best Practices

• Ensure vals is a numpy array or array-like object with min() and max() methods
• The compute_density function must be defined or imported before using this function
• Define datetime_types appropriately in your module if working with datetime data
• Handle the returned np.nan values when vals is empty before using the bounds
• Be aware that the function extends bounds by half-density on each side, which is important for pixel/cell-centered data
• The invert flag is useful for detecting descending data but only checks the first two elements
• When density is 0 or np.inf after rounding, the function falls back to full precision density
• For datetime types, ensure time_unit matches the precision needed for your data
• The function suppresses specific numpy warnings about invalid values and overflow, which is intentional for edge case handling

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function compute_density 67.0% similar

  Computes the density (samples per unit) of a grid given start and end boundaries and the number of samples, with special handling for datetime/timedelta types.

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

• function find_range 61.8% 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 dimension_range 61.8% similar

  Computes the effective range along a dimension by combining data bounds with soft and hard range constraints, optionally applying padding and logarithmic scaling.

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

• function date_range 58.1% similar

  Generates an evenly-spaced date range array with a specified number of samples between start and end dates, with dates centered in each interval.

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

• function range_pad 55.6% similar

  Pads a numeric or datetime range by a specified fraction of the interval, with optional logarithmic scaling for positive numeric values.

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