The IMAT_FNPLOT class is a class that consists of a number of methods and properties that provide convenient control of an imat_fn plot. When a plot is created, its definition is stored in an IMAT_FNPLOT object, which allows you to change the plot display after the plot has been generated. The axes associated with the plot are associated with a UIPANEL. This allows the panel to be embedded in other GUIs and manipulated accordingly (see UIPLOT). This class also offers a lot of convenience for plotting. For example, you can link different plots together, so that changing an attribute of one (for example the window) will automatically change the axes on the other linked plots.
A contextual menu is created on all IMAT_FNPLOT plots. The menu provides convenient access to the majority of the IMAT_FNPLOT methods. For a complete description of each menu item, see the contextual menu section in the imat_fn/plot documentation.
Templates are a functionality that was once exclusive to UIPLOT. They have now been added to the basic function plotting capabilities. See the imat_fn/plot documentation for more information.
An important thing to understand about an IMAT_FNPLOT is that it consists of three axes that never get destroyed. The first axes of the three is always either the real or magnitude plot. The second axis is always the imaginary or phase plot. The third axis is always the Nyquist plot. Only the axes that are relevant to the currently displayed Complex Option are visible.
The IMAT_FNPLOT has both properties and methods available to you.
The top level properties of the IMAT_FNPLOT object are the most basic to its function. The top level properties are series of handles to the different components of the plot, as well as a structure that contains the complete information about its status and format. These properties are described in the table below.
| hpanel | Handle to uipanel that contains the entire plot. |
| ha | Handles (1x3) to the three axes that comprise the plot. |
| hf | Handle to the figure that contains the plot. |
| hl | Cell array (1x3) containing the handles to the lines on each of the three axes that comprise the plot. |
| f | imat_fn object containing the functions that are plotted. |
| s | Structure containing information about the plot settings. |
The fields in the .s field of the IMAT_FNPLOT object contain a complete description of the current status/formatting of the IMAT_FNPLOT display. It should be considered 'read-only', as any changes will not affect the plot itself. Only the object methods functions called from the contextual menu affect the contents of this field.
Attributes with size 1x3 correspond to the three classifications of plots. That is: 'modulus + phase', 'real + imaginary', and 'nyquist'. Items such as labeling, windowing, and scaling are stored on an individual basis for the three different types of plots.
| title | String containing the plot title text. If it is 'default ', the title is auto-generated based on the type of data shown on the plot. If it is anything else, it overrides the default setting. |
| xlabel | Cell array (1x3) of strings that defines the X axis label for each of the three axes. If it is 'default ', the labels are auto-generated based on the type of data shown as well as the type of plot. For instance, in a magnitude/phase plot the x-label would appear only on the magnitude axis, and not the phase axis. |
| ylabel | Cell array (1x3) of cell arrays. They contain the Y axis labels for each axis of the three plot classifications. The first two cells are size 1x2 since they are multi-axis plots. |
| xscale | Cell array (1x3) of strings containing the X axis scale for each of the three plot types. |
| yscale | Cell array (1x3) of strings containing the X axis scale for each of the three plot types. |
| complex | String which defines the type of plot. The available types are 'modulus + phase','modulus', 'phase', 'real + imaginary', 'real', 'imaginary', and 'nyquist'. |
| window | Cell array (1x3) of cell arrays storing the window information for each of the three plot classifications. The window information specifies the X and Y limits of the axes. The first two classifications are stored as {xwin ywin1 ywin2}. Nyquist is stored as {xwin ywin}. X-windowing is always the same for multi-axis plots. |
| windowhistory | 1x3 structure containing the windowing history for each axis type. The field .val contains the windowing information, and the field .ind specifies the current index into .val. |
| gridopt | String which defines which grid lines are shown on the plot. The available options are 'X only', 'Y only', 'X and Y', and 'none'. |
| linkplots | Logical value which defines whether this plot listens when a notification is sent out indicating another plot has changed. |
| linkaxes | Logical value which defines whether the three axes that make up a plot listen to each other. It is advisable not to turn this off. If this is turned off, axes that belong together (such as magnitude and phase) will not act together. |
| cleanphase | Logical value defining whether the phase has been cleaned. |
| tag | Structure that completely defines any tags that have been applied to the plot. |
| style | Structure that completely defines the formatting of the lines on the plot. This field will be empty until the STYLE method is used. Each style that has been set will then appear as a field of a structure in.style. This structure will be an array of the same length as the number of functions currently plotted. |
| axis | Structure that defines the formatting of the axes on the plot. This field will be empty until the AXIS method is used. Each axis property that has been set will then appear as a field of the structure in .axis. |
| border | Structure that defines the plot borders in pixels. |
| font | Structure that completely defines the formatting of the various fonts on the plot. It is described in more detail below. |
| legend | Structure that completely defines the legend on the plot. It is described in more detail below. |
| xtick | Structure that completely defines the formatting of the X axis ticks. |
| ytick | Structure that completely defines the formatting of the Y axis ticks. |
| type | String defining whether the X or Y data (or both) is displayed on the plot when tagging. This can be 'x', 'y', or 'xy'. |
| cursoron | Logical value specifying whether cursor is currently on. |
| loc | String defining whether tagging happens on data or grid. This can be 'data' or 'grid'. |
| cursorh | Handle to the cursor line if cursoring is currently on. |
| title | String storing the original title of the plot before tagging began. |
| tags | Structure containing information on each of the tags, such as which function the tag is one, what the type of the tag was, etc. |
| h | Handles to the text and marker for each tag. |
| Logical value defining whether the tag coordinate will be printed to the command window. |
| title | Structure containing the title font attributes and their current settings. |
| xlabel | Structure containing the X axis label font attributes and their current settings. |
| ylabel | Structure containing the Y axis label font attributes and their current settings. |
| axis | Structure containing the axis font attributes and their current settings. |
| default | Structure containing the default font attributes and their current settings. When fonts are set back to their defaults, they will use these settings. |
| show | This is a logical flag defining whether the legend is shown. | ||||||||
| type | This is the type of legend that is shown. There are several types: 'default ', 'idline1', 'idline4', 'ref/res', and 'custom'. | ||||||||
| handle | This is the handle to the legend. | ||||||||
| n | This is the maximum number of legend items to display when generating the legend. This is not used when the user manually enters a custom legend. | ||||||||
| custom | This is a cell array of strings that define the entries for the custom legend. This is only populated if the type is set to 'custom'. | ||||||||
| location | This is the location of the legend. The available options are the same as theMATLAB LEGEND function. | ||||||||
| orientation | This is the orientation of the legend It is either 'Horizontal' or 'Vertical'. | ||||||||
| font |
Structure containing the legend font settings:
|
||||||||
| interpreter | This specifies the interpreter to use for legend labels. The available options are the same as the MATLAB LEGEND function. |
A number of methods are available for the IMAT_FNPLOT class. These methods allow you to manipulate the plot after it has been generated. In the documentation below, the IMAT_FNPLOT object is denoted by HPLOT.
This method applies a template stored in the template structure TMPL or in the file FNAME to the plot. If neither is input, a file dialog will be shown where the template file can be selected.
This method changes the axis properties of the axes that are displayed on an IMAT_FNPLOT. This method directly controls the style of the lines on an IMAT_FNPLOT. ATTRIBUTE1, ATTRIBUTE2, etc are attributes such as 'TickDir' and 'Box'. Attributes must be followed by their corresponding values. They are applied as attribute pairs as they would on any set() command. All of the axes on the plot will use these settings.
If other IMAT_FNPLOTs on the same figure are linked (they are by default), then the axes of those plots will also be changed by using this method.
This method changes the complex option of the IMAT_FNPLOT. The allowed options are: 'modulus + phase', 'modulus', 'phase', 'real + imaginary', 'real', 'imaginary', and 'nyquist'.
If other IMAT_FNPLOTs on the same figure are linked (they are by default), then the complex option of those plots will also be changed by using this method.
This method changes the font of the title, xlabel, ylabel, or axes. The first argument defines which of these are being defined. The following arguments define the name, weight, and angle, size, and color of the font. All don't need to be defined. If one isn't defined, the current font will be used as the starting point.
The name can be any valid font name on the system. The weight is either 'bold' or 'normal'. The angle is either 'italic' or 'normal'. The size is any real number greater than one.
This method changes the grid lines that are displayed on an IMAT_FNPLOT. The available options are:
| 'on' |
Turn on both x and y grid lines |
| 'off' |
Turn off all grid lines |
| 'x and y' |
Turn on both x and y grid lines (same as 'on') |
| 'x only' |
Turn on only the x grid lines |
| 'y only' |
Turn on only the y grid lines |
| 'none' |
Turn off all grid lines (same as 'off') |
If other IMAT_FNPLOT on the same figure are linked (they are by default), then the grid lines of those plots will also be changed by using this method.
This method functions much like the standard MATLAB LEGEND function. This one is just used specifically with IMAT_FNPLOT to enable advanced features.
The legend strings may be supplied as a series of string arguments, or as a cell array of strings. Strings specified that do not otherwise match a valid option are assumed to be the labels for the lines on the plot. You can use %ResponseCoord, %ReferenceCoord, %Name, %IDLine1, %IDLine2, %IDLine3, %IDLine4, %FunctionType,%RMS, %MAX, %MEAN and/or %MIN as part of the legend and they will get replaced with the corresponding function values. The 'Location', 'Visible', 'Orientation', 'Interpreter', 'FontName', 'FontWeight', 'FontAngle', and 'FontSize' arguments act the same as the MATLAB legend function.
The 'Type' argument is an added feature beyond the normal legend function. It determines how the legend labels are automatically generated. The allowed options are 'default ', 'idline1', 'idline4', and 'ref/res'. If custom string labels are entered, this is automatically set to 'custom' and should not be entered.
Passing in a positive numeric scalar NUMLEGEND specifies the number of legend entries to display on the plot.
This method sets the linking of the plot object. If TRUE, then whenever another IMAT_FNPLOT on the same figure sends its notification that it has changed, it will apply the same change. If FALSE, it simply ignores the notification. It is important to note, that all imat_fnplots on the same figure are linked by default.
This method loads the figure data from a special figure file and recreates the figure from the information stored in the file. This functionality is the IMAT_FNPLOT equivalent of loading from a .fig file.
FILENAME is an optional string or Nx2 cell array of strings. If it is a cell array of strings or it contains wildcards, the user will be prompted for the filename with a graphical file dialog.
This method loads the formatting of an imat_fn plot from a template file.
FNAME is an optional input containing the template filename to read. If not supplied, you will be prompted with a graphical file dialog. It is optionally also returned from this method.
TEMPLATE is a structure containing the template.
This method prints the current plot to the printer, using the MATLAB print dialog. If you select File -> Print from the figure, it will bring up the print dialog. Otherwise, it will bring up the print preview dialog.
The REMOVE method removes the plot from the figure. It does all of the clean up that is necessary for a plot's deletion not to impact the stablity of the rest of the figure.
The replace method replaces the functions that are plotted on the IMAT_FNPLOT with those in the imat_fn, G, keeping the format as similar as possible. If the number of functions in G is less than or equal to the number currently plotted, the formats will be applied in order. If the number of functions in G exceeds the number of formats currently plotted, the existing formatting will be applied for all possible, with the extras having the default formatting.
This method saves the IMAT_FNPLOT to a file. It is called when you select File -> Save As from the figure menu. If FILENAME is not supplied, or is a cell array of strings, or contains wildcards, the user will be prompted with a graphical file dialog.
This method saves the IMAT_FNPLOT to a special figure file that can then be loaded to recreate the figure. This functionality is the IMAT_FNPLOT equivalent of saving to a .fig file.
FILENAME is an optional string or Nx2 cell array of strings. If it is a cell array of strings or it contains wildcards, the user will be prompted for the filename with a graphical file dialog.
This method saves the formatting of the current plot to a template file.
FNAME is an optional input containing the template filename. If not supplied, you will be prompted with a graphical file dialog. It is optionally also returned from this method.
This method directly controls the style of the lines on an IMAT_FNPLOT. ATTRIBUTE1, ATTRIBUTE2, etc are properties such as 'LineWidth', 'Marker', or 'LineStyle'. You can set any of the Primitive Line Properties available in MATLAB. Please refer to the MATLAB documentation for more details.
Properties must be followed by their corresponding values. They are applied as property/value pairs as they would on any set() command.
INDEX specifies which lines to which to apply the properties. It can be a numeric vector corresponding to the order of the functions as they were initially plotted (and as stored in the function as they were passed in), or it can be an imat_filt. If the latter, the style will be applied to all of the functions matching the filter. If INDEX is not supplied or it is empty, the style properties will be applied to all of the lines on the plot.
This method directly controls the style of the tags on an IMAT_FNPLOT. ATTRIBUTE1, ATTRIBUTE2, etc are attributes such as 'FontSize', 'FontName', or 'Color'. They are applied as attribute pairs as they would on any set() command.The INDEX argument controls which tags the attributes will apply to. The index directly corresponds to the order of the tags as they were initially displayed. If the index is not supplied, then the style commands will apply to all of the tags on the plot.
This method adds a title to an imat_fnplot. If the complex option of the plot is changed, the title will always appear over the correct axis.
You can use %ResponseCoord, %ReferenceCoord, %Name, %IDLine1, %IDLine2, %IDLine3, %IDLine4, and %FunctionType as part of the label and they will get replaced with the value from the first function plotted.
In addition to the title, you can also specify Property/Value pairs. Valid pairs are any that the MATLAB TITLE function accepts. These properties and their values are stored as fields in hplot.s.font.title.
If other imat_fnplots on the same figure are linked (they are by default), then the xlabel of those plots will also be changed by using this method (assuming they are the same complex option).
This method opens a window where the line color, style and width can be edited on a line by line basis.
To edit the line style, select the line from the table and change the entries in the pulldowns in the table. Once the style values are set, press Apply to set the changes to the plot. When completely done, press Done to set the changes and close the window.
This method changes the xlabel of an imat_fnplot. It works slightly differently than the typical MATLAB xlabel. Here, LABEL is the desired label for the plot. If it is entered without any associated INDEX, then the label is applied to all of the axes of the plot. If an index is specified, that label is applied to that specific axis only. INDEX can range from 1 to 3. An index of 1 corresponds to the 'magnitude' or 'real' axis. An index of 2 corresponds to the 'phase' or 'imaginary' axis. An index of 3 corresponds to the 'nyquist' axis.
LABEL can be entered as a cell array of strings as long as INDEX is a vector of integers of the same size.
You can use %ResponseCoord, %ReferenceCoord, %Name, %IDLine1, %IDLine2, %IDLine3, %IDLine4, and %FunctionType as part of the label and they will get replaced with the value from the first function plotted.
In addition to the xlabel, you can also specify Property/Value pairs. Valid pairs are any that the MATLAB XLABEL function accepts. These properties and their values are stored as fields in hplot.s.font.xlabel.
If other imat_fnplots on the same figure are linked (they are by default), then the xlabel of those plots will also be changed by using this method (assuming they are the same complex option).
This method changes the x limits of an imat_fnplot. XLIM is a 1x2 vector defining the new limits. If XLIM is entered without any associated INDEX, then the limit is applied to the current complex option. If an index is specified, the limit is applied to that specific axis only. INDEX can range from 1 to 3. An index of 1 corresponds to the 'magnitude' or 'real' axis. An index of 2 corresponds to the 'phase' or 'imaginary' axis. An index of 3 corresponds to the 'nyquist' axis.
Passing INF in for XLIM will fit the X limits to the data plotted, which is the same as the 'tight' option. Passing in 'auto' or [] for XLIM sets the limit to 'auto'.
If other imat_fnplots on the same figure are linked (they are by default), then the limits of those plots will also be changed by using this method (even if they are not the same complex option).
This method changes the X axis scale of the currently visible plot.
SCALE is a string containing 'lin', 'log', or 'default'.
If other IMAT_FNPLOTs on the same figure are linked (they are by default), then the X axis scale of those plots will also be changed by using this method (assuming they are the same complex option).
This method sets the formatting of the xticks on an IMAT_FNPLOT. The xtick values and labels can be set manually using the 'value' and 'label' arguments, or they can be set so MATLAB sets them automatically using the 'valuemode' and/or 'labelmode' options.
The VALUE argument must be a numeric vector. This is the location where tick marks will be placed. The LABEL argument is a manual override of how the ticks are labeled. This must be a cell array of strings. If the size of the cell array is less than the number of ticks, then the cell array will be repeated so that all ticks have a label. If the size of the cell array is more than the number of ticks, only the labels up to the number of ticks will be used, starting from the beginning of the cell array.
VALUEMODE and LABELMODE can be set to 'manual' or 'automatic'. If values or labels are set, then these modes are set to 'manual' automatically.
It is important to note that the xticks will automatically be applied to all axes associated with the current complex option.
This method changes the ylabel of an imat_fnplot. It works slightly differently than the typical MATLAB ylabel. Here, LABEL is the desired label for the plot. If it is entered without any associated INDEX, then the label is applied to all of the axes of the plot. If an index is specified, that label is applied to that specific axis only. INDEX can range from 1 to 3. An index of 1 corresponds to the 'magnitude' or 'real' axis. An index of 2 corresponds to the 'phase' or 'imaginary' axis. An index of 3 corresponds to the 'nyquist' axis.
LABEL can be entered as a cell array of strings as long as INDEX is a vector of integers of the same size.
You can use %ResponseCoord, %ReferenceCoord, %Name, %IDLine1, %IDLine2, %IDLine3, %IDLine4, and %FunctionType as part of the label and they will get replaced with the value from the first function plotted.
In addition to the ylabel, you can also specify Property/Value pairs. Valid pairs are any that the MATLAB YLABEL function accepts. These properties and their values are stored as fields in hplot.s.font.ylabel.
If other imat_fnplots on the same figure are linked (they are by default), then the xlabel of those plots will also be changed by using this method (assuming they are the same complex option).
This method changes the y limits of an IMAT_FNPLOT. Here, YLIM is the desired y limits for the plot. If it is entered without any associated INDEX, then the limits will be applied as appropriately as possible. That is, they will be applied to all axes shown, except in the case of a magnitude/phase plot, where only the magnitude will be windowed.
If an index is specified, then the y limits are applied to that specific axis only. INDEX can range from 1 to 3. An index of 1 corresponds to the 'magnitude' or 'real' axis. An index of 2 corresponds to the 'phase' or 'imaginary' axis. An index of 3 corresponds to the 'nyquist' axis.
YLIM can be entered as a cell array of strings as long as INDEX is a vector of integers of the same size.
Passing INF in for YLIM will fit the Y limits to the data plotted, which is the same as the 'tight' option. Passing in 'auto' or [] for YLIM sets the limit to 'auto'.
If other imat_fnplots on the same figure are linked (they are by default), then the y limits of those plots will also be changed by using this method (assuming they are the same complex option).
This method changes the Y axis scale of the currently visible plot. Note that you cannot change the scale of the phase axis on a magnitude/phase plot.
SCALE is a string containing 'lin', 'log', or 'default'.
AXIND is the index of the axis to change. For multi-axis plot (e.g. magnitude/phase), 1 is the bottom axis and 2 is the top axis.
If other IMAT_FNPLOTs on the same figure are linked (they are by default), then the X axis scale of those plots will also be changed by using this method (assuming they are the same complex option).
This method sets the formatting of the yticks on an IMAT_FNPLOT. The ytick values and labels can be set manually using the 'value' and 'label' arguments, or they can be set so MATLAB sets them automatically using the 'valuemode' and/or 'labelmode' options.
INDEX is a required argument that defines which axis the yticks will be applied to. It will only be stored for that axis in the current complex option. An index of 1 corresponds to the 'magnitude' or 'real' axis. An index of 2 corresponds to the 'phase' or 'imaginary' axis. An index of 3 corresponds to the 'nyquist' axis.
The VALUE argument must be a numeric vector. This is the location where tick marks will be placed. The LABEL argument is a manual override of how the ticks are labeled. This must be a cell array of strings. If the size of the cell array is less than the number of ticks, then the cell array will be repeated so that all ticks have a label. If the size of the cell array is more than the number of ticks, only the labels up to the number of ticks will be used, starting from the beginning of the cell array.
VALUEMODE and LABELMODE can be set to 'manual' or 'automatic'. If values or labels are set, then these modes are set to 'manual' automatically.
It is important to note that the xticks will automatically be applied to all axes associated with the current complex option.