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.

[warning]Data brushing is a MATLAB figure interactive mode like zooming, panning or plot editing. Unlike plot edit mode, in which you can affect a graph’s appearance and compose annotations but cannot manipulate its data, in data brushing mode you can select, remove, and replace individual data values.
Data brushing mode applies to an entire figure and all axes within it that contain brushable data.[/warning]

Activate data brushing in any of these ways:

• Click the Data Brushing tool button on the figure toolbar.
• Click the Data Brushing tool button in the Variable Editor toolbar.
• Select Brush from the figure Tools menu.
• Call the brush function.

By default, data brushing is off. The Data Brushing tool button contains two parts and has a dual role:

• When you click the tool icon on its left side, it toggles data brushing mode on and off.
• When you click the down arrow on its right side, it displays a drop-down menu for choosing a color for brushing data.

You can set the color with the brush function as well; it accepts colorspec names and RGB triplets. For example:

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

The figures below 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. The information bar informs you that data brushing and linking are available for figures and contains hyperlinks to this page and other documentation. Once you dismiss this information bar by clicking the X on its right-hand side, it only reappears on subsequent plots if you select Show linking and brushing message bar in the MATLAB Preferences Confirmation Dialogs pane.

How to Brush Data

To brush observations on graphs and surface plots,

• To enter brushing mode, select the Data Brushing tool; click the icon on the left side to activate the mode, and optionally select a brushing color by clicking the arrow on its right side.
• 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.
• To add other observations to the highlighted set, hold down the Shift key and brush them.
• 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.

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 two 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 =
   48.0000   25.7000
   50.0000   19.5000

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

When the same x-, y- or z-variable appears in several plots, brushing observations in one plot highlights the related ones in the others whenever the plots are linked. If the brushed variables are open in the Variable Editor, rows of data containing the brushed observations are highlighted in the brushing color there as well. For more information, see Data Brushing with the Variable Editor.

[warning]You can see brushed observations highlighted in the Variable Editor if you activate the Data Brushing tool on its toolbar. In data brushing mode, you can directly brush data values in the Variable Editor to highlight them on plots. In addition, if you change any values in the Variable Editor, all linked graphs on which they appear reflect those changes.[/warning]

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.

[warning]For more in formation on managing figure windows, see Floating (Cascaded) Figures in Desktop Example in the MATLAB Desktop documentation. Managing Plotting Tools in the MATLAB Graphics documentation provides related details.[/warning]

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, for which there is no GUI as there is for figure groups. 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).

[warning]You can easily set up MATLAB code files to create subplots; see Setting Up Figures in the Graphics documentation.[/warning]

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 hist 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. For related information, see Plot Objects in the MATLAB Graphics documentation.

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:

• Types of Plots You Can Brush
• Plot Types You Cannot Brush
• Mouse Gestures for Data Brushing

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, you can select the figure’s Data Brushing tool and trace out a rectangle by dragging it, but no brush marks appear. The following figure group contains a histogram and a scatter plot that describe intensity statistics for the image displayed in the middle. Although the graphs are brushable, the image itself is not. Here the graphs are shown brushed, after having linked to their data sources.

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.