# Data ranges¶

A data range expresses bounds on *data space* of some dimensionality.
For example, the simplest
data range is just a set of two scalars representing (low, high) bounds in 1-D.
Data ranges are commonly used in plots to determine the range of plot axes.

Data ranges are typically associated to a data source, with their bounds set
to `auto`, which means that they automatically scale to fit the
data source bounds. Each data source can be associated with multiple ranges,
and each data range can be associated with multiple data sources.

## Interface¶

The basic interface for data sources is defined in
`AbstractDataRange`
and
`BaseDataRange`.

This is a summary of the most important attributes and methods (see the docstrings of this class for more details):

**Attributes**

sourcesA list of data sources associated to the data range. Concrete implementations of data range listen to the eventdata_changedand refresh their bounds as appropriate (e.g., when the bounds are set toauto).

lowThe actual value of the lower bounds of the range. The correct way to set it is to use thelow_settingattribute.

highThe actual value of the upper bounds of the range. The correct way to set it is to use thehigh_settingattribute.

low_settingSetting for the lower bound of the range. This can either be a valid lower bound value, orauto(default), in which case the lower bound is set automatically from the associated data sources.

high_settingSetting for the upper bound of the range. This can either be a valid upper bound value, orauto(default), in which case the upper bound is set automatically from the associated data sources.

**Methods**

add(*datasources)Convenience method to associate one or more data sources to the range. The method avoids adding the same data source twice.

remove(*datasources)Convenience method to remove one or more data sources from the range. If one of the data sources is not associated with the range, it is ignored.

clip_data(data)Given an array of data values of the same dimensionality as the range, return a list of data values that are inside the range.

mask_data(data)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.

bound_data(data)Given an array ofmonotonicdata values of the same dimensionality as the range, returns a tuple of indices (start, end) corresponding to the first and last elements that fall within the range.

## Events¶

The basic data range interface defines a single event,
`updated`,
which is fired when the bound values change.
The value of the event is a tuple `(low_bound, high_bound)`.

## List of Chaco data ranges¶

There are two data range implementations in Chaco, one for 1D and one for 2D ranges:

`DataRange1D`

DataRange1Drepresents a 1D data range. This subclass adds several more ways to control the bound of the range given the associated data sources.First of all, a new parameter,

tight_bounds, controls whether the bounds should fit exactly the range of the associated data sources (the default is True). If it is False, the range adds some padding on either side of the data, controlled bymargin, which is expressed as a precentage of the full data width.Second,

DataRange1Ddefines a new setting,trackforlow_settingandhigh_setting. When one of the bounds is set totrack, it follows the other bound by the amount set intracking_amount.Third, bounds can be computed using a user-supplied function specified in

bounds_func. The function takes the arguments(data_low, data_high, margin, tight_bounds), wheredata_lowanddata_highare the bounds computedaftertaking into account theautoortracksettings, andmarginandtight_boundsare defined as above.The logic of computing the bounds is implemented in the function

calc_bounds()inchaco.data_range_1d.

`DataRange2D`

DataRange2Drepresents a 2D data range. Under the hood, it is implemented using twoDataRange1Dobjects, one for each dimension, which are stored in thex_rangeandy_rangeattributes. These can be accessed directly if one wants to use the full flexibility of theDataRange1Dclass.The data range bounds,

lowandhigh, return 2-elements tuples containing the bounds for for the two dimensions.