Interactively mark, delete, modify, and save observations in graphs
brushobj = brush(figure_handle)
Data brushing is a mode for interacting with graphs in figure windows in which you can click data points or drag a selection rectangle around data points to highlight observations in a color of your choice. Highlighting takes different forms for different types of graphs, and brushing marks persist—even in other interactive modes—until removed by deselecting them.
brush on turns on interactive data brushing
brush off turns brushing mode off, leaving
any brushed observations still highlighted.
brush by itself toggles
the state of the data brushing tool.
brush color sets the current color used
for brushing graphics to the specified
Changing brush color affects subsequent brushing, but does not change
the color of observations already brushed or the brush tool's state.
brush(figure_handle,...) applies the function
to the specified figure handle.
brushobj = brush(figure_handle) returns
a brush mode object for that figure, useful
for controlling and customizing the figure's brushing state. The following
properties of such objects can be modified using
|Specifies whether this figure mode is currently enabled on the figure.|
|The associated figure handle. This property supports |
|Specifies the color to be used for brushing.|
return a brush mode object at the same time you are calling it to
set a brushing option.
On a scatter plot, drag out a rectangle to brush the graph:
x = rand(20,1); y = rand(20,1); scatter(x,y,80,'s') brush on
Brush observations from -.2 to .2 on a line plot in dark red:
x = [-2*pi:.1:2*pi]; y = sin(x); plot(x,y); h = brush; set(h,'Color',[.6 .2 .1],'Enable','on');
Not all charts support data brushing. The graphics functions listed here create charts that support data brushing.
Line charts created with
stairs. Brushing highlights a line segment when
you brush both vertices of the line segment.
Scatter charts created with
Stem charts created with
Area charts created with
Bar charts created with
Radial charts created with
Surface charts created with
meshz. Brushing highlights a surface face when
you brush all four vertices of the face.
Histogram charts created with
Before you can enable brushing, turn on data linking using the
on command or by selecting the link plot icon
in the figure toolbar.
Data brushing mode is exclusive, like zoom,
pan, data cursor, or plot edit mode. However, brush marks created
in data brushing mode persist through all changes
in mode. Brush marks that appear in other graphs while they are linked
linkdata also persist even when data linking
is subsequently turned off. That is, severing connections to a graph's
data sources does not remove brushing marks from it. The only ways
to remove brushing marks are (in brushing mode):
Brush an empty area in a brushed graph.
Right-click and select Clear all brushing from the context menu.
Changing the brushing color for a figure does not recolor existing
brush marks. If you change the brushing color and hold down the Shift key
when brushing new data, all existing brush marks change to the new
color. All brush marks that appear on linked plots in the same or
different figure also change to the new color if the brushing action
affects them. The behavior is the same whether you select a brushing
color from the Brush Tool dropdown palette, set it by calling
or by setting the
Color property of a brush mode
When you use the Data Linking tool or call the
brushing marks that you make on one plot appear on other plots that
depict the same variable you are brushing—if those plots are
also linked. This happens even if the affected plot is not in Brushing
mode. That is, brushing marks appear on a linked plot in
any mode when you brush another plot linked to it via a
common variable or brush that variable in the Variables editor. Be
aware that the following conditions apply, however:
The graph type must support data brushing. For a list, see Types of Charts You Can Brush.
The graphed variable must not be complex; if you can
plot a complex variable you can brush it, but such graphs do not respond
when you brush the complex variable in another linked plot. For more
information about linking complex variables, see Example 3 in the
linkdata reference page.
Observations that you brush display in the same color in all linked graphs. The color is the brush color you have selected in the window you are interacting with, and can differ from the brushing colors selected in the other affected figures. When you brush linked plots, the brushing color is associated with the variable(s) you brush
The last bullet implies that brush marks on an unlinked graph can change color when data linking is turned on for that figure. Brushing marks can, in fact, vanish and be replaced by marks in the same or different color when the plot enters a linked state. In the linked state, brushing is tied to variables (data sources), not just the graphics. If different observations for the same variable on a linked figure are brushed, those variables override the brushed graphics on the newly linked plot. In other words, the newly linked graph loses all its previous brush marks when it "joins the club" of common data sources.
You can brush graphs in several ways. The basic operation is to drag the mouse to highlight all observations within the rectangle you define. The following table lists data brushing gestures and their effects.
|Select data using a Region Of Interest||ROI mouse drag||Region of interest (ROI) rectangle (or rectangular prism for 3-D axes) appears during the gesture and all brushable observations within the rectangle are highlighted. All other brushing marks in the axes are removed. The ROI rectangle disappears when the mouse button is released.|
|Select a single point||Single left-click on a graphic object that supports data brushing||Produces an equivalent result to ROI rectangle, brushing where the rectangle encloses only the single vertex on the graphical object closest to the mouse. All other brushing annotations in the figure are removed.|
|Add a point to the selection or remove a highlighted one||Single left-click on a graphic object that supports data brushing, with the Shift key down||Equivalent brushing by dragging an ROI rectangle that encloses only the single vertex on the graphic object closest to the mouse. All other brushed regions in the figure remain brushed.|
|Add to or subtract from region of interest||Click or ROI drag with the Shift or Ctrl keys down||Region of interest grows; all unbrushed vertices within the rectangle become brushed and all brushed observations in it become unbrushed. All brushed vertices outside the ROI remain brushed.|
You can program the following callbacks for brush mode operations.
ActionPreCallback <function_handle> —
Function to execute before brushing
Use this callback to execute code when a brush operation begins. The function handle should reference a function with two implicit arguments:
function myfunction(src,event_data) % src handle to the figure that has been clicked % event_data object containing event data end
The event data has the following property:
The handle of the axes that is being brushed
ActionPostCallback <function_handle> —
Function to execute after brushing
Use this callback to execute code when a brush operation ends. The function handle should reference a function with two implicit arguments:
function myfunction(src,event_data) % src handle to the figure that has been clicked % event_data object containing event data % (same as the event data of the % 'ActionPreCallback' callback) end