🔍 Code Extractor

Expands an Ellipsis (...) in a __getitem__ key by replacing it with the appropriate number of empty slices (slice(None)) to match the dimensions of an object.

Purpose

This function is used to normalize indexing keys that contain an Ellipsis by padding them with empty slices. It's particularly useful for multi-dimensional data structures where users can use ... as a shorthand for multiple : slices. The function handles special cases for value dimension selection in objects with separate key dimensions (kdims) and value dimensions (vdims), ensuring proper indexing behavior in data visualization or analysis frameworks.

Source Code

def process_ellipses(obj, key, vdim_selection=False):
    """
    Helper function to pad a __getitem__ key with the right number of
    empty slices (i.e. :) when the key contains an Ellipsis (...).

    If the vdim_selection flag is true, check if the end of the key
    contains strings or Dimension objects in obj. If so, extra padding
    will not be applied for the value dimensions (i.e. the resulting key
    will be exactly one longer than the number of kdims). Note: this
    flag should not be used for composite types.
    """
    if getattr(getattr(key, 'dtype', None), 'kind', None) == 'b':
        return key
    wrapped_key = wrap_tuple(key)
    ellipse_count = sum(1 for k in wrapped_key if k is Ellipsis)
    if ellipse_count == 0:
        return key
    elif ellipse_count != 1:
        raise Exception("Only one ellipsis allowed at a time.")
    dim_count = len(obj.dimensions())
    index = wrapped_key.index(Ellipsis)
    head = wrapped_key[:index]
    tail = wrapped_key[index+1:]

    padlen = dim_count - (len(head) + len(tail))
    if vdim_selection:
        # If the end of the key (i.e. the tail) is in vdims, pad to len(kdims)+1
        if wrapped_key[-1] in obj.vdims:
            padlen = (len(obj.kdims) +1 ) - len(head+tail)
    return head + ((slice(None),) * padlen) + tail

Parameters

Parameter Details

obj: An object with a dimensions() method that returns dimensional information. Expected to have 'kdims' and 'vdims' attributes when vdim_selection is True. This is typically a HoloViews-like data structure with key and value dimensions.

key: The indexing key that may contain an Ellipsis (...). Can be a single value, tuple, or array-like object. If it's a boolean array (dtype.kind == 'b'), it's returned unchanged. Only one Ellipsis is allowed in the key.

vdim_selection: Boolean flag (default: False) that enables special handling for value dimension selection. When True and the last element of the key matches a value dimension in obj.vdims, padding is adjusted to len(kdims)+1 instead of the total dimension count. Should not be used for composite types.

Return Value

Returns a normalized key as a tuple where the Ellipsis has been replaced with the appropriate number of slice(None) objects. If the input key is a boolean array, it's returned unchanged. If no Ellipsis is present, the original key is returned. The returned tuple has length equal to the number of dimensions in obj (or len(kdims)+1 when vdim_selection is True and applicable).

Usage Example

# Assuming a HoloViews-like object with 3 dimensions
class MockObj:
    def __init__(self):
        self.kdims = ['x', 'y']
        self.vdims = ['z']
    def dimensions(self):
        return self.kdims + self.vdims

def wrap_tuple(x):
    return x if isinstance(x, tuple) else (x,)

obj = MockObj()

# Basic ellipsis expansion
key1 = (..., 'z')
result1 = process_ellipses(obj, key1)
# Returns: (slice(None), slice(None), 'z')

# With vdim_selection enabled
key2 = (..., 'z')
result2 = process_ellipses(obj, key2, vdim_selection=True)
# Returns: (slice(None), slice(None), 'z') - padded to len(kdims)+1

# Ellipsis in the middle
key3 = ('a', ..., 'z')
result3 = process_ellipses(obj, key3)
# Returns: ('a', slice(None), 'z')

Best Practices

• Only one Ellipsis is allowed per key - multiple Ellipses will raise an Exception
• The vdim_selection flag should not be used for composite types
• Boolean array keys (dtype.kind == 'b') are returned unchanged without processing
• Ensure the obj parameter has the required dimensions() method and appropriate kdims/vdims attributes when using vdim_selection
• The function depends on a wrap_tuple helper function being available in scope
• When using vdim_selection=True, the last element of the key is checked against obj.vdims to determine padding behavior

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function unpack_group 46.8% similar

  Unpacks a pandas DataFrame group by iterating over rows and yielding tuples of keys and objects, with special handling for objects with 'kdims' attribute.

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

• function expand_grid_coords 41.6% 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 wrap_tuple_streams 40.5% similar

  Fills in None values in a tuple with corresponding dimensioned stream values based on matching key dimension names.

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

• function get_unique_keys 39.6% similar

  Extracts unique key values from an ndmapping object for specified dimensions, returning an iterator of unique tuples.

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

• function drop_streams 37.8% similar

  Filters out dimensioned stream parameters from key dimensions (kdims) and their corresponding keys, returning cleaned dimensions and keys.

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