Plotgui: Difference between revisions

From Eigenvector Research Documentation Wiki
Jump to navigation Jump to search
imported>Jeremy
(Importing text file)
 
(35 intermediate revisions by 5 users not shown)
Line 1: Line 1:
===Purpose===
===Purpose===


Line 12: Line 11:
===Description===
===Description===


Plots input data dat and provides a control toolbar in the '''Plot Controls''' window to select portions of the data to view. The toolbar allows interactive selection, exclusion, and classing of rows or columns of data. The PLOTGUI command has various display options that are given as '''PropertyName', PropertyValue'' pairs or as a single keyword. Properties and Keywords are discussed below. To modify options for an existing PLOTGUI figure without providing new data, use the 'update' keyword.
Plots input data <tt>data</tt> and provides a control toolbar in the '''Plot Controls''' window to select portions of the data to view. The toolbar allows interactive selection, exclusion, and classing of rows or columns of data. The PLOTGUI command has various display options that are given as 'PropertyName', 'PropertyValue' pairs or as a single keyword. Properties and Keywords are discussed below.
 
====Inputs====
 
* '''data''' = input data, can be class "double" or "dataset". The description given below is generally listed for two-way data arrays.
: '''Notes: '''Options specific to data that are three-way or image are noted explicitly. PLOTGUI uses the dataset labels, classes, etc. when '''data''' is class "dataset".
* 'update' is used as a keyword input to modify options for an existing PLOTGUI figure without providing new data


PLOTGUI returns the handle of the figure in which the data is displayed (fig).
====Outputs====


Input dat can be class "double" or "dataset". The description given below is generally listed for two-way data arrays. Options specific to data that are three-way or image are noted explicitly. PLOTGUI uses the dataset labels, classes, etc. when dat is class "dataset".
* '''fig''' = the handle of the figure in which the data is displayed


====Plot Controls Toolbar====
====Plot Controls====


The toolbar consists of 1) a menu bar with '''File''', '''Edit''', and '''View''' menus, 2) a figure selection dropdown menu, 3) three axis menus (labeled '''x''', '''y''', and '''z'''), 4) plot update controls '''Plot''' button and '''auto-update''' checkbox, and '''Select''' button.
The toolbar consists of
*1) a menu bar with '''File''', '''Edit''', '''View''', and '''Plot''' menus (see [[Plot Controls Window Menus]] )
*2) a figure selection dropdown menu,  
*3) three axis menus (labeled '''x''', '''y''', and '''z'''),  
*4) plot update controls '''Plot''' button and '''auto-update''' checkbox, and '''Select''' button.


Each figure in the figure selection dropdown menu menu can be modified by the PLOTGUI controls. Selecting a figure from this menu will bring that figure into view and indicate the selected axis menu settings. A "'''+'''" or a "'''\*'''" next to a figure's name indicates that it is linked with another figure (see Duplicate Figure below).
Each figure in the figure selection dropdown menu menu can be modified by the PLOTGUI controls. Selecting a figure from this menu will bring that figure into view and indicate the selected axis menu settings. A "'''+'''" or a "'''\*'''" next to a figure's name indicates that it is linked with another figure (see Duplicate Figure below).
Line 26: Line 35:
The axis menus (labeled '''x''', '''y''', and '''z''') select what parts of the data should be used for the plot. Each column or row selected in the y-axis menu will be plotted against the column, row or index selected in the x-axis menu. If any selection is made on the z-axis menu, then each y-axis selection is also plotted against the column or row selected in the z-axis menu to make a three-dimensional plot.
The axis menus (labeled '''x''', '''y''', and '''z''') select what parts of the data should be used for the plot. Each column or row selected in the y-axis menu will be plotted against the column, row or index selected in the x-axis menu. If any selection is made on the z-axis menu, then each y-axis selection is also plotted against the column or row selected in the z-axis menu to make a three-dimensional plot.


If the input dat is three-way it is assumed to be a multivariate image, and the y-axis is slice or slab and the figure default is imagesc(dat(:,:,1)). This is also true if dat is class "dataset" with the type field set to 'image' or 'image'.
If the input <tt>data</tt> is three-way it is assumed to be a multivariate image, and the y-axis is slice or slab and the figure default is imagesc(dat(:,:,1)). This is also true if <tt>data</tt> is class "dataset" with the type field set to 'image' or 'image'.


If the '''auto-update''' checkbox is selected, figures are updated automatically when new axis-menu selections are made. Otherwise, the '''Plot''' button must be pressed before any changes are reflected in the figure.
If the '''auto-update''' checkbox is selected, figures are updated automatically when new axis-menu selections are made. Otherwise, the '''Plot''' button must be pressed before any changes are reflected in the figure.
====View Menu====
Various options associated with the viewed data are contained in the '''View''' menu. The specific options depend on the data being plotted. The '''View''' menu options are listed below.
* ''''''Table'''''': Opens a '''Plotted Data''' window that lists the numerical values of the plotted data.
*''''''''' Numbers''': Displays the index number next to each plotted point.
*''''''''' Labels''': Displays available lables next to each plotted point. If no labels are available this option is greyed out.
*''''''''' Classes''': Uses available class information to give each plotted point a different symbol. If no class information is available this option is greyed out. The fly-out menu includes any class sets defined in the dataset as well as options to "Outline Class Groups". Group outlining allows drawing of lines to either enclose all samples in a group ("border points") or as a confidence boundry ("confidence ellipse").
*''''''''' Declutter Labels''': Controls the label/number decluttering options. Automatic modes remove labels when they overlap. "Selected Only" removes labels on all points except those which have been selected using the standard selection tools.
*''''''''' Label Angle''': Changes the angle of (i.e. rotates) all labels in a plot.
*''''''''' Excluded Data''': Shows any points which have been "excluded" from the data set.
*''''''''' Axis Lines''': Places lines through the origin.
*''''''''' Log Scales''': Switches axes between log and linear scaling.
*''''''''' Auto y-scale''': When enabled, all plotted data items are scaled so that their y-axis values are on a similar scale (that is, they are each baselined and normalized). The different methods for y-scaling include: Sum, Length, Max. In each case, the given property is set equal to 1 for each plotted data item. In addition, if the plot has been zoomed, the y-scaling method is based only on the currently visible data. The scaling can be recalculated for any given zoomed view by selecting "Scale from current zoom".
*''''''''' Auto Contrast''': Contrast enhancement for a slice/slab for multivariate images (only available when the data are 3-way or type image).
*''''''''' Duplicate Figure''': Creates a duplicate copy of the current figure that is linked to the current figure i.e. if one figure is modified the other automatically changes to reflect the modification. The parent figure will have a "+" next to its name in the figure selection dropdown menu and the child figure will have a "\*".
*''''''''' Spawn Figure''': Creates a duplicate copy of the current figure that is not controled by the '''Plot Controls''' toolbar. This is a simple MATLAB figure.
*''''''''' Dock Controls''': When checked, the '''Plot Controls''' toolbar are "docked" next to the controled figure.
*''''''''' Settings''': Allows the user to modify other view settings.
====Plot Menu====
Selects the "mode" in which the current data should be viewed. This can be either a summary of any given mode (Data Summary mode) or one of the standard modes of a data matrix including the rows, columns, or slabs.
*''''''''' Data Summary''': Plots all the data, the mean, the standard deviation, or the mean ? the standard deviation. For Variables (columns) or Samples (rows) depending on what is selected in the x-axis.
*''''''''' Rows''': Plots the data across rows selecting which rows (usually samples) to view.
*''''''''' Columns''': Plots the data down the columns selecting which columns (usually variables) to view.
*''''''''' Slabs''': Uses IMAGESC to view a slice/slab of a 3-way array (only available when the data are 3-way).
====Selection using the Select button====


The '''Select''' button allows the user to select plotted points in the current figure. After clicking '''Select''', the current figure will be brought to the front and points are selected using the current selection tool (selected using the '''Tool''' button; see also Edit/Selection Mode menu). To extend a selection (i.e. add new points to the already selected points), use the '''shift-key''' while pressing the mouse button. To remove points from the selection, use the '''control-key''' while pressing the mouse button. To keep from making any selection, press "'''Esc'''" or "'''Escape'''".
The '''Select''' button allows the user to select plotted points in the current figure. After clicking '''Select''', the current figure will be brought to the front and points are selected using the current selection tool (selected using the '''Tool''' button; see also Edit/Selection Mode menu). To extend a selection (i.e. add new points to the already selected points), use the '''shift-key''' while pressing the mouse button. To remove points from the selection, use the '''control-key''' while pressing the mouse button. To keep from making any selection, press "'''Esc'''" or "'''Escape'''".
====Edit Menu====
The '''Edit''' menu contains various actions relating to selections. The specific actions available depends on the current selection and PLOTGUI mode. The '''Edit''' menu options are listed below.
* ''''''Select''' All''': Selects all plotted points.
*''''''''' Deselect All''': Deselects all plotted points.
*''''''''' Select Class''': Select all points of a given class or classes in the data (if any classes are defined).
*''''''''' Select Excluded''': Selects all points which are currently excluded (see '''View/Excluded Data''').
*''''''''' Selection Mode''': Menu used to choose selection mode from the following:
*'''''''''  Box''': Click and drag a rubber band box around points,
*'''''''''  Polygon''': Click to mark the corners of a polygon around points and click on the intial point or press [Enter] to close the polygon,
*'''''''''  Circle''': Click to mark center of a circle, then click to mark the outside edge of the circle,
*'''''''''  Ellipse: '''Click to mark center of an ellipse, click again to mark the minor axis size for the ellipse, then complete the selection by clicking to mark the size and direction of the major axis for the ellipse
*'''''''''  Paintbrush''': Click and drag to "paint" a selection onto points,
*'''''''''  Lasso: '''Click and drag a free-form line to "ensnare" the points,
*'''''''''  Single X''': Click to select a single point on the x-axis,
*'''''''''  Single Y''': Click to select a single point on the y-axis,
*'''''''''  X Range''': Click and drag to select a range of points on the x-axis,
*'''''''''  Y Range''': Click and drag to select a range of points on the y-axis, and
*'''''''''  Nearest''': Click to select the nearest point.
*'''''''''  Multiple Nearest''': Click to select the nearest point, repeated until the [Enter] key is pressed.
*''''''''' Include All''': Includes all excluded points (whether or not they are selected).
*''''''''' Exclude Selection''': Excludes (soft deletes) the selected points from the data set. See '''View/Excluded Data'''.
*''''''Include''' Selection''': Includes the selected points in the data set. See '''View/Excluded Data'''.
*''''''''' Include Only Selection''':  Exclude all ''unselected'' points from the data set i.e. keep only the selected points.
* ''''''Info''' on Selection''': Get information on selected point (only available when a single point is selected).
*''''''''' Set Class''': Set the class of the selected points.
*''''''''' Exclude Plotted Data''': Excludes all items currently selected in the y-axis menu for plotting. Note that unlike the other exclusion options in this menu, this and the next two options act on the mode selected in the '''Plot''' menu.
*''''''''' Include Plotted Data''': Includes all items currently selected in the y-axis menu for plotting.
*''''''''' Include Only Plotted''': Includes all items currently selected in the y-axis menu for plotting and only those items (all others are excluded).
====File Menu====
The '''File''' menu contains various actions relating to files. The '''File''' menu options are listed below.
* ''''''Load''' Data''': Creates an interface for the user to load data into PLOTGUI from the base workspace or a file.
* ''''''Save''' Data''': Creates an interface for the user to save data from PLOTGUI to the base workspace or a file.
* ''''''Open''' in Editor''': Opens the given dataset in a linked DataSet Editor window.
* ''''''Export''' Figure''': Allows exporting the current figure to Various external programs (exporting will not function correctly if the given program is not installed on the computer).
* ''''''Save''' Selected Indices''': Saves the current selection as a vector of indices. This can be used with the Load Selected Indices command to quickly store and reload different selections.
*''''''Load''' Selected Indices''': Load a vector of indices to use as a selection.
*''''''Reset''' Controls''': Refreshes Plot Controls. Useful if graphical objects are not correctly aligned.


===Properties and Keywords===
===Properties and Keywords===


The following is a list of available properties. Each should be included as a '''PropertyName', PropertyValue'' pair in an initial PLOTGUI call or a PLOTGUI 'update' call. Note that calls to PLOTGUI for '''PropertyName''' and ''PropertyValue'' are case insensitive.
The following is a list of available properties. Each should be included as a 'PropertyName', 'PropertyValue' pair in an initial PLOTGUI call or a PLOTGUI 'update' call. Note that calls to PLOTGUI for '''PropertyName''' and '''PropertyValue''' are case insensitive.


The current value of almost all properties can be retrieved using the getappdata function on the PLOTGUI figure and requesting the property of interest. Note that calls to GETAPPDATA are case sensitive and '''PropertyName''' must be in all lower-case. The I/O format is:
The current value of almost all properties can be retrieved using the GETAPPDATA function on the PLOTGUI figure and requesting the property of interest. Note that calls to GETAPPDATA are case sensitive and '''PropertyName''' must be in all lower-case. The I/O format is:


:currentvalue = getappdata(fig,'propertyname')
:currentvalue = getappdata(fig,'propertyname')


where fig is the handle of the PLOTGUI figure. If 'propertyname' is not included getappdata(fig) will list all the properties and their current values. Properties and their possible values follow:
where <tt>fig</tt> is the handle of the PLOTGUI figure. If 'propertyname' is not included getappdata(fig) will list all the properties and their current values. Properties and their possible values follow:


: AxisMenuValues: {[x] [y] [z]}, Two or three element cell containing indices or strings indicating which item, or items, to select in each of the three axis pull down menus. In [x] or [y] a value of 0 (zero) means to select index number. In [z] a value of 'none' means to not use the z-axis.
* '''AxisMenuValues:''' {[x] [y] [z]}, Two or three element cell containing indices or strings indicating which item, or items, to select in each of the three axis pull down menus. In [x] or [y] a value of 0 (zero) means to select index number. In [z] a value of 'none' means to not use the z-axis.
* '''AxisMenuDefaults:''' Axis menu defaults are axis menu values used if the axis menu values can not be restored. The input format is the same as axismenuvalues.
* '''Figure:''' [scalar integer], Figure on which data should be plotted {default is current figure}.
* '''New:''' Key word - no associated ''PropertyValue''. Creates a new figure for display of data. This is equivalent to an initial PLOTGUI call.
* '''PlotBy:''' [scalar integer], Dimension (mode) for the axis menu selections: 0 = special "data browser", 1 = rows, 2 = columns, etc. (see '''View''' menu). The default is 2 or the number of modes in the data if larger than 2-way.
* '''VSIndex:''' [ 1 1] {default}, Two element vector indicating if "Index" should be offered on x and y axis menus. A 1 indicates that it should be offered as a selection and a 0 indicates that it should not e.g. [1 1] indicates that it should be offered for both the x-axis and y-axis.


: AxisMenuDefaults: Axis menu defaults are axis menu values used if the axis menu values can not be restored. The input format is the same as axismenuvalues.
====Image Specific Properties====


: Figure: [scalar integer], Figure on which data should be plotted {default is current figure}.
* '''Image:''' Key word - no associated ''PropertyValue''. Unfolds a 2 or 3-way array and displays it as and image, allowing selection, classing, and exclusion of individual pixels.
* '''Unfold:''' Key word - no associated ''PropertyValue''. Pseudonym for "image".
* '''AsImage:''' Key word - no associated ''PropertyValue''. Display 3-way data that have already been unfolded as an image allowing selection, classing, and exclusion of individual pixels.
* '''slabcolormode''': [‘rgb’] {default}, <String>, determins the colormap used when viewing more than 3 image slabs in a false-color image. Each pixel is assigned a single color from the colormap based on the slab with the largest value for that pixel. This value is then scaled based on the slab color contrast setting. ''lines'' = draw from standard line color sequence; ''rgb'' = similar to lines but starts with red, green, blue; ''classes'' = draw from color scheme used for class symbols; ''jet'' = interpolate from the jet color scheme; ''colormap'' = interpolate from current figure's colormap.
* '''slabcolorcontrast''': [0.8] {default}, Set the level of intensity contrast shown for each slab when viewing more than 3 slabs in a false-color image. The higher the value, the more the base color is scaled by the image''s value. A value of zero shows the color without scaling.
* '''viewautocontrast''': [0] {default}, A Boolean that turns on/off the use of auto-contrasting on images. When on, image data magnitude is truncated to 3 times the standard deviation. Helps adjust the color scale of images when unusually large or small values are present.
* '''viewinterpolated''': [0] {default}, A Boolean that turns on/off the use of interpolated-color images. When on, images are interpolated to higher spatial resolution. Note that not all display modes support interpolation. Other settings may disable this feature.
* '''viewpixelscale''': [0] {default}, Turns on/off the display of pixel axis scales on images. When off, axis scales will be hidden unless user defines an image axisscale. When on, axis scales will be shown in pixels if no user-defined image axisscale is set.
* '''imagegunorder''': [1 2 3] {default}, <Vector>, determines the order of the color used for false color images. 1 = red, 2 = green, 3 = blue.
* '''viewdensity''': [1] {default} A Boolean that turns on/off use of density plots for images, turn off to force the use of a scatter plot.
* '''densitybinsmin''': [64] {default}, Minimum number of bins to use in image density plots.
* '''densitybinsmax''': [512] {default}, Maximum number of bins to use in image density plots.  


: New: Key word - no associated ''PropertyValue''. Creates a new figure for display of data. This is equivalent to an initial PLOTGUI call.
====View Properties====
 
: PlotBy: [scalar integer], Dimension (mode) for the axis menu selections: 0 = special "data browser", 1 = rows, 2 = columns, etc. (see '''View''' menu). The default is 2 or the number of modes in the data if larger than 2-way.
 
: VSIndex: [ 1 1] {default}, Two element vector indicating if "Index" should be offered on x and y axis menus. A 1 indicates that it should be offered as a selection and a 0 indicates that it should not e.g. [1 1] indicates that it should be offered for both the x-axis and y-axis.
 
The following are '''image specific''' properties:
 
: Image: Key word - no associated ''PropertyValue''. Unfolds a 2 or 3-way array and displays it as and image, allowing selection, classing, and exclusion of individual pixels.
 
: Unfold: Key word - no associated ''PropertyValue''. Pseudonym for "image".
 
: AsImage: Key word - no associated ''PropertyValue''. Display 3-way data that have already been unfolded as an image allowing selection, classing, and exclusion of individual pixels.
 
The following are view properties:


* '''ViewClasses''': [1] {default}, Turns on '''View/Classes''' menu. A 0 (zero) turns it off.
* '''ViewClasses''': [1] {default}, Turns on '''View/Classes''' menu. A 0 (zero) turns it off.
 
* '''ViewExcludedData:''' [1] {default}, Turns on '''View/Excluded Data''' menu. A 0 (zero) turns it off.
: ViewExcludedData: [1] {default}, Turns on '''View/Excluded Data''' menu. A 0 (zero) turns it off.
 
* '''ViewLabels''': [1] {default}, Turns on '''View/Labels''' menu. A 0 (zero) turns it off.
* '''ViewLabels''': [1] {default}, Turns on '''View/Labels''' menu. A 0 (zero) turns it off.
* '''ViewNumbers''': [1] {default}, Turns on '''View/Numbers''' menu. A 0 (zero) turns it off.
* '''viewlabelset''': [1] {default}, Specifies the label set (by integer number) to use when labeling data.
* '''declutter''': [0.5] {default}, Specifies the level of decluttering to use on labels. 0 = no declutter, 0-1 = light, 1-5 = moderate, 5+ = significant.
* '''labelselected''': [1] {default}, A Boolean that turns on/off the labeling of selected points only. If "on" only selected points will be labeled (when ViewLabels is on). If "off" all points are labeled.
* '''viewlabelangle''': [0] {default}, Specifies the angle of text labels in degrees. 0 = Horizontal Right, 90 = Vertical up. Valid values range from 0 through 360.
* '''viewlabelmaxy''': [] {default}, Specifies the upper limit on position of text labels (i.e. on the y-axis). Used to keep labels below the specified position.
* '''viewlabelminy''': [] {default}, Specifies the lower limit on position of text labels (i.e. on the y-axis). Used to keep labels above the specified position.
* '''textinterpreter''': ‘None’ {default}, <String> Specifies the text interpreter to use on labels. ‘LaTex’ and ‘Tex’ interpret strings using special notation for various text effects.
* '''menulabelset''': [1] {default}, Specifies the label set (by integer number) to use for the labels in the y-axis menu on the Plot Controls.
* '''viewlabelprespace''': [1] or [3] (for Mac) {default}, Specifies the number of padding spaces to include before point labels (allows easy offset of labels).
* '''viewaxisscale''': [0] {default}, A Boolean that turns on/off the labeling of data using the DataSet-defined axisscale (if present).
* '''viewaxisscaleset''': [1] {default}, Specifies the axisscale set (by integer number) to use when labeling data.


* '''ViewNumbers''': [1] {default}, Turns on '''View/Numbers''' menu. A 0 (zero) turns it off.


The following are plot properties:
====Plot Properties====


* '''LineStyle''': <string>, Defines line style (see PLOT).
* '''LineStyle''': <string>, Defines line style (see PLOT).
* '''PlotType''': <string>, String used to select plot type {default [ ] is atuomatic selection}. Other values are 'scatter', 'bar', 'none' ('none' = do no plotting). Automatic plotting checks to see if data is continuous (line plot), has steps (monotonic), otherwise (scatter).
* '''symbolsize''': [] {default}, Specifies an overriding symbol size to use in plots. Empty or zero uses the default symbol size.
* '''linewidth''': [] {default}, Specifies an overriding line width to use in plots. Empty or zero uses the default line width.
* '''SelectionMarker''': <string>, Defines marker style for selected points (see PLOT).
* '''automonotonic''': [0] {default}, A Boolean that specifies whether or not Monotonic is acceptable as an automatic selection for plot type. A 0 value disables the possible auto-selection of Monotonic plot types which are typically only used with time-based data.
* '''viewcompressgaps''': [0] {default}, A Boolean turns on/off squeezing out points which are excluded, the x-axis is compressed to leave out gaps.
* '''autoscale''': 0 {default}, A Boolean turns on/off automatic y-scaling and plot all items on the same scale.
* '''autoscaleorder''': [1] {default}, Define type of automatic y-scaling to use on each plotted item. 0 = none, 1 = mean area, [2] = normalized length, inf = min/max scaling (0/1).
* '''autoscalewindow''': {} {default}, A Cell array containing indices to use as window for scaling (see autoscale). There is a cell element for each mode of the data.
* '''viewaxislines''': [0 0 0] {default}, Governs the display of axis = 0 lines for the [X Y Z] axes. A value of "1" shows the axis=0 line for the specified axis.
* '''viewaxisplanes''': [0] {default}, A Boolean that turns on/off the display of axis "planes" in 3D plots when view axis lines is ON for any axis.
* '''viewdiag''': [0] {default}, A Boolean that turns on/off the display of a 1:1 diagonal line on the plot. Does not apply to 3-dimensional plots.
* '''viewtable''': [0] {default}, A Boolean that that turns on/off the display of a table showing the currently-plotted values.
* '''findpeakswidth''': [] {default}, Enables peak finding using the specified width window for peak sensitivity threshold. 0 or empty disables peak finding.
* '''usespecialmarkers''': [0] {default}, A Boolean that turns on/off the use of complex symbols on different scatter-plot items (i.e. on a non-continuous x-axis). Complex symbols shift both inner and outer color to increase the number of possible unique element styles.
* '''viewtimeaxisauto''': [1] {default}, A Boolean that turns on/off the automatic detection of a time-stamp x-axis scale. When "1", the x-axis scale is examined and, if it appears to be a time stamp, dates and times are used instead of raw numbers.
* '''viewtimeaxis''': [ 0 0 0] {default}, Forces the interpretation of one or more axes as time-stamps (labeled using dates and times). Specified for each of the [X Y Z] axes.


* '''PlotType''': <string>, String used to select plot type {default [ ] is atuomatic selection}. Other values are 'scatter', 'bar', 'none' ('none' = do no plotting).
====Selection Properties====
 
: SelectionMarker: <string>, Defines marker style for selected points (see PLOT).
 
The following are selection properties:


* '''SelectionMode''': <string>, Defines the selection mode. This can be any string listed under '''View/Selection Mode''' above. Also see GSELECT.
* '''SelectionMode''': <string>, Defines the selection mode. This can be any string listed under '''View/Selection Mode''' above. Also see GSELECT.
* '''BrushWidth''': [scalar integer number of pixels], This defines the brush width for use when selectionmode = 'paintbrush'. See '''View/Selection Mode/Paintbrush'''.
* '''BrushWidth''': [scalar integer number of pixels], This defines the brush width for use when selectionmode = 'paintbrush'. See '''View/Selection Mode/Paintbrush'''.
* '''NoSelect''': [0] {default}, When set to 0 this allows selections. When set to 1 no selection is allowed.
* '''NoSelect''': [0] {default}, When set to 0 this allows selections. When set to 1 no selection is allowed.
* '''NoInclude''': [0] {default}, When set to 0 this allows changes to the inlclud field (i.e. it allows data to be excluded). When set to 1 no changes to the inlclud field are allowed (i.e. data can not be excluded).
* '''noload''': [0] {default},  A Boolean that turns on/off the ability of the user to load new data.
* '''showcontrols''': [1] {default}, A Boolean that turns on/off the display of the Plot Controls when the target figure is active.
* '''pgtoolbar''': [1] {default}, A Boolean that specifies if the toolbar controls should be added to the target figure.
* '''status''': [] {default}, Specifies the label to use for the given figure in the list of figures on the Plot Controls (top of the controls).
* '''targetaxestag''': [‘’] {default}, Specifies a tag which, if non-empty, indicates the axis on which all plots should be plotted. All other plots will be ignored.


* '''NoInclud''': [0] {default}, When set to 0 this allows changes to the inlclud field (i.e. it allows data to be excluded). When set to 1 no changes to the inlclud field are allowed (i.e. data can not be excluded).


The following are on-event properties:
====Class Plotting Properties====


: CloseGUICallback: Command(s) to execute when the figure is closed.
* '''viewclassset''': [1] {default}, Specifies the class set (by integer number) to use when viewing classes.
* '''connectclasses''': [0] {default}, Governs plotting of class-encirciling ellipses. When 1 ellipses are drawn around each displayed class.
* '''classsymbol''': [‘’] {default}, <String> Symbol to use when plotting classes. If not specified, all symbols are used in a rotating manner.
* '''classsymbolsize''': [ ] {default}, Specifies the symbol size to use when plotting classes. If empty, the default symbol size is used.
* '''classfacecolor''': [1] {default}, Governs the use of symbol face color when viewing classes. If (0), each symbol is a single color. If (1), the face color of symbols will be rotated through the class colors independently from the symbol outline color.
* '''classcolormode''': [‘’] {default}, <String>  Specifies a standard colormap to use for class colors. Empty (the default) uses a standard "optimized" color map (recommended). "figure" uses the colormap set on the current figure. Any other setting is assumed to be a standard colormap name. If using "figure" you must update the plot (by clicking the "plot" button or issuing an 'update' command) after changing the figure colormap to have the change take effect.
* '''connectclassmethod''': [‘pca’] {default}, <String> Specifies method used to outline classes (when connectclasses is (1)).
** ''pca'' uses PCA confidence ellipses
** ''outline'' draws a border around the outermost class members,
** ''connect'' connects all class members in series,
** ''means'' mean at each X,
** ''spider'' spider plot,
** ''sequence'' connect in sequence of data,
** ''delauncy''  2-D Delaunay triangulation of the points.
* '''connectclasslimit''': [.95] {default}, Specifies confidence level at which classes should be outlined when using "PCA" class connect method.
* '''connectclassitems''': [ ] {default}, List of classes to apply connect method on. If empty, all classes are used.
* '''selectioncolor''': [1 0 1] {default}, Specifies the color to use for selections. Set using a three-element vector indicating [red green blue] where each value is between zero and one.
* '''selectpersistent''': [0] {default}, A Boolean that keeps selection button toggled on after selection. Meaning a second click starts a new selection automatically.
* '''connectitems''': [] {default}, Indices of items to connect sequentially in the plot.
* '''connectitemsstyle''': [‘’] {default}, <String> A Line/Marker style to use on connected items (see connectitems).
* '''connectitemslinewidth''': [2] {default}, Width of the line used to connect items.
* '''imageselection''': [‘overlay’] {default}, <String> Style of selection on images. "overlay" uses a semi-transparent mask, "outline" outlines selected pixels.
* '''viewclassesasoverlay''': [0] {default}, A Boolean that turns on/off displaying underlying data lines when classes are shown. (Hidden (0) or shown (1)).
* '''autosizemarkers''': [0] {default}, A Boolean that turns on/off the auto adjusting the size of symbols.  When (1), and no symbol size is specified, symbol size is adjusted to axes size and smaller symbols are used when axis is small.


: IncludChangeCallback: Command executed when includ field of the dataset is modified.
====On-Event Properties====


: InfoReqCallback: Command executed when information on a selected point is requested.
* '''CloseGUICallback:''' Command(s) to execute when the figure is closed.
* '''InfoReqCallback:''' Command executed when information on a selected point is requested.
* '''PlotCommand:''' Command executed after plotting (e.g. draw limits, assign ButtonDownFcns, modifiy axes, ...).


: PlotCommand: Command executed after plotting (e.g. draw limits, assign ButtonDownFcns, modifiy axes, ...).
====Confidence Limit Properties====
 
: SelectionChangeCallback: Command executed when a selction is made.
 
: SetClassCallback: Command executed when the class field of the dataset is changed.
 
The following are confidence limit properties:


* '''ConfLimits''': Boolean flag to make "Conf. Limits" controls visible. 1 = show controls (PLOTGUI does nothing with these controls, thus the routine specified in '[plotcommand-]' must be set to use values).
* '''ConfLimits''': Boolean flag to make "Conf. Limits" controls visible. 1 = show controls (PLOTGUI does nothing with these controls, thus the routine specified in '[plotcommand-]' must be set to use values).
* '''LimitsValue''': Value for Conf. Limits editbox.
* '''LimitsValue''': Value for Conf. Limits editbox.
* '''ShowLimits''': Value for "Conf. Limits" checkbox (1 = checked).


* '''ShowLimits''': Value for "Conf. Limits" checkbox (1 = checked).
====Color Properties====


The following are figure linking properties (WARNING! Modifying these settings can lead to unexpected results!):
* '''colorby''': [] {default}, Specifies an item number (from the data’s ‘plotby’ mode), or an explicit vector of values to use in coloring the data. When not empty, the given values or index into the dataset is used to color-code the plotted data using the class color scale.
* '''colorbybins''': [30] {default}, Specifies the number of color bins to group the ‘colorby’ vector into. The more bins, the slower the plotting and more complex the legend, but the more detailed the color mapping. Default is recommended.
* '''colorbyscale''': [‘linear’] {default} <String>, specifies the type of ‘colorby’ bin mapping to use. "linear" maps colorby values to color maintaining the scale of the values. "nonlinear" maps values to color compressing values into sorted non-linear bins (may increase color contrast).


* '''Children''': Add new child of the current PLOTGUI figure (all child figures are updated when their parent is updated and closed when their parent is closed). Note: this property will only allow adding of additional children. Other modifications must be made using setappdata.
====Plot Controls Properties====


* '''ControlBy''': Reassign control for PLOTGUI figure.
* '''validplotby''': [] {default}, specifies the mode(s) the user is permitted to select from the "Plot" menu. Empty [] allows any mode in the data.
* '''axismenuenable''': [1 1 1] {default} <Vector>, enabling/disabling the [X Y Z] axis menus. If off (0), the specified axis menu is not enabled and the user cannot change the default selected value. See AxisMenuValues property to set the default value.
* '''axisautoinvert''': [1] {default}, When on (1) x-axis will be inverted in direction if the axisscale in the data is in decreasing order. When -1, x-axis will ALWAYS be inverted (irrespective of the data direction). When 0, axis will never invert.
* '''labelwithnumber''': [‘auto’] {default}, <String> Can be set to ‘on’, ’off’, or ‘auto’. Controls numbering of axis menu items (appended within parenthesis at the end of the label), ''auto'' adds numbering if there are duplicate.
* '''autoduplicate''': [1] {default}, A Boolean. When on (1) a clicked sub-plot is automatically duplicated as a single axis in a new figure.
* '''autopopulate''': [1] {default}, A Boolean, when on (1) new sub-plots are automatically populated with results. When off (0) subplots are left empty for the user to populate manually.
* '''maximumyitems''': [200000] {default}, specifies the maximum number of items allowed to be shown in the y-axis listbox menu.
* '''maximumitems''': [500] {default}, specifies the maximum number of items allowed to be shown in the x- and z-axis pull-down menus.
* '''maximumdatasummary''': [1000] {default}, specifies the maximum number of items allowed to be shown in the "data" view of the "Data Summary" plot mode.
* '''maxclassview''': [200] {default}, specifies the maximum number of classes to display in a scatter plot.


* '''Parent''': Assign a parental link (Forces the parent figure to update if this figure is updated, also see 'Children').
====Figure Linking Properties====
'''WARNING!''' Modifying these settings can lead to unexpected results!


* '''ControlBy''': Reassign control for PLOTGUI figure.
* '''TimeStamp''': Time-stamp of last time this figure was updated (can be set to any string to isolate figure from updating by parents).
* '''TimeStamp''': Time-stamp of last time this figure was updated (can be set to any string to isolate figure from updating by parents).


The following are other miscellaneous properties:
====Other Miscellaneous Properties====


* '''UIControl''': Add extra uicontrol(s) to PLOTGUI control toolbar for use with current figure (buttons, sliders, etc.). The value passed to UIControl should be a cell in which each entry is the tag of a new object to create and the value of that field should contain a cell of uicontrol property / value pairs to set for that object. For example:
* '''UIControl''': Add extra uicontrol(s) to PLOTGUI control toolbar for use with current figure (buttons, sliders, etc.). The value passed to UIControl should be a cell in which each entry is the tag of a new object to create and the value of that field should contain a cell of uicontrol property / value pairs to set for that object. For example:
*:<tt>myobj.mybtn''' = {'style', 'pushbutton', 'string', 'new fig', 'callback', 'figure'};</tt>
*:<tt>plotgui('update','uicontrol',myobj)</tt>
*: creates a button with the tag 'mybtn' on the controls for the current figure.
**In addition to standard object properties, the special property 'updatecallback' can be set on an object. This callback will be executed whenever the Plot Controls window is updated. The variables <tt>targfig</tt> and <tt>h</tt> will be available to the callback to indicate the current "target figure" handle and the current object's handle, respectively. This property is useful for updating an object's enable or value properties when multiple figures share the same object (e.g. a checkbox which reflects some user-defined appdata). For an example of its use, see the [[plotscores]] function which uses this property for the "Show Error Bars" checkbox.
**If the cell for any object does not contain a 'position' property for the object, PLOTGUI will manage the object's position.


*  '''myobj.mybtn''' = {'style', 'pushbutton', 'string', 'new fig', 'callback', 'figure'};
====Read-Only Properties====


*  '''plotgui('update','uicontrol',myobj)'''
These properties can only be viewed and are only accessible through the MATLAB getappdata command.


*  '''creates''' a button with the tag 'mybtn' on the controls for the current figure.  
* '''Selection''': Cell array of currently selected values. Usually the same format as "includ" field of DataSet object where each cell represents the index of selected items in each dimension {rows, columns, slabs, ...}.
*  '''When''' selecting elements in greater than 2-dimensional data (and without the use of the 'image' keyword), two cells of this field will be pairs of selected indices: {x,y,[]} or {[],y,z}.
* '''FigureType''': 'PlotGUI'
* '''DataSet''': DataSet used in figure (or pointer to figure with actual dataset)
::'''Note''': This is set by calling PLOTGUI with a new dataset as an input. The actual DataSet can be retrieved using the getdataset command (see below).
 
====Other Valid Figure Properties====
 
See the MATLAB documentation on FIGURE properties for additional information.


* '''If''' the cell for any object does not contain a 'position' property for the object, PLOTGUI will manage the object's position.
* HandleVisibility, MenuBar, Name, NumberTitle, Position, Resize, Tag, ToolBar, Units, UserData, Visible, WindowStyle


The following are read-only properties. These properties can only be viewed and are only accessible through the MATLAB getappdata command.
===Examples===


* '''Selection''': Cell array of currently selected values. Usually the same format as "includ" field of DataSet object where each cell represents the index of selected items in each dimension {rows, columns, slabs, ...}.
The following give some typical use examples:


*  '''When''' selecting elements in greater than 2-dimensional data (and without the use of the 'image' keyword), two cells of this field will be pairs of selected indices: {x,y,[]} or {[],y,z}.
:fig = plotgui(mydata)  


* '''FigureType''': 'PlotGUI'
plots <tt>mydata</tt> allowing user to select which column(s) of <tt>mydata</tt> to plot using pull-down menus. Figure number of plot is returned.


* '''DataSet''': DataSet used in figure (or pointer to figure with actual dataset)
:plotgui(mydata,'plotby',1) or plotgui(mydata,'plotby','rows')  


*  '''Note''': This is set by calling PLOTGUI with a new dataset as an input. The actual DataSet can be retrieved using the getdataset command (see below).
plots mydata as in first example except that rows of mydata (dimension 1) are used for pull-down menus instead of columns. Note: When a PLOTGUI property is set for a given figure, the new value will be retained until a new value for that property is provided, even if new data is plotted on the same PLOTGUI figure.


The following are other valid figure properties. See the MATLAB doc umentation on FIGURE properties for additional information.
:fig = plotgui(mydata,'plotby',1,'axismenuvalues',{[1] [2 3]})


HandleVisibility, MenuBar, Name, NumberTitle, Position, Resize, Tag, ToolBar, Units, UserData, Visible, WindowStyle
plots rows of mydata; sets controls with row 1 selected for the x-axis and rows 2 and 3 selected for the y-axis. Use:


===Examples===
:getappdata(fig,'axismenuvalues')


fig = plotgui(mydata) plots mydata allowing user to select which column(s) of mydata to plot using pull-down menus. Figure number of plot is returned.
retrieves current axis menu settings. [axispulldown-]


plotgui(mydata,'plotby',1) or plotgui(mydata,'plotby','rows') plots mydata as in first example except that rows of mydata (dimension 1) are used for pull-down menus instead of columns. Note: When a PLOTGUI property is set for a given figure, the new value will be retained until a new value for that property is provided, even if new data is plotted on the same PLOTGUI figure.
:plotgui(mydata,'viewclasses',1)


fig = plotgui(mydata,'plotby',1,'axismenuvalues',{[1] [2 3]}) plots rows of mydata; sets controls with row 1 selected for the x-axis and rows 2 and 3 selected for the y-axis. Use:
plots <tt>mydata</tt> using symbols to identify the classes stored in dataset <tt>mydata</tt>. Use a value of 0 (zero) to turn off viewclasses.


:getappdata(fig,'axismenuvalues')  
:plotgui('update','viewclasses',1)


to retrieve current axis menu settings. [axispulldown-]
Turns on viewclasses property for current figure without having to pass data to plot (substitute string 'update' for data)


plotgui(mydata,'viewclasses',1) plots mydata using symbols to identify the classes stored in dataset mydata. Use a value of 0 (zero) to turn off viewclasses.
:mydata = plotgui('getdataset',fig)


plotgui('update','viewclasses',1) Turns on viewclasses property for current figure without having to pass data to plot (substitute string 'update' for data)
Retrieves <tt>mydata</tt> from figure <tt>fig</tt>.


mydata = plotgui('getdataset',fig) Retrieves mydata from figure fig.
:plotgui(myimage,'image')  


plotgui(myimage,'image') plots 3-way image myimage selecting slabs of the image for display. The keyword 'image' allows selection, classing and exclusion of pixels in the image.
plots 3-way image <tt>myimage</tt> selecting slabs of the image for display. The keyword 'image' allows selection, classing and exclusion of pixels in the image.


===See Also===
===See Also===


[[dataset]], [[analysis]], [[plotloads]], [[plotscores]]
[[analysis]], [[boxplot]], [[dataset]], [[editds]], [[gselect]], [[modelviewer]], [[mplot]], [[ploteigen]], [[plotloads]], [[plotscores]], [[trendtool]]

Latest revision as of 08:09, 13 September 2019

Purpose

Interactive data viewer.

Synopsis

fig = plotgui(data)
fig = plotgui(data,'PropertyName',PropertyValue,...)
fig = plotgui('update','PropertyName',PropertyValue,...)

Description

Plots input data data and provides a control toolbar in the Plot Controls window to select portions of the data to view. The toolbar allows interactive selection, exclusion, and classing of rows or columns of data. The PLOTGUI command has various display options that are given as 'PropertyName', 'PropertyValue' pairs or as a single keyword. Properties and Keywords are discussed below.

Inputs

  • data = input data, can be class "double" or "dataset". The description given below is generally listed for two-way data arrays.
Notes: Options specific to data that are three-way or image are noted explicitly. PLOTGUI uses the dataset labels, classes, etc. when data is class "dataset".
  • 'update' is used as a keyword input to modify options for an existing PLOTGUI figure without providing new data

Outputs

  • fig = the handle of the figure in which the data is displayed

Plot Controls

The toolbar consists of

  • 1) a menu bar with File, Edit, View, and Plot menus (see Plot Controls Window Menus )
  • 2) a figure selection dropdown menu,
  • 3) three axis menus (labeled x, y, and z),
  • 4) plot update controls Plot button and auto-update checkbox, and Select button.

Each figure in the figure selection dropdown menu menu can be modified by the PLOTGUI controls. Selecting a figure from this menu will bring that figure into view and indicate the selected axis menu settings. A "+" or a "\*" next to a figure's name indicates that it is linked with another figure (see Duplicate Figure below).

The axis menus (labeled x, y, and z) select what parts of the data should be used for the plot. Each column or row selected in the y-axis menu will be plotted against the column, row or index selected in the x-axis menu. If any selection is made on the z-axis menu, then each y-axis selection is also plotted against the column or row selected in the z-axis menu to make a three-dimensional plot.

If the input data is three-way it is assumed to be a multivariate image, and the y-axis is slice or slab and the figure default is imagesc(dat(:,:,1)). This is also true if data is class "dataset" with the type field set to 'image' or 'image'.

If the auto-update checkbox is selected, figures are updated automatically when new axis-menu selections are made. Otherwise, the Plot button must be pressed before any changes are reflected in the figure.

The Select button allows the user to select plotted points in the current figure. After clicking Select, the current figure will be brought to the front and points are selected using the current selection tool (selected using the Tool button; see also Edit/Selection Mode menu). To extend a selection (i.e. add new points to the already selected points), use the shift-key while pressing the mouse button. To remove points from the selection, use the control-key while pressing the mouse button. To keep from making any selection, press "Esc" or "Escape".

Properties and Keywords

The following is a list of available properties. Each should be included as a 'PropertyName', 'PropertyValue' pair in an initial PLOTGUI call or a PLOTGUI 'update' call. Note that calls to PLOTGUI for PropertyName and PropertyValue are case insensitive.

The current value of almost all properties can be retrieved using the GETAPPDATA function on the PLOTGUI figure and requesting the property of interest. Note that calls to GETAPPDATA are case sensitive and PropertyName must be in all lower-case. The I/O format is:

currentvalue = getappdata(fig,'propertyname')

where fig is the handle of the PLOTGUI figure. If 'propertyname' is not included getappdata(fig) will list all the properties and their current values. Properties and their possible values follow:

  • AxisMenuValues: {[x] [y] [z]}, Two or three element cell containing indices or strings indicating which item, or items, to select in each of the three axis pull down menus. In [x] or [y] a value of 0 (zero) means to select index number. In [z] a value of 'none' means to not use the z-axis.
  • AxisMenuDefaults: Axis menu defaults are axis menu values used if the axis menu values can not be restored. The input format is the same as axismenuvalues.
  • Figure: [scalar integer], Figure on which data should be plotted {default is current figure}.
  • New: Key word - no associated PropertyValue. Creates a new figure for display of data. This is equivalent to an initial PLOTGUI call.
  • PlotBy: [scalar integer], Dimension (mode) for the axis menu selections: 0 = special "data browser", 1 = rows, 2 = columns, etc. (see View menu). The default is 2 or the number of modes in the data if larger than 2-way.
  • VSIndex: [ 1 1] {default}, Two element vector indicating if "Index" should be offered on x and y axis menus. A 1 indicates that it should be offered as a selection and a 0 indicates that it should not e.g. [1 1] indicates that it should be offered for both the x-axis and y-axis.

Image Specific Properties

  • Image: Key word - no associated PropertyValue. Unfolds a 2 or 3-way array and displays it as and image, allowing selection, classing, and exclusion of individual pixels.
  • Unfold: Key word - no associated PropertyValue. Pseudonym for "image".
  • AsImage: Key word - no associated PropertyValue. Display 3-way data that have already been unfolded as an image allowing selection, classing, and exclusion of individual pixels.
  • slabcolormode: [‘rgb’] {default}, <String>, determins the colormap used when viewing more than 3 image slabs in a false-color image. Each pixel is assigned a single color from the colormap based on the slab with the largest value for that pixel. This value is then scaled based on the slab color contrast setting. lines = draw from standard line color sequence; rgb = similar to lines but starts with red, green, blue; classes = draw from color scheme used for class symbols; jet = interpolate from the jet color scheme; colormap = interpolate from current figure's colormap.
  • slabcolorcontrast: [0.8] {default}, Set the level of intensity contrast shown for each slab when viewing more than 3 slabs in a false-color image. The higher the value, the more the base color is scaled by the images value. A value of zero shows the color without scaling.
  • viewautocontrast: [0] {default}, A Boolean that turns on/off the use of auto-contrasting on images. When on, image data magnitude is truncated to 3 times the standard deviation. Helps adjust the color scale of images when unusually large or small values are present.
  • viewinterpolated: [0] {default}, A Boolean that turns on/off the use of interpolated-color images. When on, images are interpolated to higher spatial resolution. Note that not all display modes support interpolation. Other settings may disable this feature.
  • viewpixelscale: [0] {default}, Turns on/off the display of pixel axis scales on images. When off, axis scales will be hidden unless user defines an image axisscale. When on, axis scales will be shown in pixels if no user-defined image axisscale is set.
  • imagegunorder: [1 2 3] {default}, <Vector>, determines the order of the color used for false color images. 1 = red, 2 = green, 3 = blue.
  • viewdensity: [1] {default} A Boolean that turns on/off use of density plots for images, turn off to force the use of a scatter plot.
  • densitybinsmin: [64] {default}, Minimum number of bins to use in image density plots.
  • densitybinsmax: [512] {default}, Maximum number of bins to use in image density plots.

View Properties

  • ViewClasses: [1] {default}, Turns on View/Classes menu. A 0 (zero) turns it off.
  • ViewExcludedData: [1] {default}, Turns on View/Excluded Data menu. A 0 (zero) turns it off.
  • ViewLabels: [1] {default}, Turns on View/Labels menu. A 0 (zero) turns it off.
  • ViewNumbers: [1] {default}, Turns on View/Numbers menu. A 0 (zero) turns it off.
  • viewlabelset: [1] {default}, Specifies the label set (by integer number) to use when labeling data.
  • declutter: [0.5] {default}, Specifies the level of decluttering to use on labels. 0 = no declutter, 0-1 = light, 1-5 = moderate, 5+ = significant.
  • labelselected: [1] {default}, A Boolean that turns on/off the labeling of selected points only. If "on" only selected points will be labeled (when ViewLabels is on). If "off" all points are labeled.
  • viewlabelangle: [0] {default}, Specifies the angle of text labels in degrees. 0 = Horizontal Right, 90 = Vertical up. Valid values range from 0 through 360.
  • viewlabelmaxy: [] {default}, Specifies the upper limit on position of text labels (i.e. on the y-axis). Used to keep labels below the specified position.
  • viewlabelminy: [] {default}, Specifies the lower limit on position of text labels (i.e. on the y-axis). Used to keep labels above the specified position.
  • textinterpreter: ‘None’ {default}, <String> Specifies the text interpreter to use on labels. ‘LaTex’ and ‘Tex’ interpret strings using special notation for various text effects.
  • menulabelset: [1] {default}, Specifies the label set (by integer number) to use for the labels in the y-axis menu on the Plot Controls.
  • viewlabelprespace: [1] or [3] (for Mac) {default}, Specifies the number of padding spaces to include before point labels (allows easy offset of labels).
  • viewaxisscale: [0] {default}, A Boolean that turns on/off the labeling of data using the DataSet-defined axisscale (if present).
  • viewaxisscaleset: [1] {default}, Specifies the axisscale set (by integer number) to use when labeling data.


Plot Properties

  • LineStyle: <string>, Defines line style (see PLOT).
  • PlotType: <string>, String used to select plot type {default [ ] is atuomatic selection}. Other values are 'scatter', 'bar', 'none' ('none' = do no plotting). Automatic plotting checks to see if data is continuous (line plot), has steps (monotonic), otherwise (scatter).
  • symbolsize: [] {default}, Specifies an overriding symbol size to use in plots. Empty or zero uses the default symbol size.
  • linewidth: [] {default}, Specifies an overriding line width to use in plots. Empty or zero uses the default line width.
  • SelectionMarker: <string>, Defines marker style for selected points (see PLOT).
  • automonotonic: [0] {default}, A Boolean that specifies whether or not Monotonic is acceptable as an automatic selection for plot type. A 0 value disables the possible auto-selection of Monotonic plot types which are typically only used with time-based data.
  • viewcompressgaps: [0] {default}, A Boolean turns on/off squeezing out points which are excluded, the x-axis is compressed to leave out gaps.
  • autoscale: 0 {default}, A Boolean turns on/off automatic y-scaling and plot all items on the same scale.
  • autoscaleorder: [1] {default}, Define type of automatic y-scaling to use on each plotted item. 0 = none, 1 = mean area, [2] = normalized length, inf = min/max scaling (0/1).
  • autoscalewindow: {} {default}, A Cell array containing indices to use as window for scaling (see autoscale). There is a cell element for each mode of the data.
  • viewaxislines: [0 0 0] {default}, Governs the display of axis = 0 lines for the [X Y Z] axes. A value of "1" shows the axis=0 line for the specified axis.
  • viewaxisplanes: [0] {default}, A Boolean that turns on/off the display of axis "planes" in 3D plots when view axis lines is ON for any axis.
  • viewdiag: [0] {default}, A Boolean that turns on/off the display of a 1:1 diagonal line on the plot. Does not apply to 3-dimensional plots.
  • viewtable: [0] {default}, A Boolean that that turns on/off the display of a table showing the currently-plotted values.
  • findpeakswidth: [] {default}, Enables peak finding using the specified width window for peak sensitivity threshold. 0 or empty disables peak finding.
  • usespecialmarkers: [0] {default}, A Boolean that turns on/off the use of complex symbols on different scatter-plot items (i.e. on a non-continuous x-axis). Complex symbols shift both inner and outer color to increase the number of possible unique element styles.
  • viewtimeaxisauto: [1] {default}, A Boolean that turns on/off the automatic detection of a time-stamp x-axis scale. When "1", the x-axis scale is examined and, if it appears to be a time stamp, dates and times are used instead of raw numbers.
  • viewtimeaxis: [ 0 0 0] {default}, Forces the interpretation of one or more axes as time-stamps (labeled using dates and times). Specified for each of the [X Y Z] axes.

Selection Properties

  • SelectionMode: <string>, Defines the selection mode. This can be any string listed under View/Selection Mode above. Also see GSELECT.
  • BrushWidth: [scalar integer number of pixels], This defines the brush width for use when selectionmode = 'paintbrush'. See View/Selection Mode/Paintbrush.
  • NoSelect: [0] {default}, When set to 0 this allows selections. When set to 1 no selection is allowed.
  • NoInclude: [0] {default}, When set to 0 this allows changes to the inlclud field (i.e. it allows data to be excluded). When set to 1 no changes to the inlclud field are allowed (i.e. data can not be excluded).
  • noload: [0] {default}, A Boolean that turns on/off the ability of the user to load new data.
  • showcontrols: [1] {default}, A Boolean that turns on/off the display of the Plot Controls when the target figure is active.
  • pgtoolbar: [1] {default}, A Boolean that specifies if the toolbar controls should be added to the target figure.
  • status: [] {default}, Specifies the label to use for the given figure in the list of figures on the Plot Controls (top of the controls).
  • targetaxestag: [‘’] {default}, Specifies a tag which, if non-empty, indicates the axis on which all plots should be plotted. All other plots will be ignored.


Class Plotting Properties

  • viewclassset: [1] {default}, Specifies the class set (by integer number) to use when viewing classes.
  • connectclasses: [0] {default}, Governs plotting of class-encirciling ellipses. When 1 ellipses are drawn around each displayed class.
  • classsymbol: [‘’] {default}, <String> Symbol to use when plotting classes. If not specified, all symbols are used in a rotating manner.
  • classsymbolsize: [ ] {default}, Specifies the symbol size to use when plotting classes. If empty, the default symbol size is used.
  • classfacecolor: [1] {default}, Governs the use of symbol face color when viewing classes. If (0), each symbol is a single color. If (1), the face color of symbols will be rotated through the class colors independently from the symbol outline color.
  • classcolormode: [‘’] {default}, <String> Specifies a standard colormap to use for class colors. Empty (the default) uses a standard "optimized" color map (recommended). "figure" uses the colormap set on the current figure. Any other setting is assumed to be a standard colormap name. If using "figure" you must update the plot (by clicking the "plot" button or issuing an 'update' command) after changing the figure colormap to have the change take effect.
  • connectclassmethod: [‘pca’] {default}, <String> Specifies method used to outline classes (when connectclasses is (1)).
    • pca uses PCA confidence ellipses
    • outline draws a border around the outermost class members,
    • connect connects all class members in series,
    • means mean at each X,
    • spider spider plot,
    • sequence connect in sequence of data,
    • delauncy 2-D Delaunay triangulation of the points.
  • connectclasslimit: [.95] {default}, Specifies confidence level at which classes should be outlined when using "PCA" class connect method.
  • connectclassitems: [ ] {default}, List of classes to apply connect method on. If empty, all classes are used.
  • selectioncolor: [1 0 1] {default}, Specifies the color to use for selections. Set using a three-element vector indicating [red green blue] where each value is between zero and one.
  • selectpersistent: [0] {default}, A Boolean that keeps selection button toggled on after selection. Meaning a second click starts a new selection automatically.
  • connectitems: [] {default}, Indices of items to connect sequentially in the plot.
  • connectitemsstyle: [‘’] {default}, <String> A Line/Marker style to use on connected items (see connectitems).
  • connectitemslinewidth: [2] {default}, Width of the line used to connect items.
  • imageselection: [‘overlay’] {default}, <String> Style of selection on images. "overlay" uses a semi-transparent mask, "outline" outlines selected pixels.
  • viewclassesasoverlay: [0] {default}, A Boolean that turns on/off displaying underlying data lines when classes are shown. (Hidden (0) or shown (1)).
  • autosizemarkers: [0] {default}, A Boolean that turns on/off the auto adjusting the size of symbols. When (1), and no symbol size is specified, symbol size is adjusted to axes size and smaller symbols are used when axis is small.

On-Event Properties

  • CloseGUICallback: Command(s) to execute when the figure is closed.
  • InfoReqCallback: Command executed when information on a selected point is requested.
  • PlotCommand: Command executed after plotting (e.g. draw limits, assign ButtonDownFcns, modifiy axes, ...).

Confidence Limit Properties

  • ConfLimits: Boolean flag to make "Conf. Limits" controls visible. 1 = show controls (PLOTGUI does nothing with these controls, thus the routine specified in '[plotcommand-]' must be set to use values).
  • LimitsValue: Value for Conf. Limits editbox.
  • ShowLimits: Value for "Conf. Limits" checkbox (1 = checked).

Color Properties

  • colorby: [] {default}, Specifies an item number (from the data’s ‘plotby’ mode), or an explicit vector of values to use in coloring the data. When not empty, the given values or index into the dataset is used to color-code the plotted data using the class color scale.
  • colorbybins: [30] {default}, Specifies the number of color bins to group the ‘colorby’ vector into. The more bins, the slower the plotting and more complex the legend, but the more detailed the color mapping. Default is recommended.
  • colorbyscale: [‘linear’] {default} <String>, specifies the type of ‘colorby’ bin mapping to use. "linear" maps colorby values to color maintaining the scale of the values. "nonlinear" maps values to color compressing values into sorted non-linear bins (may increase color contrast).

Plot Controls Properties

  • validplotby: [] {default}, specifies the mode(s) the user is permitted to select from the "Plot" menu. Empty [] allows any mode in the data.
  • axismenuenable: [1 1 1] {default} <Vector>, enabling/disabling the [X Y Z] axis menus. If off (0), the specified axis menu is not enabled and the user cannot change the default selected value. See AxisMenuValues property to set the default value.
  • axisautoinvert: [1] {default}, When on (1) x-axis will be inverted in direction if the axisscale in the data is in decreasing order. When -1, x-axis will ALWAYS be inverted (irrespective of the data direction). When 0, axis will never invert.
  • labelwithnumber: [‘auto’] {default}, <String> Can be set to ‘on’, ’off’, or ‘auto’. Controls numbering of axis menu items (appended within parenthesis at the end of the label), auto adds numbering if there are duplicate.
  • autoduplicate: [1] {default}, A Boolean. When on (1) a clicked sub-plot is automatically duplicated as a single axis in a new figure.
  • autopopulate: [1] {default}, A Boolean, when on (1) new sub-plots are automatically populated with results. When off (0) subplots are left empty for the user to populate manually.
  • maximumyitems: [200000] {default}, specifies the maximum number of items allowed to be shown in the y-axis listbox menu.
  • maximumitems: [500] {default}, specifies the maximum number of items allowed to be shown in the x- and z-axis pull-down menus.
  • maximumdatasummary: [1000] {default}, specifies the maximum number of items allowed to be shown in the "data" view of the "Data Summary" plot mode.
  • maxclassview: [200] {default}, specifies the maximum number of classes to display in a scatter plot.

Figure Linking Properties

WARNING! Modifying these settings can lead to unexpected results!

  • ControlBy: Reassign control for PLOTGUI figure.
  • TimeStamp: Time-stamp of last time this figure was updated (can be set to any string to isolate figure from updating by parents).

Other Miscellaneous Properties

  • UIControl: Add extra uicontrol(s) to PLOTGUI control toolbar for use with current figure (buttons, sliders, etc.). The value passed to UIControl should be a cell in which each entry is the tag of a new object to create and the value of that field should contain a cell of uicontrol property / value pairs to set for that object. For example:
    myobj.mybtn = {'style', 'pushbutton', 'string', 'new fig', 'callback', 'figure'};
    plotgui('update','uicontrol',myobj)
    creates a button with the tag 'mybtn' on the controls for the current figure.
    • In addition to standard object properties, the special property 'updatecallback' can be set on an object. This callback will be executed whenever the Plot Controls window is updated. The variables targfig and h will be available to the callback to indicate the current "target figure" handle and the current object's handle, respectively. This property is useful for updating an object's enable or value properties when multiple figures share the same object (e.g. a checkbox which reflects some user-defined appdata). For an example of its use, see the plotscores function which uses this property for the "Show Error Bars" checkbox.
    • If the cell for any object does not contain a 'position' property for the object, PLOTGUI will manage the object's position.

Read-Only Properties

These properties can only be viewed and are only accessible through the MATLAB getappdata command.

  • Selection: Cell array of currently selected values. Usually the same format as "includ" field of DataSet object where each cell represents the index of selected items in each dimension {rows, columns, slabs, ...}.
  • When selecting elements in greater than 2-dimensional data (and without the use of the 'image' keyword), two cells of this field will be pairs of selected indices: {x,y,[]} or {[],y,z}.
  • FigureType: 'PlotGUI'
  • DataSet: DataSet used in figure (or pointer to figure with actual dataset)
Note: This is set by calling PLOTGUI with a new dataset as an input. The actual DataSet can be retrieved using the getdataset command (see below).

Other Valid Figure Properties

See the MATLAB documentation on FIGURE properties for additional information.

  • HandleVisibility, MenuBar, Name, NumberTitle, Position, Resize, Tag, ToolBar, Units, UserData, Visible, WindowStyle

Examples

The following give some typical use examples:

fig = plotgui(mydata)

plots mydata allowing user to select which column(s) of mydata to plot using pull-down menus. Figure number of plot is returned.

plotgui(mydata,'plotby',1) or plotgui(mydata,'plotby','rows')

plots mydata as in first example except that rows of mydata (dimension 1) are used for pull-down menus instead of columns. Note: When a PLOTGUI property is set for a given figure, the new value will be retained until a new value for that property is provided, even if new data is plotted on the same PLOTGUI figure.

fig = plotgui(mydata,'plotby',1,'axismenuvalues',{[1] [2 3]})

plots rows of mydata; sets controls with row 1 selected for the x-axis and rows 2 and 3 selected for the y-axis. Use:

getappdata(fig,'axismenuvalues')

retrieves current axis menu settings. [axispulldown-]

plotgui(mydata,'viewclasses',1)

plots mydata using symbols to identify the classes stored in dataset mydata. Use a value of 0 (zero) to turn off viewclasses.

plotgui('update','viewclasses',1)

Turns on viewclasses property for current figure without having to pass data to plot (substitute string 'update' for data)

mydata = plotgui('getdataset',fig)

Retrieves mydata from figure fig.

plotgui(myimage,'image')

plots 3-way image myimage selecting slabs of the image for display. The keyword 'image' allows selection, classing and exclusion of pixels in the image.

See Also

analysis, boxplot, dataset, editds, gselect, modelviewer, mplot, ploteigen, plotloads, plotscores, trendtool

Retrieved from "https://www.wiki.eigenvector.com/index.php?title=Plotgui&oldid=10846"