🔍 Code Extractor

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

Purpose

This function is used in data visualization and plotting contexts to determine the final axis range by reconciling multiple range specifications: the actual data range (lower/upper), user-specified soft constraints (soft_range), hard limits (hard_range), and optional padding. It implements a priority system where hard_range overrides all other values, soft_range provides flexible boundaries, and padding expands the data range. This is commonly used in plotting libraries to automatically determine axis limits while respecting user constraints.

Source Code

def dimension_range(lower, upper, hard_range, soft_range, padding=None, log=False):
    """
    Computes the range along a dimension by combining the data range
    with the Dimension soft_range and range.
    """
    plower, pupper = range_pad(lower, upper, padding, log)
    if isfinite(soft_range[0]) and soft_range[0] <= lower:
        lower = soft_range[0]
    else:
        lower = max_range([(plower, None), (soft_range[0], None)])[0]
    if isfinite(soft_range[1]) and soft_range[1] >= upper:
        upper = soft_range[1]
    else:
        upper = max_range([(None, pupper), (None, soft_range[1])])[1]
    dmin, dmax = hard_range
    lower = lower if dmin is None or not isfinite(dmin) else dmin
    upper = upper if dmax is None or not isfinite(dmax) else dmax
    return lower, upper

Parameters

Parameter Details

lower: The lower bound of the data range. Expected to be a numeric value (int, float) representing the minimum value in the dataset along this dimension.

upper: The upper bound of the data range. Expected to be a numeric value (int, float) representing the maximum value in the dataset along this dimension.

hard_range: A tuple (dmin, dmax) representing absolute hard limits for the range. These values override all other range specifications. Use None for either value to indicate no hard limit. Values must be numeric or None.

soft_range: A tuple (soft_min, soft_max) representing preferred range boundaries. These are used if they extend beyond the data range but can be overridden by hard_range. Values should be numeric and checked with isfinite().

padding: Optional padding to apply to the data range before combining with soft_range. Can be None (no padding), a single numeric value (symmetric padding), or a tuple (lower_pad, upper_pad). Used by range_pad() function.

log: Boolean flag indicating whether logarithmic scaling should be applied when computing padding. Default is False. When True, padding calculations account for logarithmic scale.

Return Value

Returns a tuple (lower, upper) representing the final computed range along the dimension. Both values are numeric (int or float). The lower value is the minimum bound and upper is the maximum bound, determined by the priority: hard_range > soft_range > padded data range.

Dependencies

• numpy

Required Imports

import numpy as np

Usage Example

# Assuming helper functions are available
# from util_module import dimension_range, range_pad, isfinite, max_range

# Example 1: Basic usage with data range and soft constraints
lower, upper = dimension_range(
    lower=0.0,
    upper=10.0,
    hard_range=(None, None),
    soft_range=(-1.0, 12.0),
    padding=0.1,
    log=False
)
# Result: lower=-1.0, upper=12.0 (soft_range extends beyond padded data)

# Example 2: With hard range constraints
lower, upper = dimension_range(
    lower=5.0,
    upper=15.0,
    hard_range=(0.0, 20.0),
    soft_range=(-5.0, 25.0),
    padding=None,
    log=False
)
# Result: lower=0.0, upper=20.0 (hard_range overrides all)

# Example 3: Logarithmic scale with padding
lower, upper = dimension_range(
    lower=1.0,
    upper=1000.0,
    hard_range=(None, None),
    soft_range=(0.1, 10000.0),
    padding=0.05,
    log=True
)
# Result depends on range_pad implementation for log scale

Best Practices

• Ensure that lower <= upper in the input data range to avoid unexpected behavior
• Use None in hard_range tuple elements when you don't want to enforce a hard limit on that side
• The soft_range values should be finite numbers or will be ignored; use isfinite() to validate
• When using log=True, ensure that lower and upper are positive values to avoid logarithm domain errors
• The function depends on helper functions (range_pad, isfinite, max_range) that must be available in scope
• Hard range always takes precedence: if hard_range is set, it will override both soft_range and padded data range
• Soft range is only applied if it extends the range beyond the padded data bounds
• Consider the interaction between padding and soft_range: padding is applied first, then soft_range is considered

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function range_pad 62.8% 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

• function bound_range 61.8% 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 find_range 56.3% 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 max_extents 51.7% similar

  Computes the maximal extent (bounding box) from a list of extent tuples, supporting both 2D (4-tuples) and 3D (6-tuples) coordinate systems with special handling for datetime and string values.

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

• function max_range 50.4% similar

  Computes the maximal lower and upper bounds from a list of range tuples, handling various data types including numeric, datetime, and string values.

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