Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

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

Example 2

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

More About

collapse all

Tips

Types of Charts You Can Brush

Not all charts support data brushing. The graphics functions listed here create charts that support data brushing.

  • Line charts created with plot, plot3, loglog, semilogx, semilogy, or stairs. Brushing highlights a line segment when you brush both vertices of the line segment.

  • Scatter charts created with scatter, scatter3, or spy.

  • Stem charts created with stem or stem3.

  • Area charts created with area

  • Bar charts created with bar or barh.

  • Radial charts created with compass, feather, rose or ezpolar.

  • Surface charts created with surf, surfc, surfl, mesh, meshc, or meshz. Brushing highlights a surface face when you brush all four vertices of the face.

  • Histogram charts created with histogram or histogram2. Before you can enable brushing, turn on data linking using the linkdata on command or by selecting the link plot icon in the figure toolbar.

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

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

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(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:

    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(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
Was this topic helpful?