Data Sources

AbstractDataSource

class enthought.chaco.api.AbstractDataSource

Bases: enthought.traits.has_traits.HasTraits

This abstract interface must be implemented by any class supplying data to Chaco.

Chaco does not have a notion of a “data format”. For the most part, a data source looks like an array of values with an optional mask and metadata. If you implement this interface, you are responsible for adapting your domain-specific or application-specific data to meet this interface.

Chaco provides some basic data source implementations. In most cases, the easiest strategy is to create one of these basic data source with the numeric data from a domain model. In cases when this strategy is not possible, domain classes (or an adapter) must implement AbstractDataSource.

Traits:

value_dimension : DimensionTrait

The dimensionality of the value at each index point. Subclasses re-declare this trait as a read-only trait with the right default value.

index_dimension : DimensionTrait

The dimensionality of the indices into this data source. Subclasses re-declare this trait as a read-only trait with the right default value.

metadata : Dict

A dictionary keyed on strings. In general, it maps to indices (or tuples of indices, depending on value_dimension), as in the case of selections and annotations. Applications and renderers can add their own custom metadata, but must avoid using keys that might result in name collision.

data_changed : Event

Event that fires when the data values change.

bounds_changed : Event

Event that fires when just the bounds change.

metadata_changed : Event

Event that fires when metadata structure is changed.

persist_data : Bool(True)

Should the data that this datasource refers to be serialized when the datasource is serialized?

get_bounds() -> tuple(min, max)

Returns a tuple (min, max) of the bounding values for the data source. In the case of 2-D data, min and max are 2-D points that represent the bounding corners of a rectangle enclosing the data set. Note that these values are not view-dependent, but represent intrinsic properties of the data source.

If data is the empty set, then the min and max vals are 0.0.

get_data()

get_data() -> data_array

Returns a data array of the dimensions of the data source. This data array must not be altered in-place, and the caller must assume it is read-only. This data is contiguous and not masked.

In the case of structured (gridded) 2-D data, this method may return two 1-D ArrayDataSources as an optimization.

get_data_mask() -> (data_array, mask_array)

Returns the full, raw, source data array and a corresponding binary mask array. Treat both arrays as read-only.

The mask is a superposition of the masks of all upstream data sources. The length of the returned array may be much larger than what get_size() returns; the unmasked portion, however, matches what get_size() returns.

get_size()

get_size() -> int

Returns an integer estimate or the exact size of the dataset that get_data() returns for this object. This method is useful for down-sampling.

is_masked()

is_masked() -> bool

Returns True if this data source’s data uses a mask. In this case, to retrieve the data, call get_data_mask() instead of get_data(). If you call get_data() for this data source, it returns data, but that data might not be the expected data.

ArrayDataSource

class enthought.chaco.api.ArrayDataSource(data=array([], dtype=float64), sort_order='none', **kw)

Bases: enthought.chaco.abstract_data_source.AbstractDataSource

A data source representing a single, continuous array of numerical data.

This class does not listen to the array for value changes; if you need that behavior, create a subclass that hooks up the appropriate listeners.

Traits:

index_dimension : Constant(‘scalar’)

The dimensionality of the indices into this data source (overrides AbstractDataSource).

value_dimension : Constant(‘scalar’)

The dimensionality of the value at each index point (overrides AbstractDataSource).

sort_order : SortOrderTrait

The sort order of the data. This is a specialized optimization for 1-D arrays, but it’s an important one that’s used everywhere.

get_bounds()

Returns the minimum and maximum values of the data source’s data.

Implements AbstractDataSource.

get_data()

Returns the data for this data source, or 0.0 if it has no data.

Implements AbstractDataSource.

get_data_mask() -> (data_array, mask_array)
Implements AbstractDataSource.
get_size()

get_size() -> int

Implements AbstractDataSource.

is_masked()

is_masked() -> bool

Implements AbstractDataSource.

remove_mask()
Removes the mask on this data source.
reverse_map(pt, index=0, outside_returns_none=True)

Returns the index of pt in the data source.

Parameters:

pt : scalar value

value to find

index :

ignored for data series with 1-D indices

outside_returns_none : Boolean

Whether the method returns None if pt is outside the range of the data source; if False, the method returns the value of the bound that pt is outside of.

set_data(newdata, sort_order=None)

Sets the data, and optionally the sort order, for this data source.

Parameters:

newdata : array

The data to use.

sort_order : SortOrderTrait

The sort order of the data

set_mask(mask)
Sets the mask for this data source.

MultiArrayDataSource

class enthought.chaco.api.MultiArrayDataSource(data=array([], dtype=float64), sort_order='ascending', **traits)

Bases: enthought.chaco.abstract_data_source.AbstractDataSource

A data source representing a single, continuous array of numerical data of potentially more than one dimension.

This class does not listen to the array for value changes; To implement such behavior, define a subclass that hooks up the appropriate listeners.

Traits:

index_dimension : Int(0)

The dimensionality of the indices into this data source (overrides AbstractDataSource).

value_dimension : Int(1)

The dimensionality of the value at each index point (overrides AbstractDataSource).

sort_order : SortOrderTrait

The sort order of the data. This is a specialized optimization for 1-D arrays, but it’s an important one that’s used everywhere.

get_bounds() -> tuple(min, max)

Returns a tuple (min, max) of the bounding values for the data source. In the case of 2-D data, min and max are 2-D points that represent the bounding corners of a rectangle enclosing the data set. Note that these values are not view-dependent, but represent intrinsic properties of the data source.

If data is the empty set, then the min and max vals are 0.0.

If value and index are both None, then the method returns the global minimum and maximum for the entire data set. If value is an integer, then the method returns the minimum and maximum along the value slice in the value_dimension. If index is an integer, then the method returns the minimum and maximum along the index slice in the index_direction.

get_data(axes=None, remove_nans=False)

get_data() -> data_array

If called with no arguments, this method returns a data array. Treat this data array as read-only, and do not alter it in-place. This data is contiguous and not masked.

If axes is an integer or tuple, this method returns the data array, sliced along the index_dimension.

get_data_mask() -> (data_array, mask_array)
Implements AbstractDataSource.
get_shape()
Returns the shape of the multi-dimensional data source.
get_size()

get_size() -> int

Implements AbstractDataSource. Returns an integer estimate, or the exact size, of the dataset that get_data() returns. This method is useful for downsampling.

get_value_size()

get_value_size() -> size

Returns the size along the value dimension.

is_masked()

is_masked() -> bool

Returns True if this data source’s data uses a mask. In this case, retrieve the data using get_data_mask() instead of get_data(). If you call get_data() for this data source, it returns data, but that data may not be the expected data.)

set_data(value)

Sets the data for this data source.

Parameters:

value : array

The data to use.

PointDataSource

class enthought.chaco.api.PointDataSource(data=array([], shape=(0, 2), dtype=float64), **kw)

Bases: enthought.chaco.array_data_source.ArrayDataSource

A data source representing a (possibly unordered) set of (X,Y) points.

This is internally always represented by an Nx2 array, so that data[i] refers to a single point (represented as a length-2 array).

Most of the traits and methods of ArrayDataSeries work for the PointDataSeries as well, since its data is linear. This class overrides only the methods and traits that are different.

Traits:

index_dimension : ReadOnly(‘scalar’)

The dimensionality of the indices into this data source (overrides ArrayDataSource).

value_dimension : ReadOnly(‘point’)

The dimensionality of the value at each index point (overrides ArrayDataSource).

sort_order : SortOrderTrait

The sort order of the data. Although sort order is less common with point data, it can be useful in case where the value data is sorted along some axis. Note that sort_index is used only if sort_order is not ‘none’.

sort_index : Enum(0, 1)

Which of the value axes the sort_order refers to. If sort_order is ‘none’, this attribute is ignored. In the unlikely event that the value data is sorted along both X and Y (i.e., monotonic in both axes), then set sort_index to whichever one has the best binary-search performance for hit-testing.

get_data()

Returns the data for this data source, or (0.0, 0.0) if it has no data.

Overrides ArryDataSource.

reverse_map(pt, index=0, outside_returns_none=True)

Returns the index of pt in the data source.

Overrides ArrayDataSource.

Parameters:

pt : (x, y)

value to find

index : 0 or 1

Which of the axes of pt the sort_order refers to.

outside_returns_none : Boolean

Whether the method returns None if pt is outside the range of the data source; if False, the method returns the value of the bound that pt is outside of, in the index dimension.

GridDataSource

class enthought.chaco.api.GridDataSource(xdata=array([], dtype=float64), ydata=array([], dtype=float64), sort_order=('none', 'none'), **kwargs)

Bases: enthought.chaco.abstract_data_source.AbstractDataSource

Implements a structured gridded 2-D data source (suitable as an index for an image, for example).

Traits:

index_dimension : Constant(‘image’)

The dimensionality of the indices into this data source (overrides AbstractDataSource).

value_dimension : Constant(‘scalar’)

The dimensionality of the value at each index point (overrides AbstractDataSource).

sort_order : Tuple(SortOrderTrait, SortOrderTrait)

The sort order of the data (overrides AbstractDataSource). There is no overall sort order on 2-D data, but for gridded 2-D data, each axis can have a sort order.

get_bounds() -> ((LLx, LLy), (URx, URy))

Implements AbstractDataSource. Returns two 2-D points, min and max, that represent the bounding corners of a rectangle enclosing the data set. Note that these values are not view-dependent, but represent intrinsic properties of the DataSource.

If data axis is the empty set, then the min and max valuess are 0.0.

get_data() -> (xdata, ydata)
Implements AbstractDataSource. Because this class uses structured (gridded) data, this method returns the pair of data axes, instead of, for example, a full mesh-grid. This behavious differs from other data sources.
set_data(xdata, ydata, sort_order=None)

Sets the data, and optionally the sort order, for this data source.

Parameters:

xdata, ydata : array

The data to use.

sort_order : SortOrderTrait

The sort order of the data

ImageData

class enthought.chaco.api.ImageData

Bases: enthought.chaco.abstract_data_source.AbstractDataSource

Represents a grid of data to be plotted using a Numpy 2-D grid.

The data array has dimensions NxM, but it may have more than just 2 dimensions. The appropriate dimensionality of the value array depends on the context in which the ImageData instance will be used.

Traits:

dimension : ReadOnly(DimensionTrait(‘image’))

The dimensionality of the data.

value_depth : Int(1)

Depth of the values at each i,j. Values that are used include:

  • 3: color images, without alpha channel
  • 4: color images, with alpha channel

data : Property(ImageTrait)

Holds the grid data that forms the image. The shape of the array is (N, M, D) where:

  • D is 1, 3, or 4.
  • N is the length of the y-axis.
  • M is the length of the x-axis.

Thus, data[0,:,:] must be the first row of data. If D is 1, then the array must be of type float; if D is 3 or 4, then the array must be of type uint8.

NOTE: If this ImageData was constructed with a transposed data array, then internally it is still transposed (i.e., the x-axis is the first axis and the y-axis is the second), and the data array property might not be contiguous. If contiguousness is required and calling copy() is too expensive, use the raw_value attribute. Also note that setting this trait does not change the value of transposed, so be sure to set it to its proper value when using the same ImageData instance interchangeably to store transposed and non-transposed data.

transposed : Bool(False)

Is raw_value, the actual underlying image data array, transposed from value? (I.e., does the first axis correspond to the x-direction and the second axis correspond to the y-direction?)

Rather than transposing or swapping axes on the data and destroying continuity, this class exposes the data as both value and raw_value.

raw_value : Property(ImageTrait)

A read-only attribute that exposes the underlying array.

fromfile
Alternate constructor to create an ImageData from an image file on disk. ‘filename’ may be a file path or a file object.
get_array_bounds()
Always returns ((0, width), (0, height)) for x-bounds and y-bounds.
get_bounds()

Returns the minimum and maximum values of the data source’s data.

Implements AbstractDataSource.

get_data()

Returns the data for this data source.

Implements AbstractDataSource.

get_height()
Returns the shape of the y-axis.
get_size()

get_size() -> int

Implements AbstractDataSource.

get_width()
Returns the shape of the x-axis.
is_masked()

is_masked() -> False

Implements AbstractDataSource.

set_data(data)

Sets the data for this data source.

Parameters:

data : array

The data to use.