Marking Up Graphs with Data Brushing

What Is Data Brushing?

When you brush data, you manually select observations on an interactive data display in the course of assessing validity, testing hypotheses, or segregating observations for further processing. You can brush data on 2-D graphs, 3-D graphs, and surfaces. Most of the MATLAB® high-level plotting functions allow you to brush on their displays. For a list of restrictions, see Plot Types You Cannot Brush in the brush function reference page, which also illustrates the types of graphs you can brush.

Data brushing is a MATLAB figure interactive mode like zooming, panning or plot editing. You can use data brushing mode to select, remove, and replace individual data values.

Activate data brushing in any of these ways:

  • Click on the figure toolbar.

  • Select Tools > Brush.

  • Right-click a cell in the Variables editor and select Brushing > Brushing on.

  • Call the brush function.

The figure toolbar data brushing button contains two parts:

  • Data brushing button that toggles data brushing on and off.

  • Data brushing button arrow ▼ that displays a drop-down menu for choosing the brushing color.

You also can set the color with the brush function; it accepts ColorSpec names and RGB triplets. For example:

brush magenta
brush([.1 .3 .5])

How to Brush Data

To brush observations on graphs and surface plots,

  1. To enter brushing mode, select the Data Brushing button in the figure toolbar. You also can select a brushing color with the Data Brushing button arrow ▼.

  2. Drag a selection rectangle to highlight observations on a graph in the current brushing color.
    Instead of dragging out a rectangle, you can click any observation to select it. Double-clicking selects all the observations in a series.

  3. To add other observations to the highlighted set, hold down the Shift key and brush them.

  4. Shift+clicking or Shift+dragging highlighted observations eliminates their highlighting and removes them from the selection set; this lets you select any set of observations.

The following figures show a scatter plot before and after brushing some outlying observations; the left-hand plot displays the Data Brushing tool palette for choosing a brush color.

Brushed observations remain brushed even in other modes (pan, zoom, edit) until you deselect them by brushing an empty area or by selecting Clear all brushing from the context menu. You can add and remove data tips to a brushed plot without disturbing its brushing.

Once you have brushed observations from one or more graphed variables, you can perform several tasks with the brushing set, either from the Tools menu or by right-clicking any brushed observation:

  • Remove all brushed observations from the plot.

  • Remove all unbrushed observations from the plot.

  • Replace the brushed observations with NaN or constant values.

  • Copy the brushed data values to the clipboard.

  • Paste the brushed data values to the command window

  • Create a variable to hold the brushed data values

  • Clear brushing marks from the plot (context menu only)

The two following figures show a lineseries plot of a variable, along with constant lines showing its mean and two standard deviations. On the left, the user is brushing observations that lie beyond two standard deviations from the mean. On the right, the user has eliminated these extreme values by selecting Brushing > Remove brushed from the Tools (or context) menu. The plot immediately redisplays with three fewer x- and y-values. The original workspace variable, however, remains unchanged.

Before removing the extreme values, you can save them as a new workspace variable with Tools > Brushing > Create new variable. Doing this opens a dialog box for you to declare a variable name.

Typing extremevals to name the variable and pressing OK to dismiss the dialog produces

extremevals =

    9.0000    3.5784
   12.0000    3.0349
   35.0000   -2.9443
The new variable contains one row per observation selected. The first column contains the x-values and the second column contains the y-values, copied from the lineseries' XData and YData. In graphs where multiple series are brushed, the Create New Variable dialog box helps you identify what series the new variable should represent, allowing you to select and name one at a time.

Effects of Brushing on Data

Brushing simply highlights data points in a graph, without affecting data on which the plot is based. If you remove brushed or unbrushed observations or replace them with NaN values, the change applies to the XData, YData, and possibly ZData properties of the plot itself, but not to variables in the workspace. You can undo such changes. However, if you replot a brushed graph using the same workspace variables, not only do its brushing marks go away, all removed or replaced values are restored and you cannot undo it. If you want brushing to affect the underlying workspace data, you must link the plot to the variables it displays. See Making Graphs Responsive with Data Linking for more information.

Brushed 3-D Plots

When an axes displays three-dimensional graphics, brushing defines a region of interest (ROI) as an unbounded rectangular prism. The central axis of the prism is a line perpendicular to the plane of the screen. Opposite corners of the prism pass through points defined by the CurrentPoint associated with the initial mouse click and the value of CurrentPoint during the drag. All vertices lying within the rectangular prism ROI highlight as you brush them, even those that are hidden from view.

The next figure contains two views of a brushed ROI on a peaks surface plot. On the left plot, only the cross-section of the rectangular prism is visible (the brown rectangle) because the central axis of the prism is perpendicular to the viewing plane. When the viewpoint rotates by about 90 degrees clockwise (right-hand plot), you see that the prism extends along the initial axis of view and that the brushed region conforms to the surface.

Brushed Multiple Plots

When the same x-, y- or z-variable appears in several plots, brushing observations in one plot highlights the related observations in the other plots when they are linked. If the brushed variables are open in the Variables editor, the rows containing the brushed observations are highlighted. For more information, see Data Brushing with the Variables Editor.

Organizing Plots for Brushing.  Data brushing usually involves creating multiple views of related variables on graphs and in tables. Just as computer users organize their virtual desktops in many different ways, you can use various strategies for viewing sets of plots:

  • Multiple overlapping figure windows

  • Tiled figure windows

  • Tabbed figure windows

  • Subplots presenting multiple views

When MATLAB figures are created, by default, they appear as separate windows. Many users keep them as such, arranging, overlapping, hiding and showing them as their work requires. Any figure, however, can dock inside a figure group, which itself can float or dock in the MATLAB desktop. Once docked in a figure group, you can float and overlap the individual plots, tile them in various arrangements, or use tabs to show and hide them.

    Note:   For more information on managing figure windows, see Document Layout.

Another way of organizing plots is to arrange them as subplots within a single figure window, as illustrated in the example for Linking vs. Refreshing Plots. You create and organize subplots with the subplot function. Subplots are useful when you have an idea of how many graphs you want to work with simultaneously and how you want to arrange them (they do not need to be all the same size).

    Note:   You can easily set up MATLAB code files to create subplots; see subplot for more information.

Other Data Brushing Aspects

Not all types of graphs can be brushed, and each type that you can brush is marked up in a particular way. To be brushable, a graphic object must have XDataSource, YDataSource, and where applicable, ZDataSource properties. The one exception is the patch objects produced by the histogram function, which are brushable due to the special handling they receive. In order to brush a histogram, you must put the figure containing it into a linked state.

The brush function reference page explains how to apply brushing to different graph types, describes how to use different mouse gestures for brushing, and lists graph types that you can and cannot brush. See the following sections:

Keep in mind that data brushing is a mode that operates on entire figures, like zoom, pan, or other modes. This means that some figures can be in data brushing mode at the same time other figures are in other modes. When you dock multiple figures into a figure group, there is only one toolbar, which reflects the state or mode of whatever figure docked in the group you happen to select. Thus, even when docked, some graphs may be in data brushing mode while others are not.

If an axes contains a plot type that cannot be brushed, such as an image object, you can select the figure's Data Brushing tool and trace out a rectangle by dragging it, but no brush marks appear. When you lay out graphs in subplots within a single figure and enter data brushing mode, all the subplot axes become brushable as long as the graphic objects they contain are brushable. If the figure is also in a linked state, brushing one subplot marks any other in the figure that shares a data source with it. Although this also happens when separate figures are linked and brushed, you can prevent individual figures from being brushed by unlinking them from data sources.

Was this topic helpful?