MATLAB Function Reference

brush

Interactively mark, delete, modify, and save observations in graphs

GUI Alternatives

To turn data brushing on or off, use the Data Brushing tool in the figure toolbar, the right side of which drops down as a color palette for changing the current brushing color. For details, see Marking Up Graphs with Data Brushing in the MATLAB^® Data Analysis documentation.

Syntax

brush on brush off brush brush color brush(figure_handle,...) brushobj = brush(figure_handle)

Description

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 mode.

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 ColorSpec. 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 get and set:

`Enable` `'on' \| {'off'}`	Specifies whether this figure mode is currently enabled on the figure.
`FigureHandle`	The associated figure handle. This property supports `get` only.
`Color`	Specifies the color to be used for brushing.

brush cannot return a brush mode object at the same time you are calling it to set a brushing option.

Remarks

Types of Plots You Can Brush

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?
lineseries	Colored lines slightly wider than those in the lineseries with a marker distinct from those on the lineseries (filled circles if none) to identify brushed vertices. Only those line segments that connect brushed vertices are highlighted	Y
scattergroup	Line with `LineStyle 'none'` and a marker with a color distinct from and slightly larger than the base scattergroup marker.	Y
stemseries	The brushed stems and stem heads are shaded in the brushing color.	Y
barseries	The interior of selected bars is filled in the brushing color.	N
histogram	The bars to which brushed observations contribute are proportionately filled from the bottom up with the brushing color.	N
areaseries	Patches filling the region between selected points and the x-axis in the brushing color.	N
surfaceplot	Patches with edges slightly wider than the surfaceplot line width and with a marker distinct from that of the surfaceplot (X if none) to identify brushed vertices. Patches are plotted only when all four vertices that define them are brushed. The brushed observations are the set of marked vertices, not the patches.	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 lineseries, scatterseries, and stemseries brushing marks can be overlaid in this manner. Although you can brush them, you cannot overlay brushing marks on areaseries, barseries, histograms, or surfaceplots.

Plot Types You Cannot Brush

Currently, not all plot types enable data brushing. Graph functions that do not support brushing are:

Line plots created with line
Scatter plots created with spy
Contour plots created with contour, contourf, or contour3
Pie charts created with pie or pie3
Radial graphs created with polar, compass, or rose
Direction graphs created with feather, quiver, or comet
Area and image plots created with fill, image, imagesc, or pcolor
Bar graphs created with pareto or errorbar
Functional plots created with ezcontour or ezcontourf
3-D plot types other than plot3, stem3, scatter3, mesh, meshc, surf, surfl, and surfc

You can use some of these functions to display base data that do not need to be brushable. For example, use line to plot mean y-values as horizontal lines that you do not need or want to brush.

Mode Exclusivity and Persistence

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 via 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 brushing marks on it until you brush it again. If you hold down the Shift key, 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 brush(colorspec), or by setting the Color property of a brush mode object (e.g., set(brushobj,'Color',colorspec).

How Data Linking Affects Data Brushing

When you use the Data Linking tool or call the linkdata function, brushing marks that you make on one plot appear on other plots that depict the same variable you are brushing—if they 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 Variable Editor. Two limiting conditions apply, however:

The graph type must support data brushing (see Types of Plots You Can Brush and Plot Types You Cannot Brush)
The graphed variable should 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.

Brush marks on a an unlinked graph can change color when data linking is turned on for that figure. They can, in fact, vanish and be replaced by marks in the same or different color when the plot enters a linked state. This happens because in the linked state, the variables (data sources) are brushed, not just the graphics. If different observations for the same variable on a linked figure are brushed, those brushed 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.

Mouse Gestures for Data Brushing

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.

Action	Gesture	Result
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, Variable 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.

Examples

Example 1

On a scatterplot, drag out a rectangle to brush the graph:

x = rand(20,1);
y = rand(20,1);
scatter(x,y,80,'s')
brush on

Example 2

Brush observations from -.2 to .2 on a lineseries 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');