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');
Data brushing places lines and patches on plots to create highlighting, marking different types of graphs as follows (brushing marks are shown in red):
|Graph Type||Brushing Annotation||Overlays?||Example|
|line||Colored lines slightly wider than those in the line with a marker distinct from those on the line (filled circles if none) to identify brushed vertices. Only those line segments that connect brushed vertices are highlighted||Y|
|scatter||Line with ||Y|
|stem||The brushed stems and stem heads are shaded in the brushing color.||Y|
|bar||The interior of selected bars is filled in the brushing color.||N|
|area||Patches filling the region between selected points and the x-axis in the brushing color.||N|
|surface||Faces with edges slightly wider than the surface line width and with a marker distinct from that of the surface (X if none) to identify brushed vertices. Faces are plotted only when all four vertices that define them are brushed. The brushed observations are the set of marked vertices, not the faces.||N|
When using the linked plots feature, a graph can become brushed when you brush another graph that displays some of the same data, potentially brushing the same observations more than once. The overlaid brushing marks (whether lines or markers) are slightly wider than the brushing marks that they overlay; this makes multiply brushed observations visually distinct. The wider brushing marks are placed under the narrower ones, so that if they happen to have different colors, you can see all the colors. See the subsection How Data Linking Affects Data Brushing for more information about brushing linked figures.
As the above table indicates, only line, scatter, and stem brushing marks can be overlaid in this manner. Although you can brush them, you cannot overlay brushing marks on area, bar, or surface.
Currently, not all plot types enable data brushing. Graph functions that do not support brushing are:
Line plots created with
Scatter plots created with
Contour plots created with
Pie charts created with
Radial graphs created with
Direction graphs created with
Area and image plots created with
Bar graphs created with
Functional plots created with
3-D plot types other than
You can use some of these functions to display base
data that do not need to be brushable. For example, use
plot mean y-values as horizontal lines that you
do not need or want to brush.
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 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.|
|Select all data associated with a graphic object||Double left-click on a graphic object that supports data brushing||All vertices for the graphic object are 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.|
|Copy brushed data to Editor, Command Window, Variables editor, or Workspace Browser||Drag brushed data to another window or to a program/icon on the system desktop||Equivalent to copying brushed data and pasting into other window or an existing/new variable.|
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