Data Ranges

AbstractDataRange

class chaco.api.AbstractDataRange(*sources, **kwargs)

Bases: traits.has_traits.HasTraits

Abstract class for ranges that represent sub-regions of data space.

They support “autoscaling” by querying their associated data sources.

Traits:

sources : List(Instance(AbstractDataSource))

The list of data sources to which this range responds.

low : Float(0.0)

The actual value of the lower bound of this range. To set it, use low_setting. (Setting this attribute directly just calls the setter for low_setting.) Although the default value is specified as 0.0, subclasses can redefine the default. Also, subclasses can redefined the type to correspond to their dimensionality.

high : Float(1.0)

The actual value of the upper bound of this range. To set it, use high_setting. (Setting this attribute directly just calls the setter for high_setting.) Although the default value is specified as 1.0, subclasses can redefine the default. Also, subclasses can redefined the type to correspond to their dimensionality.

low_setting : Trait(‘auto’, ‘auto’, Float)

Setting for the lower bound of this range.

high_setting : Trait(‘auto’, ‘auto’, Float)

Setting for the upper bound of this range.

updated : Event

Event that is fired when the actual bounds values change; the value of the event is a tuple (low_bound, high_bound)

bound_data(data)

Returns a tuple of indices for the start and end of the first run of data that falls within the range.

Given an array of data values of the same dimensionality as the range, returns a tuple of indices (start, end) corresponding to the first and last elements of the first run of data that falls within the range. For monotonic data, this basically returns the first and last elements that fall within the range. Using this method is not advised for non-monotonic data; in that case, it returns the first and last elements of the first “chunk” of data that falls within the range.

clip_data(data)

Returns a list of data values that are within the range.

Given an array of data values of the same dimensionality as the range, returns a list of data values that are inside the range.

mask_data(data)

Returns a mask array, indicating whether values in the given array are inside the range.

Given an array of data values of the same dimensionality as the range, this method returns a mask array of the same length as data, filled with 1s and 0s corresponding to whether the data value at that index is inside or outside the range.

set_bounds(*new_bounds)

Sets all the bounds of the range simultaneously.

Because each bounds change probably fires an event, this method allows tools to set all range elements in a single, atomic step.

Parameters:

new_bounds : a tuple of (low, high)

The new bounds for the range; the dimensionality and cardinality depend on the specific subclass.

This method not only reduces the number of spurious events (the :

ones that result from having to set both **high and low), but also** :

allows listeners to differentiate between translation and resize :

operations. :

BaseDataRange

class chaco.api.BaseDataRange(*datasources, **kwtraits)

Bases: chaco.abstract_data_range.AbstractDataRange

Ranges represent sub-regions of data space.

They support “autoscaling” by querying their associated data sources.

add(*datasources)

Convenience method to add a data source.

remove(*datasources)

Convenience method to remove a data source.

DataRange1D

class chaco.api.DataRange1D(*datasources, **kwtraits)

Bases: chaco.base_data_range.BaseDataRange

Represents a 1-D data range.

Traits:

low : Property

The actual value of the lower bound of this range (overrides AbstractDataRange). To set it, use low_setting.

high : Property

The actual value of the upper bound of this range (overrides AbstractDataRange). To set it, use high_setting.

low_setting : Property(Trait(‘auto’, ‘auto’, ‘track’, CFloat))

Property for the lower bound of this range (overrides AbstractDataRange).

  • ‘auto’: The lower bound is automatically set at or below the minimum of the data.
  • ‘track’: The lower bound tracks the upper bound by tracking_amount.
  • CFloat: An explicit value for the lower bound

high_setting : Property(Trait(‘auto’, ‘auto’, ‘track’, CFloat))

Property for the upper bound of this range (overrides AbstractDataRange).

  • ‘auto’: The upper bound is automatically set at or above the maximum of the data.
  • ‘track’: The upper bound tracks the lower bound by tracking_amount.
  • CFloat: An explicit value for the upper bound

tight_bounds : Bool(True)

Do “auto” bounds imply an exact fit to the data? If False, they pad a little bit of margin on either side.

bounds_func : Callable

A user supplied function returning the proper bounding interval. bounds_func takes (data_low, data_high, margin, tight_bounds) and returns (low, high)

margin : Float(0.05)

The amount of margin to place on either side of the data, expressed as a percentage of the full data width

epsilon : CFloat(1e-10)

The minimum percentage difference between low and high. That is, (high-low) >= epsilon * low. Used to be 1.0e-20 but chaco cannot plot at such a precision!

default_tracking_amount : CFloat(20.0)

When either high or low tracks the other, track by this amount.

tracking_amount : default_tracking_amount

The current tracking amount. This value changes with zooming.

default_state : Enum(‘auto’, ‘high_track’, ‘low_track’)

Default tracking state. This value is used when self.reset() is called.

  • ‘auto’: Both bounds reset to ‘auto’.
  • ‘high_track’: The high bound resets to ‘track’, and the low bound resets to ‘auto’.
  • ‘low_track’: The low bound resets to ‘track’, and the high bound resets to ‘auto’.

fit_to_subset : Bool(False)

FIXME: this attribute is not used anywhere, is it safe to remove it? Is this range dependent upon another range?

bound_data(data)

Returns a tuple of indices for the start and end of the first run of data that falls within the range.

Implements AbstractDataRange.

clip_data(data)

Returns a list of data values that are within the range.

Implements AbstractDataRange.

mask_data(data)

Returns a mask array, indicating whether values in the given array are inside the range.

Implements AbstractDataRange.

refresh()

If any of the bounds is ‘auto’, this method refreshes the actual low and high values from the set of the view filters’ data sources.

reset()

Resets the bounds of this range, based on default_state.

scale_tracking_amount(multiplier)

Sets the tracking_amount to a new value, scaled by multiplier.

set_bounds(low, high)

Sets all the bounds of the range simultaneously.

Implements AbstractDataRange.

set_default_tracking_amount(amount)

Sets the default_tracking_amount to a new value, amount.

set_tracking_amount(amount)

Sets the tracking_amount to a new value, amount.

DataRange2D

class chaco.api.DataRange2D(*args, **kwargs)

Bases: chaco.base_data_range.BaseDataRange

A range on (2-D) image data.

In a mathematically general sense, a 2-D range is an arbitrary region in the plane. Arbitrary regions are difficult to implement well, so this class supports only rectangular regions for now.

Traits:

low : Property

The actual value of the lower bound of this range. To set it, use low_setting.

high : Property

The actual value of the upper bound of this range. To set it, use high_setting.

low_setting : Property

Property for the lower bound of this range (overrides AbstractDataRange).

high_setting : Property

Property for the upper bound of this range (overrides AbstractDataRange).

x_range : Property

Property for the range in the x-dimension.

y_range : Property

Property for the range in the y-dimension.

tight_bounds : Tuple(Bool(True), Bool(True))

Do “auto” bounds imply an exact fit to the data? (One Boolean per dimension) If False, the bounds pad a little bit of margin on either side.

epsilon : Tuple(CFloat(0.0001), CFloat(0.0001))

The minimum percentage difference between low and high for each dimension. That is, (high-low) >= epsilon * low.

bound_data(data)

Not implemented for this class.

clip_data(data)

Returns a list of data values that are within the range.

Implements AbstractDataRange.

mask_data(data)

Returns a mask array, indicating whether values in the given array are inside the range.

Implements AbstractDataRange.

refresh()

If any of the bounds is ‘auto’, this method refreshes the actual low and high values from the set of the view filters’ data sources.

reset()

Resets the bounds of this range.

set_bounds(low, high)

Sets all the bounds of the range simultaneously.

Implements AbstractDataRange.

Parameters:

low : (x,y)

Lower-left corner of the range.

high : (x,y)

Upper right corner of the range.