From 60fccae7379d4f4915464c1d5f31e38dc5afd6b7 Mon Sep 17 00:00:00 2001 From: Aaron Ayres Date: Tue, 9 Mar 2021 14:29:10 -0600 Subject: [PATCH 1/2] Clean up updates for docs/source/user_manual/basic_elements/ --- .../basic_elements/data_ranges.rst | 102 +++--- .../basic_elements/data_sources.rst | 162 ++++----- .../user_manual/basic_elements/mappers.rst | 107 +++--- .../user_manual/basic_elements/overlays.rst | 35 +- .../basic_elements/plot_renderers.rst | 331 ++++++++---------- 5 files changed, 307 insertions(+), 430 deletions(-) diff --git a/docs/source/user_manual/basic_elements/data_ranges.rst b/docs/source/user_manual/basic_elements/data_ranges.rst index 89fde57b6..0cfb18cad 100644 --- a/docs/source/user_manual/basic_elements/data_ranges.rst +++ b/docs/source/user_manual/basic_elements/data_ranges.rst @@ -1,3 +1,5 @@ +.. _data_ranges: + =========== Data ranges =========== @@ -23,70 +25,62 @@ and This is a summary of the most important attributes and methods (see the docstrings of this class for more details): -**Attributes** - - :attr:`~chaco.abstract_data_range.AbstractDataRange.sources` - - A list of data sources associated to the data range. Concrete implementations - of data range listen to the event - :attr:`~chaco.abstract_data_source.AbstractDataSource.data_changed` - and refresh their bounds as appropriate (e.g., when the bounds are - set to ``auto``). - - :attr:`~chaco.abstract_data_range.AbstractDataRange.low` - - The actual value of the lower bounds of the range. The correct way - to set it is to use the :attr:`low_setting` attribute. - - :attr:`~chaco.abstract_data_range.AbstractDataRange.high` - - The actual value of the upper bounds of the range. The correct way - to set it is to use the :attr:`high_setting` attribute. +Attributes +^^^^^^^^^^ - :attr:`~chaco.abstract_data_range.AbstractDataRange.low_setting` +:attr:`~chaco.abstract_data_range.AbstractDataRange.sources` + A list of data sources associated to the data range. Concrete implementations + of data range listen to the event + :attr:`~chaco.abstract_data_source.AbstractDataSource.data_changed` + and refresh their bounds as appropriate (e.g., when the bounds are + set to ``auto``). - Setting for the lower bound of the range. This can either be a valid - lower bound value, or ``auto`` (default), in which case the - lower bound is set automatically from the associated data sources. +:attr:`~chaco.abstract_data_range.AbstractDataRange.low` + The actual value of the lower bounds of the range. The correct way + to set it is to use the :attr:`low_setting` attribute. - :attr:`~chaco.abstract_data_range.AbstractDataRange.high_setting` +:attr:`~chaco.abstract_data_range.AbstractDataRange.high` + The actual value of the upper bounds of the range. The correct way + to set it is to use the :attr:`high_setting` attribute. - Setting for the upper bound of the range. This can either be a valid - upper bound value, or ``auto`` (default), in which case the - upper bound is set automatically from the associated data sources. +:attr:`~chaco.abstract_data_range.AbstractDataRange.low_setting` + Setting for the lower bound of the range. This can either be a valid + lower bound value, or ``auto`` (default), in which case the + lower bound is set automatically from the associated data sources. +:attr:`~chaco.abstract_data_range.AbstractDataRange.high_setting` + Setting for the upper bound of the range. This can either be a valid + upper bound value, or ``auto`` (default), in which case the + upper bound is set automatically from the associated data sources. -**Methods** - :attr:`~chaco.base_data_range.BaseDataRange.add(*datasources)` +Methods +^^^^^^^ - Convenience method to associate one or more data sources to the range. - The method avoids adding the same data source twice. +:meth:`~chaco.base_data_range.BaseDataRange.add` + Convenience method to associate one or more data sources to the range. + The method avoids adding the same data source twice. - :attr:`~chaco.base_data_range.BaseDataRange.remove(*datasources)` +:meth:`~chaco.base_data_range.BaseDataRange.remove` + 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. - 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. +:meth:`~chaco.abstract_data_range.AbstractDataRange.clip_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. - :attr:`~chaco.abstract_data_range.AbstractDataRange.clip_data(data)` +:meth:`~chaco.abstract_data_range.AbstractDataRange.mask_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. - Given an array of data values of the same dimensionality as the range, - return a list of data values that are inside the range. - - :attr:`~chaco.abstract_data_range.AbstractDataRange.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. - - :attr:`~chaco.abstract_data_range.AbstractDataRange.bound_data(data)` - - Given an array of *monotonic* data 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. +:meth:`~chaco.abstract_data_range.AbstractDataRange.bound_data` + Given an array of *monotonic* data 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 @@ -104,7 +98,6 @@ There are two data range implementations in Chaco, one for 1D and one for 2D ranges: :class:`~chaco.data_range_1d.DataRange1D` - :class:`~chaco.data_range_1d.DataRange1D` represents a 1D data range. This subclass adds several more ways to control the bound of the range given the associated data sources. @@ -136,9 +129,8 @@ for 2D ranges: :class:`~chaco.data_range_2d.DataRange2D` - :class:`~chaco.data_range_2d.DataRange2D` represents a 2D data range. - Under the hood, it is implemented using two + Internally, it is implemented using two :class:`~chaco.data_range_1d.DataRange1D` objects, one for each dimension, which are stored in the diff --git a/docs/source/user_manual/basic_elements/data_sources.rst b/docs/source/user_manual/basic_elements/data_sources.rst index 50ae4ceaf..59f106506 100644 --- a/docs/source/user_manual/basic_elements/data_sources.rst +++ b/docs/source/user_manual/basic_elements/data_sources.rst @@ -1,4 +1,7 @@ -Data sources +.. _data_sources: + +============ +Data Sources ============ A data source is a wrapper object for the actual data that the plot will be @@ -31,60 +34,51 @@ The basic interface for data sources is defined in Here is a summary of the most important attributes and methods (see the docstrings of this class for more details): - :attr:`~chaco.abstract_data_source.AbstractDataSource.value_dimension` - - The dimensionality of the data value at each point. It is defined - as a :class:`DimensionTrait`, i.e., one of - "scalar", "point", "image", or "cube". For example, - a :class:`GridDataSource` represents data in a 2D array and thus its - :attr:`value_dimension` is "scalar". - - :attr:`~chaco.abstract_data_source.AbstractDataSource.index_dimension` - - The dimensionality of the data value at each point. It is defined - as a :class:`DimensionTrait`, i.e., one of - "scalar", "point", "image", or "cube". For example, - a :class:`GridDataSource` represents data in a 2D array and thus its - :attr:`index_dimension` is "image". - - :attr:`~chaco.abstract_data_source.AbstractDataSource.metadata` - - A dictionary that maps strings to arbitrary data. Usually, the mapped - data is a set of indices, as in the case of selections and annotations. - By default, :attr:`metadata` contains the keys *"selections"* (representing - indices that are currently selected by some tool) - and *"annotations"*, both initialized to an empty list. - - :attr:`~chaco.abstract_data_source.AbstractDataSource.persist_data` - - If True (default), the data that this data source refers to is serialized - when the data source is. - - :meth:`~chaco.abstract_data_source.AbstractDataSource.get_data()` - - Returns a data array containing the data referred to by the data source. - Treat the returned array as read-only. - - :meth:`~chaco.abstract_data_source.AbstractDataSource.is_masked()` - - 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()``. - - :meth:`~chaco.abstract_data_source.AbstractDataSource.get_data_mask()` - - Returns the full, raw, source data array and a corresponding binary - mask array. Treat both arrays as read-only. - - :meth:`~chaco.abstract_data_source.AbstractDataSource.get_size()` - - Returns the size of the data. - - :meth:`~chaco.abstract_data_source.AbstractDataSource.get_bounds()` - - 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. - If data is the empty set, then the min and max vals are 0.0. +:attr:`~chaco.abstract_data_source.AbstractDataSource.value_dimension` + The dimensionality of the data value at each point. It is defined + as a :class:`DimensionTrait`, i.e., one of + "scalar", "point", "image", or "cube". For example, + a :class:`GridDataSource` represents data in a 2D array and thus its + :attr:`value_dimension` is "scalar". + +:attr:`~chaco.abstract_data_source.AbstractDataSource.index_dimension` + The dimensionality of the data value at each point. It is defined + as a :class:`DimensionTrait`, i.e., one of + "scalar", "point", "image", or "cube". For example, + a :class:`GridDataSource` represents data in a 2D array and thus its + :attr:`index_dimension` is "image". + +:attr:`~chaco.abstract_data_source.AbstractDataSource.metadata` + A dictionary that maps strings to arbitrary data. Usually, the mapped + data is a set of indices, as in the case of selections and annotations. + By default, :attr:`metadata` contains the keys *"selections"* (representing + indices that are currently selected by some tool) + and *"annotations"*, both initialized to an empty list. + +:attr:`~chaco.abstract_data_source.AbstractDataSource.persist_data` + If True (default), the data that this data source refers to is serialized + when the data source is. + +:meth:`~chaco.abstract_data_source.AbstractDataSource.get_data()` + Returns a data array containing the data referred to by the data source. + Treat the returned array as read-only. + +:meth:`~chaco.abstract_data_source.AbstractDataSource.is_masked()` + 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()``. + +:meth:`~chaco.abstract_data_source.AbstractDataSource.get_data_mask()` + Returns the full, raw, source data array and a corresponding binary + mask array. Treat both arrays as read-only. + +:meth:`~chaco.abstract_data_source.AbstractDataSource.get_size()` + Returns the size of the data. + +:meth:`~chaco.abstract_data_source.AbstractDataSource.get_bounds()` + 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. + If data is the empty set, then the min and max vals are 0.0. Events ------ @@ -92,25 +86,22 @@ Events :class:`~chaco.abstract_data_source.AbstractDataSource` defines three events that can be used in Traits applications to react to changes in the data source: - :attr:`~chaco.abstract_data_source.AbstractDataSource.data_changed` - - Fired when the data values change. - - .. note:: +:attr:`~chaco.abstract_data_source.AbstractDataSource.data_changed` + Fired when the data values change. - The majority of concrete data sources do not fire this event when - the data values change. Rather, the event is usually fired when new - data or a new mask is assigned through setter methods (see - notes below). - - :attr:`~chaco.abstract_data_source.AbstractDataSource.bounds_changed` + .. note:: - Fired when the data bounds change. + The majority of concrete data sources do not fire this event when + the data values change. Rather, the event is usually fired when new + data or a new mask is assigned through setter methods (see + notes below). - :attr:`~chaco.abstract_data_source.AbstractDataSource.metadata_changed` +:attr:`~chaco.abstract_data_source.AbstractDataSource.bounds_changed` + Fired when the data bounds change. - Fired when the content of :attr:`metadata` changes (both the - :attr:`metadata` dictionary object or any of its items). +:attr:`~chaco.abstract_data_source.AbstractDataSource.metadata_changed` + Fired when the content of :attr:`metadata` changes (both the + :attr:`metadata` dictionary object or any of its items). List of Chaco data sources @@ -120,7 +111,6 @@ This is a list of all concrete implementations of data sources in Chaco: :class:`~chaco.array_data_source.ArrayDataSource` - A data source representing a single, continuous array of numerical data. This is the most common data source for Chaco plots. @@ -128,13 +118,11 @@ This is a list of all concrete implementations of data sources in Chaco: interface: :attr:`~chaco.abstract_data_source.ArrayDataSource.sort_order` - The sort order of the data, one of 'ascending', 'descending', or 'none'. If the underlying data is sorted, and this attribute is set appropriately, Chaco is able to use shortcuts and optimizations in many places. :attr:`~chaco.abstract_data_source.ArrayDataSource.reverse_map(pt)` - Returns the index of *pt* in the data source (optimized if :attr:`sort_order` is set). @@ -148,7 +136,6 @@ This is a list of all concrete implementations of data sources in Chaco: :class:`~chaco.image_data.ImageData` - Represents a 2D grid of image data. The underlying data array is 3D, where the third dimension is either @@ -174,18 +161,15 @@ This is a list of all concrete implementations of data sources in Chaco: Noteworthy methods of this class are: :attr:`~chaco.image_data.ImageData.fromfile(filename)` + Factory method that creates an :class:`~chaco.image_data.ImageData` + instance from an image file. *filename* can be either a file path or a file + object. - Factory method that creates an :class:`ImageData` instance from an image - file. *filename* can be either a file path or a file object. - - :meth:`~chaco.image_data.ImageData.get_width`, - :meth:`~chaco.image_data.ImageData.get_height` - + :meth:`~chaco.image_data.ImageData.get_width`, :meth:`~chaco.image_data.ImageData.get_height` Return the width or the height of the image (takes the value of :attr:`transposed` into account). :meth:`~chaco.image_data.ImageData.get_array_bounds` - Return ((0, width), (0, height)). .. note:: @@ -201,17 +185,15 @@ This is a list of all concrete implementations of data sources in Chaco: :class:`~chaco.grid_data_source.GridDataSource` - Data source representing the coordinates of a 2D grid. It is used, for example, as a source for the index data in an - :class:`ImagePlot`. + :class:`~.ImagePlot`. It defines these attributes: :attr:`~chaco.abstract_data_source.GridDataSource.sort_order` - Similar to the :attr:`sort_order` attribute for the - :class:`ArrayDataSource` class above, but this is a tuple + :class:`~.ArrayDataSource` class above, but this is a tuple with two elements, one per dimension. .. note:: @@ -227,7 +209,6 @@ This is a list of all concrete implementations of data sources in Chaco: :class:`~chaco.multi_array_data_source.MultiArrayDataSource` - A data source representing a single, continuous array of multidimensional numerical data. @@ -236,13 +217,13 @@ This is a list of all concrete implementations of data sources in Chaco: or to represent multiple values for each index (as in :class:`~chaco.multi_line_plot.MultiLinePlot`). - As :class:`ArrayDataSource`, this data source defines a + As :class:`~.ArrayDataSource`, this data source defines a :attr:`~chaco.abstract_data_source.MultiArrayDataSource.sort_order` attribute for its index dimension. .. warning:: - In :class:`MultiArrayDataSource`, + In :class:`~.MultiArrayDataSource`, the :attr:`index_dimension` and :attr:`value_dimension` attributes are integers that define which dimension of the data array correspond to indices and which @@ -258,10 +239,9 @@ This is a list of all concrete implementations of data sources in Chaco: :class:`~chaco.point_data_source.PointDataSource` - A data source representing a set of (X,Y) points. - This is a subclass of :class:`ArrayDataSource`, and inherits its methods + This is a subclass of :class:`~.ArrayDataSource`, and inherits its methods and attributes. The attribute :attr:`~chaco.point_data_source.PointDataSource.sort_index` defines whether the data is sorted along the X's or the Y's (as specified @@ -275,7 +255,6 @@ This is a list of all concrete implementations of data sources in Chaco: :class:`~chaco.function_data_source.FunctionDataSource` - A subclass of :class:`~chaco.array_data_source.ArrayDataSource` that sets the values of the underlying data array based on a function (defined in the callable attribute @@ -285,7 +264,6 @@ This is a list of all concrete implementations of data sources in Chaco: :class:`~chaco.function_data_source.FunctionImageData` - A subclass of :class:`~chaco.array_data_source.ImageData` that sets the values of the underlying data array based on a 2D function (defined in the callable attribute diff --git a/docs/source/user_manual/basic_elements/mappers.rst b/docs/source/user_manual/basic_elements/mappers.rst index 891e9e506..c983ce8d4 100644 --- a/docs/source/user_manual/basic_elements/mappers.rst +++ b/docs/source/user_manual/basic_elements/mappers.rst @@ -15,45 +15,37 @@ The general interface for mappers is defined in :class:`~chaco.abstract_mapper.AbstractMapper` and defines only a few methods: - :attr:`~chaco.abstract_mapper.AbstractMapper.map_screen(data_value)`, - :attr:`~chaco.abstract_mapper.AbstractMapper.map_data(screen_value)` +:attr:`~chaco.abstract_mapper.AbstractMapper.map_screen(data_value)`, :attr:`~chaco.abstract_mapper.AbstractMapper.map_data(screen_value)` + Maps a vector of data coordinates to screen coordinates, and vice versa. - Maps a vector of data coordinates to screen coordinates, and vice versa. - - :attr:`~chaco.abstract_mapper.AbstractMapper.map_data_array(screen_value_array)` - - Maps an array of points in data coordinates to screen coordinates. - By default, this method just loops over the points, calling :attr:`map_data()` - on each one. For vectorizable mapping functions, this - implementation is overridden with a faster one. +:attr:`~chaco.abstract_mapper.AbstractMapper.map_data_array(screen_value_array)` + Maps an array of points in data coordinates to screen coordinates. + By default, this method just loops over the points, calling :attr:`map_data()` + on each one. For vectorizable mapping functions, this + implementation is overridden with a faster one. Mappers for 1D data have a slightly larger interface, defined in :class:`~chaco.base_1d_mapper.Base1DMapper`. These mappers rely on a :class:`~chaco.data_range_1d.DataRange1D` object to find the bounds on the data domain. - :attr:`~chaco.abstract_mapper.AbstractMapper.range` - - A :class:`~chaco.data_range_1d.DataRange1D` instance to define the - data-space bounds of the mapper. The mapper listens to the - :attr:`updated` event of the range and re-fires it as its - own :attr:`updated` event (see below). - - :attr:`~chaco.abstract_mapper.AbstractMapper.low_pos`, - :attr:`~chaco.abstract_mapper.AbstractMapper.high_pos`, - :attr:`~chaco.abstract_mapper.AbstractMapper.screen_bounds`, - - The screen space position of the lower/upper bound of the data space. - :attr:`screen_bounds` is a convenience property to set/get the screen - bounds with a single attribute. +:attr:`~chaco.abstract_mapper.AbstractMapper.range` + A :class:`~chaco.data_range_1d.DataRange1D` instance to define the + data-space bounds of the mapper. The mapper listens to the + :attr:`updated` event of the range and re-fires it as its + own :attr:`updated` event (see below). - :attr:`~chaco.abstract_mapper.AbstractMapper.stretch_data` +:attr:`~chaco.abstract_mapper.AbstractMapper.low_pos`, :attr:`~chaco.abstract_mapper.AbstractMapper.high_pos`, :attr:`~chaco.abstract_mapper.AbstractMapper.screen_bounds` + The screen space position of the lower/upper bound of the data space. + :attr:`screen_bounds` is a convenience property to set/get the screen + bounds with a single attribute. - When the screen bounds change (in response, for instance, to the - window resizing) one could either fit more data space on the screen, or - stretch the data space to the new bounds. - If :attr:`stretch_data` is True (default), the data is stretched; - if it is False, the mapper preserves the screen-to-data ratio. +:attr:`~chaco.abstract_mapper.AbstractMapper.stretch_data` + When the screen bounds change (in response, for instance, to the + window resizing) one could either fit more data space on the screen, or + stretch the data space to the new bounds. + If :attr:`stretch_data` is True (default), the data is stretched; + if it is False, the mapper preserves the screen-to-data ratio. Events @@ -75,12 +67,10 @@ List of Chaco data mappers -------------------------- :class:`~chaco.linear_mapper.LinearMapper` (subclass of :class:`~chaco.base_1d_mapper.Base1DMapper`) - This mapper transforms a 1D data space range linearly to a fixed 1D range in screen space. :class:`~chaco.log_mapper.LogMapper` (subclass of :class:`~chaco.base_1d_mapper.Base1DMapper`) - Maps a 1D data space range to a 1D range in screen space through a logarithmic transform. Data values smaller than or equal to 0.0 are @@ -88,28 +78,21 @@ List of Chaco data mappers (default is 1.0) before the logarithmic transformation. :class:`~chaco.grid_mapper.GridMapper` - Same as :class:`~chaco.linear_mapper.LinearMapper` for 2D ranges. This class - replaces the :class:`Base1DMapper` attributes with analogous ones: - - :attr:`~chaco.grid_mapper.GridMapper.range` - - A :class:`~chaco.data_range_2d.DataRange2D` instance to define the - data-space bounds of the mapper. - - :attr:`~chaco.grid_mapper.GridMapper.x_low_pos`, - :attr:`~chaco.grid_mapper.GridMapper.y_low_pos`, - :attr:`~chaco.grid_mapper.GridMapper.x_high_pos`, - :attr:`~chaco.grid_mapper.GridMapper.y_high_pos` - - Screen space positions for the lower and upper bounds of the x and - y axes. - - :attr:`~chaco.grid_mapper.GridMapper.screen_bounds` - - Convenience property to set/get the screen bounds with a single attribute. - The value of this attribute is a 4-element tuple - ``(x_low_pos, x_high_pos, y_low_pos, y_high_pos)``. + replaces the :class:`~.Base1DMapper` attributes with analogous ones: + + :attr:`~chaco.grid_mapper.GridMapper.range` + A :class:`~chaco.data_range_2d.DataRange2D` instance to define the + data-space bounds of the mapper. + + :attr:`~chaco.grid_mapper.GridMapper.x_low_pos`, :attr:`~chaco.grid_mapper.GridMapper.y_low_pos`, :attr:`~chaco.grid_mapper.GridMapper.x_high_pos`, :attr:`~chaco.grid_mapper.GridMapper.y_high_pos` + Screen space positions for the lower and upper bounds of the x and + y axes. + + :attr:`~chaco.grid_mapper.GridMapper.screen_bounds` + Convenience property to set/get the screen bounds with a single attribute. + The value of this attribute is a 4-element tuple + ``(x_low_pos, x_high_pos, y_low_pos, y_high_pos)``. :class:`~chaco.grid_mapper.GridMapper` uses two :class:`~chaco.base_1d_mapper.Base1DMapper` instances to define mappers for @@ -117,21 +100,9 @@ List of Chaco data mappers :attr:`_xmapper` and :attr:`_ymapper`). It thus possible to set them to be linear or logarithmic mappers. This is best made using the class constructor, which has - this signature: + this signature:: - :class:`~chaco.grid_mapper.GridMapper(x_type="linear", y_type="linear", range=None, **kwargs)` + GridMapper(x_type="linear", y_type="linear", range=None, **kwargs) ``x_type`` and ``y_type`` can be either 'linear' or 'log', which will - create a corresponding :class:`LinearMapper` or :class:`LogMapper` classes. - - -:class:`~chaco.polar_mapper.PolarMapper` - - This class should map data polar coordinates to screen cartesian coordinates, - to use for example with a :class:`~chaco.polar_line_renderer.PolarLineRenderer`, - but at the moment it is a copy of :class:`~chaco.linear_mapper.LinearMapper`. - - .. warning:: - - The implementation of this mapper is under construction. - + create a corresponding :class:`~.LinearMapper` or :class:`~.LogMapper` classes. \ No newline at end of file diff --git a/docs/source/user_manual/basic_elements/overlays.rst b/docs/source/user_manual/basic_elements/overlays.rst index fa5a24e88..e378042a9 100644 --- a/docs/source/user_manual/basic_elements/overlays.rst +++ b/docs/source/user_manual/basic_elements/overlays.rst @@ -1,5 +1,5 @@ ================================== -Overlays: axis, legend, grid, etc. +Overlays: axis, and, grid, etc. ================================== Overlays are elements that decorate plots, like for example @@ -84,12 +84,7 @@ Attributes These attributes control the appearance of the axis: -:attr:`~chaco.axis.PlotAxis.title`, -:attr:`~chaco.axis.PlotAxis.title_font`, -:attr:`~chaco.axis.PlotAxis.title_color`, -:attr:`~chaco.axis.PlotAxis.title_spacing` -:attr:`~chaco.axis.PlotAxis.title_angle` - +:attr:`~chaco.axis.PlotAxis.title`, :attr:`~chaco.axis.PlotAxis.title_font`, :attr:`~chaco.axis.PlotAxis.title_color`, :attr:`~chaco.axis.PlotAxis.title_spacing` :attr:`~chaco.axis.PlotAxis.title_angle` Define the axis label. :attr:`title` is a string or unicode object that is rendered using the given font and color. :attr:`title_font` is a string describing a font (e.g. '12 pt bold italic', @@ -101,12 +96,7 @@ These attributes control the appearance of the axis: wrt horizontal). -:attr:`~chaco.axis.PlotAxis.tick_weight`, -:attr:`~chaco.axis.PlotAxis.tick_color`, -:attr:`~chaco.axis.PlotAxis.tick_in`, -:attr:`~chaco.axis.PlotAxis.tick_out`, -:attr:`~chaco.axis.PlotAxis.tick_visible`, - +:attr:`~chaco.axis.PlotAxis.tick_weight`, :attr:`~chaco.axis.PlotAxis.tick_color`, :attr:`~chaco.axis.PlotAxis.tick_in`, :attr:`~chaco.axis.PlotAxis.tick_out`, :attr:`~chaco.axis.PlotAxis.tick_visible`, These attributes control the aspect of the ticks on the axis. If :attr:`tick_visible` is True, ticks are represented as lines of color :attr:`tick_color` (default is black) and thickness @@ -115,14 +105,7 @@ These attributes control the appearance of the axis: :attr:`tick_out` pixels (default is 5). -:attr:`~chaco.axis.PlotAxis.tick_label_font`, -:attr:`~chaco.axis.PlotAxis.tick_label_color`, -:attr:`~chaco.axis.PlotAxis.tick_label_rotate_angle`, -:attr:`~chaco.axis.PlotAxis.tick_label_alignment`, -:attr:`~chaco.axis.PlotAxis.tick_label_margin`, -:attr:`~chaco.axis.PlotAxis.tick_label_offset`, -:attr:`~chaco.axis.PlotAxis.tick_label_position`, - +:attr:`~chaco.axis.PlotAxis.tick_label_font`, :attr:`~chaco.axis.PlotAxis.tick_label_color`, :attr:`~chaco.axis.PlotAxis.tick_label_rotate_angle`, :attr:`~chaco.axis.PlotAxis.tick_label_alignment`, :attr:`~chaco.axis.PlotAxis.tick_label_margin`, :attr:`~chaco.axis.PlotAxis.tick_label_offset`, :attr:`~chaco.axis.PlotAxis.tick_label_position`, These attributes allow to fine-tune the aspect of the tick labels: first of all, the font (e.g. '12 pt bold italic') and color of the labels. The position and orientation of the label can be also be @@ -139,7 +122,6 @@ These attributes control the appearance of the axis: :attr:`~chaco.axis.PlotAxis.tick_label_formatter` - By default, tick labels are assumed to be floating point numbers, and are displayed as such after removing trailing zeros and the decimal dot if necessary (e.g., '10.000' will be displayed as '10', and '21.10' as '21.1'). @@ -148,9 +130,7 @@ These attributes control the appearance of the axis: formatted string. -:attr:`~chaco.axis.PlotAxis.tick_interval`, -:attr:`~chaco.axis.PlotAxis.tick_generator`, - +:attr:`~chaco.axis.PlotAxis.tick_interval`, :attr:`~chaco.axis.PlotAxis.tick_generator`, Locations and distances of ticks are controlled by the attribute :attr:`tick_generator` @@ -162,9 +142,8 @@ These attributes control the appearance of the axis: Events ------ -updated - -Fired when the axis's range bounds change. +:attr:`~chaco.axis.PlotAxis.updated` + Fired when the axis's range bounds change. .. _legend: diff --git a/docs/source/user_manual/basic_elements/plot_renderers.rst b/docs/source/user_manual/basic_elements/plot_renderers.rst index f268057bf..784cf3ee8 100644 --- a/docs/source/user_manual/basic_elements/plot_renderers.rst +++ b/docs/source/user_manual/basic_elements/plot_renderers.rst @@ -58,86 +58,64 @@ that includes the padding and border area. The properties of the boxes are controlled by these attributes: - :attr:`position` - - Position of the internal box relative to its container, - given as a list [x,y]. - If there is no container, this is set to [0, 0]. - "Absolute" coordinates of point (i.e., relative to top-level parent - :class:`Window` object) can be obtained using - :attr:`get_absolute_coords(*coords)`. - - :attr:`x`, :attr:`y`, :attr:`x2`, :attr:`y2` - - Coordinates of the lower-left (x,y) and upper-right (x2,y2) - pixel of the internal box, relative to its container. - - :attr:`bounds`, - :attr:`width`, :attr:`height` - - Bounds of the internal box, in pixels. - :attr:`bounds` is a list [width, height]. - - - :attr:`outer_position`, - :attr:`outer_x`, :attr:`outer_y`, :attr:`outer_x2`, :attr:`outer_y2`, - :attr:`outer_bounds`, - :attr:`outer_width`, :attr:`outer_height`, - :attr:`set_outer_position(index, value)`, - :attr:`set_outer_bounds(index, value)` - - Attributes for the outer box equivalent to those defined above for the - inner box. Modifying the outer position attributes is - the right way to move the plot without changing its padding or bounds. - Similarly, modifying the outer bounds attributes leaves the - lower-left position and the padding unchanged. - - - :attr:`resizable`, - :attr:`fixed_preferred_size` - - String that defines in which dimensions the component is resizable. - One of '' (not resizable), 'v' (resizable vertically), 'h' - (resizable horizontally), 'hv' (resizable in both directions, default). - If the component is resizable, :attr:`fixed_preferred_size` - can be used to specify the - amount of space that the component would like to get in each dimension, - as a tuple (width, height). In this case, width and height have to be - understood as relative sized: if one component in a container - specifies, say, a fixed preferred width of 50 and another one - specifies a fixed preferred width of 100, then the latter component will - always be twice as wide as the former. - - :attr:`aspect_ratio`, - :attr:`auto_center` - - Ratio of the component's width to its height. This is used to maintain - a fixed ratio between bounds when thet are changed independently, - for example when resizing the window. :attr:`auto_center` - specifies if the component should center itself in any space - that is left empty (default is True). - - :attr:`padding_left`, - :attr:`padding_right`, - :attr:`padding_top`, - :attr:`padding_bottom`, - :attr:`padding`, - :attr:`hpadding`, - :attr:`vpadding` - - Padding space (in pixels). :attr:`padding` is a convenience property - that returns a tuple of (left, right, top, bottom) padding. It can - also be set to a single integer, in which case all four padding - attributes are set to the same value. - - :attr:`hpadding` and :attr:`vpadding` are read-only properties that return - the total amount of horizontal and vertical padding (including - the border width if the border is visible). - - :attr:`get_absolute_coords(*coords)` - - Transform coordinates relative to this component's origin to - "absolute" coordinates, relative to top-level container. +:attr:`position` + Position of the internal box relative to its container, + given as a list [x,y]. + If there is no container, this is set to [0, 0]. + "Absolute" coordinates of point (i.e., relative to top-level parent + :class:`Window` object) can be obtained using + :attr:`get_absolute_coords(*coords)`. + +:attr:`x`, :attr:`y`, :attr:`x2`, :attr:`y2` + Coordinates of the lower-left (x,y) and upper-right (x2,y2) + pixel of the internal box, relative to its container. + +:attr:`bounds`, :attr:`width`, :attr:`height` + Bounds of the internal box, in pixels. + :attr:`bounds` is a list [width, height]. + + +:attr:`outer_position`, :attr:`outer_x`, :attr:`outer_y`, :attr:`outer_x2`, :attr:`outer_y2`, :attr:`outer_bounds`, :attr:`outer_width`, :attr:`outer_height`, :meth:`set_outer_position`, :meth:`set_outer_bounds` + Attributes for the outer box equivalent to those defined above for the + inner box. Modifying the outer position attributes is + the right way to move the plot without changing its padding or bounds. + Similarly, modifying the outer bounds attributes leaves the + lower-left position and the padding unchanged. + + +:attr:`resizable`, :attr:`fixed_preferred_size` + String that defines in which dimensions the component is resizable. + One of '' (not resizable), 'v' (resizable vertically), 'h' + (resizable horizontally), 'hv' (resizable in both directions, default). + If the component is resizable, :attr:`fixed_preferred_size` + can be used to specify the + amount of space that the component would like to get in each dimension, + as a tuple (width, height). In this case, width and height have to be + understood as relative sized: if one component in a container + specifies, say, a fixed preferred width of 50 and another one + specifies a fixed preferred width of 100, then the latter component will + always be twice as wide as the former. + +:attr:`aspect_ratio`, :attr:`auto_center` + Ratio of the component's width to its height. This is used to maintain + a fixed ratio between bounds when thet are changed independently, + for example when resizing the window. :attr:`auto_center` + specifies if the component should center itself in any space + that is left empty (default is True). + +:attr:`padding_left`, :attr:`padding_right`, :attr:`padding_top`, :attr:`padding_bottom`, :attr:`padding`, :attr:`hpadding`, :attr:`vpadding` + Padding space (in pixels). :attr:`padding` is a convenience property + that returns a tuple of (left, right, top, bottom) padding. It can + also be set to a single integer, in which case all four padding + attributes are set to the same value. + + :attr:`hpadding` and :attr:`vpadding` are read-only properties that return + the total amount of horizontal and vertical padding (including + the border width if the border is visible). + +:attr:`get_absolute_coords(*coords)` + Transform coordinates relative to this component's origin to + "absolute" coordinates, relative to top-level container. Aspect properties ----------------- @@ -145,33 +123,27 @@ Aspect properties These attributes control the aspect (e.g. color) of padding, background, and borders: - :attr:`bgcolor` +:attr:`bgcolor` + The background color of this component (default is white). This can be + set to "transparent" or "none" if the component should be see-through. + The color can be specified as a string or as an RGB or RGBa tuple. - The background color of this component (default is white). This can be - set to "transparent" or "none" if the component should be see-through. - The color can be specified as a string or as an RGB or RGBa tuple. +:attr:`fill_padding` + If True (default), fill the padding area with the background color. - :attr:`fill_padding` +:attr:`border_visible` + Determines if the border is visible (default is False). - If True (default), fill the padding area with the background color. +:attr:`border_width` + Thickness of the border around the component in pixels (default is 1). - :attr:`border_visible` +:attr:`border_dash` + Style of the lines tracing the border. One of 'solid' (default), + 'dot dash', 'dash', 'dot', or 'long dash'. - Determines if the border is visible (default is False). - - :attr:`border_width` - - Thickness of the border around the component in pixels (default is 1). - - :attr:`border_dash` - - Style of the lines tracing the border. One of 'solid' (default), - 'dot dash', 'dash', 'dot', or 'long dash'. - - :attr:`border_color` - - Color of the border. - The color can be specified as a string or as an RGB or RGBa tuple. +:attr:`border_color` + Color of the border. + The color can be specified as a string or as an RGB or RGBa tuple. .. _plot_layers: @@ -187,29 +159,29 @@ The default drawing order is defined in :attr:`~chaco.plot_component.PlotComponent.draw_order` as a list of the names of the layers. The definition of the layers is as follows: - 1. 'background': Background image, shading, and borders +1. **background**: Background image, shading, and borders - 2. 'image': A special layer for plots that render as images. This is in a - separate layer since these plots must all render before non-image plots +2. **image**: A special layer for plots that render as images. This is in a + separate layer since these plots must all render before non-image plots - 3. 'underlay': Axes and grids +3. **underlay**: Axes and grids - 4. 'plot': The main plot area itself +4. **plot**: The main plot area itself - 5. 'annotation': Lines and text that are conceptually part of the "plot" but - need to be rendered on top of everything else in the plot. +5. **annotation**: Lines and text that are conceptually part of the "plot" but + need to be rendered on top of everything else in the plot. - 6. 'selection': Selected content are rendered above normal plot elements to - make them stand out. This can be disabled by setting :attr:`use_selection` - to False (default). +6. **selection**: Selected content are rendered above normal plot elements to + make them stand out. This can be disabled by setting :attr:`use_selection` + to False (default). - 7. 'border': Plot borders +7. **border**: Plot borders - 8. 'annotation': Lines and text that are conceptually part of the "plot" but - need to be rendered on top of everything else in the plot +8. **annotation**: Lines and text that are conceptually part of the "plot" but + need to be rendered on top of everything else in the plot - 9. 'overlay': Legends, selection regions, and other tool-drawn visual - elements +9. **overlay**: Legends, selection regions, and other tool-drawn visual + elements Concrete plot renderers set their default draw layer in :attr:`~chaco.plot_component.PlotComponent.draw_layer` (default is 'plot'). @@ -230,7 +202,7 @@ as such are able to react to keyboard and mouse events. However, interactions are usually defined as tools and overlays. Therefore, this part of the interface is described at those pages. -TODO: add reference to interaction interface +.. TODO: add reference to interaction interface Context ------- @@ -238,18 +210,15 @@ Context Since plot renderers take care of displaying graphics, they keep references to the larger graphical context: - :attr:`container` - - Reference to a container object (None if no container is defined). - The renderer defines its position relative to this. - - :attr:`window` +:attr:`container` + Reference to a container object (None if no container is defined). + The renderer defines its position relative to this. - Reference to the top-level enable Window. +:attr:`window` + Reference to the top-level enable Window. - :attr:`viewports` - - List of viewport that are viewing this component +:attr:`viewports` + List of viewport that are viewing this component Screen and Data Mapping ----------------------- @@ -258,52 +227,47 @@ All :class:`~chaco.abstract_plot_renderer.AbstractPlotRenderer` subclasses are expected to provide three methods for mapping to and from screen space and data space: - .. :py:method:: map_screen(data_array) - - :map_screen: +.. :py:method:: map_screen(data_array) - This is expected to take an array of points (as columns) in - the appropriate data coordinates, and return the corresponding points - in screen pixel coordinates (measured from the bottom left of the - plot component). +:map_screen: + This is expected to take an array of points (as columns) in + the appropriate data coordinates, and return the corresponding points + in screen pixel coordinates (measured from the bottom left of the + plot component). - .. :py:method: map_data(screen_pt) +.. :py:method: map_data(screen_pt) - :map_data: +:map_data: + This is the reverse of map_screen, and takes an array of + points (as columns) screen pixel coordinates relative to the renderer + component and return the corresponding points in screen data + coordinates. - This is the reverse of map_screen, and takes an array of - points (as columns) screen pixel coordinates relative to the renderer - component and return the corresponding points in screen data - coordinates. +.. :py:method:map_index(screen_pt, + threshold=0.0, + outside_returns_none=True, + index_only=False) - .. :py:method:map_index(screen_pt, - threshold=0.0, - outside_returns_none=True, - index_only=False) - - :map_index: - - This method takes a point in screen pixel coordinates and returns an - appropriate index value that can be used to index into data. This can - be used by hit-testing methods (see below), and provides optional - arguments such as threshold distances. Not every renderer implements - this, and some data sets may not be amenable to this method, either. +:map_index: + This method takes a point in screen pixel coordinates and returns an + appropriate index value that can be used to index into data. This can + be used by hit-testing methods (see below), and provides optional + arguments such as threshold distances. Not every renderer implements + this, and some data sets may not be amenable to this method, either. Others ------ - :attr:`use_backbuffer` - - If True, the plot renders itself to an - offscreen buffer that is cached for later use. If False (default), then - the component will *never* render itself back-buffered, even if asked - to do so. +:attr:`use_backbuffer` + If True, the plot renders itself to an + offscreen buffer that is cached for later use. If False (default), then + the component will *never* render itself back-buffered, even if asked + to do so. - :attr:`invalidate_and_redraw()` - - Convenience method to invalidate our contents and request redraw. - This method is sometimes useful when modifying a Chaco plot in an - ipython shell. +:meth:`invalidate_and_redraw` + Convenience method to invalidate our contents and request redraw. + This method is sometimes useful when modifying a Chaco plot in an + ipython shell. .. _xy_plots: @@ -350,27 +314,22 @@ Axis, labels, and grids shortcuts to find axis and grid objects in the :ref:`underlays and overlays layers ` of the plot: - :attr:`~chaco.base_xy_plot.BaseXYPlot.hgrid`, - :attr:`~chaco.base_xy_plot.BaseXYPlot.vgrid` - - Look into the underlays and overlays layers (in this order) for a - :class:`PlotGrid` object of horizontals / vertical orientation and return - it. Return None if none is found. +:attr:`~chaco.base_xy_plot.BaseXYPlot.hgrid`, :attr:`~chaco.base_xy_plot.BaseXYPlot.vgrid` + Look into the underlays and overlays layers (in this order) for a + :class:`PlotGrid` object of horizontals / vertical orientation and return + it. Return None if none is found. - :attr:`~chaco.base_xy_plot.BaseXYPlot.x_axis`, - :attr:`~chaco.base_xy_plot.BaseXYPlot.y_axis` +:attr:`~chaco.base_xy_plot.BaseXYPlot.x_axis`, :attr:`~chaco.base_xy_plot.BaseXYPlot.y_axis` + Look into the underlays and overlays layers (in this order) for a + :class:`PlotAxis` object positioned to the bottom or top, or to the + left or right of plot, respectively. Return the axis, or None if + none is found. - Look into the underlays and overlays layers (in this order) for a - :class:`PlotAxis` object positioned to the bottom or top, or to the - left or right of plot, respectively. Return the axis, or None if - none is found. +:attr:`~chaco.base_xy_plot.BaseXYPlot.labels` + Return a list of all :class:`PlotLabel` objects in the + overlays and underlays layers. - :attr:`~chaco.base_xy_plot.BaseXYPlot.labels` - - Return a list of all :class:`PlotLabel` objects in the - overlays and underlays layers. - -TODO: add links to axis and grid documentation +.. TODO: add links to axis and grid documentation Hittest ------- @@ -393,8 +352,8 @@ which is one of 'point' (default), or 'line'. If the closest point or line is further than :attr:`threshold` pixels away, the methods returns None. -Alternatively, users may call the methods :attr:`get_closest_point` -and :attr:`get_closest_line`. +Alternatively, users may call the methods :meth:`get_closest_point` +and :meth:`get_closest_line`. Others ------ @@ -402,12 +361,10 @@ Others Two more attributes are worth mentioning: :attr:`~chaco.base_xy_plot.BaseXYPlot.bgcolor` - This is inherited from the AbstractPlotRenderer interface, but is now - set to 'transparent` by default. + set to 'transparent' by default. :attr:`~chaco.base_xy_plot.BaseXYPlot.use_downsampling` - If this attribute is True, the plot uses downsampling for faster display (default is False). In other words, the number of display points depends on the plot size and range, and not on the total number of data points From c4d460718845000437f2799781eec8b44fa4f8a2 Mon Sep 17 00:00:00 2001 From: aaronayres35 <36972686+aaronayres35@users.noreply.github.com> Date: Wed, 10 Mar 2021 06:03:41 -0700 Subject: [PATCH 2/2] Update docs/source/user_manual/basic_elements/overlays.rst Co-authored-by: Poruri Sai Rahul --- docs/source/user_manual/basic_elements/overlays.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/user_manual/basic_elements/overlays.rst b/docs/source/user_manual/basic_elements/overlays.rst index e378042a9..c3b88d934 100644 --- a/docs/source/user_manual/basic_elements/overlays.rst +++ b/docs/source/user_manual/basic_elements/overlays.rst @@ -1,5 +1,5 @@ ================================== -Overlays: axis, and, grid, etc. +Overlays: Axis, Grid, etc. ================================== Overlays are elements that decorate plots, like for example @@ -154,4 +154,3 @@ Legend Grid ==== -