🔍 Code Extractor

function compute_density

Maturity: 45

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.

File:
/tf/active/vicechatdev/patches/util.py
Lines:
2055 - 2070
Complexity:
moderate

Purpose

This function calculates grid density for both numeric and datetime ranges. For numeric ranges, it returns samples per unit. For datetime ranges, it converts timedeltas to the specified time unit and computes density accordingly. This is useful for determining sampling rates, grid resolutions, or data point distributions across time or numeric ranges.

Source Code

def compute_density(start, end, length, time_unit='us'):
    """
    Computes a grid density given the edges and number of samples.
    Handles datetime grids correctly by computing timedeltas and
    computing a density for the given time_unit.
    """
    if isinstance(start, int): start = float(start)
    if isinstance(end, int): end = float(end)
    diff = end-start
    if isinstance(diff, timedelta_types):
        if isinstance(diff, np.timedelta64):
            diff = np.timedelta64(diff, time_unit).tolist()
        tscale = 1./np.timedelta64(1, time_unit).tolist().total_seconds()
        return (length/(diff.total_seconds()*tscale))
    else:
        return length/diff

Parameters

Name Type Default Kind
start - - positional_or_keyword
end - - positional_or_keyword
length - - positional_or_keyword
time_unit - 'us' positional_or_keyword

Parameter Details

start: The starting value of the range. Can be int, float, datetime, or any type that supports subtraction with 'end'. Integers are automatically converted to floats for numeric calculations.

end: The ending value of the range. Must be the same type as 'start' and support subtraction. Can be int, float, datetime, or any type that supports subtraction with 'start'. Integers are automatically converted to floats for numeric calculations.

length: The number of samples or grid points in the range. Should be a positive numeric value representing the count of elements between start and end.

time_unit: The time unit for density calculation when dealing with datetime ranges. Default is 'us' (microseconds). Valid values include standard numpy timedelta units: 'Y' (year), 'M' (month), 'W' (week), 'D' (day), 'h' (hour), 'm' (minute), 's' (second), 'ms' (millisecond), 'us' (microsecond), 'ns' (nanosecond).

Return Value

Returns a float representing the density (number of samples per unit). For numeric ranges, this is length/(end-start). For datetime ranges, this is length per time_unit, where the calculation accounts for the total seconds in the timedelta and scales by the specified time_unit.

Dependencies

  • numpy

Required Imports

import numpy as np

Usage Example

import numpy as np
from datetime import datetime, timedelta

# Define timedelta_types (required in scope)
timedelta_types = (timedelta, np.timedelta64)

# Example 1: Numeric range
start = 0.0
end = 10.0
length = 100
density = compute_density(start, end, length)
print(f"Numeric density: {density}")  # Output: 10.0 (100 samples / 10 units)

# Example 2: Datetime range
start_dt = datetime(2023, 1, 1)
end_dt = datetime(2023, 1, 2)
length_dt = 86400  # One sample per second
density_dt = compute_density(start_dt, end_dt, length_dt, time_unit='s')
print(f"Datetime density: {density_dt}")  # Output: 1.0 (1 sample per second)

# Example 3: With numpy timedelta64
start_np = np.datetime64('2023-01-01')
end_np = np.datetime64('2023-01-02')
density_np = compute_density(start_np, end_np, 24, time_unit='h')
print(f"NumPy datetime density: {density_np}")  # Output: 1.0 (1 sample per hour)

Best Practices

  • Ensure 'timedelta_types' is defined in the scope before calling this function, typically as a tuple containing datetime.timedelta, np.timedelta64, and potentially pd.Timedelta
  • When using datetime inputs, ensure start and end are compatible datetime types that support subtraction
  • The time_unit parameter should match the scale of your data - use 's' for second-level data, 'us' for microsecond precision, etc.
  • Be aware that integer inputs are automatically converted to floats, which may affect precision in some edge cases
  • For datetime calculations, the function assumes the timedelta has a total_seconds() method, which is standard for Python datetime.timedelta and pandas Timedelta objects
  • Avoid division by zero by ensuring start and end are different values

Tags

density grid datetime timedelta sampling numeric temporal resolution data-processing time-series numpy

Similar Components

AI-powered semantic similarity - components with related functionality:

  • function bound_range 67.0% 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 date_range 57.9% 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 expand_grid_coords 47.1% similar

    Expands coordinates along a specified dimension of a gridded dataset into an N-dimensional array that matches the full dimensionality of the dataset.

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

  • function isdatetime 44.3% 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 dt64_to_dt 43.9% similar

    Converts a NumPy datetime64 object to a Python datetime.datetime object by calculating seconds since Unix epoch.

    From: /tf/active/vicechatdev/patches/util.py
← Back to Browse