Plotting
********

Plotting Basics
===============

Octave makes it easy to create many different types of two- and three-dimensional plots using a few high-level functions.

If you need finer control over graphics, see Advanced Plotting.

Two-Dimensional Plots
---------------------

The plot function allows you to create simple x-y plots with linear axes.  For example,

     x = -10:0.1:10;
     plot (x, sin (x));

displays a sine wave shown in fig:plot.  On most systems, this command will open a separate plot window to display the graph.

Figure: Simple Two-Dimensional Plot.

(plot)

The plotyy function may be used to create a plot with two independent y axes.

(plotyy)

The functions semilogx, semilogy, and loglog are similar to the plot function, but produce plots in which one or both of the axes use log scales.

(semilogx)

(semilogy)

(loglog)

The functions bar, barh, stairs, and stem are useful for displaying discrete data.  For example,

     hist (randn (10000, 1), 30);

produces the histogram of 10,000 normally distributed random numbers shown in fig:hist.

Figure: Histogram.

(bar)

(barh)

(hist)

(stairs)

(stem)

(stem3)

(scatter)

(scatter3)

(plotmatrix)

(pareto)

(rose)

The contour, contourf and contourc functions produce two-dimensional contour plots from three dimensional data.

(contour)

(contourf)

(contourc)

(contour3)

The errorbar, semilogxerr, semilogyerr, and loglogerr functions produce plots with error bar markers.  For example,

     x = 0:0.1:10;
     y = sin (x);
     yp =  0.1 .* randn (size (x));
     ym = -0.1 .* randn (size (x));
     errorbar (x, sin (x), ym, yp);

produces the figure shown in fig:errorbar.

Figure: Errorbar plot.

(errorbar)

(semilogxerr)

(semilogyerr)

(loglogerr)

Finally, the polar function allows you to easily plot data in polar coordinates.  However, the display coordinates remain rectangular and linear.  For example,

     polar (0:0.1:10*pi, 0:0.1:10*pi);

produces the spiral plot shown in fig:polar.

Figure: Polar plot.

(polar)

(pie)

(quiver)

(quiver3)

(compass)

(feather)

(pcolor)

(area)

(comet)

The axis function may be used to change the axis limits of an existing plot and various other axis properties, such as the aspect ratio and the appearance of tic marks.

(axis)

Similarly the axis limits of the colormap can be changed with the caxis function.

(caxis)

The xlim, ylim, and zlim functions may be used to get or set individual axis limits.  Each has the same form.

(xlim)

Two-dimensional Function Plotting
.................................

Octave can plot a function from a function handle inline function or string defining the function without the user needing to explicitly create the data to be plotted.  The function fplot also generates two-dimensional plots with linear axes using a function name and limits for the range of the x-coordinate instead of the x and y data.  For example,

     fplot (@sin, [-10, 10], 201);

produces a plot that is equivalent to the one above, but also includes a legend displaying the name of the plotted function.

(fplot)

Other functions that can create two-dimensional plots directly from a function include ezplot, ezcontour, ezcontourf and ezpolar.

(ezplot)

(ezcontour)

(ezcontourf)

(ezpolar)

Three-Dimensional Plotting
--------------------------

The function mesh produces mesh surface plots.  For example,

     tx = ty = linspace (-8, 8, 41)';
     [xx, yy] = meshgrid (tx, ty);
     r = sqrt (xx .^ 2 + yy .^ 2) + eps;
     tz = sin (r) ./ r;
     mesh (tx, ty, tz);

produces the familiar ``sombrero'' plot shown in fig:mesh.  Note the use of the function meshgrid to create matrices of X and Y coordinates to use for plotting the Z data.  The ndgrid function is similar to meshgrid, but works for N-dimensional matrices.

Figure: Mesh plot.

The meshc function is similar to mesh, but also produces a plot of contours for the surface.

The plot3 function displays arbitrary three-dimensional data, without requiring it to form a surface.  For example

     t = 0:0.1:10*pi;
     r = linspace (0, 1, numel (t));
     z = linspace (0, 1, numel (t));
     plot3 (r.*sin(t), r.*cos(t), z);

displays the spiral in three dimensions shown in fig:plot3.

Figure: Three dimensional spiral.

Finally, the view function changes the viewpoint for three-dimensional plots.

(mesh)

(meshc)

(meshz)

(hidden)

(surf)

(surfc)

(surfl)

(surfnorm)

(diffuse)

(specular)

(meshgrid)

(ndgrid)

(plot3)

(view)

(slice)

(ribbon)

(shading)

Three-dimensional Function Plotting
...................................

(ezplot3)

(ezmesh)

(ezmeshc)

(ezsurf)

(ezsurfc)

Three-dimensional Geometric Shapes
..................................

(cylinder)

(sphere)

(ellipsoid)

Plot Annotations
----------------

You can add titles, axis labels, legends, and arbitrary text to an existing plot.  For example,

     x = -10:0.1:10;
     plot (x, sin (x));
     title ("sin(x) for x = -10:0.1:10");
     xlabel ("x");
     ylabel ("sin (x)");
     text (pi, 0.7, "arbitrary text");
     legend ("sin (x)");

The functions grid and box may also be used to add grid and border lines to the plot.  By default, the grid is off and the border lines are on.

(title)

(legend)

(text)

See Text Properties for the properties that you can set.

(xlabel)

(clabel)

(box)

(grid)

(colorbar)

Multiple Plots on One Page
--------------------------

Octave can display more than one plot in a single figure.  The simplest way to do this is to use the subplot function to divide the plot area into a series of subplot windows that are indexed by an integer. For example,

     subplot (2, 1, 1)
     fplot (@sin, [-10, 10]);
     subplot (2, 1, 2)
     fplot (@cos, [-10, 10]);

creates a figure with two separate axes, one displaying a sine wave and the other a cosine wave.  The first call to subplot divides the figure into two plotting areas (two rows and one column) and makes the first plot area active.  The grid of plot areas created by subplot is numbered in column-major order (top to bottom, left to right).

(subplot)

Multiple Plot Windows
---------------------

You can open multiple plot windows using the figure function. For example

     figure (1);
     fplot (@sin, [-10, 10]);
     figure (2);
     fplot (@cos, [-10, 10]);

creates two figures, with the first displaying a sine wave and the second a cosine wave.  Figure numbers must be positive integers.

(figure)

Printing Plots
--------------

The print command allows you to save plots in a variety of formats.  For example,

     print -deps foo.eps

writes the current figure to an encapsulated PostScript file called foo.eps.

(print)

(orient)

Interacting with plots
----------------------

The user can select points on a plot with the ginput function or selection the position at which to place text on the plot with the gtext function using the mouse.

(ginput)

(waitforbuttonpress)

(gtext)

Test Plotting Functions
-----------------------

The functions sombrero and peaks provide a way to check that plotting is working.  Typing either sombrero or peaks at the Octave prompt should display a three dimensional plot.

(sombrero)

(peaks)

Advanced Plotting
=================

Graphics Objects
----------------

Plots in Octave are constructed from the following graphics objects.  Each graphics object has a set of properties that define its appearance and may also contain links to other graphics objects. Graphics objects are only referenced by a numeric index, or handle.

root figure
     The parent of all figure objects.  The index for the root figure is defined to be 0.

figure
     A figure window.

axes
     An set of axes.  This object is a child of a figure object and may be a parent of line, text, image, patch, or surface objects.

line
     A line in two or three dimensions.

text
     Text annotations.

image
     A bitmap image.

patch
     A filled polygon, currently limited to two dimensions.

surface
     A three-dimensional surface.

To determine whether an object is a graphics object index or a figure index, use the functions ishandle and isfigure.

(ishandle)

(ishghandle)

(isfigure)

The function gcf returns an index to the current figure object, or creates one if none exists.  Similarly, gca returns the current axes object, or creates one (and its parent figure object) if none exists.

(gcf)

(gca)

The get and set functions may be used to examine and set properties for graphics objects.  For example,

     get (0)
         => ans =
            {
              type = root figure
              currentfigure = [](0x0)
              children = [](0x0)
              visible = on
            }

returns a structure containing all the properties of the root figure. As with all functions in Octave, the structure is returned by value, so modifying it will not modify the internal root figure plot object.  To do that, you must use the set function.  Also, note that in this case, the currentfigure property is empty, which indicates that there is no current figure window.

The get function may also be used to find the value of a single property.  For example,

     get (gca (), "xlim")
         => [ 0 1 ]

returns the range of the x-axis for the current axes object in the current figure.

To set graphics object properties, use the set function.  For example,

     set (gca (), "xlim", [-10, 10]);

sets the range of the x-axis for the current axes object in the current figure to [-10, 10].  Additionally, calling set with a graphics object index as the only argument returns a structure containing the default values for all the properties for the given object type.  For example,

     set (gca ())

returns a structure containing the default property values for axes objects.

(get)

(set)

(ancestor)

(allchild)

You can create axes, line, and patch objects directly using the axes, line, and patch functions.  These objects become children of the current axes object.

(axes)

(line)

(patch)

(fill)

(surface)

By default, Octave refreshes the plot window when a prompt is printed, or when waiting for input.  To force an update at other times, call the drawnow function.

(drawnow)

Only figures that are modified will be updated.  The refresh function can also be to force an update of the current figure, even if it is nor modified.

(refresh)

Normally, high-level plot functions like plot or mesh call newplot to initialize the state of the current axes so that the next plot is drawn in a blank window with default property settings.  To have two plots superimposed over one another, call the hold function.  For example,

     hold ("on");
     x = -10:0.1:10;
     plot (x, sin (x));
     plot (x, cos (x));
     hold ("off");

displays sine and cosine waves on the same axes.  If the hold state is off, consecutive plotting commands like this will only display the last plot.

(newplot)

(hold)

(ishold)

To clear the current figure, call the clf function.  To clear the current axis, call the cla function.  To bring the current figure to the top of the window stack, call the shg function.  To delete a graphics object, call delete on its index.  To close the figure window, call the close function.

(clf)

(cla)

(shg)

(delete)

(close)

(closereq)

Graphics Object Properties
--------------------------

Root Figure Properties
......................

currentfigure
     Index to graphics object for the current figure.

Figure Properties
.................

nextplot
     May be one of

     "new"

     "add"

     "replace"

     "replacechildren"

closerequestfcn
     Handle of function to call when a figure is closed.

currentaxes
     Index to graphics object of current axes.

colormap
     An N-by-3 matrix containing the color map for the current axes.

visible
     Either "on" or "off" to toggle display of the figure.

paperorientation
     Indicates the orientation for printing.  Either "landscape" or "portrait".

Axes Properties
...............

position
     A vector specifying the position of the plot, excluding titles, axes and legend.  The four elements of the vector are the coordinates of the lower left corner and width and height of the plot, in units normalized to the width and height of the plot window.  For example, [0.2, 0.3, 0.4, 0.5] sets the lower left corner of the axes at (0.2, 0.3) and the width and height to be 0.4 and 0.5 respectively.  See also the outerposition property.

title
     Index of text object for the axes title.

box
     Either "on" or "off" to toggle display of the box around the axes.

key
     Either "on" or "off" to toggle display of the legend. Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

keybox
     Either "on" or "off" to toggle display of a box around the legend.  Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

keypos
     An integer from 1 to 4 specifying the position of the legend.  1 indicates upper right corner, 2 indicates upper left, 3 indicates lower left, and 4 indicates lower right.  Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

dataaspectratio
     A two-element vector specifying the relative height and width of the data displayed in the axes.  Setting dataaspectratio to 1, 2] causes the length of one unit as displayed on the y axis to be the same as the length of 2 units on the x axis.  Setting dataaspectratio also forces the dataaspectratiomode property to be set to "manual".

dataaspectratiomode
     Either "manual" or "auto".

xlim
ylim
zlim
clim
     Two-element vectors defining the limits for the x, y, and z axes and the Setting one of these properties also forces the corresponding mode property to be set to "manual".

xlimmode
ylimmode
zlimmode
climmode
     Either "manual" or "auto".

xlabel
ylabel
zlabel
     Indices to text objects for the axes labels.

xgrid
ygrid
zgrid
     Either "on" or "off" to toggle display of grid lines.

xminorgrid
yminorgrid
zminorgrid
     Either "on" or "off" to toggle display of minor grid lines.

xtick
ytick
ztick
     Setting one of these properties also forces the corresponding mode property to be set to "manual".

xtickmode
ytickmode
ztickmode
     Either "manual" or "auto".

xticklabel
yticklabel
zticklabel
     Setting one of these properties also forces the corresponding mode property to be set to "manual".

xticklabelmode
yticklabelmode
zticklabelmode
     Either "manual" or "auto".

xscale
yscale
zscale
     Either "linear" or "log".

xdir
ydir
zdir
     Either "forward" or "reverse".

xaxislocation
yaxislocation
     Either "top" or "bottom" for the x axis and "left" or "right" for the y axis.

view
     A three element vector specifying the view point for three-dimensional plots.

visible
     Either "on" or "off" to toggle display of the axes.

nextplot
     May be one of

     "new"

     "add"

     "replace"

     "replacechildren"

outerposition
     A vector specifying the position of the plot, including titles, axes and legend.  The four elements of the vector are the coordinates of the lower left corner and width and height of the plot, in units normalized to the width and height of the plot window.  For example, [0.2, 0.3, 0.4, 0.5] sets the lower left corner of the axes at (0.2, 0.3) and the width and height to be 0.4 and 0.5 respectively.  See also the position property.

Line Properties
...............

xdata
ydata
zdata
ldata
udata
xldata
xudata
     The data to be plotted.  The ldata and udata elements are for errorbars in the y direction, and the xldata and xudata elements are for errorbars in the x direction.

color
     The RGB color of the line, or a color name.  See Colors.

linestyle
linewidth
     See Line Styles.

marker

markeredgecolor

markerfacecolor

markersize
     See Marker Styles.

keylabel
     The text of the legend entry corresponding to this line.  Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

Text Properties
...............

string
     The character string contained by the text object.

units
     May be "normalized" or "graph".

position
     The coordinates of the text object.

rotation
     The angle of rotation for the displayed text, measured in degrees.

horizontalalignment
     May be "left", "center", or "right".

color
     The color of the text.  See Colors.

fontname
     The font used for the text.

fontsize
     The size of the font, in points to use.

fontangle
     Flag whether the font is italic or normal.  Valid values are 'normal', 'italic' and 'oblique'.

fontweight
     Flag whether the font is bold, etc.  Valid values are 'normal', 'bold', 'demi' or 'light'.

interpreter
     Determines how the text is rendered.  Valid values are 'none', 'tex' or 'latex'.

All text objects, including titles, labels, legends, and text, include the property 'interpreter', this property determines the manner in which special control sequences in the text are rendered.  If the interpreter is set to 'none', then no rendering occurs.  At this point the 'latex' option is not implemented and so the 'latex' interpreter also does not interpret the text.

The 'tex' option implements a subset of TEX functionality in the rendering of the text.  This allows the insertion of special characters such as Greek or mathematical symbols within the text.  The special characters are also inserted with a code starting with the back-slash (\) character, as in the table tab:extended.

In addition, the formatting of the text can be changed within the string with the codes

  \bf   Bold font
  \it   Italic font
  \sl   Oblique Font
  \rm   Normal font

These are be used in conjunction with the { and } characters to limit the change in the font to part of the string.  For example

     xlabel ('{\bf H} = a {\bf V}')

where the character 'a' will not appear in a bold font.  Note that to avoid having Octave interpret the backslash characters in the strings, the strings should be in single quotes.

It is also possible to change the fontname and size within the text

  \fontname{FONTNAME}   Specify the font to use
  \fontsize{SIZE}   Specify the size of the font to
use

Finally, the superscript and subscripting can be controlled with the '^' and '_' characters.  If the '^' or '_' is followed by a { character, then all of the block surrounded by the { } pair is super- or sub-scripted.  Without the { } pair, only the character immediately following the '^' or '_' is super- or sub-scripted.

   \forall        \exists        \ni
   \cong          \Delta         \Phi
   \Gamma         \vartheta      \Lambda
   \Pi            \Theta         \Sigma
   \varsigma      \Omega         \Xi
   \Psi           \perp          \alpha
   \beta          \chi           \delta
   \epsilon       \phi           \gamma
   \eta           \iota          \varphi
   \kappa         \lambda        \mu
   \nu            \o             \pi
   \theta         \rho           \sigma
   \tau           \upsilon       \varpi
   \omega         \xi            \psi
   \zeta          \sim           \Upsilon
   \prime         \leq           \infty
   \clubsuit      \diamondsuit       \heartsuit
   \spadesuit     \leftrightarrow    \leftarrow
   \uparrow       \rightarrow    \downarrow
   \circ         \pm             \geq
   \times         \propto        \partial
   \bullet       \div            \neq
   \equiv         \approx        \ldots
   \mid           \aleph         \Im
   \Re           \wp             \otimes
   \oplus        \oslash         \cap
   \cup            \supset       \supseteq
   \subset       \subseteq       \in
   \notin        \angle          \bigrightriangledown
   \langle        \rangle        \nabla
   \prod         \surd           \cdot
   \neg           \wedge        \vee
   \Leftrightarrow   \Leftarrow   \Uparrow
   \Rightarrow   \Downarrow     \diamond
   \copyright     \lfloor        \lceil
   \rfloor        \rceil         \int

Table: Available special characters in TEX mode

A complete example showing the capabilities of the extended text is

     x = 0:0.01:3;
     plot(x,erf(x));
     hold on;
     plot(x,x,"r");
     axis([0, 3, 0, 1]);
     text(0.65, 0.6175, strcat('\leftarrow x = {2/\surd\pi',
     ' {\fontsize{16}\int_{\fontsize{8}0}^{\fontsize{8}x}}',
     ' e^{-t^2} dt} = 0.6175'))

Image Properties
................

cdata
     The data for the image.  Each pixel of the image corresponds to an element of cdata.  The value of an element of cdata specifies the row-index into the colormap of the axes object containing the image.  The color value found in the color map for the given index determines the color of the pixel.

xdata
ydata
     Two-element vectors specifying the range of the x- and y- coordinates for the image.

Patch Properties
................

cdata
xdata
ydata
zdata
     Data defining the patch object.

facecolor
     The fill color of the patch.  See Colors.

facealpha
     A number in the range [0, 1] indicating the transparency of the patch.

edgecolor
     The color of the line defining the patch.  See Colors.

linestyle
linewidth
     See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     See Marker Styles.

Surface Properties
..................

xdata
ydata
zdata
     The data determining the surface.  The xdata and ydata elements are vectors and zdata must be a matrix.

keylabel
     The text of the legend entry corresponding to this surface.  Note that this property is not compatible with MATLAB and may be removed in a future version of Octave.

Searching Properties
....................

(findobj)

(findall)

Managing Default Properties
---------------------------

Object properties have two classes of default values, factory defaults (the initial values) and user-defined defaults, which may override the factory defaults.

Although default values may be set for any object, they are set in parent objects and apply to child objects.  For example,

     set (0, "defaultlinecolor", "green");

sets the default line color for all objects.  The rule for constructing the property name to set a default value is

     default + OBJECT-TYPE + PROPERTY-NAME

This rule can lead to some strange looking names, for example defaultlinelinewidth" specifies the default linewidth property for line objects.

The example above used the root figure object, 0, so the default property value will apply to all line objects.  However, default values are hierarchical, so defaults set in a figure objects override those set in the root figure object.  Likewise, defaults set in axes objects override those set in figure or root figure objects.  For example,

     subplot (2, 1, 1);
     set (0, "defaultlinecolor", "red");
     set (1, "defaultlinecolor", "green");
     set (gca (), "defaultlinecolor", "blue");
     line (1:10, rand (1, 10));
     subplot (2, 1, 2);
     line (1:10, rand (1, 10));
     figure (2)
     line (1:10, rand (1, 10));

produces two figures.  The line in first subplot window of the first figure is blue because it inherits its color from its parent axes object.  The line in the second subplot window of the first figure is green because it inherits its color from its parent figure object.  The line in the second figure window is red because it inherits its color from the global root figure parent object.

To remove a user-defined default setting, set the default property to the value "remove".  For example,

     set (gca (), "defaultlinecolor", "remove");

removes the user-defined default line color setting from the current axes object.

Getting the "default" property of an object returns a list of user-defined defaults set for the object.  For example,

     get (gca (), "default");

returns a list of user-defined default values for the current axes object.

Factory default values are stored in the root figure object.  The command

     get (0, "factory");

returns a list of factory defaults.

Colors
------

Colors may be specified as RGB triplets with values ranging from zero to one, or by name.  Recognized color names include "blue", "black", "cyan", "green", "magenta", "red", "white", and "yellow".

Line Styles
-----------

Line styles are specified by the following properties:

linestyle
     May be one of

     "-"
          Solid lines.

     "--"
          Dashed lines.

     ":"
          Points.

     "-."
          A dash-dot line.

linewidth
     A number specifying the width of the line.  The default is 1.  A value of 2 is twice as wide as the default, etc.

Marker Styles
-------------

Marker styles are specified by the following properties:

marker
     A character indicating a plot marker to be place at each data point, or "none", meaning no markers should be displayed.

markeredgecolor
     The color of the edge around the marker, or "auto", meaning that the edge color is the same as the face color.  See Colors.

markerfacecolor
     The color of the marker, or "none" to indicate that the marker should not be filled.  See Colors.

markersize
     A number specifying the size of the marker.  The default is 1.  A value of 2 is twice as large as the default, etc.

Callbacks
---------

Callback functions can be associated with graphics objects and triggered after certain events occur.  The basic structure of all callback function is

     function mycallback (src, data)
     ...
     endfunction

where src gives a handle to the source of the callback, and code gives some event specific data.  This can then be associated with an object either at the objects creation or later with the set function.  For example

     plot (x, "DeleteFcn", @(s, e) disp("Window Deleted"))

where at the moment that the plot is deleted, the message "Window Deleted" will be displayed.

Additional user arguments can be passed to callback functions, and will be passed after the 2 default arguments.  For example

     plot (x, "DeleteFcn", {@mycallback, "1"})
     ...
     function mycallback (src, data, a1)
       fprintf ("Closing plot %d\n", a1);
     endfunction

The basic callback functions that are available for all graphics objects are

  * CreateFcn This is the callback that is called at the moment of the objects creation.  It is not called if the object is altered in any way, and so it only makes sense to define this callback in the function call that defines the object.  Callbacks that are added to CreateFcn later with the set function will never be executed.

  * DeleteFcn This is the callback that is called at the moment an object is deleted.

  * ButtonDownFcn This is the callback that is called if a mouse button is pressed while the pointer is over this object.  Note, that the gnuplot interface does not respect this callback.

The object and figure that the event occurred in that resulted in the callback being called can be found with the gcbo and gcbf functions.

(gcbo)

(gcbf)

Callbacks can equally be added to properties with the addlistener function described below.

Object Groups
-------------

A number of Octave high level plot functions return groups of other graphics objects or they return graphics objects that are have their properties linked in such a way that changes to one of the properties results in changes in the others.  A graphic object that groups other objects is an hggroup

(hggroup)

For example a simple use of a hggroup might be

     x = 0:0.1:10;
     hg = hggroup ();
     plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
     hold on
     plot (x, cos (x), "color", [0, 1, 0], "parent", hg);
     set (hg, "visible", "off");

which groups the two plots into a single object and controls their visibility directly.  The default properties of an hggroup are the same as the set of common properties for the other graphics objects.  Additional properties can be added with the addproperty function.

(addproperty)

Once a property in added to an hggroup, it is not linked to any other property of either the children of the group, or any other graphics object.  Add so to control the way in which this newly added property is used, the addlistener function is used to define a callback function that is executed when the property is altered.

(addlistener)

(dellistener)

An example of the use of these two functions might be

     x = 0:0.1:10;
     hg = hggroup ();
     h = plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
     addproperty ("linestyle", hg, "linelinestyle", get (h, "linestyle"));
     addlistener (hg, "linestyle", @update_props);
     hold on
     plot (x, cos (x), "color", [0, 1, 0], "parent", hg);

     function update_props (h, d)
       set (get (h, "children"), "linestyle", get (h, "linestyle"));
     endfunction

that adds a linestyle property to the hggroup and propagating any changes its value to the children of the group.  The linkprop function can be used to simplify the above to be

     x = 0:0.1:10;
     hg = hggroup ();
     h1 = plot (x, sin (x), "color", [1, 0, 0], "parent", hg);
     addproperty ("linestyle", hg, "linelinestyle", get (h, "linestyle"));
     hold on
     h2 = plot (x, cos (x), "color", [0, 1, 0], "parent", hg);
     hlink = linkprop ([hg, h1, h2], "color");

(linkprop)

These capabilities are used in a number of basic graphics objects. The hggroup objects created by the functions of Octave contain one or more graphics object and are used to:

  * group together multiple graphics objects,

  * create linked properties between different graphics objects, and

  * to hide the nominal user data, from the actual data of the objects.

For example the stem function creates a stem series where each hggroup of the stem series contains two line objects representing the body and head of the stem.  The ydata property of the hggroup of the stem series represents the head of the stem, whereas the body of the stem is between the baseline and this value.  For example

     h = stem (1:4)
     get (h, "xdata")
     => [  1   2   3   4]'
     get (get (h, "children")(1), "xdata")
     => [  1   1 NaN   2   2 NaN   3   3 NaN   4   4 NaN]'

shows the difference between the xdata of the hggroup of a stem series object and the underlying line.

The basic properties of such group objects is that they consist of one or more linked hggroup, and that changes in certain properties of these groups are propagated to other members of the group.  Whereas, certain properties of the members of the group only apply to the current member.

In addition the members of the group can also be linked to other graphics objects through callback functions.  For example the baseline of the bar or stem functions is a line object, whose length and position are automatically adjusted, based on changes to the corresponding hggroup elements.

Data sources in object groups
.............................

All of the group objects contain data source parameters.  There are string parameters that contain an expression that is evaluated to update the relevant data property of the group when the refreshdata function is called.

(refreshdata)

Area series
...........

Area series objects are created by the area function.  Each of the hggroup elements contains a single patch object.  The properties of the area series are

basevalue
     The value where the base of the area plot is drawn.

linewidth
linestyle
     The line width and style of the edge of the patch objects making up the areas.  See Line Styles.

edgecolor
facecolor
     The line and fill color of the patch objects making up the areas.  See Colors.

xdata
ydata
     The x and y coordinates of the original columns of the data passed to area prior to the cumulative summation used in the area function.

xdatasource
ydatasource
     Data source variables.

Bar series
..........

Bar series objects are created by the bar or barh functions.  Each hggroup element contains a single patch object. The properties of the bar series are

showbaseline
baseline
basevalue
     The property showbaseline flags whether the baseline of the bar series is displayed (default is "on").  The handle of the graphics object representing the baseline is given by the baseline property and the y-value of the baseline by the basevalue property.

     Changes to any of these property are propagated to the other members of the bar series and to the baseline itself.  Equally changes in the properties of the base line itself are propagated to the members of the corresponding bar series.

barwidth
barlayout
horizontal
     The property barwidth is the width of the bar corresponding to the WIDTH variable passed to bar or BARH.  Whether the bar series is "grouped" or "stacked" is determined by the barlayout property and whether the bars are horizontal or vertical by the horizontal property.

     Changes to any of these property are propagated to the other members of the bar series.

linewidth
linestyle
     The line width and style of the edge of the patch objects making up the bars.  See Line Styles.

edgecolor
facecolor
     The line and fill color of the patch objects making up the bars.  See Colors.

xdata
     The nominal x positions of the bars.  Changes in this property and propagated to the other members of the bar series.

ydata
     The y value of the bars in the hggroup.

xdatasource
ydatasource
     Data source variables.

Contour groups
..............

Contour group objects are created by the contour, contourf and contour3 functions.  The are equally one of the handles returned by the surfc and meshc functions.  The properties of the contour group are

contourmatrix
     A read only property that contains the data return by contourc used to create the contours of the plot.

fill
     A radio property that can have the values "on" or "off" that flags whether the contours to plot are to be filled.

zlevelmode
zlevel
     The radio property zlevelmode can have the values "none", "auto" or "manual".  When its value is "none" there is no z component to the plotted contours.  When its value is "auto" the z value of the plotted contours is at the same value as the contour itself.  If the value is "manual", then the z value at which to plot the contour is determined by the zlevel property.

levellistmode
levellist
levelstepmode
levelstep
     If levellistmode is "manual", then the levels at which to plot the contours is determined by levellist.  If levellistmode is set to "auto", then the distance between contours is determined by levelstep.  If both levellistmode and levelstepmode are set to "auto", then there are assumed to be 10 equal spaced contours.

textlistmode
textlist
textstepmode
textstep
     If textlistmode is "manual", then the labelled contours is determined by textlist.  If textlistmode is set to "auto", then the distance between labelled contours is determined by textstep.  If both textlistmode and textstepmode are set to "auto", then there are assumed to be 10 equal spaced labelled contours.

showtext
     Flag whether the contour labels are shown or not.

labelspacing
     The distance between labels on a single contour in points.

linewidth

linestyle

linecolor
     The properties of the contour lines.  The properties linewidth and linestyle are similar to the corresponding properties for lines.  The property linecolor is a color property (see Colors), that can also have the values of "none" or "auto".  If linecolor is "none", then no contour line is drawn.  If linecolor is "auto" then the line color is determined by the colormap.

xdata
ydata
zdata
     The original x, y, and z data of the contour lines.

xdatasource
ydatasource
zdatasource
     Data source variables.

Error bar series
................

Error bar series are created by the errorbar function.  Each hggroup element contains two line objects representing the data and the errorbars separately.  The properties of the error bar series are

color
     The RGB color or color name of the line objects of the error bars.  See Colors.

linewidth
linestyle
     The line width and style of the line objects of the error bars.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers on the error bars.  See Colors.

xdata
ydata
ldata
udata
xldata
xudata
     The original x, y, l, u, xl, xu data of the error bars.

xdatasource
ydatasource
ldatasource
udatasource
xldatasource
xudatasource
     Data source variables.

Line series
...........

Line series objects are created by the plot  and plot3 functions and are of the type line.  The properties of the line series with the ability to add data sources.

color
     The RGB color or color name of the line objects.  See Colors.

linewidth
linestyle
     The line width and style of the line objects.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers.  See Colors.

xdata
ydata
zdata
     The original x, y and z data.

xdatasource
ydatasource
zdatasource
     Data source variables.

Quiver group
............

Quiver series objects are created by the quiver or quiver3 functions.  Each hggroup element of the series contains three line objects as children representing the body and head of the arrow, together with a marker as the point of original of the arrows.  The properties of the quiver series are

autoscale
autoscalefactor
     Flag whether the length of the arrows is scaled or defined directly from the U, V and W data.  If the arrow length is flagged as being scaled by the autoscale property, then the length of the autoscaled arrow is controlled by the autoscalefactor.

maxheadsize
     This property controls the size of the head of the arrows in the quiver series.  The default value is 0.2.

showarrowhead
     Flag whether the arrow heads are displayed in the quiver plot.

color
     The RGB color or color name of the line objects of the quiver.  See Colors.

linewidth
linestyle
     The line width and style of the line objects of the quiver.  See Line Styles.

marker
markerfacecolor
markersize
     The line and fill color of the marker objects at the original of the arrows.  See Colors.

xdata
ydata
zdata
     The origins of the values of the vector field.

udata
vdata
wdata
     The values of the vector field to plot.

xdatasource
ydatasource
zdatasource
udatasource
vdatasource
wdatasource
     Data source variables.

Scatter group
.............

Scatter series objects are created by the scatter or scatter3 functions.  A single hggroup element contains as many children as there are points in the scatter plot, with each child representing one of the points. The properties of the stem series are

linewidth
     The line width of the line objects of the points.  See Line Styles.

marker
markeredgecolor
markerfacecolor
     The line and fill color of the markers of the points.  See Colors.

xdata
ydata
zdata
     The original x, y and z data of the stems.

cdata
     The color data for the points of the plot.  Each point can have a separate color, or a unique color can be specified.

sizedata
     The size data for the points of the plot.  Each point can its own size or a unique size can be specified.

xdatasource
ydatasource
zdatasource
cdatasource
sizedatasource
     Data source variables.

Stair group
...........

Stair series objects are created by the stair function.  Each hggroup element of the series contains a single line object as a child representing the stair.  The properties of the stair series are

color
     The RGB color or color name of the line objects of the stairs.  See Colors.

linewidth
linestyle
     The line width and style of the line objects of the stairs.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers on the stairs.  See Colors.

xdata
ydata
     The original x and y data of the stairs.

xdatasource
ydatasource
     Data source variables.

Stem Series
...........

Stem series objects are created by the stem or stem3 functions.  Each hggroup element contains a single line object as a child representing the stems.  The properties of the stem series are

showbaseline
baseline
basevalue
     The property showbaseline flags whether the baseline of the stem series is displayed (default is "on").  The handle of the graphics object representing the baseline is given by the baseline property and the y-value (or z-value for stem3) of the baseline by the basevalue property.

     Changes to any of these property are propagated to the other members of the stem series and to the baseline itself.  Equally changes in the properties of the base line itself are propagated to the members of the corresponding stem series.

color
     The RGB color or color name of the line objects of the stems.  See Colors.

linewidth
linestyle
     The line width and style of the line objects of the stems.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers on the stems.  See Colors.

xdata
ydata
zdata
     The original x, y and z data of the stems.

xdatasource
ydatasource
zdatasource
     Data source variables.

Surface group
.............

Surface group objects are created by the surf or mesh functions, but are equally one of the handles returned by the surfc or meshc functions.  The surface group is of the type surface.

The properties of the surface group are

edgecolor

facecolor
     The RGB color or color name of the edges or faces of the surface.  See Colors.

linewidth
linestyle
     The line width and style of the lines on the surface.  See Line Styles.

marker
markeredgecolor
markerfacecolor
markersize
     The line and fill color of the markers on the surface.  See Colors.

xdata
ydata
zdata

cdata
     The original x, y, z and c data.

xdatasource
ydatasource
zdatasource
cdatasource
     Data source variables.

Graphics backends
-----------------

(backend)

(available_backends)

Interaction with gnuplot
........................

(gnuplot_binary)