Documentation Center

  • Trial Software
  • Product Updates

brush

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

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.
FigureHandleThe associated figure handle. This property supports get only.
ColorSpecifies 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.

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');

More About

expand all

Tips

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 TypeBrushing AnnotationOverlays?Example
lineseriesColored 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 highlightedY

scattergroupLine with LineStyle 'none' and a marker with a color distinct from and slightly larger than the base scattergroup marker.Y

stemseriesThe brushed stems and stem heads are shaded in the brushing color.Y

barseriesThe interior of selected bars is filled in the brushing color.N

histogramThe bars to which brushed observations contribute are proportionately filled from the bottom up with the brushing color.N

areaseriesPatches filling the region between selected points and the x-axis in the brushing color.N

surfaceplotPatches 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 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 (see Types of Plots You Can Brush and Plot Types You Cannot 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.

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.

ActionGestureResult
Select data using a region of interest ROI mouse dragRegion 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 pointSingle left-click on a graphic object that supports data brushingProduces 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 oneSingle left-click on a graphic object that supports data brushing, with the Shift key downEquivalent 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 objectDouble left-click on a graphic object that supports data brushingAll vertices for the graphic object are brushed.
Add to or subtract from region of interestClick 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 desktopEquivalent to copying brushed data and pasting into other window or an existing/new variable.

Brush Mode Callbacks

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(obj,event_obj)
    % obj         handle to the figure that has been clicked
    % event_obj   object containing struct of event data
    

    The event data struct has the following field:

    Axes

    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(obj,event_obj)
    % obj         handle to the figure that has been clicked
    % event_obj   object containing struct of event data
    %				    (same as the event data of the
    %             'ActionPreCallback' callback)
    

See Also

| | | |

Was this topic helpful?