This is octave.info, produced by makeinfo version 7.1.1 from
octave.texi.

INFO-DIR-SECTION Math
START-INFO-DIR-ENTRY
* Octave: (octave).             Interactive language for numerical computations.
END-INFO-DIR-ENTRY

Copyright © 1996-2026 The Octave Project Developers

 Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

 Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

 Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: octave.info,  Node: Surface Properties,  Next: Light Properties,  Prev: Scatter Properties,  Up: Graphics Object Properties

15.3.3.10 Surface Properties
............................

Properties of ‘surface’ objects (*note surface: XREFsurface.):

Categories:
...........

*note Callback Execution: XREFsurfacecategoryCallbackExecution. | *note
Color and Transparency: XREFsurfacecategoryColorandTransparency. | *note
Coordinate Data: XREFsurfacecategoryCoordinateData. | *note
Creation/Deletion: XREFsurfacecategoryCreation/Deletion. | *note
Display: XREFsurfacecategoryDisplay. | *note Faces Appearance:
XREFsurfacecategoryFacesAppearance. | *note Legend Options:
XREFsurfacecategoryLegendOptions. | *note Lighting:
XREFsurfacecategoryLighting. | *note Marker Appearance:
XREFsurfacecategoryMarkerAppearance. | *note Mouse Interaction:
XREFsurfacecategoryMouseInteraction. | *note Object Identification:
XREFsurfacecategoryObjectIdentification. | *note Outline Appearance:
XREFsurfacecategoryOutlineAppearance. | *note Parent/Children:
XREFsurfacecategoryParent/Children.

Callback Execution
..................

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object's callback
     properties when it is unable to interrupt another object's
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘interruptible’: "off" | {"on"}
     Specify whether this object's callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

Color and Transparency
......................

‘alphadata’: scalar | matrix, def. ‘1’
     Transparency is not yet implemented for surface objects.
     ‘alphadata’ is unused.

‘alphadatamapping’: "direct" | "none" | {"scaled"}
     Transparency is not yet implemented for surface objects.
     ‘alphadatamapping’ is unused.

‘cdata’: array, def. 3-by-3 double
     Color data values for surface vertices.  Data is stored either as a
     2-D matrix the same size as *note "zdata": XREFsurfacezdata. where
     each element's value determines that vertex's color according to
     the current colormap, or as a 3-D array where the third dimension
     contains separate red, blue, and green components for each vertex.

‘cdatamapping’: "direct" | {"scaled"}
     Sets the method for mapping data from the *note "cdata" property:
     XREFsurfacecdata. to the current colormap.  "Direct" mapping
     selects the color using the "cdata" value as an index to the
     current colormap.  "Scale" mapping scales the "cdata" values to the
     range specified in the *note "clim" axes property: XREFaxesclim.

‘cdatasource’: string, def. ""
     The name of a workspace variable that contains data that will be
     used for the *note "cdata" property: XREFsurfacecdata.  Data is
     transferred into "cdata" using the *note refreshdata function:
     XREFrefreshdata.

Coordinate Data
...............

‘xdata’: matrix, def. ‘[1 2 3]’
     Data for the x-coordinate.

‘xdatasource’: string, def. ""
     The name of a workspace variable that contains data that will be
     used for the *note "xdata" property: XREFsurfacexdata.  Data is
     transferred into "xdata" using the *note refreshdata function:
     XREFrefreshdata.

‘ydata’: matrix, def. ‘[1; 2; 3]’
     Data for the y-coordinate.

‘ydatasource’: string, def. ""
     The name of a workspace variable that contains data that will be
     used for the *note "ydata" property: XREFsurfaceydata.  Data is
     transferred into "ydata" using the *note refreshdata function:
     XREFrefreshdata.

‘zdata’: matrix, def. 3-by-3 double
     Data for the z-coordinate.

‘zdatasource’: string, def. ""
     The name of a workspace variable that contains data that will be
     used for the *note "zdata" property: XREFsurfacezdata.  Data is
     transferred into "zdata" using the *note refreshdata function:
     XREFrefreshdata.

Creation/Deletion
.................

‘beingdeleted’: {"off"} | "on"
     Property indicating that a function has initiated deletion of the
     object.  ‘beingdeleted’ is set to true until the object no longer
     exists.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after surface has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultsurfacecreatefcn", 'disp ("surface
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before surface is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Display
.......

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the surface is clipped in its parent axes
     limits.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the surface is not rendered on screen.

Faces Appearance
................

‘facealpha’: scalar | "flat" | "interp" | "texturemap", def. ‘1’
     Transparency level of the faces of the surface object.  Only double
     values are supported at present where a value of 0 means complete
     transparency and a value of 1 means solid faces without
     transparency.  Setting the property to "flat", "interp" or
     "texturemap" causes the faces to not being rendered.  Additionally,
     the faces are not sorted from back to front which might lead to
     unexpected results when rendering layered transparent faces.

‘facecolor’: colorspec | "none" | {"flat"} | "interp"
     Color of the faces of the surface object, specified as either a
     valid color specification or one of "none", "flat", or "interp".
     "flat" and "interp" will set either a single color for each face or
     a color interpolated across the face's vertices using the color
     value data stored in *note "cdata": XREFsurfacecdata.  *Note
     colorspec: Colors.

‘facelighting’: {"flat"} | "gouraud" | "none" | "phong"
     When set to a value other than "none", the faces of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (faceted look), and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘facenormals’: def. ‘[](0x0)’
     Face normals are used for lighting the edges or faces if the
     ‘edgelighting’ or ‘facelighting’ properties are set to "flat".
     Setting ‘facenormals’ also forces the ‘facenormalsmode’ property to
     be set to "manual".

‘facenormalsmode’: {"auto"} | "manual"
     If this property is set to "auto", ‘facenormals’ are automatically
     calculated if the ‘edgelighting’ or ‘facelighting’ property are set
     to "flat" and at least one ‘light’ object is present and visible in
     the same axes.

Legend Options
..............

‘displayname’: def. ""
     Text for the legend entry corresponding to this surface.

Lighting
........

‘ambientstrength’: scalar, def. ‘0.3000’
     Strength of the ambient light.  Value between 0.0 and 1.0.

‘backfacelighting’: "lit" | {"reverselit"} | "unlit"
     "lit": The normals are used as is for lighting.  "reverselit": The
     normals are always oriented towards the point of view.  "unlit":
     Faces with normals pointing away from the point of view are unlit.

‘diffusestrength’: scalar, def. ‘0.6000’
     Strength of the diffuse reflection.  Value between 0.0 (no diffuse
     reflection) and 1.0 (full diffuse reflection).

‘specularcolorreflectance’: scalar, def. ‘1’
     Reflectance for specular color.  Value between 0.0 (color of
     underlying face) and 1.0 (color of light source).

‘specularexponent’: scalar, def. ‘10’
     Exponent for the specular reflection.  The lower the value, the
     more the reflection is spread out.

‘specularstrength’: scalar, def. ‘0.9000’
     Strength of the specular reflection.  Value between 0.0 (no
     specular reflection) and 1.0 (full specular reflection).

‘vertexnormals’: def. ‘[](0x0)’
     Vertex normals are used for lighting the edges or faces if the
     ‘edgelighting’ or ‘facelighting’ properties are set to "gouraud".
     Setting ‘vertexnormals’ also forces the ‘vertexnormalsmode’
     property to be set to "manual".

‘vertexnormalsmode’: {"auto"} | "manual"
     If this property is set to "auto", ‘vertexnormals’ are
     automatically calculated if the ‘edgelighting’ or ‘facelighting’
     property are set to "gouraud" and at least one ‘light’ object is
     present and visible in the same axes.

Marker Appearance
.................

‘marker’: "*" | "+" | "." | "<" | ">" | "^" | "_" | "d" | "diamond" | "h" | "hexagram" | {"none"} | "o" | "p" | "pentagram" | "s" | "square" | "v" | "x" | "|"
     *Note Marker Styles::.

‘markeredgecolor’: {"auto"} | "flat" | "none"
     *Note line markeredgecolor property: XREFlinemarkeredgecolor.

‘markerfacecolor’: "auto" | "flat" | {"none"}
     *Note line markerfacecolor property: XREFlinemarkerfacecolor.

‘markersize’: scalar, def. ‘6’
     *Note line markersize property: XREFlinemarkersize.

Mouse Interaction
.................

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this surface object.

‘hittest’: "off" | {"on"}
     Specify whether surface processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFsurfacepickableparts.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether surface will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the surface
     or its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFsurfacehittest.

‘selected’: {"off"} | "on"
     Property indicates whether this surface is selected.

‘selectionhighlight’: "off" | {"on"}
     If ‘selectionhighlight’ is "on", then the surface's selection state
     is visually highlighted.

Object Identification
.....................

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "surface".

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

Outline Appearance
..................

‘edgealpha’: scalar, def. ‘1’
     Transparency is not yet implemented for surface objects.
     ‘edgealpha’ is unused.

‘edgecolor’: colorspec | "none" | "flat" | "interp", def. ‘[0 0 0]’
     Color of the edges of the surface object, specified as either a
     valid color specification or one of "none", "flat", or "interp".
     "flat" and "interp" will set either a single color for each edge or
     a color interpolated between two adjacent vertices using the color
     value data stored in *note "cdata": XREFsurfacecdata.  *Note
     colorspec: Colors.

‘edgelighting’: "flat" | "gouraud" | {"none"} | "phong"
     When set to a value other than "none", the edges of the object are
     drawn with light and shadow effects.  Supported values are "none"
     (no lighting effects), "flat" (faceted look), and "gouraud" (linear
     interpolation of the lighting effects between the vertices).
     "phong" is deprecated and has the same effect as "gouraud".

‘linestyle’: {"-"} | "-" | "-." | ":" | "none"
     *Note Line Styles::.

‘linewidth’: scalar, def. ‘0.5000’
     *Note line linewidth property: XREFlinelinewidth.

‘meshstyle’: {"both"} | "column" | "row"
     Specifies whether to display the edges associated with the surface
     data's rows, columns, or both.

Parent/Children
...............

‘children’ (read-only): vector of graphics handles, def. ‘[](0x0)’
     Child objects for Surfaces is not yet implemented for surface
     objects.  ‘children’ is unused.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the surface's handle is not visible
     in its parent's "children" property.

‘parent’: graphics handle
     Handle of the parent graphics object.


File: octave.info,  Node: Light Properties,  Next: Uimenu Properties,  Prev: Surface Properties,  Up: Graphics Object Properties

15.3.3.11 Light Properties
..........................

Properties of ‘light’ objects (*note light: XREFlight.):

Categories:
...........

*note Callback Execution: XREFlightcategoryCallbackExecution. | *note
Creation/Deletion: XREFlightcategoryCreation/Deletion. | *note Display:
XREFlightcategoryDisplay. | *note Lighting: XREFlightcategoryLighting. |
*note Mouse Interaction: XREFlightcategoryMouseInteraction. | *note
Object Identification: XREFlightcategoryObjectIdentification. | *note
Parent/Children: XREFlightcategoryParent/Children.

Callback Execution
..................

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object's callback
     properties when it is unable to interrupt another object's
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘interruptible’: "off" | {"on"}
     Specify whether this object's callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

Creation/Deletion
.................

‘beingdeleted’: {"off"} | "on"
     Property indicating that a function has initiated deletion of the
     object.  ‘beingdeleted’ is set to true until the object no longer
     exists.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after light has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultlightcreatefcn", 'disp ("light
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before light is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Display
.......

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the light is clipped in its parent axes
     limits.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the light is not rendered on screen.

Lighting
........

‘color’: colorspec, def. ‘[1 1 1]’
     Color of the light source.  *Note colorspec: Colors.

‘position’: def. ‘[1 0 1]’
     Position of the light source.

‘style’: {"infinite"} | "local"
     This string defines whether the light emanates from a light source
     at infinite distance ("infinite") or from a local point source
     ("local").

Mouse Interaction
.................

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this light object.

‘hittest’: "off" | {"on"}
     Specify whether light processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFlightpickableparts.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether light will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the light or
     its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFlighthittest.

‘selected’: {"off"} | "on"
     Property indicates whether this light is selected.

‘selectionhighlight’: "off" | {"on"}
     If ‘selectionhighlight’ is "on", then the light's selection state
     is visually highlighted.

Object Identification
.....................

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "light".

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

Parent/Children
...............

‘children’ (read-only): vector of graphics handles, def. ‘[](0x0)’
     light objects have no child objects.  ‘children’ is unused.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the light's handle is not visible
     in its parent's "children" property.

‘parent’: graphics handle
     Handle of the parent graphics object.


File: octave.info,  Node: Uimenu Properties,  Next: Uibuttongroup Properties,  Prev: Light Properties,  Up: Graphics Object Properties

15.3.3.12 Uimenu Properties
...........................

Properties of ‘uimenu’ objects (*note uimenu: XREFuimenu.):

Categories:
...........

*note Appearance: XREFuimenucategoryAppearance. | *note
Callback Execution: XREFuimenucategoryCallbackExecution. | *note
Creation/Deletion: XREFuimenucategoryCreation/Deletion. | *note Display:
XREFuimenucategoryDisplay. | *note Keyboard Interaction:
XREFuimenucategoryKeyboardInteraction. | *note Menu Options:
XREFuimenucategoryMenuOptions. | *note Mouse Interaction:
XREFuimenucategoryMouseInteraction. | *note Object Identification:
XREFuimenucategoryObjectIdentification. | *note Object Position:
XREFuimenucategoryObjectPosition. | *note Parent/Children:
XREFuimenucategoryParent/Children.

Appearance
..........

‘foregroundcolor’: colorspec, def. ‘[0 0 0]’
     The color value of the text for this menu entry.

‘separator’: {"off"} | "on"
     State indicating whether a separator line will be drawn above the
     current menu position.

Callback Execution
..................

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object's callback
     properties when it is unable to interrupt another object's
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘interruptible’: "off" | {"on"}
     Specify whether this object's callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘menuselectedfcn’: string | function handle, def. ‘[](0x0)’
     Function that is called when this menu item is executed.  For
     information on how to write graphics listener functions see *note
     Callbacks section: Callbacks.

Creation/Deletion
.................

‘beingdeleted’: {"off"} | "on"
     Property indicating that a function has initiated deletion of the
     object.  ‘beingdeleted’ is set to true until the object no longer
     exists.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uimenu has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuimenucreatefcn", 'disp ("uimenu
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uimenu is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Display
.......

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uimenu is clipped in its parent axes
     limits.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uimenu is not rendered on screen.

Keyboard Interaction
....................

‘accelerator’: character, def. ""
     A character that when pressed together with CTRL will execute this
     menu entry (e.g., "x" for ‘CTRL+x’).

Menu Options
............

‘checked’: {"off"} | "on"
     Sets whether or not a mark appears at this menu entry.

‘enable’: "off" | {"on"}
     Sets whether this menu entry is active or is grayed out.

‘text’: string, def. ""
     The text for this menu entry.  A "&" character can be used to mark
     the *note "accelerator" key: XREFuimenuaccelerator.

Mouse Interaction
.................

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uimenu object.

‘hittest’: "off" | {"on"}
     Specify whether uimenu processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuimenupickableparts.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uimenu will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the uimenu
     or its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFuimenuhittest.

‘selected’: {"off"} | "on"
     Property indicates whether this uimenu is selected.

‘selectionhighlight’: "off" | {"on"}
     If ‘selectionhighlight’ is "on", then the uimenu's selection state
     is visually highlighted.

Object Identification
.....................

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uimenu".

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

Object Position
...............

‘position’: scalar, def. ‘4’
     A scalar value containing the relative menu position from the left
     or top depending on the orientation of the menu.

Parent/Children
...............

‘children’ (read-only): vector of graphics handles, def. ‘[](0x0)’
     Graphics handles of the uimenu's children.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uimenu's handle is not visible
     in its parent's "children" property.

‘parent’: graphics handle
     Handle of the parent graphics object.


File: octave.info,  Node: Uibuttongroup Properties,  Next: Uicontextmenu Properties,  Prev: Uimenu Properties,  Up: Graphics Object Properties

15.3.3.13 Uibuttongroup Properties
..................................

Properties of ‘uibuttongroup’ objects (*note uibuttongroup:
XREFuibuttongroup.):

Categories:
...........

*note Appearance: XREFuibuttongroupcategoryAppearance. | *note
Button Group Operation: XREFuibuttongroupcategoryButtonGroupOperation. |
*note Callback Execution: XREFuibuttongroupcategoryCallbackExecution. |
*note Creation/Deletion: XREFuibuttongroupcategoryCreation/Deletion. |
*note Display: XREFuibuttongroupcategoryDisplay. | *note
Mouse Interaction: XREFuibuttongroupcategoryMouseInteraction. | *note
Object Identification: XREFuibuttongroupcategoryObjectIdentification. |
*note Object Position: XREFuibuttongroupcategoryObjectPosition. | *note
Parent/Children: XREFuibuttongroupcategoryParent/Children. | *note
Text Appearance: XREFuibuttongroupcategoryTextAppearance.

Appearance
..........

‘backgroundcolor’: colorspec, def. ‘[0.9400 0.9400 0.9400]’
     The color value of the background of this buttongroup.

‘bordertype’: "beveledin" | "beveledout" | {"etchedin"} | "etchedout" | "line" | "none"
     Sets whether or not a line border will surround the buttongroup.

‘borderwidth’: whole number scalar, def. ‘1’
     The width of the line border in pixels.

‘foregroundcolor’: colorspec, def. ‘[0 0 0]’
     The color value of the title text for this buttongroup.

‘highlightcolor’: colorspec, def. ‘[1 1 1]’
     The color value of the line bordering this buttongroup.

‘shadowcolor’: colorspec, def. ‘[0.7000 0.7000 0.7000]’
     The color value of the line surrounding the border line around this
     buttongroup.

‘sizechangedfcn’: string | function handle, def. ‘[](0x0)’
     Callback triggered when the buttongroup size is changed.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Button Group Operation
......................

‘selectedobject’: def. ‘[](0x0)’
     Graphic handle of the currently selected item in the buttongroup.

Callback Execution
..................

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object's callback
     properties when it is unable to interrupt another object's
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘interruptible’: "off" | {"on"}
     Specify whether this object's callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘resizefcn’: string | function handle, def. ‘[](0x0)’
     ‘resizefcn’ is deprecated.  Use ‘sizechangedfcn’ instead.

‘selectionchangedfcn’: string | function handle, def. ‘[](0x0)’
     Callback triggered when the selected item within the buttongroup is
     changed.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Creation/Deletion
.................

‘beingdeleted’: {"off"} | "on"
     Property indicating that a function has initiated deletion of the
     object.  ‘beingdeleted’ is set to true until the object no longer
     exists.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uibuttongroup has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuibuttongroupcreatefcn", 'disp
     ("uibuttongroup created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uibuttongroup is
     deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Display
.......

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uibuttongroup is clipped in its parent
     axes limits.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uibuttongroup is not rendered on screen.

Mouse Interaction
.................

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uibuttongroup object.

‘hittest’: "off" | {"on"}
     Specify whether uibuttongroup processes mouse events or passes them
     to ancestors of the object.  When enabled, the object may respond
     to mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuibuttongrouppickableparts.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uibuttongroup will accept mouse clicks.  By
     default, ‘pickableparts’ is "visible" and only visible parts of the
     uibuttongroup or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuibuttongrouphittest.

‘selected’: {"off"} | "on"
     Property indicates whether this uibuttongroup is selected.

‘selectionhighlight’: "off" | {"on"}
     If ‘selectionhighlight’ is "on", then the uibuttongroup's selection
     state is visually highlighted.

Object Identification
.....................

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always
     "uibuttongroup".

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

Object Position
...............

‘position’: four-element vector, def. ‘[0 0 1 1]’
     Size of the buttongroup represented as the four-element vector
     [left, bottom, width, height].

‘units’: "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points"
     Unit of measurement used to interpret the "position" property.

Parent/Children
...............

‘children’ (read-only): vector of graphics handles, def. ‘[](0x0)’
     Graphics handles of the uibuttongroup's children.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uibuttongroup's handle is not
     visible in its parent's "children" property.

‘parent’: graphics handle
     Handle of the parent graphics object.

Text Appearance
...............

‘fontangle’: "italic" | {"normal"}
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

     Programming Note: On systems that don’t use FontConfig natively
     (all but Linux), the font cache is built when Octave is installed.
     You will need to run ‘system ("fc-cache -fv")’ manually after
     installing new fonts.

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFuibuttongroupfontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | {"normal"}
     Control the variant of the base font used for text rendering.

‘title’: string, def. ""
     The text for the buttongroup title.

‘titleposition’: "centerbottom" | "centertop" | "leftbottom" | {"lefttop"} | "rightbottom" | "righttop"
     Relative position of the title within the buttongroup.


File: octave.info,  Node: Uicontextmenu Properties,  Next: Uipanel Properties,  Prev: Uibuttongroup Properties,  Up: Graphics Object Properties

15.3.3.14 Uicontextmenu Properties
..................................

Properties of ‘uicontextmenu’ objects (*note uicontextmenu:
XREFuicontextmenu.):

Categories:
...........

*note Callback Execution: XREFuicontextmenucategoryCallbackExecution. |
*note Creation/Deletion: XREFuicontextmenucategoryCreation/Deletion. |
*note Display: XREFuicontextmenucategoryDisplay. | *note
Mouse Interaction: XREFuicontextmenucategoryMouseInteraction. | *note
Object Identification: XREFuicontextmenucategoryObjectIdentification. |
*note Object Position: XREFuicontextmenucategoryObjectPosition. | *note
Parent/Children: XREFuicontextmenucategoryParent/Children.

Callback Execution
..................

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object's callback
     properties when it is unable to interrupt another object's
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘callback’: string, def. ‘[](0x0)’
     A string consisting of a valid Octave expression that will be
     executed whenever this item is selected.

‘interruptible’: "off" | {"on"}
     Specify whether this object's callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

Creation/Deletion
.................

‘beingdeleted’: {"off"} | "on"
     Property indicating that a function has initiated deletion of the
     object.  ‘beingdeleted’ is set to true until the object no longer
     exists.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uicontextmenu has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuicontextmenucreatefcn", 'disp
     ("uicontextmenu created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uicontextmenu is
     deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Display
.......

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uicontextmenu is clipped in its parent
     axes limits.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uicontextmenu is not rendered on screen.

Mouse Interaction
.................

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uicontextmenu object.

‘hittest’: "off" | {"on"}
     Specify whether uicontextmenu processes mouse events or passes them
     to ancestors of the object.  When enabled, the object may respond
     to mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuicontextmenupickableparts.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uicontextmenu will accept mouse clicks.  By
     default, ‘pickableparts’ is "visible" and only visible parts of the
     uicontextmenu or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuicontextmenuhittest.

‘selected’: {"off"} | "on"
     Property indicates whether this uicontextmenu is selected.

‘selectionhighlight’: "off" | {"on"}
     If ‘selectionhighlight’ is "on", then the uicontextmenu's selection
     state is visually highlighted.

Object Identification
.....................

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always
     "uicontextmenu".

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

Object Position
...............

‘position’: def. ‘[0 0]’
     Manually setting location for uicontextmenu to appear is not yet
     implemented for uicontextmenu objects.  ‘position’ is unused.

Parent/Children
...............

‘children’ (read-only): vector of graphics handles, def. ‘[](0x0)’
     Graphics handles of the uicontextmenu's children.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uicontextmenu's handle is not
     visible in its parent's "children" property.

‘parent’: graphics handle
     Handle of the parent graphics object.


File: octave.info,  Node: Uipanel Properties,  Next: Uicontrol Properties,  Prev: Uicontextmenu Properties,  Up: Graphics Object Properties

15.3.3.15 Uipanel Properties
............................

Properties of ‘uipanel’ objects (*note uipanel: XREFuipanel.):

Categories:
...........

*note Appearance: XREFuipanelcategoryAppearance. | *note
Callback Execution: XREFuipanelcategoryCallbackExecution. | *note
Creation/Deletion: XREFuipanelcategoryCreation/Deletion. | *note
Display: XREFuipanelcategoryDisplay. | *note Mouse Interaction:
XREFuipanelcategoryMouseInteraction. | *note Object Identification:
XREFuipanelcategoryObjectIdentification. | *note Object Position:
XREFuipanelcategoryObjectPosition. | *note Parent/Children:
XREFuipanelcategoryParent/Children. | *note Text Appearance:
XREFuipanelcategoryTextAppearance.

Appearance
..........

‘backgroundcolor’: colorspec, def. ‘[0.9400 0.9400 0.9400]’
     The color value of the background of this panel.

‘bordertype’: "beveledin" | "beveledout" | {"etchedin"} | "etchedout" | "line" | "none"
     Sets whether or not a line border will surround the panel.

‘borderwidth’: whole number scalar, def. ‘1’
     The width of the line border in pixels.

‘foregroundcolor’: colorspec, def. ‘[0 0 0]’
     The color value of the title text for this panel.

‘highlightcolor’: colorspec, def. ‘[1 1 1]’
     The color value of the line bordering this panel.

‘shadowcolor’: colorspec, def. ‘[0.7000 0.7000 0.7000]’
     The color value of the line surrounding the border line around this
     panel.  *Note colorspec: Colors.

Callback Execution
..................

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object's callback
     properties when it is unable to interrupt another object's
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘interruptible’: "off" | {"on"}
     Specify whether this object's callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘resizefcn’: string | function handle, def. ‘[](0x0)’
     ‘resizefcn’ is deprecated.  Use ‘sizechangedfcn’ instead.

‘sizechangedfcn’: string | function handle, def. ‘[](0x0)’
     Callback triggered when the panel size is changed.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Creation/Deletion
.................

‘beingdeleted’: {"off"} | "on"
     Property indicating that a function has initiated deletion of the
     object.  ‘beingdeleted’ is set to true until the object no longer
     exists.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uipanel has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuipanelcreatefcn", 'disp ("uipanel
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uipanel is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Display
.......

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uipanel is clipped in its parent axes
     limits.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uipanel is not rendered on screen.

Mouse Interaction
.................

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uipanel object.

‘hittest’: "off" | {"on"}
     Specify whether uipanel processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuipanelpickableparts.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uipanel will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the uipanel
     or its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFuipanelhittest.

‘selected’: {"off"} | "on"
     Property indicates whether this uipanel is selected.

‘selectionhighlight’: "off" | {"on"}
     If ‘selectionhighlight’ is "on", then the uipanel's selection state
     is visually highlighted.

Object Identification
.....................

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uipanel".

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

Object Position
...............

‘position’: four-element vector, def. ‘[0 0 1 1]’
     Size of the panel represented as the four-element vector [left,
     bottom, width, height].

‘units’: "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points"
     Unit of measurement used to interpret the "position" property.

Parent/Children
...............

‘children’ (read-only): vector of graphics handles, def. ‘[](0x0)’
     Graphics handles of the uipanel's children.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uipanel's handle is not visible
     in its parent's "children" property.

‘parent’: graphics handle
     Handle of the parent graphics object.

Text Appearance
...............

‘fontangle’: "italic" | {"normal"}
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

     Programming Note: On systems that don’t use FontConfig natively
     (all but Linux), the font cache is built when Octave is installed.
     You will need to run ‘system ("fc-cache -fv")’ manually after
     installing new fonts.

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFuipanelfontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | {"normal"}
     Control the variant of the base font used for text rendering.

‘title’: string, def. ""
     The text for the panel title.

‘titleposition’: "centerbottom" | "centertop" | "leftbottom" | {"lefttop"} | "rightbottom" | "righttop"
     Relative position of the title within the panel.


File: octave.info,  Node: Uicontrol Properties,  Next: Uitable Properties,  Prev: Uipanel Properties,  Up: Graphics Object Properties

15.3.3.16 Uicontrol Properties
..............................

Properties of ‘uicontrol’ objects (*note uicontrol: XREFuicontrol.):

Categories:
...........

*note Appearance: XREFuicontrolcategoryAppearance. | *note
Callback Execution: XREFuicontrolcategoryCallbackExecution. | *note
Control Options: XREFuicontrolcategoryControlOptions. | *note
Creation/Deletion: XREFuicontrolcategoryCreation/Deletion. | *note
Display: XREFuicontrolcategoryDisplay. | *note Mouse Interaction:
XREFuicontrolcategoryMouseInteraction. | *note Object Identification:
XREFuicontrolcategoryObjectIdentification. | *note Object Position:
XREFuicontrolcategoryObjectPosition. | *note Parent/Children:
XREFuicontrolcategoryParent/Children. | *note Text Appearance:
XREFuicontrolcategoryTextAppearance.

Appearance
..........

‘backgroundcolor’: colorspec, def. ‘[0.9400 0.9400 0.9400]’
     The color value of the background of this control object.

‘cdata’: array, def. ‘[](0x0)’
     Image data used to represent the control object, stored as a M x N
     x 3 RGB array.

‘extent’ (read-only): four-element vector
     Size of the text string associated to the uicontrol returned in the
     form ‘[0 0 width height]’ (the two first elements are always zero).

     For multi-line strings the returned ‘width’ and ‘height’ indicate
     the size of the rectangle enclosing all lines.

‘foregroundcolor’: colorspec, def. ‘[0 0 0]’
     The color value of the text for this control object.  *Note
     colorspec: Colors.

‘style’: "checkbox" | "edit" | "frame" | "listbox" | "popupmenu" | {"pushbutton"} | "radiobutton" | "slider" | "text" | "togglebutton"
     The type of control object created.  For a complete description of
     available control styles, see the *note "uicontrol" function:
     XREFuicontrol.

Callback Execution
..................

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object's callback
     properties when it is unable to interrupt another object's
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘callback’: string, def. ‘[](0x0)’
     A string consisting of a valid Octave expression that will be
     executed whenever this control is activated.

‘interruptible’: "off" | {"on"}
     Specify whether this object's callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘keypressfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed when a key is pressed while the
     uicontrol object has focus.  The first argument to the function is
     the handle of the calling uicontrol.  The second argument holds an
     event structure which has the following members:
     ‘Character:’
          The ASCII value of the key
     ‘Modifier:’
          A cell array containing strings representing the modifiers
          pressed with the key.
     ‘Key:’
          Lowercase description of the key
     ‘Source:’
          Graphics handle of the object executing the callback function
     ‘EventName:’
          "KeyPress"

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Control Options
...............

‘enable’: "inactive" | "off" | {"on"}
     Sets whether this control object is active or is grayed out.

‘listboxtop’: scalar, def. ‘1’
     The index of the string option that will appear at the top of
     "listbox" controls

‘max’: scalar, def. ‘1’
     The maximum control value, whose effect on the control is dependent
     on the control type.  For "checkbox", "togglebutton", and
     "radiobutton" controls, the "max" value is assigned to the "value"
     property when the control object is selected.  For "slider"
     controls, "max" defines the maximum value of the slider.  For
     "edit" and "listbox" controls, if ‘Max - Min > 1’, then the control
     will permit multiple line entries or list item selections,
     respectively.

‘min’: scalar, def. ‘0’
     The minimum control value, whose effect on the control is dependent
     on the control type.  For "checkbox", "togglebutton", and
     "radiobutton" controls, the "min" value is assigned to the "value"
     property when the control object is not selected.  For "slider"
     controls, "min" defines the minimum value of the slider.  For
     "edit" and "listbox" controls, if ‘Max - Min > 1’, then the control
     will permit multiple line entries or list item selections,
     respectively.

‘sliderstep’: two-element vector, def. ‘[0.010000 0.100000]’
     The fractional step size, measured relative to the ‘Min - Max’ span
     of the slider, that the slider moves when the user clicks on the
     object.  "sliderstep" is specified as a two-element vector
     consisting of ‘[minor major]’, where "minor" is the step size for
     clicking on the slider arrows, and "major" is the step size for
     clicking within the slider bar.

‘value’: scalar, def. ‘0’
     A numerical value associated with the current state of the control
     object, with the meaning of the value dependent on the "style" of
     the control object.

Creation/Deletion
.................

‘beingdeleted’: {"off"} | "on"
     Property indicating that a function has initiated deletion of the
     object.  ‘beingdeleted’ is set to true until the object no longer
     exists.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uicontrol has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuicontrolcreatefcn", 'disp ("uicontrol
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uicontrol is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Display
.......

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uicontrol is clipped in its parent axes
     limits.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uicontrol is not rendered on screen.

Mouse Interaction
.................

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uicontrol object.

‘hittest’: "off" | {"on"}
     Specify whether uicontrol processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuicontrolpickableparts.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uicontrol will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the
     uicontrol or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuicontrolhittest.

‘selected’: {"off"} | "on"
     Property indicates whether this uicontrol is selected.

‘selectionhighlight’: "off" | {"on"}
     If ‘selectionhighlight’ is "on", then the uicontrol's selection
     state is visually highlighted.

‘tooltipstring’: string, def. ""
     A text string that appears in a tooltip when the mouse pointer
     hovers over the control object.

Object Identification
.....................

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uicontrol".

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

Object Position
...............

‘position’: four-element vector, def. ‘[0 0 80 30]’
     Size of the control object represented as the four-element vector
     [left, bottom, width, height].

‘units’: "centimeters" | "characters" | "inches" | "normalized" | {"pixels"} | "points"
     Unit of measurement used to interpret the "position" property.

Parent/Children
...............

‘children’ (read-only): vector of graphics handles, def. ‘[](0x0)’
     Graphics handles of the uicontrol's children.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uicontrol's handle is not
     visible in its parent's "children" property.

‘parent’: graphics handle
     Handle of the parent graphics object.

Text Appearance
...............

‘fontangle’: "italic" | {"normal"}
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

     Programming Note: On systems that don’t use FontConfig natively
     (all but Linux), the font cache is built when Octave is installed.
     You will need to run ‘system ("fc-cache -fv")’ manually after
     installing new fonts.

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFuicontrolfontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | {"normal"}
     Control the variant of the base font used for text rendering.

‘horizontalalignment’: {"center"} | "left" | "right"
     Specifies the horizontal justification of the text within the
     uicontrol object.

‘string’: string, def. ""
     The text appearing with the control object.

‘verticalalignment’: "bottom" | {"middle"} | "top"
     Specifies the vertical position of the text in the uicontrol
     object.


File: octave.info,  Node: Uitable Properties,  Next: Uitoolbar Properties,  Prev: Uicontrol Properties,  Up: Graphics Object Properties

15.3.3.17 Uitable Properties
............................

Properties of ‘uitable’ objects (*note uitable: XREFuitable.):

Categories:
...........

*note Appearance: XREFuitablecategoryAppearance. | *note
Callback Execution: XREFuitablecategoryCallbackExecution. | *note
Creation/Deletion: XREFuitablecategoryCreation/Deletion. | *note
Display: XREFuitablecategoryDisplay. | *note Mouse Interaction:
XREFuitablecategoryMouseInteraction. | *note Object Identification:
XREFuitablecategoryObjectIdentification. | *note Object Position:
XREFuitablecategoryObjectPosition. | *note Parent/Children:
XREFuitablecategoryParent/Children. | *note Table Data:
XREFuitablecategoryTableData. | *note Table Operation:
XREFuitablecategoryTableOperation. | *note Text Appearance:
XREFuitablecategoryTextAppearance.

Appearance
..........

‘backgroundcolor’: colorspec, def. 2-by-3 double
     Color of the background of the table specified as a 3-element RBG
     vector.  If ‘backgroundcolor’ has multiple rows, the colors cycle
     repeatedly if the *note "rowstriping" property:
     XREFuitablerowstriping. is on.

‘foregroundcolor’: colorspec, def. ‘[0 0 0]’
     Color of the data text in this table.  *Note colorspec: Colors.

‘rowstriping’: "off" | {"on"}
     Setting to indicate whether the table background color will use
     different colors for each row.  Colors are drawn from the *note
     "backgroundcolor" property: XREFuitablebackgroundcolor. in a
     repeating pattern.

Callback Execution
..................

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object's callback
     properties when it is unable to interrupt another object's
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘celleditcallback’: string, def. ‘[](0x0)’
     A string consisting of a valid Octave expression that will be
     executed whenever a table cell is edited.

‘cellselectioncallback’: string, def. ‘[](0x0)’
     A string consisting of a valid Octave expression that will be
     executed whenever a table cell is selected.

‘interruptible’: "off" | {"on"}
     Specify whether this object's callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘keypressfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed when a key is pressed while the table
     object has focus.  The first argument to the function is the handle
     of the calling table.  The second argument holds an event structure
     which has the following members:
     ‘Character:’
          The ASCII value of the key
     ‘Modifier:’
          A cell array containing strings representing the modifiers
          pressed with the key.
     ‘Key:’
          Lowercase description of the key
     ‘Source:’
          Graphics handle of the object executing the callback function
     ‘EventName:’
          "KeyPress"

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘keyreleasefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed when a key is released while the table
     object has focus.  The first argument to the function is the handle
     of the calling table.  The second argument holds an event structure
     which has the following members:
     ‘Character:’
          The ASCII value of the key
     ‘Modifier:’
          A cell array containing strings representing the modifiers
          pressed with the key.
     ‘Key:’
          Lowercase description of the key
     ‘Source:’
          Graphics handle of the object executing the callback function
     ‘EventName:’
          "KeyRelease"

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Creation/Deletion
.................

‘beingdeleted’: {"off"} | "on"
     Property indicating that a function has initiated deletion of the
     object.  ‘beingdeleted’ is set to true until the object no longer
     exists.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uitable has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuitablecreatefcn", 'disp ("uitable
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uitable is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Display
.......

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uitable is clipped in its parent axes
     limits.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uitable is not rendered on screen.

Mouse Interaction
.................

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uitable object.

‘hittest’: "off" | {"on"}
     Specify whether uitable processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuitablepickableparts.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uitable will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the uitable
     or its children may react to mouse clicks.  When ‘pickableparts’ is
     "all" both visible and invisible parts (or children) may react to
     mouse clicks.  When ‘pickableparts’ is "none" mouse clicks on the
     object are ignored and transmitted to any objects underneath this
     one.  When an object is configured to accept mouse clicks the
     "hittest" property will determine how they are processed.  *Note
     hittest property: XREFuitablehittest.

‘selected’: {"off"} | "on"
     Property indicates whether this uitable is selected.

‘selectionhighlight’: "off" | {"on"}
     If ‘selectionhighlight’ is "on", then the uitable's selection state
     is visually highlighted.

‘tooltipstring’: string, def. ""
     A text string that appears in a tooltip when the mouse pointer
     hovers over the table object.

Object Identification
.....................

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uitable".

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

Object Position
...............

‘extent’ (read-only): four-element vector
     A four-element vector indicating the size of the table.  The first
     two elements of the array are always zero, while the third and
     fourth elements contain the height and width of the table.

‘position’: four-element vector, def. ‘[20 20 300 300]’
     The position and size of the table.  The four elements of the
     vector are the coordinates of the lower left corner and width and
     height of the figure.  *Note units property: XREFuitableunits.

‘units’: "centimeters" | "characters" | "inches" | "normalized" | {"pixels"} | "points"
     Unit of measurement used to interpret the "position" property.

Parent/Children
...............

‘children’ (read-only): vector of graphics handles, def. ‘[](0x0)’
     Graphics handles of the uitable's children.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uitable's handle is not visible
     in its parent's "children" property.

‘parent’: graphics handle
     Handle of the parent graphics object.

Table Data
..........

‘columnformat’: def. ‘{}(0x0)’
     The display format for numeric data in each column.  Valid formats
     include "char", "logical", "numeric", or a valid format setting
     from the *note format function: XREFformat.

‘columnname’: def. "numbered"
     Column names specified as either "numbered" or a 1 x N cell string
     vector containing the names to be used for each column heading.

‘columnwidth’: def. "auto"
     Setting for determining width of each column, valid options
     include: "auto", "fit", evenly divided multiples specified as "1x",
     "2x", etc., or a 1 x N cell vector where each element corresponds
     to one of N table columns, and contains any of the above string
     options or a fixed width specified in pixels.  The "1x" property is
     not yet implemented.

‘data’: matrix, def. ‘[](0x0)’
     The data contained in the table specified as either a 2-D numeric,
     logical, or cell array.

‘rowname’: def. "numbered"
     Row names specified as either "numbered" or a N x 1 cell string
     vector containing the names to be used for each row heading.

Table Operation
...............

‘columneditable’: logical row vector, def. ‘[](0x0)’
     A logical indicator of whether the columns are editable.  It
     consists of either a 1 x N vector of logical values where true or
     false indicate the corresponding column is or is not editable,
     respectively, or an empty logical array indicating that no column
     is editable.

‘enable’: "off" | {"on"}
     Sets whether this table object is active or is grayed out.

‘rearrangeablecolumns’: {"off"} | "on"
     Indicates whether or not the ability to move columns by clicking
     and dragging the column headers.

Text Appearance
...............

‘fontangle’: "italic" | {"normal"}
     Control whether the font is italic or normal.

‘fontname’: string, def. "*"
     Name of font used for text rendering.  When setting this property,
     the text rendering engine will search for a matching font in your
     system.  If none is found then text is rendered using a default
     sans serif font (same as the default "*" value).

     Programming Note: On systems that don’t use FontConfig natively
     (all but Linux), the font cache is built when Octave is installed.
     You will need to run ‘system ("fc-cache -fv")’ manually after
     installing new fonts.

‘fontsize’: scalar, def. ‘10’
     Size of the font used for text rendering.  *Note fontunits
     property: XREFuitablefontunits.

‘fontunits’: "centimeters" | "inches" | "normalized" | "pixels" | {"points"}
     Units used to interpret the "fontsize" property.

‘fontweight’: "bold" | {"normal"}
     Control the variant of the base font used for text rendering.


File: octave.info,  Node: Uitoolbar Properties,  Next: Uipushtool Properties,  Prev: Uitable Properties,  Up: Graphics Object Properties

15.3.3.18 Uitoolbar Properties
..............................

Properties of ‘uitoolbar’ objects (*note uitoolbar: XREFuitoolbar.):

Categories:
...........

*note Callback Execution: XREFuitoolbarcategoryCallbackExecution. |
*note Creation/Deletion: XREFuitoolbarcategoryCreation/Deletion. | *note
Display: XREFuitoolbarcategoryDisplay. | *note Mouse Interaction:
XREFuitoolbarcategoryMouseInteraction. | *note Object Identification:
XREFuitoolbarcategoryObjectIdentification. | *note Parent/Children:
XREFuitoolbarcategoryParent/Children.

Callback Execution
..................

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object's callback
     properties when it is unable to interrupt another object's
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘interruptible’: "off" | {"on"}
     Specify whether this object's callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

Creation/Deletion
.................

‘beingdeleted’: {"off"} | "on"
     Property indicating that a function has initiated deletion of the
     object.  ‘beingdeleted’ is set to true until the object no longer
     exists.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uitoolbar has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuitoolbarcreatefcn", 'disp ("uitoolbar
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uitoolbar is deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Display
.......

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uitoolbar is clipped in its parent axes
     limits.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uitoolbar is not rendered on screen.

Mouse Interaction
.................

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uitoolbar object.

‘hittest’: "off" | {"on"}
     Specify whether uitoolbar processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuitoolbarpickableparts.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uitoolbar will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the
     uitoolbar or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuitoolbarhittest.

‘selected’: {"off"} | "on"
     Property indicates whether this uitoolbar is selected.

‘selectionhighlight’: "off" | {"on"}
     If ‘selectionhighlight’ is "on", then the uitoolbar's selection
     state is visually highlighted.

Object Identification
.....................

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uitoolbar".

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

Parent/Children
...............

‘children’ (read-only): vector of graphics handles, def. ‘[](0x0)’
     Graphics handles of the uitoolbar's children.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uitoolbar's handle is not
     visible in its parent's "children" property.

‘parent’: graphics handle
     Handle of the parent graphics object.


File: octave.info,  Node: Uipushtool Properties,  Next: Uitoggletool Properties,  Prev: Uitoolbar Properties,  Up: Graphics Object Properties

15.3.3.19 Uipushtool Properties
...............................

Properties of ‘uipushtool’ objects (*note uipushtool: XREFuipushtool.):

Categories:
...........

*note Appearance: XREFuipushtoolcategoryAppearance. | *note
Callback Execution: XREFuipushtoolcategoryCallbackExecution. | *note
Creation/Deletion: XREFuipushtoolcategoryCreation/Deletion. | *note
Display: XREFuipushtoolcategoryDisplay. | *note Mouse Interaction:
XREFuipushtoolcategoryMouseInteraction. | *note Object Identification:
XREFuipushtoolcategoryObjectIdentification. | *note Parent/Children:
XREFuipushtoolcategoryParent/Children. | *note Pushtool Operation:
XREFuipushtoolcategoryPushtoolOperation.

Appearance
..........

‘__named_icon__’: string, def. ""
     The name of an bundled icon file to use as the image for the
     pushtool object.

‘cdata’: array, def. ‘[](0x0)’
     Image data used to represent the pushtool object, stored as a M x N
     x 3 RGB array.

‘separator’: {"off"} | "on"
     State indicating whether a separator line will be drawn next to the
     current pushtool position.

Callback Execution
..................

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object's callback
     properties when it is unable to interrupt another object's
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘clickedcallback’: string, def. ‘[](0x0)’
     A string consisting of a valid Octave expression that will be
     executed whenever this control object is clicked.

‘interruptible’: "off" | {"on"}
     Specify whether this object's callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

Creation/Deletion
.................

‘beingdeleted’: {"off"} | "on"
     Property indicating that a function has initiated deletion of the
     object.  ‘beingdeleted’ is set to true until the object no longer
     exists.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uipushtool has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuipushtoolcreatefcn", 'disp ("uipushtool
     created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uipushtool is
     deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Display
.......

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uipushtool is clipped in its parent axes
     limits.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uipushtool is not rendered on screen.

Mouse Interaction
.................

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uipushtool object.

‘hittest’: "off" | {"on"}
     Specify whether uipushtool processes mouse events or passes them to
     ancestors of the object.  When enabled, the object may respond to
     mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuipushtoolpickableparts.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uipushtool will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the
     uipushtool or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuipushtoolhittest.

‘selected’: {"off"} | "on"
     Property indicates whether this uipushtool is selected.

‘selectionhighlight’: "off" | {"on"}
     If ‘selectionhighlight’ is "on", then the uipushtool's selection
     state is visually highlighted.

‘tooltipstring’: string, def. ""
     A text string that appears in a tooltip when the mouse pointer
     hovers over the pushtool object.

Object Identification
.....................

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always "uipushtool".

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

Parent/Children
...............

‘children’ (read-only): vector of graphics handles, def. ‘[](0x0)’
     Graphics handles of the uipushtool's children.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uipushtool's handle is not
     visible in its parent's "children" property.

‘parent’: graphics handle
     Handle of the parent graphics object.

Pushtool Operation
..................

‘enable’: "off" | {"on"}
     Sets whether this pushtool object is active or is grayed out.


File: octave.info,  Node: Uitoggletool Properties,  Prev: Uipushtool Properties,  Up: Graphics Object Properties

15.3.3.20 Uitoggletool Properties
.................................

Properties of ‘uitoggletool’ objects (*note uitoggletool:
XREFuitoggletool.):

Categories:
...........

*note Appearance: XREFuitoggletoolcategoryAppearance. | *note
Callback Execution: XREFuitoggletoolcategoryCallbackExecution. | *note
Creation/Deletion: XREFuitoggletoolcategoryCreation/Deletion. | *note
Display: XREFuitoggletoolcategoryDisplay. | *note Mouse Interaction:
XREFuitoggletoolcategoryMouseInteraction. | *note Object Identification:
XREFuitoggletoolcategoryObjectIdentification. | *note Parent/Children:
XREFuitoggletoolcategoryParent/Children. | *note Toggle Operation:
XREFuitoggletoolcategoryToggleOperation.

Appearance
..........

‘__named_icon__’: string, def. ""
     The name of an bundled icon file to use as the image for the
     toggletool object.

‘cdata’: array, def. ‘[](0x0)’
     Image data used to represent the toggletool object, stored as a M x
     N x 3 RGB array.

‘separator’: {"off"} | "on"
     Setting to draw a vertical line to the left of the toggletool.

Callback Execution
..................

‘busyaction’: "cancel" | {"queue"}
     Define how Octave handles the execution of this object's callback
     properties when it is unable to interrupt another object's
     executing callback.  This is only relevant when the currently
     executing callback object has its ‘interruptible’ property set to
     "off".  The ‘busyaction’ property of the interrupting callback
     object indicates whether the interrupting callback is queued
     ("queue" (default)) or discarded ("cancel").  *Note
     Callbacks section: Callbacks.

‘clickedcallback’: string, def. ‘[](0x0)’
     A string consisting of a valid Octave expression that will be
     executed whenever this control object is clicked.

‘interruptible’: "off" | {"on"}
     Specify whether this object's callback functions may be interrupted
     by other callbacks.  By default ‘interruptible’ is "on" and
     callbacks that make use of ‘drawnow’, ‘figure’, ‘waitfor’,
     ‘getframe’ or ‘pause’ functions are eventually interrupted.  *Note
     Callbacks section: Callbacks.

‘offcallback’: string, def. ‘[](0x0)’
     A string consisting of a valid Octave expression that will be
     executed whenever this control object is toggled off.

‘oncallback’: string, def. ‘[](0x0)’
     A string consisting of a valid Octave expression that will be
     executed whenever this control object is toggled on.

Creation/Deletion
.................

‘beingdeleted’: {"off"} | "on"
     Property indicating that a function has initiated deletion of the
     object.  ‘beingdeleted’ is set to true until the object no longer
     exists.

‘createfcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately after uitoggletool has been
     created.  Function is set by using default property on root object,
     e.g., ‘set (groot, "defaultuitoggletoolcreatefcn", 'disp
     ("uitoggletool created!")')’.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

‘deletefcn’: string | function handle, def. ‘[](0x0)’
     Callback function executed immediately before uitoggletool is
     deleted.

     For information on how to write graphics listener functions see
     *note Callbacks section: Callbacks.

Display
.......

‘clipping’: "off" | {"on"}
     If ‘clipping’ is "on", the uitoggletool is clipped in its parent
     axes limits.

‘visible’: "off" | {"on"}
     If ‘visible’ is "off", the uitoggletool is not rendered on screen.

Mouse Interaction
.................

‘buttondownfcn’: string | function handle, def. ‘[](0x0)’
     ‘buttondownfcn’ is unused.

‘contextmenu’: graphics handle, def. ‘[](0x0)’
     Graphics handle of the uicontextmenu object that is currently
     associated to this uitoggletool object.

‘hittest’: "off" | {"on"}
     Specify whether uitoggletool processes mouse events or passes them
     to ancestors of the object.  When enabled, the object may respond
     to mouse clicks by evaluating the "buttondownfcn", showing the
     uicontextmenu, and eventually becoming the root "currentobject".
     This property is only relevant when the object can accept mouse
     clicks which is determined by the "pickableparts" property.  *Note
     pickableparts property: XREFuitoggletoolpickableparts.

‘pickableparts’: "all" | "none" | {"visible"}
     Specify whether uitoggletool will accept mouse clicks.  By default,
     ‘pickableparts’ is "visible" and only visible parts of the
     uitoggletool or its children may react to mouse clicks.  When
     ‘pickableparts’ is "all" both visible and invisible parts (or
     children) may react to mouse clicks.  When ‘pickableparts’ is
     "none" mouse clicks on the object are ignored and transmitted to
     any objects underneath this one.  When an object is configured to
     accept mouse clicks the "hittest" property will determine how they
     are processed.  *Note hittest property: XREFuitoggletoolhittest.

‘selected’: {"off"} | "on"
     Property indicates whether this uitoggletool is selected.

‘selectionhighlight’: "off" | {"on"}
     If ‘selectionhighlight’ is "on", then the uitoggletool's selection
     state is visually highlighted.

‘tooltipstring’: string, def. ""
     A text string that appears in a tooltip when the mouse pointer
     hovers over the toggletool object.

Object Identification
.....................

‘tag’: string, def. ""
     A user-defined string to label the graphics object.

‘type’ (read-only): string
     Class name of the graphics object.  ‘type’ is always
     "uitoggletool".

‘userdata’: Any Octave data, def. ‘[](0x0)’
     User-defined data to associate with the graphics object.

Parent/Children
...............

‘children’ (read-only): vector of graphics handles, def. ‘[](0x0)’
     Graphics handles of the uitoggletool's children.

‘handlevisibility’: "callback" | "off" | {"on"}
     If ‘handlevisibility’ is "off", the uitoggletool's handle is not
     visible in its parent's "children" property.

‘parent’: graphics handle
     Handle of the parent graphics object.

Toggle Operation
................

‘enable’: "off" | {"on"}
     Sets whether this toggletool object is active or is grayed out.

‘state’: {"off"} | "on"
     The current "on" or "off" state of the toggletool object.


File: octave.info,  Node: Searching Properties,  Next: Managing Default Properties,  Prev: Graphics Object Properties,  Up: Graphics Data Structures

15.3.4 Searching Properties
---------------------------

 -- : H = findobj ()
 -- : H = findobj (PROP_NAME, PROP_VALUE, ...)
 -- : H = findobj (PROP_NAME, PROP_VALUE, "-LOGICAL_OP", PROP_NAME,
          PROP_VALUE)
 -- : H = findobj ("-property", PROP_NAME)
 -- : H = findobj ("-regexp", PROP_NAME, PATTERN)
 -- : H = findobj (HLIST, ...)
 -- : H = findobj (HLIST, "flat", ...)
 -- : H = findobj (HLIST, "-depth", D, ...)
     Find graphics objects with specified properties.

     When called without arguments, return all graphic objects beginning
     with the root object (0) and including all of its descendants.

     The simplest form for narrowing the results is

          findobj (PROP_NAME, PROP_VALUE)

     which returns the handles of all objects which have a property
     named PROP_NAME that has the value PROP_VALUE.  If multiple
     property/value pairs are specified then only objects meeting all of
     the conditions (equivalent to ‘-and’) are returned.

     The search can be limited to a particular set of objects and their
     descendants, by passing a handle or set of handles HLIST as the
     first argument.

     The depth of the object hierarchy to search can be limited with the
     "-depth" argument.  An example of searching through only three
     generations of children is:

          findobj (HLIST, "-depth", 3, PROP_NAME, PROP_VALUE)

     Specifying a depth D of 0 limits the search to the set of objects
     passed in HLIST.  A depth of 0 is also equivalent to the "flat"
     argument.  The default depth value is ‘Inf’ which includes all
     descendants.

     A specified logical operator may be used between PROP_NAME,
     PROP_VALUE pairs.  The supported logical operators are: "-and",
     "-or", "-xor", "-not".  Example code to locate all figure and axes
     objects is

          findobj ("type", "figure", "-or", "type", "axes")

     Objects may also be matched by comparing a regular expression to
     the property values, where property values that match ‘regexp
     (PROP_VALUE, PATTERN)’ are returned.

     Finally, objects which have a property name can be found with the
     "-property" option.  For example, code to locate objects with a
     "meshstyle" property is

          findobj ("-property", "meshstyle")

     Implementation Note: The search only includes objects with visible
     handles (HandleVisibility = "on").  *Note ‘findall’: XREFfindall,
     to search for all objects including hidden ones.

     See also: *note findall: XREFfindall, *note allchild: XREFallchild,
     *note get: XREFget, *note set: XREFset.

 -- : H = findall ()
 -- : H = findall (PROP_NAME, PROP_VALUE, ...)
 -- : H = findall (PROP_NAME, PROP_VALUE, "-LOGICAL_OP", PROP_NAME,
          PROP_VALUE)
 -- : H = findall ("-property", PROP_NAME)
 -- : H = findall ("-regexp", PROP_NAME, PATTERN)
 -- : H = findall (HLIST, ...)
 -- : H = findall (HLIST, "flat", ...)
 -- : H = findall (HLIST, "-depth", D, ...)
     Find graphics object, including hidden ones, with specified
     properties.

     The return value H is a list of handles to the found graphic
     objects.

     ‘findall’ performs the same search as ‘findobj’, but it includes
     hidden objects (HandleVisibility = "off").  For full documentation,
     *note ‘findobj’: XREFfindobj.

     See also: *note findobj: XREFfindobj, *note allchild: XREFallchild,
     *note get: XREFget, *note set: XREFset.


File: octave.info,  Node: Managing Default Properties,  Prev: Searching Properties,  Up: Graphics Data Structures

15.3.5 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, of the specified object type.
For example, setting the default ‘color’ property of ‘line’ objects to
"green", for the ‘root’ object, will result in all ‘line’ objects
inheriting the ‘color’ "green" as the default value.

     set (groot, "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 object 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 object.  Likewise, defaults set in an axes object override
those set in figure or root objects.  For example,

     subplot (2, 1, 1);
     set (groot, "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 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.  To quickly remove all user-defined defaults use the
‘reset’ function.

 By default, high level plotting functions such as ‘plot’ reset and
redefine axes properties independently from the defaults.  An example of
such property is the axes ‘box’ property: it is set ‘on’ by high level
2-D graphics functions regardless of the property "defaultaxesbox".  Use
the ‘hold’ function to prevent this behavior:

     set (groot, "defaultaxesbox", "off");
     subplot (2, 1, 1);
     plot (1:10)
     title ("Box is on anyway")
     subplot (2, 1, 2);
     hold on
     plot (1:10)
     title ("Box is off")

 -- : reset (H)
     Reset the properties of the graphic object H to their default
     values.

     For figures, the properties "position", "units", "windowstyle", and
     "paperunits" are not affected.  For axes, the properties "position"
     and "units" are not affected.

     The input H may also be a vector of graphic handles in which case
     each individual object will be reset.

     See also: *note cla: XREFcla, *note clf: XREFclf, *note newplot:
     XREFnewplot.

 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 object.  The command

     get (groot, "factory");

returns a list of factory defaults.


File: octave.info,  Node: Advanced Plotting,  Prev: Graphics Data Structures,  Up: Plotting

15.4 Advanced Plotting
======================

* Menu:

* Colors::
* Line Styles::
* Marker Styles::
* Callbacks::
* Application-defined Data::
* Object Groups::
* Transform Groups::
* Graphics Toolkits::


File: octave.info,  Node: Colors,  Next: Line Styles,  Up: Advanced Plotting

15.4.1 Colors
-------------

Colors may be specified in three ways: 1) RGB triplets, 2) by name, or
3) by HTML notation.

RGB triplet

     An RGB triplet is a 1x3 vector where each value is between 0 and 1
     inclusive.  The first value represents the percentage of Red, the
     second value the percentage of Green, and the third value the
     percentage of Blue.  For example, ‘[1, 0, 1]’ represents full Red
     and Blue channels resulting in the color magenta.

short or long name

     Eight colors can be specified directly by name or by a single
     character short name.

     Name            Color
     --------------------------------------------------------------------------
     ‘k’, "black"    blacK
     ‘r’, "red"      Red
     ‘g’, "green"    Green
     ‘b’, "blue"     Blue
     ‘y’, "yellow"   Yellow
     ‘m’,            Magenta
     "magenta"
     ‘c’, "cyan"     Cyan
     ‘w’, "white"    White

HTML notation

     HTML notation is a string that begins with the character ‘#’ and is
     followed by either 3 or 6 hexadecimal digits.  As with RGB
     triplets, each hexadecimal number represents the fraction of the
     Red, Green, and Blue channels present in the specified color.  For
     example, "#FF00FF" represents the color magenta.


File: octave.info,  Node: Line Styles,  Next: Marker Styles,  Prev: Colors,  Up: Advanced Plotting

15.4.2 Line Styles
------------------

Line styles are specified by the following properties:

‘linestyle’
     May be one of

     "-"
          Solid line.  [default]

     "-"
          Dashed line.

     ":"
          Dotted line.

     "-."
          A dash-dot line.

     "none"
          No line.  Points will still be marked using the current Marker
          Style.

‘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.


File: octave.info,  Node: Marker Styles,  Next: Callbacks,  Prev: Line Styles,  Up: Advanced Plotting

15.4.3 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.  *Note Colors::.

‘markerfacecolor’
     The color of the marker, or "none" to indicate that the marker
     should not be filled.  *Note 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.

 The ‘colstyle’ function will parse a ‘plot’-style specification and
will return the color, line, and marker values that would result.

 -- : [STYLE, COLOR, MARKER, MSG] = colstyle (STYLE)
     Parse the line specification STYLE and return the line style,
     color, and markers given.

     In the case of an error, the string MSG will return the text of the
     error.


File: octave.info,  Node: Callbacks,  Next: Application-defined Data,  Prev: Marker Styles,  Up: Advanced Plotting

15.4.4 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 (hsrc, evt)
       ...
     endfunction

where ‘hsrc’ is a handle to the source of the callback, and ‘evt’ gives
some event specific data.

 The function can be provided as a function handle to a plain Octave
function, as an anonymous function, or as a string representing an
Octave command.  The latter syntax is not recommended since syntax
errors will only occur when the string is evaluated.  *Note Function
Handles section: Function Handles and Anonymous Functions.

 This can then be associated with an object either at the object's
creation, or later with the ‘set’ function.  For example,

     plot (x, "DeleteFcn", @(h, 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 two default arguments.  For example:

     plot (x, "DeleteFcn", {@mycallback, "1"})
     ...
     function mycallback (h, evt, arg1)
       fprintf ("Closing plot %d\n", arg1);
     endfunction

 *Caution:* The second argument in callback functions--‘evt’--is only
partially implemented in the Qt graphics toolkit:

   • Mouse click events: ‘evt’ is a class ‘double’ value: 1 for left, 2
     for middle, and 3 for right click.

   • Key press events: ‘evt’ is a structure with fields ‘Key’ (string),
     ‘Character’ (string), and ‘Modifier’ (cell array of strings).

   • Other events: ‘evt’ is a class ‘double’ empty matrix.

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

   • CreateFcn: 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: called at the moment an object is deleted.

   • ButtonDownFcn: called if a mouse button is pressed while the
     pointer is over this object.  Note, that the gnuplot interface does
     not implement this callback.

 By default callback functions are queued (they are executed one after
the other in the event queue) unless the ‘drawnow’, ‘figure’, ‘waitfor’,
‘getframe’, or ‘pause’ functions are used.  If an executing callback
invokes one of those functions, it causes Octave to flush the event
queue, which results in the executing callback being interrupted.

 It is possible to specify that an object's callbacks should not be
interrupted by setting the object's ‘interruptible’ property to "off".
In this case, Octave decides what to do based on the ‘busyaction’
property of the *interrupting* callback object:

‘queue’ (the default)
     The interrupting callback is executed after the executing callback
     has returned.

‘cancel’
     The interrupting callback is discarded.

 The ‘interruptible’ property has no effect when the interrupting
callback is a ‘deletefcn’, or a figure ‘resizefcn’ or ‘closerequestfcn’.
Those callbacks always interrupt the executing callback.

 The handle to the object that holds the callback being executed can be
obtained with the ‘gcbo’ function.  The handle to the ancestor figure of
this object may be obtained using the ‘gcbf’ function.

 -- : H = gcbo ()
 -- : [H, FIG] = gcbo ()
     Return a handle to the object whose callback is currently
     executing.

     If no callback is executing, this function returns the empty
     matrix.  This handle is obtained from the root object property
     "CallbackObject".

     When called with a second output argument, return the handle of the
     figure containing the object whose callback is currently executing.
     If no callback is executing the second output is also set to the
     empty matrix.

     See also: *note gcbf: XREFgcbf, *note gco: XREFgco, *note gca:
     XREFgca, *note gcf: XREFgcf, *note get: XREFget, *note set:
     XREFset.

 -- : FIG = gcbf ()
     Return a handle to the figure containing the object whose callback
     is currently executing.

     If no callback is executing, this function returns the empty
     matrix.  The handle returned by this function is the same as the
     second output argument of ‘gcbo’.

     See also: *note gcbo: XREFgcbo, *note gcf: XREFgcf, *note gco:
     XREFgco, *note gca: XREFgca, *note get: XREFget, *note set:
     XREFset.

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


File: octave.info,  Node: Application-defined Data,  Next: Object Groups,  Prev: Callbacks,  Up: Advanced Plotting

15.4.5 Application-defined Data
-------------------------------

Octave has a provision for attaching application-defined data to a
graphics handle.  The data can be anything which is meaningful to the
application, and will be completely ignored by Octave.

 -- : setappdata (H, NAME, VALUE)
 -- : setappdata (H, NAME1, VALUE1, NAME2, VALUE2, ...)
 -- : setappdata (H, {NAME1, NAME2, ...}, {VALUE1, VALUE2, ...})
     Set the application data NAME to VALUE for the graphics object with
     handle H.

     H may also be a vector of graphics handles.  If the application
     data with the specified NAME does not exist, it is created.

     Multiple NAME/VALUE pairs can be specified.  Alternatively, a cell
     array of NAMES and a corresponding cell array of VALUES can be
     specified.  For details on obtaining a list of valid application
     data properties, *note ‘getappdata’: XREFgetappdata.

     See also: *note getappdata: XREFgetappdata, *note isappdata:
     XREFisappdata, *note rmappdata: XREFrmappdata, *note guidata:
     XREFguidata, *note get: XREFget, *note set: XREFset, *note getpref:
     XREFgetpref, *note setpref: XREFsetpref.

 -- : VALUE = getappdata (H, NAME)
 -- : APPDATA = getappdata (H)
     Return the VALUE of the application data NAME for the graphics
     object with handle H.

     H may also be a vector of graphics handles.  If no second argument
     NAME is given then ‘getappdata’ returns a structure, APPDATA, whose
     fields correspond to the appdata properties.

     See also: *note setappdata: XREFsetappdata, *note isappdata:
     XREFisappdata, *note rmappdata: XREFrmappdata, *note guidata:
     XREFguidata, *note get: XREFget, *note set: XREFset, *note getpref:
     XREFgetpref, *note setpref: XREFsetpref.

 -- : rmappdata (H, NAME)
 -- : rmappdata (H, NAME1, NAME2, ...)
     Delete the application data NAME from the graphics object with
     handle H.

     H may also be a vector of graphics handles.  Multiple application
     data names may be supplied to delete several properties at once.

     See also: *note setappdata: XREFsetappdata, *note getappdata:
     XREFgetappdata, *note isappdata: XREFisappdata.

 -- : VALID = isappdata (H, NAME)
     Return true if the named application data, NAME, exists for the
     graphics object with handle H.

     H may also be a vector of graphics handles.

     See also: *note getappdata: XREFgetappdata, *note setappdata:
     XREFsetappdata, *note rmappdata: XREFrmappdata, *note guidata:
     XREFguidata, *note get: XREFget, *note set: XREFset, *note getpref:
     XREFgetpref, *note setpref: XREFsetpref.


File: octave.info,  Node: Object Groups,  Next: Transform Groups,  Prev: Application-defined Data,  Up: Advanced Plotting

15.4.6 Object Groups
--------------------

A number of Octave high level plot functions return groups of other
graphics objects or they return graphics objects that 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 ()
 -- : hggroup (HAX)
 -- : hggroup (..., PROPERTY, VALUE, ...)
 -- : H = hggroup (...)
     Create handle graphics group object with axes parent HAX.

     If no parent is specified, the group is created in the current
     axes.

     Multiple property/value pairs may be specified for the hggroup, but
     they must appear in pairs.  The full list of properties is
     documented at *note Axes Properties::.

     The optional return value H is a graphics handle to the created
     hggroup object.

     Programming Note: An hggroup is a way to group base graphics
     objects such as line objects or patch objects into a single unit
     which can react appropriately.  For example, the individual lines
     of a contour plot are collected into a single hggroup so that they
     can be made visible/invisible with a single command, ‘set
     (hg_handle, "visible", "off")’.

     See also: *note addproperty: XREFaddproperty, *note addlistener:
     XREFaddlistener.

 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 (NAME, H, TYPE)
 -- : addproperty (NAME, H, TYPE, ARG, ...)
     Create a new property named NAME in graphics object H.

     TYPE determines the type of the property to create.  ARGS usually
     contains the default value of the property, but additional
     arguments might be given, depending on the type of the property.

     The supported property types are:

     ‘string’
          A string property.  ARG contains the default string value.

     ‘any’
          An un-typed property.  This kind of property can hold any
          octave value.  ARGS contains the default value.

     ‘radio’
          A string property with a limited set of accepted values.  The
          first argument must be a string with all accepted values
          separated by a vertical bar ('|').  The default value can be
          marked by enclosing it with a '{' '}' pair.  The default value
          may also be given as an optional second string argument.

     ‘boolean’
          A boolean property.  This property type is equivalent to a
          radio property with "on|off" as accepted values.  ARG contains
          the default property value.

     ‘double’
          A scalar double property.  ARG contains the default value.

     ‘handle’
          A handle property.  This kind of property holds the handle of
          a graphics object.  ARG contains the default handle value.
          When no default value is given, the property is initialized to
          the empty matrix.

     ‘data’
          A data (matrix) property.  ARG contains the default data
          value.  When no default value is given, the data is
          initialized to the empty matrix.

     ‘color’
          A color property.  ARG contains the default color value.  When
          no default color is given, the property is set to black.  An
          optional second string argument may be given to specify an
          additional set of accepted string values (like a radio
          property).

     TYPE may also be the concatenation of a core object type and a
     valid property name for that object type.  The property created
     then has the same characteristics as the referenced property (type,
     possible values, hidden state...).  This allows one to clone an
     existing property into the graphics object H.

     Examples:

          addproperty ("my_property", gcf, "string", "a string value");
          addproperty ("my_radio", gcf, "radio", "val_1|val_2|{val_3}");
          addproperty ("my_style", gcf, "linelinestyle", "--");

     See also: *note addlistener: XREFaddlistener, *note hggroup:
     XREFhggroup.

 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 (H, PROP, FCN)
     Register FCN as listener for the property PROP of the graphics
     object H.

     Property listeners are executed (in order of registration) when the
     property is set.  The new value is already available when the
     listeners are executed.

     PROP must be a string naming a valid property in H.

     FCN can be a function handle, a string or a cell array whose first
     element is a function handle.  If FCN is a function handle, the
     corresponding function should accept at least 2 arguments, that
     will be set to the object handle and the empty matrix respectively.
     If FCN is a string, it must be any valid octave expression.  If FCN
     is a cell array, the first element must be a function handle with
     the same signature as described above.  The next elements of the
     cell array are passed as additional arguments to the function.

     Example:

          function my_listener (h, dummy, p1)
            fprintf ("my_listener called with p1=%s\n", p1);
          endfunction

          addlistener (gcf, "position", {@my_listener, "my string"})

     See also: *note dellistener: XREFdellistener, *note addproperty:
     XREFaddproperty, *note hggroup: XREFhggroup.

 -- : dellistener (H, PROP, FCN)
     Remove the registration of FCN as a listener for the property PROP
     of the graphics object H.

     The function FCN must be the same variable (not just the same
     value), as was passed to the original call to ‘addlistener’.

     If FCN is not defined then all listener functions of PROP are
     removed.

     Example:

          function my_listener (h, dummy, p1)
            fprintf ("my_listener called with p1=%s\n", p1);
          endfunction

          c = {@my_listener, "my string"};
          addlistener (gcf, "position", c);
          dellistener (gcf, "position", c);

     See also: *note addlistener: XREFaddlistener.

 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");

 -- : HLINK = linkprop (H, "PROP")
 -- : HLINK = linkprop (H, {"PROP1", "PROP2", ...})
     Link graphic object properties, such that a change in one is
     propagated to the others.

     The input H is a vector of graphic handles to link.

     PROP may be a string when linking a single property, or a cell
     array of strings for multiple properties.  During the linking
     process all properties in PROP will initially be set to the values
     that exist on the first object in the list H.

     The function returns HLINK which is a special object describing the
     link.  As long as the reference HLINK exists, the link between
     graphic objects will be active.  This means that HLINK must be
     preserved in a workspace variable, a global variable, or otherwise
     stored using a function such as ‘setappdata’ or ‘guidata’.  To
     unlink properties, execute ‘clear HLINK’.

     An example of the use of ‘linkprop’ is

          x = 0:0.1:10;
          subplot (1,2,1);
          h1 = plot (x, sin (x));
          subplot (1,2,2);
          h2 = plot (x, cos (x));
          hlink = linkprop ([h1, h2], {"color","linestyle"});
          set (h1, "color", "green");
          set (h2, "linestyle", "--");

     See also: *note linkaxes: XREFlinkaxes, *note addlistener:
     XREFaddlistener.

 -- : linkaxes (HAX)
 -- : linkaxes (HAX, OPTSTR)
     Link the axis limits of 2-D plots such that a change in one is
     propagated to the others.

     The axes handles to be linked are passed as the first argument HAX.

     The optional second argument is a string which defines which axis
     limits will be linked.  The possible values for OPTSTR are:

     "x"
          Link x-axes

     "y"
          Link y-axes

     "xy" (default)
          Link both axes

     "off"
          Turn off linking

     If unspecified the default is to link both X and Y axes.

     When linking, the limits from the first axes in HAX are applied to
     the other axes in the list.  Subsequent changes to any one of the
     axes will be propagated to the others.

     See also: *note linkprop: XREFlinkprop, *note addproperty:
     XREFaddproperty.

 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.

* Menu:

* Data Sources in Object Groups::
* Area Series::
* Bar Series::
* Contour Groups::
* Error Bar Series::
* Line Series::
* Quiver Group::
* Stair Group::
* Stem Series::
* Surface Group::


File: octave.info,  Node: Data Sources in Object Groups,  Next: Area Series,  Up: Object Groups

15.4.6.1 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 ()
 -- : refreshdata (H)
 -- : refreshdata (H, WORKSPACE)
     Evaluate any ‘datasource’ properties of the current figure and
     update the plot if the corresponding data has changed.

     If the first argument H is a list of graphics handles to figure,
     axes, or graphic objects with a DataSource property, then operate
     on these objects rather than the current figure returned by ‘gcf’.

     The optional second argument WORKSPACE can take the following
     values:

     "base"
          Evaluate the datasource properties in the base workspace.
          (default).

     "caller"
          Evaluate the datasource properties in the workspace of the
          function that called ‘refreshdata’.

     An example of the use of ‘refreshdata’ is:

          x = 0:0.1:10;
          y = sin (x);
          plot (x, y, "ydatasource", "y");
          for i = 1 : 100
            pause (0.1);
            y = sin (x + 0.1*i);
            refreshdata ();
          endfor

     Programming Note: For performance, specify H as the actual
     object(s) to be updated.  If no object is supplied then Octave must
     search through all graphic objects of the current figure and
     determine which ones have DataSource properties that are not empty.


File: octave.info,  Node: Area Series,  Next: Bar Series,  Prev: Data Sources in Object Groups,  Up: Object Groups

15.4.6.2 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.  *Note Line Styles::.

‘edgecolor’
‘facecolor’
     The line and fill color of the patch objects making up the areas.
     *Note 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.


File: octave.info,  Node: Bar Series,  Next: Contour Groups,  Prev: Area Series,  Up: Object Groups

15.4.6.3 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 properties 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.  *Note Line Styles::.

‘edgecolor’
‘facecolor’
     The line and fill color of the patch objects making up the bars.
     *Note 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.


File: octave.info,  Node: Contour Groups,  Next: Error Bar Series,  Prev: Bar Series,  Up: Object Groups

15.4.6.4 Contour Groups
.......................

Contour group objects are created by the ‘contour’, ‘contourf’, and
‘contour3’ functions.  They are also 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 labeled contours is
     determined by ‘textlist’.  If ‘textlistmode’ is set to "auto", then
     the distance between labeled contours is determined by ‘textstep’.
     If both ‘textlistmode’ and ‘textstepmode’ are set to "auto", then
     there are assumed to be 10 equal spaced labeled 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 (*note
     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.


File: octave.info,  Node: Error Bar Series,  Next: Line Series,  Prev: Contour Groups,  Up: Object Groups

15.4.6.5 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.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the error bars.
     *Note Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the error bars.  *Note
     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.


File: octave.info,  Node: Line Series,  Next: Quiver Group,  Prev: Error Bar Series,  Up: Object Groups

15.4.6.6 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.  *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects.  *Note Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers.  *Note Colors::.

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

‘xdatasource’
‘ydatasource’
‘zdatasource’
     Data source variables.


File: octave.info,  Node: Quiver Group,  Next: Stair Group,  Prev: Line Series,  Up: Object Groups

15.4.6.7 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 origin 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.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the quiver.  *Note
     Line Styles::.

‘marker’
‘markerfacecolor’
‘markersize’
     The line and fill color of the marker objects at the original of
     the arrows.  *Note 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.


File: octave.info,  Node: Stair Group,  Next: Stem Series,  Prev: Quiver Group,  Up: Object Groups

15.4.6.8 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.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the stairs.  *Note
     Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the stairs.  *Note
     Colors::.

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

‘xdatasource’
‘ydatasource’
     Data source variables.


File: octave.info,  Node: Stem Series,  Next: Surface Group,  Prev: Stair Group,  Up: Object Groups

15.4.6.9 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.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the line objects of the stems.  *Note
     Line Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the stems.  *Note
     Colors::.

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

‘xdatasource’
‘ydatasource’
‘zdatasource’
     Data source variables.


File: octave.info,  Node: Surface Group,  Prev: Stem Series,  Up: Object Groups

15.4.6.10 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.
     *Note Colors::.

‘linewidth’
‘linestyle’
     The line width and style of the lines on the surface.  *Note Line
     Styles::.

‘marker’
‘markeredgecolor’
‘markerfacecolor’
‘markersize’
     The line and fill color of the markers on the surface.  *Note
     Colors::.

‘xdata’
‘ydata’
‘zdata’
‘cdata’
     The original x, y, z and c data.

‘xdatasource’
‘ydatasource’
‘zdatasource’
‘cdatasource’
     Data source variables.


File: octave.info,  Node: Transform Groups,  Next: Graphics Toolkits,  Prev: Object Groups,  Up: Advanced Plotting

15.4.7 Transform Groups
-----------------------

 -- : H = hgtransform ()
 -- : H = hgtransform (PROPERTY, VALUE, ...)
 -- : H = hgtransform (HAX, ...)

     Create a graphics transform object.

     FIXME: Need to write documentation.  FIXME: Add <makehgtform> to
     seealso list when it is implemented.

     See also: *note hggroup: XREFhggroup.


File: octave.info,  Node: Graphics Toolkits,  Prev: Transform Groups,  Up: Advanced Plotting

15.4.8 Graphics Toolkits
------------------------

 -- : TKIT = graphics_toolkit ()
 -- : TKIT = graphics_toolkit (HLIST)
 -- : graphics_toolkit (NAME)
 -- : graphics_toolkit (HLIST, NAME)
     Query or set the default graphics toolkit which is assigned to new
     figures.

     With no inputs, return the current default graphics toolkit.  If
     the input is a list of figure graphic handles, HLIST, then return
     the name of the graphics toolkit in use for each figure.

     When called with a single input NAME set the default graphics
     toolkit to NAME.  If the toolkit is not already loaded, it is
     initialized by calling the function ‘__init_NAME__’.  If the first
     input is a list of figure handles, HLIST, then the graphics toolkit
     is set to NAME for these figures only.

     See also: *note available_graphics_toolkits:
     XREFavailable_graphics_toolkits.

 -- : TOOLKITS = available_graphics_toolkits ()
     Return a cell array of registered graphics toolkits.

     See also: *note graphics_toolkit: XREFgraphics_toolkit, *note
     register_graphics_toolkit: XREFregister_graphics_toolkit.

 -- : TOOLKITS = loaded_graphics_toolkits ()
     Return a cell array of the currently loaded graphics toolkits.

     See also: *note available_graphics_toolkits:
     XREFavailable_graphics_toolkits.

 -- : register_graphics_toolkit ("TOOLKIT")
     List TOOLKIT as an available graphics toolkit.

     Programming Note: No input validation is done on the input string;
     it is simply added to the list of possible graphics toolkits.

     See also: *note available_graphics_toolkits:
     XREFavailable_graphics_toolkits.

* Menu:

* Customizing Toolkit Behavior::
* Hardware vs Software Rendering::
* Precision issues::


File: octave.info,  Node: Customizing Toolkit Behavior,  Next: Hardware vs Software Rendering,  Up: Graphics Toolkits

15.4.8.1 Customizing Toolkit Behavior
.....................................

The specific behavior of the backend toolkit may be modified using the
following utility functions.  Note: Not all functions apply to every
graphics toolkit.

 -- : [PROG, ARGS] = gnuplot_binary ()
 -- : [OLD_PROG, OLD_ARGS] = gnuplot_binary (NEW_PROG)
 -- : [OLD_PROG, OLD_ARGS] = gnuplot_binary (NEW_PROG, ARG1, ...)
     Query or set the name of the program invoked by the plot command
     when the graphics toolkit is set to "gnuplot".

     Additional arguments to pass to the external plotting program may
     also be given.  The default value is "gnuplot" with no additional
     arguments.  *Note Installation::.

     See also: *note graphics_toolkit: XREFgraphics_toolkit.

 In addition, the gnuplot program usually provides a number of different
interfaces, known as terminals.  Octave normally chooses a default
terminal, but you can override this with the environment variable
‘GNUTERM’.  This variable may be set in the shell before starting Octave
or from within Octave before plotting for the first time.  For example:

     setenv ("GNUTERM", "wxt")
     graphics_toolkit ("gnuplot")
     plot (1:10)


File: octave.info,  Node: Hardware vs Software Rendering,  Next: Precision issues,  Prev: Customizing Toolkit Behavior,  Up: Graphics Toolkits

15.4.8.2 Hardware vs Software Rendering
.......................................

When using the Windows installer for Octave, the user has the option to
select between "System OpenGL" and "Software OpenGL" renderers.  The
choice between hardware or software rendering affects the OpenGL
graphics toolkits ("qt" and "fltk") only.  Software rendering can be
used to avoid rendering and printing issues due to imperfect OpenGL
driver implementations for diverse graphic cards from different vendors
(notably integrated Intel graphics).  The downside is that software
rendering may be considerably slower than hardware-accelerated rendering
(and it might not work correctly on 32-bit platforms or WoW64).  To
permanently switch between hardware-accelerated rendering with your
graphics card drivers and software rendering, use the "OpenGL Switcher"
application from the Start menu while Octave is closed.  Alternatively,
rename the following file while Octave is closed:

 ‘OCTAVE-HOME\bin\opengl32.dll’
where OCTAVE-HOME is the directory returned by *note ‘OCTAVE_HOME’:
XREFOCTAVE_HOME, i.e., the directory in which Octave is installed (the
default is ‘C:\Program Files\GNU Octave\Octave\Octave-VERSION\mingw64’).
Change the file extension to ‘.bak’ for hardware rendering or to ‘.dll’
for software rendering.


File: octave.info,  Node: Precision issues,  Prev: Hardware vs Software Rendering,  Up: Graphics Toolkits

15.4.8.3 Precision issues
.........................

The OpenGL graphics toolkits ("qt" and "fltk") use single precision for
rendering.  This limitation in particular applies to plots of time
series against serial dates as used by the ‘datenum’, ‘datestr’,
‘datestruct’, and ‘datetick’ functions.

 Serial dates encode timestamps as days elapsed since the year zero with
hours, minutes, seconds as the fractional part.  On December 31st 1999,
the serial date representation was 730485.  A double precision variable
with this integer part allows for a resolution in its fractional part of
1.2e-10, representing about 5 microseconds.  But with single precision,
the resolution is reduced to about 0.06, representing 45 minutes.  Any
attempt to plot timestamped data with finer granularity will result in a
distorted graph.

 As a workaround, it is possible to use the "gnuplot" graphics toolkit
or subtract 2000 years--i.e., ‘datenum (2000, 0, 0)’ or 730485--from the
time values.  Due to the fact that the calendar structure repeats every
2000 years, the relation between year, month, day of month and day of
week will stay unchanged and the ticks and ticklabels produced by the
‘datetick’ function will still be correct.  Only years will lack the
millennium digit.  Thus, "2020" will be printed as "20".  For example:

     # timestamps of 24 hours in one minute steps
     t = datenum (2020, 1, 1):(1/1440):datenum (2020, 1, 2);

     # some example time series data
     x = -cos (2*pi*t) + rand (size (t)) / 10;

     subplot (1, 2, 1);
     plot (t, x);
     datetick ("x");
     xlabel ("serial date");
     title ("problem");

     subplot (1, 2, 2);
     plot (t - 730485, x);
     datetick ("x");
     xlabel ("2000 years off");
     title ("workaround");

 Similarly, other data can be translated or re-scaled to work around
this issue.


File: octave.info,  Node: Matrix Manipulation,  Next: Arithmetic,  Prev: Plotting,  Up: Top

16 Matrix Manipulation
**********************

There are a number of functions available for checking to see if the
elements of a matrix meet some condition, and for rearranging the
elements of a matrix.  For example, Octave can easily tell you if all
the elements of a matrix are finite, or are less than some specified
value.  Octave can also rotate the elements, extract the upper- or
lower-triangular parts, or sort the columns of a matrix.

* Menu:

* Finding Elements and Checking Conditions::
* Rearranging Matrices::
* Special Utility Matrices::
* Famous Matrices::


File: octave.info,  Node: Finding Elements and Checking Conditions,  Next: Rearranging Matrices,  Up: Matrix Manipulation

16.1 Finding Elements and Checking Conditions
=============================================

The functions ‘any’ and ‘all’ are useful for determining whether any or
all of the elements of a matrix satisfy some condition.  The ‘find’
function is also useful in determining which elements of a matrix meet a
specified condition.

 -- : TF = any (X)
 -- : TF = any (X, DIM)
 -- : TF = any (X, VECDIM)
 -- : TF = any (X, "all")
     Return true (logical 1) if any elements are nonzero or true.

     If X is a vector, then ‘any (X)’ returns true (logical 1) if any
     elements of the vector are nonzero.

     If X is a matrix, then ‘any (X)’ returns a row vector of logical
     ones and zeros where each element indicates whether any of the
     elements of the corresponding column of the matrix are nonzero.

     If X is an array, then ‘any(X)’ operates along the first
     non-singleton dimension of X and returns a logical array, whose
     size is equal to X except for the operating dimension which becomes
     1.

     The optional input DIM specifies the dimension to operate on and
     must be a positive integer.  Specifying any singleton dimension in
     X, including any dimension exceeding ‘ndims (X)’, will return X.

     Specifying multiple dimensions with input VECDIM, a vector of
     non-repeating dimensions, will operate along the array slice
     defined by VECDIM.  If VECDIM indexes all dimensions of X, then it
     is equivalent to the option "all".  Any dimension in VECDIM greater
     than ‘ndims (X)’ is ignored.  The size of the dimensions specified
     by VECDIM become 1 in the returned logical array.

     Specifying the dimension as "all" will cause ‘any’ to operate on
     all elements of X, and is equivalent to ‘any (X(:))’.

     See also: *note all: XREFall.

 -- : TF = all (X)
 -- : TF = all (X, DIM)
 -- : TF = all (X, VECDIM)
 -- : TF = all (X, "all")
     Return true (logical 1) if all elements are nonzero or true.

     If X is a vector, then ‘all (X)’ returns true (logical 1) if all
     elements of the vector are nonzero.

     If X is a matrix, then ‘all (X)’ returns a row vector of logical
     ones and zeros where each element indicates whether all of the
     elements of the corresponding column of the matrix are nonzero.

     If X is an array, then ‘all(X)’ operates along the first
     non-singleton dimension of X and returns a logical array, whose
     size is equal to X except for the operating dimension which becomes
     1.

     The optional input DIM specifies the dimension to operate on and
     must be a positive integer.  Specifying any singleton dimension in
     X, including any dimension exceeding ‘ndims (X)’, will return X.

     Specifying multiple dimensions with input VECDIM, a vector of
     non-repeating dimensions, will operate along the array slice
     defined by VECDIM.  If VECDIM indexes all dimensions of X, then it
     is equivalent to the option "all".  Any dimension in VECDIM greater
     than ‘ndims (X)’ is ignored.  The size of the dimensions specified
     by VECDIM become 1 in the returned logical array.

     Specifying the dimension as "all" will cause ‘all’ to operate on
     all elements of X, and is equivalent to ‘all (X(:))’.

     See also: *note any: XREFany.

 Since the comparison operators (*note Comparison Ops::) return matrices
of ones and zeros, it is easy to test a matrix for many things, not just
whether the elements are nonzero.  For example,

     all (all (rand (5) < 0.9))
          ⇒ 0

tests a random 5 by 5 matrix to see if all of its elements are less than
0.9.

 Note that in conditional contexts (like the test clause of ‘if’ and
‘while’ statements) Octave treats the test as if you had typed ‘all (all
(condition))’.

 -- : Z = xor (X, Y)
 -- : Z = xor (X1, X2, ...)
     Return the “exclusive or” of X and Y.

     For boolean expressions X and Y, ‘xor (X, Y)’ is true if and only
     if one of X or Y is true.  Otherwise, if X and Y are both true or
     both false, ‘xor’ returns false.

     The truth table for the xor operation is

                                    X   Y    Z
                                    -   -    -
                                    0   0    0
                                    1   0    1
                                    0   1    1
                                    1   1    0

     If more than two arguments are given the xor operation is applied
     cumulatively from left to right:

          (...((x1 XOR x2) XOR x3) XOR ...)

     See also: *note and: XREFand, *note or: XREFor, *note not: XREFnot.

 -- : Y = diff (X)
 -- : Y = diff (X, K)
 -- : Y = diff (X, K, DIM)
     If X is a vector of length n, ‘diff (X)’ is the vector of first
     differences X(2) - X(1), ..., X(n) - X(n-1).

     If X is a matrix, ‘diff (X)’ is the matrix of column differences
     along the first non-singleton dimension.

     The second argument is optional.  If supplied, ‘diff (X, K)’, where
     K is a non-negative integer, returns the K-th differences.  It is
     possible that K is larger than the first non-singleton dimension of
     the matrix.  In this case, ‘diff’ continues to take the differences
     along the next non-singleton dimension.

     The dimension along which to take the difference can be explicitly
     stated with the optional variable DIM.  In this case the K-th order
     differences are calculated along this dimension.  In the case where
     K exceeds ‘size (X, DIM)’ an empty matrix is returned.

     See also: *note sort: XREFsort, *note merge: XREFmerge.

 -- : TF = isinf (X)
     Return a logical array which is true where the elements of X are
     infinite and false where they are not.

     For example:

          isinf ([13, Inf, NA, NaN])
                ⇒ [ 0, 1, 0, 0 ]

     See also: *note isfinite: XREFisfinite, *note isnan: XREFisnan,
     *note isna: XREFisna.

 -- : TF = isnan (X)
     Return a logical array which is true where the elements of X are
     NaN values and false where they are not.

     NA values are also considered NaN values.  For example:

          isnan ([13, Inf, NA, NaN])
                ⇒ [ 0, 0, 1, 1 ]

     See also: *note isna: XREFisna, *note isinf: XREFisinf, *note
     isfinite: XREFisfinite.

 -- : TF = isfinite (X)
     Return a logical array which is true where the elements of X are
     finite values and false where they are not.

     For example:

          isfinite ([13, Inf, NA, NaN])
               ⇒ [ 1, 0, 0, 0 ]

     See also: *note isinf: XREFisinf, *note isnan: XREFisnan, *note
     isna: XREFisna.

 -- : [ERR, YI, ...] = common_size (XI, ...)
     Determine if all input arguments are either scalar or of common
     size.

     If true, ERR is zero, and YI is a matrix of the common size with
     all entries equal to XI if this is a scalar or XI otherwise.  If
     the inputs cannot be brought to a common size, ERR is 1, and YI is
     XI.  For example:

          [err, a, b] = common_size ([1 2; 3 4], 5)
               ⇒ err = 0
               ⇒ a = [ 1, 2; 3, 4 ]
               ⇒ b = [ 5, 5; 5, 5 ]

     This is useful for implementing functions where arguments can
     either be scalars or of common size.

     See also: *note size: XREFsize, *note size_equal: XREFsize_equal,
     *note numel: XREFnumel, *note ndims: XREFndims.

 -- : IDX = find (X)
 -- : IDX = find (X, N)
 -- : IDX = find (X, N, DIRECTION)
 -- : [i, j] = find (...)
 -- : [i, j, v] = find (...)
     Return a vector of indices of nonzero elements of a matrix, as a
     row if X is a row vector or as a column otherwise.

     To obtain a single index for each matrix element, Octave pretends
     that the columns of a matrix form one long vector (like Fortran
     arrays are stored).  For example:

          find (eye (2))
            ⇒ [ 1; 4 ]

     If two inputs are given, N indicates the maximum number of elements
     to find from the beginning of the matrix or vector.

     If three inputs are given, DIRECTION should be one of "first" or
     "last", requesting only the first or last N indices, respectively.
     However, the indices are always returned in ascending order.

     If two outputs are requested, ‘find’ returns the row and column
     indices of nonzero elements of a matrix.  For example:

          [i, j] = find (2 * eye (2))
              ⇒ i = [ 1; 2 ]
              ⇒ j = [ 1; 2 ]

     If three outputs are requested, ‘find’ also returns a vector
     containing the nonzero values.  For example:

          [i, j, v] = find (3 * eye (2))
                 ⇒ i = [ 1; 2 ]
                 ⇒ j = [ 1; 2 ]
                 ⇒ v = [ 3; 3 ]

     If X is a multi-dimensional array of size m x n x p x ..., J
     contains the column locations as if X was flattened into a
     two-dimensional matrix of size m x (n + p + ...).

     Note that this function is particularly useful for sparse matrices,
     as it extracts the nonzero elements as vectors, which can then be
     used to create the original matrix.  For example:

          sz = size (a);
          [i, j, v] = find (a);
          b = sparse (i, j, v, sz(1), sz(2));

     See also: *note nonzeros: XREFnonzeros.

 -- : IDX = lookup (TABLE, Y)
 -- : IDX = lookup (TABLE, Y, OPT)
     Lookup values in a *sorted* table.

     This function is usually used as a prelude to interpolation.

     If table is increasing, of length N and ‘idx = lookup (table, y)’,
     then ‘table(idx(i)) <= y(i) < table(idx(i+1))’ for all ‘y(i)’
     within the table.  If ‘y(i) < table(1)’ then ‘idx(i)’ is 0.  If
     ‘y(i) >= table(end)’ or ‘isnan (y(i))’ then ‘idx(i)’ is N.

     If the table is decreasing, then the tests are reversed.  For
     non-strictly monotonic tables, empty intervals are always skipped.
     The result is undefined if TABLE is not monotonic, or if TABLE
     contains a NaN.

     The complexity of the lookup is O(M*log(N)) where M is the size of
     Y.  In the special case when Y is also sorted, the complexity is
     O(min (M*log(N), M+N)).

     TABLE and Y can also be cell arrays of strings (or Y can be a
     single string).  In this case, string lookup is performed using
     lexicographical comparison.

     If OPTS is specified, it must be a string with letters indicating
     additional options.

     ‘m’
          Match.  ‘table(idx(i)) == y(i)’ if ‘y(i)’ occurs in table;
          otherwise, ‘idx(i)’ is zero.

     ‘b’
          Boolean.  ‘idx(i)’ is a logical 1 or 0, indicating whether
          ‘y(i)’ is contained in table or not.

     ‘l’
          Left.  For numeric lookups the leftmost subinterval shall be
          extended to minus infinity (i.e., all indices at least 1).

     ‘r’
          Right.  For numeric lookups the rightmost subinterval shall be
          extended to infinity (i.e., all indices at most N-1).

     *Note*: If TABLE is not sorted the results from ‘lookup’ will be
     unpredictable.

 If you wish to check if a variable exists at all, instead of properties
its elements may have, consult *note Status of Variables::.


File: octave.info,  Node: Rearranging Matrices,  Next: Special Utility Matrices,  Prev: Finding Elements and Checking Conditions,  Up: Matrix Manipulation

16.2 Rearranging Matrices
=========================

 -- : B = fliplr (A)
     Flip array left to right.

     Return a copy of A with the order of the columns reversed.  In
     other words, A is flipped left-to-right about a vertical axis.  For
     example:

          fliplr ([1, 2; 3, 4])
               ⇒  2  1
                   4  3

     See also: *note flipud: XREFflipud, *note flip: XREFflip, *note
     rot90: XREFrot90, *note rotdim: XREFrotdim.

 -- : B = flipud (A)
     Flip array upside down.

     Return a copy of A with the order of the rows reversed.  In other
     words, A is flipped upside-down about a horizontal axis.  For
     example:

          flipud ([1, 2; 3, 4])
               ⇒  3  4
                   1  2

     See also: *note fliplr: XREFfliplr, *note flip: XREFflip, *note
     rot90: XREFrot90, *note rotdim: XREFrotdim.

 -- : B = flip (A)
 -- : B = flip (A, DIM)
     Return a copy of array A flipped across dimension DIM.

     If DIM is unspecified it defaults to the first non-singleton
     dimension.

     Examples:

          ## row vector
          flip ([1  2  3  4])
                ⇒  4  3  2  1

          ## column vector
          flip ([1; 2; 3; 4])
                ⇒  4
                    3
                    2
                    1

          ## 2-D matrix along dimension 1
          flip ([1 2; 3 4])
                ⇒  3  4
                    1  2

          ## 2-D matrix along dimension 2
          flip ([1 2; 3 4], 2)
                ⇒  2  1
                    4  3

     See also: *note fliplr: XREFfliplr, *note flipud: XREFflipud, *note
     rot90: XREFrot90, *note rotdim: XREFrotdim, *note permute:
     XREFpermute, *note transpose: XREFtranspose.

 -- : B = rot90 (A)
 -- : B = rot90 (A, K)
     Rotate array by 90 degree increments.

     Return a copy of A with the elements rotated counterclockwise in
     90-degree increments.

     The second argument is optional, and specifies how many 90-degree
     rotations are to be applied (the default value is 1).  Negative
     values of K rotate the matrix in a clockwise direction.  For
     example,

          rot90 ([1, 2; 3, 4], -1)
              ⇒  3  1
                  4  2

     rotates the given matrix clockwise by 90 degrees.  The following
     are all equivalent statements:

          rot90 ([1, 2; 3, 4], -1)
          rot90 ([1, 2; 3, 4], 3)
          rot90 ([1, 2; 3, 4], 7)

     The rotation is always performed on the plane of the first two
     dimensions, i.e., rows and columns.  To perform a rotation on any
     other plane, use ‘rotdim’.

     See also: *note rotdim: XREFrotdim, *note fliplr: XREFfliplr, *note
     flipud: XREFflipud, *note flip: XREFflip.

 -- : B = rotdim (A)
 -- : B = rotdim (A, N)
 -- : B = rotdim (A, N, PLANE)
     Return a copy of A with the elements rotated counterclockwise in
     90-degree increments.

     The second argument N is optional, and specifies how many 90-degree
     rotations are to be applied (the default value is 1).  Negative
     values of N rotate the matrix in a clockwise direction.

     The third argument is also optional and defines the plane of the
     rotation.  If present, PLANE is a two element vector containing two
     different valid dimensions of the matrix.  When PLANE is not given
     the first two non-singleton dimensions are used.

     For example,

          rotdim ([1, 2; 3, 4], -1, [1, 2])
               ⇒  3  1
                   4  2

     rotates the given matrix clockwise by 90 degrees.  The following
     are all equivalent statements:

          rotdim ([1, 2; 3, 4], -1, [1, 2])
          rotdim ([1, 2; 3, 4], 3, [1, 2])
          rotdim ([1, 2; 3, 4], 7, [1, 2])

     See also: *note rot90: XREFrot90, *note fliplr: XREFfliplr, *note
     flipud: XREFflipud, *note flip: XREFflip.

 -- : A = cat (DIM, ARRAY1, ARRAY2, ..., ARRAYN)
     Return the concatenation of N-D array objects, ARRAY1, ARRAY2, ...,
     ARRAYN along dimension DIM.

          A = ones (2, 2);
          B = zeros (2, 2);
          cat (2, A, B)
            ⇒ 1 1 0 0
               1 1 0 0

     Alternatively, we can concatenate A and B along the second
     dimension in the following way:

          [A, B]

     DIM can be larger than the dimensions of the N-D array objects and
     the result will thus have DIM dimensions as the following example
     shows:

          cat (4, ones (2, 2), zeros (2, 2))
            ⇒ ans(:,:,1,1) =

                 1 1
                 1 1

               ans(:,:,1,2) =

                 0 0
                 0 0

     See also: *note horzcat: XREFhorzcat, *note vertcat: XREFvertcat.

 -- : A = horzcat (ARRAY1, ARRAY2, ..., ARRAYN)
     Return the horizontal concatenation of N-D array objects, ARRAY1,
     ARRAY2, ..., ARRAYN along dimension 2.

     Arrays may also be concatenated horizontally using the syntax for
     creating new matrices.  For example:

          A = [ ARRAY1, ARRAY2, ... ]

     This syntax is slightly more efficient because the Octave parser
     can concatenate the arrays without the overhead of a function call.

     See also: *note cat: XREFcat, *note vertcat: XREFvertcat.

 -- : A = vertcat (ARRAY1, ARRAY2, ..., ARRAYN)
     Return the vertical concatenation of N-D array objects, ARRAY1,
     ARRAY2, ..., ARRAYN along dimension 1.

     Arrays may also be concatenated vertically using the syntax for
     creating new matrices.  For example:

          A = [ ARRAY1; ARRAY2; ... ]

     This syntax is slightly more efficient because the Octave parser
     can concatenate the arrays without the overhead of a function call.

     See also: *note cat: XREFcat, *note horzcat: XREFhorzcat.

 -- : B = permute (A, PERM)
     Return the generalized transpose for an N-D array object A.

     The permutation vector PERM must contain the elements
     ‘1:ndims (A)’ (in any order, but each element must appear only
     once).  The Nth dimension of A gets remapped to dimension
     ‘PERM(N)’.  For example:

          X = zeros ([2, 3, 5, 7]);
          size (X)
             ⇒  2   3   5   7

          size (permute (X, [2, 1, 3, 4]))
             ⇒  3   2   5   7

          size (permute (X, [1, 3, 4, 2]))
             ⇒  2   5   7   3

          ## The identity permutation
          size (permute (X, [1, 2, 3, 4]))
             ⇒  2   3   5   7

     See also: *note ipermute: XREFipermute.

 -- : A = ipermute (B, IPERM)
     The inverse of the ‘permute’ function.

     The expression

          ipermute (permute (A, perm), perm)

     returns the original array A.

     See also: *note permute: XREFpermute.

 -- : B = reshape (A, M, N, ...)
 -- : B = reshape (A, [M N ...])
 -- : B = reshape (A, ..., [], ...)
 -- : B = reshape (A, SIZE)
     Return a matrix with the specified dimensions (M, N, ...) whose
     elements are taken from the matrix A.

     The elements of the matrix are accessed in column-major order (like
     Fortran arrays are stored).

     The following code demonstrates reshaping a 1x4 row vector into a
     2x2 square matrix.

          reshape ([1, 2, 3, 4], 2, 2)
                ⇒  1  3
                    2  4

     Note that the total number of elements in the original matrix
     (‘prod (size (A))’) must match the total number of elements in the
     new matrix (‘prod ([M N ...])’).

     A single dimension of the return matrix may be left unspecified and
     Octave will determine its size automatically.  An empty matrix ([])
     is used to flag the unspecified dimension.

     See also: *note resize: XREFresize, *note vec: XREFvec, *note
     postpad: XREFpostpad, *note cat: XREFcat, *note squeeze:
     XREFsqueeze.

 -- : B = resize (A, M)
 -- : B = resize (A, M, N, ...)
 -- : B = resize (A, [M N ...])
     Resize A cutting off elements as necessary.

     In the result, element with certain indices is equal to the
     corresponding element of A if the indices are within the bounds of
     A; otherwise, the element is set to zero.

     In other words, the statement

          B = resize (A, dv)

     is equivalent to the following code:

          B = zeros (dv, class (A));
          sz = min (dv, size (A));
          for i = 1:length (sz)
            idx{i} = 1:sz(i);
          endfor
          B(idx{:}) = A(idx{:});

     but is performed more efficiently.

     If only M is supplied, and it is a scalar, the dimension of the
     result is M-by-M.  If M, N, ... are all scalars, then the
     dimensions of the result are M-by-N-by-...  If given a vector as
     input, then the dimensions of the result are given by the elements
     of that vector.

     An object can be resized to more dimensions than it has; in such
     case the missing dimensions are assumed to be 1.  Resizing an
     object to fewer dimensions is not possible.

     See also: *note reshape: XREFreshape, *note postpad: XREFpostpad,
     *note prepad: XREFprepad, *note cat: XREFcat.

 -- : Y = circshift (X, N)
 -- : Y = circshift (X, N, DIM)
     Circularly shift the values of the array X.

     N must be a vector of integers no longer than the number of
     dimensions in X.  The values of N can be either positive or
     negative, which determines the direction in which the values of X
     are shifted.  If an element of N is zero, then the corresponding
     dimension of X will not be shifted.  If N is a scalar and no DIM is
     specified then the shift is applied to the first non-singular
     dimension.

     If a scalar DIM is given then operate along the specified
     dimension.  In this case N must be a scalar as well.

     Examples:

          x = [1, 2, 3;
               4, 5, 6;
               7, 8, 9];
          ## positive shift on rows (1st non-singular dim)
          circshift (x, 1)
            ⇒
                 7   8   9
                 1   2   3
                 4   5   6
          ## negative shift on rows (1st non-singular dim)
          circshift (x, -2)
            ⇒
                 7   8   9
                 1   2   3
                 4   5   6
          ## no shift of rows, shift columns by 1 (2nd dimension)
          circshift (x, [0,1])
            ⇒
                 3   1   2
                 6   4   5
                 9   7   8
          ## shift columns (2nd dimension)
          circshift (x, 1, 2)
            ⇒
                 3   1   2
                 6   4   5
                 9   7   8

     See also: *note permute: XREFpermute, *note ipermute: XREFipermute,
     *note shiftdim: XREFshiftdim.

 -- : Y = shiftdim (X, N)
 -- : [Y, NS] = shiftdim (X)
     Shift the dimensions of X by N, where N must be an integer scalar.

     When N is positive, the dimensions of X are shifted to the left,
     with the leading dimensions circulated to the end.  If N is
     negative, then the dimensions of X are shifted to the right, with N
     leading singleton dimensions added.

     Called with a single argument, ‘shiftdim’, removes the leading
     singleton dimensions, returning the number of dimensions removed in
     the second output argument NS.

     For example:

          x = ones (1, 2, 3);
          size (shiftdim (x, -1))
            ⇒   1   1   2   3
          size (shiftdim (x, 1))
            ⇒   2   3
          [b, ns] = shiftdim (x)
            ⇒ b =
                  1   1   1
                  1   1   1
            ⇒ ns = 1

     See also: *note reshape: XREFreshape, *note permute: XREFpermute,
     *note ipermute: XREFipermute, *note circshift: XREFcircshift, *note
     squeeze: XREFsqueeze.

 -- : [S, I] = sort (X)
 -- : [S, I] = sort (X, DIM)
 -- : [S, I] = sort (X, MODE)
 -- : [S, I] = sort (X, DIM, MODE)
     Return a copy of X with the elements arranged in increasing order.

     For matrices, ‘sort’ orders the elements within columns

     For example:

          sort ([1, 2; 2, 3; 3, 1])
             ⇒  1  1
                 2  2
                 3  3

     If the optional argument DIM is given, then the matrix is sorted
     along the dimension defined by DIM.  The optional argument MODE
     defines the order in which the values will be sorted.  Valid values
     of MODE are "ascend" or "descend".

     The ‘sort’ function may also be used to produce a matrix containing
     the original row indices of the elements in the sorted matrix.  For
     example:

          [s, i] = sort ([1, 2; 2, 3; 3, 1])
            ⇒ s = 1  1
                   2  2
                   3  3
            ⇒ i = 1  3
                   2  1
                   3  2

     For equal elements, the indices are such that equal elements are
     listed in the order in which they appeared in the original list.

     Sorting of complex entries is done first by magnitude
     (‘abs (Z)’) and for any ties by phase angle (‘angle (z)’).  For
     example:

          sort ([1+i; 1; 1-i])
              ⇒ 1 + 0i
                 1 - 1i
                 1 + 1i

     NaN values are treated as being greater than any other value and
     are sorted to the end of the list.

     The ‘sort’ function may also be used to sort strings and cell
     arrays of strings, in which case ASCII dictionary order (uppercase
     'A' precedes lowercase 'a') of the strings is used.

     The algorithm used in ‘sort’ is optimized for the sorting of
     partially ordered lists.

     See also: *note sortrows: XREFsortrows, *note issorted:
     XREFissorted.

 -- : [S, I] = sortrows (A)
 -- : [S, I] = sortrows (A, C)
     Sort the rows of the matrix A according to the order of the columns
     specified in C.

     By default (C omitted, or a particular column unspecified in C) an
     ascending sort order is used.  However, if elements of C are
     negative then the corresponding column is sorted in descending
     order.  If the elements of A are strings then a lexicographical
     sort is used.

     Example: sort by column 2 in descending order, then 3 in ascending
     order

          x = [ 7, 1, 4;
                8, 3, 5;
                9, 3, 6 ];
          sortrows (x, [-2, 3])
             ⇒ 8  3  5
                9  3  6
                7  1  4

     See also: *note sort: XREFsort.

 -- : TF = issorted (A)
 -- : TF = issorted (A, MODE)
 -- : TF = issorted (A, "rows", MODE)
     Return true if the vector A is sorted according to MODE, which may
     be either "ascend", "descend", "either", or "monotonic" ("either"
     and "monotonic" are equivalent).

     By default, MODE is "ascend".  NaNs are treated in the same manner
     as ‘sort’.

     If the optional argument "rows" is supplied, check whether the
     matrix is sorted by rows as output by the function ‘sortrows’ (with
     no options).

     This function does not support sparse matrices.

     See also: *note sort: XREFsort, *note sortrows: XREFsortrows.

 -- : NEL = nth_element (X, N)
 -- : NEL = nth_element (X, N, DIM)
     Select the n-th smallest element of a vector, using the ordering
     defined by ‘sort’.

     The result is equivalent to ‘sort(X)(N)’.

     N can also be a contiguous range, either ascending ‘l:u’ or
     descending ‘u:-1:l’, in which case a range of elements is returned.

     If X is an array, ‘nth_element’ operates along the dimension
     defined by DIM, or the first non-singleton dimension if DIM is not
     given.

     Programming Note: nth_element encapsulates the C++ standard library
     algorithms nth_element and partial_sort.  On average, the
     complexity of the operation is O(M*log(K)), where
     ‘M = size (X, DIM)’ and ‘K = length (N)’.  This function is
     intended for cases where the ratio K/M is small; otherwise, it may
     be better to use ‘sort’.

     See also: *note sort: XREFsort, *note min: XREFmin, *note max:
     XREFmax.

 -- : A_LO = tril (A)
 -- : A_LO = tril (A, K)
 -- : A_LO = tril (A, K, PACK)
     Return a new matrix formed by extracting the lower triangular part
     of the matrix A, and setting all other elements to zero.

     The optional second argument specifies how many diagonals above or
     below the main diagonal should also be set to zero.  The default
     value of K is zero which includes the main diagonal as part of the
     result.  If the value of K is a nonzero integer then the selection
     of elements starts at an offset of K diagonals above the main
     diagonal for positive K or below the main diagonal for negative K.
     The absolute value of K may not be greater than the number of
     subdiagonals or superdiagonals.

     Example 1 : exclude main diagonal

          tril (ones (3), -1)
               ⇒  0  0  0
                   1  0  0
                   1  1  0

     Example 2 : include first superdiagonal

          tril (ones (3), 1)
               ⇒  1  1  0
                   1  1  1
                   1  1  1

     If the optional third argument "pack" is given then the extracted
     elements are not inserted into a matrix, but instead stacked
     column-wise one above another, and returned as a column vector.

     See also: *note triu: XREFtriu, *note istril: XREFistril, *note
     diag: XREFdiag.

 -- : A_UP = triu (A)
 -- : A_UP = triu (A, K)
 -- : A_UP = triu (A, K, PACK)
     Return a new matrix formed by extracting the upper triangular part
     of the matrix A, and setting all other elements to zero.

     The optional second argument specifies how many diagonals above or
     below the main diagonal should also be set to zero.  The default
     value of K is zero which includes the main diagonal as part of the
     result.  If the value of K is a nonzero integer then the selection
     of elements starts at an offset of K diagonals above the main
     diagonal for positive K or below the main diagonal for negative K.
     The absolute value of K may not be greater than the number of
     subdiagonals or superdiagonals.

     Example 1 : exclude main diagonal

          triu (ones (3), 1)
               ⇒  0  1  1
                   0  0  1
                   0  0  0

     Example 2 : include first subdiagonal

          triu (ones (3), -1)
               ⇒  1  1  1
                   1  1  1
                   0  1  1

     If the optional third argument "pack" is given then the extracted
     elements are not inserted into a matrix, but instead stacked
     column-wise one above another, and returned as a column vector.

     See also: *note tril: XREFtril, *note istriu: XREFistriu, *note
     diag: XREFdiag.

 -- : V = vec (X)
 -- : V = vec (X, DIM)
     Return the vector obtained by stacking the columns of the matrix X
     one above the other.

     Without DIM this is equivalent to ‘X(:)’.

     If DIM is supplied, the dimensions of V are set to DIM with all
     elements along the last dimension.  This is equivalent to ‘shiftdim
     (X(:), 1-DIM)’.

     See also: *note vech: XREFvech, *note resize: XREFresize, *note
     cat: XREFcat.

 -- : V = vech (X)
     Return the vector obtained by eliminating all superdiagonal
     elements of the square matrix X and stacking the result one column
     above the other.

     This has uses in matrix calculus where the underlying matrix is
     symmetric and it would be pointless to keep values above the main
     diagonal.

     See also: *note vec: XREFvec.

 -- : B = prepad (A, L)
 -- : B = prepad (A, L, C)
 -- : B = prepad (A, L, C, DIM)
     Prepend the scalar value C to the vector A until it is of length L.
     If C is not given, a value of 0 is used.

     If ‘length (A) > L’, elements from the beginning of A are removed
     until a vector of length L is obtained.

     If A is a matrix, elements are prepended or removed from each row.

     If the optional argument DIM is given, operate along this
     dimension.

     If DIM is larger than the dimensions of A, the result will have DIM
     dimensions.

     See also: *note postpad: XREFpostpad, *note cat: XREFcat, *note
     resize: XREFresize.

 -- : B = postpad (A, L)
 -- : B = postpad (A, L, C)
 -- : B = postpad (A, L, C, DIM)
     Append the scalar value C to the vector A until it is of length L.
     If C is not given, a value of 0 is used.

     If ‘length (A) > L’, elements from the end of A are removed until a
     vector of length L is obtained.

     If A is a matrix, elements are appended or removed from each row.

     If the optional argument DIM is given, operate along this
     dimension.

     If DIM is larger than the dimensions of A, the result will have DIM
     dimensions.

     See also: *note prepad: XREFprepad, *note cat: XREFcat, *note
     resize: XREFresize.

 -- : M = diag (V)
 -- : M = diag (V, K)
 -- : M = diag (V, M, N)
 -- : V = diag (M)
 -- : V = diag (M, K)
     Return a diagonal matrix with vector V on diagonal K.

     The second argument is optional.  If it is positive, the vector is
     placed on the K-th superdiagonal.  If it is negative, it is placed
     on the -K-th subdiagonal.  The default value of K is 0, and the
     vector is placed on the main diagonal.  For example:

          diag ([1, 2, 3], 1)
             ⇒  0  1  0  0
                 0  0  2  0
                 0  0  0  3
                 0  0  0  0

     The 3-input form returns a diagonal matrix with vector V on the
     main diagonal and the resulting matrix being of size M rows x N
     columns.

     Given a matrix argument, instead of a vector, ‘diag’ extracts the
     K-th diagonal of the matrix.

 -- : M = blkdiag (A, B, C, ...)
     Build a block diagonal matrix from A, B, C, ...

     All arguments must be numeric and either two-dimensional matrices
     or scalars.  If any argument is of type sparse, the output will
     also be sparse.

     See also: *note diag: XREFdiag, *note horzcat: XREFhorzcat, *note
     vertcat: XREFvertcat, *note sparse: XREFsparse.


File: octave.info,  Node: Special Utility Matrices,  Next: Famous Matrices,  Prev: Rearranging Matrices,  Up: Matrix Manipulation

16.3 Special Utility Matrices
=============================

 -- : I = eye ()
 -- : I = eye (N)
 -- : I = eye (M, N)
 -- : I = eye ([M, N])
 -- : I = eye (..., CLASS)
     Return an identity matrix.

     If called with no arguments, return the scalar value ‘1’.

     If invoked with a single scalar argument N, return a square NxN
     identity matrix.

     If supplied two scalar arguments (M, N), or a 2-element vector
     ‘[M, N]’, return an MxN identity matrix with M rows and N columns.

     The optional argument CLASS specifies the return type of the matrix
     and defaults to "double".

     Example 1 : 1-input, square identity matrix

          eye (3)
           ⇒  1  0  0
               0  1  0
               0  0  1

     Example 2 : following expressions all produce 2x2 identity matrix

          eye (2) ≡ eye (2, 2) ≡ eye (size ([1, 2; 3, 4]))
           ⇒  1  0
               0  1

     Example 3 : 2x2 uint8 identity matrix

          I = eye (2, "uint8")

     Programming Note: Calling ‘eye’ with no arguments is equivalent to
     calling it with an argument of ‘1’.  Any negative dimensions are
     treated as zero.  These odd definitions are for compatibility with
     MATLAB.

     See also: *note speye: XREFspeye, *note ones: XREFones, *note
     zeros: XREFzeros.

 -- : X = ones ()
 -- : X = ones (N)
 -- : X = ones (M, N, ...)
 -- : X = ones ([M, N, ...])
 -- : X = ones (..., CLASS)
 -- : X = ones (..., "like", VAR)
     Return a scalar, matrix, or N-dimensional array whose elements are
     all ‘1’.

     If called with no arguments, return the scalar value ‘1’.

     If invoked with a single scalar integer argument N, return a square
     NxN matrix.

     If invoked with two or more scalar integer arguments, or a vector
     of integer values, return an array with the given dimensions.

     The optional argument CLASS specifies the class of the return array
     and defaults to "double".

     If a variable VAR is specified after "like", the output VAL will
     have the same data type, complexity, and sparsity as VAR.

     Example 1 : MxN matrix of constant value VAL

          C = VAL * ones (M, N)

     Example 2 : MxN matrix of uint8

          C = ones (M, N, "uint8")

     Programming Note: Any negative dimensions are treated as zero, and
     any zero dimensions will result in an empty matrix.  This odd
     behavior is for MATLAB compatibility.

     See also: *note zeros: XREFzeros, *note true: XREFtrue, *note
     false: XREFfalse.

 -- : X = zeros ()
 -- : X = zeros (N)
 -- : X = zeros (M, N, ...)
 -- : X = zeros ([M, N, ...])
 -- : X = zeros (..., CLASS)
 -- : X = zeros (..., "like", VAR)
     Return a scalar, matrix, or N-dimensional array whose elements are
     all ‘0’.

     If called with no arguments, return the scalar value ‘0’.

     If invoked with a single scalar integer argument N, return a square
     NxN matrix.

     If invoked with two or more scalar integer arguments, or a vector
     of integer values, return an array with the given dimensions.

     The optional argument CLASS specifies the class of the return array
     and defaults to "double".

     If a variable VAR is specified after "like", the output VAL will
     have the same data type, complexity, and sparsity as VAR.

     Example : MxN matrix of uint8

          C = ones (M, N, "uint8")

     Programming Note: Any negative dimensions are treated as zero, and
     any zero dimensions will result in an empty matrix.  This odd
     behavior is for MATLAB compatibility.

     See also: *note ones: XREFones, *note true: XREFtrue, *note false:
     XREFfalse.

 -- : B = repmat (A, M)
 -- : B = repmat (A, M, N)
 -- : B = repmat (A, M, N, P ...)
 -- : B = repmat (A, [M N])
 -- : B = repmat (A, [M N P ...])
     Repeat matrix or N-D array.

     Form a block matrix of size M by N, with a copy of matrix A as each
     element.

     If N is not specified, form an M by M block matrix.  For copying
     along more than two dimensions, specify the number of times to copy
     across each dimension M, N, P, ..., in a vector in the second
     argument.

     See also: *note bsxfun: XREFbsxfun, *note kron: XREFkron, *note
     repelems: XREFrepelems.

 -- : Y = repelems (X, R)
     Construct a vector of repeated elements from X.

     R is a 2xN integer matrix specifying which elements to repeat and
     how often to repeat each element.  Entries in the first row,
     R(1,j), select an element to repeat.  The corresponding entry in
     the second row, R(2,j), specifies the repeat count.  If X is a
     matrix then the columns of X are imagined to be stacked on top of
     each other for purposes of the selection index.  A row vector is
     always returned.

     Conceptually the result is calculated as follows:

          y = [];
          for i = 1:columns (R)
            y = [y, X(R(1,i)*ones(1, R(2,i)))];
          endfor

     See also: *note repmat: XREFrepmat, *note cat: XREFcat.

 -- : XXX = repelem (X, R)
 -- : XXX = repelem (X, R_1, ..., R_N)
     Construct an array of repeated elements from X and repeat
     instructions R_1, ...

     X must be a scalar, vector, or N-dimensional array.

     A repeat instruction R_J must either be a scalar or a vector.  If
     the instruction is a scalar then each component of X in dimension J
     is repeated R_J times.  If the instruction is a vector then it must
     have the same number of elements as the corresponding dimension J
     of X.  In this case, the Kth component of dimension J is repeated
     ‘R_J(K)’ times.

     If X is a scalar or vector then ‘repelem’ may be called with just a
     single repeat instruction R and ‘repelem’ will return a vector with
     the same orientation as the input.

     If X is a matrix then at least two R_Js must be specified.

     Note: Using ‘repelem’ with a vector X and a vector for R_J is
     equivalent to Run Length Decoding.

     Examples:

          A = [1 2 3 4 5];
          B = [2 1 0 1 2];
          repelem (A, B)
            ⇒   1   1   2   4   5   5

          A = magic (3)
            ⇒ A =
                 8   1   6
                 3   5   7
                 4   9   2
          B1 = [1 2 3];
          B2 = 2;
          repelem (A, B1, B2)
            ⇒     8   8   1   1   6   6
                   3   3   5   5   7   7
                   3   3   5   5   7   7
                   4   4   9   9   2   2
                   4   4   9   9   2   2
                   4   4   9   9   2   2

     More R_J may be specified than the number of dimensions of X.  Any
     excess R_J must be scalars (because X's size in those dimensions is
     only 1), and X will be replicated in those dimensions accordingly.

          A = [1 2 3 4 5];
          B1 = 2;
          B2 = [2 1 3 0 2];
          B3 = 3;
          repelem (A, B1, B2, B3)
            ⇒    ans(:,:,1) =
                     1   1   2   3   3   3   5   5
                     1   1   2   3   3   3   5   5

                  ans(:,:,2) =

                     1   1   2   3   3   3   5   5
                     1   1   2   3   3   3   5   5

                  ans(:,:,3) =
                     1   1   2   3   3   3   5   5
                     1   1   2   3   3   3   5   5

     R_J must be specified in order.  A placeholder of 1 may be used for
     dimensions which do not need replication.

          repelem ([-1, 0; 0, 1], 1, 2, 1, 2)
            ⇒  ans(:,:,1,1) =
                  -1  -1   0   0
                   0   0   1   1

                ans(:,:,1,2) =
                  -1  -1   0   0
                   0   0   1   1

     If fewer R_J are given than the number of dimensions in X,
     ‘repelem’ will assume R_J is 1 for those dimensions.

          A = cat (3, [-1 0; 0 1], [-1 0; 0 1])
            ⇒  ans(:,:,1) =
                  -1   0
                   0   1

                ans(:,:,2) =
                  -1   0
                   0   1

          repelem (A,2,3)
            ⇒  ans(:,:,1) =
                  -1  -1  -1   0   0   0
                  -1  -1  -1   0   0   0
                   0   0   0   1   1   1
                   0   0   0   1   1   1

                ans(:,:,2) =
                  -1  -1  -1   0   0   0
                  -1  -1  -1   0   0   0
                   0   0   0   1   1   1
                   0   0   0   1   1   1

     ‘repelem’ preserves the class of X, and works with strings, cell
     arrays, NA, and NAN inputs.  If any R_J is 0 the output will be an
     empty array.

          repelem ("Octave", 2, 3)
            ⇒    OOOccctttaaavvveee
                  OOOccctttaaavvveee

          repelem ([1 2 3; 1 2 3], 2, 0)
            ⇒    [](4x0)

     See also: *note cat: XREFcat, *note kron: XREFkron, *note repmat:
     XREFrepmat.

 The functions ‘linspace’ and ‘logspace’ make it very easy to create
vectors with evenly or logarithmically spaced elements.  *Note Ranges::.

 -- : Y = linspace (START, END)
 -- : Y = linspace (START, END, N)
     Return a row vector with N linearly spaced elements between START
     and END.

     If the number of elements N is greater than one, then the endpoints
     START and END are always included in the range.  If START is
     greater than END, the elements are stored in decreasing order.  If
     the number of points N is not specified, a value of 100 is used.

     The ‘linspace’ function returns a row vector when both START and
     END are scalars.  If one, or both, inputs are vectors, then
     ‘linspace’ transforms them to column vectors and returns a matrix
     where each row is an independent sequence between
     ‘START(ROW_N), END(ROW_N)’.

     Programming Notes: For compatibility with MATLAB, return the second
     argument (END) when a single value (N = 1) is requested.  If N is
     not an integer then ‘floor (N)’ is used to round the number of
     elements.  If N is zero or negative then an empty 1x0 matrix is
     returned.

     See also: *note colon: XREFcolon, *note logspace: XREFlogspace.

 -- : Y = logspace (A, B)
 -- : Y = logspace (A, B, N)
 -- : Y = logspace (A, pi)
 -- : Y = logspace (A, pi, N)
     Return a row vector with N elements logarithmically spaced from
     10^A to 10^B.

     If the number of elements N is unspecified it defaults to 50.

     If B is equal to pi, the points are between 10^A and pi, _not_ 10^A
     and 10^pi, which is useful in digital signal processing.

     Programming Notes: For compatibility with MATLAB, return the
     right-hand side of the range (10^B) when a single value (N = 1) is
     requested.  If N is not an integer then ‘floor (N)’ is used to
     round the number of elements.  If N is zero or negative then an
     empty 1x0 matrix is returned.

     See also: *note linspace: XREFlinspace.

 -- : X = rand ()
 -- : X = rand (N)
 -- : X = rand (M, N, ...)
 -- : X = rand ([M, N, ...])
 -- : X = rand (..., CLASS)
 -- : V = rand ("state")
 -- : rand ("state", V)
 -- : rand ("state", "reset")
 -- : V = rand ("seed")
 -- : rand ("seed", V)
 -- : rand ("seed", "reset")
     Return a scalar, matrix, or N-dimensional array whose elements are
     random numbers uniformly distributed on the interval (0, 1).

     If called with no arguments, return a scalar random value.

     If invoked with a single scalar integer argument N, return a square
     NxN matrix.

     If invoked with two or more scalar integer arguments, or a vector
     of integer values, return an array with the given dimensions.

     The optional argument CLASS specifies the class of the return
     array.  The only valid options are "double" (default) or "single".

     Programming Note: Any negative dimensions are treated as zero, and
     any zero dimensions will result in an empty matrix.  This odd
     behavior is for MATLAB compatibility.

     The additional calling forms provide an interface to the underlying
     random number generator.

     You can query the state of the random number generator using the
     form

          v = rand ("state")

     This returns a column vector V of length 625.  Later, you can
     restore the random number generator to the state V using the form

          rand ("state", v)

     You may also initialize the state vector from an arbitrary vector
     of length ≤ 625 for V.  The new state will be a hash based on the
     value of V, not V itself.

     By default, the generator is initialized by contributing entropy
     from the wall clock time, the CPU time, the current fraction of a
     second, the process ID and--if available--up to 1024 bits from the
     C++ random number source ‘random_device’, which might be
     non-deterministic (implementation specific).  Note that this
     differs from MATLAB, which always initializes the random number
     generator to the same state at startup.  To obtain behavior
     comparable to MATLAB, initialize with a deterministic state vector
     in Octave's startup files (*note Startup Files::).

     Programming Notes: To compute the pseudo-random sequence, ‘rand’
     uses the Mersenne Twister with a period of 2^{19937}-1 (See M.
     Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally
     equidistributed uniform pseudorandom number generator", ‘ACM Trans.
     on Modeling and Computer Simulation’, Vol. 8, No. 1, pp. 3-30,
     January 1998,
     <http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html>).  Do
     *not* use for cryptography without securely hashing several
     returned values together, otherwise the generator state can be
     learned after reading 624 consecutive values.

     Older versions of Octave used a different random number generator.
     The new generator is used by default as it is significantly faster
     than the old generator, and produces random numbers with a
     significantly longer cycle time.  However, in some circumstances it
     might be desirable to obtain the same random sequences as produced
     by the old generators.  To do this the keyword "seed" is used to
     specify that the old generators should be used, as in

          rand ("seed", val)

     which sets the seed of the generator to VAL.  The seed of the
     generator can be queried with

          s = rand ("seed")

     However, it should be noted that querying the seed will not cause
     ‘rand’ to use the old generators, only setting the seed will.  To
     cause ‘rand’ to once again use the new generators, the keyword
     "state" must be used to reset ‘rand’ back to using the default
     generator.

     The state or seed of the generator can be reset to a new random
     value using the "reset" keyword.

     See also: *note randi: XREFrandi, *note randn: XREFrandn, *note
     rande: XREFrande, *note randg: XREFrandg, *note randp: XREFrandp.

 -- : R = randi (IMAX)
 -- : R = randi (IMAX, N)
 -- : R = randi (IMAX, M, N, ...)
 -- : R = randi (IMAX, [M, N, ...])
 -- : R = randi ([IMIN, IMAX], ...)
 -- : R = randi (..., "CLASS")
     Return a scalar, matrix, or N-dimensional array whose elements are
     random integers in the range [1, IMAX].

     If called with no size arguments, return a scalar random value.

     If invoked with a single scalar size argument N, return a square
     NxN matrix.

     If invoked with two or more scalar integer size arguments, or a
     vector of integer values, return an array with the given
     dimensions.

     The integer range may optionally be described by a two-element
     matrix with a lower and upper bound in which case the returned
     integers will be on the interval [IMIN, IMAX].

     The optional argument CLASS will return a matrix of the requested
     type.  The default is "double".  Supported classes are: "double",
     "single", "int8", "int16", "int32", "uint8", "uint16", "uint32",
     and "logical".

     Programming Notes: ‘randi’ relies internally on ‘rand’ which uses
     class "double" to represent numbers.  This limits the maximum
     integer (IMAX) and range (IMAX - IMIN) to the value returned by the
     ‘flintmax’ function.  For IEEE 754 floating point numbers this
     value is 2^{53} - 1.

     When the output class is "logical" the function constructs an array
     of random integers as specified and then applies the test ‘X > 0’
     to determine which elements will be true.  Because the one-input
     form of the function uses ‘1’ for IMIN ‘randi’ will always return a
     matrix of all ones.

     Example: 150 integers in the range 1-10.

          ri = randi (10, 150, 1)

     See also: *note rand: XREFrand, *note randn: XREFrandn, *note
     rande: XREFrande, *note randg: XREFrandg, *note randp: XREFrandp.

 -- : X = randn ()
 -- : X = randn (N)
 -- : X = randn (M, N, ...)
 -- : X = randn ([M, N, ...])
 -- : X = randn (..., CLASS)
 -- : V = randn ("state")
 -- : randn ("state", V)
 -- : randn ("state", "reset")
 -- : V = randn ("seed")
 -- : randn ("seed", V)
 -- : randn ("seed", "reset")
     Return a scalar, matrix, or N-dimensional array whose elements are
     random numbers from the standard normal distribution having a mean
     of ‘0’ and a variance of ‘1’.

     If called with no arguments, return a scalar random value.

     If invoked with a single scalar integer argument N, return a square
     NxN matrix.

     If invoked with two or more scalar integer arguments, or a vector
     of integer values, return an array with the given dimensions.

     The optional argument CLASS specifies the class of the return
     array.  The only valid options are "double" (default) or "single".

     Programming Note: Any negative dimensions are treated as zero, and
     any zero dimensions will result in an empty matrix.  This odd
     behavior is for MATLAB compatibility.

     The additional calling forms provide an interface to the underlying
     random number generator.  See *note ‘rand’: XREFrand. for
     documentation on querying and controlling the random number
     generator.

     Programming Note: By default, ‘randn’ uses the Marsaglia and Tsang
     "Ziggurat technique" to transform from a uniform to a normal
     distribution.

     Reference: G. Marsaglia and W.W. Tsang, "Ziggurat Method for
     Generating Random Variables", ‘J. Statistical Software’, Vol. 5,
     2000, <https://www.jstatsoft.org/v05/i08/>

     See also: *note rand: XREFrand, *note randi: XREFrandi, *note
     rande: XREFrande, *note randg: XREFrandg, *note randp: XREFrandp.

 -- : X = rande ()
 -- : X = rande (N)
 -- : X = rande (M, N, ...)
 -- : X = rande ([M, N, ...])
 -- : X = rande (..., CLASS)
 -- : V = rande ("state")
 -- : rande ("state", V)
 -- : rande ("state", "reset")
 -- : V = rande ("seed")
 -- : rande ("seed", V)
 -- : rande ("seed", "reset")
     Return a scalar, matrix, or N-dimensional array whose elements are
     random numbers from the exponential distribution with rate
     parameter ‘0’.

     If called with no arguments, return a scalar random value.

     If invoked with a single scalar integer argument N, return a square
     NxN matrix.

     If invoked with two or more scalar integer arguments, or a vector
     of integer values, return an array with the given dimensions.

     The optional argument CLASS specifies the class of the return
     array.  The only valid options are "double" (default) or "single".

     Programming Note: Any negative dimensions are treated as zero, and
     any zero dimensions will result in an empty matrix.  This odd
     behavior is for MATLAB compatibility.

     The additional calling forms provide an interface to the underlying
     random number generator.  See *note ‘rand’: XREFrand. for
     documentation on querying and controlling the random number
     generator.

     Programming Note: By default, ‘rande’ uses the Marsaglia and Tsang
     "Ziggurat technique" to transform from a uniform to an exponential
     distribution.

     Reference: G. Marsaglia and W.W. Tsang, "Ziggurat Method for
     Generating Random Variables", ‘J. Statistical Software’, Vol 5,
     2000, <https://www.jstatsoft.org/v05/i08/>

     See also: *note rand: XREFrand, *note randi: XREFrandi, *note
     randn: XREFrandn, *note randg: XREFrandg, *note randp: XREFrandp.

 -- : X = randp (L)
 -- : X = randp (L, N)
 -- : X = randp (L, M, N, ...)
 -- : X = randp (L, [M, N, ...])
 -- : X = randp (..., CLASS)
 -- : V = randp ("state")
 -- : randp ("state", V)
 -- : randp ("state", "reset")
 -- : V = randp ("seed")
 -- : randp ("seed", V)
 -- : randp ("seed", "reset")
     Return a scalar, matrix, or N-dimensional array whose elements are
     random numbers from the Poisson distribution with mean value
     parameter L.

     If called with no size arguments, return a scalar random value.

     If invoked with a single scalar size argument N, return a square
     NxN matrix.

     If invoked with two or more scalar integer size arguments, or a
     vector of integer values, return an array with the given
     dimensions.

     The optional argument CLASS specifies the class of the return
     array.  The only valid options are "double" (default) or "single".

     Programming Note: Any negative dimensions are treated as zero, and
     any zero dimensions will result in an empty matrix.  This odd
     behavior is for MATLAB compatibility.

     The additional calling forms provide an interface to the underlying
     random number generator.  See *note ‘rand’: XREFrand. for
     documentation on querying and controlling the random number
     generator.

     Programming Notes: Five different algorithms are used depending on
     the range of L and whether L is a scalar or a matrix.

     For scalar L ≤ 12, use direct method.
          W.H. Press, et al., ‘Numerical Recipes in C’, Cambridge
          University Press, 1992.

     For scalar L > 12, use rejection method.[1]
          W.H. Press, et al., ‘Numerical Recipes in C’, Cambridge
          University Press, 1992.

     For matrix L ≤ 10, use inversion method.[2]
          E. Stadlober, et al., WinRand source code, available via FTP.

     For matrix L > 10, use patchwork rejection method.
          E. Stadlober, et al., WinRand source code, available via FTP,
          or H. Zechner, ‘Efficient sampling from continuous and
          discrete unimodal distributions’, Doctoral Dissertation,
          pp. 156, Technical University Graz, Austria, 1994.

     For L > 1e8, use normal approximation.
          L. Montanet, et al., "Review of Particle Properties",
          ‘Physical Review D’, 50, p. 1284, 1994.

     See also: *note rand: XREFrand, *note randi: XREFrandi, *note
     randn: XREFrandn, *note rande: XREFrande, *note randg: XREFrandg.

 -- : X = randg (A)
 -- : X = randg (A, N)
 -- : X = randg (A, M, N, ...)
 -- : X = randg (A, [M, N, ...])
 -- : X = randg (..., CLASS)
 -- : V = randg ("state")
 -- : randg ("state", V)
 -- : randg ("state", "reset")
 -- : V = randg ("seed")
 -- : randg ("seed", V)
 -- : randg ("seed", "reset")
     Return a scalar, matrix, or N-dimensional array whose elements are
     random numbers from the gamma distribution ‘gamma (A,1)’.

     If called with no size arguments, return a scalar random value.

     If invoked with a single scalar size argument N, return a square
     NxN matrix.

     If invoked with two or more scalar integer size arguments, or a
     vector of integer values, return an array with the given
     dimensions.

     The optional argument CLASS specifies the class of the return
     array.  The only valid options are "double" (default) or "single".

     Programming Note: Any negative dimensions are treated as zero, and
     any zero dimensions will result in an empty matrix.  This odd
     behavior is for MATLAB compatibility.

     The additional calling forms provide an interface to the underlying
     random number generator.  See *note ‘rand’: XREFrand. for
     documentation on querying and controlling the random number
     generator.

     Programming Notes: The gamma distribution can be used to generate
     many other distributions:

     ‘gamma (a, b)’ for ‘a > -1’, ‘b > 0’

               r = b * randg (a)

     ‘beta (a, b)’ for ‘a > -1’, ‘b > -1’

               r1 = randg (a, 1)
               r = r1 / (r1 + randg (b, 1))

     ‘Erlang (a, n)’

               r = a * randg (n)

     ‘chisq (df)’ for ‘df > 0’

               r = 2 * randg (df / 2)

     ‘t (df)’ for ‘0 < df < inf’ (use randn if df is infinite)

               r = randn () / sqrt (2 * randg (df / 2) / df)

     ‘F (n1, n2)’ for ‘0 < n1’, ‘0 < n2’

               ## r1 equals 1 if n1 is infinite
               r1 = 2 * randg (n1 / 2) / n1
               ## r2 equals 1 if n2 is infinite
               r2 = 2 * randg (n2 / 2) / n2
               r = r1 / r2

     negative ‘binomial (n, p)’ for ‘n > 0’, ‘0 < p <= 1’

               r = randp ((1 - p) / p * randg (n))

     non-central ‘chisq (df, L)’, for ‘df >= 0’ and ‘L > 0’
          (use chisq if ‘L = 0’)

               r = randp (L / 2)
               r(r > 0) = 2 * randg (r(r > 0))
               r(df > 0) += 2 * randg (df(df > 0)/2)

     ‘Dirichlet (a1, ... ak)’

               r = (randg (a1), ..., randg (ak))
               r = r / sum (r)

     See also: *note rand: XREFrand, *note randi: XREFrandi, *note
     randn: XREFrandn, *note rande: XREFrande, *note randp: XREFrandp.

 -- : rng (SEED)
 -- : rng (SEED, "GENERATOR")
 -- : rng ("shuffle")
 -- : rng ("shuffle", "GENERATOR")
 -- : rng ("default")
 -- : S = rng ()
 -- : rng (S)
 -- : S = rng (...)
     Set or query the seed of the random number generator used by ‘rand’
     and ‘randn’.

     The input SEED is a scalar numeric value used to initialize the
     state vector of the random number generator.

     The optional string GENERATOR specifies the type of random number
     generator to be used.  Its value can be "twister", "v5uniform", or
     "v5normal".  The "twister" keyword is described below.  "v5uniform"
     and "v5normal" refer to older versions of Octave that used to use a
     different random number generator.

     The state or seed of the random number generator can be reset to a
     new random value using the "shuffle" keyword.

     The random number generator can be reset to default values using
     the "default" keyword.  The default values are to use the Mersenne
     Twister generator with a seed of 0.

     The optional return value S contains the state of the random number
     generator at the time the function is called (i.e., before it might
     be modified according to the input arguments).  It is encoded as a
     structure variable with three fields: "Type", "Seed", and "State".
     The random number generator can be restored to the state S using
     ‘rng (S)’.  This is useful when the identical sequence of
     pseudo-random numbers is required for an algorithm.

     By default, and with the "twister" option, pseudo-random sequences
     are computed using the Mersenne Twister with a period of
     2^{19937}-1 (See M. Matsumoto and T. Nishimura, "Mersenne Twister:
     A 623-dimensionally equidistributed uniform pseudorandom number
     generator", ‘ACM Trans. on Modeling and Computer Simulation’,
     Vol. 8, No. 1, pp. 3-30, January 1998,
     <http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html>).  Do
     *not* use for cryptography without securely hashing several
     returned values together, otherwise the generator state can be
     learned after reading 624 consecutive values.

     See also: *note rand: XREFrand, *note randn: XREFrandn.

 The generators operate in the new or old style together, it is not
possible to mix the two.  Initializing any generator with "state" or
"seed" causes the others to switch to the same style for future calls.

 The state of each generator is independent and calls to different
generators can be interleaved without affecting the final result.  For
example,

     rand ("state", [11, 22, 33]);
     randn ("state", [44, 55, 66]);
     u = rand (100, 1);
     n = randn (100, 1);

and

     rand ("state", [11, 22, 33]);
     randn ("state", [44, 55, 66]);
     u = zeros (100, 1);
     n = zeros (100, 1);
     for i = 1:100
       u(i) = rand ();
       n(i) = randn ();
     end

produce equivalent results.  When the generators are initialized in the
old style with "seed" only ‘rand’ and ‘randn’ are independent, because
the old ‘rande’, ‘randg’ and ‘randp’ generators make calls to ‘rand’ and
‘randn’.

 The generators are initialized with random states at start-up, so that
the sequences of random numbers are not the same each time you run
Octave.(1)  If you really do need to reproduce a sequence of numbers
exactly, you can set the state or seed to a specific value.

 If invoked without arguments, ‘rand’ and ‘randn’ return a single
element of a random sequence.

 The original ‘rand’ and ‘randn’ functions use Fortran code from RANLIB,
a library of Fortran routines for random number generation, compiled by
Barry W. Brown and James Lovato of the Department of Biomathematics at
The University of Texas, M.D. Anderson Cancer Center, Houston, TX 77030.

 -- : V = randperm (N)
 -- : V = randperm (N, M)
     Return a row vector containing a random permutation of ‘1:N’.

     If M is supplied, return M unique entries, sampled without
     replacement from ‘1:N’.

     The complexity is O(N) in memory and O(M) in time, unless M < N/5,
     in which case O(M) memory is used as well.  The randomization is
     performed using rand().  All permutations are equally likely.

     See also: *note perms: XREFperms.

   ---------- Footnotes ----------

   (1) The old versions of ‘rand’ and ‘randn’ obtain their initial seeds
from the system clock.


File: octave.info,  Node: Famous Matrices,  Prev: Special Utility Matrices,  Up: Matrix Manipulation

16.4 Famous Matrices
====================

The following functions return famous matrix forms.

 -- : gallery (NAME)
 -- : gallery (NAME, ARGS)
     Create interesting matrices for testing.

 -- : C = gallery ("cauchy", X)
 -- : C = gallery ("cauchy", X, Y)
     Create a Cauchy matrix.

 -- : C = gallery ("chebspec", N)
 -- : C = gallery ("chebspec", N, K)
     Create a Chebyshev spectral differentiation matrix.

 -- : C = gallery ("chebvand", P)
 -- : C = gallery ("chebvand", M, P)
     Create a Vandermonde-like matrix for the Chebyshev polynomials.

 -- : A = gallery ("chow", N)
 -- : A = gallery ("chow", N, ALPHA)
 -- : A = gallery ("chow", N, ALPHA, DELTA)
     Create a Chow matrix - a singular Toeplitz lower Hessenberg matrix.

 -- : C = gallery ("circul", V)
     Create a circulant matrix.

 -- : A = gallery ("clement", N)
 -- : A = gallery ("clement", N, K)
     Create a tridiagonal matrix with zero diagonal entries.

 -- : C = gallery ("compar", A)
 -- : C = gallery ("compar", A, K)
     Create a comparison matrix.

 -- : A = gallery ("condex", N)
 -- : A = gallery ("condex", N, K)
 -- : A = gallery ("condex", N, K, THETA)
     Create a "counterexample" matrix to a condition estimator.

 -- : A = gallery ("cycol", [M N])
 -- : A = gallery ("cycol", N)
 -- : A = gallery (..., K)
     Create a matrix whose columns repeat cyclically.

 -- : [C, D, E] = gallery ("dorr", N)
 -- : [C, D, E] = gallery ("dorr", N, THETA)
 -- : A = gallery ("dorr", ...)
     Create a diagonally dominant, ill-conditioned, tridiagonal matrix.

 -- : A = gallery ("dramadah", N)
 -- : A = gallery ("dramadah", N, K)
     Create a (0, 1) matrix whose inverse has large integer entries.

 -- : A = gallery ("fiedler", C)
     Create a symmetric Fiedler matrix.

 -- : A = gallery ("forsythe", N)
 -- : A = gallery ("forsythe", N, ALPHA)
 -- : A = gallery ("forsythe", N, ALPHA, LAMBDA)
     Create a Forsythe matrix (a perturbed Jordan block).

 -- : F = gallery ("frank", N)
 -- : F = gallery ("frank", N, K)
     Create a Frank matrix (ill-conditioned eigenvalues).

 -- : C = gallery ("gcdmat", N)
     Create a greatest common divisor matrix.

     C is an N-by-N matrix whose values correspond to the greatest
     common divisor of its coordinate values, i.e., C(i,j) correspond
     ‘gcd (i, j)’.

 -- : A = gallery ("gearmat", N)
 -- : A = gallery ("gearmat", N, I)
 -- : A = gallery ("gearmat", N, I, J)
     Create a Gear matrix.

 -- : G = gallery ("grcar", N)
 -- : G = gallery ("grcar", N, K)
     Create a Toeplitz matrix with sensitive eigenvalues.

 -- : A = gallery ("hanowa", N)
 -- : A = gallery ("hanowa", N, D)
     Create a matrix whose eigenvalues lie on a vertical line in the
     complex plane.

 -- : V = gallery ("house", X)
 -- : [V, BETA] = gallery ("house", X)
     Create a householder matrix.

 -- : A = gallery ("integerdata", IMAX, [M N ...], J)
 -- : A = gallery ("integerdata", IMAX, M, N, ..., J)
 -- : A = gallery ("integerdata", [IMIN, IMAX], [M N ...], J)
 -- : A = gallery ("integerdata", [IMIN, IMAX], M, N, ..., J)
 -- : A = gallery ("integerdata", ..., "CLASS")
     Create a matrix with random integers in the range [1, IMAX].  If
     IMIN is given then the integers are in the range [IMIN, IMAX].

     The second input is a matrix of dimensions describing the size of
     the output.  The dimensions can also be input as comma-separated
     arguments.

     The input J is an integer index in the range [0, 2^32-1].  The
     values of the output matrix are always exactly the same
     (reproducibility) for a given size input and J index.

     The final optional argument determines the class of the resulting
     matrix.  Possible values for CLASS: "uint8", "uint16", "uint32",
     "int8", "int16", int32", "single", "double".  The default is
     "double".

 -- : A = gallery ("invhess", X)
 -- : A = gallery ("invhess", X, Y)
     Create the inverse of an upper Hessenberg matrix.

 -- : A = gallery ("invol", N)
     Create an involutory matrix.

 -- : A = gallery ("ipjfact", N)
 -- : A = gallery ("ipjfact", N, K)
     Create a Hankel matrix with factorial elements.

 -- : A = gallery ("jordbloc", N)
 -- : A = gallery ("jordbloc", N, LAMBDA)
     Create a Jordan block.

 -- : U = gallery ("kahan", N)
 -- : U = gallery ("kahan", N, THETA)
 -- : U = gallery ("kahan", N, THETA, PERT)
     Create a Kahan matrix (upper trapezoidal).

 -- : A = gallery ("kms", N)
 -- : A = gallery ("kms", N, RHO)
     Create a Kac-Murdock-Szego Toeplitz matrix.

 -- : B = gallery ("krylov", A)
 -- : B = gallery ("krylov", A, X)
 -- : B = gallery ("krylov", A, X, J)
     Create a Krylov matrix.

 -- : A = gallery ("lauchli", N)
 -- : A = gallery ("lauchli", N, MU)
     Create a Lauchli matrix (rectangular).

 -- : A = gallery ("lehmer", N)
     Create a Lehmer matrix (symmetric positive definite).

 -- : T = gallery ("lesp", N)
     Create a tridiagonal matrix with real, sensitive eigenvalues.

 -- : A = gallery ("lotkin", N)
     Create a Lotkin matrix.

 -- : A = gallery ("minij", N)
     Create a symmetric positive definite matrix MIN(i,j).

 -- : A = gallery ("moler", N)
 -- : A = gallery ("moler", N, ALPHA)
     Create a Moler matrix (symmetric positive definite).

 -- : [A, T] = gallery ("neumann", N)
     Create a singular matrix from the discrete Neumann problem
     (sparse).

 -- : A = gallery ("normaldata", [M N ...], J)
 -- : A = gallery ("normaldata", M, N, ..., J)
 -- : A = gallery ("normaldata", ..., "CLASS")
     Create a matrix with random samples from the standard normal
     distribution (mean = 0, std = 1).

     The first input is a matrix of dimensions describing the size of
     the output.  The dimensions can also be input as comma-separated
     arguments.

     The input J is an integer index in the range [0, 2^32-1].  The
     values of the output matrix are always exactly the same
     (reproducibility) for a given size input and J index.

     The final optional argument determines the class of the resulting
     matrix.  Possible values for CLASS: "single", "double".  The
     default is "double".

 -- : Q = gallery ("orthog", N)
 -- : Q = gallery ("orthog", N, K)
     Create orthogonal and nearly orthogonal matrices.

 -- : A = gallery ("parter", N)
     Create a Parter matrix (a Toeplitz matrix with singular values near
     pi).

 -- : P = gallery ("pei", N)
 -- : P = gallery ("pei", N, ALPHA)
     Create a Pei matrix.

 -- : A = gallery ("poisson", N)
     Create a block tridiagonal matrix from Poisson's equation (sparse).

 -- : A = gallery ("prolate", N)
 -- : A = gallery ("prolate", N, W)
     Create a prolate matrix (symmetric, ill-conditioned Toeplitz
     matrix).

 -- : H = gallery ("randhess", X)
     Create a random, orthogonal upper Hessenberg matrix.

 -- : A = gallery ("rando", N)
 -- : A = gallery ("rando", N, K)
     Create a random matrix with elements -1, 0 or 1.

 -- : A = gallery ("randsvd", N)
 -- : A = gallery ("randsvd", N, KAPPA)
 -- : A = gallery ("randsvd", N, KAPPA, MODE)
 -- : A = gallery ("randsvd", N, KAPPA, MODE, KL)
 -- : A = gallery ("randsvd", N, KAPPA, MODE, KL, KU)
     Create a random matrix with pre-assigned singular values.

 -- : A = gallery ("redheff", N)
     Create a zero and ones matrix of Redheffer associated with the
     Riemann hypothesis.

 -- : A = gallery ("riemann", N)
     Create a matrix associated with the Riemann hypothesis.

 -- : A = gallery ("ris", N)
     Create a symmetric Hankel matrix.

 -- : A = gallery ("smoke", N)
 -- : A = gallery ("smoke", N, K)
     Create a complex matrix, with a "smoke ring" pseudospectrum.

 -- : T = gallery ("toeppd", N)
 -- : T = gallery ("toeppd", N, M)
 -- : T = gallery ("toeppd", N, M, W)
 -- : T = gallery ("toeppd", N, M, W, THETA)
     Create a symmetric positive definite Toeplitz matrix.

 -- : P = gallery ("toeppen", N)
 -- : P = gallery ("toeppen", N, A)
 -- : P = gallery ("toeppen", N, A, B)
 -- : P = gallery ("toeppen", N, A, B, C)
 -- : P = gallery ("toeppen", N, A, B, C, D)
 -- : P = gallery ("toeppen", N, A, B, C, D, E)
     Create a pentadiagonal Toeplitz matrix (sparse).

 -- : A = gallery ("tridiag", X, Y, Z)
 -- : A = gallery ("tridiag", N)
 -- : A = gallery ("tridiag", N, C, D, E)
     Create a tridiagonal matrix (sparse).

 -- : T = gallery ("triw", N)
 -- : T = gallery ("triw", N, ALPHA)
 -- : T = gallery ("triw", N, ALPHA, K)
     Create an upper triangular matrix discussed by Kahan, Golub, and
     Wilkinson.

 -- : A = gallery ("uniformdata", [M N ...], J)
 -- : A = gallery ("uniformdata", M, N, ..., J)
 -- : A = gallery ("uniformdata", ..., "CLASS")
     Create a matrix with random samples from the standard uniform
     distribution (range [0,1]).

     The first input is a matrix of dimensions describing the size of
     the output.  The dimensions can also be input as comma-separated
     arguments.

     The input J is an integer index in the range [0, 2^32-1].  The
     values of the output matrix are always exactly the same
     (reproducibility) for a given size input and J index.

     The final optional argument determines the class of the resulting
     matrix.  Possible values for CLASS: "single", "double".  The
     default is "double".

 -- : A = gallery ("wathen", NX, NY)
 -- : A = gallery ("wathen", NX, NY, K)
     Create the Wathen matrix.

 -- : [A, B] = gallery ("wilk", N)
     Create various specific matrices devised/discussed by Wilkinson.

 -- : H = hadamard (N)
     Construct a Hadamard matrix (Hn) of size N-by-N.

     The size N must be of the form 2^k * p in which p is one of 1, 12,
     20 or 28.  The returned matrix is normalized, meaning
     ‘Hn(:,1) == 1’ and ‘Hn(1,:) == 1’.

     Some of the properties of Hadamard matrices are:

        • ‘kron (Hm, Hn)’ is a Hadamard matrix of size M-by-N.

        • ‘Hn * Hn' = N * eye (N)’.

        • The rows of Hn are orthogonal.

        • ‘det (A) <= abs (det (Hn))’ for all A with
          ‘abs (A(i, j)) <= 1’.

        • Multiplying any row or column by -1 and the matrix will remain
          a Hadamard matrix.

     See also: *note compan: XREFcompan, *note hankel: XREFhankel, *note
     toeplitz: XREFtoeplitz.

 -- : H = hankel (C)
 -- : H = hankel (C, R)
     Return the Hankel matrix constructed from the first column C, and
     (optionally) the last row R.

     If the last element of C is not the same as the first element of R,
     the last element of C is used.  If the second argument is omitted,
     it is assumed to be a vector of zeros with the same size as C.

     A Hankel matrix formed from an m-vector C, and an n-vector R, has
     the elements

          H(i,j) = c(i+j-1),  i+j-1 <= m;
          H(i,j) = r(i+j-m),  otherwise

     See also: *note hadamard: XREFhadamard, *note toeplitz:
     XREFtoeplitz.

 -- : H = hilb (N)
     Return the Hilbert matrix of order N.

     The i,j element of a Hilbert matrix is defined as

          H(i, j) = 1 / (i + j - 1)

     Hilbert matrices are close to being singular which make them
     difficult to invert with numerical routines.  Comparing the
     condition number of a random matrix 5x5 matrix with that of a
     Hilbert matrix of order 5 reveals just how difficult the problem
     is.

          cond (rand (5))
             ⇒ 14.392
          cond (hilb (5))
             ⇒ 4.7661e+05

     See also: *note invhilb: XREFinvhilb.

 -- : HINV = invhilb (N)
     Return the inverse of the Hilbert matrix of order N.

     This can be computed exactly using


                     (i+j)         /n+i-1\  /n+j-1\   /i+j-2\ 2
          A(i,j) = -1      (i+j-1)(       )(       ) (       )
                                   \ n-j /  \ n-i /   \ i-2 /

                 = p(i) p(j) / (i+j-1)


     where

                   k  /k+n-1\   /n\
          p(k) = -1  (       ) (   )
                      \ k-1 /   \k/

     The validity of this formula can easily be checked by expanding the
     binomial coefficients in both formulas as factorials.  It can be
     derived more directly via the theory of Cauchy matrices.  See J. W.
     Demmel, ‘Applied Numerical Linear Algebra’, p. 92.

     Compare this with the numerical calculation of ‘inv (hilb (n))’,
     which suffers from the ill-conditioning of the Hilbert matrix, and
     the finite precision of your computer's floating point arithmetic.

     See also: *note hilb: XREFhilb.

 -- : M = magic (N)

     Create an N-by-N magic square.

     A magic square is an arrangement of the integers ‘1:n^2’ such that
     the row sums, column sums, and diagonal sums are all equal to the
     same value.

     Note: N must be a scalar greater than or equal to 3.  If you supply
     N less than 3, magic returns either a nonmagic square, or else the
     degenerate magic squares 1 and [].

 -- : P = pascal (N)
 -- : P = pascal (N, T)
     Return the Pascal matrix of order N if ‘T = 0’.

     The default value of T is 0.

     When ‘T = 1’, return the pseudo-lower triangular Cholesky factor of
     the Pascal matrix (The sign of some columns may be negative).  This
     matrix is its own inverse, that is ‘pascal (N, 1) ^ 2 == eye (N)’.

     If ‘T = -1’, return the true Cholesky factor with strictly positive
     values on the diagonal.

     If ‘T = 2’, return a transposed and permuted version of ‘pascal (N,
     1)’, which is the cube root of the identity matrix.  That is,
     ‘pascal (N, 2) ^ 3 == eye (N)’.

     See also: *note chol: XREFchol.

 -- : R = rosser ()
     Return the Rosser matrix.

     This is a difficult test case used to evaluate eigenvalue
     algorithms.

     See also: *note wilkinson: XREFwilkinson, *note eig: XREFeig.

 -- : T = toeplitz (C)
 -- : T = toeplitz (C, R)
     Return the Toeplitz matrix constructed from the first column C, and
     optionally the first row R.

     If the second argument is omitted, the first row is taken to be the
     same as the first column.  If the first element of R is not the
     same as the first element of C, the first element of C is used.

     A Toeplitz, or diagonal-constant, matrix has the same value along
     each diagonal.  Although it need not be square, it often is.  An
     MxN Toeplitz matrix has the form:

          c(1)  r(2)   r(3)  ...  r(n)
          c(2)  c(1)   r(2)  ... r(n-1)
          c(3)  c(2)   c(1)  ... r(n-2)
           .     .      .   .      .
           .     .      .     .    .
           .     .      .       .  .
          c(m) c(m-1) c(m-2) ... c(m-n+1)

     See also: *note hankel: XREFhankel.

 -- : V = vander (C)
 -- : V = vander (C, N)
     Return the Vandermonde matrix whose next to last column is C.

     If N is specified, it determines the number of columns; otherwise,
     N is taken to be equal to the length of C.

     A Vandermonde matrix has the form:

          c(1)^(n-1) ... c(1)^2  c(1)  1
          c(2)^(n-1) ... c(2)^2  c(2)  1
              .     .      .      .    .
              .       .    .      .    .
              .         .  .      .    .
          c(n)^(n-1) ... c(n)^2  c(n)  1

     See also: *note polyfit: XREFpolyfit.

 -- : W = wilkinson (N)
     Return the Wilkinson matrix of order N.

     Wilkinson matrices are symmetric and tridiagonal with pairs of
     nearly, but not exactly, equal eigenvalues.  They are useful in
     testing the behavior and performance of eigenvalue solvers.

     See also: *note rosser: XREFrosser, *note eig: XREFeig.


File: octave.info,  Node: Arithmetic,  Next: Linear Algebra,  Prev: Matrix Manipulation,  Up: Top

17 Arithmetic
*************

Unless otherwise noted, all of the functions described in this chapter
will work for real and complex scalar, vector, or matrix arguments.
Functions described as “mapping functions” apply the given operation
individually to each element when given a matrix argument.  For example:

     sin ([1, 2; 3, 4])
          ⇒  0.84147   0.90930
              0.14112  -0.75680

* Menu:

* Exponents and Logarithms::
* Complex Arithmetic::
* Trigonometry::
* Sums and Products::
* Utility Functions::
* Special Functions::
* Rational Approximations::
* Coordinate Transformations::
* Mathematical Constants::


File: octave.info,  Node: Exponents and Logarithms,  Next: Complex Arithmetic,  Up: Arithmetic

17.1 Exponents and Logarithms
=============================

 -- : Y = exp (X)
     Compute ‘e^x’ for each element of X.

     To compute the matrix exponential, *note Linear Algebra::.

     See also: *note log: XREFlog.

 -- : Y = expm1 (X)
     Compute ‘exp (X) - 1’ accurately in the neighborhood of zero.

     See also: *note exp: XREFexp.

 -- : Y = log (X)
     Compute the natural logarithm, ‘ln (X)’, for each element of X.

     To compute the matrix logarithm, *note Linear Algebra::.

     See also: *note exp: XREFexp, *note log1p: XREFlog1p, *note log2:
     XREFlog2, *note log10: XREFlog10, *note logspace: XREFlogspace.

 -- : Y = reallog (X)
     Return the real-valued natural logarithm of each element of X.

     If any element results in a complex return value ‘reallog’ aborts
     and issues an error.

     See also: *note log: XREFlog, *note realpow: XREFrealpow, *note
     realsqrt: XREFrealsqrt.

 -- : Y = log1p (X)
     Compute ‘log (1 + X)’ accurately in the neighborhood of zero.

     See also: *note log: XREFlog, *note exp: XREFexp, *note expm1:
     XREFexpm1.

 -- : Y = log10 (X)
     Compute the base-10 logarithm of each element of X.

     See also: *note log: XREFlog, *note log2: XREFlog2, *note logspace:
     XREFlogspace, *note exp: XREFexp.

 -- : Y = log2 (X)
 -- : [F, E] = log2 (X)
     Compute the base-2 logarithm of each element of X.

     If called with one output, compute the base-2 logarithm such that
     ‘2^Y = X’.

     If called with two output arguments, split X into binary mantissa
     (F) and exponent (E) such that ‘X = F * 2^E’ where
     ‘1/2 <= abs (F) < 1’ and E is an integer.  If ‘x = 0’, ‘f = e = 0’.

     See also: *note pow2: XREFpow2, *note log: XREFlog, *note log10:
     XREFlog10, *note exp: XREFexp.

 -- : Y = pow2 (X)
 -- : Y = pow2 (F, E)
     With one input argument, compute y = 2 .^ x for each element of X.

     With two input arguments, return y = f .* (2 .^ e).  where for
     complex inputs only the real part of both inputs is regarded and
     from E only the real integer part.  This calling form corresponds
     to C/C++ standard function ‘ldexp()’.

     See also: *note log2: XREFlog2, *note nextpow2: XREFnextpow2, *note
     power: XREFpower.

 -- : N = nextpow2 (X)
     Compute the exponent of the next power of two not smaller than the
     input.

     For each element in the input array X, return the smallest integer
     N such that ‘2^N ≥ abs (X)’.  For input elements equal to zero,
     return zero.

     See also: *note pow2: XREFpow2, *note log2: XREFlog2.

 -- : Z = realpow (X, Y)
     Compute the real-valued, element-by-element power operator.

     This is equivalent to ‘X .^ Y’, except that ‘realpow’ reports an
     error if any return value is complex.

     See also: *note power: XREFpower, *note reallog: XREFreallog, *note
     realsqrt: XREFrealsqrt.

 -- : Y = sqrt (X)
     Compute the square root of each element of X.

     If X is negative, a complex result is returned.

     To compute the matrix square root, *note Linear Algebra::.

     See also: *note realsqrt: XREFrealsqrt, *note nthroot: XREFnthroot.

 -- : Y = realsqrt (X)
     Return the real-valued square root of each element of X.

     If any element results in a complex return value ‘realsqrt’ aborts
     and issues an error.

     See also: *note sqrt: XREFsqrt, *note realpow: XREFrealpow, *note
     reallog: XREFreallog.

 -- : Y = cbrt (X)
     Compute the real-valued cube root of each element of X.

     Unlike ‘X^(1/3)’, the result will be negative if X is negative.

     If any element of X is complex, ‘cbrt’ aborts with an error.

     See also: *note nthroot: XREFnthroot.

 -- : Y = nthroot (X, N)

     Compute the real (non-complex) N-th root of X.

     X must have all real entries and N must be a scalar.  If N is an
     even integer and X has negative entries then ‘nthroot’ aborts and
     issues an error.

     Example:

          nthroot (-1, 3)
          ⇒ -1
          (-1) ^ (1 / 3)
          ⇒ 0.50000 - 0.86603i

     See also: *note realsqrt: XREFrealsqrt, *note sqrt: XREFsqrt, *note
     cbrt: XREFcbrt.


File: octave.info,  Node: Complex Arithmetic,  Next: Trigonometry,  Prev: Exponents and Logarithms,  Up: Arithmetic

17.2 Complex Arithmetic
=======================

In the descriptions of the following functions, Z is the complex number
X + IY, where I is defined as ‘sqrt (-1)’.

 -- : Z = abs (X)
     Compute the magnitude of X.

     The magnitude is defined as |Z| = ‘sqrt (x^2 + y^2)’.

     For example:

          abs (3 + 4i)
               ⇒ 5

     See also: *note arg: XREFarg.

 -- : THETA = arg (Z)
 -- : THETA = angle (Z)
     Compute the argument, i.e., angle of Z.

     This is defined as, THETA = ‘atan2 (Y, X)’, in radians.

     For example:

          arg (3 + 4i)
               ⇒ 0.92730

     See also: *note abs: XREFabs.

 -- : ZC = conj (Z)
     Return the complex conjugate of Z.

     The complex conjugate is defined as ‘conj (Z)’ = X - IY.

     See also: *note real: XREFreal, *note imag: XREFimag.

 -- : ZSORT = cplxpair (Z)
 -- : ZSORT = cplxpair (Z, TOL)
 -- : ZSORT = cplxpair (Z, TOL, DIM)
     Sort the numbers Z into complex conjugate pairs ordered by
     increasing real part.

     The negative imaginary complex numbers are placed first within each
     pair.  All real numbers (those with ‘abs (imag (Z)) / abs (Z) <
     TOL’) are placed after the complex pairs.

     TOL is a weighting factor in the range [0, 1) which determines the
     tolerance of the matching.  The default value is ‘100 * eps’ and
     the resulting tolerance for a given complex pair is ‘TOL * abs
     (Z(i)))’.

     By default the complex pairs are sorted along the first
     non-singleton dimension of Z.  If DIM is specified, then the
     complex pairs are sorted along this dimension.

     Signal an error if some complex numbers could not be paired.
     Signal an error if all complex numbers are not exact conjugates (to
     within TOL).  Note that there is no defined order for pairs with
     identical real parts but differing imaginary parts.

          cplxpair (exp (2i*pi*[0:4]'/5)) == exp (2i*pi*[3; 2; 4; 1; 0]/5)

 -- : Y = imag (Z)
     Return the imaginary part of Z as a real number.

     See also: *note real: XREFreal, *note conj: XREFconj.

 -- : X = real (Z)
     Return the real part of Z.

     See also: *note imag: XREFimag, *note conj: XREFconj.


File: octave.info,  Node: Trigonometry,  Next: Sums and Products,  Prev: Complex Arithmetic,  Up: Arithmetic

17.3 Trigonometry
=================

Octave provides the following trigonometric functions where angles are
specified in radians.  To convert from degrees to radians multiply by
‘pi/180’ or use the ‘deg2rad’ function.  For example, ‘sin (30 *
pi/180)’ returns the sine of 30 degrees.  As an alternative, Octave
provides a number of trigonometric functions which work directly on an
argument specified in degrees.  These functions are named after the base
trigonometric function with a ‘d’ suffix.  As an example, ‘sin’ expects
an angle in radians while ‘sind’ expects an angle in degrees.

 Octave uses the C library trigonometric functions.  It is expected that
these functions are defined by the ISO/IEC 9899 Standard.  This Standard
is available at:
<http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf>.  Section
F.9.1 deals with the trigonometric functions.  The behavior of most of
the functions is relatively straightforward.  However, there are some
exceptions to the standard behavior.  Many of the exceptions involve the
behavior for -0.  The most complex case is atan2.  Octave exactly
implements the behavior given in the Standard.  Including ‘atan2(+- 0,
0)’ returns ‘+- pi’.

 It should be noted that MATLAB uses different definitions which
apparently do not distinguish -0.

 -- : RAD = deg2rad (DEG)

     Convert degrees to radians.

     The input DEG must be a scalar, vector, or N-dimensional array of
     double or single floating point values.  DEG may be complex in
     which case the real and imaginary components are converted
     separately.

     The output RAD is the same size and shape as DEG with degrees
     converted to radians using the conversion constant ‘pi/180’.

     Example:

          deg2rad ([0, 90, 180, 270, 360])
            ⇒  0.00000   1.57080   3.14159   4.71239   6.28319

     See also: *note rad2deg: XREFrad2deg.

 -- : DEG = rad2deg (RAD)

     Convert radians to degrees.

     The input RAD must be a scalar, vector, or N-dimensional array of
     double or single floating point values.  RAD may be complex in
     which case the real and imaginary components are converted
     separately.

     The output DEG is the same size and shape as RAD with radians
     converted to degrees using the conversion constant ‘180/pi’.

     Example:

          rad2deg ([0, pi/2, pi, 3/2*pi, 2*pi])
            ⇒  0    90   180   270   360

     See also: *note deg2rad: XREFdeg2rad.

 -- : Y = sin (X)
     Compute the sine for each element of X in radians.

     See also: *note asin: XREFasin, *note sind: XREFsind, *note sinh:
     XREFsinh.

 -- : Y = cos (X)
     Compute the cosine for each element of X in radians.

     See also: *note acos: XREFacos, *note cosd: XREFcosd, *note cosh:
     XREFcosh.

 -- : Y = tan (Z)
     Compute the tangent for each element of X in radians.

     See also: *note atan: XREFatan, *note tand: XREFtand, *note tanh:
     XREFtanh.

 -- : Y = sec (X)
     Compute the secant for each element of X in radians.

     See also: *note asec: XREFasec, *note secd: XREFsecd, *note sech:
     XREFsech.

 -- : Y = csc (X)
     Compute the cosecant for each element of X in radians.

     See also: *note acsc: XREFacsc, *note cscd: XREFcscd, *note csch:
     XREFcsch.

 -- : Y = cot (X)
     Compute the cotangent for each element of X in radians.

     See also: *note acot: XREFacot, *note cotd: XREFcotd, *note coth:
     XREFcoth.

 -- : Y = asin (X)
     Compute the inverse sine in radians for each element of X.

     See also: *note sin: XREFsin, *note asind: XREFasind.

 -- : Y = acos (X)
     Compute the inverse cosine in radians for each element of X.

     See also: *note cos: XREFcos, *note acosd: XREFacosd.

 -- : Y = atan (X)
     Compute the inverse tangent in radians for each element of X.

     See also: *note tan: XREFtan, *note atand: XREFatand.

 -- : Y = asec (X)
     Compute the inverse secant in radians for each element of X.

     See also: *note sec: XREFsec, *note asecd: XREFasecd.

 -- : Y = acsc (X)
     Compute the inverse cosecant in radians for each element of X.

     See also: *note csc: XREFcsc, *note acscd: XREFacscd.

 -- : Y = acot (X)
     Compute the inverse cotangent in radians for each element of X.

     See also: *note cot: XREFcot, *note acotd: XREFacotd.

 -- : Y = sinh (X)
     Compute the hyperbolic sine for each element of X.

     See also: *note asinh: XREFasinh, *note cosh: XREFcosh, *note tanh:
     XREFtanh.

 -- : Y = cosh (X)
     Compute the hyperbolic cosine for each element of X.

     See also: *note acosh: XREFacosh, *note sinh: XREFsinh, *note tanh:
     XREFtanh.

 -- : Y = tanh (X)
     Compute hyperbolic tangent for each element of X.

     See also: *note atanh: XREFatanh, *note sinh: XREFsinh, *note cosh:
     XREFcosh.

 -- : Y = sech (X)
     Compute the hyperbolic secant of each element of X.

     See also: *note asech: XREFasech.

 -- : Y = csch (X)
     Compute the hyperbolic cosecant of each element of X.

     See also: *note acsch: XREFacsch.

 -- : Y = coth (X)
     Compute the hyperbolic cotangent of each element of X.

     See also: *note acoth: XREFacoth.

 -- : Y = asinh (X)
     Compute the inverse hyperbolic sine for each element of X.

     See also: *note sinh: XREFsinh.

 -- : Y = acosh (X)
     Compute the inverse hyperbolic cosine for each element of X.

     See also: *note cosh: XREFcosh.

 -- : Y = atanh (X)
     Compute the inverse hyperbolic tangent for each element of X.

     See also: *note tanh: XREFtanh.

 -- : Y = asech (X)
     Compute the inverse hyperbolic secant of each element of X.

     See also: *note sech: XREFsech.

 -- : Y = acsch (X)
     Compute the inverse hyperbolic cosecant of each element of X.

     See also: *note csch: XREFcsch.

 -- : Y = acoth (X)
     Compute the inverse hyperbolic cotangent of each element of X.

     See also: *note coth: XREFcoth.

 -- : ANGLE = atan2 (Y, X)
     Compute atan (Y / X) for corresponding elements of Y and X.

     Y and X must match in size and orientation.  The signs of elements
     of Y and X are used to determine the quadrants of each resulting
     value.

     This function is equivalent to ‘arg (complex (X, Y))’.

     See also: *note tan: XREFtan, *note tand: XREFtand, *note tanh:
     XREFtanh, *note atanh: XREFatanh.

 Octave provides the following trigonometric functions where angles are
specified in degrees.  These functions produce true zeros at the
appropriate intervals rather than the small round-off error that occurs
when using radians.  For example:

     cosd (90)
          ⇒ 0
     cos (pi/2)
          ⇒ 6.1230e-17

 -- : Y = sind (X)
     Compute the sine for each element of X in degrees.

     The function is more accurate than ‘sin’ for large values of X and
     for multiples of 180 degrees (‘X/180’ is an integer) where ‘sind’
     returns 0 rather than a small value on the order of eps.

     See also: *note asind: XREFasind, *note sin: XREFsin.

 -- : Y = cosd (X)
     Compute the cosine for each element of X in degrees.

     The function is more accurate than ‘cos’ for large values of X and
     for multiples of 90 degrees (‘X = 90 + 180*n’ with n an integer)
     where ‘cosd’ returns 0 rather than a small value on the order of
     eps.

     See also: *note acosd: XREFacosd, *note cos: XREFcos.

 -- : Y = tand (X)
     Compute the tangent for each element of X in degrees.

     Returns zero for elements where ‘X/180’ is an integer and ‘Inf’ for
     elements where ‘(X-90)/180’ is an integer.

     See also: *note atand: XREFatand, *note tan: XREFtan.

 -- : Y = secd (X)
     Compute the secant for each element of X in degrees.

     See also: *note asecd: XREFasecd, *note sec: XREFsec.

 -- : Y = cscd (X)
     Compute the cosecant for each element of X in degrees.

     See also: *note acscd: XREFacscd, *note csc: XREFcsc.

 -- : Y = cotd (X)
     Compute the cotangent for each element of X in degrees.

     See also: *note acotd: XREFacotd, *note cot: XREFcot.

 -- : Y = asind (X)
     Compute the inverse sine in degrees for each element of X.

     See also: *note sind: XREFsind, *note asin: XREFasin.

 -- : Y = acosd (X)
     Compute the inverse cosine in degrees for each element of X.

     See also: *note cosd: XREFcosd, *note acos: XREFacos.

 -- : Y = atand (X)
     Compute the inverse tangent in degrees for each element of X.

     See also: *note tand: XREFtand, *note atan: XREFatan.

 -- : D = atan2d (Y, X)
     Compute atan (Y / X) in degrees for corresponding elements from Y
     and X.

     See also: *note tand: XREFtand, *note atan2: XREFatan2.

 -- : Y = asecd (X)
     Compute the inverse secant in degrees for each element of X.

     See also: *note secd: XREFsecd, *note asec: XREFasec.

 -- : Y = acscd (X)
     Compute the inverse cosecant in degrees for each element of X.

     See also: *note cscd: XREFcscd, *note acsc: XREFacsc.

 -- : Y = acotd (X)
     Compute the inverse cotangent in degrees for each element of X.

     See also: *note cotd: XREFcotd, *note acot: XREFacot.

 Finally, there are two trigonometric functions that calculate special
arguments with increased accuracy.

 -- : Y = sinpi (X)
     Compute sine (X * pi) for each element of X accurately.

     The ordinary ‘sin’ function uses IEEE 754 floating point numbers
     and may produce results that are very close (within a few eps) of
     the correct value, but which are not exact.  The ‘sinpi’ function
     is more accurate and returns 0 exactly for integer values of X and
     +1/-1 for half-integer values (e.g., ..., -3/2, -1/2, 1/2, 3/2,
     ...).

     Example
     comparison of ‘sin’ and ‘sinpi’ for integer values of X

          sin ([0, 1, 2, 3] * pi)
          ⇒
               0   1.2246e-16  -2.4493e-16   3.6739e-16

          sinpi ([0, 1, 2, 3])
          ⇒
                 0   0   0   0

     See also: *note cospi: XREFcospi, *note sin: XREFsin.

 -- : Y = cospi (X)
     Compute cosine (X * pi) for each element of X accurately.

     The ordinary ‘cos’ function uses IEEE 754 floating point numbers
     and may produce results that are very close (within a few eps) of
     the correct value, but which are not exact.  The ‘cospi’ function
     is more accurate and returns 0 exactly for half-integer values of X
     (e.g., ..., -3/2, -1/2, 1/2, 3/2, ...), and +1/-1 for integer
     values.

     Example
     comparison of ‘cos’ and ‘cospi’ for half-integer values of X

          cos ([-3/2, -1/2, 1/2, 3/2] * pi)
          ⇒
               -1.8370e-16   6.1232e-17   6.1232e-17  -1.8370e-16

          cospi ([-3/2, -1/2, 1/2, 3/2])
          ⇒
                 0   0   0   0

     See also: *note sinpi: XREFsinpi, *note cos: XREFcos.


File: octave.info,  Node: Sums and Products,  Next: Utility Functions,  Prev: Trigonometry,  Up: Arithmetic

17.4 Sums and Products
======================

 -- : Y = sum (X)
 -- : Y = sum (X, DIM)
 -- : Y = sum (X, VECDIM)
 -- : Y = sum (X, "all")
 -- : Y = sum (..., OUTTYPE)
 -- : Y = sum (..., NANFLAG)
     Compute the sum of the elements of X.

     If X is a vector, then ‘sum (X)’ returns the sum of the elements in
     X.

     If X is a matrix, then ‘sum (X)’ returns a row vector with each
     element containing the sum of the corresponding column in X.

     If X is an array, then ‘sum(X)’ computes the sum along the first
     non-singleton dimension of X.

     The optional input DIM specifies the dimension to operate on and
     must be a positive integer.  Specifying any singleton dimension in
     X, including any dimension exceeding ‘ndims (X)’, will return X.

     Specifying multiple dimensions with input VECDIM, a vector of
     non-repeating dimensions, will operate along the array slice
     defined by VECDIM.  If VECDIM indexes all dimensions of X, then it
     is equivalent to the option "all".  Any dimension in VECDIM greater
     than ‘ndims (X)’ is ignored.

     Specifying the dimension as "all" will cause ‘sum’ to operate on
     all elements of X, and is equivalent to ‘cumsum (X(:))’.

     The optional input OUTTYPE specifies the data type that is returned
     as well as the class of the variable used for calculations.
     OUTTYPE can take the following values:

     "default" : Operations on floating point inputs (double or
          single) are performed in their native data type, while
          operations on integer, logical, and character data types are
          performed using doubles.  Output is of type double, unless the
          input is single in which case the output is of type single.

     "double" : Operations are performed in double precision even for
          single precision inputs.  Output is of type double.

     "extra" : For double precision inputs, ‘sum’ will use a more
          accurate algorithm than straightforward summation.  For single
          precision inputs, "extra" is the same as "double".  For all
          other data type "extra" has no effect.

     "native" : Operations are performed in their native data types
          and output is of the same type as the input as reported by
          (‘class (X)’).  When the input is logical, ‘sum (X, "native")’
          is equivalent to ‘any (X)’.

     The optional variable NANFLAG specifies whether to include or
     exclude NaN values from the calculation using any of the previously
     specified input argument combinations.  The default value for
     NANFLAG is "includenan" which keeps NaN values in the calculation.
     To exclude NaN values set the value of NANFLAG to "omitnan".  The
     output will be 0, if X consists of all NaN values in the operating
     dimension.

     See also: *note cumsum: XREFcumsum, *note sumsq: XREFsumsq, *note
     prod: XREFprod.

 -- : Y = prod (X)
 -- : Y = prod (X, DIM)
 -- : Y = prod (X, VECDIM)
 -- : Y = prod (X, "all")
 -- : Y = prod (..., OUTTYPE)
 -- : Y = prod (..., NANFLAG)
     Compute the product of the elements of X.

     If X is a vector, then ‘prod (X)’ returns the product of the
     elements in X.

     If X is a matrix, then ‘prod (X)’ returns a row vector with each
     element containing the product of the corresponding column in X.

     If X is an array, then ‘prod(X)’ computes the product along the
     first non-singleton dimension of X.

     The optional input DIM specifies the dimension to operate on and
     must be a positive integer.  Specifying any singleton dimension in
     X, including any dimension exceeding ‘ndims (X)’, will return X.

     Specifying multiple dimensions with input VECDIM, a vector of
     non-repeating dimensions, will operate along the array slice
     defined by VECDIM.  If VECDIM indexes all dimensions of X, then it
     is equivalent to the option "all".  Any dimension in VECDIM greater
     than ‘ndims (X)’ is ignored.

     Specifying the dimension as "all" will cause ‘prod’ to operate on
     all elements of X, and is equivalent to ‘prod (X(:))’.

     The optional input OUTTYPE specifies the data type that is returned
     as well as the class of the variable used for calculations.
     OUTTYPE can take the following values:

     "default" : Operations on floating point inputs (double or
          single) are performed in their native data type, while
          operations on integer, logical, and character data types are
          performed using doubles.  Output is of type double, unless the
          input is single in which case the output is of type single.

     "double" : Operations are performed in double precision even for
          single precision inputs.  Output is of type double.

     "native" : Operations are performed in their native data types
          and output is of the same type as the input as reported by
          (‘class (X)’).  When the input is logical, ‘prod (X,
          "native")’ is equivalent to ‘all (X)’.

     The optional variable NANFLAG specifies whether to include or
     exclude NaN values from the calculation using any of the previously
     specified input argument combinations.  The default value for
     NANFLAG is "includenan" which keeps NaN values in the calculation.
     To exclude NaN values set the value of NANFLAG to "omitnan".  The
     output will be 1, if X consists of all NaN values in the operating
     dimension.

     See also: *note cumprod: XREFcumprod, *note sum: XREFsum.

 -- : Y = cumsum (X)
 -- : Y = cumsum (X, DIM)
 -- : Y = cumsum (X, VECDIM)
 -- : Y = cumsum (..., "all")
 -- : Y = cumsum (..., DIRECTION)
 -- : Y = cumsum (..., NANFLAG)
     Compute the cumulative sum of elements in X.

     If X is a vector, then ‘cumsum (X)’ returns a vector of the same
     size with the cumulative sum of X.

     If X is a matrix, then ‘cumsum (X)’ returns a matrix of the same
     size with the cumulative sum along each column of X.

     If X is an array, then ‘cumsum(X)’ returns an array of the same
     size with the cumulative sum along the first non-singleton
     dimension of X.

     The class of output Y is the same as the class of input X, unless X
     is logical, in which case Y is double.

     The optional input DIM specifies the dimension to operate on and
     must be a positive integer.  Specifying any singleton dimension in
     X, including any dimension exceeding ‘ndims (X)’, will return X.

     Specifying multiple dimensions with input VECDIM, a vector of
     non-repeating dimensions, will operate along the array slice
     defined by VECDIM.  If VECDIM indexes all dimensions of X, then it
     is equivalent to the option "all".  Any dimension in VECDIM greater
     than ‘ndims (X)’ is ignored.

     Specifying the dimension as "all" will cause ‘cumsum’ to operate on
     all elements of X, and is equivalent to ‘cumsum (X(:))’.

     The optional input DIRECTION specifies how the operating dimension
     is traversed and can take the following values:

     "forward" (default)

          The cumulative sum is computed from beginning (index 1) to end
          along the operating dimension.

     "reverse"

          The cumulative sum is computed from end to beginning along the
          operating dimension.

     The optional variable NANFLAG specifies whether to include or
     exclude NaN values from the calculation using any of the previously
     specified input argument combinations.  The default value for
     NANFLAG is "includenan" which keeps NaN values in the calculation.
     To exclude NaN values set the value of NANFLAG to "omitnan".  The
     output will still contain NaN values if X consists of all NaN
     values in the operating dimension.

     See also: *note sum: XREFsum, *note cumprod: XREFcumprod.

 -- : Y = cumprod (X)
 -- : Y = cumprod (X, DIM)
 -- : Y = cumprod (X, VECDIM)
 -- : Y = cumprod (..., "all")
 -- : Y = cumprod (..., DIRECTION)
 -- : Y = cumprod (..., NANFLAG)
     Compute the cumulative product of elements in X.

     If X is a vector, then ‘cumprod (X)’ returns a vector of the same
     size with the cumulative product of X.

     If X is a matrix, then ‘cumprod (X)’ returns a matrix of the same
     size with the cumulative product along each column of X.

     If X is an array, then ‘cumprod(X)’ returns an array of the same
     size with the cumulative product along the first non-singleton
     dimension of X.

     The class of output Y is the same as the class of input X, unless X
     is logical, in which case Y is double.

     The optional input DIM specifies the dimension to operate on and
     must be a positive integer.  Specifying any singleton dimension in
     X, including any dimension exceeding ‘ndims (X)’, will return X.

     Specifying multiple dimensions with input VECDIM, a vector of
     non-repeating dimensions, will operate along the array slice
     defined by VECDIM.  If VECDIM indexes all dimensions of X, then it
     is equivalent to the option "all".  Any dimension in VECDIM greater
     than ‘ndims (X)’ is ignored.

     Specifying the dimension as "all" will cause ‘cumprod’ to operate
     on all elements of X, and is equivalent to ‘cumprod (X(:))’.

     The optional input DIRECTION specifies how the operating dimension
     is traversed and can take the following values:

     "forward" (default)

          The cumulative product is computed from beginning (index 1) to
          end along the operating dimension.

     "reverse"

          The cumulative product is computed from end to beginning along
          the operating dimension.

     The optional variable NANFLAG specifies whether to include or
     exclude NaN values from the calculation using any of the previously
     specified input argument combinations.  The default value for
     NANFLAG is "includenan" which keeps NaN values in the calculation.
     To exclude NaN values set the value of NANFLAG to "omitnan".  The
     output will still contain NaN values if X consists of all NaN
     values in the operating dimension.

     See also: *note prod: XREFprod, *note cumsum: XREFcumsum.

 -- : Y = sumsq (X)
 -- : Y = sumsq (X, DIM)
 -- : Y = sumsq (X, VECDIM)
 -- : Y = sumsq (X, "all")
 -- : Y = sumsq (..., OUTTYPE)
 -- : Y = sumsq (..., NANFLAG)
     Compute the sum of squares of the elements of X.

     If X is a vector, then ‘sumsq (X)’ returns the sum of the squares
     of the elements in X.

     If X is a matrix, then ‘sumsq (X)’ returns a row vector with each
     element containing the sum of squares of the corresponding column
     in X.

     If X is an array, then ‘sumsq(X)’ computes the sum of squares along
     the first non-singleton dimension of X.

     This function is conceptually equivalent to computing

          sum (x .* conj (x))

     but it uses less memory and avoids calling ‘conj’ if X is real.

     The optional input DIM specifies the dimension to operate on and
     must be a positive integer.  Specifying any singleton dimension in
     X, including any dimension exceeding ‘ndims (X)’, will return a sum
     of squares equal to ‘X.^2’.

     Specifying multiple dimensions with input VECDIM, a vector of
     non-repeating dimensions, will operate along the array slice
     defined by VECDIM.  If VECDIM indexes all dimensions of X, then it
     is equivalent to the option "all".  Any dimension in VECDIM greater
     than ‘ndims (X)’ is ignored.

     Specifying the dimension as "all" will cause ‘prod’ to operate on
     all elements of X, and is equivalent to ‘sumsq (X(:))’.

     The optional input OUTTYPE specifies the data type that is returned
     as well as the class of the variable used for calculations.
     OUTTYPE can take the following values:

     "default" : Operations on floating point inputs (double or
          single) are performed in their native data type, while
          operations on integer, logical, and character data types are
          performed using doubles.  Output is of type double, unless the
          input is single in which case the output is of type single.

     "double" : Operations are performed in double precision even for
          single precision inputs.  Output is of type double.

     "native" : Operations are performed in their native data types
          and output is of the same type as the input as reported by
          (‘class (X)’).  When the input is logical, ‘sumsq (X,
          "native")’ is equivalent to ‘all (X)’.

     The optional variable NANFLAG specifies whether to include or
     exclude NaN values from the calculation using any of the previously
     specified input argument combinations.  The default value for
     NANFLAG is "includenan" which keeps NaN values in the calculation.
     To exclude NaN values set the value of NANFLAG to "omitnan".  The
     output will be 0, if X consists of all NaN values in the operating
     dimension.

     See also: *note sum: XREFsum, *note prod: XREFprod.


File: octave.info,  Node: Utility Functions,  Next: Special Functions,  Prev: Sums and Products,  Up: Arithmetic

17.5 Utility Functions
======================

 -- : Y = ceil (X)
     Return the smallest integer not less than X.

     This is equivalent to rounding towards positive infinity.

     If X is complex, return ‘ceil (real (X)) + ceil (imag (X)) * I’.

          ceil ([-2.7, 2.7])
              ⇒ -2    3

     See also: *note floor: XREFfloor, *note round: XREFround, *note
     fix: XREFfix.

 -- : Y = fix (X)
     Truncate fractional portion of X and return the integer portion.

     This is equivalent to rounding towards zero.  If X is complex,
     return ‘fix (real (X)) + fix (imag (X)) * I’.

          fix ([-2.7, 2.7])
             ⇒ -2    2

     See also: *note ceil: XREFceil, *note floor: XREFfloor, *note
     round: XREFround.

 -- : Y = floor (X)
     Return the largest integer not greater than X.

     This is equivalent to rounding towards negative infinity.  If X is
     complex, return ‘floor (real (X)) + floor (imag (X)) * I’.

          floor ([-2.7, 2.7])
               ⇒ -3    2

     See also: *note ceil: XREFceil, *note round: XREFround, *note fix:
     XREFfix.

 -- : Y = round (X)
     Return the integer nearest to X.

     If X is complex, return ‘round (real (X)) + round (imag (X)) * I’.
     If there are two nearest integers, return the one further away from
     zero.

          round ([-2.7, 2.7])
               ⇒ -3    3

     See also: *note ceil: XREFceil, *note floor: XREFfloor, *note fix:
     XREFfix, *note roundb: XREFroundb.

 -- : Y = roundb (X)
     Return the integer nearest to X.  If there are two nearest
     integers, return the even one (banker's rounding).

     If X is complex, return ‘roundb (real (X)) + roundb (imag (X)) *
     I’.

     See also: *note round: XREFround.

 -- : M = max (X)
 -- : M = max (X, [], DIM)
 -- : M = max (X, [], VECDIM)
 -- : M = max (X, [], "all")
 -- : M = max (X, [], NANFLAG)
 -- : [M, IM] = max (...)
 -- : [M, IM] = max (..., "linear")
 -- : M = max (X, Y)
 -- : M = max (X, Y, NANFLAG)
 -- : ... = max (..., "ComparisonMethod", METHOD)
     Find maximum values in the array X.

     If X is a vector, then ‘max (X)’ returns the maximum value of the
     elements in X.

     If X is a matrix, then ‘max (X)’ returns a row vector with each
     element containing the maximum value of the corresponding column in
     X.

     If X is an array, then ‘max (X)’ computes the maximum value along
     the first non-singleton dimension of X.

     The optional input DIM specifies the dimension to operate on and
     must be a positive integer.  Specifying any singleton dimension of
     X, including any dimension exceeding ‘ndims (X)’, will return X.

     Specifying multiple dimensions with input VECDIM, a vector of
     non-repeating dimensions, will operate along the array slice
     defined by VECDIM.  If VECDIM indexes all dimensions of X, then it
     is equivalent to the option "all".  Any dimension in VECDIM greater
     than ‘ndims (X)’ is ignored.

     Specifying the dimension as "all" will cause ‘max’ to operate on on
     all elements of X, and is equivalent to ‘max (X(:))’.

     If called with two output arguments, ‘max’ also returns the first
     index of the maximum value(s) in X.  The second output argument is
     only valid when ‘max’ operates on a single input array.  Setting
     the "linear" flag returns the linear index to the corresponding
     minimum values in X.

     If called with two input arrays (X and Y), ‘max’ return the
     pairwise maximum according to the rules for *note Broadcasting::.

     The optional variable NANFLAG specifies whether to include or
     exclude ‘NaN’ values from the calculation using any of the
     previously specified input argument combinations.  The default
     value for NANFLAG is "omitnan" which ignores ‘NaN’ values in the
     calculation.  To include ‘NaN’ values, set the value of NANFLAG to
     "includenan", in which case ‘max’ will return ‘NaN’, if any element
     along the operating dimension is ‘NaN’.

     The optional "ComparisonMethod" paired argument specifies the
     comparison method for numeric input and it applies to both one
     input and two input arrays.  METHOD can take any of the following
     values:

     'auto' : This is the default method, which compares elements by
          ‘real (X)’ when X is real, and by ‘abs (X)’ when X is complex.

     'real' : Compares elements by ‘real (X)’ when X
          is real or complex.  For elements with equal real parts, a
          second comparison by ‘imag (X)’ is performed.

     'abs' : Compares elements by ‘abs (X)’ when X
          is real or complex.  For elements with equal magnitude, a
          second comparison by ‘angle (X)’ in the interval [-pi,pi] is
          performed.

     See also: *note min: XREFmin, *note cummax: XREFcummax, *note
     cummin: XREFcummin.

 -- : M = min (X)
 -- : M = min (X, [], DIM)
 -- : M = min (X, [], VECDIM)
 -- : M = min (X, [], "all")
 -- : M = min (X, [], NANFLAG)
 -- : [M, IM] = min (...)
 -- : [M, IM] = min (..., "linear")
 -- : M = min (X, Y)
 -- : M = min (X, Y, NANFLAG)
 -- : ... = min (..., "ComparisonMethod", METHOD)
     Find minimum values in the array X.

     If X is a vector, then ‘min (X)’ returns the minimum value of the
     elements in X.

     If X is a matrix, then ‘min (X)’ returns a row vector with each
     element containing the minimum value of the corresponding column in
     X.

     If X is an array, then ‘min (X)’ computes the minimum value along
     the first non-singleton dimension of X.

     The optional input DIM specifies the dimension to operate on and
     must be a positive integer.  Specifying any singleton dimension of
     X, including any dimension exceeding ‘ndims (X)’, will return X.

     Specifying multiple dimensions with input VECDIM, a vector of
     non-repeating dimensions, will operate along the array slice
     defined by VECDIM.  If VECDIM indexes all dimensions of X, then it
     is equivalent to the option "all".  Any dimension in VECDIM greater
     than ‘ndims (X)’ is ignored.

     Specifying the dimension as "all" will cause ‘min’ to operate on on
     all elements of X, and is equivalent to ‘min (X(:))’.

     If called with two output arguments, ‘min’ also returns the first
     index of the minimum value(s) in X.  The second output argument is
     only valid when ‘min’ operates on a single input array.  Setting
     the "linear" flag returns the linear index to the corresponding
     minimum values in X.

     If called with two input arrays (X and Y), ‘min’ return the
     pairwise minimum according to the rules for *note Broadcasting::.

     The optional variable NANFLAG specifies whether to include or
     exclude ‘NaN’ values from the calculation using any of the
     previously specified input argument combinations.  The default
     value for NANFLAG is "omitnan" which ignores ‘NaN’ values in the
     calculation.  To include ‘NaN’ values, set the value of NANFLAG to
     "includenan", in which case ‘min’ will return ‘NaN’, if any element
     along the operating dimension is ‘NaN’.

     The optional "ComparisonMethod" paired argument specifies the
     comparison method for numeric input and it applies to both one
     input and two input arrays.  METHOD can take any of the following
     values:

     'auto' : This is the default method, which compares elements by
          ‘real (X)’ when X is real, and by ‘abs (X)’ when X is complex.

     'real' : Compares elements by ‘real (X)’ when X
          is real or complex.  For elements with equal real parts, a
          second comparison by ‘imag (X)’ is performed.

     'abs' : Compares elements by ‘abs (X)’ when X
          is real or complex.  For elements with equal magnitude, a
          second comparison by ‘angle (X)’ in the interval [-pi,pi] is
          performed.

     See also: *note max: XREFmax, *note cummin: XREFcummin, *note
     cummax: XREFcummax.

 -- : M = cummax (X)
 -- : M = cummax (X, DIM)
 -- : M = cummax (X, VECDIM)
 -- : M = cummax (X, "all")
 -- : M = cummax (..., DIRECTION)
 -- : M = cummax (X, NANFLAG)
 -- : [M, IM] = cummax (...)
 -- : [M, IM] = cummax (..., "linear")
 -- : ... = cummax (..., "ComparisonMethod", METHOD)
     Return the cumulative maximum values from the array X.

     If X is a vector, then ‘cummax (X)’ returns a vector of the same
     size with the cumulative maximum values of X.

     If X is a matrix, then ‘cummax (X)’ returns a matrix of the same
     size with the cumulative maximum values along each column of X.

     If X is an array, then ‘cummax(X)’ returns an array of the same
     size with the cumulative product along the first non-singleton
     dimension of X.

     The class of output Y is the same as the class of input X, unless X
     is logical, in which case Y is double.

     The optional input DIM specifies the dimension to operate on and
     must be a positive integer.  Specifying any singleton dimension in
     X, including any dimension exceeding ‘ndims (X)’, will return X.

     Specifying multiple dimensions with input VECDIM, a vector of
     non-repeating dimensions, will operate along the array slice
     defined by VECDIM.  If VECDIM indexes all dimensions of X, then it
     is equivalent to the option "all".  Any dimension in VECDIM greater
     than ‘ndims (X)’ is ignored.

     Specifying the dimension as "all" will cause ‘cummax’ to operate on
     all elements of X, and is equivalent to ‘cummax (X(:))’.

     The optional input DIRECTION specifies how the operating dimension
     is traversed and can take the following values:

     "forward" (default)

          The cumulative maximum values are computed from beginning
          (index 1) to end along the operating dimension.

     "reverse"

          The cumulative maximum values are computed from end to
          beginning along the operating dimension.

     The optional variable NANFLAG specifies whether to include or
     exclude ‘NaN’ values from the calculation using any of the
     previously specified input argument combinations.  The default
     value for NANFLAG is "omitnan" which ignores ‘NaN’ values in the
     calculation.  To include ‘NaN’ values, set the value of NANFLAG to
     "includenan", in which case ‘max’ will return ‘NaN’, if any element
     along the operating dimension is ‘NaN’.

     If called with two output arguments, ‘cummax’ also returns the
     first index of the maximum value(s) in X.  Setting the "linear"
     flag returns the linear index to the corresponding minimum values
     in X.

     The optional "ComparisonMethod" paired argument specifies the
     comparison method for numeric input and it applies to both one
     input and two input arrays.  METHOD can take any of the following
     values:

     'auto' : This is the default method, which compares elements by
          ‘real (X)’ when X is real, and by ‘abs (X)’ when X is complex.

     'real' : Compares elements by ‘real (X)’ when X
          is real or complex.  For elements with equal real parts, a
          second comparison by ‘imag (X)’ is performed.

     'abs' : Compares elements by ‘abs (X)’ when X
          is real or complex.  For elements with equal magnitude, a
          second comparison by ‘angle (X)’ in the interval [-pi,pi] is
          performed.

     See also: *note cummin: XREFcummin, *note max: XREFmax, *note min:
     XREFmin.

 -- : M = cummin (X)
 -- : M = cummin (X, DIM)
 -- : M = cummin (X, VECDIM)
 -- : M = cummin (X, "all")
 -- : M = cummin (..., DIRECTION)
 -- : M = cummin (X, NANFLAG)
 -- : [M, IM] = cummin (...)
 -- : [M, IM] = cummin (..., "linear")
 -- : ... = cummin (..., "ComparisonMethod", METHOD)
     Return the cumulative minimum values from the array X.

     If X is a vector, then ‘cummin (X)’ returns a vector of the same
     size with the cumulative minimum values of X.

     If X is a matrix, then ‘cummin (X)’ returns a matrix of the same
     size with the cumulative minimum values along each column of X.

     If X is an array, then ‘cummin(X)’ returns an array of the same
     size with the cumulative product along the first non-singleton
     dimension of X.

     The class of output Y is the same as the class of input X, unless X
     is logical, in which case Y is double.

     The optional input DIM specifies the dimension to operate on and
     must be a positive integer.  Specifying any singleton dimension in
     X, including any dimension exceeding ‘ndims (X)’, will return X.

     Specifying multiple dimensions with input VECDIM, a vector of
     non-repeating dimensions, will operate along the array slice
     defined by VECDIM.  If VECDIM indexes all dimensions of X, then it
     is equivalent to the option "all".  Any dimension in VECDIM greater
     than ‘ndims (X)’ is ignored.

     Specifying the dimension as "all" will cause ‘cummin’ to operate on
     all elements of X, and is equivalent to ‘cummin (X(:))’.

     The optional input DIRECTION specifies how the operating dimension
     is traversed and can take the following values:

     "forward" (default)

          The cumulative minimum values are computed from beginning
          (index 1) to end along the operating dimension.

     "reverse"

          The cumulative minimum values are computed from end to
          beginning along the operating dimension.

     The optional variable NANFLAG specifies whether to include or
     exclude ‘NaN’ values from the calculation using any of the
     previously specified input argument combinations.  The default
     value for NANFLAG is "omitnan" which ignores ‘NaN’ values in the
     calculation.  To include ‘NaN’ values, set the value of NANFLAG to
     "includenan", in which case ‘max’ will return ‘NaN’, if any element
     along the operating dimension is ‘NaN’.

     If called with two output arguments, ‘cummin’ also returns the
     first index of the minimum value(s) in X.  Setting the "linear"
     flag returns the linear index to the corresponding minimum values
     in X.

     The optional "ComparisonMethod" paired argument specifies the
     comparison method for numeric input and it applies to both one
     input and two input arrays.  METHOD can take any of the following
     values:

     'auto' : This is the default method, which compares elements by
          ‘real (X)’ when X is real, and by ‘abs (X)’ when X is complex.

     'real' : Compares elements by ‘real (X)’ when X
          is real or complex.  For elements with equal real parts, a
          second comparison by ‘imag (X)’ is performed.

     'abs' : Compares elements by ‘abs (X)’ when X
          is real or complex.  For elements with equal magnitude, a
          second comparison by ‘angle (X)’ in the interval [-pi,pi] is
          performed.

     See also: *note cummax: XREFcummax, *note min: XREFmin, *note max:
     XREFmax.

 -- : H = hypot (X, Y)
 -- : H = hypot (X, Y, Z, ...)
     Compute the element-by-element square root of the sum of the
     squares of X and Y.

     This is equivalent to ‘sqrt (X.^2 + Y.^2)’, but is calculated in a
     manner that avoids overflows for large values of X or Y.

     ‘hypot’ can also be called with more than 2 arguments; in this
     case, the arguments are accumulated from left to right:

          hypot (hypot (X, Y), Z)
          hypot (hypot (hypot (X, Y), Z), W), etc.

 -- : DX = gradient (M)
 -- : [DX, DY, DZ, ...] = gradient (M)
 -- : [...] = gradient (M, S)
 -- : [...] = gradient (M, SX, SY, SZ, ...)
 -- : [...] = gradient (F, X0)
 -- : [...] = gradient (F, X0, S)
 -- : [...] = gradient (F, X0, SX, SY, ...)

     Calculate the gradient of sampled data or a function.

                       d                d                 d
     grad F(x,y,z)  =  -- F(x,y,z) i  + -- F(x,y,z) j  +  -- F(x,y,z) k
                       dx               dy                dz

     If M is a vector, calculate the one-dimensional numerical gradient
     of M.  If M is a matrix the gradient is calculated for each
     dimension.  The return argument(s) are the estimated partial
     derivatives for each dimension at the specified sample points.

     The default spacing of between data points is 1.  A constant
     spacing between points can be specified with the S parameter.  If S
     is a scalar, the single spacing value is used for all dimensions.
     Otherwise, separate values of the spacing can be supplied by the
     SX, ... arguments.  Scalar values specify an equidistant spacing.
     Vector values for the SX, ... arguments specify the coordinate for
     that dimension.  The length must match the respective dimension of
     M.

     If the first argument F is a function handle, the gradient of the
     function is calculated for the points in X0.  As with sampled data,
     the spacing values between the points from which the gradient is
     estimated can be set via the S or DX, DY, ... arguments.  By
     default a spacing of 1 is used, however this is normally overly
     large unless the function is very slowly varying, and it is often
     necessary to specify a smaller sample spacing.

     Example: numerical gradient of ‘cos’ (analytically = ‘-sin’)

          gradient (@cos, pi/2, .1)
          ⇒ -0.9983
          -sin (pi/2)
          ⇒ -1

     Programming Notes: The value for interior data points is
     approximated using the central difference.

          y'(i) = 1/2 * (y(i+1) - y(i-1)).

     At boundary points a linear extrapolation is applied.

          y'(1) = y(2) - y(1).

     See also: *note diff: XREFdiff, *note del2: XREFdel2.

 -- : Z = dot (X, Y)
 -- : Z = dot (X, Y, DIM)
     Compute the dot product of two vectors.

     If X and Y are matrices, calculate the dot products along the first
     non-singleton dimension.

     If the optional argument DIM is given, calculate the dot products
     along this dimension.

     Implementation Note: This is equivalent to ‘sum (conj (X) .* Y,
     DIM)’, but avoids forming a temporary array and is faster.  When X
     and Y are column vectors, the result is equivalent to ‘X' * Y’.
     Although, ‘dot’ is defined for integer arrays, the output may
     differ from the expected result due to the limited range of integer
     objects.

     See also: *note cross: XREFcross, *note divergence: XREFdivergence,
     *note tensorprod: XREFtensorprod.

 -- : Z = cross (X, Y)
 -- : Z = cross (X, Y, DIM)
     Compute the vector cross product of two 3-dimensional vectors X and
     Y.

     If X and Y are arrays, the cross product is applied along the first
     dimension with three elements.

     The optional argument DIM forces the cross product to be calculated
     along the specified dimension.  An error will be produced if the
     specified dimension is not three elements in size.

     In the case of a complex output, orthogonality of the output with
     respect to the inputs is also satisfied, and the condition

          dot (conj (Z), X) ≡ dot (conj (Z), Y) = 0

     is met.  ‘dot (Z, X) = 0’ and ‘dot (Z, Y) = 0’ will not hold.  Also
     note that instead of using the ‘dot’ function, the inner product

          Z(:).' * X(:) ≡ Z(:).' * Y(:) = 0

     will meet the orthogonality condition for vector input.

     Example Code:

          cross ([1, 1, 0], [0, 1, 1])
            ⇒
                 1  -1   1

          cross (magic (3), eye (3), 2)
            ⇒
                 0   6  -1
                -7   0   3
                 9  -4   0

     See also: *note dot: XREFdot, *note curl: XREFcurl, *note
     divergence: XREFdivergence, *note conj: XREFconj.

 -- : DIV = divergence (X, Y, Z, FX, FY, FZ)
 -- : DIV = divergence (FX, FY, FZ)
 -- : DIV = divergence (X, Y, FX, FY)
 -- : DIV = divergence (FX, FY)
     Calculate divergence of a vector field given by the arrays FX, FY,
     and FZ or FX, FY respectively.

                            d               d               d
          div F(x,y,z)  =   -- F(x,y,z)  +  -- F(x,y,z)  +  -- F(x,y,z)
                            dx              dy              dz

     The coordinates of the vector field can be given by the arguments
     X, Y, Z or X, Y respectively.

     See also: *note curl: XREFcurl, *note gradient: XREFgradient, *note
     del2: XREFdel2, *note dot: XREFdot.

 -- : [CX, CY, CZ, V] = curl (X, Y, Z, FX, FY, FZ)
 -- : [CZ, V] = curl (X, Y, FX, FY)
 -- : [...] = curl (FX, FY, FZ)
 -- : [...] = curl (FX, FY)
 -- : V = curl (...)
     Calculate curl of vector field given by the arrays FX, FY, and FZ
     or FX, FY respectively.

                            / d         d       d         d       d         d     \
          curl F(x,y,z)  =  | -- Fz  -  -- Fy,  -- Fx  -  -- Fz,  -- Fy  -  -- Fx |
                            \ dy        dz      dz        dx      dx        dy    /

     The coordinates of the vector field can be given by the arguments
     X, Y, Z or X, Y respectively.  V calculates the scalar component of
     the angular velocity vector in direction of the z-axis for
     two-dimensional input.  For three-dimensional input the scalar
     rotation is calculated at each grid point in direction of the
     vector field at that point.

     See also: *note divergence: XREFdivergence, *note gradient:
     XREFgradient, *note del2: XREFdel2, *note cross: XREFcross.

 -- : L = del2 (M)
 -- : L = del2 (M, H)
 -- : L = del2 (M, DX, DY, ...)

     Calculate the discrete Laplace operator.

     For a 2-dimensional matrix M(x, y) this is defined as

                1    / d^2            d^2         \
          L  = --- * | ---  M(x,y) +  ---  M(x,y) |
                4    \ dx^2           dy^2        /

     For N-dimensional arrays the sum in parentheses is expanded to
     include second derivatives over the additional higher dimensions.

     The spacing between evaluation points may be defined by H, which is
     a scalar defining the equidistant spacing in all dimensions.
     Alternatively, the spacing in each dimension may be defined
     separately by DX, DY, etc.  A scalar spacing argument defines
     equidistant spacing, whereas a vector argument can be used to
     specify variable spacing.  The length of the spacing vectors must
     match the respective dimension of M.  The default spacing value is
     1.

     Dimensions with fewer than 3 data points are skipped.  Boundary
     points are calculated from the linear extrapolation of interior
     points.

     Example: Second derivative of 2*x^3

          f = @(x) 2*x.^3;
          dd = @(x) 12*x;
          x = 1:6;
          L = 4*del2 (f(x));
          assert (L, dd (x));

     See also: *note gradient: XREFgradient, *note diff: XREFdiff.

 -- : F = factorial (N)
     Return the factorial of N where N is a real non-negative integer.

     If N is a scalar, this is equivalent to ‘prod (1:N)’.  For vector
     or matrix arguments, return the factorial of each element in the
     array.

     For non-integers see the generalized factorial function ‘gamma’.
     Note that the factorial function grows large quite quickly, and
     even with double precision values overflow will occur if N > 171.
     For such cases consider ‘gammaln’.

     See also: *note prod: XREFprod, *note gamma: XREFgamma, *note
     gammaln: XREFgammaln.

 -- : PF = factor (Q)
 -- : [PF, N] = factor (Q)
     Return the prime factorization of Q.

     The prime factorization is defined as ‘prod (PF) == Q’ where every
     element of PF is a prime number.  If ‘Q == 1’, return 1.  The
     output PF is of the same numeric class as the input.

     With two output arguments, return the unique prime factors PF and
     their multiplicities.  That is, ‘prod (PF .^ N) == Q’.

     Implementation Note: If the input Q is ‘single’ or ‘double’, then
     it must not exceed the corresponding ‘flintmax’.  For larger
     inputs, cast them to ‘uint64’ if they're less than 2^64:

          factor (uint64 (18446744073709011493))
             ⇒     571111    761213  42431951

     For even larger inputs, use ‘sym’ if you have the Symbolic package
     installed and loaded:

          factor (sym ('9444733049654361449941'))
             ⇒ (sym)
                        1           1
           1099511627689 ⋅8589934669

     See also: *note gcd: XREFgcd, *note lcm: XREFlcm, *note isprime:
     XREFisprime, *note primes: XREFprimes.

 -- : G = gcd (A1, A2, ...)
 -- : [G, V1, ...] = gcd (A1, A2, ...)
     Compute the greatest common divisor of A1, A2, ...

     All arguments must be the same size or scalar.  For arrays, the
     greatest common divisor is calculated for each element
     individually.  All elements must be ordinary or Gaussian (complex)
     integers.  Note that for Gaussian integers, the gcd is only unique
     up to a phase factor (multiplication by 1, -1, i, or -i), so an
     arbitrary greatest common divisor among the four possible is
     returned.

     Optional return arguments V1, ..., contain integer vectors such
     that,

          G = V1 .* A1 + V2 .* A2 + ...

     Example code:

          gcd ([15, 9], [20, 18])
             ⇒  5  9

     Programming tip: To find the GCD of all the elements of a single
     array, use ‘num2cell’ instead of nested calls or a loop:

          x = [30 42 70 105];    # vector or array of inputs
          gcd (num2cell (x) {:})
             ⇒     1

     See also: *note lcm: XREFlcm, *note factor: XREFfactor, *note
     isprime: XREFisprime.

 -- : L = lcm (X, Y)
 -- : L = lcm (X, Y, ...)
     Compute the least common multiple of X and Y, or of the list of all
     arguments.

     All inputs must be of the same size, or scalar.  All elements must
     be real integer or Gaussian (complex) integer.  For complex inputs,
     the result is unique only up to a phase factor (multiplication by
     +1, +i, -1, or -i), and one of the four is returned arbitrarily.

     Example code:

          lcm (5:8, 9:12)
             ⇒  45  30  77  24

     Programming tip: To find the LCM of all the elements of a single
     array, use ‘num2cell’ instead of nested calls or a loop:

          x = 1:10;    # vector or array of inputs
          lcm (num2cell (x) {:})
             ⇒     2520

     See also: *note factor: XREFfactor, *note gcd: XREFgcd, *note
     isprime: XREFisprime.

 -- : R = rem (X, Y)
     Return the remainder of the division ‘X / Y’.

     The remainder is computed using the expression

          x - y .* fix (x ./ y)

     An error message is printed if the dimensions of the arguments do
     not agree, or if either argument is complex.

     Programming Notes: When calculating with floating point numbers
     (double, single), values within a few eps of an integer will be
     rounded to that integer before computation for compatibility with
     MATLAB.  Any floating point integers greater than ‘flintmax’ (2^53
     for double) will not compute correctly.  For larger integer values
     convert the input to ‘uint64’ before calling this function.

     By convention,

          rem (X, 0) = NaN  if X is a floating point variable
          rem (X, 0) = 0    if X is an integer variable
          rem (X, Y)  returns a value with the signbit from X

     For the opposite conventions see the ‘mod’ function.  In general,
     ‘rem’ is best when computing the remainder after division of two
     _positive_ numbers.  For negative numbers, or when the values are
     periodic, ‘mod’ is a better choice.

     See also: *note mod: XREFmod.

 -- : M = mod (X, Y)
     Compute the modulo of X and Y.

     Conceptually this is given by

          x - y .* floor (x ./ y)

     and is written such that the correct modulus is returned for
     integer types.  This function handles negative values correctly.
     That is, ‘mod (-1, 3)’ is 2, not -1, as ‘rem (-1, 3)’ returns.

     An error results if the dimensions of the arguments do not agree,
     or if either of the arguments is complex.

     Programming Notes: When calculating with floating point numbers
     (double, single), values within a few eps of an integer will be
     rounded to that integer before computation for compatibility with
     MATLAB.  Any floating point integers greater than ‘flintmax’ (2^53
     for double) will not compute correctly.  For larger integer values
     convert the input to ‘uint64’ before calling this function.

     By convention,

          mod (X, 0) = X
          mod (X, Y)      returns a value with the signbit from Y

     For the opposite conventions see the ‘rem’ function.  In general,
     ‘mod’ is a better choice than ‘rem’ when any of the inputs are
     negative numbers or when the values are periodic.

     See also: *note rem: XREFrem.

 -- : P = primes (N)
     Return all primes up to N.

     The output data class (double, single, uint32, etc.) is the same as
     the input class of N.  The algorithm used is the Sieve of
     Eratosthenes.

     Note: For a specific number N of primes, call ‘list_primes (N)’.
     Alternatively, call ‘primes (N*log (K*N))(1:N)’ where K is about 5
     or 6.  This works because the distance from one prime to the next
     is proportional to the logarithm of the prime, on average.  On
     integrating, there are about N primes less than ‘N * log (5*N)’.

     See also: *note list_primes: XREFlist_primes, *note isprime:
     XREFisprime.

 -- : P = list_primes ()
 -- : P = list_primes (N)
     List the first N primes.

     If N is unspecified, the first 25 primes are listed.

     See also: *note primes: XREFprimes, *note isprime: XREFisprime.

 -- : Y = sign (X)
     Compute the “signum” function.

     This is defined as

                     -1, x < 0;
          sign (x) =  0, x = 0;
                      1, x > 0.

     For complex arguments, ‘sign’ returns ‘x ./ abs (X)’.

     Note that ‘sign (-0.0)’ is 0.  Although IEEE 754 floating point
     allows zero to be signed, 0.0 and -0.0 compare equal.  If you must
     test whether zero is signed, use the ‘signbit’ function.

     See also: *note signbit: XREFsignbit.

 -- : Y = signbit (X)
     Return logical true if the value of X has its sign bit set and
     false otherwise.

     This behavior is consistent with the other logical functions.
     *Note Logical Values::.  The behavior differs from the C language
     function which returns nonzero if the sign bit is set.

     This is not the same as ‘x < 0.0’, because IEEE 754 floating point
     allows zero to be signed.  The comparison ‘-0.0 < 0.0’ is false,
     but ‘signbit (-0.0)’ will return a nonzero value.

     See also: *note sign: XREFsign.


File: octave.info,  Node: Special Functions,  Next: Rational Approximations,  Prev: Utility Functions,  Up: Arithmetic

17.6 Special Functions
======================

 -- : A = airy (Z)
 -- : A = airy (K, Z)
 -- : A = airy (K, Z, SCALE)
 -- : [A, IERR] = airy (...)

     Compute Airy functions of the first and second kind, and their
     derivatives.

           K   Function   Scale factor (if SCALE is true)
          ---  --------   ---------------------------------------
           0   Ai (Z)     exp ((2/3) * Z * sqrt (Z))
           1   dAi(Z)/dZ  exp ((2/3) * Z * sqrt (Z))
           2   Bi (Z)     exp (-abs (real ((2/3) * Z * sqrt (Z))))
           3   dBi(Z)/dZ  exp (-abs (real ((2/3) * Z * sqrt (Z))))

     The function call ‘airy (Z)’ is equivalent to ‘airy (0, Z)’.

     The optional third input SCALE determines whether to apply scaling
     as described above.  It is false by default.

     The result A is the same size as Z.

     The optional output IERR contains the following status information
     and is the same size as the result.

       0. Normal return.

       1. Input error, return ‘NaN’.

       2. Overflow, return ‘Inf’.

       3. Loss of significance by argument reduction results in less
          than half of machine accuracy.

       4. Loss of significance by argument reduction, output may be
          inaccurate.

       5. Error--no computation, algorithm termination condition not
          met, return ‘NaN’.

 -- : J = besselj (ALPHA, X)
 -- : J = besselj (ALPHA, X, OPT)
 -- : [J, IERR] = besselj (...)
     Compute Bessel functions of the first kind.

     The order of the Bessel function ALPHA must be real.  The points
     for evaluation X may be complex.

     If the optional argument OPT is 1 or true, the result J is
     multiplied by ‘exp (-abs (imag (X)))’.

     If ALPHA is a scalar, the result is the same size as X.  If X is a
     scalar, the result is the same size as ALPHA.  If ALPHA is a row
     vector and X is a column vector, the result is a matrix with
     ‘length (X)’ rows and ‘length (ALPHA)’ columns.  Otherwise, ALPHA
     and X must conform and the result will be the same size.

     If requested, IERR contains the following status information and is
     the same size as the result.

       0. Normal return.

       1. Input error, return ‘NaN’.

       2. Overflow, return ‘Inf’.

       3. Loss of significance by argument reduction results in less
          than half of machine accuracy.

       4. Loss of significance by argument reduction, output may be
          inaccurate.

       5. Error--no computation, algorithm termination condition not
          met, return ‘NaN’.

     See also: *note bessely: XREFbessely, *note besseli: XREFbesseli,
     *note besselk: XREFbesselk, *note besselh: XREFbesselh.

 -- : Y = bessely (ALPHA, X)
 -- : Y = bessely (ALPHA, X, OPT)
 -- : [Y, IERR] = bessely (...)
     Compute Bessel functions of the second kind.

     The order of the Bessel function ALPHA must be real.  The points
     for evaluation X may be complex.

     If the optional argument OPT is 1 or true, the result Y is
     multiplied by ‘exp (-abs (imag (X)))’.

     If ALPHA is a scalar, the result is the same size as X.  If X is a
     scalar, the result is the same size as ALPHA.  If ALPHA is a row
     vector and X is a column vector, the result is a matrix with
     ‘length (X)’ rows and ‘length (ALPHA)’ columns.  Otherwise, ALPHA
     and X must conform and the result will be the same size.

     If requested, IERR contains the following status information and is
     the same size as the result.

       0. Normal return.

       1. Input error, return ‘NaN’.

       2. Overflow, return ‘Inf’.

       3. Loss of significance by argument reduction results in less
          than half of machine accuracy.

       4. Complete loss of significance by argument reduction, return
          ‘NaN’.

       5. Error--no computation, algorithm termination condition not
          met, return ‘NaN’.

     See also: *note besselj: XREFbesselj, *note besseli: XREFbesseli,
     *note besselk: XREFbesselk, *note besselh: XREFbesselh.

 -- : I = besseli (ALPHA, X)
 -- : I = besseli (ALPHA, X, OPT)
 -- : [I, IERR] = besseli (...)
     Compute modified Bessel functions of the first kind.

     The order of the Bessel function ALPHA must be real.  The points
     for evaluation X may be complex.

     If the optional argument OPT is 1 or true, the result I is
     multiplied by ‘exp (-abs (real (X)))’.

     If ALPHA is a scalar, the result is the same size as X.  If X is a
     scalar, the result is the same size as ALPHA.  If ALPHA is a row
     vector and X is a column vector, the result is a matrix with
     ‘length (X)’ rows and ‘length (ALPHA)’ columns.  Otherwise, ALPHA
     and X must conform and the result will be the same size.

     If requested, IERR contains the following status information and is
     the same size as the result.

       0. Normal return.

       1. Input error, return ‘NaN’.

       2. Overflow, return ‘Inf’.

       3. Loss of significance by argument reduction results in less
          than half of machine accuracy.

       4. Complete loss of significance by argument reduction, return
          ‘NaN’.

       5. Error--no computation, algorithm termination condition not
          met, return ‘NaN’.

     See also: *note besselk: XREFbesselk, *note besselj: XREFbesselj,
     *note bessely: XREFbessely, *note besselh: XREFbesselh.

 -- : K = besselk (ALPHA, X)
 -- : K = besselk (ALPHA, X, OPT)
 -- : [K, IERR] = besselk (...)

     Compute modified Bessel functions of the second kind.

     The order of the Bessel function ALPHA must be real.  The points
     for evaluation X may be complex.

     If the optional argument OPT is 1 or true, the result K is
     multiplied by ‘exp (X)’.

     If ALPHA is a scalar, the result is the same size as X.  If X is a
     scalar, the result is the same size as ALPHA.  If ALPHA is a row
     vector and X is a column vector, the result is a matrix with
     ‘length (X)’ rows and ‘length (ALPHA)’ columns.  Otherwise, ALPHA
     and X must conform and the result will be the same size.

     If requested, IERR contains the following status information and is
     the same size as the result.

       0. Normal return.

       1. Input error, return ‘NaN’.

       2. Overflow, return ‘Inf’.

       3. Loss of significance by argument reduction results in less
          than half of machine accuracy.

       4. Complete loss of significance by argument reduction, return
          ‘NaN’.

       5. Error--no computation, algorithm termination condition not
          met, return ‘NaN’.

     See also: *note besseli: XREFbesseli, *note besselj: XREFbesselj,
     *note bessely: XREFbessely, *note besselh: XREFbesselh.

 -- : H = besselh (ALPHA, X)
 -- : H = besselh (ALPHA, K, X)
 -- : H = besselh (ALPHA, K, X, OPT)
 -- : [H, IERR] = besselh (...)
     Compute Bessel functions of the third kind (Hankel functions).

     The order of the Bessel function ALPHA must be real.  The kind of
     Hankel function is specified by K and may be either first (K = 1)
     or second (K = 2).  The default is Hankel functions of the first
     kind.  The points for evaluation X may be complex.

     If the optional argument OPT is 1 or true, the result is multiplied
     by ‘exp (-I*X)’ for K = 1 or ‘exp (I*X)’ for K = 2.

     If ALPHA is a scalar, the result is the same size as X.  If X is a
     scalar, the result is the same size as ALPHA.  If ALPHA is a row
     vector and X is a column vector, the result is a matrix with
     ‘length (X)’ rows and ‘length (ALPHA)’ columns.  Otherwise, ALPHA
     and X must conform and the result will be the same size.

     If requested, IERR contains the following status information and is
     the same size as the result.

       0. Normal return.

       1. Input error, return ‘NaN’.

       2. Overflow, return ‘Inf’.

       3. Loss of significance by argument reduction results in less
          than half of machine accuracy.

       4. Complete loss of significance by argument reduction, return
          ‘NaN’.

       5. Error--no computation, algorithm termination condition not
          met, return ‘NaN’.

     See also: *note besselj: XREFbesselj, *note bessely: XREFbessely,
     *note besseli: XREFbesseli, *note besselk: XREFbesselk.

 -- : Y = beta (A, B)
     Compute the Beta function for real inputs A and B.

     The Beta function definition is

          beta (a, b) = gamma (a) * gamma (b) / gamma (a + b).

     The Beta function can grow quite large and it is often more useful
     to work with the logarithm of the output rather than the function
     directly.  *Note ‘betaln’: XREFbetaln, for computing the logarithm
     of the Beta function in an efficient manner.

     See also: *note betaln: XREFbetaln, *note betainc: XREFbetainc,
     *note betaincinv: XREFbetaincinv.

 -- : I = betainc (X, A, B)
 -- : I = betainc (X, A, B, TAIL)
     Compute the incomplete beta function.

     This is defined as

                                    x
                                   /
                           1       |
          I_x (a, b) = ----------  | t^(a-1) (1-t)^(b-1) dt
                       beta (a,b)  |
                                   /
                                  0

     with real X in the range [0,1].  The inputs A and B must be real
     and strictly positive (> 0).  If one of the inputs is not a scalar
     then the other inputs must be scalar or of compatible dimensions.

     By default, TAIL is "lower" and the incomplete beta function
     integrated from 0 to X is computed.  If TAIL is "upper" then the
     complementary function integrated from X to 1 is calculated.  The
     two choices are related by

     betainc (X, A, B, "upper") = 1 - betainc (X, A, B, "lower").

     ‘betainc’ uses a more sophisticated algorithm than subtraction to
     get numerically accurate results when the "lower" value is small.

     Reference: A. Cuyt, V. Brevik Petersen, B. Verdonk, H. Waadeland,
     W.B. Jones, ‘Handbook of Continued Fractions for Special
     Functions’, ch. 18.

     See also: *note beta: XREFbeta, *note betaincinv: XREFbetaincinv,
     *note betaln: XREFbetaln.

 -- : X = betaincinv (Y, A, B)
 -- : X = betaincinv (Y, A, B, "lower")
 -- : X = betaincinv (Y, A, B, "upper")
     Compute the inverse of the normalized incomplete beta function.

     The normalized incomplete beta function is defined as

                                    x
                                   /
                           1       |
          I_x (a, b) = ----------  | t^(a-1) (1-t)^(b-1) dt
                       beta (a,b)  |
                                   /
                                  0

     If two inputs are scalar, then ‘betaincinv (Y, A, B)’ is returned
     for each of the other inputs.

     If two or more inputs are not scalar, the sizes of them must agree,
     and ‘betaincinv’ is applied element-by-element.

     The variable Y must be in the interval [0,1], while A and B must be
     real and strictly positive.

     By default, TAIL is "lower" and the inverse of the incomplete beta
     function integrated from 0 to X is computed.  If TAIL is "upper"
     then the complementary function integrated from X to 1 is inverted.

     The function is computed by standard Newton's method, by solving

          Y - betainc (X, A, B) = 0

     See also: *note betainc: XREFbetainc, *note beta: XREFbeta, *note
     betaln: XREFbetaln.

 -- : LNB = betaln (A, B)
     Compute the natural logarithm of the Beta function for real inputs
     A and B.

     ‘betaln’ is defined as

          betaln (a, b) = log (beta (a, b))

     and is calculated in a way to reduce the occurrence of underflow.

     The Beta function can grow quite large and it is often more useful
     to work with the logarithm of the output rather than the function
     directly.

     See also: *note beta: XREFbeta, *note betainc: XREFbetainc, *note
     betaincinv: XREFbetaincinv, *note gammaln: XREFgammaln.

 -- : B = bincoeff (N, K)
     Return the binomial coefficient of N and K.

     The binomial coefficient is defined as

           /   \
           | n |    n (n-1) (n-2) ... (n-k+1)
           |   |  = -------------------------
           | k |               k!
           \   /

     For example:

          bincoeff (5, 2)
             ⇒ 10

     In most cases, the ‘nchoosek’ function is faster for small scalar
     integer arguments.  It also warns about loss of precision for big
     arguments.

     See also: *note nchoosek: XREFnchoosek.

 -- : K = commutation_matrix (M, N)
     Return the commutation matrix K(m,n) which is the unique M*N by M*N
     matrix such that K(m,n) * vec(A) = vec(A') for all m by n matrices
     A.

     If only one argument M is given, K(m,m) is returned.

     See Magnus and Neudecker, ‘Matrix Differential Calculus with
     Applications in Statistics and Econometrics’, 1988.

 -- : Y = cosint (X)
     Compute the cosine integral function:

                      +oo
                     /
          Ci (x) = - | (cos (t)) / t dt
                     /
                    x

     An equivalent definition is

                                       x
                                      /
                                      |  cos (t) - 1
          Ci (x) = gamma + log (x) +  | -------------  dt
                                      |        t
                                      /
                                     0

     Reference:

     M. Abramowitz and I.A. Stegun, ‘Handbook of Mathematical
     Functions’, 1964.

     See also: *note sinint: XREFsinint, *note expint: XREFexpint, *note
     cos: XREFcos.

 -- : D = duplication_matrix (N)
     Return the duplication matrix Dn which is the unique
     N^2-by-N*(N+1)/2 matrix such that ‘Dn * vech (A) = vec (A)’ for all
     symmetric N-by-N matrices A.

     See Magnus and Neudecker, ‘Matrix Differential Calculus with
     Applications in Statistics and Econometrics’, 1988.

 -- : V = dawson (Z)
     Compute the Dawson (scaled imaginary error) function.

     The Dawson function is defined as

          (sqrt (pi) / 2) * exp (-z^2) * erfi (z)

     See also: *note erfc: XREFerfc, *note erf: XREFerf, *note erfcx:
     XREFerfcx, *note erfi: XREFerfi, *note erfinv: XREFerfinv, *note
     erfcinv: XREFerfcinv.

 -- : [SN, CN, DN, ERR] = ellipj (U, M)
 -- : [SN, CN, DN, ERR] = ellipj (U, M, TOL)
     Compute the Jacobi elliptic functions SN, CN, and DN of complex
     argument U and real parameter M.

     If M is a scalar, the results are the same size as U.  If U is a
     scalar, the results are the same size as M.  If U is a column
     vector and M is a row vector, the results are matrices with ‘length
     (U)’ rows and ‘length (M)’ columns.  Otherwise, U and M must
     conform in size and the results will be the same size as the
     inputs.

     The value of U may be complex.  The value of M must be 0 ≤ M ≤ 1.

     The optional input TOL is currently ignored (MATLAB uses this to
     allow faster, less accurate approximation).

     If requested, ERR contains the following status information and is
     the same size as the result.

       0. Normal return.

       1. Error--no computation, algorithm termination condition not
          met, return ‘NaN’.

     Reference: Milton Abramowitz and Irene A Stegun, ‘Handbook of
     Mathematical Functions’, Chapter 16 (Sections 16.4, 16.13, and
     16.15), Dover, 1965.

     See also: *note ellipke: XREFellipke.

 -- : K = ellipke (M)
 -- : K = ellipke (M, TOL)
 -- : [K, E] = ellipke (...)
     Compute complete elliptic integrals of the first K(M) and second
     E(M) kind.

     M must be a scalar or real array with -Inf ≤ M ≤ 1.

     The optional input TOL controls the stopping tolerance of the
     algorithm and defaults to ‘eps (class (M))’.  The tolerance can be
     increased to compute a faster, less accurate approximation.

     When called with one output only elliptic integrals of the first
     kind are returned.

     Mathematical Note:

     Elliptic integrals of the first kind are defined as

                   1
                  /               dt
          K (m) = | ------------------------------
                  / sqrt ((1 - t^2)*(1 - m*t^2))
                 0

     Elliptic integrals of the second kind are defined as

                   1
                  /  sqrt (1 - m*t^2)
          E (m) = |  ------------------ dt
                  /  sqrt (1 - t^2)
                 0

     Reference: Milton Abramowitz and Irene A. Stegun, ‘Handbook of
     Mathematical Functions’, Chapter 17, Dover, 1965.

     See also: *note ellipj: XREFellipj.

 -- : V = erf (Z)
     Compute the error function.

     The error function is defined as

                                  z
                        2        /
          erf (z) = --------- *  | e^(-t^2) dt
                    sqrt (pi)    /
                              t=0

     See also: *note erfc: XREFerfc, *note erfcx: XREFerfcx, *note erfi:
     XREFerfi, *note dawson: XREFdawson, *note erfinv: XREFerfinv, *note
     erfcinv: XREFerfcinv.

 -- : V = erfc (Z)
     Compute the complementary error function.

     The complementary error function is defined as ‘1 - erf (Z)’.

     See also: *note erfcinv: XREFerfcinv, *note erfcx: XREFerfcx, *note
     erfi: XREFerfi, *note dawson: XREFdawson, *note erf: XREFerf, *note
     erfinv: XREFerfinv.

 -- : V = erfcx (Z)
     Compute the scaled complementary error function.

     The scaled complementary error function is defined as

          exp (z^2) * erfc (z)

     See also: *note erfc: XREFerfc, *note erf: XREFerf, *note erfi:
     XREFerfi, *note dawson: XREFdawson, *note erfinv: XREFerfinv, *note
     erfcinv: XREFerfcinv.

 -- : V = erfi (Z)
     Compute the imaginary error function.

     The imaginary error function is defined as

          -i * erf (i*z)

     See also: *note erfc: XREFerfc, *note erf: XREFerf, *note erfcx:
     XREFerfcx, *note dawson: XREFdawson, *note erfinv: XREFerfinv,
     *note erfcinv: XREFerfcinv.

 -- : Y = erfinv (X)
     Compute the inverse error function.

     The inverse error function is defined such that

          erf (Y) == X

     See also: *note erf: XREFerf, *note erfc: XREFerfc, *note erfcx:
     XREFerfcx, *note erfi: XREFerfi, *note dawson: XREFdawson, *note
     erfcinv: XREFerfcinv.

 -- : Y = erfcinv (X)
     Compute the inverse complementary error function.

     The inverse complementary error function is defined such that

          erfc (Y) == X

     See also: *note erfc: XREFerfc, *note erf: XREFerf, *note erfcx:
     XREFerfcx, *note erfi: XREFerfi, *note dawson: XREFdawson, *note
     erfinv: XREFerfinv.

 -- : Y = expint (X)
     Compute the exponential integral.

     The exponential integral is defined as:

                     +oo
                    /
                    | exp (-t)
          E_1 (x) = | -------- dt
                    |    t
                    /
                   x

     Note: For compatibility, this function uses the MATLAB definition
     of the exponential integral.  Most other sources refer to this
     particular value as E_1 (x), and the exponential integral as

                      +oo
                     /
                     | exp (-t)
          Ei (x) = - | -------- dt
                     |    t
                     /
                   -x

     The two definitions are related, for positive real values of X, by
     ‘E_1 (-x) = -Ei (x) - i*pi’.

     References:

     M. Abramowitz and I.A. Stegun, ‘Handbook of Mathematical
     Functions’, 1964.

     N. Bleistein and R.A. Handelsman, ‘Asymptotic expansions of
     integrals’, 1986.

     See also: *note cosint: XREFcosint, *note sinint: XREFsinint, *note
     exp: XREFexp.

 -- : V = gamma (Z)
     Compute the Gamma function.

     The Gamma function is defined as

                       infinity
                      /
          gamma (z) = | t^(z-1) exp (-t) dt.
                      /
                   t=0

     Programming Note: The gamma function can grow quite large even for
     small input values.  In many cases it may be preferable to use the
     natural logarithm of the gamma function (‘gammaln’) in calculations
     to minimize loss of precision.  The final result is then ‘exp
     (RESULT_USING_GAMMALN).’

     See also: *note gammainc: XREFgammainc, *note gammaln: XREFgammaln,
     *note factorial: XREFfactorial.

 -- : Y = gammainc (X, A)
 -- : Y = gammainc (X, A, TAIL)
     Compute the normalized incomplete gamma function.

     This is defined as

                                          x
                                 1       /
          gammainc (x, a) = ---------    | exp (-t) t^(a-1) dt
                            gamma (a)    /
                                      t=0

     with the limiting value of 1 as X approaches infinity.  The
     standard notation is P(a,x), e.g., Abramowitz and Stegun (6.5.1).

     If A is scalar, then ‘gammainc (X, A)’ is returned for each element
     of X and vice versa.

     If neither X nor A is scalar then the sizes of X and A must agree,
     and ‘gammainc’ is applied element-by-element.  The elements of A
     must be non-negative.

     By default, TAIL is "lower" and the incomplete gamma function
     integrated from 0 to X is computed.  If TAIL is "upper" then the
     complementary function integrated from X to infinity is calculated.

     If TAIL is "scaledlower", then the lower incomplete gamma function
     is multiplied by gamma(a+1)*exp(x)/(x^a).  If TAIL is
     "scaledupper", then the upper incomplete gamma function is
     multiplied by the same quantity.

     References:

     M. Abramowitz and I.A. Stegun, ‘Handbook of mathematical
     functions’, Dover publications, Inc., 1972.

     W. Gautschi, "A computational procedure for incomplete gamma
     functions", ‘ACM Trans. Math Software’, Vol. 5, No. 4, pp. 466-481,
     2012.

     W. H. Press, S. A. Teukolsky, W. T. Vetterling, and B. P. Flannery,
     ‘Numerical Recipes in Fortran 77’, Vol. 1, ch. 6.2, 1992.

     See also: *note gamma: XREFgamma, *note gammaincinv:
     XREFgammaincinv, *note gammaln: XREFgammaln.

 -- : X = gammaincinv (Y, A)
 -- : X = gammaincinv (Y, A, TAIL)
     Compute the inverse of the normalized incomplete gamma function.

     The normalized incomplete gamma function is defined as

                                          x
                                 1       /
          gammainc (x, a) = ---------    | exp (-t) t^(a-1) dt
                            gamma (a)    /
                                      t=0

     and ‘gammaincinv (gammainc (X, A), A) = X’ for each non-negative
     value of X.  If A is scalar then ‘gammaincinv (Y, A)’ is returned
     for each element of Y and vice versa.

     If neither Y nor A is scalar then the sizes of Y and A must agree,
     and ‘gammaincinv’ is applied element-by-element.  The variable Y
     must be in the interval [0,1] while A must be real and positive.

     By default, TAIL is "lower" and the inverse of the incomplete gamma
     function integrated from 0 to X is computed.  If TAIL is "upper",
     then the complementary function integrated from X to infinity is
     inverted.

     The function is computed with Newton's method by solving

          Y - gammainc (X, A) = 0

     Reference: A. Gil, J. Segura, and N. M. Temme, "Efficient and
     accurate algorithms for the computation and inversion of the
     incomplete gamma function ratios", ‘SIAM J. Sci. Computing’,
     Vol. 34, pp. A2965-A2981, 2012.

     See also: *note gammainc: XREFgammainc, *note gamma: XREFgamma,
     *note gammaln: XREFgammaln.

 -- : L = legendre (N, X)
 -- : L = legendre (N, X, NORMALIZATION)
     Compute the associated Legendre function of degree N and order M =
     0 ... N.

     The value N must be a real non-negative integer.

     X is a vector with real-valued elements in the range [-1, 1].

     The optional argument NORMALIZATION may be one of "unnorm", "sch",
     or "norm".  The default if no normalization is given is "unnorm".

     When the optional argument NORMALIZATION is "unnorm", compute the
     associated Legendre function of degree N and order M and return all
     values for M = 0 ... N.  The return value has one dimension more
     than X.

     The associated Legendre function of degree N and order M:

           m         m      2  m/2   d^m
          P(x) = (-1) * (1-x  )    * ----  P(x)
           n                         dx^m   n

     with Legendre polynomial of degree N:

                    1    d^n   2    n
          P(x) = ------ [----(x - 1) ]
           n     2^n n!  dx^n

     ‘legendre (3, [-1.0, -0.9, -0.8])’ returns the matrix:

           x  |   -1.0   |   -0.9   |   -0.8
          ------------------------------------
          m=0 | -1.00000 | -0.47250 | -0.08000
          m=1 |  0.00000 | -1.99420 | -1.98000
          m=2 |  0.00000 | -2.56500 | -4.32000
          m=3 |  0.00000 | -1.24229 | -3.24000

     When the optional argument NORMALIZATION is "sch", compute the
     Schmidt semi-normalized associated Legendre function.  The Schmidt
     semi-normalized associated Legendre function is related to the
     unnormalized Legendre functions by the following:

     For Legendre functions of degree N and order 0:

            0      0
          SP(x) = P(x)
            n      n

     For Legendre functions of degree n and order m:

            m      m         m    2(n-m)! 0.5
          SP(x) = P(x) * (-1)  * [-------]
            n      n              (n+m)!

     When the optional argument NORMALIZATION is "norm", compute the
     fully normalized associated Legendre function.  The fully
     normalized associated Legendre function is related to the
     unnormalized associated Legendre functions by the following:

     For Legendre functions of degree N and order M

            m      m         m    (n+0.5)(n-m)! 0.5
          NP(x) = P(x) * (-1)  * [-------------]
            n      n                  (n+m)!

 -- : Y = gammaln (X)
 -- : Y = lgamma (X)
     Return the natural logarithm of the gamma function of X.

     Programming Note: ‘lgamma’ is an alias for ‘gammaln’ and either
     name can be used in Octave.

     See also: *note gamma: XREFgamma, *note gammainc: XREFgammainc.

 -- : Y = psi (Z)
 -- : Y = psi (K, Z)
     Compute the psi (polygamma) function.

     The polygamma functions are the Kth derivative of the logarithm of
     the gamma function.  If unspecified, K defaults to zero.  A value
     of zero computes the digamma function, a value of 1, the trigamma
     function, and so on.

     The digamma function is defined:

          psi (z) = d (log (gamma (z))) / dx

     When computing the digamma function (when K equals zero), Z can
     have any value real or complex value.  However, for polygamma
     functions (K higher than 0), Z must be real and non-negative.

     See also: *note gamma: XREFgamma, *note gammainc: XREFgammainc,
     *note gammaln: XREFgammaln.

 -- : Y = sinint (X)
     Compute the sine integral function:

                     x
                    /
          Si (x) =  | sin (t) / t dt
                    /
                   0

     Reference: M. Abramowitz and I.A. Stegun, ‘Handbook of Mathematical
     Functions’, 1964.

     See also: *note cosint: XREFcosint, *note expint: XREFexpint, *note
     sin: XREFsin.

