### DO NOT EDIT!
###
### This file is generated automatically from Octave source files.
### Edit source files directly and run make to update this file.

@ftp/ascii
@c @ftp/ascii scripts/@ftp/ascii.m
-*- texinfo -*-
@deftypefn {Function File} {} ascii (@var{f})
Set the FTP connection @var{f} to use ASCII mode for transfers.

ASCII mode is only appropriate for text files as it will convert the
remote host's newline representation to the local host's newline
representation.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
@ftp/binary
@c @ftp/binary scripts/@ftp/binary.m
-*- texinfo -*-
@deftypefn {Function File} {} binary (@var{f})
Set the FTP connection @var{f} to use binary mode for transfers.

In binary mode there is no conversion of newlines from the remote
representation to the local representation.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
@ftp/cd
@c @ftp/cd scripts/@ftp/cd.m
-*- texinfo -*-
@deftypefn  {Function File} {} cd (@var{f})
@deftypefnx {Function File} {} cd (@var{f}, @var{path})
Get or set the remote directory on the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.

If @var{path} is not specified, return the remote current working
directory.  Otherwise, set the remote directory to @var{path} and return
the new remote working directory.

If the directory does not exist, an error message is printed and the
working directory is not changed.
@end deftypefn
@ftp/close
@c @ftp/close scripts/@ftp/close.m
-*- texinfo -*-
@deftypefn {Function File} {} close (@var{f})
Close the FTP connection represented by the FTP object @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
@ftp/delete
@c @ftp/delete scripts/@ftp/delete.m
-*- texinfo -*-
@deftypefn {Function File} {} delete (@var{f}, @var{file})
Delete the remote file @var{file} over the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
@ftp/dir
@c @ftp/dir scripts/@ftp/dir.m
-*- texinfo -*-
@deftypefn {Function File} {@var{lst} =} dir (@var{f})
List the current directory in verbose form for the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
@ftp/ftp
@c @ftp/ftp scripts/@ftp/ftp.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{f} =} ftp (@var{host})
@deftypefnx {Function File} {@var{f} =} ftp (@var{host}, @var{username}, @var{password})
Connect to the FTP server @var{host} with @var{username} and @var{password}.

If @var{username} and @var{password} are not specified, user
@qcode{"anonymous"} with no password is used.  The returned FTP object
@var{f} represents the established FTP connection.

The list of actions for an FTP object are shown below.  All functions
require an FTP object as the first argument.

@multitable @columnfractions 0.15 0.8
@headitem Method @tab Description
@item ascii @tab Set transfer type to ascii
@item binary @tab Set transfer type to binary
@item cd @tab Change remote working directory
@item close @tab Close FTP connection
@item delete @tab Delete remote file
@item dir @tab List remote directory contents
@item mget @tab Download remote files
@item mkdir @tab Create remote directory
@item mput @tab Upload local files
@item rename @tab Rename remote file or directory
@item rmdir @tab Remove remote directory
@end multitable

@end deftypefn
@ftp/mget
@c @ftp/mget scripts/@ftp/mget.m
-*- texinfo -*-
@deftypefn  {Function File} {} mget (@var{f}, @var{file})
@deftypefnx {Function File} {} mget (@var{f}, @var{dir})
@deftypefnx {Function File} {} mget (@var{f}, @var{remote_name}, @var{target})
Download a remote file @var{file} or directory @var{dir} to the local
directory on the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.

The arguments @var{file} and @var{dir} can include wildcards and any
files or directories on the remote server that match will be downloaded.

If a third argument @var{target} is given, then a single file or
directory will be downloaded to the local directory and the local name
will be changed to @var{target}.
@end deftypefn
@ftp/mkdir
@c @ftp/mkdir scripts/@ftp/mkdir.m
-*- texinfo -*-
@deftypefn {Function File} {} mkdir (@var{f}, @var{path})
Create the remote directory @var{path}, over the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
@ftp/mput
@c @ftp/mput scripts/@ftp/mput.m
-*- texinfo -*-
@deftypefn {Function File} {} mput (@var{f}, @var{file})
Upload the local file @var{file} into the current remote directory on the
FTP connection @var{f}.

@var{f} is an FTP object returned by the ftp function.

The argument @var{file} is passed through the @code{glob} function and any
files that match the wildcards in @var{file} will be uploaded.
@end deftypefn
@ftp/rename
@c @ftp/rename scripts/@ftp/rename.m
-*- texinfo -*-
@deftypefn {Function File} {} rename (@var{f}, @var{oldname}, @var{newname})
Rename or move the remote file or directory @var{oldname} to @var{newname},
over the FTP connection @var{f}.

@var{f} is an FTP object returned by the ftp function.
@end deftypefn
@ftp/rmdir
@c @ftp/rmdir scripts/@ftp/rmdir.m
-*- texinfo -*-
@deftypefn {Function File} {} rmdir (@var{f}, @var{path})
Remove the remote directory @var{path}, over the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@end deftypefn
lin2mu
@c lin2mu scripts/audio/lin2mu.m
-*- texinfo -*-
@deftypefn {Function File} {} lin2mu (@var{x}, @var{n})
Convert audio data from linear to mu-law.

Mu-law values use 8-bit unsigned integers.  Linear values use @var{n}-bit
signed integers or floating point values in the range -1 @leq{} @var{x}
@leq{} 1 if @var{n} is 0.

If @var{n} is not specified it defaults to 0, 8, or 16 depending on
the range of values in @var{x}.
@seealso{mu2lin}
@end deftypefn
mu2lin
@c mu2lin scripts/audio/mu2lin.m
-*- texinfo -*-
@deftypefn {Function File} {} mu2lin (@var{x}, @var{n})
Convert audio data from mu-law to linear.

Mu-law values are 8-bit unsigned integers.  Linear values use @var{n}-bit
signed integers or floating point values in the range -1@leq{}y@leq{}1 if
@var{n} is 0.

If @var{n} is not specified it defaults to 0.
@seealso{lin2mu}
@end deftypefn
record
@c record scripts/audio/record.m
-*- texinfo -*-
@deftypefn  {Function File} {} record (@var{sec})
@deftypefnx {Function File} {} record (@var{sec}, @var{fs})
Record @var{sec} seconds of audio from the system's default audio input at
a sampling rate of 8000 samples per second.

If the optional argument @var{fs} is given, it specifies the sampling rate
for recording.

For more control over audio recording, use the @code{audiorecorder} class.
@seealso{sound, soundsc}
@end deftypefn
sound
@c sound scripts/audio/sound.m
-*- texinfo -*-
@deftypefn  {Function File} {} sound (@var{y})
@deftypefnx {Function File} {} sound (@var{y}, @var{fs})
@deftypefnx {Function File} {} sound (@var{y}, @var{fs}, @var{nbits})
Play audio data @var{y} at sample rate @var{fs} to the default audio
device.

The audio signal @var{y} can be a vector or a two-column array, representing
mono or stereo audio, respectively.

If @var{fs} is not given, a default sample rate of 8000 samples per second
is used.

The optional argument @var{nbits} specifies the bit depth to play to the
audio device and defaults to 8 bits.

For more control over audio playback, use the @code{audioplayer} class.
@seealso{soundsc, record}
@end deftypefn
soundsc
@c soundsc scripts/audio/soundsc.m
-*- texinfo -*-
@deftypefn  {Function File} {} soundsc (@var{y})
@deftypefnx {Function File} {} soundsc (@var{y}, @var{fs})
@deftypefnx {Function File} {} soundsc (@var{y}, @var{fs}, @var{nbits})
@deftypefnx {Function File} {} soundsc (@dots{}, [@var{ymin}, @var{ymax}])
Scale the audio data @var{y} and play it at sample rate @var{fs} to the
default audio device.

The audio signal @var{y} can be a vector or a two-column array, representing
mono or stereo audio, respectively.

If @var{fs} is not given, a default sample rate of 8000 samples per second
is used.

The optional argument @var{nbits} specifies the bit depth to play to the
audio device and defaults to 8 bits.

By default, @var{y} is automatically normalized to the range [-1, 1].  If the
range [@var{ymin}, @var{ymax}] is given, then elements of @var{y} that fall
within the range @var{ymin} @leq{} @var{y} @leq{} @var{ymax} are scaled to
the range [-1, 1] instead.

For more control over audio playback, use the @code{audioplayer} class.
@seealso{sound, record}
@end deftypefn
wavread
@c wavread scripts/audio/wavread.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{y} =} wavread (@var{filename})
@deftypefnx {Function File} {[@var{y}, @var{fs}, @var{nbits}] =} wavread (@var{filename})
@deftypefnx {Function File} {[@dots{}] =} wavread (@var{filename}, @var{n})
@deftypefnx {Function File} {[@dots{}] =} wavread (@var{filename}, [@var{n1} @var{n2}])
@deftypefnx {Function File} {[@dots{}] =} wavread (@dots{}, @var{datatype})
@deftypefnx {Function File} {@var{sz} =} wavread (@var{filename}, "size")
@deftypefnx {Function File} {[@var{n_samp}, @var{n_chan}] =} wavread (@var{filename}, "size")
Read the audio signal @var{y} from the RIFF/WAVE sound file @var{filename}.

If the file contains multichannel data, then @var{y} is a matrix with the
channels represented as columns.

If @var{n} is specified, only the first @var{n} samples of the file are
returned.  If [@var{n1} @var{n2}] is specified, only the range of samples
from @var{n1} to @var{n2} is returned.  A value of @code{Inf} can be used
to represent the total number of samples in the file.

If the option @qcode{"size"} is given, then the size of the audio signal
is returned instead of the data.  The size is returned in a row vector of
the form [@var{samples} @var{channels}].  If there are two output arguments,
the number of samples is assigned to the first and the number of channels
is assigned to the second.

The optional return value @var{fs} is the sample rate of the audio file in
Hz.  The optional return value @var{nbits} is the number of bits per sample
as encoded in the file.

@seealso{audioread, audiowrite, wavwrite}
@end deftypefn
wavwrite
@c wavwrite scripts/audio/wavwrite.m
-*- texinfo -*-
@deftypefn  {Function File} {} wavwrite (@var{y}, @var{filename})
@deftypefnx {Function File} {} wavwrite (@var{y}, @var{fs}, @var{filename})
@deftypefnx {Function File} {} wavwrite (@var{y}, @var{fs}, @var{nbits}, @var{filename})
Write the audio signal @var{y} to the RIFF/WAVE sound file @var{filename}.

If @var{y} is a matrix, the columns represent multiple audio channels.

The optional argument @var{fs} specifies the sample rate of the audio signal
in Hz.

The optional argument @var{nbits} specifies the number of bits per sample
to write to @var{filename}.

The default sample rate is 8000 Hz and the default bit depth is 16 bits
per sample.

@seealso{audiowrite, audioread, wavread}
@end deftypefn
@audioplayer/__get_properties__
@c @audioplayer/__get_properties__ scripts/audio/@audioplayer/__get_properties__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{properties} =} __get_properties__ (@var{player})
Return a struct containing all named properties of the audioplayer object
@var{player}.
@end deftypefn
@audioplayer/audioplayer
@c @audioplayer/audioplayer scripts/audio/@audioplayer/audioplayer.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{player} =} audioplayer (@var{y}, @var{fs})
@deftypefnx {Function File} {@var{player} =} audioplayer (@var{y}, @var{fs}, @var{nbits})
@deftypefnx {Function File} {@var{player} =} audioplayer (@var{y}, @var{fs}, @var{nbits}, @var{id})
@deftypefnx {Function File} {@var{player} =} audioplayer (@var{recorder})
@deftypefnx {Function File} {@var{player} =} audioplayer (@var{recorder}, @var{id})
Create an audioplayer object that will play back data @var{y} at sample
rate @var{fs}.

The optional arguments @var{nbits}, and @var{id} specify the bit depth and
player device id, respectively.  Device IDs may be found using the
audiodevinfo function.  Given an audioplayer object, use the data from the
object to initialize the player.

The signal @var{y} can be a vector or a two-dimensional array.

The following example will create an audioplayer object that will play
back one second of white noise at 44100 sample rate using 8 bits per
sample.

@example
@group
y = randn (2, 44100) - 0.5;
player = audioplayer (y, 44100, 8);
play (player);
@end group
@end example
@end deftypefn
@audioplayer/display
@c @audioplayer/display scripts/audio/@audioplayer/display.m
-*- texinfo -*-
@deftypefn {Function File} {} display (@var{player})
Display the properties of the audioplayer object @var{player}.
@end deftypefn
@audioplayer/get
@c @audioplayer/get scripts/audio/@audioplayer/get.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{value} =} get (@var{player}, @var{name})
@deftypefnx {Function File} {@var{values} =} get (@var{player})
Return the @var{value} of the property identified by @var{name}.

If @var{name} is a cell array return the values of the properties
identified by the elements of the cell array.  Given only the player
object, return a scalar structure with values of all properties of
@var{player}.  The field names of the structure correspond to property
names.
@end deftypefn
@audioplayer/isplaying
@c @audioplayer/isplaying scripts/audio/@audioplayer/isplaying.m
-*- texinfo -*-
@deftypefn {Function File} {} isplaying (@var{player})
Return true if the audioplayer object @var{player} is currently playing back
audio and false otherwise.
@end deftypefn
@audioplayer/pause
@c @audioplayer/pause scripts/audio/@audioplayer/pause.m
-*- texinfo -*-
@deftypefn {Function File} {} pause (@var{player})
Pause the audioplayer @var{player}.
@end deftypefn
@audioplayer/play
@c @audioplayer/play scripts/audio/@audioplayer/play.m
-*- texinfo -*-
@deftypefn  {Function File} {} play (@var{player})
@deftypefnx {Function File} {} play (@var{player}, @var{start})
@deftypefnx {Function File} {} play (@var{player}, @var{limits})
Play audio stored in the audioplayer object @var{player} without blocking.

Given optional argument start, begin playing at @var{start} seconds in the
recording.  Given a two-element vector @var{limits}, begin and end playing
at the number of seconds specified by the elements of the vector.
@end deftypefn
@audioplayer/playblocking
@c @audioplayer/playblocking scripts/audio/@audioplayer/playblocking.m
-*- texinfo -*-
@deftypefn  {Function File} {} playblocking (@var{player})
@deftypefnx {Function File} {} playblocking (@var{player}, @var{start})
@deftypefnx {Function File} {} playblocking (@var{player}, @var{limits})
Play audio stored in the audioplayer object @var{player} with blocking.

Given optional argument start, begin playing at @var{start} seconds in the
recording.  Given a two-element vector @var{limits}, begin and end playing
at the number of seconds specified by the elements of the vector.
@end deftypefn
@audioplayer/resume
@c @audioplayer/resume scripts/audio/@audioplayer/resume.m
-*- texinfo -*-
@deftypefn {Function File} {} resume (@var{player})
Resume playback for the paused audioplayer object @var{player}.
@end deftypefn
@audioplayer/set
@c @audioplayer/set scripts/audio/@audioplayer/set.m
-*- texinfo -*-
@deftypefn  {Function File} {} set (@var{player}, @var{name}, @var{value})
@deftypefnx {Function File} {} set (@var{player}, @var{properties})
@deftypefnx {Function File} {@var{properties} =} set (@var{player})
Set the value of property specified by @var{name} to a given @var{value}.

If @var{name} and @var{value} are cell arrays, set each property to the
corresponding value.  Given a structure of @var{properties} with fields
corresponding to property names, set the value of those properties to the
field values.  Given only the audioplayer object, return a structure of
settable properties.
@end deftypefn
@audioplayer/stop
@c @audioplayer/stop scripts/audio/@audioplayer/stop.m
-*- texinfo -*-
@deftypefn {Function File} {} stop (@var{player})
Stop the playback for the audioplayer @var{player} and reset the
relevant variables to their starting values.
@end deftypefn
@audioplayer/subsasgn
@c @audioplayer/subsasgn scripts/audio/@audioplayer/subsasgn.m
-*- texinfo -*-
@deftypefn {Function File} {@var{value} =} subsasgn (@var{player}, @var{idx}, @var{rhs})
Perform subscripted assignment on the audio player object @var{player}.

Assign the value of @var{rhs} to the player property named by @var{idx}.
@end deftypefn
@audioplayer/subsref
@c @audioplayer/subsref scripts/audio/@audioplayer/subsref.m
-*- texinfo -*-
@deftypefn {Function File} {@var{value} =} subsref (@var{player}, @var{idx})
Perform subscripted selection on the audio player object @var{player}.

Return the player property value named by @var{idx}.
@end deftypefn
@audiorecorder/__get_properties__
@c @audiorecorder/__get_properties__ scripts/audio/@audiorecorder/__get_properties__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{properties} =} __get_properties__ (@var{recorder})
Return a struct containing all named properties of the recorder object
@var{recorder}.
@end deftypefn
@audiorecorder/audiorecorder
@c @audiorecorder/audiorecorder scripts/audio/@audiorecorder/audiorecorder.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{recorder} =} audiorecorder ()
@deftypefnx {Function File} {@var{recorder} =} audiorecorder (@var{fs}, @var{nbits}, @var{channels})
@deftypefnx {Function File} {@var{recorder} =} audiorecorder (@var{fs}, @var{nbits}, @var{channels}, @var{id})
Create an audiorecorder object recording 8 bit mono audio at 8000 Hz
sample rate.

The optional arguments @var{fs}, @var{nbits}, @var{channels}, and @var{id}
specify the sample rate, bit depth, number of channels and recording
device id, respectively.  Device IDs may be found using the audiodevinfo
function.
@end deftypefn
@audiorecorder/display
@c @audiorecorder/display scripts/audio/@audiorecorder/display.m
-*- texinfo -*-
@deftypefn {Function File} {} display (@var{recorder})
Display the properties of the audiorecorder object @var{recorder}.
@end deftypefn
@audiorecorder/get
@c @audiorecorder/get scripts/audio/@audiorecorder/get.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{value} =} get (@var{recorder}, @var{name})
@deftypefnx {Function File} {@var{values} =} get (@var{recorder})
Return the @var{value} of the property identified by @var{name}.

If @var{name} is a cell array, return the values of the properties
corresponding to the elements of the cell array.  Given only the recorder
object, return a scalar structure with values of all properties of
@var{recorder}.  The field names of the structure correspond to property
names.
@end deftypefn
@audiorecorder/getaudiodata
@c @audiorecorder/getaudiodata scripts/audio/@audiorecorder/getaudiodata.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{data} =} getaudiodata (@var{recorder})
@deftypefnx {Function File} {@var{data} =} getaudiodata (@var{recorder}, @var{datatype})
Return recorder audio data as a matrix with values between -1.0 and 1.0
and with as many columns as there are channels in the recorder.

Given the optional argument @var{datatype}, convert the recorded data
to the specified type, which may be one of @qcode{"double"},
@qcode{"single"}, @qcode{"int16"}, @qcode{"int8"} or @qcode{"uint8"}.
@end deftypefn
@audiorecorder/getplayer
@c @audiorecorder/getplayer scripts/audio/@audiorecorder/getplayer.m
-*- texinfo -*-
@deftypefn {Function File} {@var{player} =} getplayer (@var{recorder})
Return an audioplayer object with data recorded by the audiorecorder object
@var{recorder}.
@end deftypefn
@audiorecorder/isrecording
@c @audiorecorder/isrecording scripts/audio/@audiorecorder/isrecording.m
-*- texinfo -*-
@deftypefn {Function File} {} isrecording (@var{recorder})
Return true if the audiorecorder object @var{recorder} is currently recording
audio and false otherwise.
@end deftypefn
@audiorecorder/pause
@c @audiorecorder/pause scripts/audio/@audiorecorder/pause.m
-*- texinfo -*-
@deftypefn {Function File} {} pause (@var{recorder})
Pause recording with audiorecorder object @var{recorder}.
@end deftypefn
@audiorecorder/play
@c @audiorecorder/play scripts/audio/@audiorecorder/play.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{player} =} play (@var{recorder})
@deftypefnx {Function File} {@var{player} =} play (@var{recorder}, @var{start})
@deftypefnx {Function File} {@var{player} =} play (@var{recorder}, [@var{start}, @var{end}])
Play the audio recorded in @var{recorder} and return a corresponding
audioplayer object.

If the optional argument @var{start} is provided, begin playing
@var{start} seconds in to the recording.

If the optional argument @var{end} is provided, stop playing at
@var{end} seconds in the recording.
@end deftypefn
@audiorecorder/record
@c @audiorecorder/record scripts/audio/@audiorecorder/record.m
-*- texinfo -*-
@deftypefn  {Function File} {} record (@var{recorder})
@deftypefnx {Function File} {} record (@var{recorder}, @var{length})
Record audio without blocking using the audiorecorder object
@var{recorder} until stopped or paused by the @var{stop} or @var{pause}
method.

Given the optional argument @var{length}, record for @var{length} seconds.
@end deftypefn
@audiorecorder/recordblocking
@c @audiorecorder/recordblocking scripts/audio/@audiorecorder/recordblocking.m
-*- texinfo -*-
@deftypefn {Function File} {} recordblocking (@var{recorder}, @var{length})
Record audio with blocking (synchronous I/O).

The length of the recording in seconds (@var{length}) must be specified.
@end deftypefn
@audiorecorder/resume
@c @audiorecorder/resume scripts/audio/@audiorecorder/resume.m
-*- texinfo -*-
@deftypefn {Function File} {} resume (@var{recorder})
Resume recording with the paused audiorecorder object @var{recorder}.
@end deftypefn
@audiorecorder/set
@c @audiorecorder/set scripts/audio/@audiorecorder/set.m
-*- texinfo -*-
@deftypefn  {Function File} {} set (@var{recorder}, @var{name}, @var{value})
@deftypefnx {Function File} {} set (@var{recorder}, @var{properties})
@deftypefnx {Function File} {@var{properties} =} set (@var{recorder})
Set the value of property specified by @var{name} to a given @var{value}.

If @var{name} and @var{value} are cell arrays of the same size, set each
property to a corresponding value.  Given a structure with fields
corresponding to property names, set the value of those properties to the
corresponding field values.  Given only the recorder object, return a
structure of settable properties.
@end deftypefn
@audiorecorder/stop
@c @audiorecorder/stop scripts/audio/@audiorecorder/stop.m
-*- texinfo -*-
@deftypefn {Function File} {} stop (@var{recorder})
Stop the audiorecorder object @var{recorder} and clean up any audio streams.
@end deftypefn
@audiorecorder/subsasgn
@c @audiorecorder/subsasgn scripts/audio/@audiorecorder/subsasgn.m
-*- texinfo -*-
@deftypefn {Function File} {@var{value} =} subsasgn (@var{recorder}, @var{idx}, @var{rhs})
Perform subscripted assignment on the audio recorder object @var{recorder}.

Assign the value of @var{rhs} to the recorder property named by @var{idx}.
@end deftypefn
@audiorecorder/subsref
@c @audiorecorder/subsref scripts/audio/@audiorecorder/subsref.m
-*- texinfo -*-
@deftypefn {Function File} {@var{value} =} subsref (@var{recorder}, @var{idx})
Perform subscripted selection on the audio recorder object @var{recorder}.

Return the recorder property value named by @var{idx}.
@end deftypefn
bicubic
@c bicubic scripts/deprecated/bicubic.m
-*- texinfo -*-
@deftypefn {Function File} {@var{zi} =} bicubic (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi}, @var{extrapval})

@code{bicubic} is deprecated and will be removed in Octave version 4.4.
Use @code{interp2 (@dots{}, "spline")} for the equivalent functionality.

Return a matrix @var{zi} corresponding to the bicubic
interpolations at @var{xi} and @var{yi} of the data supplied
as @var{x}, @var{y} and @var{z}.  Points outside the grid are set
to @var{extrapval}.

See @url{http://wiki.woodpecker.org.cn/moin/Octave/Bicubic}
for further information.
@seealso{interp2}
@end deftypefn
default_save_options
@c default_save_options scripts/deprecated/default_save_options.m
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} default_save_options ()
@deftypefnx {Built-in Function} {@var{old_val} =} default_save_options (@var{new_val})
@deftypefnx {Built-in Function} {} default_save_options (@var{new_val}, "local")
This function has been deprecated.  Use @code{@file{save_default_options}}
instead.
@seealso{save_default_options}
@end deftypefn
delaunay3
@c delaunay3 scripts/deprecated/delaunay3.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{tetr} =} delaunay3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {@var{tetr} =} delaunay3 (@var{x}, @var{y}, @var{z}, @var{options})

@code{delaunay3} is deprecated and will be removed in Octave version 4.4.
Please use @code{delaunay} in all new code.

Compute the Delaunay triangulation for a 3-D set of points.
The return value @var{tetr} is a set of tetrahedrons which satisfies the
Delaunay circum-circle criterion, i.e., only a single data point from
[@var{x}, @var{y}, @var{z}] is within the circum-circle of the defining
tetrahedron.

The set of tetrahedrons @var{tetr} is a matrix of size [n, 4].  Each
row defines a tetrahedron and the four columns are the four vertices
of the tetrahedron.  The value of @code{@var{tetr}(i,j)} is an index into
@var{x}, @var{y}, @var{z} for the location of the j-th vertex of the i-th
tetrahedron.

An optional fourth argument, which must be a string or cell array of strings,
contains options passed to the underlying qhull command.
See the documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.
The default options are @code{@{"Qt", "Qbb", "Qc", "Qz"@}}.

If @var{options} is not present or @code{[]} then the default arguments are
used.  Otherwise, @var{options} replaces the default argument list.
To append user options to the defaults it is necessary to repeat the
default arguments in @var{options}.  Use a null string to pass no arguments.

@seealso{delaunay, delaunayn, convhull, voronoi, tetramesh}
@end deftypefn
dump_prefs
@c dump_prefs scripts/deprecated/dump_prefs.m
-*- texinfo -*-
@deftypefn  {Function File} {} dump_prefs ()
@deftypefnx {Function File} {} dump_prefs (@var{fid})

@code{dump_prefs} is deprecated and will be removed in Octave version 4.4.
Please use individual preference get/set routines in all new code.

Dump the current settings of all user preferences to stdout in a format that
can be parsed by Octave later.

If the optional argument @var{fid} is given then the results are written to
the file specified by file descriptor @var{fid}.
@seealso{octave_config_info}
@end deftypefn
find_dir_in_path
@c find_dir_in_path scripts/deprecated/find_dir_in_path.m
-*- texinfo -*-
@deftypefn  {Built-in Function} {} find_dir_in_path (@var{dir})
@deftypefnx {Built-in Function} {} find_dir_in_path (@var{dir}, "all")
This function has been deprecated.  Use @code{dir_in_loadpath} instead.
@seealso{dir_in_loadpath}
@end deftypefn
finite
@c finite scripts/deprecated/finite.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} finite (@var{x})

@code{finite} is deprecated and will be removed in Octave version 4.4.
Please use @code{isfinite} in all new code.

Return a logical array which is true where the elements of @var{x} are
finite values and false where they are not.
For example:

@example
@group
finite ([13, Inf, NA, NaN])
     @result{} [ 1, 0, 0, 0 ]
@end group
@end example
@seealso{isfinite, isinf, isnan, isna}
@end deftypefn
fmod
@c fmod scripts/deprecated/fmod.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} fmod (@var{x}, @var{y})

@code{fmod} is deprecated and will be removed in Octave version 4.4.
Please use @code{rem} in all new code.

Return the remainder of the division @code{@var{x} / @var{y}}, computed
using the expression

@example
x - y .* fix (x ./ y)
@end example

An error message is printed if the dimensions of the arguments do not
agree, or if either of the arguments is complex.
@seealso{rem, mod}
@end deftypefn
fnmatch
@c fnmatch scripts/deprecated/fnmatch.m
-*- texinfo -*-
@deftypefn {Built-in Function} {} fnmatch (@var{pattern}, @var{string})

@code{fnmatch} is deprecated and will be removed in Octave version 4.4.
Please use @code{glob} or @code{regexp} in all new code.

Return true or false for each element of @var{string} that matches any of
the elements of the string array @var{pattern}, using the rules of
filename pattern matching.  For example:

@example
@group
fnmatch (\"a*b\", @{\"ab\"; \"axyzb\"; \"xyzab\"@})
     @result{} [ 1; 1; 0 ]
@end group
@end example
@seealso{glob, regexp}
@end deftypefn
gen_doc_cache
@c gen_doc_cache scripts/deprecated/gen_doc_cache.m
-*- texinfo -*-
@deftypefn {Function File} {} gen_doc_cache (@var{out_file}, @var{directory})
This function has been deprecated.  Use @code{doc_cache_create} instead.
@seealso{doc_cache_create}
@end deftypefn
gmap40
@c gmap40 scripts/deprecated/gmap40.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} gmap40 ()
@deftypefnx {Function File} {@var{map} =} gmap40 (@var{n})

@code{gmap40} is deprecated and will be removed in Octave version 4.4.

Create color colormap.  The colormap consists of red, green, blue, yellow,
magenta and cyan.

This colormap is specifically designed for users of gnuplot 4.0 where these
6 colors are the allowable ones for patch objects.

The argument @var{n} must be a scalar.
If unspecified, a length of 6 is assumed.  Larger values of @var{n} result
in a repetition of the above colors.
@seealso{colormap}
@end deftypefn
interp1q
@c interp1q scripts/deprecated/interp1q.m
-*- texinfo -*-
@deftypefn {Function File} {@var{yi} =} interp1q (@var{x}, @var{y}, @var{xi})
One-dimensional linear interpolation without error checking.
Interpolates @var{y}, defined at the points @var{x}, at the points
@var{xi}.  The sample points @var{x} must be a strictly monotonically
increasing column vector.  If @var{y} is a matrix or an N-dimensional
array, the interpolation is performed on each column of @var{y}.  If
@var{y} is a vector, it must be a column vector of the same length as
@var{x}.

Values of @var{xi} beyond the endpoints of the interpolation result
in NA being returned.

Note that the error checking is only a significant portion of the
execution time of this @code{interp1} if the size of the input arguments
is relatively small.  Therefore, the benefit of using @code{interp1q}
is relatively small.
@seealso{interp1}
@end deftypefn
isequalwithequalnans
@c isequalwithequalnans scripts/deprecated/isequalwithequalnans.m
-*- texinfo -*-
@deftypefn {Function File} {} isequalwithequalnans (@var{x1}, @var{x2}, @dots{})
This function has been deprecated.  Use @code{@file{isequaln}} instead.
@seealso{isequaln}
@end deftypefn
isstr
@c isstr scripts/deprecated/isstr.m
-*- texinfo -*-
@deftypefn {Function File} {} isstr (@var{a})
This function has been deprecated.  Use ischar instead.
@end deftypefn
java_convert_matrix
@c java_convert_matrix scripts/deprecated/java_convert_matrix.m
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} java_convert_matrix ()
@deftypefnx {Built-in Function} {@var{old_val} =} java_convert_matrix (@var{new_val})
@deftypefnx {Built-in Function} {} java_convert_matrix (@var{new_val}, "local")
Query or set the internal variable that controls whether Java arrays are
automatically converted to Octave matrices.  The default value is false.

When called from inside a function with the @qcode{"local"} option, the
variable is changed locally for the function and any subroutines it calls.
 The original variable value is restored when exiting the function.
@seealso{java_matrix_autoconversion, java_unsigned_conversion, java_debug}
@end deftypefn
java_debug
@c java_debug scripts/deprecated/java_debug.m
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} java_debug ()
@deftypefnx {Built-in Function} {@var{old_val} =} java_debug (@var{new_val})
@deftypefnx {Built-in Function} {} java_debug (@var{new_val}, "local")
Query or set the internal variable that determines whether extra debugging
information regarding the initialization of the JVM and any Java exceptions
is printed.

When called from inside a function with the @qcode{"local"} option, the
variable is changed locally for the function and any subroutines it calls.
 The original variable value is restored when exiting the function.
@seealso{debug_java, java_convert_matrix, java_unsigned_conversion}
@end deftypefn
java_invoke
@c java_invoke scripts/deprecated/java_invoke.m
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{ret} =} java_invoke (@var{obj}, @var{methodname})
@deftypefnx {Built-in Function} {@var{ret} =} java_invoke (@var{obj}, @var{methodname}, @var{arg1}, @dots{})
Invoke the method @var{methodname} on the Java object @var{obj} with the
arguments @var{arg1}, @dots{}  For static methods, @var{obj} can be a
string representing the fully qualified name of the corresponding class.
The function returns the result of the method invocation.

When @var{obj} is a regular Java object, structure-like indexing can be
used as a shortcut syntax.  For instance, the two following statements are
equivalent

@example
@group
  ret = java_invoke (x, "method1", 1.0, "a string")
  ret = x.method1 (1.0, "a string")
@end group
@end example

@seealso{javaMethod, javaObject}
@end deftypefn
java_new
@c java_new scripts/deprecated/java_new.m
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{obj} =} java_new (@var{name})
@deftypefnx {Loadable Function} {@var{obj} =} java_new (@var{name}, @var{arg1}, @dots{})
Create a Java object of class @var{name}, by calling the class constructor
with the arguments @var{arg1}, @dots{}

@example
@group
  x = java_new ("java.lang.StringBuffer")
  x = java_new ("java.lang.StringBuffer", "Initial string")
@end group
@end example

@seealso{javaObject, javaMethod}
@end deftypefn
java_unsigned_conversion
@c java_unsigned_conversion scripts/deprecated/java_unsigned_conversion.m
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} java_unsigned_conversion ()
@deftypefnx {Built-in Function} {@var{old_val} =} java_unsigned_conversion (@var{new_val})
@deftypefnx {Built-in Function} {} java_unsigned_conversion (@var{new_val}, "local")
Query or set the internal variable that controls how integer classes are
converted when Java matrix autoconversion is enabled.  When enabled, Java
arrays of class Byte or Integer are converted to matrices of class uint8 or
uint32 respectively.

When called from inside a function with the @qcode{"local"} option, the
variable is changed locally for the function and any subroutines it calls.
 The original variable value is restored when exiting the function.
@seealso{java_unsigned_autoconversion, java_convert_matrix, debug_java}
@end deftypefn
javafields
@c javafields scripts/deprecated/javafields.m
-*- texinfo -*-
@deftypefn  {Function File} {} javafields (@var{javaobj})
@deftypefnx {Function File} {} javafields ("@var{classname}")
@deftypefnx {Function File} {@var{fld_names} =} javafields (@dots{})
Return the fields of a Java object or Java class in the form of a cell
array of strings.  If no output is requested, print the result
to the standard output.
@seealso{fieldnames, methods, javaObject}
@end deftypefn
javamethods
@c javamethods scripts/deprecated/javamethods.m
-*- texinfo -*-
@deftypefn  {Function File} {} javamethods (@var{javaobj})
@deftypefnx {Function File} {} javamethods ("@var{classname}")
@deftypefnx {Function File} {@var{mtd_names} =} javamethods (@dots{})
Return the methods of a Java object or Java class in the form of a cell
array of strings.  If no output is requested, print the result to the
standard output.
@seealso{methods, fieldnames, javaMethod, javaObject}
@end deftypefn
loadaudio
@c loadaudio scripts/deprecated/loadaudio.m
-*- texinfo -*-
@deftypefn {Function File} {} loadaudio (@var{name}, @var{ext}, @var{bps})

@code{loadaudio} is deprecated and will be removed in Octave version 4.4.
Please use @code{audioread} in all new code.

Load audio data from the file @file{@var{name}.@var{ext}} into the
vector @var{x}.

The extension @var{ext} determines how the data in the audio file is
interpreted; the extensions @file{lin} (default) and @file{raw}
correspond to linear, the extensions @file{au}, @file{mu}, or @file{snd}
to mu-law encoding.

The argument @var{bps} can be either 8 (default) or 16, and specifies
the number of bits per sample used in the audio file.
@seealso{lin2mu, mu2lin, saveaudio, playaudio, setaudio, record}
@end deftypefn
luinc
@c luinc scripts/deprecated/luinc.m
@deftypefn  {Built-in Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, '0')
@deftypefnx {Built-in Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, @var{droptol})
@deftypefnx {Built-in Function} {[@var{L}, @var{U}, @var{P}, @var{Q}] =} luinc (@var{A}, @var{opts})

@code{luinc} is deprecated and will be removed in Octave version 4.4.
Please use @code{ilu} or @code{ichol} in all new code.

Produce the incomplete LU@tie{}factorization of the sparse matrix @var{A}.
Two types of incomplete factorization are possible, and the type
is determined by the second argument to @code{luinc}.

Called with a second argument of @qcode{'0'}, the zero-level incomplete
LU@tie{}factorization is produced.  This creates a factorization of @var{A}
where the position of the nonzero arguments correspond to the same
positions as in the matrix @var{A}.

Alternatively, the fill-in of the incomplete LU@tie{}factorization can
be controlled through the variable @var{droptol} or the structure
@var{opts}.  The @sc{umfpack} multifrontal factorization code by Tim A.
Davis is used for the incomplete LU@tie{}factorization, (availability
@url{http://www.cise.ufl.edu/research/sparse/umfpack/})

@var{droptol} determines the values below which the values in the
LU@tie{} factorization are dropped and replaced by zero.  It must be a
positive scalar, and any values in the factorization whose absolute value
are less than this value are dropped, expect if leaving them increase the
sparsity of the matrix.  Setting @var{droptol} to zero results in a complete
LU@tie{}factorization which is the default.

@var{opts} is a structure containing one or more of the fields

@table @code
@item droptol
The drop tolerance as above.  If @var{opts} only contains @code{droptol}
then this is equivalent to using the variable @var{droptol}.

@item milu
A logical variable flagging whether to use the modified incomplete
LU@tie{} factorization.  In the case that @code{milu} is true, the dropped
values are subtracted from the diagonal of the matrix @var{U} of the
factorization.  The default is @code{false}.

@item udiag
A logical variable that flags whether zero elements on the diagonal of
@var{U} should be replaced with @var{droptol} to attempt to avoid singular
factors.  The default is @code{false}.

@item thresh
Defines the pivot threshold in the interval [0,1].  Values outside that
range are ignored.
@end table

All other fields in @var{opts} are ignored.  The outputs from @code{luinc}
are the same as for @code{lu}.

Given the string argument @qcode{\"vector\"}, @code{luinc} returns the
values of @var{p} @var{q} as vector values.
@seealso{ilu, ichol, lu, sparse}
@end deftypefn
mouse_wheel_zoom
@c mouse_wheel_zoom scripts/deprecated/mouse_wheel_zoom.m
-*- texinfo -*-
@deftypefn {Loadable Function} {@var{old_val} =} mouse_wheel_zoom (@var{new_val})
Query or set the mouse wheel zoom factor.

The zoom factor is a number in the range (0,1) which is the
percentage of the current axis limits that will be used when zooming.
For example, if the current x-axis limits are [0, 50] and
@code{mouse_wheel_zoom} is 0.4 (40%), then a zoom operation will
change the limits by 20.
@end deftypefn
nfields
@c nfields scripts/deprecated/nfields.m
-*- texinfo -*-
@deftypefn {Function File} {} nfields (@var{s})
Return the number of fields of the structure @var{s}.

@strong{Warning:} @code{nfields} is scheduled for removal in version 4.4.
Use @code{numfields} instead.
@seealso{numfields, fieldnames}
@end deftypefn
octave_tmp_file_name
@c octave_tmp_file_name scripts/deprecated/octave_tmp_file_name.m
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{fname} =} octave_tmp_file_name ()
@deftypefnx {Built-in Function} {@var{fname} =} octave_tmp_file_name (@var{dir})
@deftypefnx {Built-in Function} {@var{fname} =} octave_tmp_file_name (@var{dir}, @var{prefix})

@code{octave_tmp_file_name} is deprecated and will be removed in Octave
version 4.4.  Use @code{tempname} for equivalent functionality.

Return a unique temporary file name as a string.

If @var{prefix} is omitted, a value of @qcode{"oct-"} is used.
If @var{dir} is also omitted, the default directory for temporary files
(@code{P_tmpdir} is used.  If @var{dir} is provided, it must exist,
otherwise the default directory for temporary files is used.
@seealso{tempname, tmpnam, mkstemp, tempdir, P_tmpdir, tmpfile}
@end deftypefn
playaudio
@c playaudio scripts/deprecated/playaudio.m
-*- texinfo -*-
@deftypefn  {Function File} {} playaudio (@var{name}, @var{ext})
@deftypefnx {Function File} {} playaudio (@var{x})

@code{playaudio} is deprecated and will be removed in Octave version 4.4.
Please use @code{audioplayer} in all new code.

Play the audio file @file{@var{name}.@var{ext}} or the audio data
stored in the vector @var{x}.
@seealso{lin2mu, mu2lin, loadaudio, saveaudio, setaudio, record}
@end deftypefn
re_read_readline_init_file
@c re_read_readline_init_file scripts/deprecated/re_read_readline_init_file.m
-*- texinfo -*-
@deftypefn {Built-in Function} {} re_read_readline_init_file (@var{file})
This function has been deprecated.  Use
@code{@file{readline_re_read_init_file}} instead.
@seealso{readline_read_init_file}
@end deftypefn
read_readline_init_file
@c read_readline_init_file scripts/deprecated/read_readline_init_file.m
-*- texinfo -*-
@deftypefn {Built-in Function} {} read_readline_init_file (@var{file})
This function has been deprecated.  Use
@code{@file{readline_read_init_file}} instead.
@seealso{readline_read_init_file}
@end deftypefn
saveaudio
@c saveaudio scripts/deprecated/saveaudio.m
-*- texinfo -*-
@deftypefn {Function File} {} saveaudio (@var{name}, @var{x}, @var{ext}, @var{bps})

@code{saveaudio} is deprecated and will be removed in Octave version 4.4.
Please use @code{audiowrite} in all new code.

Save a vector @var{x} of audio data to the file
@file{@var{name}.@var{ext}}.  The optional parameters @var{ext} and
@var{bps} determine the encoding and the number of bits per sample used
in the audio file (see @code{loadaudio}); defaults are @file{lin} and
8, respectively.
@seealso{lin2mu, mu2lin, loadaudio, playaudio, setaudio, record}
@end deftypefn
saving_history
@c saving_history scripts/deprecated/saving_history.m
-*- texinfo -*-
@deftypefn  {Built-in Function} {@var{val} =} saving_history ()
@deftypefnx {Built-in Function} {@var{old_val} =} saving_history (@var{new_val})
@deftypefnx {Built-in Function} {} saving_history (@var{new_val}, "local")
This function has been deprecated.  Use @code{@file{history_save}} instead.
@seealso{history_save}
@end deftypefn
setaudio
@c setaudio scripts/deprecated/setaudio.m
-*- texinfo -*-
@deftypefn  {Function File} {} setaudio ()
@deftypefnx {Function File} {} setaudio (@var{w_type})
@deftypefnx {Function File} {} setaudio (@var{w_type}, @var{value})

@code{setaudio} is deprecated and will be removed in Octave version 4.4.
Please scale the audio signal in all new code or use the operating system's
native tools to adjust audio input and output levels.

Execute the shell command @samp{mixer}, possibly with optional
arguments @var{w_type} and @var{value}.
@end deftypefn
syl
@c syl scripts/deprecated/syl.m
-*- texinfo -*-
@deftypefn {Built-in Function} {@var{x} =} syl (@var{A}, @var{B}, @var{C})

@code{syl} is deprecated and will be removed in Octave version 4.4.
Use @code{sylvester} for the equivalent functionality.

Solve the Sylvester equation
@tex
$$
 A X + X B + C = 0
$$
@end tex
@ifnottex

@example
A X + X B + C = 0
@end example

@end ifnottex
using standard @sc{lapack} subroutines.  For example:

@example
@group
syl ([1, 2; 3, 4], [5, 6; 7, 8], [9, 10; 11, 12])
   @result{} [ -0.50000, -0.66667; -0.66667, -0.50000 ]
@end group
@end example
@end deftypefn
usage
@c usage scripts/deprecated/usage.m
-*- texinfo -*-
@deftypefn {Built-in Function} {} usage (@var{msg})

@code{usage} is deprecated and will be removed in Octave version 4.4.
Please use @code{print_usage} in all new code.

Print the message @var{msg}, prefixed by the string @samp{usage: }, and
set Octave's internal error state such that control will return to the
top level without evaluating any more commands.  This is useful for
aborting from functions.

After @code{usage} is evaluated, Octave will print a traceback of all
the function calls leading to the usage message.

You should use this function for reporting problems errors that result
from an improper call to a function, such as calling a function with an
incorrect number of arguments, or with arguments of the wrong type.  For
example, most functions distributed with Octave begin with code like
this

@example
@group
if (nargin != 2)
  usage (\"foo (a, b)\");
endif
@end group
@end example

@noindent
to check for the proper number of arguments.
@seealso{print_usage}
@end deftypefn
acosd
@c acosd scripts/elfun/acosd.m
-*- texinfo -*-
@deftypefn {Function File} {} acosd (@var{x})
Compute the inverse cosine in degrees for each element of @var{x}.
@seealso{cosd, acos}
@end deftypefn
acot
@c acot scripts/elfun/acot.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} acot (@var{x})
Compute the inverse cotangent in radians for each element of @var{x}.
@seealso{cot, acotd}
@end deftypefn
acotd
@c acotd scripts/elfun/acotd.m
-*- texinfo -*-
@deftypefn {Function File} {} acotd (@var{x})
Compute the inverse cotangent in degrees for each element of @var{x}.
@seealso{cotd, acot}
@end deftypefn
acoth
@c acoth scripts/elfun/acoth.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} acoth (@var{x})
Compute the inverse hyperbolic cotangent of each element of @var{x}.
@seealso{coth}
@end deftypefn
acsc
@c acsc scripts/elfun/acsc.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} acsc (@var{x})
Compute the inverse cosecant in radians for each element of @var{x}.
@seealso{csc, acscd}
@end deftypefn
acscd
@c acscd scripts/elfun/acscd.m
-*- texinfo -*-
@deftypefn {Function File} {} acscd (@var{x})
Compute the inverse cosecant in degrees for each element of @var{x}.
@seealso{cscd, acsc}
@end deftypefn
acsch
@c acsch scripts/elfun/acsch.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} acsch (@var{x})
Compute the inverse hyperbolic cosecant of each element of @var{x}.
@seealso{csch}
@end deftypefn
asec
@c asec scripts/elfun/asec.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} asec (@var{x})
Compute the inverse secant in radians for each element of @var{x}.
@seealso{sec, asecd}
@end deftypefn
asecd
@c asecd scripts/elfun/asecd.m
-*- texinfo -*-
@deftypefn {Function File} {} asecd (@var{x})
Compute the inverse secant in degrees for each element of @var{x}.
@seealso{secd, asec}
@end deftypefn
asech
@c asech scripts/elfun/asech.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} asech (@var{x})
Compute the inverse hyperbolic secant of each element of @var{x}.
@seealso{sech}
@end deftypefn
asind
@c asind scripts/elfun/asind.m
-*- texinfo -*-
@deftypefn {Function File} {} asind (@var{x})
Compute the inverse sine in degrees for each element of @var{x}.
@seealso{sind, asin}
@end deftypefn
atan2d
@c atan2d scripts/elfun/atan2d.m
-*- texinfo -*-
@deftypefn {Function File} {} atan2d (@var{y}, @var{x})
Compute atan2 (@var{y} / @var{x}) in degrees for corresponding elements
from @var{y} and @var{x}.
@seealso{tand, atan2}
@end deftypefn
atand
@c atand scripts/elfun/atand.m
-*- texinfo -*-
@deftypefn {Function File} {} atand (@var{x})
Compute the inverse tangent in degrees for each element of @var{x}.
@seealso{tand, atan}
@end deftypefn
cosd
@c cosd scripts/elfun/cosd.m
-*- texinfo -*-
@deftypefn {Function File} {} cosd (@var{x})
Compute the cosine for each element of @var{x} in degrees.

Returns zero for elements where @code{(@var{x}-90)/180} is an integer.
@seealso{acosd, cos}
@end deftypefn
cot
@c cot scripts/elfun/cot.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} cot (@var{x})
Compute the cotangent for each element of @var{x} in radians.
@seealso{acot, cotd, coth}
@end deftypefn
cotd
@c cotd scripts/elfun/cotd.m
-*- texinfo -*-
@deftypefn {Function File} {} cotd (@var{x})
Compute the cotangent for each element of @var{x} in degrees.
@seealso{acotd, cot}
@end deftypefn
coth
@c coth scripts/elfun/coth.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} coth (@var{x})
Compute the hyperbolic cotangent of each element of @var{x}.
@seealso{acoth}
@end deftypefn
csc
@c csc scripts/elfun/csc.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} csc (@var{x})
Compute the cosecant for each element of @var{x} in radians.
@seealso{acsc, cscd, csch}
@end deftypefn
cscd
@c cscd scripts/elfun/cscd.m
-*- texinfo -*-
@deftypefn {Function File} {} cscd (@var{x})
Compute the cosecant for each element of @var{x} in degrees.
@seealso{acscd, csc}
@end deftypefn
csch
@c csch scripts/elfun/csch.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} csch (@var{x})
Compute the hyperbolic cosecant of each element of @var{x}.
@seealso{acsch}
@end deftypefn
sec
@c sec scripts/elfun/sec.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} sec (@var{x})
Compute the secant for each element of @var{x} in radians.
@seealso{asec, secd, sech}
@end deftypefn
secd
@c secd scripts/elfun/secd.m
-*- texinfo -*-
@deftypefn {Function File} {} secd (@var{x})
Compute the secant for each element of @var{x} in degrees.
@seealso{asecd, sec}
@end deftypefn
sech
@c sech scripts/elfun/sech.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} sech (@var{x})
Compute the hyperbolic secant of each element of @var{x}.
@seealso{asech}
@end deftypefn
sind
@c sind scripts/elfun/sind.m
-*- texinfo -*-
@deftypefn {Function File} {} sind (@var{x})
Compute the sine for each element of @var{x} in degrees.

Returns zero for elements where @code{@var{x}/180} is an integer.
@seealso{asind, sin}
@end deftypefn
tand
@c tand scripts/elfun/tand.m
-*- texinfo -*-
@deftypefn {Function File} {} tand (@var{x})
Compute the tangent for each element of @var{x} in degrees.

Returns zero for elements where @code{@var{x}/180} is an integer and
@code{Inf} for elements where @code{(@var{x}-90)/180} is an integer.
@seealso{atand, tan}
@end deftypefn
accumarray
@c accumarray scripts/general/accumarray.m
-*- texinfo -*-
@deftypefn  {Function File} {} accumarray (@var{subs}, @var{vals}, @var{sz}, @var{func}, @var{fillval}, @var{issparse})
@deftypefnx {Function File} {} accumarray (@var{subs}, @var{vals}, @dots{})

Create an array by accumulating the elements of a vector into the
positions defined by their subscripts.

The subscripts are defined by the rows of the matrix @var{subs} and the
values by @var{vals}.  Each row of @var{subs} corresponds to one of the
values in @var{vals}.  If @var{vals} is a scalar, it will be used for each
of the row of @var{subs}.  If @var{subs} is a cell array of vectors, all
vectors must be of the same length, and the subscripts in the @var{k}th
vector must correspond to the @var{k}th dimension of the result.

The size of the matrix will be determined by the subscripts
themselves.  However, if @var{sz} is defined it determines the matrix
size.  The length of @var{sz} must correspond to the number of columns
in @var{subs}.  An exception is if @var{subs} has only one column, in
which case @var{sz} may be the dimensions of a vector and the
subscripts of @var{subs} are taken as the indices into it.

The default action of @code{accumarray} is to sum the elements with
the same subscripts.  This behavior can be modified by defining the
@var{func} function.  This should be a function or function handle
that accepts a column vector and returns a scalar.  The result of the
function should not depend on the order of the subscripts.

The elements of the returned array that have no subscripts associated
with them are set to zero.  Defining @var{fillval} to some other value
allows these values to be defined.  This behavior changes, however,
for certain values of @var{func}.  If @var{func} is @code{min}
(respectively, @code{max}) then the result will be filled with the
minimum (respectively, maximum) integer if @var{vals} is of integral
type, logical false (respectively, logical true) if @var{vals} is of
logical type, zero if @var{fillval} is zero and all values are
non-positive (respectively, non-negative), and NaN otherwise.

By default @code{accumarray} returns a full matrix.  If
@var{issparse} is logically true, then a sparse matrix is returned
instead.

The following @code{accumarray} example constructs a frequency table
that in the first column counts how many occurrences each number in
the second column has, taken from the vector @var{x}.  Note the usage
of @code{unique}  for assigning to all repeated elements of @var{x}
the same index (@pxref{XREFunique,,unique}).

@example
@group
@var{x} = [91, 92, 90, 92, 90, 89, 91, 89, 90, 100, 100, 100];
[@var{u}, ~, @var{j}] = unique (@var{x});
[accumarray(@var{j}', 1), @var{u}']
  @result{}  2    89
      3    90
      2    91
      2    92
      3   100
@end group
@end example

Another example, where the result is a multi-dimensional 3-D array and
the default value (zero) appears in the output:

@example
@group
accumarray ([1, 1, 1;
             2, 1, 2;
             2, 3, 2;
             2, 1, 2;
             2, 3, 2], 101:105)
@result{} ans(:,:,1) = [101, 0, 0; 0, 0, 0]
@result{} ans(:,:,2) = [0, 0, 0; 206, 0, 208]
@end group
@end example

The sparse option can be used as an alternative to the @code{sparse}
constructor (@pxref{XREFsparse,,sparse}).  Thus

@example
sparse (@var{i}, @var{j}, @var{sv})
@end example

@noindent
can be written with @code{accumarray} as

@example
accumarray ([@var{i}, @var{j}], @var{sv}', [], [], 0, true)
@end example

@noindent
For repeated indices, @code{sparse} adds the corresponding value.  To
take the minimum instead, use @code{min} as an accumulator function:

@example
accumarray ([@var{i}, @var{j}], @var{sv}', [], @@min, 0, true)
@end example

The complexity of accumarray in general for the non-sparse case is
generally O(M+N), where N is the number of subscripts and M is the
maximum subscript (linearized in multi-dimensional case).  If
@var{func} is one of @code{@@sum} (default), @code{@@max},
@code{@@min} or @code{@@(x) @{x@}}, an optimized code path is used.
Note that for general reduction function the interpreter overhead can
play a major part and it may be more efficient to do multiple
accumarray calls and compute the results in a vectorized manner.

@seealso{accumdim, unique, sparse}
@end deftypefn
accumdim
@c accumdim scripts/general/accumdim.m
-*- texinfo -*-
@deftypefn {Function File} {} accumdim (@var{subs}, @var{vals}, @var{dim}, @var{n}, @var{func}, @var{fillval})
Create an array by accumulating the slices of an array into the
positions defined by their subscripts along a specified dimension.

The subscripts are defined by the index vector @var{subs}.
The dimension is specified by @var{dim}.  If not given, it defaults
to the first non-singleton dimension.  The length of @var{subs} must
be equal to @code{size (@var{vals}, @var{dim})}.

The extent of the result matrix in the working dimension will be
determined by the subscripts themselves.  However, if @var{n} is
defined it determines this extent.

The default action of @code{accumdim} is to sum the subarrays with the
same subscripts.  This behavior can be modified by defining the
@var{func} function.  This should be a function or function handle
that accepts an array and a dimension, and reduces the array along
this dimension.  As a special exception, the built-in @code{min} and
@code{max} functions can be used directly, and @code{accumdim}
accounts for the middle empty argument that is used in their calling.

The slices of the returned array that have no subscripts associated
with them are set to zero.  Defining @var{fillval} to some other
value allows these values to be defined.

An example of the use of @code{accumdim} is:

@example
@group
accumdim ([1, 2, 1, 2, 1], [ 7, -10,   4;
                            -5, -12,   8;
                           -12,   2,   8;
                           -10,   9,  -3;
                            -5,  -3, -13])
@result{} [-10,-11,-1;-15,-3,5]
@end group
@end example

@seealso{accumarray}
@end deftypefn
bincoeff
@c bincoeff scripts/general/bincoeff.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} bincoeff (@var{n}, @var{k})
Return the binomial coefficient of @var{n} and @var{k}, defined as
@tex
$$
 {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
$$
@end tex
@ifnottex

@example
@group
 /   \
 | n |    n (n-1) (n-2) @dots{} (n-k+1)
 |   |  = -------------------------
 | k |               k!
 \   /
@end group
@end example

@end ifnottex
For example:

@example
@group
bincoeff (5, 2)
   @result{} 10
@end group
@end example

In most cases, the @code{nchoosek} function is faster for small
scalar integer arguments.  It also warns about loss of precision for
big arguments.

@seealso{nchoosek}
@end deftypefn
bitcmp
@c bitcmp scripts/general/bitcmp.m
-*- texinfo -*-
@deftypefn {Function File} {} bitcmp (@var{A}, @var{k})
Return the @var{k}-bit complement of integers in @var{A}.

If @var{k} is omitted @code{k = log2 (bitmax) + 1} is assumed.

@example
@group
bitcmp (7,4)
  @result{} 8
dec2bin (11)
  @result{} 1011
dec2bin (bitcmp (11, 6))
  @result{} 110100
@end group
@end example

@seealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax}
@end deftypefn
bitget
@c bitget scripts/general/bitget.m
-*- texinfo -*-
@deftypefn {Function File} {@var{c} =} bitget (@var{A}, @var{n})
Return the status of bit(s) @var{n} of the unsigned integers in @var{A}.

The least significant bit is @var{n} = 1.

@example
@group
bitget (100, 8:-1:1)
@result{} 0  1  1  0  0  1  0  0
@end group
@end example
@seealso{bitand, bitor, bitxor, bitset, bitcmp, bitshift, bitmax}
@end deftypefn
bitset
@c bitset scripts/general/bitset.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{C} =} bitset (@var{A}, @var{n})
@deftypefnx {Function File} {@var{C} =} bitset (@var{A}, @var{n}, @var{val})
Set or reset bit(s) @var{n} of the unsigned integers in @var{A}.

@var{val} = 0 resets and @var{val} = 1 sets the bits.
The least significant bit is @var{n} = 1.  All variables must be the same
size or scalars.

@example
@group
dec2bin (bitset (10, 1))
  @result{} 1011
@end group
@end example
@seealso{bitand, bitor, bitxor, bitget, bitcmp, bitshift, bitmax}
@end deftypefn
blkdiag
@c blkdiag scripts/general/blkdiag.m
-*- texinfo -*-
@deftypefn {Function File} {} blkdiag (@var{A}, @var{B}, @var{C}, @dots{})
Build a block diagonal matrix from @var{A}, @var{B}, @var{C}, @dots{}

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.
@seealso{diag, horzcat, vertcat, sparse}
@end deftypefn
cart2pol
@c cart2pol scripts/general/cart2pol.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{theta}, @var{r}] =} cart2pol (@var{x}, @var{y})
@deftypefnx {Function File} {[@var{theta}, @var{r}, @var{z}] =} cart2pol (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {[@var{theta}, @var{r}] =} cart2pol (@var{C})
@deftypefnx {Function File} {[@var{theta}, @var{r}, @var{z}] =} cart2pol (@var{C})
@deftypefnx {Function File} {@var{P} =} cart2pol (@dots{})

Transform Cartesian coordinates to polar or cylindrical coordinates.

The inputs @var{x}, @var{y} (, and @var{z}) must be the same shape, or
scalar.  If called with a single matrix argument then each row of @var{C}
represents the Cartesian coordinate (@var{x}, @var{y} (, @var{z})).

@var{theta} describes the angle relative to the positive x-axis.

@var{r} is the distance to the z-axis @w{(0, 0, z)}.

If only a single return argument is requested then return a matrix @var{P}
where each row represents one polar/(cylindrical) coordinate
(@var{theta}, @var{phi} (, @var{z})).
@seealso{pol2cart, cart2sph, sph2cart}
@end deftypefn
cart2sph
@c cart2sph scripts/general/cart2sph.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{theta}, @var{phi}, @var{r}] =} cart2sph (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {[@var{theta}, @var{phi}, @var{r}] =} cart2sph (@var{C})
@deftypefnx {Function File} {@var{S} =} cart2sph (@dots{})
Transform Cartesian coordinates to spherical coordinates.

The inputs @var{x}, @var{y}, and @var{z} must be the same shape, or scalar.
If called with a single matrix argument then each row of @var{C} represents
the Cartesian coordinate (@var{x}, @var{y}, @var{z}).

@var{theta} describes the angle relative to the positive x-axis.

@var{phi} is the angle relative to the xy-plane.

@var{r} is the distance to the origin @w{(0, 0, 0)}.

If only a single return argument is requested then return a matrix @var{S}
where each row represents one spherical coordinate
(@var{theta}, @var{phi}, @var{r}).
@seealso{sph2cart, cart2pol, pol2cart}
@end deftypefn
cell2mat
@c cell2mat scripts/general/cell2mat.m
-*- texinfo -*-
@deftypefn {Function File} {@var{m} =} cell2mat (@var{c})
Convert the cell array @var{c} into a matrix by concatenating all
elements of @var{c} into a hyperrectangle.

Elements of @var{c} must be numeric, logical, or char matrices; or cell
arrays; or structs; and @code{cat} must be able to concatenate them together.
@seealso{mat2cell, num2cell}
@end deftypefn
celldisp
@c celldisp scripts/general/celldisp.m
-*- texinfo -*-
@deftypefn  {Function File} {} celldisp (@var{c})
@deftypefnx {Function File} {} celldisp (@var{c}, @var{name})
Recursively display the contents of a cell array.

By default the values are displayed with the name of the variable @var{c}.
However, this name can be replaced with the variable @var{name}.  For
example:

@example
@group
c = @{1, 2, @{31, 32@}@};
celldisp (c, "b")
   @result{}
      b@{1@} =
       1
      b@{2@} =
       2
      b@{3@}@{1@} =
       31
      b@{3@}@{2@} =
       32
@end group
@end example

@seealso{disp}
@end deftypefn
chop
@c chop scripts/general/chop.m
-*- texinfo -*-
@deftypefn {Function File} {} chop (@var{x}, @var{ndigits}, @var{base})
Truncate elements of @var{x} to a length of @var{ndigits} such that the
resulting numbers are exactly divisible by @var{base}.

If @var{base} is not specified it defaults to 10.

@example
@group
chop (-pi, 5, 10)
   @result{} -3.14200000000000
chop (-pi, 5, 5)
   @result{} -3.14150000000000
@end group
@end example
@end deftypefn
circshift
@c circshift scripts/general/circshift.m
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} circshift (@var{x}, @var{n})
Circularly shift the values of the array @var{x}.

@var{n} must be a vector of integers no longer than the number of
dimensions in @var{x}.  The values of @var{n} can be either positive or
negative, which determines the direction in which the values or @var{x}
are shifted.  If an element of @var{n} is zero, then the corresponding
dimension of @var{x} will not be shifted.  For example:

@example
@group
x = [1, 2, 3; 4, 5, 6; 7, 8, 9];
circshift (x, 1)
@result{}  7, 8, 9
    1, 2, 3
    4, 5, 6
circshift (x, -2)
@result{}  7, 8, 9
    1, 2, 3
    4, 5, 6
circshift (x, [0,1])
@result{}  3, 1, 2
    6, 4, 5
    9, 7, 8
@end group
@end example
@seealso{permute, ipermute, shiftdim}
@end deftypefn
common_size
@c common_size scripts/general/common_size.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{err}, @var{y1}, @dots{}] =} common_size (@var{x1}, @dots{})
Determine if all input arguments are either scalar or of common size.

If true, @var{err} is zero, and @var{yi} is a matrix of the common size
with all entries equal to @var{xi} if this is a scalar or @var{xi}
otherwise.  If the inputs cannot be brought to a common size, @var{err} is
1, and @var{yi} is @var{xi}.  For example:

@example
@group
[errorcode, a, b] = common_size ([1 2; 3 4], 5)
     @result{} errorcode = 0
     @result{} a = [ 1, 2; 3, 4 ]
     @result{} b = [ 5, 5; 5, 5 ]
@end group
@end example

@noindent
This is useful for implementing functions where arguments can either be
scalars or of common size.
@end deftypefn
cplxpair
@c cplxpair scripts/general/cplxpair.m
-*- texinfo -*-
@deftypefn  {Function File} {} cplxpair (@var{z})
@deftypefnx {Function File} {} cplxpair (@var{z}, @var{tol})
@deftypefnx {Function File} {} cplxpair (@var{z}, @var{tol}, @var{dim})
Sort the numbers @var{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
@code{abs (imag (@var{z}) / @var{z}) < @var{tol}}) are placed after the
complex pairs.

If @var{tol} is unspecified the default value is 100*@code{eps}.

By default the complex pairs are sorted along the first non-singleton
dimension of @var{z}.  If @var{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 @var{tol}).
Note that there is no defined order for pairs with identical real parts but
differing imaginary parts.
@c Set example in small font to prevent overfull line

@smallexample
cplxpair (exp(2i*pi*[0:4]'/5)) == exp(2i*pi*[3; 2; 4; 1; 0]/5)
@end smallexample
@end deftypefn
cumtrapz
@c cumtrapz scripts/general/cumtrapz.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{q} =} cumtrapz (@var{y})
@deftypefnx {Function File} {@var{q} =} cumtrapz (@var{x}, @var{y})
@deftypefnx {Function File} {@var{q} =} cumtrapz (@dots{}, @var{dim})
Cumulative numerical integration of points @var{y} using the trapezoidal
method.

@w{@code{cumtrapz (@var{y})}} computes the cumulative integral of @var{y}
along the first non-singleton dimension.  Where @code{trapz} reports only
the overall integral sum, @code{cumtrapz} reports the current partial sum
value at each point of @var{y}.

When the argument @var{x} is omitted an equally spaced @var{x} vector with
unit spacing (1) is assumed.  @code{cumtrapz (@var{x}, @var{y})} evaluates
the integral with respect to the spacing in @var{x} and the values in
@var{y}.  This is useful if the points in @var{y} have been sampled unevenly.

If the optional @var{dim} argument is given, operate along this dimension.

Application Note: If @var{x} is not specified then unit spacing will be
used.  To scale the integral to the correct value you must multiply by the
actual spacing value (deltaX).
@seealso{trapz, cumsum}
@end deftypefn
curl
@c curl scripts/general/curl.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{cx}, @var{cy}, @var{cz}, @var{v}] =} curl (@var{x}, @var{y}, @var{z}, @var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {[@var{cz}, @var{v}] =} curl (@var{x}, @var{y}, @var{fx}, @var{fy})
@deftypefnx {Function File} {[@dots{}] =} curl (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {[@dots{}] =} curl (@var{fx}, @var{fy})
@deftypefnx {Function File} {@var{v} =} curl (@dots{})
Calculate curl of vector field given by the arrays @var{fx}, @var{fy}, and
@var{fz} or @var{fx}, @var{fy} respectively.
@tex
$$ curl F(x,y,z) = \left( {\partial{d} \over \partial{y}} F_z - {\partial{d} \over \partial{z}} F_y, {\partial{d} \over \partial{z}} F_x - {\partial{d} \over \partial{x}} F_z, {\partial{d} \over \partial{x}} F_y - {\partial{d} \over \partial{y}} F_x \right)$$
@end tex
@ifnottex

@example
@group
                  / d         d       d         d       d         d     \
curl F(x,y,z)  =  | -- Fz  -  -- Fy,  -- Fx  -  -- Fz,  -- Fy  -  -- Fx |
                  \ dy        dz      dz        dx      dx        dy    /
@end group
@end example

@end ifnottex
The coordinates of the vector field can be given by the arguments @var{x},
@var{y}, @var{z} or @var{x}, @var{y} respectively.  @var{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.
@seealso{divergence, gradient, del2, cross}
@end deftypefn
dblquad
@c dblquad scripts/general/dblquad.m
-*- texinfo -*-
@deftypefn  {Function File} {} dblquad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb})
@deftypefnx {Function File} {} dblquad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{tol})
@deftypefnx {Function File} {} dblquad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{tol}, @var{quadf})
@deftypefnx {Function File} {} dblquad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{tol}, @var{quadf}, @dots{})
Numerically evaluate the double integral of @var{f}.

@var{f} is a function handle, inline function, or string containing the name
of the function to evaluate.  The function @var{f} must have the form
@math{z = f(x,y)} where @var{x} is a vector and @var{y} is a scalar.  It
should return a vector of the same length and orientation as @var{x}.

@var{xa}, @var{ya} and @var{xb}, @var{yb} are the lower and upper limits of
integration for x and y respectively.  The underlying integrator determines
whether infinite bounds are accepted.

The optional argument @var{tol} defines the absolute tolerance used to
integrate each sub-integral.  The default value is @math{1e^{-6}}.

The optional argument @var{quadf} specifies which underlying integrator
function to use.  Any choice but @code{quad} is available and the default
is @code{quadcc}.

Additional arguments, are passed directly to @var{f}.  To use the default
value for @var{tol} or @var{quadf} one may pass @qcode{':'} or an empty
matrix ([]).
@seealso{triplequad, quad, quadv, quadl, quadgk, quadcc, trapz}
@end deftypefn
deal
@c deal scripts/general/deal.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{r1}, @var{r2}, @dots{}, @var{rn}] =} deal (@var{a})
@deftypefnx {Function File} {[@var{r1}, @var{r2}, @dots{}, @var{rn}] =} deal (@var{a1}, @var{a2}, @dots{}, @var{an})

Copy the input parameters into the corresponding output parameters.

If only a single input parameter is supplied, its value is copied to each
of the outputs.

For example,

@example
[a, b, c] = deal (x, y, z);
@end example

@noindent
is equivalent to

@example
@group
a = x;
b = y;
c = z;
@end group
@end example

@noindent
and

@example
[a, b, c] = deal (x);
@end example

@noindent
is equivalent to

@example
a = b = c = x;
@end example

Programming Note: @code{deal} is often used with comma separated lists
derived from cell arrays or structures.  This is unnecessary as the
interpreter can perform the same action without the overhead of a function
call.  For example:

@example
@group
c = @{[1 2], "Three", 4@};
[x, y, z ] = c@{:@}
@result{}
   x =

      1   2

   y = Three
   z =  4
@end group
@end example
@seealso{cell2struct, struct2cell, repmat}
@end deftypefn
del2
@c del2 scripts/general/del2.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{d} =} del2 (@var{M})
@deftypefnx {Function File} {@var{d} =} del2 (@var{M}, @var{h})
@deftypefnx {Function File} {@var{d} =} del2 (@var{M}, @var{dx}, @var{dy}, @dots{})

Calculate the discrete Laplace
@tex
operator $( \nabla^2 )$.
@end tex
@ifnottex
operator.
@end ifnottex

For a 2-dimensional matrix @var{M} this is defined as
@tex
$$d = {1 \over 4} \left( {d^2 \over dx^2} M(x,y) + {d^2 \over dy^2} M(x,y) \right)$$
@end tex
@ifnottex

@example
@group
      1    / d^2            d^2         \
D  = --- * | ---  M(x,y) +  ---  M(x,y) |
      4    \ dx^2           dy^2        /
@end group
@end example

@end ifnottex
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 @var{h}, which is a
scalar defining the equidistant spacing in all dimensions.  Alternatively,
the spacing in each dimension may be defined separately by @var{dx},
@var{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
@var{M}.  The default spacing value is 1.

At least 3 data points are needed for each dimension.  Boundary points are
calculated from the linear extrapolation of interior points.

@seealso{gradient, diff}
@end deftypefn
display
@c display scripts/general/display.m
-*- texinfo -*-
@deftypefn {Function File} {} display (@var{a})
Display the contents of an object.

If @var{a} is an object of the class @qcode{"myclass"}, then @code{display}
is called in a case like

@example
myclass (@dots{})
@end example

@noindent
where Octave is required to display the contents of a variable of the
type @qcode{"myclass"}.

@seealso{class, subsref, subsasgn}
@end deftypefn
divergence
@c divergence scripts/general/divergence.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{div} =} divergence (@var{x}, @var{y}, @var{z}, @var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {@var{div} =} divergence (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {@var{div} =} divergence (@var{x}, @var{y}, @var{fx}, @var{fy})
@deftypefnx {Function File} {@var{div} =} divergence (@var{fx}, @var{fy})
Calculate divergence of a vector field given by the arrays @var{fx},
@var{fy}, and @var{fz} or @var{fx}, @var{fy} respectively.

@tex
$$
div F(x,y,z) = \partial_x{F} + \partial_y{F} + \partial_z{F}
$$
@end tex
@ifnottex

@example
@group
                  d               d               d
div F(x,y,z)  =   -- F(x,y,z)  +  -- F(x,y,z)  +  -- F(x,y,z)
                  dx              dy              dz
@end group
@end example

@end ifnottex
The coordinates of the vector field can be given by the arguments @var{x},
@var{y}, @var{z} or @var{x}, @var{y} respectively.

@seealso{curl, gradient, del2, dot}
@end deftypefn
fieldnames
@c fieldnames scripts/general/fieldnames.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{names} =} fieldnames (@var{struct})
@deftypefnx {Function File} {@var{names} =} fieldnames (@var{obj})
@deftypefnx {Function File} {@var{names} =} fieldnames (@var{javaobj})
@deftypefnx {Function File} {@var{names} =} fieldnames ("@var{jclassname}")
Return a cell array of strings with the names of the fields in the
specified input.

When the input is a structure @var{struct}, the names are the elements of
the structure.

When the input is an Octave object @var{obj}, the names are the public
properties of the object.

When the input is a Java object @var{javaobj} or Java classname
@var{jclassname} the name are the public data elements of the object or
class.
@seealso{numfields, isfield, orderfields, struct, methods}
@end deftypefn
flip
@c flip scripts/general/flip.m
-*- texinfo -*-
@deftypefn  {Function File} {} flip (@var{x})
@deftypefnx {Function File} {} flip (@var{x}, @var{dim})
Flip array across dimension @var{dim}.

Return a copy of @var{x} flipped about the dimension @var{dim}.
@var{dim} defaults to the first non-singleton dimension.
For example:

@example
@group
flip ([1  2  3  4])
      @result{}  4  3  2  1

flip ([1; 2; 3; 4])
      @result{}  4
          3
          2
          1

flip ([1 2; 3 4])
      @result{}  3  4
          1  2

flip ([1 2; 3 4], 2)
      @result{}  2  1
          4  3
@end group
@end example

@seealso{fliplr, flipud, rot90, rotdim, permute, transpose}
@end deftypefn
flipdim
@c flipdim scripts/general/flipdim.m
-*- texinfo -*-
@deftypefn  {Function File} {} flipdim (@var{x})
@deftypefnx {Function File} {} flipdim (@var{x}, @var{dim})
Flip array across dimension @var{dim}.

This function is an alias for @code{flip} and exists for backwards and
@sc{matlab} compatibility.  See @code{flip} for complete usage information.

@seealso{flip, fliplr, flipud, rot90, rotdim}
@end deftypefn
fliplr
@c fliplr scripts/general/fliplr.m
-*- texinfo -*-
@deftypefn {Function File} {} fliplr (@var{x})
Flip array left to right.

Return a copy of @var{x} with the order of the columns reversed.  In other
words, @var{x} is flipped left-to-right about a vertical axis.  For example:

@example
@group
fliplr ([1, 2; 3, 4])
     @result{}  2  1
         4  3
@end group
@end example

@seealso{flipud, flip, rot90, rotdim}
@end deftypefn
flipud
@c flipud scripts/general/flipud.m
-*- texinfo -*-
@deftypefn {Function File} {} flipud (@var{x})
Flip array upside down.

Return a copy of @var{x} with the order of the rows reversed.  In other
words, @var{x} is flipped upside-down about a horizontal axis.  For example:

@example
@group
flipud ([1, 2; 3, 4])
     @result{}  3  4
         1  2
@end group
@end example

@seealso{fliplr, flip, rot90, rotdim}
@end deftypefn
gradient
@c gradient scripts/general/gradient.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{dx} =} gradient (@var{m})
@deftypefnx {Function File} {[@var{dx}, @var{dy}, @var{dz}, @dots{}] =} gradient (@var{m})
@deftypefnx {Function File} {[@dots{}] =} gradient (@var{m}, @var{s})
@deftypefnx {Function File} {[@dots{}] =} gradient (@var{m}, @var{x}, @var{y}, @var{z}, @dots{})
@deftypefnx {Function File} {[@dots{}] =} gradient (@var{f}, @var{x0})
@deftypefnx {Function File} {[@dots{}] =} gradient (@var{f}, @var{x0}, @var{s})
@deftypefnx {Function File} {[@dots{}] =} gradient (@var{f}, @var{x0}, @var{x}, @var{y}, @dots{})

Calculate the gradient of sampled data or a function.

If @var{m} is a vector, calculate the one-dimensional gradient of @var{m}.
If @var{m} is a matrix the gradient is calculated for each dimension.

@code{[@var{dx}, @var{dy}] = gradient (@var{m})} calculates the
one-dimensional gradient for @var{x} and @var{y} direction if @var{m} is a
matrix.  Additional return arguments can be use for multi-dimensional
matrices.

A constant spacing between two points can be provided by the @var{s}
parameter.  If @var{s} is a scalar, it is assumed to be the spacing for all
dimensions.  Otherwise, separate values of the spacing can be supplied by
the @var{x}, @dots{} arguments.  Scalar values specify an equidistant
spacing.  Vector values for the @var{x}, @dots{} arguments specify the
coordinate for that dimension.  The length must match their respective
dimension of @var{m}.

At boundary points a linear extrapolation is applied.  Interior points
are calculated with the first approximation of the numerical gradient

@example
y'(i) = 1/(x(i+1)-x(i-1)) * (y(i-1)-y(i+1)).
@end example

If the first argument @var{f} is a function handle, the gradient of the
function at the points in @var{x0} is approximated using central difference.
For example, @code{gradient (@@cos, 0)} approximates the gradient of the
cosine function in the point @math{x0 = 0}.  As with sampled data, the
spacing values between the points from which the gradient is estimated can
be set via the @var{s} or @var{dx}, @var{dy}, @dots{} arguments.  By default
a spacing of 1 is used.
@seealso{diff, del2}
@end deftypefn
idivide
@c idivide scripts/general/idivide.m
-*- texinfo -*-
@deftypefn {Function File} {} idivide (@var{x}, @var{y}, @var{op})
Integer division with different rounding rules.

The standard behavior of integer division such as @code{@var{a} ./ @var{b}}
is to round the result to the nearest integer.  This is not always the
desired behavior and @code{idivide} permits integer element-by-element
division to be performed with different treatment for the fractional
part of the division as determined by the @var{op} flag.  @var{op} is
a string with one of the values:

@table @asis
@item @qcode{"fix"}
Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
towards zero.

@item @qcode{"round"}
Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
towards the nearest integer.

@item @qcode{"floor"}
Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
towards negative infinity.

@item @qcode{"ceil"}
Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
towards positive infinity.
@end table

@noindent
If @var{op} is not given it defaults to @qcode{"fix"}.
An example demonstrating these rounding rules is

@example
@group
idivide (int8 ([-3, 3]), int8 (4), "fix")
  @result{} int8 ([0, 0])
idivide (int8 ([-3, 3]), int8 (4), "round")
  @result{} int8 ([-1, 1])
idivide (int8 ([-3, 3]), int8 (4), "floor")
  @result{} int8 ([-1, 0])
idivide (int8 ([-3, 3]), int8 (4), "ceil")
  @result{} int8 ([0, 1])
@end group
@end example

@seealso{ldivide, rdivide}
@end deftypefn
inputParser
@c inputParser scripts/general/inputParser.m
-*- texinfo -*-
@deftypefn {Function File} {@var{p} =} inputParser ()
Create object @var{p} of the inputParser class.

This class is designed to allow easy parsing of function arguments.  The
class supports four types of arguments:

@enumerate
@item mandatory (see @command{addRequired});

@item optional (see @command{addOptional});

@item named (see @command{addParamValue});

@item switch (see @command{addSwitch}).
@end enumerate

After defining the function API with these methods, the supplied arguments
can be parsed with the @command{parse} method and the parsing results
accessed with the @command{Results} accessor.

@end deftypefn
@deftypefn {Accessor method} {} inputParser.Parameters
Return list of parameter names already defined.

@end deftypefn
@deftypefn {Accessor method} {} inputParser.Results
Return structure with argument names as fieldnames and corresponding values.

@end deftypefn
@deftypefn {Accessor method} {} inputParser.Unmatched
Return structure similar to @command{Results}, but for unmatched parameters.
See the @command{KeepUnmatched} property.

@end deftypefn
@deftypefn {Accessor method} {} inputParser.UsingDefaults
Return cell array with the names of arguments that are using default values.

@end deftypefn
@deftypefn {Class property} {} inputParser.CaseSensitive = @var{boolean}
Set whether matching of argument names should be case sensitive.  Defaults
to false.

@end deftypefn
@deftypefn {Class property} {} inputParser.FunctionName = @var{name}
Set function name to be used in error messages; Defaults to empty string.

@end deftypefn
@deftypefn {Class property} {} inputParser.KeepUnmatched = @var{boolean}
Set whether an error should be given for non-defined arguments.  Defaults to
false.  If set to true, the extra arguments can be accessed through
@code{Unmatched} after the @code{parse} method.  Note that since
@command{Switch} and @command{ParamValue} arguments can be mixed, it is
not possible to know the unmatched type.  If argument is found unmatched
it is assumed to be of the @command{ParamValue} type and it is expected to
be followed by a value.

@end deftypefn
@deftypefn {Class property} {} inputParser.StructExpand = @var{boolean}
Set whether a structure can be passed to the function instead of
parameter/value pairs.  Defaults to true.  Not implemented yet.

The following example shows how to use this class:

@example
@group
function check (varargin)
@c The next two comments need to be indented by one for alignment
  p = inputParser ();                      # create object
  p.FunctionName = "check";                # set function name
  p.addRequired ("pack", @@ischar);         # mandatory argument
  p.addOptional ("path", pwd(), @@ischar);  # optional argument

  ## create a function handle to anonymous functions for validators
  val_mat = @@(x) isvector (x) && all (x <= 1) && all (x >= 0);
  p.addOptional ("mat", [0 0], val_mat);

  ## create two arguments of type "ParamValue"
  val_type = @@(x) any (strcmp (x, @{"linear", "quadratic"@}));
  p.addParamValue ("type", "linear", val_type);
  val_verb = @@(x) any (strcmp (x, @{"low", "medium", "high"@}));
  p.addParamValue ("tolerance", "low", val_verb);

  ## create a switch type of argument
  p.addSwitch ("verbose");

  p.parse (varargin@{:@});  # Run created parser on inputs

  ## the rest of the function can access inputs by using p.Results.
  ## for example, get the tolerance input with p.Results.tolerance
endfunction
@end group

check ("mech");           # valid, use defaults for other arguments
check ();                 # error, one argument is mandatory
check (1);                # error, since ! ischar
check ("mech", "~/dev");  # valid, use defaults for other arguments

check ("mech", "~/dev", [0 1 0 0], "type", "linear");  # valid

## following is also valid.  Note how the Switch argument type can
## be mixed into or before the ParamValue argument type (but it
## must still appear after any Optional argument).
check ("mech", "~/dev", [0 1 0 0], "verbose", "tolerance", "high");

## following returns an error since not all optional arguments,
## `path' and `mat', were given before the named argument `type'.
check ("mech", "~/dev", "type", "linear");
@end example

@emph{Note 1}: A function can have any mixture of the four API types but
they must appear in a specific order.  @command{Required} arguments must be
first and can be followed by any @command{Optional} arguments.  Only
the @command{ParamValue} and @command{Switch} arguments may be mixed
together and they must appear at the end.

@emph{Note 2}: If both @command{Optional} and @command{ParamValue} arguments
are mixed in a function API then once a string Optional argument fails to
validate it will be considered the end of the @command{Optional}
arguments.  The remaining arguments will be compared against any
@command{ParamValue} or @command{Switch} arguments.

@seealso{nargin, validateattributes, validatestring, varargin}
@end deftypefn
int2str
@c int2str scripts/general/int2str.m
-*- texinfo -*-
@deftypefn {Function File} {} int2str (@var{n})
Convert an integer (or array of integers) to a string (or a character
array).

@example
@group
int2str (123)
     @result{} "123"

s = int2str ([1, 2, 3; 4, 5, 6])
     @result{} s =
        1  2  3
        4  5  6

whos s
     @result{}
      Attr Name        Size                     Bytes  Class
      ==== ====        ====                     =====  =====
           s           2x7                         14  char
@end group
@end example

This function is not very flexible.  For better control over the
results, use @code{sprintf} (@pxref{Formatted Output}).
@seealso{sprintf, num2str, mat2str}
@end deftypefn
interp1
@c interp1 scripts/general/interp1.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{yi} =} interp1 (@var{x}, @var{y}, @var{xi})
@deftypefnx {Function File} {@var{yi} =} interp1 (@var{y}, @var{xi})
@deftypefnx {Function File} {@var{yi} =} interp1 (@dots{}, @var{method})
@deftypefnx {Function File} {@var{yi} =} interp1 (@dots{}, @var{extrap})
@deftypefnx {Function File} {@var{yi} =} interp1 (@dots{}, "left")
@deftypefnx {Function File} {@var{yi} =} interp1 (@dots{}, "right")
@deftypefnx {Function File} {@var{pp} =} interp1 (@dots{}, "pp")

One-dimensional interpolation.

Interpolate input data to determine the value of @var{yi} at the points
@var{xi}.  If not specified, @var{x} is taken to be the indices of @var{y}
(@code{1:length (@var{y})}).  If @var{y} is a matrix or an N-dimensional
array, the interpolation is performed on each column of @var{y}.

The interpolation @var{method} is one of:

@table @asis
@item @qcode{"nearest"}
Return the nearest neighbor.

@item @qcode{"previous"}
Return the previous neighbor.

@item @qcode{"next"}
Return the next neighbor.

@item @qcode{"linear"} (default)
Linear interpolation from nearest neighbors.

@item @qcode{"pchip"}
Piecewise cubic Hermite interpolating polynomial---shape-preserving
interpolation with smooth first derivative.

@item @qcode{"cubic"}
Cubic interpolation (same as @qcode{"pchip"}).

@item @qcode{"spline"}
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

Adding '*' to the start of any method above forces @code{interp1}
to assume that @var{x} is uniformly spaced, and only @code{@var{x}(1)}
and @code{@var{x}(2)} are referenced.  This is usually faster,
and is never slower.  The default method is @qcode{"linear"}.

If @var{extrap} is the string @qcode{"extrap"}, then extrapolate values
beyond the endpoints using the current @var{method}.  If @var{extrap} is a
number, then replace values beyond the endpoints with that number.  When
unspecified, @var{extrap} defaults to @code{NA}.

If the string argument @qcode{"pp"} is specified, then @var{xi} should not
be supplied and @code{interp1} returns a piecewise polynomial object.  This
object can later be used with @code{ppval} to evaluate the interpolation.
There is an equivalence, such that @code{ppval (interp1 (@var{x},
@var{y}, @var{method}, @qcode{"pp"}), @var{xi}) == interp1 (@var{x}, @var{y},
@var{xi}, @var{method}, @qcode{"extrap"})}.

Duplicate points in @var{x} specify a discontinuous interpolant.  There
may be at most 2 consecutive points with the same value.
If @var{x} is increasing, the default discontinuous interpolant is
right-continuous.  If @var{x} is decreasing, the default discontinuous
interpolant is left-continuous.
The continuity condition of the interpolant may be specified by using
the options @qcode{"left"} or @qcode{"right"} to select a left-continuous
or right-continuous interpolant, respectively.
Discontinuous interpolation is only allowed for @qcode{"nearest"} and
@qcode{"linear"} methods; in all other cases, the @var{x}-values must be
unique.

An example of the use of @code{interp1} is

@example
@group
xf = [0:0.05:10];
yf = sin (2*pi*xf/5);
xp = [0:10];
yp = sin (2*pi*xp/5);
lin = interp1 (xp, yp, xf);
near = interp1 (xp, yp, xf, "nearest");
pch = interp1 (xp, yp, xf, "pchip");
spl = interp1 (xp, yp, xf, "spline");
plot (xf,yf,"r", xf,near,"g", xf,lin,"b", xf,pch,"c", xf,spl,"m",
      xp,yp,"r*");
legend ("original", "nearest", "linear", "pchip", "spline");
@end group
@end example

@seealso{pchip, spline, interpft, interp2, interp3, interpn}
@end deftypefn
interp2
@c interp2 scripts/general/interp2.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{zi} =} interp2 (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi})
@deftypefnx {Function File} {@var{zi} =} interp2 (@var{z}, @var{xi}, @var{yi})
@deftypefnx {Function File} {@var{zi} =} interp2 (@var{z}, @var{n})
@deftypefnx {Function File} {@var{zi} =} interp2 (@var{z})
@deftypefnx {Function File} {@var{zi} =} interp2 (@dots{}, @var{method})
@deftypefnx {Function File} {@var{zi} =} interp2 (@dots{}, @var{method}, @var{extrap})

Two-dimensional interpolation.

Interpolate reference data @var{x}, @var{y}, @var{z} to determine @var{zi}
at the coordinates @var{xi}, @var{yi}.  The reference data @var{x}, @var{y}
can be matrices, as returned by @code{meshgrid}, in which case the sizes of
@var{x}, @var{y}, and @var{z} must be equal.  If @var{x}, @var{y} are
vectors describing a grid then @code{length (@var{x}) == columns (@var{z})}
and @code{length (@var{y}) == rows (@var{z})}.  In either case the input
data must be strictly monotonic.

If called without @var{x}, @var{y}, and just a single reference data matrix
@var{z}, the 2-D region
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})} is assumed.
This saves memory if the grid is regular and the distance between points is
not important.

If called with a single reference data matrix @var{z} and a refinement
value @var{n}, then perform interpolation over a grid where each original
interval has been recursively subdivided @var{n} times.  This results in
@code{2^@var{n}-1} additional points for every interval in the original
grid.  If @var{n} is omitted a value of 1 is used.  As an example, the
interval [0,1] with @code{@var{n}==2} results in a refined interval with
points at [0, 1/4, 1/2, 3/4, 1].

The interpolation @var{method} is one of:

@table @asis
@item @qcode{"nearest"}
Return the nearest neighbor.

@item @qcode{"linear"} (default)
Linear interpolation from nearest neighbors.

@item @qcode{"pchip"}
Piecewise cubic Hermite interpolating polynomial---shape-preserving
interpolation with smooth first derivative.

@item @qcode{"cubic"}
Cubic interpolation (same as @qcode{"pchip"}).

@item @qcode{"spline"}
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

@var{extrap} is a scalar number.  It replaces values beyond the endpoints
with @var{extrap}.  Note that if @var{extrapval} is used, @var{method} must
be specified as well.  If @var{extrap} is omitted and the @var{method} is
@qcode{"spline"}, then the extrapolated values of the @qcode{"spline"} are
used.  Otherwise the default @var{extrap} value for any other @var{method}
is @qcode{"NA"}.
@seealso{interp1, interp3, interpn, meshgrid}
@end deftypefn
interp3
@c interp3 scripts/general/interp3.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{vi} =} interp3 (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {Function File} {@var{vi} =} interp3 (@var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {Function File} {@var{vi} =} interp3 (@var{v}, @var{n})
@deftypefnx {Function File} {@var{vi} =} interp3 (@var{v})
@deftypefnx {Function File} {@var{vi} =} interp3 (@dots{}, @var{method})
@deftypefnx {Function File} {@var{vi} =} interp3 (@dots{}, @var{method}, @var{extrapval})

Three-dimensional interpolation.

Interpolate reference data @var{x}, @var{y}, @var{z}, @var{v} to determine
@var{vi} at the coordinates @var{xi}, @var{yi}, @var{zi}.  The reference
data @var{x}, @var{y}, @var{z} can be matrices, as returned by
@code{meshgrid}, in which case the sizes of @var{x}, @var{y}, @var{z}, and
@var{v} must be equal.  If @var{x}, @var{y}, @var{z} are vectors describing
a cubic grid then @code{length (@var{x}) == columns (@var{v})},
@code{length (@var{y}) == rows (@var{v})}, and
@code{length (@var{z}) == size (@var{v}, 3)}.  In either case the input
data must be strictly monotonic.

If called without @var{x}, @var{y}, @var{z}, and just a single reference
data matrix @var{v}, the 3-D region
@code{@var{x} = 1:columns (@var{v}), @var{y} = 1:rows (@var{v}),
@var{z} = 1:size (@var{v}, 3)} is assumed.
This saves memory if the grid is regular and the distance between points is
not important.

If called with a single reference data matrix @var{v} and a refinement
value @var{n}, then perform interpolation over a 3-D grid where each original
interval has been recursively subdivided @var{n} times.  This results in
@code{2^@var{n}-1} additional points for every interval in the original
grid.  If @var{n} is omitted a value of 1 is used.  As an example, the
interval [0,1] with @code{@var{n}==2} results in a refined interval with
points at [0, 1/4, 1/2, 3/4, 1].

The interpolation @var{method} is one of:

@table @asis
@item @qcode{"nearest"}
Return the nearest neighbor.

@item @qcode{"linear"} (default)
Linear interpolation from nearest neighbors.

@item @qcode{"cubic"}
Piecewise cubic Hermite interpolating polynomial---shape-preserving
interpolation with smooth first derivative (not implemented yet).

@item @qcode{"spline"}
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

@var{extrapval} is a scalar number.  It replaces values beyond the endpoints
with @var{extrapval}.  Note that if @var{extrapval} is used, @var{method}
must be specified as well.  If @var{extrapval} is omitted and the
@var{method} is @qcode{"spline"}, then the extrapolated values of the
@qcode{"spline"} are used.  Otherwise the default @var{extrapval} value for
any other @var{method} is @qcode{"NA"}.
@seealso{interp1, interp2, interpn, meshgrid}
@end deftypefn
interpft
@c interpft scripts/general/interpft.m
-*- texinfo -*-
@deftypefn  {Function File} {} interpft (@var{x}, @var{n})
@deftypefnx {Function File} {} interpft (@var{x}, @var{n}, @var{dim})

Fourier interpolation.

If @var{x} is a vector then @var{x} is resampled with @var{n} points.  The
data in @var{x} is assumed to be equispaced.  If @var{x} is a matrix or an
N-dimensional array, the interpolation is performed on each column of
@var{x}.

If @var{dim} is specified, then interpolate along the dimension @var{dim}.

@code{interpft} assumes that the interpolated function is periodic, and so
assumptions are made about the endpoints of the interpolation.
@seealso{interp1}
@end deftypefn
interpn
@c interpn scripts/general/interpn.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{vi} =} interpn (@var{x1}, @var{x2}, @dots{}, @var{v}, @var{y1}, @var{y2}, @dots{})
@deftypefnx {Function File} {@var{vi} =} interpn (@var{v}, @var{y1}, @var{y2}, @dots{})
@deftypefnx {Function File} {@var{vi} =} interpn (@var{v}, @var{m})
@deftypefnx {Function File} {@var{vi} =} interpn (@var{v})
@deftypefnx {Function File} {@var{vi} =} interpn (@dots{}, @var{method})
@deftypefnx {Function File} {@var{vi} =} interpn (@dots{}, @var{method}, @var{extrapval})

Perform @var{n}-dimensional interpolation, where @var{n} is at least two.

Each element of the @var{n}-dimensional array @var{v} represents a value
at a location given by the parameters @var{x1}, @var{x2}, @dots{}, @var{xn}.
The parameters @var{x1}, @var{x2}, @dots{}, @var{xn} are either
@var{n}-dimensional arrays of the same size as the array @var{v} in
the @qcode{"ndgrid"} format or vectors.  The parameters @var{y1}, etc.
respect a similar format to @var{x1}, etc., and they represent the points
at which the array @var{vi} is interpolated.

If @var{x1}, @dots{}, @var{xn} are omitted, they are assumed to be
@code{x1 = 1 : size (@var{v}, 1)}, etc.  If @var{m} is specified, then
the interpolation adds a point half way between each of the interpolation
points.  This process is performed @var{m} times.  If only @var{v} is
specified, then @var{m} is assumed to be @code{1}.

The interpolation @var{method} is one of:

@table @asis
@item @qcode{"nearest"}
Return the nearest neighbor.

@item @qcode{"linear"} (default)
Linear interpolation from nearest neighbors.

@item @qcode{"pchip"}
Piecewise cubic Hermite interpolating polynomial---shape-preserving
interpolation with smooth first derivative (not implemented yet).

@item @qcode{"cubic"}
Cubic interpolation (same as @qcode{"pchip"} [not implemented yet]).

@item @qcode{"spline"}
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

The default method is @qcode{"linear"}.

@var{extrapval} is a scalar number.  It replaces values beyond the endpoints
with @var{extrapval}.  Note that if @var{extrapval} is used, @var{method}
must be specified as well.  If @var{extrapval} is omitted and the
@var{method} is @qcode{"spline"}, then the extrapolated values of the
@qcode{"spline"} are used.  Otherwise the default @var{extrapval} value for
any other @var{method} is @qcode{"NA"}.
@seealso{interp1, interp2, interp3, spline, ndgrid}
@end deftypefn
isdir
@c isdir scripts/general/isdir.m
-*- texinfo -*-
@deftypefn {Function File} {} isdir (@var{f})
Return true if @var{f} is a directory.
@seealso{exist, stat, is_absolute_filename, is_rooted_relative_filename}
@end deftypefn
isequal
@c isequal scripts/general/isequal.m
-*- texinfo -*-
@deftypefn {Function File} {} isequal (@var{x1}, @var{x2}, @dots{})
Return true if all of @var{x1}, @var{x2}, @dots{} are equal.
@seealso{isequaln}
@end deftypefn
isequaln
@c isequaln scripts/general/isequaln.m
-*- texinfo -*-
@deftypefn {Function File} {} isequaln (@var{x1}, @var{x2}, @dots{})
Return true if all of @var{x1}, @var{x2}, @dots{} are equal under the
additional assumption that NaN == NaN (no comparison of NaN placeholders
in dataset).
@seealso{isequal}
@end deftypefn
loadobj
@c loadobj scripts/general/loadobj.m
-*- texinfo -*-
@deftypefn {Function File} {@var{b} =} loadobj (@var{a})
Method of a class to manipulate an object after loading it from a file.

The function @code{loadobj} is called when the object @var{a} is loaded
using the @code{load} function.  An example of the use of @code{saveobj}
might be to add fields to an object that don't make sense to be saved.
For example:

@example
@group
function b = loadobj (a)
  b = a;
  b.addmissingfield = addfield (b);
endfunction
@end group
@end example

@seealso{saveobj, class}
@end deftypefn
logspace
@c logspace scripts/general/logspace.m
-*- texinfo -*-
@deftypefn  {Function File} {} logspace (@var{a}, @var{b})
@deftypefnx {Function File} {} logspace (@var{a}, @var{b}, @var{n})
@deftypefnx {Function File} {} logspace (@var{a}, pi, @var{n})
Return a row vector with @var{n} elements logarithmically spaced from
@tex
$10^{a}$ to $10^{b}$.
@end tex
@ifnottex
10^@var{a} to 10^@var{b}.
@end ifnottex

If @var{n} is unspecified it defaults to 50.

If @var{b} is equal to
@tex
$\pi$,
@end tex
@ifnottex
pi,
@end ifnottex
the points are between
@tex
$10^{a}$ and $\pi$,
@end tex
@ifnottex
10^@var{a} and pi,
@end ifnottex
@emph{not}
@tex
$10^{a}$ and $10^{\pi}$,
@end tex
@ifnottex
10^@var{a} and 10^pi,
@end ifnottex
in order to be compatible with the corresponding @sc{matlab} function.

Also for compatibility with @sc{matlab}, return the second argument @var{b}
if fewer than two values are requested.
@seealso{linspace}
@end deftypefn
methods
@c methods scripts/general/methods.m
-*- texinfo -*-
@deftypefn  {Function File} {} methods (@var{obj})
@deftypefnx {Function File} {} methods ("@var{classname}")
@deftypefnx {Function File} {@var{mtds} =} methods (@dots{})

Return a cell array containing the names of the methods for the
object @var{obj} or the named class @var{classname}.

@var{obj} may be an Octave class object or a Java object.

@seealso{fieldnames}
@end deftypefn
nargchk
@c nargchk scripts/general/nargchk.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{msgstr} =} nargchk (@var{minargs}, @var{maxargs}, @var{nargs})
@deftypefnx {Function File} {@var{msgstr} =} nargchk (@var{minargs}, @var{maxargs}, @var{nargs}, "string")
@deftypefnx {Function File} {@var{msgstruct} =} nargchk (@var{minargs}, @var{maxargs}, @var{nargs}, "struct")
Return an appropriate error message string (or structure) if the number of
inputs requested is invalid.

This is useful for checking to see that the number of input arguments
supplied to a function is within an acceptable range.

@strong{Caution}: @code{nargchk} is scheduled for deprecation.  Use
@code{narginchk} in all new code.
@seealso{narginchk, nargoutchk, error, nargin, nargout}
@end deftypefn
narginchk
@c narginchk scripts/general/narginchk.m
-*- texinfo -*-
@deftypefn {Function File} {} narginchk (@var{minargs}, @var{maxargs})
Check for correct number of input arguments.

Generate an error message if the number of arguments in the calling function
is outside the range @var{minargs} and @var{maxargs}.  Otherwise, do nothing.

Both @var{minargs} and @var{maxargs} must be scalar numeric values.  Zero,
Inf, and negative values are all allowed, and @var{minargs} and @var{maxargs}
may be equal.

Note that this function evaluates @code{nargin} on the caller.

@seealso{nargoutchk, error, nargout, nargin}
@end deftypefn
nargoutchk
@c nargoutchk scripts/general/nargoutchk.m
-*- texinfo -*-
@deftypefn  {Function File} {} nargoutchk (@var{minargs}, @var{maxargs})
@deftypefnx {Function File} {@var{msgstr} =} nargoutchk (@var{minargs}, @var{maxargs}, @var{nargs})
@deftypefnx {Function File} {@var{msgstr} =} nargoutchk (@var{minargs}, @var{maxargs}, @var{nargs}, "string")
@deftypefnx {Function File} {@var{msgstruct} =} nargoutchk (@var{minargs}, @var{maxargs}, @var{nargs}, "struct")
Check for correct number of output arguments.

In the first form, return an error if the number of arguments is not between
@var{minargs} and @var{maxargs}.  Otherwise, do nothing.  Note that this
function evaluates the value of @code{nargout} on the caller so its value
must have not been tampered with.

Both @var{minargs} and @var{maxargs} must be numeric scalars.  Zero, Inf,
and negative are all valid, and they can have the same value.

For backwards compatibility, the other forms return an appropriate error
message string (or structure) if the number of outputs requested is
invalid.

This is useful for checking to that the number of output arguments supplied
to a function is within an acceptable range.
@seealso{narginchk, error, nargout, nargin}
@end deftypefn
nextpow2
@c nextpow2 scripts/general/nextpow2.m
-*- texinfo -*-
@deftypefn {Function File} {} nextpow2 (@var{x})
Compute the exponent for the smallest power of two larger than the input.

For each element in the input array @var{x}, return the first integer
@var{n} such that
@tex
$2^n \ge |x|$.
@end tex
@ifnottex
2^n @geq{} abs (x).
@end ifnottex

@seealso{pow2, log2}
@end deftypefn
nthargout
@c nthargout scripts/general/nthargout.m
-*- texinfo -*-
@deftypefn  {Function File} {} nthargout (@var{n}, @var{func}, @dots{})
@deftypefnx {Function File} {} nthargout (@var{n}, @var{ntot}, @var{func}, @dots{})
Return the @var{n}th output argument of the function specified by the
function handle or string @var{func}.

Any additional arguments are passed directly to @var{func}.  The total
number of arguments to call @var{func} with can be passed in @var{ntot}; by
default @var{ntot} is @var{n}.  The input @var{n} can also be a vector of
indices of the output, in which case the output will be a cell array of the
requested output arguments.

The intended use @code{nthargout} is to avoid intermediate variables.  For
example, when finding the indices of the maximum entry of a matrix, the
following two compositions of nthargout

@example
@group
@var{m} = magic (5);
cell2mat (nthargout ([1, 2], @@ind2sub, size (@var{m}),
                     nthargout (2, @@max, @var{m}(:))))
@result{} 5   3
@end group
@end example

@noindent
are completely equivalent to the following lines:

@example
@group
@var{m} = magic (5);
[~, idx] = max (@var{M}(:));
[i, j] = ind2sub (size (@var{m}), idx);
[i, j]
@result{} 5   3
@end group
@end example

It can also be helpful to have all output arguments in a single cell in the
following manner:

@example
@var{USV} = nthargout ([1:3], @@svd, hilb (5));
@end example

@seealso{nargin, nargout, varargin, varargout, isargout}
@end deftypefn
num2str
@c num2str scripts/general/num2str.m
-*- texinfo -*-
@deftypefn  {Function File} {} num2str (@var{x})
@deftypefnx {Function File} {} num2str (@var{x}, @var{precision})
@deftypefnx {Function File} {} num2str (@var{x}, @var{format})
Convert a number (or array) to a string (or a character array).

The optional second argument may either give the number of significant
digits (@var{precision}) to be used in the output or a format template
string (@var{format}) as in @code{sprintf} (@pxref{Formatted Output}).
@code{num2str} can also process complex numbers.

Examples:

@example
@group
num2str (123.456)
     @result{} "123.46"

num2str (123.456, 4)
     @result{} "123.5"

s = num2str ([1, 1.34; 3, 3.56], "%5.1f")
     @result{} s =
        1.0  1.3
        3.0  3.6
whos s
     @result{}
      Attr Name        Size                     Bytes  Class
      ==== ====        ====                     =====  =====
           s           2x8                         16  char

num2str (1.234 + 27.3i)
     @result{} "1.234+27.3i"
@end group
@end example

Notes:

For @sc{matlab} compatibility, leading spaces are stripped before returning
the string.

The @code{num2str} function is not very flexible.  For better control
over the results, use @code{sprintf} (@pxref{Formatted Output}).

For complex @var{x}, the format string may only contain one output
conversion specification and nothing else.  Otherwise, results will be
unpredictable.
@seealso{sprintf, int2str, mat2str}
@end deftypefn
pol2cart
@c pol2cart scripts/general/pol2cart.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{x}, @var{y}] =} pol2cart (@var{theta}, @var{r})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} pol2cart (@var{theta}, @var{r}, @var{z})
@deftypefnx {Function File} {[@var{x}, @var{y}] =} pol2cart (@var{P})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} pol2cart (@var{P})
@deftypefnx {Function File} {@var{C} =} pol2cart (@dots{})
Transform polar or cylindrical coordinates to Cartesian coordinates.

The inputs @var{theta}, @var{r}, (and @var{z}) must be the same shape, or
scalar.  If called with a single matrix argument then each row of @var{P}
represents the polar/(cylindrical) coordinate (@var{theta}, @var{r}
(, @var{z})).

@var{theta} describes the angle relative to the positive x-axis.

@var{r} is the distance to the z-axis (0, 0, z).

If only a single return argument is requested then return a matrix @var{C}
where each row represents one Cartesian coordinate
(@var{x}, @var{y} (, @var{z})).
@seealso{cart2pol, sph2cart, cart2sph}
@end deftypefn
polyarea
@c polyarea scripts/general/polyarea.m
-*- texinfo -*-
@deftypefn  {Function File} {} polyarea (@var{x}, @var{y})
@deftypefnx {Function File} {} polyarea (@var{x}, @var{y}, @var{dim})

Determine area of a polygon by triangle method.

The variables @var{x} and @var{y} define the vertex pairs, and must
therefore have the same shape.  They can be either vectors or arrays.  If
they are arrays then the columns of @var{x} and @var{y} are treated
separately and an area returned for each.

If the optional @var{dim} argument is given, then @code{polyarea} works
along this dimension of the arrays @var{x} and @var{y}.

@end deftypefn
postpad
@c postpad scripts/general/postpad.m
-*- texinfo -*-
@deftypefn  {Function File} {} postpad (@var{x}, @var{l})
@deftypefnx {Function File} {} postpad (@var{x}, @var{l}, @var{c})
@deftypefnx {Function File} {} postpad (@var{x}, @var{l}, @var{c}, @var{dim})
Append the scalar value @var{c} to the vector @var{x} until it is of length
@var{l}.  If @var{c} is not given, a value of 0 is used.

If @code{length (@var{x}) > @var{l}}, elements from the end of @var{x} are
removed until a vector of length @var{l} is obtained.

If @var{x} is a matrix, elements are appended or removed from each row.

If the optional argument @var{dim} is given, operate along this dimension.

If @var{dim} is larger than the dimensions of @var{x}, the result will have
@var{dim} dimensions.
@seealso{prepad, cat, resize}
@end deftypefn
prepad
@c prepad scripts/general/prepad.m
-*- texinfo -*-
@deftypefn  {Function File} {} prepad (@var{x}, @var{l})
@deftypefnx {Function File} {} prepad (@var{x}, @var{l}, @var{c})
@deftypefnx {Function File} {} prepad (@var{x}, @var{l}, @var{c}, @var{dim})
Prepend the scalar value @var{c} to the vector @var{x} until it is of length
@var{l}.  If @var{c} is not given, a value of 0 is used.

If @code{length (@var{x}) > @var{l}}, elements from the beginning of @var{x}
are removed until a vector of length @var{l} is obtained.

If @var{x} is a matrix, elements are prepended or removed from each row.

If the optional argument @var{dim} is given, operate along this dimension.

If @var{dim} is larger than the dimensions of @var{x}, the result will have
@var{dim} dimensions.
@seealso{postpad, cat, resize}
@end deftypefn
profexplore
@c profexplore scripts/general/profexplore.m
-*- texinfo -*-
@deftypefn  {Function File} {} profexplore ()
@deftypefnx {Function File} {} profexplore (@var{data})
Interactively explore hierarchical profiler output.

Assuming @var{data} is the structure with profile data returned by
@code{profile (@qcode{"info"})}, this command opens an interactive prompt
that can be used to explore the call-tree.  Type @kbd{help} to get a list
of possible commands.  If @var{data} is omitted, @code{profile ("info")}
is called and used in its place.
@seealso{profile, profshow}
@end deftypefn
profile
@c profile scripts/general/profile.m
-*- texinfo -*-
@deftypefn  {Command} {} profile on
@deftypefnx {Command} {} profile off
@deftypefnx {Command} {} profile resume
@deftypefnx {Command} {} profile clear
@deftypefnx {Function File} {@var{S} =} profile ("status")
@deftypefnx {Function File} {@var{T} =} profile ("info")
Control the built-in profiler.

@table @code
@item profile on
Start the profiler, clearing all previously collected data if there is any.

@item profile off
Stop profiling.  The collected data can later be retrieved and examined
with @code{T = profile ("info")}.

@item profile clear
Clear all collected profiler data.

@item profile resume
Restart profiling without clearing the old data.  All newly collected
statistics are added to the existing ones.

@item @var{S} = profile ("status")
Return a structure with information about the current status of the profiler.
At the moment, the only field is @code{ProfilerStatus} which is either
@qcode{"on"} or @qcode{"off"}.

@item @var{T} = profile ("info")
Return the collected profiling statistics in the structure @var{T}.  The
flat profile is returned in the field @code{FunctionTable} which is an
array of structures, each entry corresponding to a function which was called
and for which profiling statistics are present.  In addition, the field
@code{Hierarchical} contains the hierarchical call tree.  Each node has an
index into the @code{FunctionTable} identifying the function it corresponds
to as well as data fields for number of calls and time spent at this level
in the call tree.
@seealso{profshow, profexplore}
@end table
@end deftypefn
profshow
@c profshow scripts/general/profshow.m
-*- texinfo -*-
@deftypefn  {Function File} {} profshow (@var{data})
@deftypefnx {Function File} {} profshow (@var{data}, @var{n})
@deftypefnx {Function File} {} profshow ()
@deftypefnx {Function File} {} profshow (@var{n})
Display flat per-function profiler results.

Print out profiler data (execution time, number of calls) for the most
critical @var{n} functions.  The results are sorted in descending order by
the total time spent in each function.  If @var{n} is unspecified it
defaults to 20.

The input @var{data} is the structure returned by @code{profile ("info")}.
If unspecified, @code{profshow} will use the current profile dataset.

The attribute column displays @samp{R} for recursive functions, and is blank
for all other function types.
@seealso{profexplore, profile}
@end deftypefn
quadgk
@c quadgk scripts/general/quadgk.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{q} =} quadgk (@var{f}, @var{a}, @var{b})
@deftypefnx {Function File} {@var{q} =} quadgk (@var{f}, @var{a}, @var{b}, @var{abstol})
@deftypefnx {Function File} {@var{q} =} quadgk (@var{f}, @var{a}, @var{b}, @var{abstol}, @var{trace})
@deftypefnx {Function File} {@var{q} =} quadgk (@var{f}, @var{a}, @var{b}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {[@var{q}, @var{err}] =} quadgk (@dots{})

Numerically evaluate the integral of @var{f} from @var{a} to @var{b}
using adaptive Gauss-Konrod quadrature.

@var{f} is a function handle, inline function, or string containing the name
of the function to evaluate.  The function @var{f} must be vectorized and
return a vector of output values when given a vector of input values.

@var{a} and @var{b} are the lower and upper limits of integration.  Either
or both limits may be infinite or contain weak end singularities.  Variable
transformation will be used to treat any infinite intervals and weaken the
singularities.  For example:

@example
quadgk (@@(x) 1 ./ (sqrt (x) .* (x + 1)), 0, Inf)
@end example

@noindent
Note that the formulation of the integrand uses the element-by-element
operator @code{./} and all user functions to @code{quadgk} should do the
same.

The optional argument @var{tol} defines the absolute tolerance used to stop
the integration procedure.  The default value is 1e-10.

The algorithm used by @code{quadgk} involves subdividing the integration
interval and evaluating each subinterval.  If @var{trace} is true then after
computing each of these partial integrals display: (1) the number of
subintervals at this step, (2) the current estimate of the error @var{err},
(3) the current estimate for the integral @var{q}.

Alternatively, properties of @code{quadgk} can be passed to the function as
pairs @qcode{"@var{prop}", @var{val}}.  Valid properties are

@table @code
@item AbsTol
Define the absolute error tolerance for the quadrature.  The default
absolute tolerance is 1e-10.

@item RelTol
Define the relative error tolerance for the quadrature.  The default
relative tolerance is 1e-5.

@item MaxIntervalCount
@code{quadgk} initially subdivides the interval on which to perform the
quadrature into 10 intervals.  Subintervals that have an unacceptable error
are subdivided and re-evaluated.  If the number of subintervals exceeds 650
subintervals at any point then a poor convergence is signaled and the
current estimate of the integral is returned.  The property
@qcode{"MaxIntervalCount"} can be used to alter the number of subintervals
that can exist before exiting.

@item WayPoints
Discontinuities in the first derivative of the function to integrate can be
flagged with the @qcode{"WayPoints"} property.  This forces the ends of a
subinterval to fall on the breakpoints of the function and can result in
significantly improved estimation of the error in the integral, faster
computation, or both.  For example,

@example
quadgk (@@(x) abs (1 - x.^2), 0, 2, "Waypoints", 1)
@end example

@noindent
signals the breakpoint in the integrand at @code{@var{x} = 1}.

@item Trace
If logically true @code{quadgk} prints information on the convergence of the
quadrature at each iteration.
@end table

If any of @var{a}, @var{b}, or @var{waypoints} is complex then the
quadrature is treated as a contour integral along a piecewise continuous
path defined by the above.  In this case the integral is assumed to have no
edge singularities.  For example,

@example
@group
quadgk (@@(z) log (z), 1+1i, 1+1i, "WayPoints",
        [1-1i, -1,-1i, -1+1i])
@end group
@end example

@noindent
integrates @code{log (z)} along the square defined by
@code{[1+1i, 1-1i, -1-1i, -1+1i]}.

The result of the integration is returned in @var{q}.

@var{err} is an approximate bound on the error in the integral
@code{abs (@var{q} - @var{I})}, where @var{I} is the exact value of the
integral.

Reference: @nospell{L.F. Shampine},
@cite{"Vectorized adaptive quadrature in @sc{matlab}"}, Journal of
Computational and Applied Mathematics, pp. 131--140, Vol 211, Issue 2,
Feb 2008.

@seealso{quad, quadv, quadl, quadcc, trapz, dblquad, triplequad}
@end deftypefn
quadl
@c quadl scripts/general/quadl.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{q} =} quadl (@var{f}, @var{a}, @var{b})
@deftypefnx {Function File} {@var{q} =} quadl (@var{f}, @var{a}, @var{b}, @var{tol})
@deftypefnx {Function File} {@var{q} =} quadl (@var{f}, @var{a}, @var{b}, @var{tol}, @var{trace})
@deftypefnx {Function File} {@var{q} =} quadl (@var{f}, @var{a}, @var{b}, @var{tol}, @var{trace}, @var{p1}, @var{p2}, @dots{})

Numerically evaluate the integral of @var{f} from @var{a} to @var{b} using
an adaptive Lobatto rule.

@var{f} is a function handle, inline function, or string containing the name
of the function to evaluate.  The function @var{f} must be vectorized and
return a vector of output values when given a vector of input values.

@var{a} and @var{b} are the lower and upper limits of integration.  Both
limits must be finite.

The optional argument @var{tol} defines the relative tolerance with which
to perform the integration.  The default value is @code{eps}.

The algorithm used by @code{quadl} involves recursively subdividing the
integration interval.  If @var{trace} is defined then for each subinterval
display: (1) the left end of the subinterval, (2) the length of the
subinterval, (3) the approximation of the integral over the subinterval.

Additional arguments @var{p1}, etc., are passed directly to the function
@var{f}.  To use default values for @var{tol} and @var{trace}, one may pass
empty matrices ([]).

Reference: @nospell{W. Gander and W. Gautschi}, @cite{Adaptive Quadrature -
Revisited}, BIT Vol. 40, No. 1, March 2000, pp. 84--101.
@url{http://www.inf.ethz.ch/personal/gander/}
@seealso{quad, quadv, quadgk, quadcc, trapz, dblquad, triplequad}
@end deftypefn
quadv
@c quadv scripts/general/quadv.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{q} =} quadv (@var{f}, @var{a}, @var{b})
@deftypefnx {Function File} {@var{q} =} quadv (@var{f}, @var{a}, @var{b}, @var{tol})
@deftypefnx {Function File} {@var{q} =} quadv (@var{f}, @var{a}, @var{b}, @var{tol}, @var{trace})
@deftypefnx {Function File} {@var{q} =} quadv (@var{f}, @var{a}, @var{b}, @var{tol}, @var{trace}, @var{p1}, @var{p2}, @dots{})
@deftypefnx {Function File} {[@var{q}, @var{nfun}] =} quadv (@dots{})

Numerically evaluate the integral of @var{f} from @var{a} to @var{b}
using an adaptive Simpson's rule.

@var{f} is a function handle, inline function, or string containing the name
of the function to evaluate.  @code{quadv} is a vectorized version of
@code{quad} and the function defined by @var{f} must accept a scalar or
vector as input and return a scalar, vector, or array as output.

@var{a} and @var{b} are the lower and upper limits of integration.  Both
limits must be finite.

The optional argument @var{tol} defines the absolute tolerance used to stop
the adaptation procedure.  The default value is 1e-6.

The algorithm used by @code{quadv} involves recursively subdividing the
integration interval and applying Simpson's rule on each subinterval.
If @var{trace} is true then after computing each of these partial
integrals display: (1) the total number of function evaluations,
(2) the left end of the subinterval, (3) the length of the subinterval,
(4) the approximation of the integral over the subinterval.

Additional arguments @var{p1}, etc., are passed directly to the function
@var{f}.  To use default values for @var{tol} and @var{trace}, one may pass
empty matrices ([]).

The result of the integration is returned in @var{q}

@var{nfun} indicates the number of function evaluations that were made.

Note: @code{quadv} is written in Octave's scripting language and can be
used recursively in @code{dblquad} and @code{triplequad}, unlike the
@code{quad} function.
@seealso{quad, quadl, quadgk, quadcc, trapz, dblquad, triplequad}
@end deftypefn
randi
@c randi scripts/general/randi.m
-*- texinfo -*-
@deftypefn  {Function File} {} randi (@var{imax})
@deftypefnx {Function File} {} randi (@var{imax}, @var{n})
@deftypefnx {Function File} {} randi (@var{imax}, @var{m}, @var{n}, @dots{})
@deftypefnx {Function File} {} randi ([@var{imin} @var{imax}], @dots{})
@deftypefnx {Function File} {} randi (@dots{}, "@var{class}")
Return random integers in the range 1:@var{imax}.

Additional arguments determine the shape of the return matrix.  When no
arguments are specified a single random integer is returned.  If one
argument @var{n} is specified then a square matrix @w{(@var{n} x @var{n})}
is returned.  Two or more arguments will return a multi-dimensional matrix
@w{(@var{m} x @var{n} x @dots{})}.

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 @w{[@var{imin}, @var{imax}]}.

The optional argument @var{class} will return a matrix of the requested
type.  The default is @qcode{"double"}.

The following example returns 150 integers in the range 1--10.

@example
ri = randi (10, 150, 1)
@end example

Implementation Note: @code{randi} relies internally on @code{rand} which
uses class @qcode{"double"} to represent numbers.  This limits the maximum
integer (@var{imax}) and range (@var{imax} - @var{imin}) to the value
returned by the @code{flintmax} function.  For IEEE floating point numbers
this value is @w{@math{2^{53} - 1}}.

@seealso{rand}
@end deftypefn
rat
@c rat scripts/general/rat.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{s} =} rat (@var{x}, @var{tol})
@deftypefnx {Function File} {[@var{n}, @var{d}] =} rat (@var{x}, @var{tol})

Find a rational approximation to @var{x} within the tolerance defined by
@var{tol} using a continued fraction expansion.

For example:

@example
@group
rat (pi) = 3 + 1/(7 + 1/16) = 355/113
rat (e) = 3 + 1/(-4 + 1/(2 + 1/(5 + 1/(-2 + 1/(-7)))))
        = 1457/536
@end group
@end example

When called with two output arguments return the numerator and denominator
separately as two matrices.
@seealso{rats}
@end deftypefn
repmat
@c repmat scripts/general/repmat.m
-*- texinfo -*-
@deftypefn  {Function File} {} repmat (@var{A}, @var{m})
@deftypefnx {Function File} {} repmat (@var{A}, @var{m}, @var{n})
@deftypefnx {Function File} {} repmat (@var{A}, @var{m}, @var{n}, @var{p} @dots{})
@deftypefnx {Function File} {} repmat (@var{A}, [@var{m} @var{n}])
@deftypefnx {Function File} {} repmat (@var{A}, [@var{m} @var{n} @var{p} @dots{}])
Form a block matrix of size @var{m} by @var{n}, with a copy of matrix
@var{A} as each element.

If @var{n} is not specified, form an @var{m} by @var{m} block matrix.  For
copying along more than two dimensions, specify the number of times to copy
across each dimension @var{m}, @var{n}, @var{p}, @dots{}, in a vector in the
second argument.
@seealso{repelems}
@end deftypefn
rot90
@c rot90 scripts/general/rot90.m
-*- texinfo -*-
@deftypefn  {Function File} {} rot90 (@var{A})
@deftypefnx {Function File} {} rot90 (@var{A}, @var{k})
Rotate array by 90 degree increments.

Return a copy of @var{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 @var{k}
rotate the matrix in a clockwise direction.
For example,

@example
@group
rot90 ([1, 2; 3, 4], -1)
    @result{}  3  1
        4  2
@end group
@end example

@noindent
rotates the given matrix clockwise by 90 degrees.  The following are all
equivalent statements:

@example
@group
rot90 ([1, 2; 3, 4], -1)
rot90 ([1, 2; 3, 4], 3)
rot90 ([1, 2; 3, 4], 7)
@end group
@end example

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
@code{rotdim}.

@seealso{rotdim, fliplr, flipud, flip}
@end deftypefn
rotdim
@c rotdim scripts/general/rotdim.m
-*- texinfo -*-
@deftypefn  {Function File} {} rotdim (@var{x})
@deftypefnx {Function File} {} rotdim (@var{x}, @var{n})
@deftypefnx {Function File} {} rotdim (@var{x}, @var{n}, @var{plane})
Return a copy of @var{x} with the elements rotated counterclockwise in
90-degree increments.

The second argument @var{n} is optional, and specifies how many 90-degree
rotations are to be applied (the default value is 1).  Negative values of
@var{n} rotate the matrix in a clockwise direction.

The third argument is also optional and defines the plane of the rotation.
If present, @var{plane} is a two element vector containing two different
valid dimensions of the matrix.  When @var{plane} is not given the first two
non-singleton dimensions are used.

For example,

@example
@group
rotdim ([1, 2; 3, 4], -1, [1, 2])
     @result{}  3  1
         4  2
@end group
@end example

@noindent
rotates the given matrix clockwise by 90 degrees.  The following are all
equivalent statements:

@example
@group
rotdim ([1, 2; 3, 4], -1, [1, 2])
rotdim ([1, 2; 3, 4], 3, [1, 2])
rotdim ([1, 2; 3, 4], 7, [1, 2])
@end group
@end example
@seealso{rot90, fliplr, flipud, flip}
@end deftypefn
saveobj
@c saveobj scripts/general/saveobj.m
-*- texinfo -*-
@deftypefn {Function File} {@var{b} =} saveobj (@var{a})
Method of a class to manipulate an object prior to saving it to a file.

The function @code{saveobj} is called when the object @var{a} is saved
using the @code{save} function.  An example of the use of @code{saveobj}
might be to remove fields of the object that don't make sense to be saved
or it might be used to ensure that certain fields of the object are
initialized before the object is saved.  For example:

@example
@group
function b = saveobj (a)
  b = a;
  if (isempty (b.field))
     b.field = initfield (b);
  endif
endfunction
@end group
@end example

@seealso{loadobj, class}
@end deftypefn
shift
@c shift scripts/general/shift.m
-*- texinfo -*-
@deftypefn  {Function File} {} shift (@var{x}, @var{b})
@deftypefnx {Function File} {} shift (@var{x}, @var{b}, @var{dim})
If @var{x} is a vector, perform a circular shift of length @var{b} of
the elements of @var{x}.

If @var{x} is a matrix, do the same for each column of @var{x}.

If the optional @var{dim} argument is given, operate along this dimension.
@end deftypefn
shiftdim
@c shiftdim scripts/general/shiftdim.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{y} =} shiftdim (@var{x}, @var{n})
@deftypefnx {Function File} {[@var{y}, @var{ns}] =} shiftdim (@var{x})
Shift the dimensions of @var{x} by @var{n}, where @var{n} must be
an integer scalar.

When @var{n} is positive, the dimensions of @var{x} are shifted to the left,
with the leading dimensions circulated to the end.  If @var{n} is negative,
then the dimensions of @var{x} are shifted to the right, with @var{n}
leading singleton dimensions added.

Called with a single argument, @code{shiftdim}, removes the leading
singleton dimensions, returning the number of dimensions removed in the
second output argument @var{ns}.

For example:

@example
@group
x = ones (1, 2, 3);
size (shiftdim (x, -1))
   @result{} [1, 1, 2, 3]
size (shiftdim (x, 1))
   @result{} [2, 3]
[b, ns] = shiftdim (x)
   @result{} b = [1, 1, 1; 1, 1, 1]
   @result{} ns = 1
@end group
@end example
@seealso{reshape, permute, ipermute, circshift, squeeze}
@end deftypefn
sortrows
@c sortrows scripts/general/sortrows.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{s}, @var{i}] =} sortrows (@var{A})
@deftypefnx {Function File} {[@var{s}, @var{i}] =} sortrows (@var{A}, @var{c})
Sort the rows of the matrix @var{A} according to the order of the columns
specified in @var{c}.

If @var{c} is omitted, a lexicographical sort is used.  By default ascending
order is used however if elements of @var{c} are negative then the
corresponding column is sorted in descending order.
@seealso{sort}
@end deftypefn
sph2cart
@c sph2cart scripts/general/sph2cart.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{x}, @var{y}, @var{z}] =} sph2cart (@var{theta}, @var{phi}, @var{r})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} sph2cart (@var{S})
@deftypefnx {Function File} {@var{C} =} sph2cart (@dots{})
Transform spherical coordinates to Cartesian coordinates.

The inputs @var{theta}, @var{phi}, and @var{r} must be the same shape, or
scalar.  If called with a single matrix argument then each row of @var{S}
represents the spherical coordinate (@var{theta}, @var{phi}, @var{r}).

@var{theta} describes the angle relative to the positive x-axis.

@var{phi} is the angle relative to the xy-plane.

@var{r} is the distance to the origin @w{(0, 0, 0)}.

If only a single return argument is requested then return a matrix @var{C}
where each row represents one Cartesian coordinate
(@var{x}, @var{y}, @var{z}).
@seealso{cart2sph, pol2cart, cart2pol}
@end deftypefn
structfun
@c structfun scripts/general/structfun.m
-*- texinfo -*-
@deftypefn  {Function File} {} structfun (@var{func}, @var{S})
@deftypefnx {Function File} {[@var{A}, @dots{}] =} structfun (@dots{})
@deftypefnx {Function File} {} structfun (@dots{}, "ErrorHandler", @var{errfunc})
@deftypefnx {Function File} {} structfun (@dots{}, "UniformOutput", @var{val})

Evaluate the function named @var{name} on the fields of the structure
@var{S}.  The fields of @var{S} are passed to the function @var{func}
individually.

@code{structfun} accepts an arbitrary function @var{func} in the form of an
inline function, function handle, or the name of a function (in a character
string).  In the case of a character string argument, the function must
accept a single argument named @var{x}, and it must return a string value.
If the function returns more than one argument, they are returned as
separate output variables.

If the parameter @qcode{"UniformOutput"} is set to true (the default), then
the function must return a single element which will be concatenated into
the return value.  If @qcode{"UniformOutput"} is false, the outputs are
placed into a structure with the same fieldnames as the input structure.

@example
@group
s.name1 = "John Smith";
s.name2 = "Jill Jones";
structfun (@@(x) regexp (x, '(\w+)$', "matches")@{1@}, s,
           "UniformOutput", false)
@result{}
   @{
     name1 = Smith
     name2 = Jones
   @}
@end group
@end example

Given the parameter @qcode{"ErrorHandler"}, @var{errfunc} defines a function
to call in case @var{func} generates an error.  The form of the function is

@example
function [@dots{}] = errfunc (@var{se}, @dots{})
@end example

@noindent
where there is an additional input argument to @var{errfunc} relative to
@var{func}, given by @nospell{@var{se}}.  This is a structure with the
elements @qcode{"identifier"}, @qcode{"message"} and @qcode{"index"},
giving respectively the error identifier, the error message, and the index
into the input arguments of the element that caused the error.  For an
example on how to use an error handler, @pxref{XREFcellfun,,cellfun}.

@seealso{cellfun, arrayfun, spfun}
@end deftypefn
subsindex
@c subsindex scripts/general/subsindex.m
-*- texinfo -*-
@deftypefn {Function File} {@var{idx} =} subsindex (@var{a})
Convert an object to an index vector.

When @var{a} is a class object defined with a class constructor, then
@code{subsindex} is the overloading method that allows the conversion of
this class object to a valid indexing vector.  It is important to note that
@code{subsindex} must return a zero-based real integer vector of the class
@qcode{"double"}.  For example, if the class constructor

@example
@group
function b = myclass (a)
  b = class (struct ("a", a), "myclass");
endfunction
@end group
@end example

@noindent
then the @code{subsindex} function

@example
@group
function idx = subsindex (a)
  idx = double (a.a) - 1.0;
endfunction
@end group
@end example

@noindent
can then be used as follows

@example
@group
a = myclass (1:4);
b = 1:10;
b(a)
@result{} 1  2  3  4
@end group
@end example

@seealso{class, subsref, subsasgn}
@end deftypefn
trapz
@c trapz scripts/general/trapz.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{q} =} trapz (@var{y})
@deftypefnx {Function File} {@var{q} =} trapz (@var{x}, @var{y})
@deftypefnx {Function File} {@var{q} =} trapz (@dots{}, @var{dim})

Numerically evaluate the integral of points @var{y} using the trapezoidal
method.

@w{@code{trapz (@var{y})}} computes the integral of @var{y} along the first
non-singleton dimension.  When the argument @var{x} is omitted an equally
spaced @var{x} vector with unit spacing (1) is assumed.
@code{trapz (@var{x}, @var{y})} evaluates the integral with respect to the
spacing in @var{x} and the values in @var{y}.  This is useful if the points
in @var{y} have been sampled unevenly.

If the optional @var{dim} argument is given, operate along this dimension.

Application Note: If @var{x} is not specified then unit spacing will be
used.  To scale the integral to the correct value you must multiply by the
actual spacing value (deltaX).  As an example, the integral of @math{x^3}
over the range [0, 1] is @math{x^4/4} or 0.25.  The following code uses
@code{trapz} to calculate the integral in three different ways.

@example
@group
x = 0:0.1:1;
y = x.^3;
q = trapz (y)
  @result{} q = 2.525   # No scaling
q * 0.1
  @result{} q = 0.2525  # Approximation to integral by scaling
trapz (x, y)
  @result{} q = 0.2525  # Same result by specifying @var{x}
@end group
@end example

@seealso{cumtrapz}
@end deftypefn
triplequad
@c triplequad scripts/general/triplequad.m
-*- texinfo -*-
@deftypefn  {Function File} {} triplequad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{za}, @var{zb})
@deftypefnx {Function File} {} triplequad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{za}, @var{zb}, @var{tol})
@deftypefnx {Function File} {} triplequad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{za}, @var{zb}, @var{tol}, @var{quadf})
@deftypefnx {Function File} {} triplequad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{za}, @var{zb}, @var{tol}, @var{quadf}, @dots{})
Numerically evaluate the triple integral of @var{f}.

@var{f} is a function handle, inline function, or string containing the name
of the function to evaluate.  The function @var{f} must have the form
@math{w = f(x,y,z)} where either @var{x} or @var{y} is a vector and the
remaining inputs are scalars.  It should return a vector of the same length
and orientation as @var{x} or @var{y}.

@var{xa}, @var{ya}, @var{za} and @var{xb}, @var{yb}, @var{zb} are the lower
and upper limits of integration for x, y, and z respectively.  The
underlying integrator determines whether infinite bounds are accepted.

The optional argument @var{tol} defines the absolute tolerance used to
integrate each sub-integral.  The default value is 1e-6.

The optional argument @var{quadf} specifies which underlying integrator
function to use.  Any choice but @code{quad} is available and the default
is @code{quadcc}.

Additional arguments, are passed directly to @var{f}.  To use the default
value for @var{tol} or @var{quadf} one may pass @qcode{':'} or an empty
matrix ([]).
@seealso{dblquad, quad, quadv, quadl, quadgk, quadcc, trapz}
@end deftypefn
validateattributes
@c validateattributes scripts/general/validateattributes.m
-*- texinfo -*-
@deftypefn  {Function File} {} validateattributes (@var{A}, @var{classes}, @var{attributes})
@deftypefnx {Function File} {} validateattributes (@var{A}, @var{classes}, @var{attributes}, @var{arg_idx})
@deftypefnx {Function File} {} validateattributes (@var{A}, @var{classes}, @var{attributes}, @var{func_name})
@deftypefnx {Function File} {} validateattributes (@var{A}, @var{classes}, @var{attributes}, @var{func_name}, @var{arg_name})
@deftypefnx {Function File} {} validateattributes (@var{A}, @var{classes}, @var{attributes}, @var{func_name}, @var{arg_name}, @var{arg_idx})
Check validity of input argument.

Confirms that the argument @var{A} is valid by belonging to one of
@var{classes}, and holding all of the @var{attributes}.  If it does not,
an error is thrown, with a message formatted accordingly.  The error
message can be made further complete by the function name @var{fun_name},
the argument name @var{arg_name}, and its position in the input
@var{arg_idx}.

@var{classes} must be a cell array of strings (an empty cell array is
allowed) with the name of classes (remember that a class name is case
sensitive).  In addition to the class name, the following categories
names are also valid:

@table @asis
@item @qcode{"float"}
Floating point value comprising classes @qcode{"double"} and
@qcode{"single"}.

@item @qcode{"integer"}
Integer value comprising classes (u)int8, (u)int16, (u)int32, (u)int64.

@item @qcode{"numeric"}
Numeric value comprising either a floating point or integer value.

@end table

@var{attributes} must be a cell array with names of checks for @var{A}.
Some of them require an additional value to be supplied right after the
name (see details for each below).

@table @asis
@item @qcode{"<="}
All values are less than or equal to the following value in @var{attributes}.

@item @qcode{"<"}
All values are less than the following value in @var{attributes}.

@item @qcode{">="}
All values are greater than or equal to the following value in
@var{attributes}.

@item @qcode{">"}
All values are greater than the following value in @var{attributes}.

@item @qcode{"2d"}
A 2-dimensional matrix.  Note that vectors and empty matrices have
2 dimensions, one of them being of length 1, or both length 0.

@item @qcode{"3d"}
Has no more than 3 dimensions.  A 2-dimensional matrix is a 3-D matrix
whose 3rd dimension is of length 1.

@item @qcode{"binary"}
All values are either 1 or 0.

@item @qcode{"column"}
Values are arranged in a single column.

@item @qcode{"decreasing"}
No value is @var{NaN}, and each is less than the preceding one.

@item @qcode{"even"}
All values are even numbers.

@item @qcode{"finite"}
All values are finite.

@item @qcode{"increasing"}
No value is @var{NaN}, and each is greater than the preceding one.

@item @qcode{"integer"}
All values are integer.  This is different than using @code{isinteger}
which only checks its an integer type.  This checks that each value in
@var{A} is an integer value, i.e., it has no decimal part.

@item @qcode{"ncols"}
Has exactly as many columns as the next value in @var{attributes}.

@item @qcode{"ndims"}
Has exactly as many dimensions as the next value in @var{attributes}.

@item @qcode{"nondecreasing"}
No value is @var{NaN}, and each is greater than or equal to the preceding
one.

@item @qcode{"nonempty"}
It is not empty.

@item @qcode{"nonincreasing"}
No value is @var{NaN}, and each is less than or equal to the preceding one.

@item @qcode{"nonnan"}
No value is a @code{NaN}.

@item @qcode{"nonnegative"}
All values are non negative.

@item @qcode{"nonsparse"}
It is not a sparse matrix.

@item @qcode{"nonzero"}
No value is zero.

@item @qcode{"nrows"}
Has exactly as many rows as the next value in @var{attributes}.

@item @qcode{"numel"}
Has exactly as many elements as the next value in @var{attributes}.

@item @qcode{"odd"}
All values are odd numbers.

@item @qcode{"positive"}
All values are positive.

@item @qcode{"real"}
It is a non-complex matrix.

@item @qcode{"row"}
Values are arranged in a single row.

@item @qcode{"scalar"}
It is a scalar.

@item @qcode{"size"}
Its size has length equal to the values of the next in @var{attributes}.
The next value must is an array with the length for each dimension.  To
ignore the check for a certain dimension, the value of @code{NaN} can be
used.

@item @qcode{"square"}
Is a square matrix.

@item @qcode{"vector"}
Values are arranged in a single vector (column or vector).

@end table

@seealso{isa, validatestring, inputParser}
@end deftypefn
convhull
@c convhull scripts/geometry/convhull.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{H} =} convhull (@var{x}, @var{y})
@deftypefnx {Function File} {@var{H} =} convhull (@var{x}, @var{y}, @var{options})
Compute the convex hull of the set of points defined by the
arrays @var{x} and @var{y}.  The hull @var{H} is an index vector into
the set of points and specifies which points form the enclosing hull.

An optional third argument, which must be a string or cell array of strings,
contains options passed to the underlying qhull command.
See the documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.
The default option is @code{@{"Qt"@}}.

If @var{options} is not present or @code{[]} then the default arguments are
used.  Otherwise, @var{options} replaces the default argument list.
To append user options to the defaults it is necessary to repeat the
default arguments in @var{options}.  Use a null string to pass no arguments.

@seealso{convhulln, delaunay, voronoi}
@end deftypefn
delaunayn
@c delaunayn scripts/geometry/delaunayn.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{T} =} delaunayn (@var{pts})
@deftypefnx {Function File} {@var{T} =} delaunayn (@var{pts}, @var{options})
Compute the Delaunay triangulation for an N-dimensional set of points.

The Delaunay triangulation is a tessellation of the convex hull of a set of
points such that no N-sphere defined by the N-triangles contains any other
points from the set.

The input matrix @var{pts} of size [n, dim] contains n points in a space of
dimension dim.  The return matrix @var{T} has size [m, dim+1].  Each row of
@var{T} contains a set of indices back into the original set of points
@var{pts} which describes a simplex of dimension dim.  For example, a 2-D
simplex is a triangle and 3-D simplex is a tetrahedron.

An optional second argument, which must be a string or cell array of strings,
contains options passed to the underlying qhull command.
See the documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.
The default options depend on the dimension of the input:

@itemize
@item 2-D and 3-D: @var{options} = @code{@{"Qt", "Qbb", "Qc", "Qz"@}}

@item 4-D and higher: @var{options} = @code{@{"Qt", "Qbb", "Qc", "Qx"@}}
@end itemize

If @var{options} is not present or @code{[]} then the default arguments are
used.  Otherwise, @var{options} replaces the default argument list.
To append user options to the defaults it is necessary to repeat the
default arguments in @var{options}.  Use a null string to pass no arguments.

@seealso{delaunay, convhulln, voronoin, trimesh, tetramesh}
@end deftypefn
delaunay
@c delaunay scripts/geometry/delaunay.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{tri} =} delaunay (@var{x}, @var{y})
@deftypefnx {Function File} {@var{tetr} =} delaunay (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {@var{tri} =} delaunay (@var{x})
@deftypefnx {Function File} {@var{tri} =} delaunay (@dots{}, @var{options})
Compute the Delaunay triangulation for a 2-D or 3-D set of points.

For 2-D sets, the return value @var{tri} is a set of triangles which
satisfies the Delaunay circum-circle criterion, i.e., only a single data
point from [@var{x}, @var{y}] is within the circum-circle of the defining
triangle.  The set of triangles @var{tri} is a matrix of size [n, 3].  Each
row defines a triangle and the three columns are the three vertices of the
triangle.  The value of @code{@var{tri}(i,j)} is an index into @var{x} and
@var{y} for the location of the j-th vertex of the i-th triangle.

For 3-D sets, the return value @var{tetr} is a set of tetrahedrons which
satisfies the Delaunay circum-circle criterion, i.e., only a single data
point from [@var{x}, @var{y}, @var{z}] is within the circum-circle of the
defining tetrahedron.  The set of tetrahedrons is a matrix of size [n, 4].
Each row defines a tetrahedron and the four columns are the four vertices of
the tetrahedron.  The value of @code{@var{tetr}(i,j)} is an index into
@var{x}, @var{y}, @var{z} for the location of the j-th vertex of the i-th
tetrahedron.

The input @var{x} may also be a matrix with two or three columns where the
first column contains x-data, the second y-data, and the optional third
column contains z-data.

The optional last argument, which must be a string or cell array of strings,
contains options passed to the underlying qhull command.
See the documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.
The default options are @code{@{"Qt", "Qbb", "Qc", "Qz"@}}.

If @var{options} is not present or @code{[]} then the default arguments are
used.  Otherwise, @var{options} replaces the default argument list.
To append user options to the defaults it is necessary to repeat the
default arguments in @var{options}.  Use a null string to pass no arguments.

@example
@group
x = rand (1, 10);
y = rand (1, 10);
tri = delaunay (x, y);
triplot (tri, x, y);
hold on;
plot (x, y, "r*");
axis ([0,1,0,1]);
@end group
@end example
@seealso{delaunayn, convhull, voronoi, triplot, trimesh, tetramesh, trisurf}
@end deftypefn
dsearch
@c dsearch scripts/geometry/dsearch.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{idx} =} dsearch (@var{x}, @var{y}, @var{tri}, @var{xi}, @var{yi})
@deftypefnx {Function File} {@var{idx} =} dsearch (@var{x}, @var{y}, @var{tri}, @var{xi}, @var{yi}, @var{s})
Return the index @var{idx} of the closest point in @code{@var{x}, @var{y}}
to the elements @code{[@var{xi}(:), @var{yi}(:)]}.

The variable @var{s} is accepted for compatibility but is ignored.
@seealso{dsearchn, tsearch}
@end deftypefn
dsearchn
@c dsearchn scripts/geometry/dsearchn.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{idx} =} dsearchn (@var{x}, @var{tri}, @var{xi})
@deftypefnx {Function File} {@var{idx} =} dsearchn (@var{x}, @var{tri}, @var{xi}, @var{outval})
@deftypefnx {Function File} {@var{idx} =} dsearchn (@var{x}, @var{xi})
@deftypefnx {Function File} {[@var{idx}, @var{d}] =} dsearchn (@dots{})
Return the index @var{idx} of the closest point in @var{x} to the elements
@var{xi}.

If @var{outval} is supplied, then the values of @var{xi} that are not
contained within one of the simplices @var{tri} are set to @var{outval}.
Generally, @var{tri} is returned from @code{delaunayn (@var{x})}.
@seealso{dsearch, tsearch}
@end deftypefn
griddata
@c griddata scripts/geometry/griddata.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{zi} =} griddata (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi})
@deftypefnx {Function File} {@var{zi} =} griddata (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi}, @var{method})
@deftypefnx {Function File} {[@var{xi}, @var{yi}, @var{zi}] =} griddata (@dots{})

Generate a regular mesh from irregular data using interpolation.

The function is defined by @code{@var{z} = f (@var{x}, @var{y})}.  Inputs
@code{@var{x}, @var{y}, @var{z}} are vectors of the same length or
@code{@var{x}, @var{y}} are vectors and @code{@var{z}} is matrix.

The interpolation points are all @code{(@var{xi}, @var{yi})}.  If @var{xi},
@var{yi} are vectors then they are made into a 2-D mesh.

The interpolation method can be @qcode{"nearest"}, @qcode{"cubic"} or
@qcode{"linear"}.  If method is omitted it defaults to @qcode{"linear"}.
@seealso{griddata3, griddatan, delaunay}
@end deftypefn
griddata3
@c griddata3 scripts/geometry/griddata3.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{vi} =} griddata3 (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {Function File} {@var{vi} =} griddata3 (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi}, @var{method})
@deftypefnx {Function File} {@var{vi} =} griddata3 (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi}, @var{method}, @var{options})

Generate a regular mesh from irregular data using interpolation.

The function is defined by @code{@var{v} = f (@var{x}, @var{y}, @var{z})}.
The interpolation points are specified by @var{xi}, @var{yi}, @var{zi}.

The interpolation method can be @qcode{"nearest"} or @qcode{"linear"}.
If method is omitted it defaults to @qcode{"linear"}.

The optional argument @var{options} is passed directly to Qhull when
computing the Delaunay triangulation used for interpolation.  See
@code{delaunayn} for information on the defaults and how to pass different
values.
@seealso{griddata, griddatan, delaunayn}
@end deftypefn
griddatan
@c griddatan scripts/geometry/griddatan.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{yi} =} griddatan (@var{x}, @var{y}, @var{xi})
@deftypefnx {Function File} {@var{yi} =} griddatan (@var{x}, @var{y}, @var{xi}, @var{method})
@deftypefnx {Function File} {@var{yi} =} griddatan (@var{x}, @var{y}, @var{xi}, @var{method}, @var{options})

Generate a regular mesh from irregular data using interpolation.

The function is defined by @code{@var{y} = f (@var{x})}.
The interpolation points are all @var{xi}.

The interpolation method can be @qcode{"nearest"} or @qcode{"linear"}.
If method is omitted it defaults to @qcode{"linear"}.

The optional argument @var{options} is passed directly to Qhull when
computing the Delaunay triangulation used for interpolation.  See
@code{delaunayn} for information on the defaults and how to pass different
values.
@seealso{griddata, griddata3, delaunayn}
@end deftypefn
inpolygon
@c inpolygon scripts/geometry/inpolygon.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{in} =} inpolygon (@var{x}, @var{y}, @var{xv}, @var{yv})
@deftypefnx {Function File} {[@var{in}, @var{on}] =} inpolygon (@var{x}, @var{y}, @var{xv}, @var{yv})

For a polygon defined by vertex points @code{(@var{xv}, @var{yv})}, return
true if the points @code{(@var{x}, @var{y})} are inside (or on the boundary)
of the polygon; Otherwise, return false.

The input variables @var{x} and @var{y}, must have the same dimension.

The optional output @var{on} returns true if the points are exactly on the
polygon edge, and false otherwise.
@seealso{delaunay}
@end deftypefn
rectint
@c rectint scripts/geometry/rectint.m
-*- texinfo -*-
@deftypefn {Function File} {@var{area} =} rectint (@var{a}, @var{b})
Compute area or volume of intersection of rectangles or N-D boxes.

Compute the area of intersection of rectangles in @var{a} and rectangles in
@var{b}.  N-dimensional boxes are supported in which case the volume, or
hypervolume is computed according to the number of dimensions.

2-dimensional rectangles are defined as @code{[xpos ypos width height]}
where xpos and ypos are the position of the bottom left corner.  Higher
dimensions are supported where the coordinates for the minimum value of each
dimension follow the length of the box in that dimension, e.g.,
@code{[xpos ypos zpos kpos @dots{} width height depth k_length @dots{}]}.

Each row of @var{a} and @var{b} define a rectangle, and if both define
multiple rectangles, then the output, @var{area}, is a matrix where the i-th
row corresponds to the i-th row of a and the j-th column corresponds to the
j-th row of b.

@seealso{polyarea}
@end deftypefn
tsearchn
@c tsearchn scripts/geometry/tsearchn.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{idx} =} tsearchn (@var{x}, @var{t}, @var{xi})
@deftypefnx {Function File} {[@var{idx}, @var{p}] =} tsearchn (@var{x}, @var{t}, @var{xi})
Search for the enclosing Delaunay convex hull.

For @code{@var{t} = delaunayn (@var{x})}, finds the index in @var{t}
containing the points @var{xi}.  For points outside the convex hull,
@var{idx} is NaN.

If requested @code{tsearchn} also returns the Barycentric coordinates @var{p}
of the enclosing triangles.
@seealso{delaunay, delaunayn}
@end deftypefn
voronoi
@c voronoi scripts/geometry/voronoi.m
-*- texinfo -*-
@deftypefn  {Function File} {} voronoi (@var{x}, @var{y})
@deftypefnx {Function File} {} voronoi (@var{x}, @var{y}, @var{options})
@deftypefnx {Function File} {} voronoi (@dots{}, "linespec")
@deftypefnx {Function File} {} voronoi (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} voronoi (@dots{})
@deftypefnx {Function File} {[@var{vx}, @var{vy}] =} voronoi (@dots{})
Plot the Voronoi diagram of points @code{(@var{x}, @var{y})}.

The Voronoi facets with points at infinity are not drawn.

The @var{options} argument, which must be a string or cell array of strings,
contains options passed to the underlying qhull command.
See the documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.

If @qcode{"linespec"} is given it is used to set the color and line style of
the plot.

If an axis graphics handle @var{hax} is supplied then the Voronoi diagram is
drawn on the specified axis rather than in a new figure.

If a single output argument is requested then the Voronoi diagram will be
plotted and a graphics handle @var{h} to the plot is returned.

[@var{vx}, @var{vy}] = voronoi (@dots{}) returns the Voronoi vertices
instead of plotting the diagram.

@example
@group
x = rand (10, 1);
y = rand (size (x));
h = convhull (x, y);
[vx, vy] = voronoi (x, y);
plot (vx, vy, "-b", x, y, "o", x(h), y(h), "-g");
legend ("", "points", "hull");
@end group
@end example

@seealso{voronoin, delaunay, convhull}
@end deftypefn
voronoin
@c voronoin scripts/geometry/voronoin.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{C}, @var{F}] =} voronoin (@var{pts})
@deftypefnx {Function File} {[@var{C}, @var{F}] =} voronoin (@var{pts}, @var{options})
Compute N-dimensional Voronoi facets.

The input matrix @var{pts} of size [n, dim] contains n points in a space of
dimension dim.

@var{C} contains the points of the Voronoi facets.  The list @var{F}
contains, for each facet, the indices of the Voronoi points.

An optional second argument, which must be a string or cell array of strings,
contains options passed to the underlying qhull command.
See the documentation for the Qhull library for details
@url{http://www.qhull.org/html/qh-quick.htm#options}.

The default options depend on the dimension of the input:

@itemize
@item 2-D and 3-D: @var{options} = @code{@{"Qbb"@}}

@item 4-D and higher: @var{options} = @code{@{"Qbb", "Qx"@}}
@end itemize

If @var{options} is not present or @code{[]} then the default arguments are
used.  Otherwise, @var{options} replaces the default argument list.
To append user options to the defaults it is necessary to repeat the
default arguments in @var{options}.  Use a null string to pass no arguments.

@seealso{voronoi, convhulln, delaunayn}
@end deftypefn
errordlg
@c errordlg scripts/gui/errordlg.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} errordlg (@var{msg})
@deftypefnx {Function File} {@var{h} =} errordlg (@var{msg}, @var{title})
@deftypefnx {Function File} {@var{h} =} errordlg (@var{msg}, @var{title}, @var{createmode})
Display @var{msg} using an error dialog box.

The message may have multiple lines separated by newline characters ("\n"),
or it may be a cellstr array with one element for each line.

The optional input @var{title} (character string) can be used to set the
dialog caption.  The default title is @qcode{"Error Dialog"}.

The return value is always 1.

Compatibility Note: The optional argument @var{createmode} is accepted for
@sc{matlab} compatibility, but is not implemented.

@seealso{helpdlg, inputdlg, listdlg, msgbox, questdlg, warndlg}
@end deftypefn
guidata
@c guidata scripts/gui/guidata.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{data} =} guidata (@var{h})
@deftypefnx {Function File} {} guidata (@var{h}, @var{data})
Query or set user-custom GUI data.

The GUI data is stored in the figure handle @var{h}.  If @var{h} is not a
figure handle then it's parent figure will be used for storage.

@var{data} must be a single object which means it is usually preferable
for it to be a data container such as a cell array or struct so that
additional data items can be added easily.

@seealso{getappdata, setappdata, get, set, getpref, setpref}
@end deftypefn
guihandles
@c guihandles scripts/gui/guihandles.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{hdata} =} guihandles (@var{h})
@deftypefnx {Function File} {@var{hdata} =} guihandles
Return a structure of object handles for the figure associated with
handle @var{h}.

If no handle is specified the current figure returned by @code{gcf} is used.

The fieldname for each entry of @var{hdata} is taken from the @qcode{"tag"}
property of the graphic object.  If the tag is empty then the handle is not
returned.  If there are multiple graphic objects with the same tag then
the entry in @var{hdata} will be a vector of handles.  @code{guihandles}
includes all possible handles, including those for
which @qcode{"HandleVisibility"} is @qcode{"off"}.
@seealso{guidata, findobj, findall, allchild}
@end deftypefn
helpdlg
@c helpdlg scripts/gui/helpdlg.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} helpdlg (@var{msg})
@deftypefnx {Function File} {@var{h} =} helpdlg (@var{msg}, @var{title})
Display @var{msg} in a help dialog box.

The message may have multiple lines separated by newline characters
("\n"), or it may be a cellstr array with one element for each
line.

The optional input @var{title} (character string) can be used to
set the dialog caption.  The default title is @qcode{"Help Dialog"}.

The return value is always 1.
@seealso{errordlg, inputdlg, listdlg, msgbox, questdlg, warndlg}
@end deftypefn
inputdlg
@c inputdlg scripts/gui/inputdlg.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{cstr} =} inputdlg (@var{prompt})
@deftypefnx {Function File} {@var{cstr} =} inputdlg (@var{prompt}, @var{title})
@deftypefnx {Function File} {@var{cstr} =} inputdlg (@var{prompt}, @var{title}, @var{rowscols})
@deftypefnx {Function File} {@var{cstr} =} inputdlg (@var{prompt}, @var{title}, @var{rowscols}, @var{defaults})
Return user input from a multi-textfield dialog box in a cell array of
strings, or an empty cell array if the dialog is closed by the Cancel
button.

Inputs:

@table @var
@item prompt
A cell array with strings labeling each text field.  This input is required.

@item title
String to use for the caption of the dialog.  The default is
@qcode{"Input Dialog"}.

@item rowscols
Specifies the size of the text fields and can take three forms:

@enumerate
@item a scalar value which defines the number of rows used for each text field.

@item a vector which defines the individual number of rows used for each text field.

@item a matrix which defines the individual number of rows and columns used for each text field.  In the matrix each row describes a single text field.  The first column specifies the number of input rows to use and the second column specifies the text field width.
@end enumerate

@item defaults
A list of default values to place in each text fields.  It must be a cell
array of strings with the same size as @var{prompt}.
@end table
@seealso{errordlg, helpdlg, listdlg, msgbox, questdlg, warndlg}
@end deftypefn
listdlg
@c listdlg scripts/gui/listdlg.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{sel}, @var{ok}] =} listdlg (@var{key}, @var{value}, @dots{})
Return user inputs from a list dialog box in a vector of selection indices
@var{sel} and a flag @var{ok} indicating how the user closed the dialog
box.

The value of @var{ok} is 1 if the user closed the box with the OK button,
otherwise it is 0 and @var{sel} is empty.

The indices in @var{sel} are 1-based.

The arguments are specified in form of @var{key}, @var{value} pairs.
The @qcode{"ListString"} argument pair must be specified.

Valid @var{key} and @var{value} pairs are:

@table @asis
@item @qcode{"ListString"}
a cell array of strings comprising the content of the list.

@item @qcode{"SelectionMode"}
can be either @qcode{"Single"} or @qcode{"Multiple"} (default).

@item @qcode{"ListSize"}
a vector with two elements @var{width} and @var{height} defining the size
of the list field in pixels.  Default is [160 300].

@item @qcode{"InitialValue"}
a vector containing 1-based indices of preselected elements.
Default is 1 (first item).

@item @qcode{"Name"}
a string to be used as the dialog caption.  Default is "".

@item @qcode{"PromptString"}
a cell array of strings to be displayed above the list field.
Default is @{@}.

@item @qcode{"OKString"}
a string used to label the OK button.  Default is @qcode{"OK"}.

@item @qcode{"CancelString"}
a string used to label the Cancel button.  Default is @qcode{"Cancel"}.
@end table

Example:

@example
@group
[sel, ok] = listdlg ("ListString", @{"An item", "another", "yet another"@},
                     "SelectionMode", "Multiple");
if (ok == 1)
  for i = 1:numel (sel)
    disp (sel(i));
  endfor
endif
@end group
@end example

@seealso{menu, errordlg, helpdlg, inputdlg, msgbox, questdlg, warndlg}
@end deftypefn
msgbox
@c msgbox scripts/gui/msgbox.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} msgbox (@var{msg})
@deftypefnx {Function File} {@var{h} =} msgbox (@var{msg}, @var{title})
@deftypefnx {Function File} {@var{h} =} msgbox (@var{msg}, @var{title}, @var{icon})
@deftypefnx {Function File} {@var{h} =} msgbox (@dots{}, @var{createmode})
Display @var{msg} using a message dialog box.

The message may have multiple lines separated by newline characters ("\n"),
or it may be a cellstr array with one element for each line.

The optional input @var{title} (character string) can be used to decorate
the dialog caption.

The optional argument @var{icon} selects a dialog icon.
It can be one of @qcode{"none"} (default), @qcode{"error"}, @qcode{"help"},
or @qcode{"warn"}.

The return value is always 1.

Compatibility Note: The optional argument @var{createmode} is accepted for
@sc{matlab} compatibility, but is not implemented.

@seealso{errordlg, helpdlg, inputdlg, listdlg, questdlg, warndlg}
@end deftypefn
questdlg
@c questdlg scripts/gui/questdlg.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{btn} =} questdlg (@var{msg})
@deftypefnx {Function File} {@var{btn} =} questdlg (@var{msg}, @var{title})
@deftypefnx {Function File} {@var{btn} =} questdlg (@var{msg}, @var{title}, @var{default})
@deftypefnx {Function File} {@var{btn} =} questdlg (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{default})
@deftypefnx {Function File} {@var{btn} =} questdlg (@var{msg}, @var{title}, @var{btn1}, @var{btn2}, @var{btn3}, @var{default})
Display @var{msg} using a question dialog box and return the caption of
the activated button.

The dialog may contain two or three buttons which will all close the dialog.

The message may have multiple lines separated by newline characters ("\n"),
or it may be a cellstr array with one element for each line.

The optional @var{title} (character string) can be used to decorate the
dialog caption.

The string @var{default} identifies the default button, which is activated
by pressing the @key{ENTER} key.  It must match one of the strings given
in @var{btn1}, @var{btn2}, or @var{btn3}.

If only @var{msg} and @var{title} are specified, three buttons with the
default captions @qcode{"Yes"}, @qcode{"No"}, and @qcode{"Cancel"} are used.

If only two button captions, @var{btn1} and @var{btn2}, are specified the
dialog will have only these two buttons.

@seealso{errordlg, helpdlg, inputdlg, listdlg, warndlg}
@end deftypefn
uicontextmenu
@c uicontextmenu scripts/gui/uicontextmenu.m
-*- texinfo -*-
@deftypefn {Function File} {@var{hui} =} uicontextmenu (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{hui} =} uicontextmenu (@var{h}, @var{property}, @var{value}, @dots{})

Create a uicontextmenu object and return a handle to it.

If @var{h} is omitted then a uicontextmenu for the current figure is
created. If no figure is available, a new figure is created first. 

If @var{h} is given then a uicontextmenu relative to @var{h} is created. 

Any provided property value pairs will override the default values of the created 
uicontextmenu object.

Examples:

@example
@group
% create figure and uicontextmenu
f = figure;
c = uicontextmenu (f);

% create menus in the context menu
m1 = uimenu ("parent",c,"label","Menu item 1","callback","disp('menu item 1')");
m2 = uimenu ("parent",c,"label","Menu item 2","callback","disp('menu item 2')");

% set the context menu for the figure
set (f, "uicontextmenu", c);
@end group
@end example
@seealso{figure, uimenu}
@end deftypefn
uicontrol
@c uicontrol scripts/gui/uicontrol.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{hui} =} uicontrol (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{hui} =} uicontrol (@var{parent}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} uicontrol (@var{h})

Create a uicontrol object and return a handle to it.

uicontrols are used to create simple interactive controls such as push buttons, checkboxes, edit and list controls.

If @var{parent} is omitted then a uicontrol for the current figure is
created. If no figure is available, a new figure is created first. 

If @var{parent} is given then a uicontrol relative to @var{parent} is created. 

Any provided property value pairs will override the default values of the created 
uicontrol object. 

Control of the type of uicontrol created is through the use of the @var{style} property.
If no style property is provided, a push button will be created.

Valid styles for uicontrol are:

@table @asis
@item @qcode{"checkbox"}
Create a checkbox control that allows user on/off selection.

@item @qcode{"edit"}
Create a edit control that allows user input of single or multiple lines of text.

@item @qcode{"listbox"}
Create a listbox control that displays a lit of items and allows user slelection of 
single or multiple items.

@item @qcode{"popupmenu"}
Create a popupmenu control that displays a list of options that can be selected 
when the user clicks on the control.

@item @qcode{"pushbutton"}
Create a push button control that allows user to press to cause an action.

@item @qcode{"radiobutton"}
Create a radio button control intended to be used for mutually exclusive input in a group of
of radiobutton controls.

@item @qcode{"slider"}
Create a slider control that allows user selection from a range of values by sliding 
knob on the control.

@item @qcode{"text"}
Create a static text control to display single or multiple lines of text.

@item @qcode{"togglebutton"}
Create a toggle button control that appears like a push button but allows the user to 
select between two states.

@end table

Examples:

@example
@group
% create figure and panel on it
f = figure;
% create a button (default style)
b1 = uicontrol (f, "string", "A Button", "position",[10 10 150 40]);
% create an edit control
e1 = uicontrol (f, "style", "edit", "string", "editable text", "position",[10 60 300 40]);
% create a checkbox
c1 = uicontrol (f, "style", "checkbox", "string", "a checkbox", "position",[10 120 150 40]);
@end group
@end example
@seealso{figure, uipanel}
@end deftypefn
uigetdir
@c uigetdir scripts/gui/uigetdir.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{dirname} =} uigetdir ()
@deftypefnx {Function File} {@var{dirname} =} uigetdir (@var{init_path})
@deftypefnx {Function File} {@var{dirname} =} uigetdir (@var{init_path}, @var{dialog_name})
Open a GUI dialog for selecting a directory.

If @var{init_path} is not given the current working directory is used.

@var{dialog_name} may be used to customize the dialog title.
@seealso{uigetfile, uiputfile}
@end deftypefn
uigetfile
@c uigetfile scripts/gui/uigetfile.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uigetfile ()
@deftypefnx {Function File} {[@dots{}] =} uigetfile (@var{flt})
@deftypefnx {Function File} {[@dots{}] =} uigetfile (@var{flt}, @var{dialog_name})
@deftypefnx {Function File} {[@dots{}] =} uigetfile (@var{flt}, @var{dialog_name}, @var{default_file})
@deftypefnx {Function File} {[@dots{}] =} uigetfile (@dots{}, "Position", [@var{px} @var{py}])
@deftypefnx {Function File} {[@dots{}] =} uigetfile (@dots{}, "MultiSelect", @var{mode})

Open a GUI dialog for selecting a file and return the filename @var{fname},
the path to this file @var{fpath}, and the filter index @var{fltidx}.

@var{flt} contains a (list of) file filter string(s) in one of the following
formats:

@table @asis
@item @qcode{"/path/to/filename.ext"}
If a filename is given then the file extension is extracted and used as
filter.  In addition, the path is selected as current path and the filename
is selected as default file.  Example: @code{uigetfile ("myfun.m")}

@item A single file extension @qcode{"*.ext"}
Example: @code{uigetfile ("*.ext")}

@item A 2-column cell array
containing a file extension in the first column and a brief description in
the second column.
Example: @code{uigetfile (@{"*.ext", "My Description";"*.xyz",
"XYZ-Format"@})}

The filter string can also contain a semicolon separated list of filter
extensions.
Example: @code{uigetfile (@{"*.gif;*.png;*.jpg", "Supported Picture
Formats"@})}
@end table

@var{dialog_name} can be used to customize the dialog title.

If @var{default_file} is given then it will be selected in the GUI dialog.
If, in addition, a path is given it is also used as current path.

The screen position of the GUI dialog can be set using the
@qcode{"Position"} key and a 2-element vector containing the pixel
coordinates.  Two or more files can be selected when setting the
@qcode{"MultiSelect"} key to @qcode{"on"}.  In that case @var{fname} is a
cell array containing the files.
@seealso{uiputfile, uigetdir}
@end deftypefn
uimenu
@c uimenu scripts/gui/uimenu.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{hui} =} uimenu (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{hui} =} uimenu (@var{h}, @var{property}, @var{value}, @dots{})
Create a uimenu object and return a handle to it.

If @var{h} is omitted then a top-level menu for the current figure is
created.  If @var{h} is given then a submenu relative to @var{h} is created.

uimenu objects have the following specific properties:

@table @asis
@item @qcode{"accelerator"}
A string containing the key combination together with CTRL to execute this
menu entry (e.g., @qcode{"x"} for CTRL+x).

@item @qcode{"callback"}
Is the function called when this menu entry is executed.  It can be either a
function string (e.g., @qcode{"myfun"}), a function handle (e.g., @@myfun)
or a cell array containing the function handle and arguments for the
callback function (e.g., @{@@myfun, arg1, arg2@}).

@item @qcode{"checked"}
Can be set @qcode{"on"} or @qcode{"off"}.  Sets a mark at this menu entry.

@item @qcode{"enable"}
Can be set @qcode{"on"} or @qcode{"off"}.  If disabled the menu entry
cannot be selected and it is grayed out.

@item @qcode{"foregroundcolor"}
A color value setting the text color for this menu entry.

@item @qcode{"label"}
A string containing the label for this menu entry.  A @qcode{"&"}-symbol
can be used to mark the @qcode{"accelerator"} character (e.g.,
@nospell{@qcode{"E&xit"}})

@item @qcode{"position"}
An scalar value containing the relative menu position.  The entry with the
lowest value is at the first position starting from left or top.

@item @qcode{"separator"}
Can be set @qcode{"on"} or @qcode{"off"}.  If enabled it draws a separator
line above the current position.  It is ignored for top level entries.

@end table

Examples:

@example
@group
f = uimenu ("label", "&File", "accelerator", "f");
e = uimenu ("label", "&Edit", "accelerator", "e");
uimenu (f, "label", "Close", "accelerator", "q", ...
           "callback", "close (gcf)");
uimenu (e, "label", "Toggle &Grid", "accelerator", "g", ...
           "callback", "grid (gca)");
@end group
@end example
@seealso{figure}
@end deftypefn
uipanel
@c uipanel scripts/gui/uipanel.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{hui} =} uipanel (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{hui} =} uipanel (@var{parent}, "@var{property}, @var{value}, @dots{})

Create a uipanel object and return a handle to it.

uipanels are used as containers to group other uicontrol objects.

If @var{parent} is omitted then a uipanel for the current figure is
created. If no figure is available, a new figure is created first. 

If @var{parent} is given then a uipanel relative to @var{parent} is created. 

Any provided property value pairs will override the default values of the created 
uipanel object.

Examples:

@example
@group
% create figure and panel on it
f = figure;
p = uipanel ("title", "Panel Title", "position", [.25 .25 .5 .5]);

% add two buttons to the panel
b1 = uicontrol ("parent", p, "string", "A Button", "position",[18 10 150 36]);
b2 = uicontrol ("parent", p, "string", "Another Button", "position",[18 60 150 36]);

@end group
@end example
@seealso{figure, uicontrol}
@end deftypefn
uipushtool
@c uipushtool scripts/gui/uipushtool.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{hui} =} uipushtool (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{hui} =} uipushtool (@var{parent}, @var{property}, @var{value}, @dots{})

Create a uipushtool object and return a handle to it.

uipushtools are buttons that appear on a figure toolbar. The button is created with a border that
is shown when the user hovers over the button. An image can be set using the cdata property.

If @var{parent} is omitted then a uipushtool for the current figure is
created. If no figure is available, a new figure is created first.  If a figure is
available, but does not contain a uitoolbar, a uitoolbar will be created.

If @var{parent} is given then a uipushtools is created on the @var{parent} uitoolbar. 

Any provided property value pairs will override the default values of the created 
uipushtool object.

Examples:

@example
@group
% create figure without a default toolbar
f = figure ("toolbar", "none");
% create empty toolbar
t = uitoolbar (f);
% create a 19x19x3 black square
img=zeros(19,19,3);
% add pushtool button to toolbar
b = uipushtool (t, "cdata", img);
@end group
@end example
@seealso{figure, uitoolbar, uitoggletool}
@end deftypefn
uiputfile
@c uiputfile scripts/gui/uiputfile.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile ()
@deftypefnx {Function File} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt})
@deftypefnx {Function File} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt}, @var{dialog_name})
@deftypefnx {Function File} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt}, @var{dialog_name}, @var{default_file})
Open a GUI dialog for selecting a file.

@var{flt} contains a (list of) file filter string(s) in one of the following
formats:

@table @asis
@item @qcode{"/path/to/filename.ext"}
If a filename is given the file extension is extracted and used as filter.
In addition the path is selected as current path and the filename is
selected as default file.  Example: @code{uiputfile ("myfun.m")}

@item @qcode{"*.ext"}
A single file extension.
Example: @code{uiputfile ("*.ext")}

@item @code{@{"*.ext", "My Description"@}}
A 2-column cell array containing the file extension in the 1st column and
a brief description in the 2nd column.
Example: @code{uiputfile (@{"*.ext","My Description";"*.xyz",
"XYZ-Format"@})}
@end table

The filter string can also contain a semicolon separated list of filter
extensions.
Example: @code{uiputfile (@{"*.gif;*.png;*.jpg",
"Supported Picture Formats"@})}

@var{dialog_name} can be used to customize the dialog title.
If @var{default_file} is given it is preselected in the GUI dialog.
If, in addition, a path is given it is also used as current path.
@seealso{uigetfile, uigetdir}
@end deftypefn
uiresume
@c uiresume scripts/gui/uiresume.m
-*- texinfo -*-
@deftypefn {Function File} {} uiresume (@var{h})
Resume program execution suspended with @code{uiwait}.

The handle @var{h} must be the same as the on specified in @code{uiwait}.
If the handle is invalid or there is no @code{uiwait} call pending for the
figure with handle @var{h}, this function does nothing.
@seealso{uiwait}
@end deftypefn
uitoggletool
@c uitoggletool scripts/gui/uitoggletool.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{hui} =} uitoggletool (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{hui} =} uitoggletool (@var{parent}, @var{property}, @var{value}, @dots{})

Create a uitoggletool object and return a handle to it.

uitoggletool are togglebuttons that appear on a figure toolbar. The button is created with a border that
is shown when the user hovers over the button. An image can be set using the cdata property.

If @var{parent} is omitted then a uitoggletool for the current figure is
created. If no figure is available, a new figure is created first.  If a figure is
available, but does not contain a uitoolbar, a uitoolbar will be created.

If @var{parent} is given then a uitoggletool is created on the @var{parent} uitoolbar. 

Any provided property value pairs will override the default values of the created 
uitoggletool object.

Examples:

@example
@group
% create figure without a default toolbar
f = figure ("toolbar", "none");
% create empty toolbar
t = uitoolbar (f);
% create a 19x19x3 black square
img=zeros(19,19,3);
% add uitoggletool button to toolbar
b = uitoggletool (t, "cdata", img);
@end group
@end example
@seealso{figure, uitoolbar, uipushtool}
@end deftypefn
uitoolbar
@c uitoolbar scripts/gui/uitoolbar.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{hui} =} uitoolbar (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{hui} =} uitoolbar (@var{parent}, @var{property}, @var{value}, @dots{})

Create a uitoolbar object and return a handle to it. A uitoolbar displays uitoggletool and uipushtool buttons.

If @var{parent} is omitted then a uitoolbar for the current figure is
created. If no figure is available, a new figure is created first. 

If @var{parent} is given then a uitoolbar relative to @var{parent} is created. 

Any provided property value pairs will override the default values of the created 
uitoolbar object. 

Examples:

@example
@group
% create figure without a default toolbar 
f = figure ("toolbar", "none");
% create empty toolbar
t = uitoolbar (f);
@end group
@end example
@seealso{figure, uitoggletool, uipushtool}
@end deftypefn
uiwait
@c uiwait scripts/gui/uiwait.m
-*- texinfo -*-
@deftypefn  {Function File} {} uiwait
@deftypefnx {Function File} {} uiwait (@var{h})
@deftypefnx {Function File} {} uiwait (@var{h}, @var{timeout})
Suspend program execution until the figure with handle @var{h} is deleted
or @code{uiresume} is called.

When no figure handle is specified this function uses the current figure.
If the figure handle is invalid or there is no current figure, this
functions returns immediately.

When specified, @var{timeout} defines the number of seconds to wait
for the figure deletion or the @code{uiresume} call.  The timeout value
must be at least 1.  If a smaller value is specified, a warning is issued
and a timeout value of 1 is used instead.  If a non-integer value is
specified, it is truncated towards 0.  If @var{timeout} is not specified,
the program execution is suspended indefinitely.
@seealso{uiresume, waitfor}
@end deftypefn
waitbar
@c waitbar scripts/gui/waitbar.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} waitbar (@var{frac})
@deftypefnx {Function File} {@var{h} =} waitbar (@var{frac}, @var{msg})
@deftypefnx {Function File} {@var{h} =} waitbar (@dots{}, "FigureProperty", "Value", @dots{})
@deftypefnx {Function File} {} waitbar (@var{frac})
@deftypefnx {Function File} {} waitbar (@var{frac}, @var{hwbar})
@deftypefnx {Function File} {} waitbar (@var{frac}, @var{hwbar}, @var{msg})
Return a handle @var{h} to a new waitbar object.

The waitbar is filled to fraction @var{frac} which must be in the range
[0, 1].

The optional message @var{msg} is centered and displayed above the waitbar.

The appearance of the waitbar figure window can be configured by passing
property/value pairs to the function.

When called with a single input the current waitbar, if it exists, is
updated to the new value @var{frac}.  If there are multiple outstanding
waitbars they can be updated individually by passing the handle @var{hwbar}
of the specific waitbar to modify.
@end deftypefn
waitforbuttonpress
@c waitforbuttonpress scripts/gui/waitforbuttonpress.m
-*- texinfo -*-
@deftypefn  {Function File} {} waitforbuttonpress ()
@deftypefnx {Function File} {@var{b} =} waitforbuttonpress ()
Wait for mouse click or key press over the current figure window.

The return value of @var{b} is 0 if a mouse button was pressed or 1 if a
key was pressed.
@seealso{waitfor, ginput, kbhit}
@end deftypefn
warndlg
@c warndlg scripts/gui/warndlg.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} warndlg (@var{msg})
@deftypefnx {Function File} {@var{h} =} warndlg (@var{msg}, @var{title})
@deftypefnx {Function File} {@var{h} =} warndlg (@var{msg}, @var{title}, @var{createmode})
Display @var{msg} using a warning dialog box.

The message may have multiple lines separated by newline characters ("\n"),
or it may be a cellstr array with one element for each line.

The optional input @var{title} (character string) can be used to set the
dialog caption.  The default title is @qcode{"Warning Dialog"}.

The return value is always 1.

Compatibility Note: The optional argument @var{createmode} is accepted for
@sc{matlab} compatibility, but is not implemented.

@seealso{helpdlg, inputdlg, listdlg, questdlg}
@end deftypefn
__gripe_missing_component__
@c __gripe_missing_component__ scripts/help/__gripe_missing_component__.m
-*- texinfo -*-
@deftypefn {Function File} {} __gripe_missing_component__ (@var{caller}, @var{component})
Undocumented internal function.
@end deftypefn
__makeinfo__
@c __makeinfo__ scripts/help/__makeinfo__.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{retval}, @var{status}] =} __makeinfo__ (@var{text}, @var{output_type})
@deftypefnx {Function File} {[@var{retval}, @var{status}] =} __makeinfo__ (@var{text}, @var{output_type}, @var{see_also})
Undocumented internal function.
@end deftypefn
__unimplemented__
@c __unimplemented__ scripts/help/__unimplemented__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{txt} =} __unimplemented__ (@var{fcn})
Return specific help text for the unimplemented function @var{fcn}.

This is usually a suggestion for an existing compatible function to use in
place of @var{fcn}.

This function is not called by users, but by the Octave interpreter when it
fails to recognize an input string as a valid function name.  See
@code{missing_function_hook} for using a different handler for this event.
@seealso{missing_function_hook}
@end deftypefn
doc
@c doc scripts/help/doc.m
-*- texinfo -*-
@deftypefn  {Command} {} doc @var{function_name}
@deftypefnx {Command} {} doc
Display documentation for the function @var{function_name} directly from an
online version of the printed manual, using the GNU Info browser.

If invoked without an argument, the manual is shown from the beginning.

For example, the command @kbd{doc rand} starts the GNU Info browser at the
@code{rand} node in the online version of the manual.

Once the GNU Info browser is running, help for using it is available using
the command @kbd{C-h}.
@seealso{help}
@end deftypefn
doc_cache_create
@c doc_cache_create scripts/help/doc_cache_create.m
-*- texinfo -*-
@deftypefn  {Function File} {} doc_cache_create (@var{out_file}, @var{directory})
@deftypefnx {Function File} {} doc_cache_create (@var{out_file})
@deftypefnx {Function File} {} doc_cache_create ()
Generate documentation cache for all functions in @var{directory}.

A documentation cache is generated for all functions in @var{directory}
which may be a single string or a cell array of strings.  The cache is used
to speed up the function @code{lookfor}.

The cache is saved in the file @var{out_file} which defaults to the value
@file{doc-cache} if not given.

If no directory is given (or it is the empty matrix), a cache for built-in
operators, etc. is generated.

@seealso{doc_cache_file, lookfor, path}
@end deftypefn
get_first_help_sentence
@c get_first_help_sentence scripts/help/get_first_help_sentence.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{text} =} get_first_help_sentence (@var{name})
@deftypefnx {Function File} {@var{text} =} get_first_help_sentence (@var{name}, @var{max_len})
@deftypefnx {Function File} {[@var{text}, @var{status}] =} get_first_help_sentence (@dots{})
Return the first sentence of a function's help text.

The first sentence is defined as the text after the function declaration
until either the first period (".") or the first appearance of two
consecutive newlines ("\n\n").  The text is truncated to a maximum length of
@var{max_len}, which defaults to 80.

The optional output argument @var{status} returns the status reported by
@code{makeinfo}.  If only one output argument is requested, and @var{status}
is nonzero, a warning is displayed.

As an example, the first sentence of this help text is

@example
@group
get_first_help_sentence ("get_first_help_sentence")
@print{} ans = Return the first sentence of a function's help text.
@end group
@end example
@end deftypefn
help
@c help scripts/help/help.m
-*- texinfo -*-
@deftypefn  {Command} {} help @var{name}
@deftypefnx {Command} {} help @code{--list}
@deftypefnx {Command} {} help @code{.}
@deftypefnx {Command} {} help
Display the help text for @var{name}.

For example, the command @kbd{help help} prints a short message describing
the @code{help} command.

Given the single argument @code{--list}, list all operators, keywords,
built-in functions, and loadable functions available in the current session
of Octave.

Given the single argument @code{.}, list all operators available in the
current session of Octave.

If invoked without any arguments, @code{help} display instructions on how to
access help from the command line.

The help command can provide information about most operators, for example
@code{help +}, but not the comma and semicolon characters which are used
by the Octave interpreter as command separators.  For help on either of
these type @kbd{help comma} or @kbd{help semicolon}.
@seealso{doc, lookfor, which, info}
@end deftypefn
lookfor
@c lookfor scripts/help/lookfor.m
-*- texinfo -*-
@deftypefn  {Command} {} lookfor @var{str}
@deftypefnx {Command} {} lookfor -all @var{str}
@deftypefnx {Function File} {[@var{fcn}, @var{help1str}] =} lookfor (@var{str})
@deftypefnx {Function File} {[@var{fcn}, @var{help1str}] =} lookfor ("-all", @var{str})
Search for the string @var{str} in the documentation of all functions in the
current function search path.

By default, @code{lookfor} looks for @var{str} in just the first sentence of
the help string for each function found.  The entire help text of each
function can be searched by using the @qcode{"-all"} argument.  All searches
are case insensitive.

When called with no output arguments, @code{lookfor} prints the list of
matching functions to the terminal.  Otherwise, the output argument
@var{fcns} contains the function names and @var{help1str} contains the first
sentence from the help string of each function.

Programming Note: The ability of @code{lookfor} to correctly identify the
first sentence of the help text is dependent on the format of the function's
help.  All Octave core functions are correctly formatted, but the same can
not be guaranteed for external packages and user-supplied functions.
Therefore, the use of the @qcode{"-all"} argument may be necessary to find
related functions that are not a part of Octave.

The speed of lookup is greatly enhanced by having a cached documentation
file.  See @code{doc_cache_create} for more information.
@seealso{help, doc, which, path, doc_cache_create}
@end deftypefn
print_usage
@c print_usage scripts/help/print_usage.m
-*- texinfo -*-
@deftypefn  {Function File} {} print_usage ()
@deftypefnx {Function File} {} print_usage (@var{name})
Print the usage message for the function @var{name}.

When called with no input arguments the @code{print_usage} function displays
the usage message of the currently executing function.
@seealso{help}
@end deftypefn
type
@c type scripts/help/type.m
-*- texinfo -*-
@deftypefn  {Command} {} type @var{name} @dots{}
@deftypefnx {Command} {} type -q @var{name} @dots{}
@deftypefnx {Function File} {text =} type ("@var{name}", @dots{})
Display the contents of @var{name} which may be a file, function (m-file),
variable, operator, or keyword.

@code{type} normally prepends a header line describing the category of
@var{name} such as function or variable; The @option{-q} option suppresses
this behavior.

If no output variable is used the contents are displayed on screen.
Otherwise, a cell array of strings is returned, where each element
corresponds to the contents of each requested function.
@end deftypefn
which
@c which scripts/help/which.m
-*- texinfo -*-
@deftypefn {Command} {} which name @dots{}
Display the type of each @var{name}.

If @var{name} is defined from a function file, the full name of the file is
also displayed.
@seealso{help, lookfor}
@end deftypefn
autumn
@c autumn scripts/image/autumn.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} autumn ()
@deftypefnx {Function File} {@var{map} =} autumn (@var{n})
Create color colormap.
This colormap ranges from red through orange to yellow.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
bone
@c bone scripts/image/bone.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} bone ()
@deftypefnx {Function File} {@var{map} =} bone (@var{n})
Create color colormap.  This colormap varies from black to white with
gray-blue shades.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
brighten
@c brighten scripts/image/brighten.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map_out} =} brighten (@var{beta})
@deftypefnx {Function File} {@var{map_out} =} brighten (@var{map}, @var{beta})
@deftypefnx {Function File} {@var{map_out} =} brighten (@var{h}, @var{beta})
@deftypefnx {Function File} {} brighten (@dots{})
Brighten or darken a colormap.

The argument @var{beta} must be a scalar between -1 and 1, where a negative
value darkens and a positive value brightens the colormap.

If the @var{map} argument is omitted, the function is applied to the current
colormap.

The first argument can also be a valid graphics handle @var{h}, in which
case @code{brighten} is applied to the colormap associated with this handle.

If no output is specified then the result is written to the current colormap.
@seealso{colormap, contrast}
@end deftypefn
cmpermute
@c cmpermute scripts/image/cmpermute.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{Y}, @var{newmap}] =} cmpermute (@var{X}, @var{map})
@deftypefnx {Function File} {[@var{Y}, @var{newmap}] =} cmpermute (@var{X}, @var{map}, @var{index})
Reorder colors in a colormap.

When called with only two arguments, @code{cmpermute} randomly rearranges
the colormap @var{map} and returns a new colormap @var{newmap}.  It also
returns the indexed image @var{Y} which is the equivalent of the original
input image @var{X} when displayed using @var{newmap}.

When called with an optional third argument the order of colors in the new
colormap is defined by @var{index}.

@strong{Caution:} @code{index} should not have repeated elements or the
function will fail.

@end deftypefn
cmunique
@c cmunique scripts/image/cmunique.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{Y}, @var{newmap}] =} cmunique (@var{X}, @var{map})
@deftypefnx {Function File} {[@var{Y}, @var{newmap}] =} cmunique (@var{RGB})
@deftypefnx {Function File} {[@var{Y}, @var{newmap}] =} cmunique (@var{I})
Convert an input image @var{X} to an ouput indexed image @var{Y} which uses
the smallest colormap possible @var{newmap}.

When the input is an indexed image (@var{X} with colormap @var{map}) the
output is a colormap @var{newmap} from which any repeated rows have been
eliminated.  The output image, @var{Y}, is the original input image with
the indices adjusted to match the new, possibly smaller, colormap.

When the input is an RGB image (an @nospell{MxNx3} array), the output
colormap will contain one entry for every unique color in the original image.
In the worst case the new map could have as many rows as the number of
pixels in the original image.

When the input is a grayscale image @var{I}, the output colormap will
contain one entry for every unique intensity value in the original image.
In the worst case the new map could have as many rows as the number of
pixels in the original image.

Implementation Details:

@var{newmap} is always an Mx3 matrix, even if the input image is
an intensity grayscale image @var{I} (all three RGB planes are
assigned the same value).

The output image is of class uint8 if the size of the new colormap is
less than or equal to 256.  Otherwise, the output image is of class double.

@seealso{rgb2ind, gray2ind}
@end deftypefn
colorcube
@c colorcube scripts/image/colorcube.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} colorcube ()
@deftypefnx {Function File} {@var{map} =} colorcube (@var{n})
Create color colormap.  This colormap is composed of as many equally
spaced colors (not grays) in the RGB color space as possible.

If there are not a perfect number @var{n} of regularly spaced colors then the
remaining entries in the colormap are gradients of pure red, green, blue,
and gray.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
colormap
@c colormap scripts/image/colormap.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{cmap} =} colormap ()
@deftypefnx {Function File} {@var{cmap} =} colormap (@var{map})
@deftypefnx {Function File} {@var{cmap} =} colormap ("default")
@deftypefnx {Function File} {@var{cmap} =} colormap ("@var{map_name}")
@deftypefnx {Function File} {@var{cmap} =} colormap (@var{hax}, @dots{})
@deftypefnx {Command} {} colormap @var{map_name}
@deftypefnx {Function File} {@var{cmaps} =} colormap ("list")
@deftypefnx {Function File} {} colormap ("register", "@var{name}")
@deftypefnx {Function File} {} colormap ("unregister", "@var{name}")
Query or set the current colormap.

With no input arguments, @code{colormap} returns the current color map.

@code{colormap (@var{map})} sets the current colormap to @var{map}.  The
colormap should be an @var{n} row by 3 column matrix.  The columns
contain red, green, and blue intensities respectively.  All entries
must be between 0 and 1 inclusive.  The new colormap is returned.

@code{colormap ("default")} restores the default colormap (the
@code{jet} map with 64 entries).  The default colormap is returned.

The map may also be specified by a string, @qcode{"@var{map_name}"}, where
@var{map_name} is the name of a function that returns a colormap.

If the first argument @var{hax} is an axes handle, then the colormap for
the parent figure of @var{hax} is queried or set.

For convenience, it is also possible to use this function with the
command form, @code{colormap @var{map_name}}.

@code{colormap ("list")} returns a cell array with all of the available
colormaps.  The options @qcode{"register"} and @qcode{"unregister"}
add or remove the colormap @var{name} from this list.

@seealso{jet}
@end deftypefn
contrast
@c contrast scripts/image/contrast.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{cmap} =} contrast (@var{x})
@deftypefnx {Function File} {@var{cmap} =} contrast (@var{x}, @var{n})
Return a gray colormap that maximizes the contrast in an image.

The returned colormap will have @var{n} rows.  If @var{n} is not defined
then the size of the current colormap is used.
@seealso{colormap, brighten}
@end deftypefn
cool
@c cool scripts/image/cool.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} cool ()
@deftypefnx {Function File} {@var{map} =} cool (@var{n})
Create color colormap.  The colormap varies from cyan to magenta.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
copper
@c copper scripts/image/copper.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} copper ()
@deftypefnx {Function File} {@var{map} =} copper (@var{n})
Create color colormap.  This colormap varies from black to a light copper
tone.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
cubehelix
@c cubehelix scripts/image/cubehelix.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} cubehelix ()
@deftypefnx {Function File} {@var{map} =} cubehelix (@var{n})
Create cubehelix colormap.

This colormap varies from black to white going though blue, green, and red
tones while maintaining a monotonically increasing perception of intensity.
This is achieved by transversing a color cube from black to white through
a helix, hence the name cubehelix, while taking into account the perceived
brightness of each channel according to the NTSC specifications from 1953.

@example
rgbplot (cubehelix (256))
@end example

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.

Reference: Green, D. A., 2011,
@cite{"A @nospell{colour} scheme for the display of astronomical intensity
images"}, Bulletin of the Astronomical Society of India, 39, 289.

@seealso{colormap}
@end deftypefn
flag
@c flag scripts/image/flag.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} flag ()
@deftypefnx {Function File} {@var{map} =} flag (@var{n})
Create color colormap.  This colormap cycles through red, white, blue, and
black with each index change.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
gray
@c gray scripts/image/gray.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} gray ()
@deftypefnx {Function File} {@var{map} =} gray (@var{n})
Create gray colormap.  This colormap varies from black to white with shades
of gray.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
gray2ind
@c gray2ind scripts/image/gray2ind.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{img} =} gray2ind (@var{I})
@deftypefnx {Function File} {@var{img} =} gray2ind (@var{I}, @var{n})
@deftypefnx {Function File} {@var{img} =} gray2ind (@var{BW})
@deftypefnx {Function File} {@var{img} =} gray2ind (@var{BW}, @var{n})
@deftypefnx {Function File} {[@var{img}, @var{map}] =} gray2ind (@dots{})
Convert a grayscale or binary intensity image to an indexed image.

The indexed image will consist of @var{n} different intensity values.
If not given @var{n} defaults to 64 for grayscale images or 2 for binary
black and white images.

The output @var{img} is of class uint8 if @var{n} is less than or equal to
256; Otherwise the return class is uint16.
@seealso{ind2gray, rgb2ind}
@end deftypefn
hot
@c hot scripts/image/hot.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} hot ()
@deftypefnx {Function File} {@var{map} =} hot (@var{n})
Create color colormap.  This colormap ranges from black through dark red,
red, orange, yellow, to white.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
hsv
@c hsv scripts/image/hsv.m
-*- texinfo -*-
@deftypefn {Function File} {} hsv (@var{n})
Create color colormap.  This colormap begins with red, changes through
yellow, green, cyan, blue, and magenta, before returning to red.

It is useful for displaying periodic functions.  The map is obtained by
linearly varying the hue through all possible values while keeping constant
maximum saturation and value.  The equivalent code is
@code{hsv2rgb ([(0:N-1)'/N, ones(N,2)])}.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
hsv2rgb
@c hsv2rgb scripts/image/hsv2rgb.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{rgb_map} =} hsv2rgb (@var{hsv_map})
@deftypefnx {Function File} {@var{rgb_img} =} hsv2rgb (@var{hsv_img})
Transform a colormap or image from hue-saturation-value (HSV) space to
red-green-blue (RGB) space.

A color in HSV space is represented by hue, saturation and value
(brightness) levels.  Value gives the amount of light in the color.  Hue
describes the dominant wavelength.  Saturation is the amount of hue mixed
into the color.

A color in the RGB space consists of red, green, and blue intensities.
@seealso{rgb2hsv, ind2rgb, ntsc2rgb}
@end deftypefn
iscolormap
@c iscolormap scripts/image/iscolormap.m
-*- texinfo -*-
@deftypefn {Function File} {} iscolormap (@var{cmap})
Return true if @var{cmap} is a colormap.

A colormap is a real matrix with @var{n} rows and 3 columns.  Each row
represents a single color.  The columns contain red, green, and blue
intensities respectively.  All entries must be between 0 and 1 inclusive.
@seealso{colormap, rgbplot}
@end deftypefn
image
@c image scripts/image/image.m
-*- texinfo -*-
@deftypefn  {Function File} {} image (@var{img})
@deftypefnx {Function File} {} image (@var{x}, @var{y}, @var{img})
@deftypefnx {Function File} {} image (@dots{}, "@var{prop}", @var{val}, @dots{})
@deftypefnx {Function File} {} image ("@var{prop1}", @var{val1}, @dots{})
@deftypefnx {Function File} {@var{h} =} image (@dots{})
Display a matrix as an indexed color image.

The elements of @var{img} are indices into the current colormap.

@var{x} and @var{y} are optional 2-element vectors, @w{@code{[min, max]}},
which specify the range for the axis labels.  If a range is specified as
@w{@code{[max, min]}} then the image will be reversed along that axis.  For
convenience, @var{x} and @var{y} may be specified as N-element vectors
matching the length of the data in @var{img}.  However, only the first and
last elements will be used to determine the axis limits.
@strong{Warning:} @var{x} and @var{y} are ignored when using gnuplot 4.0
or earlier.

Multiple property/value pairs may be specified for the image object, but
they must appear in pairs.

The optional return value @var{h} is a graphics handle to the image.

Implementation Note: The origin (0, 0) for images is located in the
upper left.  For ordinary plots, the origin is located in the lower
left.  Octave handles this inversion by plotting the data normally,
and then reversing the direction of the y-axis by setting the
@code{ydir} property to @qcode{"reverse"}.  This has implications whenever
an image and an ordinary plot need to be overlaid.  The recommended
solution is to display the image and then plot the reversed ydata
using, for example, @code{flipud (ydata)}.

Calling Forms: The @code{image} function can be called in two forms:
High-Level and Low-Level.  When invoked with normal options, the High-Level
form is used which first calls @code{newplot} to prepare the graphic figure
and axes.  When the only inputs to @code{image} are property/value pairs
the Low-Level form is used which creates a new instance of an image object
and inserts it in the current axes.
@seealso{imshow, imagesc, colormap}
@end deftypefn
imagesc
@c imagesc scripts/image/imagesc.m
-*- texinfo -*-
@deftypefn  {Function File} {} imagesc (@var{img})
@deftypefnx {Function File} {} imagesc (@var{x}, @var{y}, @var{img})
@deftypefnx {Function File} {} imagesc (@dots{}, @var{climits})
@deftypefnx {Function File} {} imagesc (@dots{}, "@var{prop}", @var{val}, @dots{})
@deftypefnx {Function File} {} imagesc ("@var{prop1}", @var{val1}, @dots{})
@deftypefnx {Function File} {} imagesc (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} imagesc (@dots{})
Display a scaled version of the matrix @var{img} as a color image.

The colormap is scaled so that the entries of the matrix occupy the entire
colormap.  If @code{@var{climits} = [@var{lo}, @var{hi}]} is given, then
that range is set to the @qcode{"clim"} of the current axes.

The axis values corresponding to the matrix elements are specified in
@var{x} and @var{y}, either as pairs giving the minimum and maximum
values for the respective axes, or as values for each row and column
of the matrix @var{img}.

The optional return value @var{h} is a graphics handle to the image.

Calling Forms: The @code{imagesc} function can be called in two forms:
High-Level and Low-Level.  When invoked with normal options, the High-Level
form is used which first calls @code{newplot} to prepare the graphic figure
and axes.  When the only inputs to @code{image} are property/value pairs
the Low-Level form is used which creates a new instance of an image object
and inserts it in the current axes.

@seealso{image, imshow, caxis}
@end deftypefn
imfinfo
@c imfinfo scripts/image/imfinfo.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{info} =} imfinfo (@var{filename})
@deftypefnx {Function File} {@var{info} =} imfinfo (@var{url})
@deftypefnx {Function File} {@var{info} =} imfinfo (@dots{}, @var{ext})
Read image information from a file.

@code{imfinfo} returns a structure containing information about the image
stored in the file @var{filename}.  If there is no file @var{filename},
and @var{ext} was specified, it will look for a file named @var{filename}
and extension @var{ext}, i.e., a file named @var{filename}.@var{ext}.

The output structure @var{info} contains the following fields:

@table @samp
@item Filename
The full name of the image file.

@item FileModDate
Date of last modification to the file.

@item FileSize
Number of bytes of the image on disk

@item Format
Image format (e.g., @qcode{"jpeg"}).

@item Height
Image height in pixels.

@item Width
Image Width in pixels.

@item BitDepth
Number of bits per channel per pixel.

@item ColorType
Image type.  Value is @qcode{"grayscale"}, @qcode{"indexed"},
@qcode{"truecolor"}, @qcode{"CMYK"}, or @qcode{"undefined"}.

@item XResolution
X resolution of the image.

@item YResolution
Y resolution of the image.

@item ResolutionUnit
Units of image resolution.  Value is @qcode{"Inch"},
@qcode{"Centimeter"}, or @qcode{"undefined"}.

@item DelayTime
Time in 1/100ths of a second (0 to 65535) which must expire before
displaying the next image in an animated sequence.

@item LoopCount
Number of iterations to loop an animation.

@item ByteOrder
Endian option for formats that support it.  Value is @qcode{"little-endian"},
@qcode{"big-endian"}, or @qcode{"undefined"}.

@item Gamma
Gamma level of the image.  The same color image displayed on two different
workstations may look different due to differences in the display monitor.

@item Quality
JPEG/MIFF/PNG compression level.  Value is an integer in the range [0 100].

@item DisposalMethod
Only valid for GIF images, control how successive frames are rendered (how
the preceding frame is disposed of) when creating a GIF animation.  Values
can be @qcode{"doNotSpecify"}, @qcode{"leaveInPlace"}, @qcode{"restoreBG"},
or @qcode{"restorePrevious"}.  For non-GIF files, value is an empty string.

@item Chromaticities
Value is a 1x8 Matrix with the x,y chromaticity values for white, red,
green, and blue points, in that order.

@item Comment
Image comment.

@item Compression
Compression type.  Value can be @qcode{"none"}, @qcode{"bzip"},
@qcode{"fax3"}, @qcode{"fax4"}, @qcode{"jpeg"}, @qcode{"lzw"},
@qcode{"rle"}, @qcode{"deflate"}, @qcode{"lzma"}, @qcode{"jpeg2000"},
@qcode{"jbig2"}, @qcode{"jbig2"}, or @qcode{"undefined"}.

@item Colormap
Colormap for each image.

@item Orientation
The orientation of the image with respect to the rows and columns.  Value
is an integer between 1 and 8 as defined in the TIFF 6 specifications, and
for @sc{matlab} compatibility.

@item Software
Name and version of the software or firmware of the camera or image input
device used to generate the image.

@item Make
The manufacturer of the recording equipment.  This is the manufacture of the
@nospell{DSC}, scanner, video digitizer or other equipment that generated
the image.

@item Model
The model name or model number of the recording equipment as mentioned on
the field @qcode{"Make"}.

@item DateTime
The date and time of image creation as defined by the Exif standard, i.e.,
it is the date and time the file was changed.

@item ImageDescription
The title of the image as defined by the Exif standard.

@item Artist
Name of the camera owner, photographer or image creator.

@item Copyright
Copyright notice of the person or organization claiming rights to the image.

@item DigitalCamera
A struct with information retrieved from the Exif tag.

@item GPSInfo
A struct with geotagging information retrieved from the Exif tag.
@end table

@seealso{imread, imwrite, imshow, imformats}
@end deftypefn
imformats
@c imformats scripts/image/imformats.m
-*- texinfo -*-
@deftypefn  {Function File} {} imformats ()
@deftypefnx {Function File} {@var{formats} =} imformats (@var{ext})
@deftypefnx {Function File} {@var{formats} =} imformats (@var{format})
@deftypefnx {Function File} {@var{formats} =} imformats ("add", @var{format})
@deftypefnx {Function File} {@var{formats} =} imformats ("remove", @var{ext})
@deftypefnx {Function File} {@var{formats} =} imformats ("update", @var{ext}, @var{format})
@deftypefnx {Function File} {@var{formats} =} imformats ("factory")
Manage supported image formats.

@var{formats} is a structure with information about each supported file
format, or from a specific format @var{ext}, the value displayed on the
field @code{ext}.  It contains the following fields:

@table @asis
@item ext
The name of the file format.  This may match the file extension but Octave
will automatically detect the file format.

@item description
A long description of the file format.

@item @nospell{isa}
A function handle to confirm if a file is of the specified format.

@item write
A function handle to write if a file is of the specified format.

@item read
A function handle to open files the specified format.

@item info
A function handle to obtain image information of the specified format.

@item alpha
Logical value if format supports alpha channel (transparency or matte).

@item multipage
Logical value if format supports multipage (multiple images per file).
@end table

It is possible to change the way Octave manages file formats with the
options @qcode{"add"}, @qcode{"remove"}, and @qcode{"update"}, and supplying
a structure @var{format} with the required fields.  The option
@qcode{"factory"} resets the configuration to the default.

This can be used by Octave packages to extend the image reading capabilities
Octave, through use of the PKG_ADD and PKG_DEL commands.

@seealso{imfinfo, imread, imwrite}
@end deftypefn
imread
@c imread scripts/image/imread.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{img}, @var{map}, @var{alpha}] =} imread (@var{filename})
@deftypefnx {Function File} {[@dots{}] =} imread (@var{url})
@deftypefnx {Function File} {[@dots{}] =} imread (@dots{}, @var{ext})
@deftypefnx {Function File} {[@dots{}] =} imread (@dots{}, @var{idx})
@deftypefnx {Function File} {[@dots{}] =} imread (@dots{}, @var{param1}, @var{val1}, @dots{})
Read images from various file formats.

Read an image as a matrix from the file @var{filename}.  If there is no file
@var{filename}, and @var{ext} was specified, it will look for a file with
the extension @var{ext}.  Finally, it will attempt to download and read an
image from @var{url}.

The size and class of the output depends on the format of the image.  A
color image is returned as an @nospell{MxNx3} matrix.  Gray-level and
black-and-white images are of size @nospell{MxN}.  Multipage images will
have an additional 4th dimension.

The bit depth of the image determines the class of the output:
@qcode{"uint8"}, @qcode{"uint16"} or @qcode{"single"} for gray and color,
and @qcode{"logical"} for black and white.  Note that indexed images always
return the indexes for a colormap, independent if @var{map} is a requested
output.  To obtain the actual RGB image, use @code{ind2rgb}.  When more
than one indexed image is being read, @var{map} is obtained from the
first.  In some rare cases this may be incorrect and @code{imfinfo} can be
used to obtain the colormap of each image.

See the Octave manual for more information in representing images.

Some file formats, such as TIFF and GIF, are able to store multiple images
in a single file.  @var{idx} can be a scalar or vector specifying the
index of the images to read.  By default, Octave will only read the first
page.

Depending on the file format, it is possible to configure the reading of
images with @var{param}, @var{val} pairs.  The following options are
supported:

@table @samp
@item @qcode{"Frames"} or @qcode{"Index"}
This is an alternative method to specify @var{idx}.  When specifying it
in this way, its value can also be the string @qcode{"all"}.

@item @qcode{"Info"}
This option exists for @sc{matlab} compatibility and has no effect.  For
maximum performance while reading multiple images from a single file, use
the Index option.

@item @qcode{"PixelRegion"}
Controls the image region that is read.  Takes as value a cell array with
two arrays of 3 elements @code{@{@var{rows} @var{cols}@}}.  The elements
in the array are the start, increment and end pixel to be read.  If the
increment value is omitted, defaults to 1.  For example, the following are
all equivalent:

@example
@group
imread (filename, "PixelRegion", @{[200 600] [300 700]@});
imread (filename, "PixelRegion", @{[200 1 600] [300 1 700]@});
imread (filename)(200:600, 300:700);
@end group
@end example

@end table

@seealso{imwrite, imfinfo, imformats}
@end deftypefn
imshow
@c imshow scripts/image/imshow.m
-*- texinfo -*-
@deftypefn  {Function File} {} imshow (@var{im})
@deftypefnx {Function File} {} imshow (@var{im}, @var{limits})
@deftypefnx {Function File} {} imshow (@var{im}, @var{map})
@deftypefnx {Function File} {} imshow (@var{rgb}, @dots{})
@deftypefnx {Function File} {} imshow (@var{filename})
@deftypefnx {Function File} {} imshow (@dots{}, @var{string_param1}, @var{value1}, @dots{})
@deftypefnx {Function File} {@var{h} =} imshow (@dots{})
Display the image @var{im}, where @var{im} can be a 2-dimensional
(grayscale image) or a 3-dimensional (RGB image) matrix.

If @var{limits} is a 2-element vector @code{[@var{low}, @var{high}]}, the
image is shown using a display range between @var{low} and @var{high}.  If
an empty matrix is passed for @var{limits}, the display range is computed
as the range between the minimal and the maximal value in the image.

If @var{map} is a valid color map, the image will be shown as an indexed
image using the supplied color map.

If a file name is given instead of an image, the file will be read and shown.

If given, the parameter @var{string_param1} has value @var{value1}.
@var{string_param1} can be any of the following:

@table @asis
@item @qcode{"displayrange"}
@var{value1} is the display range as described above.

@item @qcode{"colormap"}
@var{value1} is the colormap to use when displaying an indexed image.

@item @qcode{"xdata"}
If @var{value1} is a two element vector, it must contain horizontal axis
limits in the form [xmin xmax]; Otherwise @var{value1} must be a vector and
only the first and last elements will be used for xmin and xmax respectively.

@item @qcode{"ydata"}
If @var{value1} is a two element vector, it must contain vertical axis
limits in the form [ymin ymax]; Otherwise @var{value1} must be a vector and
only the first and last elements will be used for ymin and ymax respectively.

@end table

The optional return value @var{h} is a graphics handle to the image.
@seealso{image, imagesc, colormap, gray2ind, rgb2ind}
@end deftypefn
imwrite
@c imwrite scripts/image/imwrite.m
-*- texinfo -*-
@deftypefn  {Function File} {} imwrite (@var{img}, @var{filename})
@deftypefnx {Function File} {} imwrite (@var{img}, @var{filename}, @var{ext})
@deftypefnx {Function File} {} imwrite (@var{img}, @var{map}, @var{filename})
@deftypefnx {Function File} {} imwrite (@dots{}, @var{param1}, @var{val1}, @dots{})
Write images in various file formats.

The image @var{img} can be a binary, grayscale, RGB, or multi-dimensional
image.  The size and class of @var{img} should be the same as what should
be expected when reading it with @code{imread}: the 3rd and 4th dimensions
reserved for color space, and multiple pages respectively.  If it's an
indexed image, the colormap @var{map} must also be specified.

If @var{ext} is not supplied, the file extension of @var{filename} is used
to determine the format.  The actual supported formats are dependent on
options made during the build of Octave.  Use @code{imformats} to check
the support of the different image formats.

Depending on the file format, it is possible to configure the writing of
images with @var{param}, @var{val} pairs.  The following options are
supported:

@table @samp
@item Alpha
Alpha (transparency) channel for the image.  This must be a matrix with
same class, and number of rows and columns of @var{img}.  In case of a
multipage image, the size of the 4th dimension must also match and the third
dimension must be a singleton.  By default, image will be completely opaque.

@item DelayTime
For formats that accept animations (such as GIF), controls for how long a
frame is displayed until it moves to the next one.  The value must be scalar
(which will applied to all frames in @var{img}), or a vector of length
equal to the number of frames in @var{im}.  The value is in seconds, must
be between 0 and 655.35, and defaults to 0.5.

@item DisposalMethod
For formats that accept animations (such as GIF), controls what happens to
a frame before drawing the next one.  Its value can be one of the
following strings: "doNotSpecify" (default); "leaveInPlace"; "restoreBG";
and "restorePrevious", or a cell array of those string with length equal
to the number of frames in @var{img}.

@item LoopCount
For formats that accept animations (such as GIF), controls how many times
the sequence is repeated.  A value of Inf means an infinite loop (default),
a value of 0 or 1 that the sequence is played only once (loops zero times),
while a value of 2 or above loops that number of times (looping twice means
it plays the complete sequence 3 times).  This option is ignored when there
is only a single image at the end of writing the file.

@item Quality
Set the quality of the compression.  The value should be an integer
between 0 and 100, with larger values indicating higher visual quality and
lower compression.  Defaults to 75.

@item WriteMode
Some file formats, such as TIFF and GIF, are able to store multiple images
in a single file.  This option specifies if @var{img} should be appended
to the file (if it exists) or if a new file should be created for it
(possibly overwriting an existing file).  The value should be the string
@qcode{"Overwrite"} (default), or @qcode{"Append"}.

Despite this option, the most efficient method of writing a multipage
image is to pass a 4 dimensional @var{img} to @code{imwrite}, the same
matrix that could be expected when using @code{imread} with the option
@qcode{"Index"} set to @qcode{"all"}.

@end table

@seealso{imread, imfinfo, imformats}
@end deftypefn
ind2gray
@c ind2gray scripts/image/ind2gray.m
-*- texinfo -*-
@deftypefn {Function File} {@var{I} =} ind2gray (@var{x}, @var{map})
Convert a color indexed image to a grayscale intensity image.

The image @var{x} must be an indexed image which will be converted using the
colormap @var{cmap}.  If @var{cmap} does not contain enough colors for the
image, pixels in @var{x} outside the range are mapped to the last color in
the map before conversion to grayscale.

The output @var{I} is of the same class as the input @var{x} and may be
one of @code{uint8}, @code{uint16}, @code{single}, or @code{double}.

Implementation Note: There are several ways of converting colors to
grayscale intensities.  This functions uses the luminance value obtained
from @code{rgb2ntsc} which is @code{I = 0.299*R + 0.587*G + 0.114*B}.
Other possibilities include the value component from @code{rgb2hsv} or
using a single color channel from @code{ind2rgb}.
@seealso{gray2ind, ind2rgb}
@end deftypefn
ind2rgb
@c ind2rgb scripts/image/ind2rgb.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{rgb} =} ind2rgb (@var{x}, @var{map})
@deftypefnx {Function File} {[@var{R}, @var{G}, @var{B}] =} ind2rgb (@var{x}, @var{map})
Convert an indexed image to red, green, and blue color components.

The image @var{x} must be an indexed image which will be converted using the
colormap @var{map}.  If @var{map} does not contain enough colors for the
image, pixels in @var{x} outside the range are mapped to the last color in
the map.

The output may be a single RGB image (@nospell{MxNx3} matrix where M and N
are the original image @var{x} dimensions, one for each of the red, green
and blue channels).  Alternatively, the individual red, green, and blue
color matrices of size @nospell{MxN} may be returned.

Multi-dimensional indexed images (of size @nospell{MxNx1xK}) are also
supported.

@seealso{rgb2ind, ind2gray, hsv2rgb, ntsc2rgb}
@end deftypefn
jet
@c jet scripts/image/jet.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} jet ()
@deftypefnx {Function File} {@var{map} =} jet (@var{n})
Create color colormap.  This colormap ranges from dark blue through blue,
cyan, green, yellow, red, to dark red.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
lines
@c lines scripts/image/lines.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} lines ()
@deftypefnx {Function File} {@var{map} =} lines (@var{n})
Create color colormap.  This colormap is composed of the list of colors
in the current axes @qcode{"ColorOrder"} property.  The default is blue,
green, red, cyan, pink, yellow, and gray.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
ntsc2rgb
@c ntsc2rgb scripts/image/ntsc2rgb.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{rgb_map} =} ntsc2rgb (@var{yiq_map})
@deftypefnx {Function File} {@var{rgb_img} =} ntsc2rgb (@var{yiq_img})
Transform a colormap or image from luminance-chrominance (NTSC) space to
red-green-blue (RGB) color space.

Implementation Note:
The conversion matrix is chosen to be the inverse of the matrix used for
rgb2ntsc such that

@example
x == ntsc2rgb (rgb2ntsc (x))
@end example

@sc{matlab} uses a slightly different matrix where rounding means the
equality above does not hold.
@seealso{rgb2ntsc, hsv2rgb, ind2rgb}
@end deftypefn
ocean
@c ocean scripts/image/ocean.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} ocean ()
@deftypefnx {Function File} {@var{map} =} ocean (@var{n})
Create color colormap.  This colormap varies from black to white with shades
of blue.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
pink
@c pink scripts/image/pink.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} pink ()
@deftypefnx {Function File} {@var{map} =} pink (@var{n})
Create color colormap.  This colormap varies from black to white with
shades of gray-pink.

This colormap gives a sepia tone when used on grayscale images.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
prism
@c prism scripts/image/prism.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} prism ()
@deftypefnx {Function File} {@var{map} =} prism (@var{n})
Create color colormap.  This colormap cycles through red, orange, yellow,
green, blue and violet with each index change.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
rainbow
@c rainbow scripts/image/rainbow.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} rainbow ()
@deftypefnx {Function File} {@var{map} =} rainbow (@var{n})
Create color colormap.  This colormap ranges from red through orange,
yellow, green, blue, to violet.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
rgb2hsv
@c rgb2hsv scripts/image/rgb2hsv.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{hsv_map} =} rgb2hsv (@var{rgb})
@deftypefnx {Function File} {@var{hsv_map} =} rgb2hsv (@var{rgb})
Transform a colormap or image from red-green-blue (RGB) space to
hue-saturation-value (HSV) space.

A color in the RGB space consists of red, green, and blue intensities.

A color in HSV space is represented by hue, saturation, and value
(brightness) levels.  Value gives the amount of light in the color.  Hue
describes the dominant wavelength.  Saturation is the amount of hue mixed
into the color.
@seealso{hsv2rgb, rgb2ind, rgb2ntsc}
@end deftypefn
rgb2ind
@c rgb2ind scripts/image/rgb2ind.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{x}, @var{map}] =} rgb2ind (@var{rgb})
@deftypefnx {Function File} {[@var{x}, @var{map}] =} rgb2ind (@var{R}, @var{G}, @var{B})
Convert an image in red-green-blue (RGB) color space to an indexed image.

The input image @var{rgb} can be specified as a single matrix of size
@nospell{MxNx3}, or as three separate variables, @var{R}, @var{G}, and
@var{B}, its three color channels, red, green, and blue.

It outputs an indexed image @var{x} and a colormap @var{map} to interpret
an image exactly the same as the input.  No dithering or other form of color
quantization is performed.  The output class of the indexed image @var{x}
can be uint8, uint16 or double, whichever is required to specify the
number of unique colors in the image (which will be equal to the number
of rows in @var{map}) in order

Multi-dimensional indexed images (of size @nospell{MxNx3xK}) are also
supported, both via a single input (@var{rgb}) or its three color channels
as separate variables.

@seealso{ind2rgb, rgb2hsv, rgb2ntsc}
@end deftypefn
rgb2ntsc
@c rgb2ntsc scripts/image/rgb2ntsc.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{yiq_map} =} rgb2ntsc (@var{rgb_map})
@deftypefnx {Function File} {@var{yiq_img} =} rgb2ntsc (@var{rgb_img})
Transform a colormap or image from red-green-blue (RGB) color space to
luminance-chrominance (NTSC) space.  The input may be of class uint8,
uint16, single, or double.  The output is of class double.

Implementation Note:
The reference matrix for the transformation is

@example
@group
/Y\     0.299  0.587  0.114  /R\
|I|  =  0.596 -0.274 -0.322  |G|
\Q/     0.211 -0.523  0.312  \B/
@end group
@end example

@noindent
as documented in @url{http://en.wikipedia.org/wiki/YIQ} and truncated to 3
significant figures.  Note: The FCC version of NTSC uses only 2 significant
digits and is slightly different.
@seealso{ntsc2rgb, rgb2hsv, rgb2ind}
@end deftypefn
rgbplot
@c rgbplot scripts/image/rgbplot.m
-*- texinfo -*-
@deftypefn  {Function File} {} rgbplot (@var{cmap})
@deftypefnx {Function File} {} rgbplot (@var{cmap}, @var{style})
@deftypefnx {Function File} {@var{h} =} rgbplot (@dots{})
Plot the components of a colormap.

Two different @var{style}s are available for displaying the @var{cmap}:

@table @asis
@item profile (default)
Plot the RGB line profile of the colormap for each of the channels (red,
green and blue) with the plot lines colored appropriately.  Each line
represents the intensity of each RGB components across the colormap.

@item composite
Draw the colormap across the X-axis so that the actual index colors are
visible rather than the individual color components.

@end table

The optional return value @var{h} is a graphics handle to the created plot.

Run @code{demo rgbplot} to see an example of @code{rgbplot} and each style
option.
@seealso{colormap}
@end deftypefn
spinmap
@c spinmap scripts/image/spinmap.m
-*- texinfo -*-
@deftypefn  {Function File} {} spinmap ()
@deftypefnx {Function File} {} spinmap (@var{t})
@deftypefnx {Function File} {} spinmap (@var{t}, @var{inc})
@deftypefnx {Function File} {} spinmap ("inf")
Cycle the colormap for @var{t} seconds with a color increment of @var{inc}.

Both parameters are optional.  The default cycle time is 5 seconds and the
default increment is 2.  If the option @qcode{"inf"} is given then cycle
continuously until @kbd{Control-C} is pressed.

When rotating, the original color 1 becomes color 2, color 2 becomes
color 3, etc.  A positive or negative increment is allowed and a higher
value of @var{inc} will cause faster cycling through the colormap.
@seealso{colormap}
@end deftypefn
spring
@c spring scripts/image/spring.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} spring ()
@deftypefnx {Function File} {@var{map} =} spring (@var{n})
Create color colormap.  This colormap varies from magenta to yellow.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
summer
@c summer scripts/image/summer.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} summer ()
@deftypefnx {Function File} {@var{map} =} summer (@var{n})
Create color colormap.  This colormap varies from green to yellow.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
white
@c white scripts/image/white.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} white ()
@deftypefnx {Function File} {@var{map} =} white (@var{n})
Create color colormap.  This colormap is completely white.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
winter
@c winter scripts/image/winter.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} winter ()
@deftypefnx {Function File} {@var{map} =} winter (@var{n})
Create color colormap.  This colormap varies from blue to green.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{colormap}
@end deftypefn
beep
@c beep scripts/io/beep.m
-*- texinfo -*-
@deftypefn {Function File} {} beep ()
Produce a beep from the speaker (or visual bell).

This function sends the alarm character @qcode{"@xbackslashchar{}a"} to
the terminal. Depending on the user's configuration this may produce an
audible beep, a visual bell, or nothing at all.
@seealso{puts, fputs, printf, fprintf}
@end deftypefn
csvread
@c csvread scripts/io/csvread.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} csvread (@var{filename})
@deftypefnx {Function File} {@var{x} =} csvread (@var{filename}, @var{dlm_opts})
Read the comma-separated-value file @var{filename} into the matrix @var{x}.

This function is equivalent to

@example
@var{x} = dlmread (@var{filename}, "," , @dots{})
@end example

@seealso{csvwrite, dlmread, dlmwrite}
@end deftypefn
csvwrite
@c csvwrite scripts/io/csvwrite.m
-*- texinfo -*-
@deftypefn  {Function File} {} csvwrite (@var{filename}, @var{x})
@deftypefnx {Function File} {} csvwrite (@var{filename}, @var{x}, @var{dlm_opts})
Write the matrix @var{x} to the file @var{filename} in
@w{comma-separated-value} format.

This function is equivalent to

@example
dlmwrite (@var{filename}, @var{x}, ",", @dots{})
@end example

@seealso{csvread, dlmwrite, dlmread}
@end deftypefn
dlmwrite
@c dlmwrite scripts/io/dlmwrite.m
-*- texinfo -*-
@deftypefn  {Function File} {} dlmwrite (@var{file}, @var{M})
@deftypefnx {Function File} {} dlmwrite (@var{file}, @var{M}, @var{delim}, @var{r}, @var{c})
@deftypefnx {Function File} {} dlmwrite (@var{file}, @var{M}, @var{key}, @var{val} @dots{})
@deftypefnx {Function File} {} dlmwrite (@var{file}, @var{M}, "-append", @dots{})
@deftypefnx {Function File} {} dlmwrite (@var{fid}, @dots{})
Write the matrix @var{M} to the named file using delimiters.

@var{file} should be a file name or writable file ID given by @code{fopen}.

The parameter @var{delim} specifies the delimiter to use to separate values
on a row.

The value of @var{r} specifies the number of delimiter-only lines to add to
the start of the file.

The value of @var{c} specifies the number of delimiters to prepend to each
line of data.

If the argument @qcode{"-append"} is given, append to the end of @var{file}.

In addition, the following keyword value pairs may appear at the end of
the argument list:

@table @asis
@item @qcode{"append"}
Either @qcode{"on"} or @qcode{"off"}.  See @qcode{"-append"} above.

@item @qcode{"delimiter"}
See @var{delim} above.

@item @qcode{"newline"}
The character(s) to use to separate each row.  Three special cases exist
for this option.  @qcode{"unix"} is changed into
@qcode{"@xbackslashchar{}n"}, @qcode{"pc"} is changed into
@qcode{"@xbackslashchar{}r@xbackslashchar{}n"}, and @qcode{"mac"} is
changed into @qcode{"@xbackslashchar{}r"}.  Any other value is used
directly as the newline separator.

@item @qcode{"roffset"}
See @var{r} above.

@item @qcode{"coffset"}
See @var{c} above.

@item @qcode{"precision"}
The precision to use when writing the file.  It can either be a format
string (as used by fprintf) or a number of significant digits.
@end table

@example
dlmwrite ("file.csv", reshape (1:16, 4, 4));
@end example

@example
dlmwrite ("file.tex", a, "delimiter", "&", "newline", "\n")
@end example

@seealso{dlmread, csvread, csvwrite}
@end deftypefn
fileread
@c fileread scripts/io/fileread.m
-*- texinfo -*-
@deftypefn {Function File} {@var{str} =} fileread (@var{filename})
Read the contents of @var{filename} and return it as a string.
@seealso{fread, textread, sscanf}
@end deftypefn
importdata
@c importdata scripts/io/importdata.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{A} =} importdata (@var{fname})
@deftypefnx {Function File} {@var{A} =} importdata (@var{fname}, @var{delimiter})
@deftypefnx {Function File} {@var{A} =} importdata (@var{fname}, @var{delimiter}, @var{header_rows})
@deftypefnx {Function File} {[@var{A}, @var{delimiter}] =} importdata (@dots{})
@deftypefnx {Function File} {[@var{A}, @var{delimiter}, @var{header_rows}] =} importdata (@dots{})
Import data from the file @var{fname}.

Input parameters:

@itemize
@item @var{fname}
The name of the file containing data.

@item @var{delimiter}
The character separating columns of data.  Use @code{\t} for tab.
(Only valid for ASCII files)

@item @var{header_rows}
The number of header rows before the data begins.  (Only valid for ASCII
files)
@end itemize

Different file types are supported:

@itemize
@item ASCII table

Import ASCII table using the specified number of header rows and the
specified delimiter.

@item Image file

@item @sc{matlab} file

@item Spreadsheet files (depending on external software)

@item WAV file

@end itemize

@seealso{textscan, dlmread, csvread, load}
@end deftypefn
is_valid_file_id
@c is_valid_file_id scripts/io/is_valid_file_id.m
-*- texinfo -*-
@deftypefn {Function File} {} is_valid_file_id (@var{fid})
Return true if @var{fid} refers to an open file.
@seealso{freport, fopen}
@end deftypefn
strread
@c strread scripts/io/strread.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{a}, @dots{}] =} strread (@var{str})
@deftypefnx {Function File} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format})
@deftypefnx {Function File} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format}, @var{format_repeat})
@deftypefnx {Function File} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format}, @var{prop1}, @var{value1}, @dots{})
@deftypefnx {Function File} {[@var{a}, @dots{}] =} strread (@var{str}, @var{format}, @var{format_repeat}, @var{prop1}, @var{value1}, @dots{})
Read data from a string.

The string @var{str} is split into words that are repeatedly matched to the
specifiers in @var{format}.  The first word is matched to the first
specifier, the second to the second specifier and so forth.  If there are
more words than specifiers, the process is repeated until all words have
been processed.

The string @var{format} describes how the words in @var{str} should be
parsed.  It may contain any combination of the following specifiers:

@table @code
@item %s
The word is parsed as a string.

@item  %f
@itemx %n
The word is parsed as a number and converted to double.

@item  %d
@itemx %u
The word is parsed as a number and converted to int32.

@item %*', '%*f', '%*s
The word is skipped.

For %s and %d, %f, %n, %u and the associated %*s @dots{} specifiers an
optional width can be specified as %Ns, etc. where N is an integer > 1.
For %f, format specifiers like %N.Mf are allowed.

@item literals
In addition the format may contain literal character strings; these will be
skipped during reading.
@end table

Parsed word corresponding to the first specifier are returned in the first
output argument and likewise for the rest of the specifiers.

By default, @var{format} is @t{"%f"}, meaning that numbers are read from
@var{str}.  This will do if @var{str} contains only numeric fields.

For example, the string

@example
@group
@var{str} = "\
Bunny Bugs   5.5\n\
Duck Daffy  -7.5e-5\n\
Penguin Tux   6"
@end group
@end example

@noindent
can be read using

@example
[@var{a}, @var{b}, @var{c}] = strread (@var{str}, "%s %s %f");
@end example

Optional numeric argument @var{format_repeat} can be used for limiting the
number of items read:

@table @asis
@item -1
(default) read all of the string until the end.

@item N
Read N times @var{nargout} items.  0 (zero) is an acceptable value for
@var{format_repeat}.
@end table

The behavior of @code{strread} can be changed via property-value pairs.  The
following properties are recognized:

@table @asis
@item @qcode{"commentstyle"}
Parts of @var{str} are considered comments and will be skipped.
@var{value} is the comment style and can be any of the following.

@itemize
@item @qcode{"shell"}
Everything from @code{#} characters to the nearest end-of-line is skipped.

@item @qcode{"c"}
Everything between @code{/*} and @code{*/} is skipped.

@item @qcode{"c++"}
Everything from @code{//} characters to the nearest end-of-line is skipped.

@item @qcode{"matlab"}
Everything from @code{%} characters to the nearest end-of-line is skipped.

@item user-supplied.  Two options:
(1) One string, or 1x1 cell string: Skip everything to the right of it;
(2) 2x1 cell string array: Everything between the left and right strings
is skipped.
@end itemize

@item @qcode{"delimiter"}
Any character in @var{value} will be used to split @var{str} into words
(default value = any whitespace).  Note that whitespace is implicitly added
to the set of delimiter characters unless a @qcode{"%s"} format conversion
specifier is supplied; see @qcode{"whitespace"} parameter below.  The set
of delimiter characters cannot be empty; if needed Octave substitutes a
space as delimiter.

@item @qcode{"emptyvalue"}
Value to return for empty numeric values in non-whitespace delimited data.
The default is NaN@.  When the data type does not support NaN (int32 for
example), then default is zero.

@item @qcode{"multipledelimsasone"}
Treat a series of consecutive delimiters, without whitespace in between,
as a single delimiter.  Consecutive delimiter series need not be vertically
@qcode{"aligned"}.

@item @qcode{"treatasempty"}
Treat single occurrences (surrounded by delimiters or whitespace) of the
string(s) in @var{value} as missing values.

@item @qcode{"returnonerror"}
If @var{value} true (1, default), ignore read errors and return normally.
If false (0), return an error.

@item @qcode{"whitespace"}
Any character in @var{value} will be interpreted as whitespace and trimmed;
the string defining whitespace must be enclosed in double quotes for proper
processing of special characters like @qcode{"@xbackslashchar{}t"}.  In
each data field, multiple consecutive whitespace characters are collapsed
into one space and leading and trailing whitespace is removed.  The default
value for whitespace is
@c Note: the next line specifically has a newline which generates a space
@c       in the output of qcode, but keeps the next line < 80 characters.
@qcode{"
@xbackslashchar{}b@xbackslashchar{}r@xbackslashchar{}n@xbackslashchar{}t"}
(note the space).  Whitespace is always added to the set of delimiter
characters unless at least one @qcode{"%s"} format conversion specifier is
supplied; in that case only whitespace explicitly specified in
@qcode{"delimiter"} is retained as delimiter and removed from the set of
whitespace characters.  If whitespace characters are to be kept as-is (in
e.g., strings), specify an empty value (i.e., @qcode{""}) for
@qcode{"whitespace"}; obviously, whitespace cannot be a delimiter then.

@end table

When the number of words in @var{str} doesn't match an exact multiple of
the number of format conversion specifiers, strread's behavior depends on
the last character of @var{str}:

@table @asis
@item last character = @qcode{"@xbackslashchar{}n"}
Data columns are padded with empty fields or Nan so that all columns have
equal length

@item last character is not @qcode{"@xbackslashchar{}n"}
Data columns are not padded; strread returns columns of unequal length

@end table

@seealso{textscan, textread, load, dlmread, fscanf}
@end deftypefn
textscan
@c textscan scripts/io/textscan.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{C} =} textscan (@var{fid}, @var{format})
@deftypefnx {Function File} {@var{C} =} textscan (@var{fid}, @var{format}, @var{n})
@deftypefnx {Function File} {@var{C} =} textscan (@var{fid}, @var{format}, @var{param}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{C} =} textscan (@var{fid}, @var{format}, @var{n}, @var{param}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{C} =} textscan (@var{str}, @dots{})
@deftypefnx {Function File} {[@var{C}, @var{position}] =} textscan (@var{fid}, @dots{})
Read data from a text file or string.

The string @var{str} or file associated with @var{fid} is read from and
parsed according to @var{format}.  The function behaves like @code{strread}
except it can also read from file instead of a string.  See the documentation
of @code{strread} for details.

In addition to the options supported by @code{strread}, this function
supports a few more:

@itemize
@item @qcode{"collectoutput"}:
A value of 1 or true instructs textscan to concatenate consecutive columns
of the same class in the output cell array.  A value of 0 or false (default)
leaves output in distinct columns.

@item @qcode{"endofline"}:
Specify @qcode{"@xbackslashchar{}r"}, @qcode{"@xbackslashchar{}n"} or
@qcode{"@xbackslashchar{}r@xbackslashchar{}n"} (for CR, LF, or CRLF).  If no
value is given, it will be inferred from the file.  If set to "" (empty
string) EOLs are ignored as delimiters and added to whitespace.

@item @qcode{"headerlines"}:
The first @var{value} number of lines of @var{fid} are skipped.

@item @qcode{"returnonerror"}:
If set to numerical 1 or true (default), return normally when read errors
have been encountered.  If set to 0 or false, return an error and no data.
As the string or file is read by columns rather than by rows, and because
textscan is fairly forgiving as regards read errors, setting this option
may have little or no actual effect.
@end itemize

When reading from a character string, optional input argument @var{n}
specifies the number of times @var{format} should be used (i.e., to limit
the amount of data read).
When reading from file, @var{n} specifies the number of data lines to read;
in this sense it differs slightly from the format repeat count in strread.

The output @var{C} is a cell array whose second dimension is determined
by the number of format specifiers.

The second output, @var{position}, provides the position, in characters,
from the beginning of the file.

If the format string is empty (not: omitted) and the file contains only
numeric data (excluding headerlines), textscan will return data in a number
of columns matching the number of numeric fields on the first data line of
the file.

@seealso{dlmread, fscanf, load, strread, textread}
@end deftypefn
textread
@c textread scripts/io/textread.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{a}, @dots{}] =} textread (@var{filename})
@deftypefnx {Function File} {[@var{a}, @dots{}] =} textread (@var{filename}, @var{format})
@deftypefnx {Function File} {[@var{a}, @dots{}] =} textread (@var{filename}, @var{format}, @var{n})
@deftypefnx {Function File} {[@var{a}, @dots{}] =} textread (@var{filename}, @var{format}, @var{prop1}, @var{value1}, @dots{})
@deftypefnx {Function File} {[@var{a}, @dots{}] =} textread (@var{filename}, @var{format}, @var{n}, @var{prop1}, @var{value1}, @dots{})
Read data from a text file.

The file @var{filename} is read and parsed according to @var{format}.  The
function behaves like @code{strread} except it works by parsing a file
instead of a string.  See the documentation of @code{strread} for details.

In addition to the options supported by @code{strread}, this function
supports two more:

@itemize
@item @qcode{"headerlines"}:
The first @var{value} number of lines of @var{filename} are skipped.

@item @qcode{"endofline"}:
Specify a single character or
@qcode{"@xbackslashchar{}r@xbackslashchar{}n"}.  If no value is given, it
will be inferred from the file.  If set to @qcode{""} (empty string) EOLs
are ignored as delimiters.
@end itemize

The optional input @var{n} (format repeat count) specifies the number of
times the format string is to be used or the number of lines to be read,
whichever happens first while reading.  The former is equivalent to
requesting that the data output vectors should be of length @var{N}.
Note that when reading files with format strings referring to multiple
lines, @var{n} should rather be the number of lines to be read than the
number of format string uses.

If the format string is empty (not just omitted) and the file contains only
numeric data (excluding headerlines), textread will return a rectangular
matrix with the number of columns matching the number of numeric fields on
the first data line of the file.  Empty fields are returned as zero values.

Examples:

@example
  Assume a data file like:
  1 a 2 b
  3 c 4 d
  5 e
@end example

@example
  [a, b] = textread (f, "%f %s")
  returns two columns of data, one with doubles, the other a
  cellstr array:
  a = [1; 2; 3; 4; 5]
  b = @{"a"; "b"; "c"; "d"; "e"@}
@end example

@example
  [a, b] = textread (f, "%f %s", 3)
  (read data into two culumns, try to use the format string
  three times)
  returns
  a = [1; 2; 3]
  b = @{"a"; "b"; "c"@}

@end example

@example
  With a data file like:
  1
  a
  2
  b

  [a, b] = textread (f, "%f %s", 2)
  returns a = 1 and b = @{"a"@}; i.e., the format string is used
  only once because the format string refers to 2 lines of the
  data file. To obtain 2x1 data output columns, specify N = 4
  (number of data lines containing all requested data) rather
  than 2.
@end example

@seealso{strread, load, dlmread, fscanf, textscan}
@end deftypefn
java_get
@c java_get scripts/java/java_get.m
-*- texinfo -*-
@deftypefn {Function File} {@var{val} =} java_get (@var{obj}, @var{name})
Get the value of the field @var{name} of the Java object @var{obj}.

For static fields, @var{obj} can be a string representing the fully
qualified name of the corresponding class.

When @var{obj} is a regular Java object, structure-like indexing can be
used as a shortcut syntax.  For instance, the following two statements are
equivalent

@example
@group
  java_get (x, "field1")
  x.field1
@end group
@end example

@seealso{java_set, javaMethod, javaObject}
@end deftypefn
java_set
@c java_set scripts/java/java_set.m
-*- texinfo -*-
@deftypefn {Function File} {@var{obj} =} java_set (@var{obj}, @var{name}, @var{val})
Set the value of the field @var{name} of the Java object @var{obj} to
@var{val}.

For static fields, @var{obj} can be a string representing the fully
qualified named of the corresponding Java class.

When @var{obj} is a regular Java object, structure-like indexing can be
used as a shortcut syntax.  For instance, the following two statements are
equivalent

@example
@group
  java_set (x, "field1", val)
  x.field1 = val
@end group
@end example

@seealso{java_get, javaMethod, javaObject}
@end deftypefn
javaArray
@c javaArray scripts/java/javaArray.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{jary} =} javaArray (@var{classname}, @var{sz})
@deftypefnx {Function File} {@var{jary} =} javaArray (@var{classname}, @var{m}, @var{n}, @dots{})

Create a Java array of size @var{sz} with elements of class @var{classname}.

@var{classname} may be a Java object representing a class or a string
containing the fully qualified class name.  The size of the object may
also be specified with individual integer arguments @var{m}, @var{n}, etc.

The generated array is uninitialized.  All elements are set to null if
@var{classname} is a reference type, or to a default value (usually 0) if
@var{classname} is a primitive type.

Sample code:

@example
@group
jary = javaArray ("java.lang.String", 2, 2);
jary(1,1) = "Hello";
@end group
@end example
@seealso{javaObject}
@end deftypefn
javaaddpath
@c javaaddpath scripts/java/javaaddpath.m
-*- texinfo -*-
@deftypefn  {Function File} {} javaaddpath (@var{clspath})
@deftypefnx {Function File} {} javaaddpath (@var{clspath1}, @dots{})
Add @var{clspath} to the dynamic class path of the Java virtual machine.

@var{clspath} may either be a directory where @file{.class} files are
found, or a @file{.jar} file containing Java classes.  Multiple paths may
be added at once by specifying additional arguments.
@seealso{javarmpath, javaclasspath}
@end deftypefn
javachk
@c javachk scripts/java/javachk.m
-*- texinfo -*-
@deftypefn  {Function File} {} javachk (@var{feature})
@deftypefnx {Function File} {} javachk (@var{feature}, @var{component})
@deftypefnx {Function File} {@var{msg} =} javachk (@dots{})
Check for the presence of the Java @var{feature} in the current session
and print or return an error message if it is not.

Possible features are:

@table @asis
@item @qcode{"awt"}
Abstract Window Toolkit for GUIs.

@item @qcode{"desktop"}
Interactive desktop is running.

@item @qcode{"jvm"}
Java Virtual Machine.

@item @qcode{"swing"}
Swing components for lightweight GUIs.
@end table

If @var{feature} is supported and

@itemize @bullet
@item
no output argument is requested:

Return an empty string

@item
an output argument is requested:

Return a struct with fields @qcode{"feature"} and @qcode{"identifier"}
both empty
@end itemize

If @var{feature} is not supported and

@itemize @bullet
@item
no output argument is requested:

Emit an error message

@item
an output argument is requested:

Return a struct with field @qcode{"feature"} set to @var{feature} and field
@qcode{"identifier"} set to @var{component}
@end itemize

The optional input @var{component} will be used in place of @var{feature}
in any error messages for greater specificity.

@code{javachk} determines if specific Java features are available in an
Octave session.  This function is provided for scripts which may alter
their behavior based on the availability of Java.  The feature
@qcode{"desktop"} is never available as Octave has no Java-based desktop.
Other features may be available if Octave was compiled with the Java
Interface and Java is installed.

@seealso{usejava, error}
@end deftypefn
javaclasspath
@c javaclasspath scripts/java/javaclasspath.m
-*- texinfo -*-
@deftypefn  {Function File} {} javaclasspath ()
@deftypefnx {Function File} {@var{dpath} =} javaclasspath ()
@deftypefnx {Function File} {[@var{dpath}, @var{spath}] =} javaclasspath ()
@deftypefnx {Function File} {@var{clspath} =} javaclasspath (@var{what})
Return the class path of the Java virtual machine in the form of a cell
array of strings.

If called with no inputs:

@itemize
@item If no output is requested, the dynamic and static classpaths are
printed to the standard output.

@item If one output value @var{dpath} is requested, the result is the
dynamic classpath.

@item If two output values@var{dpath} and @var{spath} are requested, the
first variable will contain the dynamic classpath and the second will
contain the static classpath.
@end itemize

If called with a single input parameter @var{what}:

@table @asis
@item @qcode{"-dynamic"}
Return the dynamic classpath.

@item @qcode{"-static"}
Return the static classpath.

@item @qcode{"-all"}
Return both the static and dynamic classpath in a single cellstr.
@end table
@seealso{javaaddpath, javarmpath}
@end deftypefn
javamem
@c javamem scripts/java/javamem.m
-*- texinfo -*-
@deftypefn  {Function File} {} javamem ()
@deftypefnx {Function File} {@var{jmem} =} javamem ()
Show the current memory usage of the Java virtual machine (JVM) and run the
garbage collector.

When no return argument is given the info is printed to the screen.
Otherwise, the output cell array @var{jmem} contains Maximum, Total, and
Free memory (in bytes).

All Java-based routines are run in the JVM's shared memory pool, a
dedicated and separate part of memory claimed by the JVM from your
computer's total memory (which comprises physical RAM and virtual memory /
swap space on hard disk).

The maximum allowable memory usage can be configured using the file
@file{java.opts}.  The directory where this file resides is determined by
the environment variable @w{@env{OCTAVE_JAVA_DIR}}.  If unset, the directory
where @file{javaaddpath.m} resides is used instead (typically
@file{@w{@env{OCTAVE_HOME}}/share/octave/@w{@env{OCTAVE_VERSION}}/m/java/}).

@file{java.opts} is a plain text file with one option per line.  The default
initial memory size and default maximum memory size (which are both system
dependent) can be overridden like so:

@nospell{-Xms64m}

@nospell{-Xmx512m}

(in megabytes in this example).
You can adapt these values to your own requirements if your system has
limited available physical memory or if you get Java memory errors.

@qcode{"Total memory"} is what the operating system has currently assigned
to the JVM and depends on actual and active memory usage.
@qcode{"Free memory"} is self-explanatory.  During operation of Java-based
Octave functions the amount of Total and Free memory will vary, due to
Java's own cleaning up and your operating system's memory management.
@end deftypefn
javarmpath
@c javarmpath scripts/java/javarmpath.m
-*- texinfo -*-
@deftypefn  {Function File} {} javarmpath (@var{clspath})
@deftypefnx {Function File} {} javarmpath (@var{clspath1}, @dots{})
Remove @var{clspath} from the dynamic class path of the Java virtual
machine.

@var{clspath} may either be a directory where @file{.class} files are found,
or a @file{.jar} file containing Java classes.  Multiple paths may be
removed at once by specifying additional arguments.
@seealso{javaaddpath, javaclasspath}
@end deftypefn
usejava
@c usejava scripts/java/usejava.m
-*- texinfo -*-
@deftypefn {Function File} {} usejava (@var{feature})
Return true if the Java element @var{feature} is available.

Possible features are:

@table @asis
@item @qcode{"awt"}
Abstract Window Toolkit for GUIs.

@item @qcode{"desktop"}
Interactive desktop is running.

@item @qcode{"jvm"}
Java Virtual Machine.

@item @qcode{"swing"}
Swing components for lightweight GUIs.
@end table

@code{usejava} determines if specific Java features are available in an
Octave session.  This function is provided for scripts which may alter
their behavior based on the availability of Java.  The feature
@qcode{"desktop"} always returns @code{false} as Octave has no Java-based
desktop.  Other features may be available if Octave was compiled with the
Java Interface and Java is installed.
@seealso{javachk}
@end deftypefn
bandwidth
@c bandwidth scripts/linear-algebra/bandwidth.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{bw} =} bandwidth (@var{A}, @var{type})
@deftypefnx {Function File} {[@var{lower}, @var{upper}] =} bandwidth (@var{A})
Compute the bandwidth of @var{A}.

The @var{type} argument is the string @qcode{"lower"} for the lower
bandwidth and @qcode{"upper"} for the upper bandwidth.  If no @var{type} is
specified return both the lower and upper bandwidth of @var{A}.

The lower/upper bandwidth of a matrix is the number of
subdiagonals/superdiagonals with nonzero entries.

@seealso{isbanded, isdiag, istril, istriu}
@end deftypefn
commutation_matrix
@c commutation_matrix scripts/linear-algebra/commutation_matrix.m
-*- texinfo -*-
@deftypefn {Function File} {} commutation_matrix (@var{m}, @var{n})
Return the commutation matrix
@tex
 $K_{m,n}$
@end tex
@ifnottex
K(m,n)
@end ifnottex
which is the unique
@tex
 $m n \times m n$
@end tex
@ifnottex
@var{m}*@var{n} by @var{m}*@var{n}
@end ifnottex
matrix such that
@tex
 $K_{m,n} \cdot {\rm vec} (A) = {\rm vec} (A^T)$
@end tex
@ifnottex
@math{K(m,n) * vec(A) = vec(A')}
@end ifnottex
for all
@tex
 $m\times n$
@end tex
@ifnottex
@math{m} by @math{n}
@end ifnottex
matrices
@tex
 $A$.
@end tex
@ifnottex
@math{A}.
@end ifnottex

If only one argument @var{m} is given,
@tex
 $K_{m,m}$
@end tex
@ifnottex
@math{K(m,m)}
@end ifnottex
is returned.

See @nospell{Magnus and Neudecker} (1988), @cite{Matrix Differential
Calculus with Applications in Statistics and Econometrics.}
@end deftypefn
cond
@c cond scripts/linear-algebra/cond.m
-*- texinfo -*-
@deftypefn  {Function File} {} cond (@var{A})
@deftypefnx {Function File} {} cond (@var{A}, @var{p})
Compute the @var{p}-norm condition number of a matrix.

@code{cond (@var{A})} is defined as
@tex
$ {\parallel A \parallel_p * \parallel A^{-1} \parallel_p .} $
@end tex
@ifnottex
@code{norm (@var{A}, @var{p}) * norm (inv (@var{A}), @var{p})}.
@end ifnottex

By default, @code{@var{p} = 2} is used which implies a (relatively slow)
singular value decomposition.  Other possible selections are
@code{@var{p} = 1, Inf, "fro"} which are generally faster.  See @code{norm}
for a full discussion of possible @var{p} values.

The condition number of a matrix quantifies the sensitivity of the matrix
inversion operation when small changes are made to matrix elements.  Ideally
the condition number will be close to 1.  When the number is large this
indicates small changes (such as underflow or round-off error) will produce
large changes in the resulting output.  In such cases the solution results
from numerical computing are not likely to be accurate.
@seealso{condest, rcond, norm, svd}
@end deftypefn
condest
@c condest scripts/linear-algebra/condest.m
-*- texinfo -*-
@deftypefn  {Function File} {} condest (@var{A})
@deftypefnx {Function File} {} condest (@var{A}, @var{t})
@deftypefnx {Function File} {[@var{est}, @var{v}] =} condest (@dots{})
@deftypefnx {Function File} {[@var{est}, @var{v}] =} condest (@var{A}, @var{solve}, @var{solve_t}, @var{t})
@deftypefnx {Function File} {[@var{est}, @var{v}] =} condest (@var{apply}, @var{apply_t}, @var{solve}, @var{solve_t}, @var{n}, @var{t})

Estimate the 1-norm condition number of a matrix @var{A} using @var{t} test
vectors using a randomized 1-norm estimator.

If @var{t} exceeds 5, then only 5 test vectors are used.

If the matrix is not explicit, e.g., when estimating the condition
number of @var{A} given an LU@tie{}factorization, @code{condest} uses the
following functions:

@table @var
@item apply
@code{A*x} for a matrix @code{x} of size @var{n} by @var{t}.

@item apply_t
@code{A'*x} for a matrix @code{x} of size @var{n} by @var{t}.

@item solve
@code{A \ b} for a matrix @code{b} of size @var{n} by @var{t}.

@item solve_t
@code{A' \ b} for a matrix @code{b} of size @var{n} by @var{t}.
@end table

The implicit version requires an explicit dimension @var{n}.

@code{condest} uses a randomized algorithm to approximate the 1-norms.

@code{condest} returns the 1-norm condition estimate @var{est} and a vector
@var{v} satisfying @code{norm (A*v, 1) == norm (A, 1) * norm
(@var{v}, 1) / @var{est}}.  When @var{est} is large, @var{v} is an
approximate null vector.

References:

@itemize
@item
@nospell{N.J. Higham and F. Tisseur}, @cite{A Block Algorithm
for Matrix 1-Norm Estimation, with an Application to 1-Norm
Pseudospectra}. SIMAX vol 21, no 4, pp 1185-1201.
@url{http://dx.doi.org/10.1137/S0895479899356080}

@item
@nospell{N.J. Higham and F. Tisseur}, @cite{A Block Algorithm
for Matrix 1-Norm Estimation, with an Application to 1-Norm
Pseudospectra}. @url{http://citeseer.ist.psu.edu/223007.html}
@end itemize

@seealso{cond, norm, onenormest}
@end deftypefn
cross
@c cross scripts/linear-algebra/cross.m
-*- texinfo -*-
@deftypefn  {Function File} {} cross (@var{x}, @var{y})
@deftypefnx {Function File} {} cross (@var{x}, @var{y}, @var{dim})
Compute the vector cross product of two 3-dimensional vectors @var{x} and
@var{y}.

If @var{x} and @var{y} are matrices, the cross product is applied along the
first dimension with three elements.

The optional argument  @var{dim} forces the cross product to be calculated
along the specified dimension.

Example Code:

@example
@group
cross ([1,1,0], [0,1,1])
     @result{} [ 1; -1; 1 ]
@end group
@end example

@seealso{dot, curl, divergence}
@end deftypefn
duplication_matrix
@c duplication_matrix scripts/linear-algebra/duplication_matrix.m
-*- texinfo -*-
@deftypefn {Function File} {} duplication_matrix (@var{n})
Return the duplication matrix
@tex
 $D_n$
@end tex
@ifnottex
@nospell{@math{Dn}}
@end ifnottex
which is the unique
@tex
 $n^2 \times n(n+1)/2$
@end tex
@ifnottex
@math{n^2} by @math{n*(n+1)/2}
@end ifnottex
matrix such that
@tex
 $D_n * {\rm vech} (A) = {\rm vec} (A)$
@end tex
@ifnottex
@nospell{@math{Dn vech (A) = vec (A)}}
@end ifnottex
for all symmetric
@tex
 $n \times n$
@end tex
@ifnottex
@math{n} by @math{n}
@end ifnottex
matrices
@tex
 $A$.
@end tex
@ifnottex
@math{A}.
@end ifnottex

See @nospell{Magnus and Neudecker} (1988), @cite{Matrix Differential
Calculus with Applications in Statistics and Econometrics.}
@end deftypefn
expm
@c expm scripts/linear-algebra/expm.m
-*- texinfo -*-
@deftypefn {Function File} {} expm (@var{A})
Return the exponential of a matrix.

The matrix exponential is defined as the infinite Taylor series
@tex
$$
 \exp (A) = I + A + {A^2 \over 2!} + {A^3 \over 3!} + \cdots
$$
@end tex
@ifnottex

@example
expm (A) = I + A + A^2/2! + A^3/3! + @dots{}
@end example

@end ifnottex
However, the Taylor series is @emph{not} the way to compute the matrix
exponential; see @nospell{Moler and Van Loan}, @cite{Nineteen Dubious Ways
to Compute the Exponential of a Matrix}, SIAM Review, 1978.  This routine
uses Ward's diagonal Pad@'e approximation method with three step
preconditioning (SIAM Journal on Numerical Analysis, 1977).  Diagonal
Pad@'e approximations are rational polynomials of matrices
@tex
$D_q(A)^{-1}N_q(A)$
@end tex
@ifnottex

@example
@group
     -1
D (A)   N (A)
@end group
@end example

@end ifnottex
whose Taylor series matches the first
@tex
$2 q + 1 $
@end tex
@ifnottex
@code{2q+1}
@end ifnottex
terms of the Taylor series above; direct evaluation of the Taylor series
(with the same preconditioning steps) may be desirable in lieu of the
Pad@'e approximation when
@tex
$D_q(A)$
@end tex
@ifnottex
@code{Dq(A)}
@end ifnottex
is ill-conditioned.
@seealso{logm, sqrtm}
@end deftypefn
housh
@c housh scripts/linear-algebra/housh.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{housv}, @var{beta}, @var{zer}] =} housh (@var{x}, @var{j}, @var{z})
Compute Householder reflection vector @var{housv} to reflect @var{x} to be
the j-th column of identity, i.e.,

@example
@group
(I - beta*housv*housv')x =  norm (x)*e(j) if x(j) < 0,
(I - beta*housv*housv')x = -norm (x)*e(j) if x(j) >= 0
@end group
@end example

@noindent
Inputs

@table @var
@item x
vector

@item j
index into vector

@item z
threshold for zero  (usually should be the number 0)
@end table

@noindent
Outputs (see @nospell{Golub and Van Loan}):

@table @var
@item beta
If beta = 0, then no reflection need be applied (@nospell{zer} set to 0)

@item housv
householder vector
@end table
@end deftypefn
isbanded
@c isbanded scripts/linear-algebra/isbanded.m
-*- texinfo -*-
@deftypefn {Function File} {} isbanded (@var{A}, @var{lower}, @var{upper})
Return true if @var{A} is a matrix with entries confined between
@var{lower} diagonals below the main diagonal and @var{upper} diagonals
above the main diagonal.

@var{lower} and @var{upper} must be non-negative integers.
@seealso{isdiag, istril, istriu, bandwidth}
@end deftypefn
isdefinite
@c isdefinite scripts/linear-algebra/isdefinite.m
-*- texinfo -*-
@deftypefn  {Function File} {} isdefinite (@var{A})
@deftypefnx {Function File} {} isdefinite (@var{A}, @var{tol})
Return 1 if @var{A} is symmetric positive definite within the
tolerance specified by @var{tol} or 0 if @var{A} is symmetric
positive semidefinite.  Otherwise, return -1.

If @var{tol} is omitted, use a tolerance of
@code{100 * eps * norm (@var{A}, "fro")}
@seealso{issymmetric, ishermitian}
@end deftypefn
isdiag
@c isdiag scripts/linear-algebra/isdiag.m
-*- texinfo -*-
@deftypefn {Function File} {} isdiag (@var{A})
Return true if @var{A} is a diagonal matrix.
@seealso{isbanded, istril, istriu, diag, bandwidth}
@end deftypefn
ishermitian
@c ishermitian scripts/linear-algebra/ishermitian.m
-*- texinfo -*-
@deftypefn  {Function File} {} ishermitian (@var{A})
@deftypefnx {Function File} {} ishermitian (@var{A}, @var{tol})
Return true if @var{A} is Hermitian within the tolerance specified by
@var{tol}.

The default tolerance is zero (uses faster code).

Matrix @var{A} is considered symmetric if
@code{norm (@var{A} - @var{A}', Inf) / norm (@var{A}, Inf) < @var{tol}}.
@seealso{issymmetric, isdefinite}
@end deftypefn
issymmetric
@c issymmetric scripts/linear-algebra/issymmetric.m
-*- texinfo -*-
@deftypefn  {Function File} {} issymmetric (@var{A})
@deftypefnx {Function File} {} issymmetric (@var{A}, @var{tol})
Return true if @var{A} is a symmetric matrix within the tolerance specified
by @var{tol}.

The default tolerance is zero (uses faster code).

Matrix @var{A} is considered symmetric if
@code{norm (@var{A} - @var{A}.', Inf) / norm (@var{A}, Inf) < @var{tol}}.
@seealso{ishermitian, isdefinite}
@end deftypefn
istril
@c istril scripts/linear-algebra/istril.m
-*- texinfo -*-
@deftypefn {Function File} {} istril (@var{A})
Return true if @var{A} is a lower triangular matrix.

A lower triangular matrix has nonzero entries only on the main diagonal and
below.
@seealso{istriu, isbanded, isdiag, tril, bandwidth}
@end deftypefn
istriu
@c istriu scripts/linear-algebra/istriu.m
-*- texinfo -*-
@deftypefn {Function File} {} istriu (@var{A})
Return true if @var{A} is an upper triangular matrix.

An upper triangular matrix has nonzero entries only on the main diagonal and
above.
@seealso{isdiag, isbanded, istril, triu, bandwidth}
@end deftypefn
krylov
@c krylov scripts/linear-algebra/krylov.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{u}, @var{h}, @var{nu}] =} krylov (@var{A}, @var{V}, @var{k}, @var{eps1}, @var{pflg})
Construct an orthogonal basis @var{u} of block Krylov subspace

@example
[v a*v a^2*v @dots{} a^(k+1)*v]
@end example

@noindent
using Householder reflections to guard against loss of orthogonality.

If @var{V} is a vector, then @var{h} contains the Hessenberg matrix
such that @nospell{@tcode{a*u == u*h+rk*ek'}}, in which
@code{rk = a*u(:,k)-u*h(:,k)}, and @nospell{@tcode{ek'}} is the vector
@code{[0, 0, @dots{}, 1]} of length @code{k}.  Otherwise, @var{h} is
meaningless.

If @var{V} is a vector and @var{k} is greater than @code{length (A) - 1},
then @var{h} contains the Hessenberg matrix such that @code{a*u == u*h}.

The value of @var{nu} is the dimension of the span of the Krylov subspace
(based on @var{eps1}).

If @var{b} is a vector and @var{k} is greater than @var{m-1}, then @var{h}
contains the Hessenberg decomposition of @var{A}.

The optional parameter @var{eps1} is the threshold for zero.  The default
value is 1e-12.

If the optional parameter @var{pflg} is nonzero, row pivoting is used to
improve numerical behavior.  The default value is 0.

Reference: @nospell{A. Hodel, P. Misra}, @cite{Partial Pivoting in the
Computation of Krylov Subspaces of Large Sparse Systems}, Proceedings of
the 42nd IEEE Conference on Decision and Control, December 2003.
@end deftypefn
linsolve
@c linsolve scripts/linear-algebra/linsolve.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} linsolve (@var{A}, @var{b})
@deftypefnx {Function File} {@var{x} =} linsolve (@var{A}, @var{b}, @var{opts})
@deftypefnx {Function File} {[@var{x}, @var{R}] =} linsolve (@dots{})
Solve the linear system @code{A*x = b}.

With no options, this function is equivalent to the left division operator
@w{(@code{x = A \ b})} or the matrix-left-divide function
@w{(@code{x = mldivide (A, b)})}.

Octave ordinarily examines the properties of the matrix @var{A} and chooses
a solver that best matches the matrix.  By passing a structure @var{opts}
to @code{linsolve} you can inform Octave directly about the matrix @var{A}.
In this case Octave will skip the matrix examination and proceed directly
to solving the linear system.

@strong{Warning:} If the matrix @var{A} does not have the properties
listed in the @var{opts} structure then the result will not be accurate
AND no warning will be given.  When in doubt, let Octave examine the matrix
and choose the appropriate solver as this step takes little time and the
result is cached so that it is only done once per linear system.

Possible @var{opts} fields (set value to true/false):

@table @asis
@item LT
@var{A} is lower triangular

@item UT
@var{A} is upper triangular

@item UHESS
@var{A} is upper Hessenberg (currently makes no difference)

@item SYM
@var{A} is symmetric or complex Hermitian (currently makes no difference)

@item POSDEF
@var{A} is positive definite

@item RECT
@var{A} is general rectangular (currently makes no difference)

@item TRANSA
  Solve @code{A'*x = b} by @code{transpose (A) \ b}
@end table

The optional second output @var{R} is the inverse condition number of
@var{A} (zero if matrix is singular).
@seealso{mldivide, matrix_type, rcond}
@end deftypefn
logm
@c logm scripts/linear-algebra/logm.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{s} =} logm (@var{A})
@deftypefnx {Function File} {@var{s} =} logm (@var{A}, @var{opt_iters})
@deftypefnx {Function File} {[@var{s}, @var{iters}] =} logm (@dots{})
Compute the matrix logarithm of the square matrix @var{A}.

The implementation utilizes a Pad@'e approximant and the identity

@example
logm (@var{A}) = 2^k * logm (@var{A}^(1 / 2^k))
@end example

The optional input @var{opt_iters} is the maximum number of square roots
to compute and defaults to 100.

The optional output @var{iters} is the number of square roots actually
computed.
@seealso{expm, sqrtm}
@end deftypefn
normest
@c normest scripts/linear-algebra/normest.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{n} =} normest (@var{A})
@deftypefnx {Function File} {@var{n} =} normest (@var{A}, @var{tol})
@deftypefnx {Function File} {[@var{n}, @var{c}] =} normest (@dots{})
Estimate the 2-norm of the matrix @var{A} using a power series analysis.

This is typically used for large matrices, where the cost of calculating
@code{norm (@var{A})} is prohibitive and an approximation to the 2-norm is
acceptable.

@var{tol} is the tolerance to which the 2-norm is calculated.  By default
@var{tol} is 1e-6.

The optional output @var{c} returns the number of iterations needed for
@code{normest} to converge.
@end deftypefn
null
@c null scripts/linear-algebra/null.m
-*- texinfo -*-
@deftypefn  {Function File} {} null (@var{A})
@deftypefnx {Function File} {} null (@var{A}, @var{tol})
Return an orthonormal basis of the null space of @var{A}.

The dimension of the null space is taken as the number of singular values of
@var{A} not greater than @var{tol}.  If the argument @var{tol} is missing,
it is computed as

@example
max (size (@var{A})) * max (svd (@var{A})) * eps
@end example
@seealso{orth}
@end deftypefn
onenormest
@c onenormest scripts/linear-algebra/onenormest.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{est}, @var{v}, @var{w}, @var{iter}] =} onenormest (@var{A}, @var{t})
@deftypefnx {Function File} {[@var{est}, @var{v}, @var{w}, @var{iter}] =} onenormest (@var{apply}, @var{apply_t}, @var{n}, @var{t})

Apply @nospell{Higham and Tisseur's} randomized block 1-norm estimator to
matrix @var{A} using @var{t} test vectors.

If @var{t} exceeds 5, then only 5 test vectors are used.

If the matrix is not explicit, e.g., when estimating the norm of
@code{inv (@var{A})} given an LU@tie{}factorization, @code{onenormest}
applies @var{A} and its conjugate transpose through a pair of functions
@var{apply} and @var{apply_t}, respectively, to a dense matrix of size
@var{n} by @var{t}.  The implicit version requires an explicit dimension
@var{n}.

Returns the norm estimate @var{est}, two vectors @var{v} and @var{w} related
by norm @code{(@var{w}, 1) = @var{est} * norm (@var{v}, 1)}, and the number
of iterations @var{iter}.  The number of iterations is limited to 10 and is
at least 2.

References:

@itemize
@item
@nospell{N.J. Higham and F. Tisseur}, @cite{A Block Algorithm
for Matrix 1-Norm Estimation, with an Application to 1-Norm
Pseudospectra}. SIMAX vol 21, no 4, pp 1185-1201.
@url{http://dx.doi.org/10.1137/S0895479899356080}

@item
@nospell{N.J. Higham and F. Tisseur}, @cite{A Block Algorithm
for Matrix 1-Norm Estimation, with an Application to 1-Norm
Pseudospectra}. @url{http://citeseer.ist.psu.edu/223007.html}
@end itemize

@seealso{condest, norm, cond}
@end deftypefn
orth
@c orth scripts/linear-algebra/orth.m
-*- texinfo -*-
@deftypefn  {Function File} {} orth (@var{A})
@deftypefnx {Function File} {} orth (@var{A}, @var{tol})
Return an orthonormal basis of the range space of @var{A}.

The dimension of the range space is taken as the number of singular values
of @var{A} greater than @var{tol}.  If the argument @var{tol} is missing, it
is computed as

@example
max (size (@var{A})) * max (svd (@var{A})) * eps
@end example
@seealso{null}
@end deftypefn
planerot
@c planerot scripts/linear-algebra/planerot.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{G}, @var{y}] =} planerot (@var{x})
Given a two-element column vector, return the
@tex
$2 \times 2$ orthogonal matrix
@end tex
@ifnottex
2 by 2 orthogonal matrix
@end ifnottex
@var{G} such that
@code{@var{y} = @var{g} * @var{x}} and @code{@var{y}(2) = 0}.
@seealso{givens}
@end deftypefn
qzhess
@c qzhess scripts/linear-algebra/qzhess.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{aa}, @var{bb}, @var{q}, @var{z}] =} qzhess (@var{A}, @var{B})
Compute the Hessenberg-triangular decomposition of the matrix pencil
@code{(@var{A}, @var{B})}, returning
@code{@var{aa} = @var{q} * @var{A} * @var{z}},
@code{@var{bb} = @var{q} * @var{B} * @var{z}}, with @var{q} and @var{z}
orthogonal.

For example:

@example
@group
[aa, bb, q, z] = qzhess ([1, 2; 3, 4], [5, 6; 7, 8])
     @result{} aa = [ -3.02244, -4.41741;  0.92998,  0.69749 ]
     @result{} bb = [ -8.60233, -9.99730;  0.00000, -0.23250 ]
     @result{}  q = [ -0.58124, -0.81373; -0.81373,  0.58124 ]
     @result{}  z = [ 1, 0; 0, 1 ]
@end group
@end example

The Hessenberg-triangular decomposition is the first step in
@nospell{Moler and Stewart's} QZ@tie{}decomposition algorithm.

Algorithm taken from @nospell{Golub and Van Loan},
@cite{Matrix Computations, 2nd edition}.

@seealso{lu, chol, hess, qr, qz, schur, svd}
@end deftypefn
rank
@c rank scripts/linear-algebra/rank.m
-*- texinfo -*-
@deftypefn  {Function File} {} rank (@var{A})
@deftypefnx {Function File} {} rank (@var{A}, @var{tol})
Compute the rank of matrix @var{A}, using the singular value decomposition.

The rank is taken to be the number of singular values of @var{A} that are
greater than the specified tolerance @var{tol}.  If the second argument is
omitted, it is taken to be

@example
tol = max (size (@var{A})) * sigma(1) * eps;
@end example

@noindent
where @code{eps} is machine precision and @code{sigma(1)} is the largest
singular value of @var{A}.

The rank of a matrix is the number of linearly independent rows or columns
and determines how many particular solutions exist to a system of equations.
Use @code{null} for finding the remaining homogenous solutions.

Example:

@example
@group
x = [1 2 3
     4 5 6
     7 8 9];
rank (x)
  @result{} 2
@end group
@end example

@noindent
The number of linearly independent rows is only 2 because the final row is a
linear combination of -1*row1 + 2*row2.

@seealso{null, sprank, svd}
@end deftypefn
rref
@c rref scripts/linear-algebra/rref.m
-*- texinfo -*-
@deftypefn  {Function File} {} rref (@var{A})
@deftypefnx {Function File} {} rref (@var{A}, @var{tol})
@deftypefnx {Function File} {[@var{r}, @var{k}] =} rref (@dots{})
Return the reduced row echelon form of @var{A}.

@var{tol} defaults to
@code{eps * max (size (@var{A})) * norm (@var{A}, inf)}.

The optional return argument @var{k} contains the vector of
"bound variables", which are those columns on which elimination has been
performed.

@end deftypefn
subspace
@c subspace scripts/linear-algebra/subspace.m
-*- texinfo -*-
@deftypefn {Function File} {@var{angle} =} subspace (@var{A}, @var{B})
Determine the largest principal angle between two subspaces
spanned by the columns of matrices @var{A} and @var{B}.
@end deftypefn
trace
@c trace scripts/linear-algebra/trace.m
-*- texinfo -*-
@deftypefn {Function File} {} trace (@var{A})
Compute the trace of @var{A}, the sum of the elements along the main
diagonal.

The implementation is straightforward: @code{sum (diag (@var{A}))}.
@seealso{eig}
@end deftypefn
vech
@c vech scripts/linear-algebra/vech.m
-*- texinfo -*-
@deftypefn {Function File} {} vech (@var{x})
Return the vector obtained by eliminating all superdiagonal elements of
the square matrix @var{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.
@seealso{vec}
@end deftypefn
ans
@c ans scripts/miscellaneous/ans.m
-*- texinfo -*-
@defvr {Automatic Variable} ans
The most recently computed result that was not explicitly assigned to a
variable.

For example, after the expression

@example
3^2 + 4^2
@end example

@noindent
is evaluated, the value returned by @code{ans} is 25.
@end defvr
bug_report
@c bug_report scripts/miscellaneous/bug_report.m
-*- texinfo -*-
@deftypefn {Function File} {} bug_report ()
Display information about how to submit bug reports for Octave.
@end deftypefn
bunzip2
@c bunzip2 scripts/miscellaneous/bunzip2.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{filelist} =} bunzip2 (@var{bzfile})
@deftypefnx {Function File} {@var{filelist} =} bunzip2 (@var{bzfile}, @var{dir})
Unpack the bzip2 archive @var{bzfile}.

If @var{dir} is specified the files are unpacked in this directory rather
than the one where @var{bzfile} is located.

The optional output @var{filelist} is a list of the uncompressed files.
@seealso{bzip2, unpack, gunzip, unzip, untar}
@end deftypefn
bzip2
@c bzip2 scripts/miscellaneous/bzip2.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{filelist} =} bzip2 (@var{files})
@deftypefnx {Function File} {@var{filelist} =} bzip2 (@var{files}, @var{dir})
Compress the list of files specified in @var{files}.

@var{files} is a character array or cell array of strings.  Shell wildcards
in the filename such as @samp{*} or @samp{?} are accepted and expanded.
Each file is compressed separately and a new file with a @file{".bz2"}
extension is created.  The original files are not modified, but existing
compressed files will be silently overwritten.

If @var{dir} is defined the compressed files are placed in this directory,
rather than the original directory where the uncompressed file resides.
If @var{dir} does not exist it is created.

The optional output @var{filelist} is a list of the compressed files.
@seealso{bunzip2, unpack, gzip, zip, tar}
@end deftypefn
cast
@c cast scripts/miscellaneous/cast.m
-*- texinfo -*-
@deftypefn {Function File} {} cast (@var{val}, "@var{type}")
Convert @var{val} to data type @var{type}.

@var{val} must be one of the numeric classes:

@example
@group
"double"
"single"
"logical"
"char"
"int8"
"int16"
"int32"
"int64"
"uint8"
"uint16"
"uint32"
"uint64"
@end group
@end example

The value @var{val} may be modified to fit within the range of the new type.

Examples:

@example
@group
cast (-5, "uint8")
   @result{} 0
cast (300, "int8")
   @result{} 127
@end group
@end example

@seealso{typecast, int8, uint8, int16, uint16, int32, uint32, int64, uint64, double, single, logical, char, class, typeinfo}
@end deftypefn
citation
@c citation scripts/miscellaneous/citation.m
-*- texinfo -*-
@deftypefn  {Command} {} citation
@deftypefnx {Command} {} citation @var{package}
Display instructions for citing GNU Octave or its packages in publications.

When called without an argument, display information on how to cite the core
GNU Octave system.

When given a package name @var{package}, display information on citing the
specific named package.  Note that some packages may not yet have
instructions on how to cite them.

The GNU Octave developers and its active community of package authors have
invested a lot of time and effort in creating GNU Octave as it is today.
Please give credit where credit is due and cite GNU Octave and its packages
when you use them.

@end deftypefn
comma
@c comma scripts/miscellaneous/comma.m
-*- texinfo -*-
@deftypefn {Operator} {} ,
Array index, function argument, or command separator.
@seealso{semicolon}
@end deftypefn
compare_versions
@c compare_versions scripts/miscellaneous/compare_versions.m
-*- texinfo -*-
@deftypefn {Function File} {} compare_versions (@var{v1}, @var{v2}, @var{operator})
Compare two version strings using the given @var{operator}.

This function assumes that versions @var{v1} and @var{v2} are arbitrarily
long strings made of numeric and period characters possibly followed by an
arbitrary string (e.g., @qcode{"1.2.3"}, @qcode{"0.3"}, @qcode{"0.1.2+"},
or @qcode{"1.2.3.4-test1"}).

The version is first split into numeric and character portions and then
the parts are padded to be the same length (i.e., @qcode{"1.1"} would be
padded to be @qcode{"1.1.0"} when being compared with @qcode{"1.1.1"}, and
separately, the character parts of the strings are padded with nulls).

The operator can be any logical operator from the set

@itemize @bullet
@item
@qcode{"=="}
equal

@item
@qcode{"<"}
less than

@item
@qcode{"<="}
less than or equal to

@item
@qcode{">"}
greater than

@item
@qcode{">="}
greater than or equal to

@item
@qcode{"!="}
not equal

@item
@qcode{"~="}
not equal
@end itemize

Note that version @qcode{"1.1-test2"} will compare as greater than
@qcode{"1.1-test10"}.  Also, since the numeric part is compared first,
@qcode{"a"} compares less than @qcode{"1a"} because the second string
starts with a numeric part even though @code{double ("a")} is greater than
@code{double ("1").}
@end deftypefn
computer
@c computer scripts/miscellaneous/computer.m
-*- texinfo -*-
@deftypefn  {Function File} {} computer ()
@deftypefnx {Function File} {@var{c} =} computer ()
@deftypefnx {Function File} {[@var{c}, @var{maxsize}] =} computer ()
@deftypefnx {Function File} {[@var{c}, @var{maxsize}, @var{endian}] =} computer ()
@deftypefnx {Function File} {@var{arch} =} computer ("arch")
Print or return a string of the form @var{cpu}-@var{vendor}-@var{os} that
identifies the type of computer that Octave is running on.

If invoked with an output argument, the value is returned instead of
printed.  For example:

@example
@group
computer ()
   @print{} i586-pc-linux-gnu

mycomp = computer ()
   @result{} mycomp = "i586-pc-linux-gnu"
@end group
@end example

If two output arguments are requested, also return the maximum number of
elements for an array.  This will depend on whether Octave has been
compiled with 32-bit or 64-bit index vectors.

If three output arguments are requested, also return the byte order of the
current system as a character (@qcode{"B"} for big-endian or @qcode{"L"}
for little-endian).

If the argument @qcode{"arch"} is specified, return a string indicating the
architecture of the computer on which Octave is running.
@seealso{isunix, ismac, ispc}
@end deftypefn
copyfile
@c copyfile scripts/miscellaneous/copyfile.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} copyfile (@var{f1}, @var{f2})
@deftypefnx {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} copyfile (@var{f1}, @var{f2}, 'f')
Copy the source files or directories @var{f1} to the destination @var{f2}.

The name @var{f1} may contain globbing patterns.  If @var{f1} expands to
multiple file names, @var{f2} must be a directory.

When the force flag @qcode{'f'} is given any existing files will be
overwritten without prompting.

If successful, @var{status} is 1, and @var{msg}, @var{msgid} are empty
character strings ("").  Otherwise, @var{status} is 0, @var{msg} contains a
system-dependent error message, and @var{msgid} contains a unique message
identifier.  Note that the status code is exactly opposite that of the
@code{system} command.
@seealso{movefile, rename, unlink, delete, glob}
@end deftypefn
debug
@c debug scripts/miscellaneous/debug.m
-*- texinfo -*-
@deftypefn {Function File} {} debug ()
Summary of debugging commands.

For more information on each command and available options use
@code{help CMD}.

The debugging commands available in Octave are

@table @code
@item dbstop
Add a breakpoint.

@item dbclear
Remove a breakpoint.

@item dbstatus
List all breakpoints.

@item dbwhere
Report the current file and line number where execution is stopped.

@item dbtype
Display the code of the function being debugged, enumerating
the line numbers.

@item dblist
List 10 lines of code centered around the line number where execution is
stopped.

@item  dbstep
@itemx dbnext
Execute (step) one or more lines, follow execution into (step into) a
function call, or execute until the end of a function (step out), and
re-enter debug mode.

@item dbcont
Continue normal code execution from the debug prompt.

@item dbquit
Quit debugging mode immediately and return to the main prompt.

@item dbstack
Print a backtrace of the execution stack.

@item dbup
Move up the execution stack.

@item dbdown
Move down the execution stack.

@item keyboard
Force entry into debug mode from an m-file.

@item debug_on_error
Configure whether Octave enters debug mode when it encounters an error.

@item debug_on_warning
Configure whether Octave enters debug mode when it encounters a warning.

@item debug_on_interrupt
Configure whether Octave enters debug mode when it encounters an interrupt.

@item isdebugmode
Return true if in debug mode.
@end table

@noindent
When Octave encounters a breakpoint, or other reason to enter debug mode,
the prompt changes to @qcode{"debug>"}.  The workspace of the function
where the breakpoint was encountered becomes available and any Octave
command that is valid in that workspace context may be executed.

@seealso{dbstop, dbclear, dbstatus, dbwhere, dbtype, dbcont, dbquit,
dbstack, dbup, dbdown, keyboard, debug_on_error, debug_on_warning,
debug_on_interrupt, isdebugmode}
@end deftypefn
delete
@c delete scripts/miscellaneous/delete.m
-*- texinfo -*-
@deftypefn  {Function File} {} delete (@var{file})
@deftypefnx {Function File} {} delete (@var{file1}, @var{file2}, @dots{})
@deftypefnx {Function File} {} delete (@var{handle})
Delete the named file or graphics handle.

@var{file} may contain globbing patterns such as @samp{*}.  Multiple files
to be deleted may be specified in the same function call.

@var{handle} may be a scalar or vector of graphic handles to delete.

Programming Note: Deleting graphics objects is the proper way to remove
features from a plot without clearing the entire figure.
@seealso{clf, cla, unlink, rmdir}
@end deftypefn
desktop
@c desktop scripts/miscellaneous/desktop.m
-*- texinfo -*-
@deftypefn {Function File} {@var{used} =} desktop ("-inuse")
Return true if the desktop (GUI) is currently in use.
@seealso{isguirunning}
@end deftypefn
dir
@c dir scripts/miscellaneous/dir.m
-*- texinfo -*-
@deftypefn  {Function File} {} dir
@deftypefnx {Function File} {} dir (@var{directory})
@deftypefnx {Function File} {[@var{list}] =} dir (@var{directory})
Display file listing for directory @var{directory}.

If @var{directory} is not specified then list the present working directory.

If a return value is requested, return a structure array with the fields

@table @asis
@item name
File or directory name.

@item date
Timestamp of file modification (string value).

@item bytes
File size in bytes.

@item isdir
True if name is a directory.

@item datenum
Timestamp of file modification as serial date number (double).

@item statinfo
Information structure returned from @code{stat}.
@end table

If @var{directory} is a filename, rather than a directory, then return
information about the named file.  @var{directory} may also be a list rather
than a single directory or file.

@var{directory} is subject to shell expansion if it contains any wildcard
characters @samp{*}, @samp{?}, @samp{[]}.  To find a literal example of a
wildcard character the wildcard must be escaped using the backslash operator
@samp{\}.

Note that for symbolic links, @code{dir} returns information about the
file that the symbolic link points to rather than the link itself.
However, if the link points to a nonexistent file, @code{dir} returns
information about the link.
@seealso{ls, readdir, glob, what, stat, lstat}
@end deftypefn
dos
@c dos scripts/miscellaneous/dos.m
-*- texinfo -*-
@deftypefn  {Function File} {} dos ("@var{command}")
@deftypefnx {Function File} {@var{status} =} dos ("@var{command}")
@deftypefnx {Function File} {[@var{status}, @var{text}] =} dos ("@var{command"})
@deftypefnx {Function File} {[@dots{}] =} dos ("@var{command}", "-echo")
Execute a system command if running under a Windows-like operating system,
otherwise do nothing.

Octave waits for the external command to finish before returning the exit
status of the program in @var{status} and any output in @var{text}.

When called with no output argument, or the @qcode{"-echo"} argument is
given, then @var{text} is also sent to standard output.
@seealso{unix, system, isunix, ismac, ispc}
@end deftypefn
edit
@c edit scripts/miscellaneous/edit.m
-*- texinfo -*-
@deftypefn  {Command} {} edit @var{name}
@deftypefnx {Command} {} edit @var{field} @var{value}
@deftypefnx {Command} {@var{value} =} edit get @var{field}
Edit the named function, or change editor settings.

If @code{edit} is called with the name of a file or function as its
argument it will be opened in the text editor defined by @env{EDITOR}.

@itemize @bullet
@item
If the function @var{name} is available in a file on your path and that
file is modifiable, then it will be edited in place.  If it is a system
function, then it will first be copied to the directory @env{HOME} (see
below) and then edited.  If no file is found, then the m-file variant,
ending with @qcode{".m"}, will be considered.  If still no file is found,
then variants with a leading @qcode{"@@"} and then with both a leading
@qcode{"@@"} and trailing @qcode{".m"} will be considered.

@item
If @var{name} is the name of a function defined in the interpreter but not
in an m-file, then an m-file will be created in @env{HOME} to contain that
function along with its current definition.

@item
If @code{@var{name}.cc} is specified, then it will search for
@code{@var{name}.cc} in the path and try to modify it, otherwise it will
create a new @file{.cc} file in the current directory.  If @var{name} happens
to be an m-file or interpreter defined function, then the text of that
function will be inserted into the .cc file as a comment.

@item
If @file{@var{name}.ext} is on your path then it will be edited, otherwise
the editor will be started with @file{@var{name}.ext} in the current
directory as the filename.  If @file{@var{name}.ext} is not modifiable,
it will be copied to @env{HOME} before editing.

@strong{Warning:} You may need to clear @var{name} before the new definition
is available.  If you are editing a .cc file, you will need to execute
@code{mkoctfile @file{@var{name}.cc}} before the definition will be
available.
@end itemize

If @code{edit} is called with @var{field} and @var{value} variables, the
value of the control field @var{field} will be set to @var{value}.  If an
output argument is requested and the first input argument is @code{get}
then @code{edit} will return the value of the control field @var{field}.
If the control field does not exist, edit will return a structure
containing all fields and values.  Thus, @code{edit get all} returns a
complete control structure.

The following control fields are used:

@table @samp
@item home
This is the location of user local m-files.  Be sure it is in your path.
The default is @file{~/octave}.

@item author
This is the name to put after the "## Author:" field of new functions.  By
default it guesses from the @code{gecos} field of the password database.

@item email
This is the e-mail address to list after the name in the author field.  By
default it guesses @code{<$LOGNAME@@$HOSTNAME>}, and if @code{$HOSTNAME}
is not defined it uses @code{uname -n}.  You probably want to override
this.  Be sure to use the format @code{@email{user@@host}}.

@item license

@table @samp
@item gpl
GNU General Public License (default).

@item bsd
BSD-style license without advertising clause.

@item pd
Public domain.

@item "text"
Your own default copyright and license.
@end table

Unless you specify @samp{pd}, edit will prepend the copyright statement
with "Copyright (C) yyyy Function Author".

@item mode
This value determines whether the editor should be started in async mode
(editor is started in the background and Octave continues) or sync mode
(Octave waits until the editor exits).  Set it to @qcode{"sync"} to start
the editor in sync mode.  The default is @qcode{"async"}
(@pxref{XREFsystem,,system}).

@item editinplace
Determines whether files should be edited in place, without regard to
whether they are modifiable or not.  The default is @code{false}.
@end table
@end deftypefn
error_ids
@c error_ids scripts/miscellaneous/error_ids.m
-*- texinfo -*-
@cindex error ids

@table @code
@item Octave:invalid-context
Indicates the error was generated by an operation that cannot be executed in
the scope from which it was called.  For example, the function
@code{print_usage ()} when called from the Octave prompt raises this error.

@item Octave:invalid-input-arg
Indicates that a function was called with invalid input arguments.

@item Octave:invalid-fun-call
Indicates that a function was called in an incorrect way, e.g., wrong number
of input arguments.

@item Octave:invalid-indexing
Indicates that a data-type was indexed incorrectly, e.g., real-value index
for arrays, nonexistent field of a structure.

@item Octave:bad-alloc
Indicates that memory couldn't be allocated.

@item Octave:undefined-function
Indicates a call to a function that is not defined.  The function may exist
but Octave is unable to find it in the search path.

@end table

fact
@c fact scripts/miscellaneous/fact.m
-*- texinfo -*-
@deftypefn  {Command} {} fact
@deftypefnx {Function File} {@var{truth} =} fact ()
Display an amazing and random fact about the world's greatest hacker.
@end deftypefn
fileattrib
@c fileattrib scripts/miscellaneous/fileattrib.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{status}, @var{result}, @var{msgid}] =} fileattrib (@var{file})
Return information about @var{file}.

If successful, @var{status} is 1, with @var{result} containing a structure
with the following fields:

@table @code
@item Name
Full name of @var{file}.

@item archive
True if @var{file} is an archive (Windows).

@item system
True if @var{file} is a system file (Windows).

@item hidden
True if @var{file} is a hidden file (Windows).

@item directory
True if @var{file} is a directory.

@item  UserRead
@itemx GroupRead
@itemx OtherRead
True if the user (group; other users) has read permission for @var{file}.

@item  UserWrite
@itemx GroupWrite
@itemx OtherWrite
True if the user (group; other users) has write permission for @var{file}.

@item  UserExecute
@itemx GroupExecute
@itemx OtherExecute
True if the user (group; other users) has execute permission for @var{file}.
@end table

If an attribute does not apply (i.e., archive on a Unix system) then the
field is set to NaN.

With no input arguments, return information about the current directory.

If @var{file} contains globbing characters, return information about all
the matching files.
@seealso{glob}
@end deftypefn
fileparts
@c fileparts scripts/miscellaneous/fileparts.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{dir}, @var{name}, @var{ext}] =} fileparts (@var{filename})
Return the directory, name, and extension components of @var{filename}.

The input @var{filename} is a string which is parsed.  There is no attempt
to check whether the filename or directory specified actually exists.
@seealso{fullfile, filesep}
@end deftypefn
fullfile
@c fullfile scripts/miscellaneous/fullfile.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{filename} =} fullfile (@var{dir1}, @var{dir2}, @dots{}, @var{file})
@deftypefnx {Function File} {@var{filenames} =} fullfile (@dots{}, @var{files})
Build complete filename from separate parts.

Joins any number of path components intelligently.  The return value is
the concatenation of each component with exactly one file separator
between each non empty part and at most one leading and/or trailing file
separator.

If the last component part is a cell array, returns a cell array of
filepaths, one for each element in the last component, e.g.:

@example
@group
fullfile ("/home/username", "data", @{"f1.csv", "f2.csv", "f3.csv"@})
@result{}  /home/username/data/f1.csv
    /home/username/data/f2.csv
    /home/username/data/f3.csv
@end group
@end example

On Windows systems, while forward slash file separators do work, they are
replaced by backslashes; in addition drive letters are stripped of leading
file separators to obtain a valid file path.

@seealso{fileparts, filesep}
@end deftypefn
genvarname
@c genvarname scripts/miscellaneous/genvarname.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{varname} =} genvarname (@var{str})
@deftypefnx {Function File} {@var{varname} =} genvarname (@var{str}, @var{exclusions})
Create valid unique variable name(s) from @var{str}.

If @var{str} is a cellstr, then a unique variable is created for each cell
in @var{str}.

@example
@group
genvarname (@{"foo", "foo"@})
  @result{}
     @{
       [1,1] = foo
       [1,2] = foo1
     @}
@end group
@end example

If @var{exclusions} is given, then the variable(s) will be unique to each
other and to @var{exclusions} (@var{exclusions} may be either a string or a
cellstr).

@example
@group
x = 3.141;
genvarname ("x", who ())
  @result{} x1
@end group
@end example

Note that the result is a char array or cell array of strings, not the
variables themselves.  To define a variable, @code{eval()} can be used.
The following trivial example sets @code{x} to @code{42}.

@example
@group
name = genvarname ("x");
eval ([name " = 42"]);
  @result{} x =  42
@end group
@end example

This can be useful for creating unique struct field names.

@example
@group
x = struct ();
for i = 1:3
  x.(genvarname ("a", fieldnames (x))) = i;
endfor
  @result{} x =
     @{
       a =  1
       a1 =  2
       a2 =  3
     @}
@end group
@end example

Since variable names may only contain letters, digits, and underscores,
@code{genvarname} will replace any sequence of disallowed characters with
an underscore.  Also, variables may not begin with a digit; in this case
an @samp{x} is added before the variable name.

Variable names beginning and ending with two underscores @qcode{"__"} are
valid, but they are used internally by Octave and should generally be
avoided; therefore, @code{genvarname} will not generate such names.

@code{genvarname} will also ensure that returned names do not clash with
keywords such as @qcode{"for"} and @qcode{"if"}.  A number will be
appended if necessary.  Note, however, that this does @strong{not} include
function names such as @qcode{"sin"}.  Such names should be included in
@var{exclusions} if necessary.
@seealso{isvarname, iskeyword, exist, who, tempname, eval}
@end deftypefn
getappdata
@c getappdata scripts/miscellaneous/getappdata.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{value} =} getappdata (@var{h}, @var{name})
@deftypefnx {Function File} {@var{appdata} =} getappdata (@var{h})
Return the @var{value} of the application data @var{name} for the graphics
object with handle @var{h}.

@var{h} may also be a vector of graphics handles.  If no second argument
@var{name} is given then @code{getappdata} returns a structure,
@var{appdata}, whose fields correspond to the appdata properties.

@seealso{setappdata, isappdata, rmappdata, guidata, get, set, getpref, setpref}
@end deftypefn
getfield
@c getfield scripts/miscellaneous/getfield.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{val} =} getfield (@var{s}, @var{field})
@deftypefnx {Function File} {@var{val} =} getfield (@var{s}, @var{sidx1}, @var{field1}, @var{fidx1}, @dots{})
Get the value of the field named @var{field} from a structure or nested
structure @var{s}.

If @var{s} is a structure array then @var{sidx} selects an element of the
structure array, @var{field} specifies the field name of the selected
element, and @var{fidx} selects which element of the field (in the case of
an array or cell array).  See @code{setfield} for a more complete
description of the syntax.

@seealso{setfield, rmfield, orderfields, isfield, fieldnames, isstruct, struct}
@end deftypefn
gunzip
@c gunzip scripts/miscellaneous/gunzip.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{filelist} =} gunzip (@var{gzfile})
@deftypefnx {Function File} {@var{filelist} =} gunzip (@var{gzfile}, @var{dir})
Unpack the gzip archive @var{gzfile}.

If @var{gzfile} is a directory, all gzfiles in the directory will be
recursively unpacked.

If @var{dir} is specified the files are unpacked in this directory rather
than the one where @var{gzfile} is located.

The optional output @var{filelist} is a list of the uncompressed files.
@seealso{gzip, unpack, bunzip2, unzip, untar}
@end deftypefn
gzip
@c gzip scripts/miscellaneous/gzip.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{filelist} =} gzip (@var{files})
@deftypefnx {Function File} {@var{filelist} =} gzip (@var{files}, @var{dir})
Compress the list of files and directories specified in @var{files}.

@var{files} is a character array or cell array of strings.  Shell wildcards
in the filename such as @samp{*} or @samp{?} are accepted and expanded.
Each file is compressed separately and a new file with a @file{".gz"}
extension is created.  The original files are not modified, but existing
compressed files will be silently overwritten.  If a directory is
specified then @code{gzip} recursively compresses all files in the
directory.

If @var{dir} is defined the compressed files are placed in this directory,
rather than the original directory where the uncompressed file resides.
If @var{dir} does not exist it is created.

The optional output @var{filelist} is a list of the compressed files.
@seealso{gunzip, unpack, bzip2, zip, tar}
@end deftypefn
info
@c info scripts/miscellaneous/info.m
-*- texinfo -*-
@deftypefn {Function File} {} info ()
Display contact information for the GNU Octave community.
@end deftypefn
inputname
@c inputname scripts/miscellaneous/inputname.m
-*- texinfo -*-
@deftypefn {Function File} {} inputname (@var{n})
Return the name of the @var{n}-th argument to the calling function.

If the argument is not a simple variable name, return an empty string.
@code{inputname} may only be used within a function body, not at the
command line.
@seealso{nargin, nthargout}
@end deftypefn
isappdata
@c isappdata scripts/miscellaneous/isappdata.m
-*- texinfo -*-
@deftypefn {Function File} {@var{valid} =} isappdata (@var{h}, @var{name})
Return true if the named application data, @var{name}, exists for the
graphics object with handle @var{h}.

@var{h} may also be a vector of graphics handles.
@seealso{getappdata, setappdata, rmappdata, guidata, get, set, getpref, setpref}
@end deftypefn
isdeployed
@c isdeployed scripts/miscellaneous/isdeployed.m
-*- texinfo -*-
@deftypefn {Function File} {} isdeployed ()
Return true if the current program has been compiled and is running
separately from the Octave interpreter and false if it is running in
the Octave interpreter.

Currently, this function always returns false in Octave.
@end deftypefn
ismac
@c ismac scripts/miscellaneous/ismac.m
-*- texinfo -*-
@deftypefn {Function File} {} ismac ()
Return true if Octave is running on a Mac OS X system and false otherwise.
@seealso{isunix, ispc}
@end deftypefn
ispc
@c ispc scripts/miscellaneous/ispc.m
-*- texinfo -*-
@deftypefn {Function File} {} ispc ()
Return true if Octave is running on a Windows system and false otherwise.
@seealso{isunix, ismac}
@end deftypefn
isunix
@c isunix scripts/miscellaneous/isunix.m
-*- texinfo -*-
@deftypefn {Function File} {} isunix ()
Return true if Octave is running on a Unix-like system and false otherwise.
@seealso{ismac, ispc}
@end deftypefn
license
@c license scripts/miscellaneous/license.m
-*- texinfo -*-
@deftypefn  {Command} {} license
@deftypefnx {Command} {} license inuse
@deftypefnx {Command} {} license inuse @var{feature}
@deftypefnx {Function File} {} license ("inuse")
@deftypefnx {Function File} {@var{retval} =} license ("inuse")
@deftypefnx {Function File} {@var{retval} =} license ("test", @var{feature})
@deftypefnx {Function File} {@var{retval} =} license ("checkout", @var{feature})
@deftypefnx {Function File} {[@var{retval}, @var{errmsg}] =} license ("checkout", @var{feature})
Get license information for Octave and Octave packages.

GNU Octave is free software distributed under the GNU General Public
License (GPL), and a license manager makes no sense.  This function is
provided only for @sc{matlab} compatibility.

When called with no extra input arguments, it returns the Octave license,
otherwise the first input defines the operation mode and must be one of
the following strings: @code{inuse}, @code{test}, and @code{checkout}.
The optional @var{feature} argument can either be @qcode{"octave"} (core),
or an Octave package.

@table @asis
@item @qcode{"inuse"}
Returns a list of loaded features, i.e., octave and the list of loaded
packages.  If an output is requested, it returns a struct array with
the fields @qcode{"feature"}, and @qcode{"user"}.

@item @qcode{"test"}
Return true if the specified @var{feature} is installed, false otherwise.

An optional third argument @qcode{"enable"} or @qcode{"disable"} is
accepted but ignored.

@item @qcode{"checkout"}
Return true if the specified @var{feature} is installed, false otherwise.
An optional second output will have an error message if a package is not
installed.

@end table

@seealso{pkg, ver, version}
@end deftypefn
list_primes
@c list_primes scripts/miscellaneous/list_primes.m
-*- texinfo -*-
@deftypefn  {Function File} {} list_primes ()
@deftypefnx {Function File} {} list_primes (@var{n})
List the first @var{n} primes.

If @var{n} is unspecified, the first 25 primes are listed.
@seealso{primes, isprime}
@end deftypefn
ls
@c ls scripts/miscellaneous/ls.m
-*- texinfo -*-
@deftypefn  {Command} {} ls
@deftypefnx {Command} {} ls @var{filenames}
@deftypefnx {Command} {} ls @var{options}
@deftypefnx {Command} {} ls @var{options} @var{filenames}
@deftypefnx {Function File} {@var{list} =} ls (@dots{})

List directory contents.

The @code{ls} command is implemented by calling the native operating
system's directory listing command---available @var{options} will vary from
system to system.

Filenames are subject to shell expansion if they contain any wildcard
characters @samp{*}, @samp{?}, @samp{[]}.  To find a literal example of a
wildcard character the wildcard must be escaped using the backslash operator
@samp{\}.

If the optional output @var{list} is requested then @code{ls} returns a
character array with one row for each file/directory name.

Example usage on a UNIX-like system:

@example
@group
ls -l
     @print{} total 12
     @print{} -rw-r--r--   1 jwe  users  4488 Aug 19 04:02 foo.m
     @print{} -rw-r--r--   1 jwe  users  1315 Aug 17 23:14 bar.m
@end group
@end example

@seealso{dir, readdir, glob, what, stat, filesep, ls_command}
@end deftypefn
ls_command
@c ls_command scripts/miscellaneous/ls_command.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{val} =} ls_command ()
@deftypefnx {Function File} {@var{old_val} =} ls_command (@var{new_val})
Query or set the shell command used by Octave's @code{ls} command.
@seealso{ls}
@end deftypefn
menu
@c menu scripts/miscellaneous/menu.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{choice} =} menu (@var{title}, @var{opt1}, @dots{})
@deftypefnx {Function File} {@var{choice} =} menu (@var{title}, @{@var{opt1}, @dots{}@})
Display a menu with heading @var{title} and options @var{opt1}, @dots{},
and wait for user input.

If the GUI is running, or Java is available, the menu is displayed
graphically using @code{listdlg}.  Otherwise, the title and menu options
are printed on the console.

@var{title} is a string and the options may be input as individual strings
or as a cell array of strings.

The return value @var{choice} is the number of the option selected by the
user counting from 1.

This function is useful for interactive programs.  There is no limit to the
number of options that may be passed in, but it may be confusing to present
more than will fit easily on one screen.
@seealso{input, listdlg}
@end deftypefn
mex
@c mex scripts/miscellaneous/mex.m
-*- texinfo -*-
@deftypefn {Command} {} mex [options] file @dots{}
Compile source code written in C, C++, or Fortran, to a MEX file.

This is equivalent to @code{mkoctfile --mex [options] file}.
@seealso{mkoctfile, mexext}
@end deftypefn
mexext
@c mexext scripts/miscellaneous/mexext.m
-*- texinfo -*-
@deftypefn {Function File} {} mexext ()
Return the filename extension used for MEX files.
@seealso{mex}
@end deftypefn
mkoctfile
@c mkoctfile scripts/miscellaneous/mkoctfile.m
-*- texinfo -*-
@deftypefn  {Command} {} mkoctfile [-options] file @dots{}
@deftypefnx {Function File} {[@var{output}, @var{status}] =} mkoctfile (@dots{})

The @code{mkoctfile} function compiles source code written in C, C++, or
Fortran.  Depending on the options used with @code{mkoctfile}, the
compiled code can be called within Octave or can be used as a stand-alone
application.

@code{mkoctfile} can be called from the shell prompt or from the Octave
prompt.  Calling it from the Octave prompt simply delegates the call to
the shell prompt.  The output is stored in the @var{output} variable and
the exit status in the @var{status} variable.

@code{mkoctfile} accepts the following options, all of which are optional
except for the file name of the code you wish to compile:

@table @samp
@item -I DIR
Add the include directory DIR to compile commands.

@item -D DEF
Add the definition DEF to the compiler call.

@item -l LIB
Add the library LIB to the link command.

@item -L DIR
Add the library directory DIR to the link command.

@item  -M
@itemx --depend
Generate dependency files (.d) for C and C++ source files.

@item -R DIR
Add the run-time path to the link command.

@item @nospell{-Wl,@dots{}}
Pass flags though the linker like @nospell{"-Wl,-rpath=@dots{}"}.
The quotes are needed since commas are interpreted as command
separators.

@item -W@dots{}
Pass flags though the compiler like @nospell{"-Wa,OPTION"}.

@item -c
Compile but do not link.

@item -g
Enable debugging options for compilers.

@item  -o FILE
@itemx --output FILE
Output file name.  Default extension is .oct (or .mex if @samp{--mex} is
specified) unless linking a stand-alone executable.

@item  -p VAR
@itemx --print VAR
Print the configuration variable VAR@.  Recognized variables are:

@example
   ALL_CFLAGS                  INCFLAGS
   ALL_CXXFLAGS                INCLUDEDIR
   ALL_FFLAGS                  LAPACK_LIBS
   ALL_LDFLAGS                 LD_CXX
   AR                          LDFLAGS
   BLAS_LIBS                   LD_STATIC_FLAG
   CC                          LFLAGS
   CFLAGS                      LIBDIR
   CPICFLAG                    LIBOCTAVE
   CPPFLAGS                    LIBOCTINTERP
   CXX                         LIBS
   CXXFLAGS                    OCTAVE_HOME
   CXXPICFLAG                  OCTAVE_LIBS
   DEPEND_EXTRA_SED_PATTERN    OCTAVE_LINK_DEPS
   DEPEND_FLAGS                OCTAVE_LINK_OPTS
   DL_LD                       OCTAVE_PREFIX
   DL_LDFLAGS                  OCTINCLUDEDIR
   F77                         OCTLIBDIR
   F77_INTEGER8_FLAG           OCT_LINK_DEPS
   FFLAGS                      OCT_LINK_OPTS
   FFTW3F_LDFLAGS              RANLIB
   FFTW3F_LIBS                 RDYNAMIC_FLAG
   FFTW3_LDFLAGS               READLINE_LIBS
   FFTW3_LIBS                  SED
   FFTW_LIBS                   SPECIAL_MATH_LIB
   FLIBS                       XTRA_CFLAGS
   FPICFLAG                    XTRA_CXXFLAGS
@end example

@item --link-stand-alone
Link a stand-alone executable file.

@item --mex
Assume we are creating a MEX file.  Set the default output extension to
".mex".

@item  -s
@itemx --strip
Strip the output file.

@item  -v
@itemx --verbose
Echo commands as they are executed.

@item file
The file to compile or link.  Recognized file types are

@example
@group
   .c    C source
   .cc   C++ source
   .C    C++ source
   .cpp  C++ source
   .f    Fortran source (fixed form)
   .F    Fortran source (fixed form)
   .f90  Fortran source (free form)
   .F90  Fortran source (free form)
   .o    object file
   .a    library file
@end group
@end example

@end table
@end deftypefn
movefile
@c movefile scripts/miscellaneous/movefile.m
-*- texinfo -*-
@deftypefn  {Function File} {} movefile (@var{f1})
@deftypefnx {Function File} {} movefile (@var{f1}, @var{f2})
@deftypefnx {Function File} {} movefile (@var{f1}, @var{f2}, 'f')
@deftypefnx {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} movefile (@dots{})
Move the source files or directories @var{f1} to the destination @var{f2}.

The name @var{f1} may contain globbing patterns.  If @var{f1} expands to
multiple file names, @var{f2} must be a directory.  If no destination
@var{f2} is specified then the destination is the present working directory.
If @var{f2} is a file name then @var{f1} is renamed to @var{f2}.

When the force flag @qcode{'f'} is given any existing files will be
overwritten without prompting.

If successful, @var{status} is 1, and @var{msg}, @var{msgid} are empty
character strings ("").  Otherwise, @var{status} is 0, @var{msg} contains a
system-dependent error message, and @var{msgid} contains a unique message
identifier.  Note that the status code is exactly opposite that of the
@code{system} command.
@seealso{rename, copyfile, unlink, delete, glob}
@end deftypefn
namelengthmax
@c namelengthmax scripts/miscellaneous/namelengthmax.m
-*- texinfo -*-
@deftypefn {Function File} {} namelengthmax ()
Return the @sc{matlab} compatible maximum variable name length.

Octave is capable of storing strings up to @math{2^{31} - 1} in length.
However for @sc{matlab} compatibility all variable, function, and structure
field names should be shorter than the length returned by
@code{namelengthmax}.  In particular, variables stored to a @sc{matlab} file
format (@file{*.mat}) will have their names truncated to this length.
@end deftypefn
news
@c news scripts/miscellaneous/news.m
-*- texinfo -*-
@deftypefn  {Command} {} news
@deftypefnx {Command} {} news @var{package}
Display the current NEWS file for Octave or an installed package.

When called without an argument, display the NEWS file for Octave.

When given a package name @var{package}, display the current NEWS file for
that package.
@seealso{ver, pkg}
@end deftypefn
open
@c open scripts/miscellaneous/open.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{output} =} open @var{file}
@deftypefnx {Function File} {@var{output} =} open (@var{file})
Open the file @var{file} in Octave or in an external application based on
the file type as determined by the file name extension.

Recognized file types are

@table @code
@item .m
Open file in the editor.

@item .mat
Load the file in the base workspace.

@item .exe
Execute the program (on Windows systems only).
@end table

Other file types are opened in the appropriate external application.
@end deftypefn
orderfields
@c orderfields scripts/miscellaneous/orderfields.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{sout}] =} orderfields (@var{s1})
@deftypefnx {Function File} {@var{sout}] =} orderfields (@var{s1}, @var{s2})
@deftypefnx {Function File} {@var{sout}] =} orderfields (@var{s1}, @{@var{cellstr}@})
@deftypefnx {Function File} {@var{sout}] =} orderfields (@var{s1}, @var{p})
@deftypefnx {Function File} {[@var{sout}, @var{p}] =} orderfields (@dots{})
Return a @emph{copy} of @var{s1} with fields arranged alphabetically, or as
specified by the second input.

Given one input struct @var{s1}, arrange field names alphabetically.

If a second struct argument is given, arrange field names in @var{s1} as they
appear in @var{s2}.  The second argument may also specify the order in a
cell array of strings @var{cellstr}.  The second argument may also be a
permutation vector.

The optional second output argument @var{p} is the permutation vector which
converts the original name order to the new name order.

Examples:

@example
@group
s = struct ("d", 4, "b", 2, "a", 1, "c", 3);
t1 = orderfields (s)
     @result{} t1 =
        @{
          a =  1
          b =  2
          c =  3
          d =  4
        @}
@end group
@group
t = struct ("d", @{@}, "c", @{@}, "b", @{@}, "a", @{@});
t2 = orderfields (s, t)
     @result{} t2 =
        @{
          d =  4
          c =  3
          b =  2
          a =  1
        @}
@end group
@group
t3 = orderfields (s, [3, 2, 4, 1])
     @result{} t3 =
        @{
          a =  1
          b =  2
          c =  3
          d =  4
        @}
@end group
@group
[t4, p] = orderfields (s, @{"d", "c", "b", "a"@})
     @result{} t4 =
        @{
          d =  4
          c =  3
          b =  2
          a =  1
        @}
        p =
           1
           4
           2
           3
@end group
@end example

@seealso{fieldnames, getfield, setfield, rmfield, isfield, isstruct, struct}
@end deftypefn
pack
@c pack scripts/miscellaneous/pack.m
-*- texinfo -*-
@deftypefn {Function File} {} pack ()
Consolidate workspace memory in @sc{matlab}.

This function is provided for compatibility, but does nothing in Octave.
@seealso{clear}
@end deftypefn
paren
@c paren scripts/miscellaneous/paren.m
-*- texinfo -*-
@deftypefn  {Operator} {} (
@deftypefnx {Operator} {} )
Array index or function argument delimeter.
@end deftypefn
parseparams
@c parseparams scripts/miscellaneous/parseparams.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{reg}, @var{prop}] =} parseparams (@var{params})
@deftypefnx {Function File} {[@var{reg}, @var{var1}, @dots{}] =} parseparams (@var{params}, @var{name1}, @var{default1}, @dots{})
Return in @var{reg} the cell elements of @var{param} up to the first
string element and in @var{prop} all remaining elements beginning with the
first string element.

For example:

@example
@group
[reg, prop] = parseparams (@{1, 2, "linewidth", 10@})
reg =
@{
  [1,1] = 1
  [1,2] = 2
@}
prop =
@{
  [1,1] = linewidth
  [1,2] = 10
@}
@end group
@end example

The parseparams function may be used to separate regular numeric arguments
from additional arguments given as property/value pairs of the
@var{varargin} cell array.

In the second form of the call, available options are specified directly
with their default values given as name-value pairs.  If @var{params} do
not form name-value pairs, or if an option occurs that does not match any
of the available options, an error occurs.

When called from an m-file function, the error is prefixed with the name
of the caller function.

The matching of options is case-insensitive.

@seealso{varargin, inputParser}
@end deftypefn
perl
@c perl scripts/miscellaneous/perl.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{output} =} perl (@var{scriptfile})
@deftypefnx {Function File} {@var{output} =} perl (@var{scriptfile}, @var{argument1}, @var{argument2}, @dots{})
@deftypefnx {Function File} {[@var{output}, @var{status}] =} perl (@dots{})
Invoke Perl script @var{scriptfile}, possibly with a list of command line
arguments.

Return output in @var{output} and optional status in @var{status}.  If
@var{scriptfile} is not an absolute file name it is searched for in the
current directory and then in the Octave loadpath.
@seealso{system, python}
@end deftypefn
python
@c python scripts/miscellaneous/python.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{output} =} python (@var{scriptfile})
@deftypefnx {Function File} {@var{output} =} python (@var{scriptfile}, @var{argument1}, @var{argument2}, @dots{})
@deftypefnx {Function File} {[@var{output}, @var{status}] =} python (@dots{})
Invoke Python script @var{scriptfile}, possibly with a list of command line
arguments.

Return output in @var{output} and optional status in @var{status}.  If
@var{scriptfile} is not an absolute file name it is searched for in the
current directory and then in the Octave loadpath.
@seealso{system, perl}
@end deftypefn
recycle
@c recycle scripts/miscellaneous/recycle.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{current_state} =} recycle ()
@deftypefnx {Function File} {@var{old_state} =} recycle (@var{new_state})
Query or set the preference for recycling deleted files.

When recycling is enabled, commands which would permanently erase files
instead move them to a temporary location (such as the directory labeled
Trash).

Programming Note: This function is provided for @sc{matlab} compatibility,
but recycling is not implemented in Octave.  To help avoid accidental data
loss an error will be raised if an attempt is made to enable file recycling.
@seealso{delete, rmdir}
@end deftypefn
rmappdata
@c rmappdata scripts/miscellaneous/rmappdata.m
-*- texinfo -*-
@deftypefn  {Function File} {} rmappdata (@var{h}, @var{name})
@deftypefnx {Function File} {} rmappdata (@var{h}, @var{name1}, @var{name2}, @dots{})
Delete the application data @var{name} from the graphics object with handle
@var{h}.

@var{h} may also be a vector of graphics handles.  Multiple application data
names may be supplied to delete several properties at once.

@seealso{setappdata, getappdata, isappdata}
@end deftypefn
run
@c run scripts/miscellaneous/run.m
-*- texinfo -*-
@deftypefn  {Command} {} run @var{script}
@deftypefnx {Function File} {} run ("@var{script}")
Run @var{script} in the current workspace.

Scripts which reside in directories specified in Octave's load path, and
which end with the extension @file{".m"}, can be run simply by typing
their name.  For scripts not located on the load path, use @code{run}.

The file name @var{script} can be a bare, fully qualified, or relative
filename and with or without a file extension.  If no extension is specified,
Octave will first search for a script with the @file{".m"} extension before
falling back to the script name without an extension.

Implementation Note: If @var{script} includes a path component, then
@code{run} first changes the working directory to the directory where
@var{script} is found.  Next, the script is executed.  Finally, @code{run}
returns to the original working directory unless @code{script} has
specifically changed directories.
@seealso{path, addpath, source}
@end deftypefn
semicolon
@c semicolon scripts/miscellaneous/semicolon.m
-*- texinfo -*-
@deftypefn {Operator} {} ;
Array row or command separator.
@seealso{comma}
@end deftypefn
setappdata
@c setappdata scripts/miscellaneous/setappdata.m
-*- texinfo -*-
@deftypefn  {Function File} {} setappdata (@var{h}, @var{name}, @var{value})
@deftypefnx {Function File} {} setappdata (@var{h}, @var{name1}, @var{value1}, @var{name2}, @var{value3}, @dots{})
Set the application data @var{name} to @var{value} for the graphics object
with handle @var{h}.

@var{h} may also be a vector of graphics handles.  If the application data
with the specified @var{name} does not exist, it is created.  Multiple
@var{name}/@var{value} pairs can be specified at a time.

@seealso{getappdata, isappdata, rmappdata, guidata, get, set, getpref, setpref}
@end deftypefn
setfield
@c setfield scripts/miscellaneous/setfield.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{sout} =} setfield (@var{s}, @var{field}, @var{val})
@deftypefnx {Function File} {@var{sout} =} setfield (@var{s}, @var{sidx1}, @var{field1}, @var{fidx1}, @var{sidx2}, @var{field2}, @var{fidx2}, @dots{}, @var{val})

Return a @emph{copy} of the structure @var{s} with the field member
@var{field} set to the value @var{val}.

For example:

@example
@group
@var{s} = struct ();
@var{s} = setfield (@var{s}, "foo bar", 42);
@end group
@end example

@noindent
This is equivalent to

@example
@var{s}.("foo bar") = 42;
@end example

@noindent
Note that ordinary structure syntax @code{@var{s}.foo bar = 42} cannot be
used here, as the field name is not a valid Octave identifier because of
the space character.  Using arbitrary strings for field names is
incompatible with @sc{matlab}, and this usage will emit a warning if the
warning ID @code{Octave:language-extension} is enabled.
@xref{XREFwarning_ids}.

With the second calling form, set a field of a structure array.  The
input @var{sidx} selects an element of the structure array, @var{field}
specifies the field name of the selected element, and @var{fidx} selects
which element of the field (in the case of an array or cell array).
The @var{sidx}, @var{field}, and @var{fidx} inputs can be repeated to
address nested structure array elements.  The structure array index and
field element index must be cell arrays while the field name must be a
string.

For example:

@example
@group
@var{s} = struct ("baz", 42);
setfield (@var{s}, @{1@}, "foo", @{1@}, "bar", 54)
@result{}
  ans =
    scalar structure containing the fields:
      baz =  42
      foo =
        scalar structure containing the fields:
          bar =  54
@end group
@end example

The example begins with an ordinary scalar structure to which a nested
scalar structure is added.  In all cases, if the structure index @var{sidx}
is not specified it defaults to 1 (scalar structure).  Thus, the example
above could be written more concisely as
@code{setfield (@var{s}, "foo", "bar", 54)}

Finally, an example with nested structure arrays:

@example
@group
@var{sa}.foo = 1;
@var{sa} = setfield (@var{sa}, @{2@}, "bar", @{3@}, "baz", @{1, 4@}, 5);
@var{sa}(2).bar(3)
@result{}
  ans =
    scalar structure containing the fields:
      baz =  0   0   0   5
@end group
@end example

Here @var{sa} is a structure array whose field at elements 1 and 2 is in
turn another structure array whose third element is a simple scalar
structure.  The terminal scalar structure has a field which contains a
matrix value.

Note that the same result as in the above example could be achieved by:

@example
@group
@var{sa}.foo = 1;
@var{sa}(2).bar(3).baz(1,4) = 5
@end group
@end example
@seealso{getfield, rmfield, orderfields, isfield, fieldnames, isstruct, struct}
@end deftypefn
substruct
@c substruct scripts/miscellaneous/substruct.m
-*- texinfo -*-
@deftypefn {Function File} {} substruct (@var{type}, @var{subs}, @dots{})
Create a subscript structure for use with @code{subsref} or @code{subsasgn}.

For example:

@example
@group
idx = substruct ("()", @{3, ":"@})
     @result{}
       idx =
       @{
         type = ()
         subs =
         @{
           [1,1] =  3
           [1,2] = :
         @}
       @}
x = [1, 2, 3;
     4, 5, 6;
     7, 8, 9];
subsref (x, idx)
   @result{} 7  8  9
@end group
@end example
@seealso{subsref, subsasgn}
@end deftypefn
swapbytes
@c swapbytes scripts/miscellaneous/swapbytes.m
-*- texinfo -*-
@deftypefn {Function File} {} swapbytes (@var{x})
Swap the byte order on values, converting from little endian to big endian
and vice versa.

For example:

@example
@group
swapbytes (uint16 (1:4))
@result{} [   256   512   768  1024]
@end group
@end example

@seealso{typecast, cast}
@end deftypefn
symvar
@c symvar scripts/miscellaneous/symvar.m
-*- texinfo -*-
@deftypefn {Function File} {@var{vars} =} symvar (@var{str})
Identify the symbolic variable names in the string @var{str}.

Common constant names such as @code{i}, @code{j}, @code{pi}, @code{Inf} and
Octave functions such as @code{sin} or @code{plot} are ignored.

Any names identified are returned in a cell array of strings.  The array is
empty if no variables were found.

Example:

@example
@group
symvar ("x^2 + y^2 == 4")
@result{} @{
     [1,1] = x
     [2,1] = y
   @}
@end group
@end example
@end deftypefn
tar
@c tar scripts/miscellaneous/tar.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{filelist} =} tar (@var{tarfile}, @var{files})
@deftypefnx {Function File} {@var{filelist} =} tar (@var{tarfile}, @var{files}, @var{rootdir})
Pack the list of files and directories specified in @var{files} into the
TAR archive @var{tarfile}.

@var{files} is a character array or cell array of strings.  Shell wildcards
in the filename such as @samp{*} or @samp{?} are accepted and expanded.
Directories are recursively traversed and all files are added to the
archive.

If @var{rootdir} is defined then any files without absolute pathnames are
located relative to @var{rootdir} rather than the current directory.

The optional output @var{filelist} is a list of the files that were included
in the archive.
@seealso{untar, unpack, bzip2, gzip, zip}
@end deftypefn
tempdir
@c tempdir scripts/miscellaneous/tempdir.m
-*- texinfo -*-
@deftypefn {Function File} {@var{dir} =} tempdir ()
Return the name of the host system's directory for temporary files.

The directory name is taken first from the environment variable
@env{TMPDIR}.  If that does not exist the system default returned by
@code{P_tmpdir} is used.
@seealso{P_tmpdir, tempname, mkstemp, tmpfile}
@end deftypefn
tmpnam
@c tmpnam scripts/miscellaneous/tmpnam.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{fname} =} tmpnam ()
@deftypefnx {Function File} {@var{fname} =} tmpnam (@var{dir})
@deftypefnx {Function File} {@var{fname} =} tmpnam (@var{dir}, @var{prefix})
Return a unique temporary file name as a string.

If @var{prefix} is omitted, a value of @qcode{"oct-"} is used.

If @var{dir} is also omitted, the default directory for temporary files
(@code{P_tmpdir} is used.  If @var{dir} is provided, it must exist,
otherwise the default directory for temporary files is used.

Programming Note: Because the named file is not opened by @code{tmpnam},
it is possible, though relatively unlikely, that it will not be available
by the time your program attempts to open it.  If this is a concern,
see @code{tmpfile}.  The functions @code{tmpnam} and @code{tempname} are
equivalent with the latter provided for @sc{matlab} compatibility.

@strong{Caution}: @code{tmpnam} will be removed in a future version of
Octave.  Use the equivalent @code{tempname} in all new code.
@seealso{tempname, mkstemp, tempdir, P_tmpdir, tmpfile}
@end deftypefn
unix
@c unix scripts/miscellaneous/unix.m
-*- texinfo -*-
@deftypefn  {Function File} {} unix ("@var{command}")
@deftypefnx {Function File} {@var{status} =} unix ("@var{command}")
@deftypefnx {Function File} {[@var{status}, @var{text}] =} unix ("@var{command}")
@deftypefnx {Function File} {[@dots{}] =} unix ("@var{command}", "-echo")
Execute a system command if running under a Unix-like operating system,
otherwise do nothing.

Octave waits for the external command to finish before returning the exit
status of the program in @var{status} and any output in @var{text}.

When called with no output argument, or the @qcode{"-echo"} argument is
given, then @var{text} is also sent to standard output.
@seealso{dos, system, isunix, ismac, ispc}
@end deftypefn
unpack
@c unpack scripts/miscellaneous/unpack.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{files} =} unpack (@var{file})
@deftypefnx {Function File} {@var{files} =} unpack (@var{file}, @var{dir})
@deftypefnx {Function File} {@var{files} =} unpack (@var{file}, @var{dir}, @var{filetype})
Unpack the archive @var{file} based on its extension to the directory
@var{dir}.

If @var{file} is a list of strings, then each file is unpacked
individually.  Shell wildcards in the filename such as @samp{*} or
@samp{?} are accepted and expanded.

If @var{dir} is not specified or is empty (@code{[]}), it defaults to the
current directory.  If a directory is in the file list, then @var{filetype}
must also be specified.

The specific archive filetype is inferred from the extension of the file.
The @var{filetype} may also be specified directly using a string which
corresponds to a known extension.

Valid filetype extensions:

@table @code
@item  bz
@itemx bz2
bzip archive

@item gz
gzip archive

@item tar
tar archive

@item  tarbz
@itemx tarbz2
@itemx tbz
@itemx tbz2
tar + bzip archive

@item  targz
@itemx tgz
tar + gzip archive

@item z
compress archive

@item zip
zip archive
@end table

The optional return value is a list of @var{files} unpacked.
@seealso{bunzip2, gunzip, unzip, untar, bzip2, gzip, zip, tar}
@end deftypefn
untar
@c untar scripts/miscellaneous/untar.m
-*- texinfo -*-
@deftypefn  {Function File} {} untar (@var{tarfile})
@deftypefnx {Function File} {} untar (@var{tarfile}, @var{dir})
Unpack the TAR archive @var{tarfile}.

If @var{dir} is specified the files are unpacked in this directory rather
than the one where @var{tarfile} is located.

The optional output @var{filelist} is a list of the uncompressed files.
@seealso{tar, unpack, bunzip2, gunzip, unzip}
@end deftypefn
unzip
@c unzip scripts/miscellaneous/unzip.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{filelist} =} unzip (@var{zipfile})
@deftypefnx {Function File} {@var{filelist} =} unzip (@var{zipfile}, @var{dir})
Unpack the ZIP archive @var{zipfile}.

If @var{dir} is specified the files are unpacked in this directory rather
than the one where @var{zipfile} is located.

The optional output @var{filelist} is a list of the uncompressed files.
@seealso{zip, unpack, bunzip2, gunzip, untar}
@end deftypefn
ver
@c ver scripts/miscellaneous/ver.m
-*- texinfo -*-
@deftypefn  {Function File} {} ver
@deftypefnx {Function File} {} ver Octave
@deftypefnx {Function File} {} ver @var{package}
@deftypefnx {Function File} {v =} ver (@dots{})

Display a header containing the current Octave version number, license
string, and operating system.  The header is followed by a list of installed
packages, versions, and installation directories.

Use the package name @var{package} or Octave to limit the listing to a
desired component.

When called with an output argument, return a vector of structures
describing Octave and each installed package.  The structure includes the
following fields.

@table @code
@item Name
Package name.

@item Version
Version of the package.

@item Revision
Revision of the package.

@item Date
Date of the version/revision.
@end table

@seealso{version, octave_config_info, usejava, pkg}
@end deftypefn
version
@c version scripts/miscellaneous/version.m
-*- texinfo -*-
@deftypefn {Function File} {} version ()
Return the version number of Octave as a string.

This is an alias for the function @w{@env{OCTAVE_VERSION}} provided for
compatibility.
@seealso{OCTAVE_VERSION, ver}
@end deftypefn
warning_ids
@c warning_ids scripts/miscellaneous/warning_ids.m
-*- texinfo -*-
@cindex warning ids

@table @code
@item Octave:abbreviated-property-match
By default, the @code{Octave:abbreviated-property-match} warning is enabled.

@item Octave:array-to-scalar
If the @code{Octave:array-to-scalar} warning is enabled, Octave will
warn when an implicit conversion from an array to a scalar value is
attempted.
By default, the @code{Octave:array-to-scalar} warning is disabled.

@item Octave:array-to-vector
If the @code{Octave:array-to-vector} warning is enabled, Octave will
warn when an implicit conversion from an array to a vector value is
attempted.
By default, the @code{Octave:array-to-vector} warning is disabled.

@item Octave:assign-as-truth-value
If the @code{Octave:assign-as-truth-value} warning is
enabled, a warning is issued for statements like

@example
@group
if (s = t)
  @dots{}
@end group
@end example

@noindent
since such statements are not common, and it is likely that the intent
was to write

@example
@group
if (s == t)
  @dots{}
@end group
@end example

@noindent
instead.

There are times when it is useful to write code that contains
assignments within the condition of a @code{while} or @code{if}
statement.  For example, statements like

@example
@group
while (c = getc ())
  @dots{}
@end group
@end example

@noindent
are common in C programming.

It is possible to avoid all warnings about such statements by
disabling the @code{Octave:assign-as-truth-value} warning,
but that may also let real errors like

@example
@group
if (x = 1)  # intended to test (x == 1)!
  @dots{}
@end group
@end example

@noindent
slip by.

In such cases, it is possible suppress errors for specific statements by
writing them with an extra set of parentheses.  For example, writing the
previous example as

@example
@group
while ((c = getc ()))
  @dots{}
@end group
@end example

@noindent
will prevent the warning from being printed for this statement, while
allowing Octave to warn about other assignments used in conditional
contexts.

By default, the @code{Octave:assign-as-truth-value} warning is enabled.

@item Octave:associativity-change
If the @code{Octave:associativity-change} warning is
enabled, Octave will warn about possible changes in the meaning of
some code due to changes in associativity for some operators.
Associativity changes have typically been made for @sc{matlab}
compatibility.
By default, the @code{Octave:associativity-change} warning is enabled.

@item Octave:autoload-relative-file-name
If the @code{Octave:autoload-relative-file-name} is enabled,
Octave will warn when parsing autoload() function calls with relative
paths to function files.  This usually happens when using autoload()
calls in PKG_ADD files, when the PKG_ADD file is not in the same
directory as the .oct file referred to by the autoload() command.
By default, the @code{Octave:autoload-relative-file-name} warning is enabled.

@item Octave:built-in-variable-assignment
By default, the @code{Octave:built-in-variable-assignment} warning is
enabled.

@item Octave:deprecated-keyword
If the @code{Octave:deprecated-keyword} warning is enabled, a
warning is issued when Octave encounters a keyword that is obsolete and
scheduled for removal from Octave.
By default, the @code{Octave:deprecated-keyword} warning is enabled.

@item Octave:divide-by-zero
If the @code{Octave:divide-by-zero} warning is enabled, a
warning is issued when Octave encounters a division by zero.
By default, the @code{Octave:divide-by-zero} warning is enabled.

@item Octave:fopen-file-in-path
By default, the @code{Octave:fopen-file-in-path} warning is enabled.

@item Octave:function-name-clash
If the @code{Octave:function-name-clash} warning is enabled, a
warning is issued when Octave finds that the name of a function
defined in a function file differs from the name of the file.  (If
the names disagree, the name declared inside the file is ignored.)
By default, the @code{Octave:function-name-clash} warning is enabled.

@item Octave:future-time-stamp
If the @code{Octave:future-time-stamp} warning is enabled, Octave
will print a warning if it finds a function file with a time stamp
that is in the future.
By default, the @code{Octave:future-time-stamp} warning is enabled.

@item Octave:glyph-render
By default, the @code{Octave:glyph-render} warning is enabled.

@item Octave:imag-to-real
If the @code{Octave:imag-to-real} warning is enabled, a warning is
printed for implicit conversions of complex numbers to real numbers.
By default, the @code{Octave:imag-to-real} warning is disabled.

@item Octave:language-extension
Print warnings when using features that are unique to the Octave
language and that may still be missing in @sc{matlab}.
By default, the @code{Octave:language-extension} warning is disabled.
The @option{--traditional} or @option{--braindead} startup options for
Octave may also be of use, @pxref{Command Line Options}.

@item Octave:load-file-in-path
By default, the @code{Octave:load-file-in-path} warning is enabled.

@item Octave:logical-conversion
By default, the @code{Octave:logical-conversion} warning is enabled.

@item Octave:md5sum-file-in-path
By default, the @code{Octave:md5sum-file-in-path} warning is enabled.

@item Octave:missing-glyph
By default, the @code{Octave:missing-glyph} warning is enabled.

@item Octave:missing-semicolon
If the @code{Octave:missing-semicolon} warning is enabled, Octave
will warn when statements in function definitions don't end in
semicolons.
By default the @code{Octave:missing-semicolon} warning is disabled.

@item Octave:mixed-string-concat
If the @code{Octave:mixed-string-concat} warning is enabled, print a
warning when concatenating a mixture of double and single quoted strings.
By default, the @code{Octave:mixed-string-concat} warning is disabled.

@item Octave:neg-dim-as-zero
If the @code{Octave:neg-dim-as-zero} warning is enabled, print a warning
for expressions like

@example
eye (-1)
@end example

@noindent
By default, the @code{Octave:neg-dim-as-zero} warning is disabled.

@item Octave:nested-functions-coerced
By default, the @code{Octave:nested-functions-coerced} warning is enabled.

@item Octave:noninteger-range-as-index
By default, the @code{Octave:noninteger-range-as-index} warning is enabled.

@item Octave:num-to-str
If the @code{Octave:num-to-str} warning is enable, a warning is
printed for implicit conversions of numbers to their ASCII character
equivalents when strings are constructed using a mixture of strings and
numbers in matrix notation.  For example,

@example
@group
[ "f", 111, 111 ]
@result{} "foo"
@end group
@end example

@noindent
elicits a warning if the @code{Octave:num-to-str} warning is
enabled.  By default, the @code{Octave:num-to-str} warning is enabled.

@item Octave:possible-matlab-short-circuit-operator
If the @code{Octave:possible-matlab-short-circuit-operator} warning
is enabled, Octave will warn about using the not short circuiting
operators @code{&} and @code{|} inside @code{if} or @code{while}
conditions.  They normally never short circuit, but @sc{matlab} always
short circuits if any logical operators are used in a condition.  You
can turn on the option

@example
@group
do_braindead_shortcircuit_evaluation (1)
@end group
@end example

@noindent
if you would like to enable this short-circuit evaluation in
Octave.  Note that the @code{&&} and @code{||} operators always short
circuit in both Octave and @sc{matlab}, so it's only necessary to
enable @sc{matlab}-style short-circuiting if it's too arduous to modify
existing code that relies on this behavior.
By default, the @code{Octave:possible-matlab-short-circuit-operator} warning
is enabled.

@item Octave:precedence-change
If the @code{Octave:precedence-change} warning is enabled, Octave
will warn about possible changes in the meaning of some code due to
changes in precedence for some operators.  Precedence changes have
typically been made for @sc{matlab} compatibility.
By default, the @code{Octave:precedence-change} warning is enabled.

@item Octave:recursive-path-search
By default, the @code{Octave:recursive-path-search} warning is enabled.

@item Octave:remove-init-dir
The @code{path} function changes the search path that Octave uses
to find functions.  It is possible to set the path to a value which
excludes Octave's own built-in functions.  If the
@code{Octave:remove-init-dir} warning is enabled then Octave will warn
when the @code{path} function has been used in a way that may render
Octave unworkable.
By default, the @code{Octave:remove-init-dir} warning is enabled.

@item Octave:reload-forces-clear
If several functions have been loaded from the same file, Octave must
clear all the functions before any one of them can be reloaded.  If
the @code{Octave:reload-forces-clear} warning is enabled, Octave will
warn you when this happens, and print a list of the additional
functions that it is forced to clear.
By default, the @code{Octave:reload-forces-clear} warning is enabled.

@item Octave:resize-on-range-error
If the @code{Octave:resize-on-range-error} warning is enabled, print a
warning when a matrix is resized by an indexed assignment with
indices outside the current bounds.
By default, the ## @code{Octave:resize-on-range-error} warning is disabled.

@item Octave:separator-insert
Print warning if commas or semicolons might be inserted
automatically in literal matrices.
By default, the @code{Octave:separator-insert} warning is disabled.

@item Octave:shadowed-function
By default, the @code{Octave:shadowed-function} warning is enabled.

@item Octave:single-quote-string
Print warning if a single quote character is used to introduce a
string constant.
By default, the @code{Octave:single-quote-string} warning is disabled.

@item  Octave:nearly-singular-matrix
@itemx Octave:singular-matrix
By default, the @code{Octave:nearly-singular-matrix} and
@code{Octave:singular-matrix} warnings are enabled.

@item Octave:sqrtm:SingularMatrix
By default, the @code{Octave:sqrtm:SingularMatrix} warning is enabled.

@item Octave:str-to-num
If the @code{Octave:str-to-num} warning is enabled, a warning is printed
for implicit conversions of strings to their numeric ASCII equivalents.
For example,

@example
@group
"abc" + 0
@result{} 97 98 99
@end group
@end example

@noindent
elicits a warning if the @code{Octave:str-to-num} warning is enabled.
By default, the @code{Octave:str-to-num} warning is disabled.

@item Octave:undefined-return-values
If the @code{Octave:undefined-return-values} warning is disabled,
print a warning if a function does not define all the values in
the return list which are expected.
By default, the @code{Octave:undefined-return-values} warning is enabled.

@item Octave:variable-switch-label
If the @code{Octave:variable-switch-label} warning is enabled, Octave
will print a warning if a switch label is not a constant or constant
expression.
By default, the @code{Octave:variable-switch-label} warning is disabled.
@end table

what
@c what scripts/miscellaneous/what.m
-*- texinfo -*-
@deftypefn  {Command} {} what
@deftypefnx {Command} {} what @var{dir}
@deftypefnx {Function File} {w =} what (@var{dir})
List the Octave specific files in directory @var{dir}.

If @var{dir} is not specified then the current directory is used.

If a return argument is requested, the files found are returned in the
structure @var{w}.  The structure contains the following fields:

@table @asis
@item path
Full path to directory @var{dir}

@item m
Cell array of m-files

@item mat
Cell array of mat files

@item mex
Cell array of mex files

@item oct
Cell array of oct files

@item mdl
Cell array of mdl files

@item slx
Cell array of slx files

@item p
Cell array of p-files

@item classes
Cell array of class directories (@file{@@@var{classname}/})

@item packages
Cell array of package directories (@file{+@var{pkgname}/})
@end table

Compatibility Note: Octave does not support mdl, slx, and p files; nor does
it support package directories.  @code{what} will always return an empty
list for these categories.
@seealso{which, ls, exist}
@end deftypefn
xor
@c xor scripts/miscellaneous/xor.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{z} =} xor (@var{x}, @var{y})
@deftypefnx {Function File} {@var{z} =} xor (@var{x1}, @var{x2}, @dots{})
Return the @dfn{exclusive or} of @var{x} and @var{y}.

For boolean expressions @var{x} and @var{y},
@code{xor (@var{x}, @var{y})} is true if and only if one of @var{x} or
@var{y} is true.  Otherwise, if @var{x} and @var{y} are both true or both
false, @code{xor} returns false.

The truth table for the xor operation is

@multitable @columnfractions 0.44 .03 .05 .03 0.44
@item @tab @var{x} @tab @var{y} @tab @var{z} @tab
@item @tab - @tab - @tab - @tab
@item @tab 0 @tab 0 @tab 0 @tab
@item @tab 1 @tab 0 @tab 1 @tab
@item @tab 0 @tab 1 @tab 1 @tab
@item @tab 1 @tab 1 @tab 0 @tab
@end multitable

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

@example
(@dots{}((x1 XOR x2) XOR x3) XOR @dots{})
@end example

@seealso{and, or, not}
@end deftypefn
zip
@c zip scripts/miscellaneous/zip.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{filelist} =} zip (@var{zipfile}, @var{files})
@deftypefnx {Function File} {@var{filelist} =} zip (@var{zipfile}, @var{files}, @var{rootdir})
Compress the list of files and directories specified in @var{files} into the
ZIP archive @var{zipfile}.

@var{files} is a character array or cell array of strings.  Shell
wildcards in the filename such as @samp{*} or @samp{?} are accepted and
expanded.  Directories are recursively traversed and all files are
compressed and added to the archive.

If @var{rootdir} is defined then any files without absolute pathnames are
located relative to @var{rootdir} rather than the current directory.

The optional output @var{filelist} is a list of the files that were included
in the archive.
@seealso{unzip, unpack, bzip2, gzip, tar}
@end deftypefn
__all_opts__
@c __all_opts__ scripts/optimization/__all_opts__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{names} =} __all_opts__ (@dots{})
Undocumented internal function.
@end deftypefn
fminbnd
@c fminbnd scripts/optimization/fminbnd.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{fval}, @var{info}, @var{output}] =} fminbnd (@var{fun}, @var{a}, @var{b}, @var{options})
Find a minimum point of a univariate function.

@var{fun} should be a function handle or name.  @var{a}, @var{b} specify a
starting interval.  @var{options} is a structure specifying additional
options.  Currently, @code{fminbnd} recognizes these options:
@qcode{"FunValCheck"}, @qcode{"OutputFcn"}, @qcode{"TolX"},
@qcode{"MaxIter"}, @qcode{"MaxFunEvals"}.  For a description of these
options, see @ref{XREFoptimset,,optimset}.

On exit, the function returns @var{x}, the approximate minimum point and
@var{fval}, the function value thereof.

@var{info} is an exit flag that can have these values:

@itemize
@item 1
The algorithm converged to a solution.

@item 0
Maximum number of iterations or function evaluations has been exhausted.

@item -1
The algorithm has been terminated from user output function.
@end itemize

Notes: The search for a minimum is restricted to be in the interval bound by
@var{a} and @var{b}.  If you only have an initial point to begin searching
from you will need to use an unconstrained minimization algorithm such as
@code{fminunc} or @code{fminsearch}.  @code{fminbnd} internally uses a
Golden Section search strategy.
@seealso{fzero, fminunc, fminsearch, optimset}
@end deftypefn
fminsearch
@c fminsearch scripts/optimization/fminsearch.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} fminsearch (@var{fun}, @var{x0})
@deftypefnx {Function File} {@var{x} =} fminsearch (@var{fun}, @var{x0}, @var{options})
@deftypefnx {Function File} {[@var{x}, @var{fval}] =} fminsearch (@dots{})

Find a value of @var{x} which minimizes the function @var{fun}.

The search begins at the point @var{x0} and iterates using the
@nospell{Nelder & Mead} Simplex algorithm (a derivative-free method).  This
algorithm is better-suited to functions which have discontinuities or for
which a gradient-based search such as @code{fminunc} fails.

Options for the search are provided in the parameter @var{options} using the
function @code{optimset}.  Currently, @code{fminsearch} accepts the options:
@qcode{"TolX"}, @qcode{"MaxFunEvals"}, @qcode{"MaxIter"}, @qcode{"Display"}.
For a description of these options, see @code{optimset}.

On exit, the function returns @var{x}, the minimum point, and @var{fval},
the function value thereof.

Example usages:

@example
@group
fminsearch (@@(x) (x(1)-5).^2+(x(2)-8).^4, [0;0])

fminsearch (inline ("(x(1)-5).^2+(x(2)-8).^4", "x"), [0;0])
@end group
@end example
@seealso{fminbnd, fminunc, optimset}
@end deftypefn
fminunc
@c fminunc scripts/optimization/fminunc.m
-*- texinfo -*-
@deftypefn  {Function File} {} fminunc (@var{fcn}, @var{x0})
@deftypefnx {Function File} {} fminunc (@var{fcn}, @var{x0}, @var{options})
@deftypefnx {Function File} {[@var{x}, @var{fval}, @var{info}, @var{output}, @var{grad}, @var{hess}] =} fminunc (@var{fcn}, @dots{})
Solve an unconstrained optimization problem defined by the function
@var{fcn}.

@var{fcn} should accept a vector (array) defining the unknown variables, and
return the objective function value, optionally with gradient.
@code{fminunc} attempts to determine a vector @var{x} such that
@code{@var{fcn} (@var{x})} is a local minimum.

@var{x0} determines a starting guess.  The shape of @var{x0} is preserved in
all calls to @var{fcn}, but otherwise is treated as a column vector.

@var{options} is a structure specifying additional options.  Currently,
@code{fminunc} recognizes these options:
@qcode{"FunValCheck"}, @qcode{"OutputFcn"}, @qcode{"TolX"},
@qcode{"TolFun"}, @qcode{"MaxIter"}, @qcode{"MaxFunEvals"},
@qcode{"GradObj"}, @qcode{"FinDiffType"}, @qcode{"TypicalX"},
@qcode{"AutoScaling"}.

If @qcode{"GradObj"} is @qcode{"on"}, it specifies that @var{fcn}, when
called with 2 output arguments, also returns the Jacobian matrix of partial
first derivatives at the requested point.  @code{TolX} specifies the
termination tolerance for the unknown variables @var{x}, while @code{TolFun}
is a tolerance for the objective function value @var{fval}.  The default is
@code{1e-7} for both options.

For a description of the other options, see @code{optimset}.

On return, @var{x} is the location of the minimum and @var{fval} contains
the value of the objective function at @var{x}.

@var{info} may be one of the following values:

@table @asis
@item 1
Converged to a solution point.  Relative gradient error is less than
specified by @code{TolFun}.

@item 2
Last relative step size was less than @code{TolX}.

@item 3
Last relative change in function value was less than @code{TolFun}.

@item 0
Iteration limit exceeded---either maximum number of algorithm iterations
@code{MaxIter} or maximum number of function evaluations @code{MaxFunEvals}.

@item -1
Algorithm terminated by @code{OutputFcn}.

@item -3
The trust region radius became excessively small.
@end table

Optionally, @code{fminunc} can return a structure with convergence statistics
(@var{output}), the output gradient (@var{grad}) at the solution @var{x},
and approximate Hessian (@var{hess}) at the solution @var{x}.

Application Notes: If have only a single nonlinear equation of one variable
then using @code{fminbnd} is usually a better choice.

The algorithm used by @code{fminsearch} is a gradient search which depends
on the objective function being differentiable.  If the function has
discontinuities it may be better to use a derivative-free algorithm such as
@code{fminsearch}.
@seealso{fminbnd, fminsearch, optimset}
@end deftypefn
fsolve
@c fsolve scripts/optimization/fsolve.m
-*- texinfo -*-
@deftypefn  {Function File} {} fsolve (@var{fcn}, @var{x0}, @var{options})
@deftypefnx {Function File} {[@var{x}, @var{fvec}, @var{info}, @var{output}, @var{fjac}] =} fsolve (@var{fcn}, @dots{})
Solve a system of nonlinear equations defined by the function @var{fcn}.

@var{fcn} should accept a vector (array) defining the unknown variables,
and return a vector of left-hand sides of the equations.  Right-hand sides
are defined to be zeros.  In other words, this function attempts to
determine a vector @var{x} such that @code{@var{fcn} (@var{x})} gives
(approximately) all zeros.

@var{x0} determines a starting guess.  The shape of @var{x0} is preserved
in all calls to @var{fcn}, but otherwise it is treated as a column vector.

@var{options} is a structure specifying additional options.  Currently,
@code{fsolve} recognizes these options:
@qcode{"FunValCheck"}, @qcode{"OutputFcn"}, @qcode{"TolX"},
@qcode{"TolFun"}, @qcode{"MaxIter"}, @qcode{"MaxFunEvals"},
@qcode{"Jacobian"}, @qcode{"Updating"}, @qcode{"ComplexEqn"}
@qcode{"TypicalX"}, @qcode{"AutoScaling"} and @qcode{"FinDiffType"}.

If @qcode{"Jacobian"} is @qcode{"on"}, it specifies that @var{fcn}, called
with 2 output arguments also returns the Jacobian matrix of right-hand sides
at the requested point.  @qcode{"TolX"} specifies the termination tolerance
in the unknown variables, while @qcode{"TolFun"} is a tolerance for
equations.  Default is @code{1e-7} for both @qcode{"TolX"} and
@qcode{"TolFun"}.

If @qcode{"AutoScaling"} is on, the variables will be automatically scaled
according to the column norms of the (estimated) Jacobian.  As a result,
TolF becomes scaling-independent.  By default, this option is off because
it may sometimes deliver unexpected (though mathematically correct) results.

If @qcode{"Updating"} is @qcode{"on"}, the function will attempt to use
@nospell{Broyden} updates to update the Jacobian, in order to reduce the
amount of Jacobian calculations.  If your user function always calculates the
Jacobian (regardless of number of output arguments) then this option provides
no advantage and should be set to false.

@qcode{"ComplexEqn"} is @qcode{"on"}, @code{fsolve} will attempt to solve
complex equations in complex variables, assuming that the equations possess
a complex derivative (i.e., are holomorphic).  If this is not what you want,
you should unpack the real and imaginary parts of the system to get a real
system.

For description of the other options, see @code{optimset}.

On return, @var{fval} contains the value of the function @var{fcn}
evaluated at @var{x}.

@var{info} may be one of the following values:

@table @asis
@item 1
Converged to a solution point.  Relative residual error is less than
specified by TolFun.

@item 2
Last relative step size was less that TolX.

@item 3
Last relative decrease in residual was less than TolF.

@item 0
Iteration limit exceeded.

@item -3
The trust region radius became excessively small.
@end table

Note: If you only have a single nonlinear equation of one variable, using
@code{fzero} is usually a much better idea.

Note about user-supplied Jacobians:
As an inherent property of the algorithm, a Jacobian is always requested for
a solution vector whose residual vector is already known, and it is the last
accepted successful step.  Often this will be one of the last two calls, but
not always.  If the savings by reusing intermediate results from residual
calculation in Jacobian calculation are significant, the best strategy is to
employ OutputFcn: After a vector is evaluated for residuals, if OutputFcn is
called with that vector, then the intermediate results should be saved for
future Jacobian evaluation, and should be kept until a Jacobian evaluation
is requested or until OutputFcn is called with a different vector, in which
case they should be dropped in favor of this most recent vector.  A short
example how this can be achieved follows:

@example
function [fvec, fjac] = user_func (x, optimvalues, state)
persistent sav = [], sav0 = [];
if (nargin == 1)
  ## evaluation call
  if (nargout == 1)
    sav0.x = x; # mark saved vector
    ## calculate fvec, save results to sav0.
  elseif (nargout == 2)
    ## calculate fjac using sav.
  endif
else
  ## outputfcn call.
  if (all (x == sav0.x))
    sav = sav0;
  endif
  ## maybe output iteration status, etc.
endif
endfunction

## @dots{}

fsolve (@@user_func, x0, optimset ("OutputFcn", @@user_func, @dots{}))
@end example
@seealso{fzero, optimset}
@end deftypefn
fzero
@c fzero scripts/optimization/fzero.m
-*- texinfo -*-
@deftypefn  {Function File} {} fzero (@var{fun}, @var{x0})
@deftypefnx {Function File} {} fzero (@var{fun}, @var{x0}, @var{options})
@deftypefnx {Function File} {[@var{x}, @var{fval}, @var{info}, @var{output}] =} fzero (@dots{})
Find a zero of a univariate function.

@var{fun} is a function handle, inline function, or string containing the
name of the function to evaluate.

@var{x0} should be a two-element vector specifying two points which
bracket a zero.  In other words, there must be a change in sign of the
function between @var{x0}(1) and @var{x0}(2).  More mathematically, the
following must hold

@example
sign (@var{fun}(@var{x0}(1))) * sign (@var{fun}(@var{x0}(2))) <= 0
@end example

If @var{x0} is a single scalar then several nearby and distant values are
probed in an attempt to obtain a valid bracketing.  If this is not
successful, the function fails.

@var{options} is a structure specifying additional options.  Currently,
@code{fzero} recognizes these options:
@qcode{"FunValCheck"}, @qcode{"OutputFcn"}, @qcode{"TolX"},
@qcode{"MaxIter"}, @qcode{"MaxFunEvals"}.
For a description of these options, see @ref{XREFoptimset,,optimset}.

On exit, the function returns @var{x}, the approximate zero point and
@var{fval}, the function value thereof.

@var{info} is an exit flag that can have these values:

@itemize
@item 1
 The algorithm converged to a solution.

@item 0
 Maximum number of iterations or function evaluations has been reached.

@item -1
The algorithm has been terminated from user output function.

@item -5
The algorithm may have converged to a singular point.
@end itemize

@var{output} is a structure containing runtime information about the
@code{fzero} algorithm.  Fields in the structure are:

@itemize
@item iterations
 Number of iterations through loop.

@item nfev
 Number of function evaluations.

@item bracketx
 A two-element vector with the final bracketing of the zero along the x-axis.

@item brackety
 A two-element vector with the final bracketing of the zero along the y-axis.
@end itemize
@seealso{optimset, fsolve}
@end deftypefn
glpk
@c glpk scripts/optimization/glpk.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{xopt}, @var{fmin}, @var{errnum}, @var{extra}] =} glpk (@var{c}, @var{A}, @var{b}, @var{lb}, @var{ub}, @var{ctype}, @var{vartype}, @var{sense}, @var{param})
Solve a linear program using the GNU @sc{glpk} library.

Given three arguments, @code{glpk} solves the following standard LP:
@tex
$$
  \min_x C^T x
$$
@end tex
@ifnottex

@example
min C'*x
@end example

@end ifnottex
subject to
@tex
$$
  Ax = b \qquad x \geq 0
$$
@end tex
@ifnottex

@example
@group
A*x  = b
  x >= 0
@end group
@end example

@end ifnottex
but may also solve problems of the form
@tex
$$
  [ \min_x | \max_x ] C^T x
$$
@end tex
@ifnottex

@example
[ min | max ] C'*x
@end example

@end ifnottex
subject to
@tex
$$
 Ax [ = | \leq | \geq ] b \qquad LB \leq x \leq UB
$$
@end tex
@ifnottex

@example
@group
A*x [ "=" | "<=" | ">=" ] b
  x >= LB
  x <= UB
@end group
@end example

@end ifnottex

Input arguments:

@table @var
@item c
A column array containing the objective function coefficients.

@item A
A matrix containing the constraints coefficients.

@item b
A column array containing the right-hand side value for each constraint in
the constraint matrix.

@item lb
An array containing the lower bound on each of the variables.  If @var{lb}
is not supplied, the default lower bound for the variables is zero.

@item ub
An array containing the upper bound on each of the variables.  If @var{ub}
is not supplied, the default upper bound is assumed to be infinite.

@item ctype
An array of characters containing the sense of each constraint in the
constraint matrix.  Each element of the array may be one of the following
values

@table @asis
@item @qcode{"F"}
A free (unbounded) constraint (the constraint is ignored).

@item @qcode{"U"}
An inequality constraint with an upper bound (@code{A(i,:)*x <= b(i)}).

@item @qcode{"S"}
An equality constraint (@code{A(i,:)*x = b(i)}).

@item @qcode{"L"}
An inequality with a lower bound (@code{A(i,:)*x >= b(i)}).

@item @qcode{"D"}
An inequality constraint with both upper and lower bounds
(@code{A(i,:)*x >= -b(i)}) @emph{and} (@code{A(i,:)*x <= b(i)}).
@end table

@item vartype
A column array containing the types of the variables.

@table @asis
@item @qcode{"C"}
A continuous variable.

@item @qcode{"I"}
An integer variable.
@end table

@item sense
If @var{sense} is 1, the problem is a minimization.  If @var{sense} is -1,
the problem is a maximization.  The default value is 1.

@item param
A structure containing the following parameters used to define the
behavior of solver.  Missing elements in the structure take on default
values, so you only need to set the elements that you wish to change from
the default.

Integer parameters:

@table @code
@item msglev (default: 1)
Level of messages output by solver routines:

@table @asis
@item 0 (@w{@code{GLP_MSG_OFF}})
No output.

@item 1 (@w{@code{GLP_MSG_ERR}})
Error and warning messages only.

@item 2 (@w{@code{GLP_MSG_ON}})
Normal output.

@item 3 (@w{@code{GLP_MSG_ALL}})
Full output (includes informational messages).
@end table

@item scale (default: 16)
Scaling option.  The values can be combined with the bitwise OR operator and
may be the following:

@table @asis
@item 1 (@w{@code{GLP_SF_GM}})
Geometric mean scaling.

@item 16 (@w{@code{GLP_SF_EQ}})
Equilibration scaling.

@item 32 (@w{@code{GLP_SF_2N}})
Round scale factors to power of two.

@item 64 (@w{@code{GLP_SF_SKIP}})
Skip if problem is well scaled.
@end table

Alternatively, a value of 128 (@w{@env{GLP_SF_AUTO}}) may be also
specified, in which case the routine chooses the scaling options
automatically.

@item dual (default: 1)
Simplex method option:

@table @asis
@item 1 (@w{@code{GLP_PRIMAL}})
Use two-phase primal simplex.

@item 2 (@w{@code{GLP_DUALP}})
Use two-phase dual simplex, and if it fails, switch to the primal simplex.

@item 3 (@w{@code{GLP_DUAL}})
Use two-phase dual simplex.
@end table

@item price (default: 34)
Pricing option (for both primal and dual simplex):

@table @asis
@item 17 (@w{@code{GLP_PT_STD}})
Textbook pricing.

@item 34 (@w{@code{GLP_PT_PSE}})
Steepest edge pricing.
@end table

@item itlim (default: intmax)
Simplex iterations limit.  It is decreased by one each time when one simplex
iteration has been performed, and reaching zero value signals the solver to
stop the search.

@item outfrq (default: 200)
Output frequency, in iterations.  This parameter specifies how frequently
the solver sends information about the solution to the standard output.

@item branch (default: 4)
Branching technique option (for MIP only):

@table @asis
@item 1 (@w{@code{GLP_BR_FFV}})
First fractional variable.

@item 2 (@w{@code{GLP_BR_LFV}})
Last fractional variable.

@item 3 (@w{@code{GLP_BR_MFV}})
Most fractional variable.

@item 4 (@w{@code{GLP_BR_DTH}})
Heuristic by @nospell{Driebeck and Tomlin}.

@item 5 (@w{@code{GLP_BR_PCH}})
Hybrid @nospell{pseudocost} heuristic.
@end table

@item btrack (default: 4)
Backtracking technique option (for MIP only):

@table @asis
@item 1 (@w{@code{GLP_BT_DFS}})
Depth first search.

@item 2 (@w{@code{GLP_BT_BFS}})
Breadth first search.

@item 3 (@w{@code{GLP_BT_BLB}})
Best local bound.

@item 4 (@w{@code{GLP_BT_BPH}})
Best projection heuristic.
@end table

@item presol (default: 1)
If this flag is set, the simplex solver uses the built-in LP presolver.
Otherwise the LP presolver is not used.

@item lpsolver (default: 1)
Select which solver to use.  If the problem is a MIP problem this flag
will be ignored.

@table @asis
@item 1
Revised simplex method.

@item 2
Interior point method.
@end table

@item rtest (default: 34)
Ratio test technique:

@table @asis
@item 17 (@w{@code{GLP_RT_STD}})
Standard ("textbook").

@item 34 (@w{@code{GLP_RT_HAR}})
Harris' two-pass ratio test.
@end table

@item tmlim (default: intmax)
Searching time limit, in milliseconds.

@item outdly (default: 0)
Output delay, in seconds.  This parameter specifies how long the solver
should delay sending information about the solution to the standard output.

@item save (default: 0)
If this parameter is nonzero, save a copy of the problem in CPLEX LP
format to the file @file{"outpb.lp"}.  There is currently no way to change
the name of the output file.
@end table

Real parameters:

@table @code
@item tolbnd (default: 1e-7)
Relative tolerance used to check if the current basic solution is primal
feasible.  It is not recommended that you change this parameter unless you
have a detailed understanding of its purpose.

@item toldj (default: 1e-7)
Absolute tolerance used to check if the current basic solution is dual
feasible.  It is not recommended that you change this parameter unless you
have a detailed understanding of its purpose.

@item tolpiv (default: 1e-10)
Relative tolerance used to choose eligible pivotal elements of the simplex
table.  It is not recommended that you change this parameter unless you have
a detailed understanding of its purpose.

@item objll (default: -DBL_MAX)
Lower limit of the objective function.  If the objective function reaches
this limit and continues decreasing, the solver stops the search.  This
parameter is used in the dual simplex method only.

@item objul (default: +DBL_MAX)
Upper limit of the objective function.  If the objective function reaches
this limit and continues increasing, the solver stops the search.  This
parameter is used in the dual simplex only.

@item tolint (default: 1e-5)
Relative tolerance used to check if the current basic solution is integer
feasible.  It is not recommended that you change this parameter unless you
have a detailed understanding of its purpose.

@item tolobj (default: 1e-7)
Relative tolerance used to check if the value of the objective function is
not better than in the best known integer feasible solution.  It is not
recommended that you change this parameter unless you have a detailed
understanding of its purpose.
@end table
@end table

Output values:

@table @var
@item xopt
The optimizer (the value of the decision variables at the optimum).

@item fopt
The optimum value of the objective function.

@item errnum
Error code.

@table @asis
@item 0
No error.

@item 1 (@w{@code{GLP_EBADB}})
Invalid basis.

@item 2 (@w{@code{GLP_ESING}})
Singular matrix.

@item 3 (@w{@code{GLP_ECOND}})
Ill-conditioned matrix.

@item 4 (@w{@code{GLP_EBOUND}})
Invalid bounds.

@item 5 (@w{@code{GLP_EFAIL}})
Solver failed.

@item 6 (@w{@code{GLP_EOBJLL}})
Objective function lower limit reached.

@item 7 (@w{@code{GLP_EOBJUL}})
Objective function upper limit reached.

@item 8 (@w{@code{GLP_EITLIM}})
Iterations limit exhausted.

@item 9 (@w{@code{GLP_ETMLIM}})
Time limit exhausted.

@item 10 (@w{@code{GLP_ENOPFS}})
No primal feasible solution.

@item 11 (@w{@code{GLP_ENODFS}})
No dual feasible solution.

@item 12 (@w{@code{GLP_EROOT}})
Root LP optimum not provided.

@item 13 (@w{@code{GLP_ESTOP}})
Search terminated by application.

@item 14 (@w{@code{GLP_EMIPGAP}})
Relative MIP gap tolerance reached.

@item 15 (@w{@code{GLP_ENOFEAS}})
No primal/dual feasible solution.

@item 16 (@w{@code{GLP_ENOCVG}})
No convergence.

@item 17 (@w{@code{GLP_EINSTAB}})
Numerical instability.

@item 18 (@w{@code{GLP_EDATA}})
Invalid data.

@item 19 (@w{@code{GLP_ERANGE}})
Result out of range.
@end table

@item extra
A data structure containing the following fields:

@table @code
@item lambda
Dual variables.

@item redcosts
Reduced Costs.

@item time
Time (in seconds) used for solving LP/MIP problem.

@item status
Status of the optimization.

@table @asis
@item 1 (@w{@code{GLP_UNDEF}})
Solution status is undefined.

@item 2 (@w{@code{GLP_FEAS}})
Solution is feasible.

@item 3 (@w{@code{GLP_INFEAS}})
Solution is infeasible.

@item 4 (@w{@code{GLP_NOFEAS}})
Problem has no feasible solution.

@item 5 (@w{@code{GLP_OPT}})
Solution is optimal.

@item 6 (@w{@code{GLP_UNBND}})
Problem has no unbounded solution.
@end table
@end table
@end table

Example:

@example
@group
c = [10, 6, 4]';
A = [ 1, 1, 1;
     10, 4, 5;
      2, 2, 6];
b = [100, 600, 300]';
lb = [0, 0, 0]';
ub = [];
ctype = "UUU";
vartype = "CCC";
s = -1;

param.msglev = 1;
param.itlim = 100;

[xmin, fmin, status, extra] = ...
   glpk (c, A, b, lb, ub, ctype, vartype, s, param);
@end group
@end example
@end deftypefn
lsqnonneg
@c lsqnonneg scripts/optimization/lsqnonneg.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} lsqnonneg (@var{c}, @var{d})
@deftypefnx {Function File} {@var{x} =} lsqnonneg (@var{c}, @var{d}, @var{x0})
@deftypefnx {Function File} {@var{x} =} lsqnonneg (@var{c}, @var{d}, @var{x0}, @var{options})
@deftypefnx {Function File} {[@var{x}, @var{resnorm}] =} lsqnonneg (@dots{})
@deftypefnx {Function File} {[@var{x}, @var{resnorm}, @var{residual}] =} lsqnonneg (@dots{})
@deftypefnx {Function File} {[@var{x}, @var{resnorm}, @var{residual}, @var{exitflag}] =} lsqnonneg (@dots{})
@deftypefnx {Function File} {[@var{x}, @var{resnorm}, @var{residual}, @var{exitflag}, @var{output}] =} lsqnonneg (@dots{})
@deftypefnx {Function File} {[@var{x}, @var{resnorm}, @var{residual}, @var{exitflag}, @var{output}, @var{lambda}] =} lsqnonneg (@dots{})
Minimize @code{norm (@var{c}*@var{x} - d)} subject to
@code{@var{x} >= 0}.

@var{c} and @var{d} must be real.

@var{x0} is an optional initial guess for @var{x}.

Currently, @code{lsqnonneg} recognizes these options: @qcode{"MaxIter"},
@qcode{"TolX"}.  For a description of these options, see
@ref{XREFoptimset,,optimset}.

Outputs:

@itemize @bullet
@item resnorm

The squared 2-norm of the residual: norm (@var{c}*@var{x}-@var{d})^2

@item residual

The residual: @var{d}-@var{c}*@var{x}

@item exitflag

An indicator of convergence.  0 indicates that the iteration count was
exceeded, and therefore convergence was not reached; >0 indicates that the
algorithm converged.  (The algorithm is stable and will converge given
enough iterations.)

@item output

A structure with two fields:

@itemize @bullet
@item @qcode{"algorithm"}: The algorithm used (@qcode{"nnls"})

@item @qcode{"iterations"}: The number of iterations taken.
@end itemize

@item lambda

Not implemented.
@end itemize
@seealso{optimset, pqpnonneg, lscov}
@end deftypefn
optimget
@c optimget scripts/optimization/optimget.m
-*- texinfo -*-
@deftypefn  {Function File} {} optimget (@var{options}, @var{parname})
@deftypefnx {Function File} {} optimget (@var{options}, @var{parname}, @var{default})
Return the specific option @var{parname} from the optimization options
structure @var{options} created by @code{optimset}.

If @var{parname} is not defined then return @var{default} if supplied,
otherwise return an empty matrix.
@seealso{optimset}
@end deftypefn
optimset
@c optimset scripts/optimization/optimset.m
-*- texinfo -*-
@deftypefn  {Function File} {} optimset ()
@deftypefnx {Function File} {@var{options} =} optimset ()
@deftypefnx {Function File} {@var{options} =} optimset (@var{par}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{options} =} optimset (@var{old}, @var{par}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{options} =} optimset (@var{old}, @var{new})
Create options structure for optimization functions.

When called without any input or output arguments, @code{optimset} prints
a list of all valid optimization parameters.

When called with one output and no inputs, return an options structure with
all valid option parameters initialized to @code{[]}.

When called with a list of parameter/value pairs, return an options
structure with only the named parameters initialized.

When the first input is an existing options structure @var{old}, the values
are updated from either the @var{par}/@var{val} list or from the options
structure @var{new}.

Valid parameters are:

@table @asis
@item AutoScaling

@item ComplexEqn

@item Display
Request verbose display of results from optimizations.  Values are:

@table @asis
@item @qcode{"off"} [default]
No display.

@item @qcode{"iter"}
Display intermediate results for every loop iteration.

@item @qcode{"final"}
Display the result of the final loop iteration.

@item @qcode{"notify"}
Display the result of the final loop iteration if the function has
failed to converge.
@end table

@item FinDiffType

@item FunValCheck
When enabled, display an error if the objective function returns an invalid
value (a complex number, NaN, or Inf).  Must be set to @qcode{"on"} or
@qcode{"off"} [default].  Note: the functions @code{fzero} and
@code{fminbnd} correctly handle Inf values and only complex values or NaN
will cause an error in this case.

@item GradObj
When set to @qcode{"on"}, the function to be minimized must return a
second argument which is the gradient, or first derivative, of the
function at the point @var{x}.  If set to @qcode{"off"} [default], the
gradient is computed via finite differences.

@item Jacobian
When set to @qcode{"on"}, the function to be minimized must return a
second argument which is the Jacobian, or first derivative, of the
function at the point @var{x}.  If set to @qcode{"off"} [default], the
Jacobian is computed via finite differences.

@item MaxFunEvals
Maximum number of function evaluations before optimization stops.
Must be a positive integer.

@item MaxIter
Maximum number of algorithm iterations before optimization stops.
Must be a positive integer.

@item OutputFcn
A user-defined function executed once per algorithm iteration.

@item TolFun
Termination criterion for the function output.  If the difference in the
calculated objective function between one algorithm iteration and the next
is less than @code{TolFun} the optimization stops.  Must be a positive
scalar.

@item TolX
Termination criterion for the function input.  If the difference in @var{x},
the current search point, between one algorithm iteration and the next is
less than @code{TolX} the optimization stops.  Must be a positive scalar.

@item TypicalX

@item Updating
@end table
@seealso{optimget}
@end deftypefn
pqpnonneg
@c pqpnonneg scripts/optimization/pqpnonneg.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} pqpnonneg (@var{c}, @var{d})
@deftypefnx {Function File} {@var{x} =} pqpnonneg (@var{c}, @var{d}, @var{x0})
@deftypefnx {Function File} {[@var{x}, @var{minval}] =} pqpnonneg (@dots{})
@deftypefnx {Function File} {[@var{x}, @var{minval}, @var{exitflag}] =} pqpnonneg (@dots{})
@deftypefnx {Function File} {[@var{x}, @var{minval}, @var{exitflag}, @var{output}] =} pqpnonneg (@dots{})
@deftypefnx {Function File} {[@var{x}, @var{minval}, @var{exitflag}, @var{output}, @var{lambda}] =} pqpnonneg (@dots{})
Minimize @code{1/2*x'*c*x + d'*x} subject to @code{@var{x} >= 0}.

@var{c} ## and @var{d} must be real, and @var{c} must be symmetric and
positive definite.

@var{x0} is an optional initial guess for @var{x}.

Outputs:

@itemize @bullet
@item minval

The minimum attained model value, 1/2*xmin'*c*xmin + d'*xmin

@item exitflag

An indicator of convergence.  0 indicates that the iteration count was
exceeded, and therefore convergence was not reached; >0 indicates that the
algorithm converged.  (The algorithm is stable and will converge given
enough iterations.)

@item output

A structure with two fields:

@itemize @bullet
@item @qcode{"algorithm"}: The algorithm used (@qcode{"nnls"})

@item @qcode{"iterations"}: The number of iterations taken.
@end itemize

@item lambda

Not implemented.
@end itemize
@seealso{optimset, lsqnonneg, qp}
@end deftypefn
qp
@c qp scripts/optimization/qp.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H})
@deftypefnx {Function File} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H}, @var{q})
@deftypefnx {Function File} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H}, @var{q}, @var{A}, @var{b})
@deftypefnx {Function File} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H}, @var{q}, @var{A}, @var{b}, @var{lb}, @var{ub})
@deftypefnx {Function File} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H}, @var{q}, @var{A}, @var{b}, @var{lb}, @var{ub}, @var{A_lb}, @var{A_in}, @var{A_ub})
@deftypefnx {Function File} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@dots{}, @var{options})
Solve a quadratic program (QP).

Solve the quadratic program defined by
@tex
$$
 \min_x {1 \over 2} x^T H x + x^T q
$$
@end tex
@ifnottex

@example
@group
min 0.5 x'*H*x + x'*q
 x
@end group
@end example

@end ifnottex
subject to
@tex
$$
 Ax = b \qquad lb \leq x \leq ub \qquad A_{lb} \leq A_{in} \leq A_{ub}
$$
@end tex
@ifnottex

@example
@group
A*x = b
lb <= x <= ub
A_lb <= A_in*x <= A_ub
@end group
@end example

@end ifnottex
@noindent
using a null-space active-set method.

Any bound (@var{A}, @var{b}, @var{lb}, @var{ub}, @var{A_lb}, @var{A_ub})
may be set to the empty matrix (@code{[]}) if not present.  If the initial
guess is feasible the algorithm is faster.

@table @var
@item options
An optional structure containing the following parameter(s) used to define
the behavior of the solver.  Missing elements in the structure take on
default values, so you only need to set the elements that you wish to
change from the default.

@table @code
@item MaxIter (default: 200)
Maximum number of iterations.
@end table
@end table

@table @var
@item info
Structure containing run-time information about the algorithm.  The
following fields are defined:

@table @code
@item solveiter
The number of iterations required to find the solution.

@item info
An integer indicating the status of the solution.

@table @asis
@item 0
The problem is feasible and convex.  Global solution found.

@item 1
The problem is not convex.  Local solution found.

@item 2
The problem is not convex and unbounded.

@item 3
Maximum number of iterations reached.

@item 6
The problem is infeasible.
@end table
@end table
@end table
@end deftypefn
sqp
@c sqp scripts/optimization/sqp.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{x}, @var{obj}, @var{info}, @var{iter}, @var{nf}, @var{lambda}] =} sqp (@var{x0}, @var{phi})
@deftypefnx {Function File} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g})
@deftypefnx {Function File} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g}, @var{h})
@deftypefnx {Function File} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g}, @var{h}, @var{lb}, @var{ub})
@deftypefnx {Function File} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g}, @var{h}, @var{lb}, @var{ub}, @var{maxiter})
@deftypefnx {Function File} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g}, @var{h}, @var{lb}, @var{ub}, @var{maxiter}, @var{tol})
Minimize an objective function using sequential quadratic programming (SQP).

Solve the nonlinear program
@tex
$$
\min_x \phi (x)
$$
@end tex
@ifnottex

@example
@group
min phi (x)
 x
@end group
@end example

@end ifnottex
subject to
@tex
$$
 g(x) = 0 \qquad h(x) \geq 0 \qquad lb \leq x \leq ub
$$
@end tex
@ifnottex

@example
@group
g(x)  = 0
h(x) >= 0
lb <= x <= ub
@end group
@end example

@end ifnottex
@noindent
using a sequential quadratic programming method.

The first argument is the initial guess for the vector @var{x0}.

The second argument is a function handle pointing to the objective function
@var{phi}.  The objective function must accept one vector argument and
return a scalar.

The second argument may also be a 2- or 3-element cell array of function
handles.  The first element should point to the objective function, the
second should point to a function that computes the gradient of the
objective function, and the third should point to a function that computes
the Hessian of the objective function.  If the gradient function is not
supplied, the gradient is computed by finite differences.  If the Hessian
function is not supplied, a BFGS update formula is used to approximate the
Hessian.

When supplied, the gradient function @code{@var{phi}@{2@}} must accept one
vector argument and return a vector.  When supplied, the Hessian function
@code{@var{phi}@{3@}} must accept one vector argument and return a matrix.

The third and fourth arguments @var{g} and @var{h} are function handles
pointing to functions that compute the equality constraints and the
inequality constraints, respectively.  If the problem does not have
equality (or inequality) constraints, then use an empty matrix ([]) for
@var{g} (or @var{h}).  When supplied, these equality and inequality
constraint functions must accept one vector argument and return a vector.

The third and fourth arguments may also be 2-element cell arrays of
function handles.  The first element should point to the constraint
function and the second should point to a function that computes the
gradient of the constraint function:
@tex
$$
 \Bigg( {\partial f(x) \over \partial x_1},
        {\partial f(x) \over \partial x_2}, \ldots,
        {\partial f(x) \over \partial x_N} \Bigg)^T
$$
@end tex
@ifnottex

@example
@group
            [ d f(x)   d f(x)        d f(x) ]
transpose ( [ ------   -----   ...   ------ ] )
            [  dx_1     dx_2          dx_N  ]
@end group
@end example

@end ifnottex
The fifth and sixth arguments, @var{lb} and @var{ub}, contain lower and
upper bounds on @var{x}.  These must be consistent with the equality and
inequality constraints @var{g} and @var{h}.  If the arguments are vectors
then @var{x}(i) is bound by @var{lb}(i) and @var{ub}(i).  A bound can also
be a scalar in which case all elements of @var{x} will share the same
bound.  If only one bound (lb, ub) is specified then the other will
default to (-@var{realmax}, +@var{realmax}).

The seventh argument @var{maxiter} specifies the maximum number of
iterations.  The default value is 100.

The eighth argument @var{tol} specifies the tolerance for the stopping
criteria.  The default value is @code{sqrt (eps)}.

The value returned in @var{info} may be one of the following:

@table @asis
@item 101
The algorithm terminated normally.
All constraints meet the specified tolerance.

@item 102
The BFGS update failed.

@item 103
The maximum number of iterations was reached.

@item 104
The stepsize has become too small, i.e.,
@tex
$\Delta x,$
@end tex
@ifnottex
delta @var{x},
@end ifnottex
is less than @code{@var{tol} * norm (x)}.
@end table

An example of calling @code{sqp}:

@example
function r = g (x)
  r = [ sumsq(x)-10;
        x(2)*x(3)-5*x(4)*x(5);
        x(1)^3+x(2)^3+1 ];
endfunction

function obj = phi (x)
  obj = exp (prod (x)) - 0.5*(x(1)^3+x(2)^3+1)^2;
endfunction

x0 = [-1.8; 1.7; 1.9; -0.8; -0.8];

[x, obj, info, iter, nf, lambda] = sqp (x0, @@phi, @@g, [])

x =

  -1.71714
   1.59571
   1.82725
  -0.76364
  -0.76364

obj = 0.053950
info = 101
iter = 8
nf = 10
lambda =

  -0.0401627
   0.0379578
  -0.0052227
@end example

@seealso{qp}
@end deftypefn
matlabroot
@c matlabroot scripts/path/matlabroot.m
-*- texinfo -*-
@deftypefn {Function File} {} matlabroot ()
Return the name of the top-level Octave installation directory.

This is an alias for the function @w{@code{OCTAVE_HOME}} provided for
compatibility.
@seealso{OCTAVE_HOME}
@end deftypefn
pathdef
@c pathdef scripts/path/pathdef.m
-*- texinfo -*-
@deftypefn {Function File} {@var{val} =} pathdef ()
Return the default path for Octave.

The path information is extracted from one of four sources.
The possible sources, in order of preference, are:

@enumerate
@item @file{.octaverc}

@item @file{~/.octaverc}

@item @file{<OCTAVE_HOME>/@dots{}/<version>/m/startup/octaverc}

@item Octave's path prior to changes by any octaverc file.
@end enumerate
@seealso{path, addpath, rmpath, genpath, savepath}
@end deftypefn
savepath
@c savepath scripts/path/savepath.m
-*- texinfo -*-
@deftypefn  {Function File} {} savepath ()
@deftypefnx {Function File} {} savepath (@var{file})
@deftypefnx {Function File} {@var{status} =} savepath (@dots{})
Save the unique portion of the current function search path that is
not set during Octave's initialization process to @var{file}.

If @var{file} is omitted, Octave looks in the current directory for a
project-specific @file{.octaverc} file in which to save the path
information.  If no such file is present then the user's configuration file
@file{~/.octaverc} is used.

If successful, @code{savepath} returns 0.

The @code{savepath} function makes it simple to customize a user's
configuration file to restore the working paths necessary for a particular
instance of Octave.  Assuming no filename is specified, Octave will
automatically restore the saved directory paths from the appropriate
@file{.octaverc} file when starting up.  If a filename has been specified
then the paths may be restored manually by calling @code{source @var{file}}.
@seealso{path, addpath, rmpath, genpath, pathdef}
@end deftypefn
pkg
@c pkg scripts/pkg/pkg.m
-*- texinfo -*-
@deftypefn  {Command} {} pkg @var{command} @var{pkg_name}
@deftypefnx {Command} {} pkg @var{command} @var{option} @var{pkg_name}
Manage packages (groups of add-on functions) for Octave.

Different actions are available depending on the value of @var{command}.

Available commands:

@table @samp

@item install
Install named packages.  For example,

@example
pkg install image-1.0.0.tar.gz
@end example

@noindent
installs the package found in the file @file{image-1.0.0.tar.gz}.

The @var{option} variable can contain options that affect the manner
in which a package is installed.  These options can be one or more of

@table @code
@item -nodeps
The package manager will disable dependency checking.  With this option it
is possible to install a package even when it depends on another package
which is not installed on the system.  @strong{Use this option with care.}

@item -noauto
The package manager will not automatically load the installed package
when starting Octave.  This overrides any setting within the package.

@item -auto
The package manager will automatically load the installed package when
starting Octave.  This overrides any setting within the package.

@item -local
A local installation (package available only to current user) is forced,
even if the user has system privileges.

@item -global
A global installation (package available to all users) is forced, even if
the user doesn't normally have system privileges.

@item -forge
Install a package directly from the Octave-Forge repository.  This
requires an internet connection and the cURL library.

@item -verbose
The package manager will print the output of all commands as
they are performed.
@end table

@item update
Check installed Octave-Forge packages against repository and update any
outdated items.  This requires an internet connection and the cURL library.
Usage:

@example
pkg update
@end example

@item uninstall
Uninstall named packages.  For example,

@example
pkg uninstall image
@end example

@noindent
removes the @code{image} package from the system.  If another installed
package depends on the @code{image} package an error will be issued.
The package can be uninstalled anyway by using the @option{-nodeps} option.

@item load
Add named packages to the path.  After loading a package it is
possible to use the functions provided by the package.  For example,

@example
pkg load image
@end example

@noindent
adds the @code{image} package to the path.  It is possible to load all
installed packages at once with the keyword @samp{all}.  Usage:

@example
pkg load all
@end example

@item unload
Remove named packages from the path.  After unloading a package it is
no longer possible to use the functions provided by the package.  It is
possible to unload all installed packages at once with the keyword
@samp{all}.  Usage:

@example
pkg unload all
@end example

@item list
Show the list of currently installed packages.  For example,

@example
pkg list
@end example

@noindent
will produce a short report with the package name, version, and installation
directory for each installed package.  Supply a package name to limit
reporting to a particular package.  For example:

@example
pkg list image
@end example

If a single return argument is requested then @code{pkg} returns a cell
array where each element is a structure with information on a single
package.

@example
installed_packages = pkg ("list")
@end example

If two output arguments are requested @code{pkg} splits the list of
installed packages into those which were installed by the current user,
and those which were installed by the system administrator.

@example
[user_packages, system_packages] = pkg ("list")
@end example

The @qcode{"-forge"} option lists packages available at the Octave-Forge
repository.  This requires an internet connection and the cURL library.
For example:

@example
oct_forge_pkgs = pkg ("list", "-forge")
@end example

@item describe
Show a short description of the named installed packages, with the option
@qcode{"-verbose"} also list functions provided by the package.  For example,

@example
pkg describe -verbose all
@end example

@noindent
will describe all installed packages and the functions they provide.
If one output is requested a cell of structure containing the
description and list of functions of each package is returned as
output rather than printed on screen:

@example
desc = pkg ("describe", "secs1d", "image")
@end example

@noindent
If any of the requested packages is not installed, @code{pkg} returns an
error, unless a second output is requested:

@example
[desc, flag] = pkg ("describe", "secs1d", "image")
@end example

@noindent
@var{flag} will take one of the values @qcode{"Not installed"},
@qcode{"Loaded"}, or
@qcode{"Not loaded"} for each of the named packages.

@item prefix
Set the installation prefix directory.  For example,

@example
pkg prefix ~/my_octave_packages
@end example

@noindent
sets the installation prefix to @file{~/my_octave_packages}.
Packages will be installed in this directory.

It is possible to get the current installation prefix by requesting an
output argument.  For example:

@example
pfx = pkg ("prefix")
@end example

The location in which to install the architecture dependent files can be
independently specified with an addition argument.  For example:

@example
pkg prefix ~/my_octave_packages ~/my_arch_dep_pkgs
@end example

@item local_list
Set the file in which to look for information on locally
installed packages.  Locally installed packages are those that are
available only to the current user.  For example:

@example
pkg local_list ~/.octave_packages
@end example

It is possible to get the current value of local_list with the following

@example
pkg local_list
@end example

@item global_list
Set the file in which to look for information on globally
installed packages.  Globally installed packages are those that are
available to all users.  For example:

@example
pkg global_list /usr/share/octave/octave_packages
@end example

It is possible to get the current value of global_list with the following

@example
pkg global_list
@end example

@item build
Build a binary form of a package or packages.  The binary file produced
will itself be an Octave package that can be installed normally with
@code{pkg}.  The form of the command to build a binary package is

@example
pkg build builddir image-1.0.0.tar.gz @dots{}
@end example

@noindent
where @code{builddir} is the name of a directory where the temporary
installation will be produced and the binary packages will be found.
The options @option{-verbose} and @option{-nodeps} are respected, while
all other options are ignored.

@item rebuild
Rebuild the package database from the installed directories.  This can
be used in cases where the package database has been corrupted.
It can also take the @option{-auto} and @option{-noauto} options to allow the
autoloading state of a package to be changed.  For example,

@example
pkg rebuild -noauto image
@end example

@noindent
will remove the autoloading status of the image package.

@end table
@seealso{ver, news}
@end deftypefn
__clabel__
@c __clabel__ scripts/plot/appearance/__clabel__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} __clabel__ (@var{c}, @var{v}, @var{hparent}, @var{label_spacing}, @var{z}, @var{varargin})
Undocumented internal function.
@end deftypefn
__getlegenddata__
@c __getlegenddata__ scripts/plot/appearance/__getlegenddata__.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{hplots}, @var{strings}] =} __getlegenddata__ (@var{h})
Undocumented internal function.
@end deftypefn
annotation
@c annotation scripts/plot/appearance/annotation.m
-*- texinfo -*-
@deftypefn  {Function File} {} annotation (@var{type})
@deftypefnx {Function File} {} annotation ("line", @var{x}, @var{y})
@deftypefnx {Function File} {} annotation ("arrow", @var{x}, @var{y})
@deftypefnx {Function File} {} annotation ("doublearrow", @var{x}, @var{y})
@deftypefnx {Function File} {} annotation ("textarrow", @var{x}, @var{y})
@deftypefnx {Function File} {} annotation ("textbox", @var{pos})
@deftypefnx {Function File} {} annotation ("rectangle", @var{pos})
@deftypefnx {Function File} {} annotation ("ellipse", @var{pos})
@deftypefnx {Function File} {} annotation (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} annotation (@var{hf}, @dots{})
@deftypefnx {Function File} {@var{h} =} annotation (@dots{})
Draw annotations to emphasize parts of a figure.

You may build a default annotation by specifying only the @var{type}
of the annotation.

Otherwise you can select the type of annotation and then set its position
using either @var{x} and @var{y} coordinates for line-based annotations or a
position vector @var{pos} for others.  In either case, coordinates are
interpreted using the @qcode{"units"} property of the annotation object.
The default is @qcode{"normalized"}, which means the lower left hand corner
of the figure has coordinates @samp{[0 0]} and the upper right hand corner
@samp{[1 1]}.

If the first argument @var{hf} is a figure handle, then plot into this
figure, rather than the current figure returned by @code{gcf}.

Further arguments can be provided in the form of @var{prop}/@var{val} pairs
to customize the annotation appearance.

The optional return value @var{h} is a graphics handle to the created
annotation object.  This can be used with the @code{set} function to
customize an existing annotation object.

All annotation objects share two properties:

@itemize
@item @qcode{"units"}: the units in which coordinates are interpreted.@*
Its value may be one of @qcode{"centimeters"} | @qcode{"characters"} |
@qcode{"inches"} | @qcode{"@{normalized@}"} | @qcode{"pixels"} |
@qcode{"points"}.

@item @qcode{"position"}: a four-element vector [x0 y0 width height].@*
The vector specifies the coordinates (x0,y0) of the origin of the annotation
object, its width, and its height.  The width and height may be negative,
depending on the orientation of the object.

@end itemize

Valid annotation types and their specific properties are described
below:

@table @asis
@item @qcode{"line"}
Constructs a line.  @var{x} and @var{y} must be two-element vectors
specifying the x and y coordinates of the two ends of the line.

The line can be customized using @qcode{"linewidth"}, @qcode{"linestyle"},
and @qcode{"color"} properties the same way as for @code{line} objects.

@item @qcode{"arrow"}
Construct an arrow.  The second point in vectors @var{x} and @var{y}
specifies the arrowhead coordinates.

Besides line properties, the arrowhead can be customized using
@qcode{"headlength"}, @qcode{"headwidth"}, and @qcode{"headstyle"}
properties.  Supported values for @qcode{"headstyle"} property are:
[@qcode{"diamond"} | @qcode{"ellipse"} | @qcode{"plain"} |
@qcode{"rectangle"} | @qcode{"vback1"} | @qcode{"@{vback2@}"} |
@qcode{"vback3"}]

@item @qcode{"doublearrow"}
Construct a double arrow.  Vectors @var{x} and @var{y} specify the
arrowhead coordinates.

The line and the arrowhead can be customized as for arrow annotations, but
some property names are duplicated:
@qcode{"head1length"}/@qcode{"head2length"},
@qcode{"head1width"}/@qcode{"head2width"}, etc.  The index 1 marks the
properties of the arrowhead at the first point in @var{x} and @var{y}
coordinates.

@item @qcode{"textarrow"}
Construct an arrow with a text label at the opposite end from the arrowhead.

Use the "string" property to change the text string.
The line and the arrowhead can be customized as for arrow annotations, and
the text can be customized using the same properties as @code{text} graphics
objects.  Note, however, that some text property names are prefixed with
"text" to distinguish them from arrow properties:
@qcode{"textbackgroundcolor"}, @qcode{"textcolor"},
@qcode{"textedgecolor"}, @qcode{"textlinewidth"},
@qcode{"textmargin"}, @qcode{"textrotation"}.

@item @qcode{"textbox"}
Construct a box with text inside.  @var{pos} specifies the
@qcode{"position"} property of the annotation.

Use the "string" property to change the text string.
You may use @qcode{"backgroundcolor"}, @qcode{"edgecolor"},
@qcode{"linestyle"}, and @qcode{"linewidth"} properties to customize
the box background color and edge appearance.  A limited set of @code{text}
objects properties are also available; Besides @qcode{"font@dots{}"}
properties, you may also use @qcode{"horizontalalignment"} and
@qcode{"verticalalignment"} to position the text inside the box.

Finally, the @qcode{"fitboxtotext"} property controls the actual extent of
the box.  If @qcode{"on"} (the default) the box limits are fitted to the
text extent.

@item @qcode{"rectangle"}
Construct a rectangle.  @var{pos} specifies the @qcode{"position"} property
of the annotation.

You may use @qcode{"facecolor"}, @qcode{"color"}, @qcode{"linestyle"}, and
@qcode{"linewidth"} properties to customize the rectangle background color
and edge appearance.

@item @qcode{"ellipse"}
Construct an ellipse.  @var{pos} specifies the @qcode{"position"} property
of the annotation.

See @qcode{"rectangle"} annotations for customization.
@end table

@seealso{xlabel, ylabel, zlabel, title, text, gtext, legend, colorbar}
@end deftypefn
axis
@c axis scripts/plot/appearance/axis.m
-*- texinfo -*-
@deftypefn  {Function File} {} axis ()
@deftypefnx {Function File} {} axis ([@var{x}_lo @var{x}_hi])
@deftypefnx {Function File} {} axis ([@var{x}_lo @var{x}_hi @var{y}_lo @var{y}_hi])
@deftypefnx {Function File} {} axis ([@var{x}_lo @var{x}_hi @var{y}_lo @var{y}_hi @var{z}_lo @var{z}_hi])
@deftypefnx {Function File} {} axis (@var{option})
@deftypefnx {Function File} {} axis (@dots{}, @var{option})
@deftypefnx {Function File} {} axis (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{limits} =} axis ()
Set axis limits and appearance.

The argument @var{limits} should be a 2-, 4-, or 6-element vector.  The
first and second elements specify the lower and upper limits for the
x-axis.  The third and fourth specify the limits for the y-axis, and the
fifth and sixth specify the limits for the z-axis.  The special values
-Inf and Inf may be used to indicate that the limit should automatically be
computed based on the data in the axis.

Without any arguments, @code{axis} turns autoscaling on.

With one output argument, @code{@var{limits} = axis} returns the current
axis limits.

The vector argument specifying limits is optional, and additional string
arguments may be used to specify various axis properties.  For example,

@example
axis ([1, 2, 3, 4], "square");
@end example

@noindent
forces a square aspect ratio, and

@example
axis ("tic", "labely");
@end example

@noindent
turns tic marks on for all axes and tic mark labels on for the y-axis only.

@noindent
The following options control the aspect ratio of the axes.

@table @asis
@item @qcode{"square"}
Force a square aspect ratio.

@item @qcode{"equal"}
Force x distance to equal y-distance.

@item @qcode{"normal"}
Restore default aspect ratio.
@end table

@noindent
The following options control the way axis limits are interpreted.

@table @asis
@item @qcode{"auto"}
Set the specified axes to have nice limits around the data or all if no
axes are specified.

@item @qcode{"manual"}
Fix the current axes limits.

@item @qcode{"tight"}
Fix axes to the limits of the data.

@item @qcode{"image"}
Equivalent to @qcode{"tight"} and @qcode{"equal"}.
@end table

@noindent
The following options affect the appearance of tic marks.

@table @asis
@item @qcode{"on"}
Turn tic marks and labels on for all axes.

@item @qcode{"off"}
Turn tic marks off for all axes.

@item @qcode{"tic[xyz]"}
Turn tic marks on for all axes, or turn them on for the specified axes and
off for the remainder.

@item @qcode{"label[xyz]"}
Turn tic labels on for all axes, or turn them on for the specified axes
and off for the remainder.

@item @qcode{"nolabel"}
Turn tic labels off for all axes.
@end table

Note, if there are no tic marks for an axis, there can be no labels.

@noindent
The following options affect the direction of increasing values on the axes.

@table @asis
@item @qcode{"ij"}
Reverse y-axis, so lower values are nearer the top.

@item @qcode{"xy"}
Restore y-axis, so higher values are nearer the top.
@end table

If the first argument @var{hax} is an axes handle, then operate on this
axes rather than the current axes returned by @code{gca}.

@seealso{xlim, ylim, zlim, daspect, pbaspect, box, grid}
@end deftypefn
box
@c box scripts/plot/appearance/box.m
-*- texinfo -*-
@deftypefn  {Command} {} box
@deftypefnx {Command} {} box on
@deftypefnx {Command} {} box off
@deftypefnx {Function File} {} box (@var{hax}, @dots{})
Control display of the axis border.

The argument may be either @qcode{"on"} or @qcode{"off"}.  If it is
omitted, the current box state is toggled.

If the first argument @var{hax} is an axes handle, then operate on this
axis rather than the current axes returned by @code{gca}.
@seealso{axis, grid}
@end deftypefn
caxis
@c caxis scripts/plot/appearance/caxis.m
-*- texinfo -*-
@deftypefn  {Function File} {} caxis ([cmin cmax])
@deftypefnx {Function File} {} caxis ("auto")
@deftypefnx {Function File} {} caxis ("manual")
@deftypefnx {Function File} {} caxis (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{limits} =} caxis ()
Query or set color axis limits for plots.

The limits argument should be a 2-element vector specifying the lower and
upper limits to assign to the first and last value in the colormap.  Data
values outside this range are clamped to the first and last colormap
entries.

If the @qcode{"auto"} option is given then automatic colormap limits are
applied.  The automatic algorithm sets @var{cmin} to the minimum data value
and @var{cmax} to the maximum data value.  If @qcode{"manual"} is specified
then the @qcode{"climmode"} property is set to @qcode{"manual"} and the
numeric values in the @qcode{"clim"} property are used for limits.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

Called without arguments the current color axis limits are returned.
@seealso{colormap}
@end deftypefn
clabel
@c clabel scripts/plot/appearance/clabel.m
-*- texinfo -*-
@deftypefn  {Function File} {} clabel (@var{c}, @var{h})
@deftypefnx {Function File} {} clabel (@var{c}, @var{h}, @var{v})
@deftypefnx {Function File} {} clabel (@var{c}, @var{h}, "manual")
@deftypefnx {Function File} {} clabel (@var{c})
@deftypefnx {Function File} {} clabel (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} clabel (@dots{})
Add labels to the contours of a contour plot.

The contour levels are specified by the contour matrix @var{c} which is
returned by @code{contour}, @code{contourc}, @code{contourf}, and
@code{contour3}.  Contour labels are rotated to match the local line
orientation and centered on the line.  The position of labels along the
contour line is chosen randomly.

If the argument @var{h} is a handle to a contour group object, then label
this plot rather than the one in the current axes returned by @code{gca}.

By default, all contours are labeled.  However, the contours to label can be
specified by the vector @var{v}.  If the @qcode{"manual"} argument is
given then the contours to label can be selected with the mouse.

Additional property/value pairs that are valid properties of text objects
can be given and are passed to the underlying text objects.  Moreover,
the contour group property @qcode{"LabelSpacing"} is available which
determines the spacing between labels on a contour to be specified.  The
default is 144 points, or 2 inches.

The optional return value @var{h} is a vector of graphics handles to
the text objects representing each label.
The @qcode{"userdata"} property of the text objects contains the numerical
value of the contour label.

An example of the use of @code{clabel} is

@example
@group
[c, h] = contour (peaks (), -4 : 6);
clabel (c, h, -4:2:6, "fontsize", 12);
@end group
@end example

@seealso{contour, contourf, contour3, meshc, surfc, text}
@end deftypefn
daspect
@c daspect scripts/plot/appearance/daspect.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{data_aspect_ratio} =} daspect ()
@deftypefnx {Function File} {} daspect (@var{data_aspect_ratio})
@deftypefnx {Function File} {} daspect (@var{mode})
@deftypefnx {Function File} {@var{data_aspect_ratio_mode} =} daspect ("mode")
@deftypefnx {Function File} {} daspect (@var{hax}, @dots{})
Query or set the data aspect ratio of the current axes.

The aspect ratio is a normalized 3-element vector representing the span of
the x, y, and z-axis limits.

@code{daspect (@var{mode})}

Set the data aspect ratio mode of the current axes.  @var{mode} is
either @qcode{"auto"} or @qcode{"manual"}.

@code{daspect (@qcode{"mode"})}

Return the data aspect ratio mode of the current axes.

@code{daspect (@var{hax}, @dots{})}

Operate on the axes in handle @var{hax} instead of the current axes.

@seealso{axis, pbaspect, xlim, ylim, zlim}
@end deftypefn
datetick
@c datetick scripts/plot/appearance/datetick.m
-*- texinfo -*-
@deftypefn  {Function File} {} datetick ()
@deftypefnx {Function File} {} datetick (@var{form})
@deftypefnx {Function File} {} datetick (@var{axis}, @var{form})
@deftypefnx {Function File} {} datetick (@dots{}, "keeplimits")
@deftypefnx {Function File} {} datetick (@dots{}, "keepticks")
@deftypefnx {Function File} {} datetick (@var{hax}, @dots{})
Add date formatted tick labels to an axis.

The axis to apply the ticks to is determined by @var{axis} which can take
the values @qcode{"x"}, @qcode{"y"}, or @qcode{"z"}.  The default value is
@qcode{"x"}.

The formatting of the labels is determined by the variable @var{form}, which
can either be a string or positive integer that @code{datestr} accepts.
@seealso{datenum, datestr}
@end deftypefn
diffuse
@c diffuse scripts/plot/appearance/diffuse.m
-*- texinfo -*-
@deftypefn {Function File} {} diffuse (@var{sx}, @var{sy}, @var{sz}, @var{lv})
Calculate the diffuse reflection strength of a surface defined by the normal
vector elements @var{sx}, @var{sy}, @var{sz}.

The light source location vector @var{lv} can be given as a 2-element vector
[azimuth, elevation] in degrees or as a 3-element vector [x, y, z].
@seealso{specular, surfl}
@end deftypefn
grid
@c grid scripts/plot/appearance/grid.m
-*- texinfo -*-
@deftypefn  {Command} {} grid
@deftypefnx {Command} {} grid on
@deftypefnx {Command} {} grid off
@deftypefnx {Command} {} grid minor
@deftypefnx {Command} {} grid minor on
@deftypefnx {Command} {} grid minor off
@deftypefnx {Function File} {} grid (@var{hax}, @dots{})
Control the display of plot grid lines.

The function state input may be either @qcode{"on"} or @qcode{"off"}.
If it is omitted, the current grid state is toggled.

When the first argument is @qcode{"minor"} all subsequent commands
modify the minor grid rather than the major grid.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

To control the grid lines for an individual axis use the @code{set}
function.  For example:

@example
set (gca, "ygrid", "on");
@end example
@seealso{axis, box}
@end deftypefn
gtext
@c gtext scripts/plot/appearance/gtext.m
-*- texinfo -*-
@deftypefn  {Function File} {} gtext (@var{s})
@deftypefnx {Function File} {} gtext (@{@var{s1}, @var{s2}, @dots{}@})
@deftypefnx {Function File} {} gtext (@{@var{s1}; @var{s2}; @dots{}@})
@deftypefnx {Function File} {} gtext (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} gtext (@dots{})
Place text on the current figure using the mouse.

The text is defined by the string @var{s}.  If @var{s} is a cell string
organized as a row vector then each string of the cell array is written to a
separate line.  If @var{s} is organized as a column vector then one string
element of the cell array is placed for every mouse click.

Optional property/value pairs are passed directly to the underlying text
objects.

The optional return value @var{h} is a graphics handle to the created
text object(s).
@seealso{ginput, text}
@end deftypefn
hidden
@c hidden scripts/plot/appearance/hidden.m
-*- texinfo -*-
@deftypefn  {Command} {} hidden
@deftypefnx {Command} {} hidden on
@deftypefnx {Command} {} hidden off
@deftypefnx {Function File} {@var{mode} =} hidden (@dots{})
Control mesh hidden line removal.

When called with no argument the hidden line removal state is toggled.

When called with one of the modes @qcode{"on"} or @qcode{"off"} the state
is set accordingly.

The optional output argument @var{mode} is the current state.

Hidden Line Removal determines what graphic objects behind a mesh plot
are visible.  The default is for the mesh to be opaque and lines behind
the mesh are not visible.  If hidden line removal is turned off then
objects behind the mesh can be seen through the faces (openings) of the
mesh, although the mesh grid lines are still opaque.

@seealso{mesh, meshc, meshz, ezmesh, ezmeshc, trimesh, waterfall}
@end deftypefn
legend
@c legend scripts/plot/appearance/legend.m
-*- texinfo -*-
@deftypefn  {Function File} {} legend (@var{str1}, @var{str2}, @dots{})
@deftypefnx {Function File} {} legend (@var{matstr})
@deftypefnx {Function File} {} legend (@var{cellstr})
@deftypefnx {Function File} {} legend (@dots{}, "location", @var{pos})
@deftypefnx {Function File} {} legend (@dots{}, "orientation", @var{orient})
@deftypefnx {Function File} {} legend (@var{hax}, @dots{})
@deftypefnx {Function File} {} legend (@var{hobjs}, @dots{})
@deftypefnx {Function File} {} legend (@var{hax}, @var{hobjs}, @dots{})
@deftypefnx {Function File} {} legend ("@var{option}")
@deftypefnx {Function File} {[@var{hleg}, @var{hleg_obj}, @var{hplot}, @var{labels}] =} legend (@dots{})

Display a legend for the current axes using the specified strings as labels.

Legend entries may be specified as individual character string arguments,
a character array, or a cell array of character strings.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.  If the handles,
@var{hobjs}, are not specified then the legend's strings will be associated
with the axes' descendants.  @code{legend} works on line graphs,
bar graphs, etc.  A plot must exist before legend is called.

The optional parameter @var{pos} specifies the location of the legend
as follows:

@multitable @columnfractions 0.06 0.14 0.80
@headitem @tab pos @tab location of the legend
@item @tab north @tab center top
@item @tab south @tab center bottom
@item @tab east @tab right center
@item @tab west @tab left center
@item @tab northeast @tab right top (default)
@item @tab northwest @tab left top
@item @tab southeast @tab right bottom
@item @tab southwest @tab left bottom
@item
@item @tab outside @tab can be appended to any location string
@end multitable

The optional parameter @var{orient} determines if the key elements are
placed vertically or horizontally.  The allowed values are
@qcode{"vertical"} (default) or @qcode{"horizontal"}.

The following customizations are available using @var{option}:

@table @asis
@item @qcode{"show"}
  Show legend on the plot

@item @qcode{"hide"}
  Hide legend on the plot

@item @qcode{"toggle"}
  Toggles between @qcode{"hide"} and @qcode{"show"}

@item @qcode{"boxon"}
  Show a box around legend (default)

@item @qcode{"boxoff"}
  Hide the box around legend

@item @qcode{"right"}
  Place label text to the right of the keys (default)

@item @qcode{"left"}
  Place label text to the left of the keys

@item @qcode{"off"}
  Delete the legend object
@end table

The optional output values are

@table @var
@item hleg
  The graphics handle of the legend object.

@item hleg_obj
  Graphics handles to the text and line objects which make up the legend.

@item hplot
  Graphics handles to the plot objects which were used in making the legend.

@item labels
  A cell array of strings of the labels in the legend.
@end table

The legend label text is either provided in the call to @code{legend} or
is taken from the DisplayName property of graphics objects.  If no
labels or DisplayNames are available, then the label text is simply
@qcode{"data1"}, @qcode{"data2"}, @dots{}, @nospell{@qcode{"dataN"}}.

Implementation Note: A legend is implemented as an additional axes object
of the current figure with the @qcode{"tag"} set to @qcode{"legend"}.
Properties of the legend object may be manipulated directly by using
@code{set}.
@end deftypefn
orient
@c orient scripts/plot/appearance/orient.m
-*- texinfo -*-
@deftypefn  {Function File} {} orient (@var{orientation})
@deftypefnx {Function File} {} orient (@var{hfig}, @var{orientation})
@deftypefnx {Function File} {@var{orientation} =} orient ()
@deftypefnx {Function File} {@var{orientation} =} orient (@var{hfig})
Query or set the print orientation for figure @var{hfig}.

Valid values for @var{orientation} are @qcode{"portrait"},
@qcode{"landscape"}, and @qcode{"tall"}.

The @qcode{"landscape"} option changes the orientation so the plot width
is larger than the plot height.  The @qcode{"paperposition"} is also
modified so that the plot fills the page, while leaving a 0.25 inch border.

The @qcode{"tall"} option sets the orientation to @qcode{"portrait"} and
fills the page with the plot, while leaving a 0.25 inch border.

The @qcode{"portrait"} option (default) changes the orientation so the plot
height is larger than the plot width.  It also restores the default
@qcode{"paperposition"} property.

When called with no arguments, return the current print orientation.

If the argument @var{hfig} is omitted, then operate on the current figure
returned by @code{gcf}.
@seealso{print, saveas}
@end deftypefn
pbaspect
@c pbaspect scripts/plot/appearance/pbaspect.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{plot_box_aspect_ratio} =} pbaspect ( )
@deftypefnx {Function File} {} pbaspect (@var{plot_box_aspect_ratio})
@deftypefnx {Function File} {} pbaspect (@var{mode})
@deftypefnx {Function File} {@var{plot_box_aspect_ratio_mode} =} pbaspect ("mode")
@deftypefnx {Function File} {} pbaspect (@var{hax}, @dots{})

Query or set the plot box aspect ratio of the current axes.

The aspect ratio is a normalized 3-element vector representing the rendered
lengths of the x, y, and z axes.

@code{pbaspect(@var{mode})}

Set the plot box aspect ratio mode of the current axes.  @var{mode} is
either @qcode{"auto"} or @qcode{"manual"}.

@code{pbaspect ("mode")}

Return the plot box aspect ratio mode of the current axes.

@code{pbaspect (@var{hax}, @dots{})}

Operate on the axes in handle @var{hax} instead of the current axes.

@seealso{axis, daspect, xlim, ylim, zlim}
@end deftypefn
shading
@c shading scripts/plot/appearance/shading.m
-*- texinfo -*-
@deftypefn  {Function File} {} shading (@var{type})
@deftypefnx {Function File} {} shading (@var{hax}, @var{type})
Set the shading of patch or surface graphic objects.

Valid arguments for @var{type} are

@table @asis
@item @qcode{"flat"}
Single colored patches with invisible edges.

@item @qcode{"faceted"}
Single colored patches with visible edges.

@item @qcode{"interp"}
Color between patch vertices are interpolated and the patch edges are
invisible.
@end table

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.
@seealso{fill, mesh, patch, pcolor, surf, surface, hidden}
@end deftypefn
specular
@c specular scripts/plot/appearance/specular.m
-*- texinfo -*-
@deftypefn  {Function File} {} specular (@var{sx}, @var{sy}, @var{sz}, @var{lv}, @var{vv})
@deftypefnx {Function File} {} specular (@var{sx}, @var{sy}, @var{sz}, @var{lv}, @var{vv}, @var{se})
Calculate the specular reflection strength of a surface defined by the
normal vector elements @var{sx}, @var{sy}, @var{sz} using Phong's
approximation.

The light source location and viewer location vectors are specified using
parameters @var{lv} and @var{vv} respectively.  The location vectors can
given as 2-element vectors [azimuth, elevation] in degrees or as 3-element
vectors [x, y, z].

An optional sixth argument specifies the specular exponent (spread) @var{se}.
If not given, @var{se} defaults to 10.
@seealso{diffuse, surfl}
@end deftypefn
text
@c text scripts/plot/appearance/text.m
-*- texinfo -*-
@deftypefn  {Function File} {} text (@var{x}, @var{y}, @var{string})
@deftypefnx {Function File} {} text (@var{x}, @var{y}, @var{z}, @var{string})
@deftypefnx {Function File} {} text (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} text (@dots{})
Create a text object with text @var{string} at position @var{x}, @var{y},
(@var{z}) on the current axes.

Multiple locations can be specified if @var{x}, @var{y}, (@var{z}) are
vectors.  Multiple strings can be specified with a character matrix or
a cell array of strings.

Optional property/value pairs may be used to control the appearance of the
text.

The optional return value @var{h} is a vector of graphics handles to the
created text objects.
@seealso{gtext, title, xlabel, ylabel, zlabel}
@end deftypefn
title
@c title scripts/plot/appearance/title.m
-*- texinfo -*-
@deftypefn  {Function File} {} title (@var{string})
@deftypefnx {Function File} {} title (@var{string}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} title (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} title (@dots{})
Specify the string used as a title for the current axis.

An optional list of @var{property}/@var{value} pairs can be used to change
the appearance of the created title text object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created text
object.
@seealso{xlabel, ylabel, zlabel, text}
@end deftypefn
view
@c view scripts/plot/appearance/view.m
-*- texinfo -*-
@deftypefn  {Function File} {} view (@var{azimuth}, @var{elevation})
@deftypefnx {Function File} {} view ([@var{azimuth} @var{elevation}])
@deftypefnx {Function File} {} view ([@var{x} @var{y} @var{z}])
@deftypefnx {Function File} {} view (2)
@deftypefnx {Function File} {} view (3)
@deftypefnx {Function File} {} view (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{azimuth}, @var{elevation}] =} view ()
Query or set the viewpoint for the current axes.

The parameters @var{azimuth} and @var{elevation} can be given as two
arguments or as 2-element vector.  The viewpoint can also be specified with
Cartesian coordinates @var{x}, @var{y}, and @var{z}.

The call @code{view (2)} sets the viewpoint to @w{@var{azimuth} = 0}
and @w{@var{elevation} = 90}, which is the default for 2-D graphs.

The call @code{view (3)} sets the viewpoint to @w{@var{azimuth} = -37.5}
and @w{@var{elevation} = 30}, which is the default for 3-D graphs.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

If no inputs are given, return the current @var{azimuth} and @var{elevation}.
@end deftypefn
whitebg
@c whitebg scripts/plot/appearance/whitebg.m
-*- texinfo -*-
@deftypefn  {Function File} {} whitebg ()
@deftypefnx {Function File} {} whitebg (@var{color})
@deftypefnx {Function File} {} whitebg ("none")
@deftypefnx {Function File} {} whitebg (@var{hfig}, @dots{})
Invert the colors in the current color scheme.

The root properties are also inverted such that all subsequent plot use the
new color scheme.

If the optional argument @var{color} is present then the background color
is set to @var{color} rather than inverted.  @var{color} may be a string
representing one of the eight known colors or an RGB triplet.  The special
string argument @qcode{"none"} restores the plot to the default colors.

If the first argument @var{hfig} is a figure handle, then operate on
this figure rather than the current figure returned by @code{gcf}.  The
root properties will not be changed.
@seealso{reset, get, set}
@end deftypefn
xlabel
@c xlabel scripts/plot/appearance/xlabel.m
-*- texinfo -*-
@deftypefn  {Function File} {} xlabel (@var{string})
@deftypefnx {Function File} {} xlabel (@var{string}, @var{property}, @var{val}, @dots{})
@deftypefnx {Function File} {} xlabel (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} xlabel (@dots{})
Specify the string used to label the x-axis of the current axis.

An optional list of @var{property}/@var{value} pairs can be used to change
the properties of the created text label.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created text
object.
@seealso{ylabel, zlabel, datetick, title, text}
@end deftypefn
xlim
@c xlim scripts/plot/appearance/xlim.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{xlimits} =} xlim ()
@deftypefnx {Function File} {@var{xmode} =} xlim ("mode")
@deftypefnx {Function File} {} xlim ([@var{x_lo} @var{x_hi}])
@deftypefnx {Function File} {} xlim ("auto")
@deftypefnx {Function File} {} xlim ("manual")
@deftypefnx {Function File} {} xlim (@var{hax}, @dots{})
Query or set the limits of the x-axis for the current plot.

Called without arguments @code{xlim} returns the x-axis limits of the
current plot.

With the input query @qcode{"mode"}, return the current x-limit
calculation mode which is either @qcode{"auto"} or @qcode{"manual"}.

If passed a 2-element vector [@var{x_lo} @var{x_hi}], the limits of the
x-axis are set to these values and the mode is set to @qcode{"manual"}.

The current plotting mode can be changed by using either @qcode{"auto"}
or @qcode{"manual"} as the argument.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.
@seealso{ylim, zlim, axis, set, get, gca}
@end deftypefn
ylabel
@c ylabel scripts/plot/appearance/ylabel.m
-*- texinfo -*-
@deftypefn  {Function File} {} ylabel (@var{string})
@deftypefnx {Function File} {} ylabel (@var{string}, @var{property}, @var{val}, @dots{})
@deftypefnx {Function File} {} ylabel (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ylabel (@dots{})
Specify the string used to label the y-axis of the current axis.

If @var{hax} is specified then label the axis defined by @var{hax}.

An optional list of @var{property}/@var{value} pairs can be used to change
the properties of the created text label.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created text
object.
@seealso{xlabel, zlabel, datetick, title, text}
@end deftypefn
ylim
@c ylim scripts/plot/appearance/ylim.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{ylimits} =} ylim ()
@deftypefnx {Function File} {@var{xmode} =} ylim ("mode")
@deftypefnx {Function File} {} ylim ([@var{y_lo} @var{y_hi}])
@deftypefnx {Function File} {} ylim ("auto")
@deftypefnx {Function File} {} ylim ("manual")
@deftypefnx {Function File} {} ylim (@var{hax}, @dots{})
Query or set the limits of the y-axis for the current plot.

Called without arguments @code{ylim} returns the y-axis limits of the
current plot.

With the input query @qcode{"mode"}, return the current
y-limit calculation mode which is either @qcode{"auto"} or @qcode{"manual"}.

If passed a 2-element vector [@var{y_lo} @var{y_hi}], the limits of the
y-axis are set to these values and the mode is set to @qcode{"manual"}.

The current plotting mode can be changed by using either @qcode{"auto"}
or @qcode{"manual"} as the argument.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.
@seealso{xlim, zlim, axis, set, get, gca}
@end deftypefn
zlabel
@c zlabel scripts/plot/appearance/zlabel.m
-*- texinfo -*-
@deftypefn  {Function File} {} zlabel (@var{string})
@deftypefnx {Function File} {} zlabel (@var{string}, @var{property}, @var{val}, @dots{})
@deftypefnx {Function File} {} zlabel (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} zlabel (@dots{})
Specify the string used to label the z-axis of the current axis.

An optional list of @var{property}/@var{value} pairs can be used to change
the properties of the created text label.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created text
object.
@seealso{xlabel, ylabel, datetick, title, text}
@end deftypefn
Author: jwe
zlim
@c zlim scripts/plot/appearance/zlim.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{zlimits} =} zlim ()
@deftypefnx {Function File} {@var{xmode} =} zlim ("mode")
@deftypefnx {Function File} {} zlim ([@var{z_lo} @var{z_hi}])
@deftypefnx {Function File} {} zlim ("auto")
@deftypefnx {Function File} {} zlim ("manual")
@deftypefnx {Function File} {} zlim (@var{hax}, @dots{})
Query or set the limits of the z-axis for the current plot.

Called without arguments @code{zlim} returns the z-axis limits of the
current plot.

With the input query @qcode{"mode"}, return the current
z-limit calculation mode which is either @qcode{"auto"} or @qcode{"manual"}.

If passed a 2-element vector [@var{z_lo} @var{z_hi}], the limits of the
x-axis are set to these values and the mode is set to @qcode{"manual"}.

The current plotting mode can be changed by using either @qcode{"auto"}
or @qcode{"manual"} as the argument.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.
@seealso{xlim, ylim, axis, set, get, gca}
@end deftypefn
area
@c area scripts/plot/draw/area.m
-*- texinfo -*-
@deftypefn  {Function File} {} area (@var{y})
@deftypefnx {Function File} {} area (@var{x}, @var{y})
@deftypefnx {Function File} {} area (@dots{}, @var{lvl})
@deftypefnx {Function File} {} area (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} area (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} area (@dots{})
Area plot of the columns of @var{y}.

This plot shows the contributions of each column value to the row sum.
It is functionally similar to @code{plot (@var{x}, cumsum (@var{y}, 2))},
except that the area under the curve is shaded.

If the @var{x} argument is omitted it defaults to @code{1:rows (@var{y})}.
A value @var{lvl} can be defined that determines where the base level of
the shading under the curve should be defined.  The default level is 0.

Additional property/value pairs are passed directly to the underlying patch
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the hggroup
object comprising the area patch objects.  The @qcode{"BaseValue"} property
of the hggroup can be used to adjust the level where shading begins.

Example: Verify identity sin^2 + cos^2 = 1

@example
@group
t = linspace (0, 2*pi, 100)';
y = [sin(t).^2, cos(t).^2];
area (t, y);
legend ("sin^2", "cos^2", "location", "NorthEastOutside");
@end group
@end example
@seealso{plot, patch}
@end deftypefn
barh
@c barh scripts/plot/draw/barh.m
-*- texinfo -*-
@deftypefn  {Function File} {} barh (@var{y})
@deftypefnx {Function File} {} barh (@var{x}, @var{y})
@deftypefnx {Function File} {} barh (@dots{}, @var{w})
@deftypefnx {Function File} {} barh (@dots{}, @var{style})
@deftypefnx {Function File} {} barh (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} barh (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} barh (@dots{}, @var{prop}, @var{val}, @dots{})
Produce a horizontal bar graph from two vectors of X-Y data.

If only one argument is given, it is taken as a vector of Y values
and the X coordinates are the range @code{1:numel (@var{y})}.

The optional input @var{w} controls the width of the bars.  A value of
1.0 will cause each bar to exactly touch any adjacent bars.
The default width is 0.8.

If @var{y} is a matrix, then each column of @var{y} is taken to be a
separate bar graph plotted on the same graph.  By default the columns
are plotted side-by-side.  This behavior can be changed by the @var{style}
argument which can take the following values:

@table @asis
@item @qcode{"grouped"} (default)
Side-by-side bars with a gap between bars and centered over the Y-coordinate.

@item  @qcode{"stacked"}
Bars are stacked so that each Y value has a single bar composed of
multiple segments.

@item @qcode{"hist"}
Side-by-side bars with no gap between bars and centered over the
Y-coordinate.

@item @qcode{"histc"}
Side-by-side bars with no gap between bars and left-aligned to the
Y-coordinate.
@end table

Optional property/value pairs are passed directly to the underlying patch
objects.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
bar series hggroup.  For a description of the use of the
bar series, @pxref{XREFbar,,bar}.
@seealso{bar, hist, pie, plot, patch}
@end deftypefn
bar
@c bar scripts/plot/draw/bar.m
-*- texinfo -*-
@deftypefn  {Function File} {} bar (@var{y})
@deftypefnx {Function File} {} bar (@var{x}, @var{y})
@deftypefnx {Function File} {} bar (@dots{}, @var{w})
@deftypefnx {Function File} {} bar (@dots{}, @var{style})
@deftypefnx {Function File} {} bar (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} bar (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} bar (@dots{}, @var{prop}, @var{val}, @dots{})
Produce a bar graph from two vectors of X-Y data.

If only one argument is given, @var{y}, it is taken as a vector of Y values
and the X coordinates are the range @code{1:numel (@var{y})}.

The optional input @var{w} controls the width of the bars.  A value of
1.0 will cause each bar to exactly touch any adjacent bars.
The default width is 0.8.

If @var{y} is a matrix, then each column of @var{y} is taken to be a
separate bar graph plotted on the same graph.  By default the columns
are plotted side-by-side.  This behavior can be changed by the @var{style}
argument which can take the following values:

@table @asis
@item @qcode{"grouped"} (default)
Side-by-side bars with a gap between bars and centered over the X-coordinate.

@item  @qcode{"stacked"}
Bars are stacked so that each X value has a single bar composed of
multiple segments.

@item @qcode{"hist"}
Side-by-side bars with no gap between bars and centered over the
X-coordinate.

@item @qcode{"histc"}
Side-by-side bars with no gap between bars and left-aligned to the
X-coordinate.
@end table

Optional property/value pairs are passed directly to the underlying patch
objects.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of handles to the created
"bar series" hggroups with one handle per column of the variable @var{y}.
This series makes it possible to change a common element in one bar series
object and have the change reflected in the other "bar series".
For example,

@example
@group
h = bar (rand (5, 10));
set (h(1), "basevalue", 0.5);
@end group
@end example

@noindent
changes the position on the base of all of the bar series.

The following example modifies the face and edge colors using
property/value pairs.

@example
bar (randn (1, 100), "facecolor", "r", "edgecolor", "b");
@end example

@noindent
The color of the bars is taken from the figure's colormap, such that

@example
@group
bar (rand (10, 3));
colormap (summer (64));
@end group
@end example

@noindent
will change the colors used for the bars.  The color of bars can also be set
manually using the @qcode{"facecolor"} property as shown below.

@example
@group
h = bar (rand (10, 3));
set (h(1), "facecolor", "r")
set (h(2), "facecolor", "g")
set (h(3), "facecolor", "b")
@end group
@end example

@seealso{barh, hist, pie, plot, patch}
@end deftypefn
colorbar
@c colorbar scripts/plot/draw/colorbar.m
-*- texinfo -*-
@deftypefn  {Command} {} colorbar
@deftypefnx {Function File} {} colorbar (@var{loc})
@deftypefnx {Function File} {} colorbar (@var{delete_option})
@deftypefnx {Function File} {} colorbar (@var{hcb}, @dots{})
@deftypefnx {Function File} {} colorbar (@var{hax}, @dots{})
@deftypefnx {Function File} {} colorbar (@dots{}, "peer", @var{hax}, @dots{})
@deftypefnx {Function File} {} colorbar (@dots{}, "location", @var{loc}, @dots{})
@deftypefnx {Function File} {} colorbar (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} colorbar (@dots{})
Add a colorbar to the current axes.

A colorbar displays the current colormap along with numerical rulings
so that the color scale can be interpreted.

The optional input @var{loc} determines the location of the colorbar.
Valid values for @var{loc} are

@table @asis
@item @qcode{"EastOutside"}
Place the colorbar outside the plot to the right.  This is the default.

@item @qcode{"East"}
Place the colorbar inside the plot to the right.

@item @qcode{"WestOutside"}
Place the colorbar outside the plot to the left.

@item @qcode{"West"}
Place the colorbar inside the plot to the left.

@item @qcode{"NorthOutside"}
Place the colorbar above the plot.

@item @qcode{"North"}
Place the colorbar at the top of the plot.

@item @qcode{"SouthOutside"}
Place the colorbar under the plot.

@item @qcode{"South"}
Place the colorbar at the bottom of the plot.
@end table

To remove a colorbar from a plot use any one of the following keywords for
the @var{delete_option}: @qcode{"delete"}, @qcode{"hide"}, @qcode{"off"}.

If the argument @qcode{"peer"} is given, then the following argument is
treated as the axes handle in which to add the colorbar.  Alternatively,
If the first argument @var{hax} is an axes handle, then the colorbar is
added to this axis, rather than the current axes returned by @code{gca}.

If the first argument @var{hcb} is a handle to a colorbar object, then
operate on this colorbar directly.

Additional property/value pairs are passed directly to the underlying axes
object.

The optional return value @var{h} is a graphics handle to the created
colorbar object.

Implementation Note: A colorbar is created as an additional axes to the
current figure with the @qcode{"tag"} property set to @qcode{"colorbar"}.
The created axes object has the extra property @qcode{"location"} which
controls the positioning of the colorbar.
@seealso{colormap}
@end deftypefn
comet3
@c comet3 scripts/plot/draw/comet3.m
-*- texinfo -*-
@deftypefn  {Function File} {} comet3 (@var{z})
@deftypefnx {Function File} {} comet3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} comet3 (@var{x}, @var{y}, @var{z}, @var{p})
@deftypefnx {Function File} {} comet3 (@var{hax}, @dots{})
Produce a simple comet style animation along the trajectory provided by
the input coordinate vectors (@var{x}, @var{y}, @var{z}).

If only @var{z} is specified then @var{x}, @var{y} default to the indices
of @var{z}.

The speed of the comet may be controlled by @var{p}, which represents the
time each point is displayed before moving to the next one.  The default for
@var{p} is 0.1 seconds.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.
@seealso{comet}
@end deftypefn
comet
@c comet scripts/plot/draw/comet.m
-*- texinfo -*-
@deftypefn  {Function File} {} comet (@var{y})
@deftypefnx {Function File} {} comet (@var{x}, @var{y})
@deftypefnx {Function File} {} comet (@var{x}, @var{y}, @var{p})
@deftypefnx {Function File} {} comet (@var{hax}, @dots{})
Produce a simple comet style animation along the trajectory provided by
the input coordinate vectors (@var{x}, @var{y}).

If @var{x} is not specified it defaults to the indices of @var{y}.

The speed of the comet may be controlled by @var{p}, which represents the
time each point is displayed before moving to the next one.  The default for
@var{p} is 0.1 seconds.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.
@seealso{comet3}
@end deftypefn
compass
@c compass scripts/plot/draw/compass.m
-*- texinfo -*-
@deftypefn  {Function File} {} compass (@var{u}, @var{v})
@deftypefnx {Function File} {} compass (@var{z})
@deftypefnx {Function File} {} compass (@dots{}, @var{style})
@deftypefnx {Function File} {} compass (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} compass (@dots{})

Plot the @code{(@var{u}, @var{v})} components of a vector field emanating
from the origin of a polar plot.

The arrow representing each vector has one end at the origin and the tip at
[@var{u}(i), @var{v}(i)].  If a single complex argument @var{z} is given,
then @code{@var{u} = real (@var{z})} and @code{@var{v} = imag (@var{z})}.

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to the
line objects representing the drawn vectors.

@example
@group
a = toeplitz ([1;randn(9,1)], [1,randn(1,9)]);
compass (eig (a));
@end group
@end example

@seealso{polar, feather, quiver, rose, plot}
@end deftypefn
contour3
@c contour3 scripts/plot/draw/contour3.m
-*- texinfo -*-
@deftypefn  {Function File} {} contour3 (@var{z})
@deftypefnx {Function File} {} contour3 (@var{z}, @var{vn})
@deftypefnx {Function File} {} contour3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} contour3 (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {Function File} {} contour3 (@dots{}, @var{style})
@deftypefnx {Function File} {} contour3 (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contour3 (@dots{})
Create a 3-D contour plot.

@code{contour3} plots level curves (contour lines) of the matrix @var{z}
at a Z level corresponding to each contour.  This is in contrast to
@code{contour} which plots all of the contour lines at the same Z level
and produces a 2-D plot.

The level curves are taken from the contour matrix @var{c} computed by
@code{contourc} for the same arguments; see the latter for their
interpretation.

The appearance of contour lines can be defined with a line style @var{style}
in the same manner as @code{plot}.  Only line style and color are used;
Any markers defined by @var{style} are ignored.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional output @var{c} are the contour levels in @code{contourc} format.

The optional return value @var{h} is a graphics handle to the hggroup
comprising the contour lines.

Example:

@example
@group
contour3 (peaks (19));
colormap cool;
hold on;
surf (peaks (19), "facecolor", "none", "edgecolor", "black");
@end group
@end example

@seealso{contour, contourc, contourf, clabel, meshc, surfc, caxis, colormap, plot}
@end deftypefn
contourc
@c contourc scripts/plot/draw/contourc.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{c}, @var{lev}] =} contourc (@var{z})
@deftypefnx {Function File} {[@var{c}, @var{lev}] =} contourc (@var{z}, @var{vn})
@deftypefnx {Function File} {[@var{c}, @var{lev}] =} contourc (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {[@var{c}, @var{lev}] =} contourc (@var{x}, @var{y}, @var{z}, @var{vn})
Compute contour lines (isolines of constant Z value).

The matrix @var{z} contains height values above the rectangular grid
determined by @var{x} and @var{y}.  If only a single input @var{z} is
provided then @var{x} is taken to be @code{1:rows (@var{z})} and @var{y} is
taken to be @code{1:columns (@var{z})}.

The optional input @var{vn} is either a scalar denoting the number of
contour lines to compute or a vector containing the Z values where lines
will be computed.  When @var{vn} is a vector the number of contour lines
is @code{numel (@var{vn})}.  However, to compute a single contour line
at a given value use @code{@var{vn} = [val, val]}.  If @var{vn} is omitted
it defaults to 10.

The return value @var{c} is a 2x@var{n} matrix containing the
contour lines in the following format

@example
@group
@var{c} = [lev1, x1, x2, @dots{}, levn, x1, x2, ...
     len1, y1, y2, @dots{}, lenn, y1, y2, @dots{}]
@end group
@end example

@noindent
in which contour line @var{n} has a level (height) of @var{levn} and
length of @var{lenn}.

The optional return value @var{lev} is a vector with the Z values of
the contour levels.

Example:

@example
@group
x = 0:2;
y = x;
z = x' * y;
contourc (x, y, z, 2:3)
   @result{}   2.0000   2.0000   1.0000   3.0000   1.5000   2.0000
        2.0000   1.0000   2.0000   2.0000   2.0000   1.5000
@end group
@end example
@seealso{contour, contourf, contour3, clabel}
@end deftypefn
contourf
@c contourf scripts/plot/draw/contourf.m
-*- texinfo -*-
@deftypefn  {Function File} {} contourf (@var{z})
@deftypefnx {Function File} {} contourf (@var{z}, @var{vn})
@deftypefnx {Function File} {} contourf (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} contourf (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {Function File} {} contourf (@dots{}, @var{style})
@deftypefnx {Function File} {} contourf (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@dots{})
Create a 2-D contour plot with filled intervals.

Plot level curves (contour lines) of the matrix @var{z} and fill the region
between lines with colors from the current colormap.

The level curves are taken from the contour matrix @var{c} computed by
@code{contourc} for the same arguments; see the latter for their
interpretation.

The appearance of contour lines can be defined with a line style @var{style}
in the same manner as @code{plot}.  Only line style and color are used;
Any markers defined by @var{style} are ignored.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional output @var{c} contains the contour levels in @code{contourc}
format.

The optional return value @var{h} is a graphics handle to the hggroup
comprising the contour lines.

The following example plots filled contours of the @code{peaks} function.

@example
@group
[x, y, z] = peaks (50);
contourf (x, y, z, -7:9)
@end group
@end example
@seealso{ezcontourf, contour, contourc, contour3, clabel, meshc, surfc, caxis, colormap, plot}
@end deftypefn
contour
@c contour scripts/plot/draw/contour.m
-*- texinfo -*-
@deftypefn  {Function File} {} contour (@var{z})
@deftypefnx {Function File} {} contour (@var{z}, @var{vn})
@deftypefnx {Function File} {} contour (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} contour (@var{x}, @var{y}, @var{z}, @var{vn})
@deftypefnx {Function File} {} contour (@dots{}, @var{style})
@deftypefnx {Function File} {} contour (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contour (@dots{})
Create a 2-D contour plot.

Plot level curves (contour lines) of the matrix @var{z}, using the
contour matrix @var{c} computed by @code{contourc} from the same
arguments; see the latter for their interpretation.

The appearance of contour lines can be defined with a line style @var{style}
in the same manner as @code{plot}.  Only line style and color are used;
Any markers defined by @var{style} are ignored.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional output @var{c} contains the contour levels in @code{contourc}
format.

The optional return value @var{h} is a graphics handle to the hggroup
comprising the contour lines.

Example:

@example
@group
x = 0:2;
y = x;
z = x' * y;
contour (x, y, z, 2:3)
@end group
@end example

@seealso{ezcontour, contourc, contourf, contour3, clabel, meshc, surfc, caxis, colormap, plot}

@end deftypefn
cylinder
@c cylinder scripts/plot/draw/cylinder.m
-*- texinfo -*-
@deftypefn  {Command} {} cylinder
@deftypefnx {Function File} {} cylinder (@var{r})
@deftypefnx {Function File} {} cylinder (@var{r}, @var{n})
@deftypefnx {Function File} {} cylinder (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} cylinder (@dots{})
Plot a 3-D unit cylinder.

The optional input @var{r} is a vector specifying the radius along the
unit z-axis.  The default is [1 1] indicating radius 1 at @code{Z == 0}
and at @code{Z == 1}.

The optional input @var{n} determines the number of faces around the
circumference of the cylinder.  The default value is 20.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

If outputs are requested @code{cylinder} returns three matrices in
@code{meshgrid} format, such that @code{surf (@var{x}, @var{y}, @var{z})}
generates a unit cylinder.

Example:

@example
@group
[x, y, z] = cylinder (10:-1:0, 50);
surf (x, y, z);
title ("a cone");
@end group
@end example
@seealso{ellipsoid, rectangle, sphere}
@end deftypefn
ellipsoid
@c ellipsoid scripts/plot/draw/ellipsoid.m
-*- texinfo -*-
@deftypefn  {Function File} {} ellipsoid (@var{xc}, @var{yc}, @var{zc}, @var{xr}, @var{yr}, @var{zr}, @var{n})
@deftypefnx {Function File} {} ellipsoid (@dots{}, @var{n})
@deftypefnx {Function File} {} ellipsoid (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} ellipsoid (@dots{})
Plot a 3-D ellipsoid.

The inputs @var{xc}, @var{yc}, @var{zc} specify the center of the ellipsoid.
The inputs @var{xr}, @var{yr}, @var{zr} specify the semi-major axis lengths.

The optional input @var{n} determines the number of faces around the
circumference of the cylinder.  The default value is 20.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

If outputs are requested @code{ellipsoid} returns three matrices in
@code{meshgrid} format, such that @code{surf (@var{x}, @var{y}, @var{z})}
generates the ellipsoid.
@seealso{cylinder, rectangle, sphere}
@end deftypefn
errorbar
@c errorbar scripts/plot/draw/errorbar.m
-*- texinfo -*-
@deftypefn  {Function File} {} errorbar (@var{y}, @var{ey})
@deftypefnx {Function File} {} errorbar (@var{y}, @dots{}, @var{fmt})
@deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{ey})
@deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {Function File} {} errorbar (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {Function File} {} errorbar (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {Function File} {} errorbar (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} errorbar (@dots{})
Create a 2-D plot with errorbars.

Many different combinations of arguments are possible.  The simplest form is

@example
errorbar (@var{y}, @var{ey})
@end example

@noindent
where the first argument is taken as the set of @var{y} coordinates, the
second argument @var{ey} are the errors around the @var{y} values, and the
@var{x} coordinates are taken to be the indices of the elements
(@code{1:numel (@var{y})}).

The general form of the function is

@example
errorbar (@var{x}, @var{y}, @var{err1}, @dots{}, @var{fmt}, @dots{})
@end example

@noindent
After the @var{x} and @var{y} arguments there can be 1, 2, or 4
parameters specifying the error values depending on the nature of the error
values and the plot format @var{fmt}.

@table @asis
@item @var{err} (scalar)
When the error is a scalar all points share the same error value.
The errorbars are symmetric and are drawn from @var{data}-@var{err} to
@var{data}+@var{err}.
The @var{fmt} argument determines whether @var{err} is in the x-direction,
y-direction (default), or both.

@item @var{err} (vector or matrix)
Each data point has a particular error value.
The errorbars are symmetric and are drawn from @var{data}(n)-@var{err}(n) to
@var{data}(n)+@var{err}(n).

@item @var{lerr}, @var{uerr} (scalar)
The errors have a single low-side value and a single upper-side value.
The errorbars are not symmetric and are drawn from @var{data}-@var{lerr} to
@var{data}+@var{uerr}.

@item @var{lerr}, @var{uerr} (vector or matrix)
Each data point has a low-side error and an upper-side error.
The errorbars are not symmetric and are drawn from
@var{data}(n)-@var{lerr}(n) to @var{data}(n)+@var{uerr}(n).
@end table

Any number of data sets (@var{x1},@var{y1}, @var{x2},@var{y2}, @dots{}) may
appear as long as they are separated by a format string @var{fmt}.

If @var{y} is a matrix, @var{x} and the error parameters must also be
matrices having the same dimensions.  The columns of @var{y} are plotted
versus the corresponding columns of @var{x} and errorbars are taken from
the corresponding columns of the error parameters.

If @var{fmt} is missing, the yerrorbars ("~") plot style is assumed.

If the @var{fmt} argument is supplied then it is interpreted, as in normal
plots, to specify the line style, marker, and color.  In addition,
@var{fmt} may include an errorbar style which @strong{must precede} the
ordinary format codes.  The following errorbar styles are supported:

@table @samp
@item ~
Set yerrorbars plot style (default).

@item >
Set xerrorbars plot style.

@item ~>
Set xyerrorbars plot style.

@item #~
Set yboxes plot style.

@item #
Set xboxes plot style.

@item #~>
Set xyboxes plot style.
@end table

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a handle to the hggroup object
representing the data plot and errorbars.

Note: For compatibility with @sc{matlab} a line is drawn through all data
points.  However, most scientific errorbar plots are a scatter plot of
points with errorbars.  To accomplish this, add a marker style to the
@var{fmt} argument such as @qcode{"."}.  Alternatively, remove the line
by modifying the returned graphic handle with
@code{set (h, "linestyle", "none")}.

Examples:

@example
errorbar (@var{x}, @var{y}, @var{ex}, ">.r")
@end example

@noindent
produces an xerrorbar plot of @var{y} versus @var{x} with @var{x}
errorbars drawn from @var{x}-@var{ex} to @var{x}+@var{ex}.  The marker
@qcode{"."} is used so no connecting line is drawn and the errorbars
appear in red.

@example
@group
errorbar (@var{x}, @var{y1}, @var{ey}, "~",
          @var{x}, @var{y2}, @var{ly}, @var{uy})
@end group
@end example

@noindent
produces yerrorbar plots with @var{y1} and @var{y2} versus @var{x}.
Errorbars for @var{y1} are drawn from @var{y1}-@var{ey} to
@var{y1}+@var{ey}, errorbars for @var{y2} from @var{y2}-@var{ly} to
@var{y2}+@var{uy}.

@example
@group
errorbar (@var{x}, @var{y}, @var{lx}, @var{ux},
          @var{ly}, @var{uy}, "~>")
@end group
@end example

@noindent
produces an xyerrorbar plot of @var{y} versus @var{x} in which
@var{x} errorbars are drawn from @var{x}-@var{lx} to @var{x}+@var{ux}
and @var{y} errorbars from @var{y}-@var{ly} to @var{y}+@var{uy}.
@seealso{semilogxerr, semilogyerr, loglogerr, plot}
@end deftypefn
ezcontourf
@c ezcontourf scripts/plot/draw/ezcontourf.m
-*- texinfo -*-
@deftypefn  {Function File} {} ezcontourf (@var{f})
@deftypefnx {Function File} {} ezcontourf (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezcontourf (@dots{}, @var{n})
@deftypefnx {Function File} {} ezcontourf (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezcontourf (@dots{})

Plot the filled contour lines of a function.

@var{f} is a string, inline function, or function handle with two arguments
defining the function.  By default the plot is over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in each dimension.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Example:

@example
@group
f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
ezcontourf (f, [-3, 3]);
@end group
@end example

@seealso{contourf, ezcontour, ezplot, ezmeshc, ezsurfc}
@end deftypefn
ezcontour
@c ezcontour scripts/plot/draw/ezcontour.m
-*- texinfo -*-
@deftypefn  {Function File} {} ezcontour (@var{f})
@deftypefnx {Function File} {} ezcontour (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezcontour (@dots{}, @var{n})
@deftypefnx {Function File} {} ezcontour (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezcontour (@dots{})

Plot the contour lines of a function.

@var{f} is a string, inline function, or function handle with two arguments
defining the function.  By default the plot is over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in each dimension.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Example:

@example
@group
f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
ezcontour (f, [-3, 3]);
@end group
@end example

@seealso{contour, ezcontourf, ezplot, ezmeshc, ezsurfc}
@end deftypefn
ezmeshc
@c ezmeshc scripts/plot/draw/ezmeshc.m
-*- texinfo -*-
@deftypefn  {Function File} {} ezmeshc (@var{f})
@deftypefnx {Function File} {} ezmeshc (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {} ezmeshc (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezmeshc (@dots{}, @var{n})
@deftypefnx {Function File} {} ezmeshc (@dots{}, "circ")
@deftypefnx {Function File} {} ezmeshc (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezmeshc (@dots{})

Plot the mesh and contour lines defined by a function.

@var{f} is a string, inline function, or function handle with two arguments
defining the function.  By default the plot is over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If three functions are passed, then plot the parametrically defined
function @code{[@var{fx} (@var{s}, @var{t}), @var{fy} (@var{s}, @var{t}),
@var{fz} (@var{s}, @var{t})]}.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in each dimension.

If the argument @qcode{"circ"} is given, then the function is plotted over
a disk centered on the middle of the domain @var{dom}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a 2-element vector with a graphics
handle for the created mesh plot and a second handle for the created contour
plot.

Example: 2-argument function

@example
@group
f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
ezmeshc (f, [-3, 3]);
@end group
@end example

@seealso{meshc, ezmesh, ezplot, ezsurf, ezsurfc, hidden}
@end deftypefn
ezmesh
@c ezmesh scripts/plot/draw/ezmesh.m
-*- texinfo -*-
@deftypefn  {Function File} {} ezmesh (@var{f})
@deftypefnx {Function File} {} ezmesh (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {} ezmesh (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezmesh (@dots{}, @var{n})
@deftypefnx {Function File} {} ezmesh (@dots{}, "circ")
@deftypefnx {Function File} {} ezmesh (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezmesh (@dots{})

Plot the mesh defined by a function.

@var{f} is a string, inline function, or function handle with two arguments
defining the function.  By default the plot is over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If three functions are passed, then plot the parametrically defined
function @code{[@var{fx} (@var{s}, @var{t}), @var{fy} (@var{s}, @var{t}),
@var{fz} (@var{s}, @var{t})]}.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in each dimension.

If the argument @qcode{"circ"} is given, then the function is plotted over
a disk centered on the middle of the domain @var{dom}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Example 1: 2-argument function

@example
@group
f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
ezmesh (f, [-3, 3]);
@end group
@end example

Example 2: parametrically defined function

@example
@group
fx = @@(s,t) cos (s) .* cos (t);
fy = @@(s,t) sin (s) .* cos (t);
fz = @@(s,t) sin (t);
ezmesh (fx, fy, fz, [-pi, pi, -pi/2, pi/2], 20);
@end group
@end example

@seealso{mesh, ezmeshc, ezplot, ezsurf, ezsurfc, hidden}
@end deftypefn
ezplot3
@c ezplot3 scripts/plot/draw/ezplot3.m
-*- texinfo -*-
@deftypefn  {Function File} {} ezplot3 (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {} ezplot3 (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezplot3 (@dots{}, @var{n})
@deftypefnx {Function File} {} ezplot3 (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezplot3 (@dots{})

Plot a parametrically defined curve in three dimensions.

@var{fx}, @var{fy}, and @var{fz} are strings, inline functions,
or function handles with one argument defining the function.  By
default the plot is over the domain @code{0 <= @var{t} <= 2*pi}
with 500 points.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of @var{t}.

@var{n} is a scalar defining the number of points to use in plotting the
function.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

@example
@group
fx = @@(t) cos (t);
fy = @@(t) sin (t);
fz = @@(t) t;
ezplot3 (fx, fy, fz, [0, 10*pi], 100);
@end group
@end example

@seealso{plot3, ezplot, ezmesh, ezsurf}
@end deftypefn
ezplot
@c ezplot scripts/plot/draw/ezplot.m
-*- texinfo -*-
@deftypefn  {Function File} {} ezplot (@var{f})
@deftypefnx {Function File} {} ezplot (@var{f2v})
@deftypefnx {Function File} {} ezplot (@var{fx}, @var{fy})
@deftypefnx {Function File} {} ezplot (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezplot (@dots{}, @var{n})
@deftypefnx {Function File} {} ezplot (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezplot (@dots{})

Plot the 2-D curve defined by the function @var{f}.

The function @var{f} may be a string, inline function, or function handle
and can have either one or two variables.  If @var{f} has one variable, then
the function is plotted over the domain @code{-2*pi < @var{x} < 2*pi}
with 500 points.

If @var{f2v} is a function of two variables then the implicit function
@code{@var{f}(@var{x},@var{y}) = 0} is calculated over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

For example:

@example
ezplot (@@(@var{x}, @var{y}) @var{x}.^2 - @var{y}.^2 - 1)
@end example

If two functions are passed as inputs then the parametric function

@example
@group
@var{x} = @var{fx} (@var{t})
@var{y} = @var{fy} (@var{t})
@end group
@end example

@noindent
is plotted over the domain @code{-2*pi <= @var{t} <= 2*pi} with 500 points.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}, or @var{t} for a parametric plot.  If
@var{dom} is a four element vector, then the minimum and maximum values are
@code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in plotting
the function.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to
the created line objects.

@seealso{plot, ezplot3, ezpolar, ezcontour, ezcontourf, ezmesh, ezmeshc, ezsurf, ezsurfc}
@end deftypefn
ezpolar
@c ezpolar scripts/plot/draw/ezpolar.m
-*- texinfo -*-
@deftypefn  {Function File} {} ezpolar (@var{f})
@deftypefnx {Function File} {} ezpolar (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezpolar (@dots{}, @var{n})
@deftypefnx {Function File} {} ezpolar (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezpolar (@dots{})

Plot a 2-D function in polar coordinates.

The function @var{f} is a string, inline function, or function handle with
a single argument.  The expected form of the function is
@code{@var{rho} = @var{f}(@var{theta})}.
By default the plot is over the domain @code{0 <= @var{theta} <= 2*pi}
with 500 points.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of @var{theta}.

@var{n} is a scalar defining the number of points to use in plotting
the function.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Example:

@example
ezpolar (@@(t) sin (5/4 * t), [0, 8*pi]);
@end example

@seealso{polar, ezplot}
@end deftypefn
ezsurfc
@c ezsurfc scripts/plot/draw/ezsurfc.m
-*- texinfo -*-
@deftypefn  {Function File} {} ezsurfc (@var{f})
@deftypefnx {Function File} {} ezsurfc (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {} ezsurfc (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezsurfc (@dots{}, @var{n})
@deftypefnx {Function File} {} ezsurfc (@dots{}, "circ")
@deftypefnx {Function File} {} ezsurfc (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezsurfc (@dots{})

Plot the surface and contour lines defined by a function.

@var{f} is a string, inline function, or function handle with two arguments
defining the function.  By default the plot is over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If three functions are passed, then plot the parametrically defined
function @code{[@var{fx} (@var{s}, @var{t}), @var{fy} (@var{s}, @var{t}),
@var{fz} (@var{s}, @var{t})]}.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in each dimension.

If the argument @qcode{"circ"} is given, then the function is plotted over
a disk centered on the middle of the domain @var{dom}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a 2-element vector with a graphics
handle for the created surface plot and a second handle for the created
contour plot.

Example:

@example
@group
f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
ezsurfc (f, [-3, 3]);
@end group
@end example

@seealso{surfc, ezsurf, ezplot, ezmesh, ezmeshc, shading}
@end deftypefn
ezsurf
@c ezsurf scripts/plot/draw/ezsurf.m
-*- texinfo -*-
@deftypefn  {Function File} {} ezsurf (@var{f})
@deftypefnx {Function File} {} ezsurf (@var{fx}, @var{fy}, @var{fz})
@deftypefnx {Function File} {} ezsurf (@dots{}, @var{dom})
@deftypefnx {Function File} {} ezsurf (@dots{}, @var{n})
@deftypefnx {Function File} {} ezsurf (@dots{}, "circ")
@deftypefnx {Function File} {} ezsurf (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezsurf (@dots{})

Plot the surface defined by a function.

@var{f} is a string, inline function, or function handle with two arguments
defining the function.  By default the plot is over the meshed domain
@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension.

If three functions are passed, then plot the parametrically defined
function @code{[@var{fx} (@var{s}, @var{t}), @var{fy} (@var{s}, @var{t}),
@var{fz} (@var{s}, @var{t})]}.

If @var{dom} is a two element vector, it represents the minimum and maximum
values of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum values are @code{[xmin xmax ymin ymax]}.

@var{n} is a scalar defining the number of points to use in each dimension.

If the argument @qcode{"circ"} is given, then the function is plotted over
a disk centered on the middle of the domain @var{dom}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Example 1: 2-argument function

@example
@group
f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
ezsurf (f, [-3, 3]);
@end group
@end example

Example 2: parametrically defined function

@example
@group
fx = @@(s,t) cos (s) .* cos (t);
fy = @@(s,t) sin (s) .* cos (t);
fz = @@(s,t) sin (t);
ezsurf (fx, fy, fz, [-pi, pi, -pi/2, pi/2], 20);
@end group
@end example

@seealso{surf, ezsurfc, ezplot, ezmesh, ezmeshc, shading}
@end deftypefn
feather
@c feather scripts/plot/draw/feather.m
-*- texinfo -*-
@deftypefn  {Function File} {} feather (@var{u}, @var{v})
@deftypefnx {Function File} {} feather (@var{z})
@deftypefnx {Function File} {} feather (@dots{}, @var{style})
@deftypefnx {Function File} {} feather (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} feather (@dots{})

Plot the @code{(@var{u}, @var{v})} components of a vector field emanating
from equidistant points on the x-axis.

If a single complex argument @var{z} is given, then
@code{@var{u} = real (@var{z})} and @code{@var{v} = imag (@var{z})}.

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to the
line objects representing the drawn vectors.

@example
@group
phi = [0 : 15 : 360] * pi/180;
feather (sin (phi), cos (phi));
@end group
@end example

@seealso{plot, quiver, compass}
@end deftypefn
fill
@c fill scripts/plot/draw/fill.m
-*- texinfo -*-
@deftypefn  {Function File} {} fill (@var{x}, @var{y}, @var{c})
@deftypefnx {Function File} {} fill (@var{x1}, @var{y1}, @var{c1}, @var{x2}, @var{y2}, @var{c2})
@deftypefnx {Function File} {} fill (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} fill (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} fill (@dots{})
Create one or more filled 2-D polygons.

The inputs @var{x} and @var{y} are the coordinates of the polygon vertices.
If the inputs are matrices then the rows represent different vertices and
each column produces a different polygon.  @code{fill} will close any open
polygons before plotting.

The input @var{c} determines the color of the polygon.  The simplest form
is a single color specification such as a @code{plot} format or an
RGB-triple.  In this case the polygon(s) will have one unique color.  If
@var{c} is a vector or matrix then the color data is first scaled using
@code{caxis} and then indexed into the current colormap.  A row vector will
color each polygon (a column from matrices @var{x} and @var{y}) with a
single computed color.  A matrix @var{c} of the same size as @var{x} and
@var{y} will compute the color of each vertex and then interpolate the face
color between the vertices.

Multiple property/value pairs for the underlying patch object may be
specified, but they must appear in pairs.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to
the created patch objects.

Example: red square

@example
@group
vertices = [0 0
            1 0
            1 1
            0 1];
fill (vertices(:,1), vertices(:,2), "r");
axis ([-0.5 1.5, -0.5 1.5])
axis equal
@end group
@end example

@seealso{patch, caxis, colormap}
@end deftypefn
fplot
@c fplot scripts/plot/draw/fplot.m
-*- texinfo -*-
@deftypefn  {Function File} {} fplot (@var{fn}, @var{limits})
@deftypefnx {Function File} {} fplot (@dots{}, @var{tol})
@deftypefnx {Function File} {} fplot (@dots{}, @var{n})
@deftypefnx {Function File} {} fplot (@dots{}, @var{fmt})
@deftypefnx {Function File} {[@var{x}, @var{y}] =} fplot (@dots{})
Plot a function @var{fn} within the range defined by @var{limits}.

@var{fn} is a function handle, inline function, or string containing the
name of the function to evaluate.

The limits of the plot are of the form @w{@code{[@var{xlo}, @var{xhi}]}} or
@w{@code{[@var{xlo}, @var{xhi}, @var{ylo}, @var{yhi}]}}.

The next three arguments are all optional and any number of them may be
given in any order.

@var{tol} is the relative tolerance to use for the plot and defaults
to 2e-3 (.2%).

@var{n} is the minimum number of points to use.  When @var{n} is specified,
the maximum stepsize will be @code{@var{xhi} - @var{xlo} / @var{n}}.  More
than @var{n} points may still be used in order to meet the relative
tolerance requirement.

The @var{fmt} argument specifies the linestyle to be used by the plot
command.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

With no output arguments the results are immediately plotted.  With two
output arguments the 2-D plot data is returned.  The data can subsequently
be plotted manually with @code{plot (@var{x}, @var{y})}.

Example:

@example
@group
fplot (@@cos, [0, 2*pi])
fplot ("[cos(x), sin(x)]", [0, 2*pi])
@end group
@end example

Programming Notes:

@code{fplot} works best with continuous functions.  Functions with
discontinuities are unlikely to plot well.  This restriction may be removed
in the future.

@code{fplot} requires that the function accept and return a vector argument.
Consider this when writing user-defined functions and use @code{.*},
@code{./}, etc.  See the function @code{vectorize} for potentially
converting inline or anonymous functions to vectorized versions.
 
@seealso{ezplot, plot, vectorize}
@end deftypefn
hist
@c hist scripts/plot/draw/hist.m
-*- texinfo -*-
@deftypefn  {Function File} {} hist (@var{y})
@deftypefnx {Function File} {} hist (@var{y}, @var{x})
@deftypefnx {Function File} {} hist (@var{y}, @var{nbins})
@deftypefnx {Function File} {} hist (@var{y}, @var{x}, @var{norm})
@deftypefnx {Function File} {} hist (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} hist (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{nn}, @var{xx}] =} hist (@dots{})
Produce histogram counts or plots.

With one vector input argument, @var{y}, plot a histogram of the values
with 10 bins.  The range of the histogram bins is determined by the
range of the data.  With one matrix input argument, @var{y}, plot a
histogram where each bin contains a bar per input column.

Given a second vector argument, @var{x}, use that as the centers of
the bins, with the width of the bins determined from the adjacent
values in the vector.

If scalar, the second argument, @var{nbins}, defines the number of bins.

If a third argument is provided, the histogram is normalized such that
the sum of the bars is equal to @var{norm}.

Extreme values are lumped into the first and last bins.

The histogram's appearance may be modified by specifying property/value
pairs.  For example the face and edge color may be modified.

@example
@group
hist (randn (1, 100), 25, "facecolor", "r", "edgecolor", "b");
@end group
@end example

@noindent
The histogram's colors also depend upon the current colormap.

@example
@group
hist (rand (10, 3));
colormap (summer ());
@end group
@end example

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

With two output arguments, produce the values @var{nn} (numbers of elements)
and @var{xx} (bin centers) such that @code{bar (@var{xx}, @var{nn})} will
plot the histogram.

@seealso{histc, bar, pie, rose}
@end deftypefn
isocolors
@c isocolors scripts/plot/draw/isocolors.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{cd}] =} isocolors (@var{c}, @var{v})
@deftypefnx {Function File} {[@var{cd}] =} isocolors (@var{x}, @var{y}, @var{z}, @var{c}, @var{v})
@deftypefnx {Function File} {[@var{cd}] =} isocolors (@var{x}, @var{y}, @var{z}, @var{r}, @var{g}, @var{b}, @var{v})
@deftypefnx {Function File} {[@var{cd}] =} isocolors (@var{r}, @var{g}, @var{b}, @var{v})
@deftypefnx {Function File} {[@var{cd}] =} isocolors (@dots{}, @var{p})
@deftypefnx {Function File} {} isocolors (@dots{})

Compute isosurface colors.

If called with one output argument and the first input argument
@var{c} is a three-dimensional array that contains color values and
the second input argument @var{v} keeps the vertices of a geometry
then return a matrix @var{cd} with color data information for the
geometry at computed points
@command{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}.  The output argument
@var{cd} can be taken to manually set FaceVertexCData of a patch.

If called with further input arguments @var{x}, @var{y} and @var{z}
which are three--dimensional arrays of the same size than @var{c}
then the color data is taken at those given points.  Instead of the
color data @var{c} this function can also be called with RGB values
@var{r}, @var{g}, @var{b}.  If input argumnets @var{x}, @var{y},
@var{z} are not given then again @command{meshgrid} computed values
are taken.

Optionally, the patch handle @var{p} can be given as the last input
argument to all variations of function calls instead of the vertices
data @var{v}.  Finally, if no output argument is given then directly
change the colors of a patch that is given by the patch handle
@var{p}.

For example:

@example
function [] = isofinish (p)
  set (gca, "PlotBoxAspectRatioMode", "manual", ...
            "PlotBoxAspectRatio", [1 1 1]);
  set (p, "FaceColor", "interp");
  ## set (p, "FaceLighting", "flat");
  ## light ("Position", [1 1 5]);  # Available with JHandles
endfunction

N = 15;    # Increase number of vertices in each direction
iso = .4;  # Change isovalue to .1 to display a sphere
lin = linspace (0, 2, N);
[x, y, z] = meshgrid (lin, lin, lin);
c = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2);
figure (); # Open another figure window

subplot (2,2,1); view (-38, 20);
[f, v] = isosurface (x, y, z, c, iso);
p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none");
cdat = rand (size (c));       # Compute random patch color data
isocolors (x, y, z, cdat, p); # Directly set colors of patch
isofinish (p);                # Call user function isofinish

subplot (2,2,2); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none");
[r, g, b] = meshgrid (lin, 2-lin, 2-lin);
cdat = isocolors (x, y, z, c, v); # Compute color data vertices
set (p, "FaceVertexCData", cdat); # Set color data manually
isofinish (p);

subplot (2,2,3); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none");
cdat = isocolors (r, g, b, c, p); # Compute color data patch
set (p, "FaceVertexCData", cdat); # Set color data manually
isofinish (p);

subplot (2,2,4); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none");
r = g = b = repmat ([1:N] / N, [N, 1, N]); # Black to white
cdat = isocolors (x, y, z, r, g, b, v);
set (p, "FaceVertexCData", cdat);
isofinish (p);
@end example

@seealso{isosurface, isonormals}
@end deftypefn
isonormals
@c isonormals scripts/plot/draw/isonormals.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{n}] =} isonormals (@var{val}, @var{v})
@deftypefnx {Function File} {[@var{n}] =} isonormals (@var{val}, @var{p})
@deftypefnx {Function File} {[@var{n}] =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{v})
@deftypefnx {Function File} {[@var{n}] =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{p})
@deftypefnx {Function File} {[@var{n}] =} isonormals (@dots{}, "negate")
@deftypefnx {Function File} {} isonormals (@dots{}, @var{p})

Calculate normals to an isosurface.

If called with one output argument and the first input argument
@var{val} is a three-dimensional array that contains the data for an
isosurface geometry and the second input argument @var{v} keeps the
vertices of an isosurface then return the normals @var{n} in form of
a matrix with the same size than @var{v} at computed points
@command{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}.  The output argument
@var{n} can be taken to manually set @var{VertexNormals} of a patch.

If called with further input arguments @var{x}, @var{y} and @var{z}
which are three--dimensional arrays with the same size than @var{val}
then the volume data is taken at those given points.  Instead of the
vertices data @var{v} a patch handle @var{p} can be passed to this
function.

If given the string input argument @qcode{"negate"} as last input argument
then compute the reverse vector normals of an isosurface geometry.

If no output argument is given then directly redraw the patch that is
given by the patch handle @var{p}.

For example:
@c Set example in small font to prevent overfull line

@smallexample
function [] = isofinish (p)
  set (gca, "PlotBoxAspectRatioMode", "manual", ...
            "PlotBoxAspectRatio", [1 1 1]);
  set (p, "VertexNormals", -get (p,"VertexNormals")); # Revert normals
  set (p, "FaceColor", "interp");
  ## set (p, "FaceLighting", "phong");
  ## light ("Position", [1 1 5]); # Available with JHandles
endfunction

N = 15;    # Increase number of vertices in each direction
iso = .4;  # Change isovalue to .1 to display a sphere
lin = linspace (0, 2, N);
[x, y, z] = meshgrid (lin, lin, lin);
c = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2);
figure (); # Open another figure window

subplot (2,2,1); view (-38, 20);
[f, v, cdat] = isosurface (x, y, z, c, iso, y);
p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, ...
           "FaceColor", "interp", "EdgeColor", "none");
isofinish (p);  # Call user function isofinish

subplot (2,2,2); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, ...
           "FaceColor", "interp", "EdgeColor", "none");
isonormals (x, y, z, c, p); # Directly modify patch
isofinish (p);

subplot (2,2,3); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, ...
           "FaceColor", "interp", "EdgeColor", "none");
n = isonormals (x, y, z, c, v); # Compute normals of isosurface
set (p, "VertexNormals", n);    # Manually set vertex normals
isofinish (p);

subplot (2,2,4); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, ...
           "FaceColor", "interp", "EdgeColor", "none");
isonormals (x, y, z, c, v, "negate"); # Use reverse directly
isofinish (p);
@end smallexample

@seealso{isosurface, isocolors}
@end deftypefn
isosurface
@c isosurface scripts/plot/draw/isosurface.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{fv}] =} isosurface (@var{val}, @var{iso})
@deftypefnx {Function File} {[@var{fv}] =} isosurface (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso})
@deftypefnx {Function File} {[@var{fv}] =} isosurface (@dots{}, "noshare", "verbose")
@deftypefnx {Function File} {[@var{fvc}] =} isosurface (@dots{}, @var{col})
@deftypefnx {Function File} {[@var{f}, @var{v}] =} isosurface (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso})
@deftypefnx {Function File} {[@var{f}, @var{v}, @var{c}] =} isosurface (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso}, @var{col})
@deftypefnx {Function File} {} isosurface (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso}, @var{col}, @var{opt})

Calculate isosurface of 3-D data.

If called with one output argument and the first input argument
@var{val} is a three-dimensional array that contains the data of an
isosurface geometry and the second input argument @var{iso} keeps the
isovalue as a scalar value then return a structure array @var{fv}
that contains the fields @var{Faces} and @var{Vertices} at computed
points @command{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}.  The output
argument @var{fv} can directly be taken as an input argument for the
@command{patch} function.

If called with further input arguments @var{x}, @var{y} and @var{z}
which are three--dimensional arrays with the same size than @var{val}
then the volume data is taken at those given points.

The string input argument @qcode{"noshare"} is only for compatibility and
has no effect.  If given the string input argument
@qcode{"verbose"} then print messages to the command line interface about the
current progress.

If called with the input argument @var{col} which is a
three-dimensional array of the same size than @var{val} then take
those values for the interpolation of coloring the isosurface
geometry.  Add the field @var{FaceVertexCData} to the structure
array @var{fv}.

If called with two or three output arguments then return the
information about the faces @var{f}, vertices @var{v} and color data
@var{c} as separate arrays instead of a single structure array.

If called with no output argument then directly process the
isosurface geometry with the @command{patch} command.

For example,

@example
@group
[x, y, z] = meshgrid (1:5, 1:5, 1:5);
val = rand (5, 5, 5);
isosurface (x, y, z, val, .5);
@end group
@end example

@noindent
will directly draw a random isosurface geometry in a graphics window.
Another example for an isosurface geometry with different additional
coloring
@c Set example in small font to prevent overfull line

@smallexample
N = 15;    # Increase number of vertices in each direction
iso = .4;  # Change isovalue to .1 to display a sphere
lin = linspace (0, 2, N);
[x, y, z] = meshgrid (lin, lin, lin);
c = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2);
figure (); # Open another figure window

subplot (2,2,1); view (-38, 20);
[f, v] = isosurface (x, y, z, c, iso);
p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none");
set (gca, "PlotBoxAspectRatioMode", "manual", ...
          "PlotBoxAspectRatio", [1 1 1]);
# set (p, "FaceColor", "green", "FaceLighting", "phong");
# light ("Position", [1 1 5]); # Available with the JHandles package

subplot (2,2,2); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "EdgeColor", "blue");
set (gca, "PlotBoxAspectRatioMode", "manual", ...
          "PlotBoxAspectRatio", [1 1 1]);
# set (p, "FaceColor", "none", "FaceLighting", "phong");
# light ("Position", [1 1 5]);

subplot (2,2,3); view (-38, 20);
[f, v, c] = isosurface (x, y, z, c, iso, y);
p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", c, ...
           "FaceColor", "interp", "EdgeColor", "none");
set (gca, "PlotBoxAspectRatioMode", "manual", ...
          "PlotBoxAspectRatio", [1 1 1]);
# set (p, "FaceLighting", "phong");
# light ("Position", [1 1 5]);

subplot (2,2,4); view (-38, 20);
p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", c, ...
           "FaceColor", "interp", "EdgeColor", "blue");
set (gca, "PlotBoxAspectRatioMode", "manual", ...
          "PlotBoxAspectRatio", [1 1 1]);
# set (p, "FaceLighting", "phong");
# light ("Position", [1 1 5]);
@end smallexample

@seealso{isonormals, isocolors}
@end deftypefn
line
@c line scripts/plot/draw/line.m
-*- texinfo -*-
@deftypefn  {Function File} {} line ()
@deftypefnx {Function File} {} line (@var{x}, @var{y})
@deftypefnx {Function File} {} line (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} line (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} line (@var{x}, @var{y}, @var{z}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} line (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} line (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} line (@dots{})
Create line object from @var{x} and @var{y} (and possibly @var{z}) and
insert in the current axes.

Multiple property-value pairs may be specified for the line object, but they
must appear in pairs.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle (or vector of handles)
to the line objects created.

@seealso{image, patch, rectangle, surface, text}
@end deftypefn
loglogerr
@c loglogerr scripts/plot/draw/loglogerr.m
-*- texinfo -*-
@deftypefn  {Function File} {} loglogerr (@var{y}, @var{ey})
@deftypefnx {Function File} {} loglogerr (@var{y}, @dots{}, @var{fmt})
@deftypefnx {Function File} {} loglogerr (@var{x}, @var{y}, @var{ey})
@deftypefnx {Function File} {} loglogerr (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {Function File} {} loglogerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {Function File} {} loglogerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {Function File} {} loglogerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {Function File} {} loglogerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {Function File} {} loglogerr (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} loglogerr (@dots{})
Produce 2-D plots on a double logarithm axis with errorbars.

Many different combinations of arguments are possible.  The most common
form is

@example
loglogerr (@var{x}, @var{y}, @var{ey}, @var{fmt})
@end example

@noindent
which produces a double logarithm plot of @var{y} versus @var{x}
with errors in the @var{y}-scale defined by @var{ey} and the plot
format defined by @var{fmt}.  @xref{XREFerrorbar,,errorbar}, for available
formats and additional information.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.
@seealso{errorbar, semilogxerr, semilogyerr}
@end deftypefn
loglog
@c loglog scripts/plot/draw/loglog.m
-*- texinfo -*-
@deftypefn  {Function File} {} loglog (@var{y})
@deftypefnx {Function File} {} loglog (@var{x}, @var{y})
@deftypefnx {Function File} {} loglog (@var{x}, @var{y}, @var{prop}, @var{value}, @dots{})
@deftypefnx {Function File} {} loglog (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} loglog (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} loglog (@dots{})
Produce a 2-D plot using logarithmic scales for both axes.

See the documentation of @code{plot} for a description of the arguments
that @code{loglog} will accept.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.
@seealso{plot, semilogx, semilogy}
@end deftypefn
meshc
@c meshc scripts/plot/draw/meshc.m
-*- texinfo -*-
@deftypefn  {Function File} {} meshc (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} meshc (@var{z})
@deftypefnx {Function File} {} meshc (@dots{}, @var{c})
@deftypefnx {Function File} {} meshc (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} meshc (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} meshc (@dots{})
Plot a 3-D wireframe mesh with underlying contour lines.

The wireframe mesh is plotted using rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The color of the mesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a 2-element vector with a graphics
handle to the created surface object and to the created contour plot.

@seealso{ezmeshc, mesh, meshz, contour, surfc, surface, meshgrid, hidden, shading, colormap, caxis}
@end deftypefn
mesh
@c mesh scripts/plot/draw/mesh.m
-*- texinfo -*-
@deftypefn  {Function File} {} mesh (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} mesh (@var{z})
@deftypefnx {Function File} {} mesh (@dots{}, @var{c})
@deftypefnx {Function File} {} mesh (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} mesh (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} mesh (@dots{})
Plot a 3-D wireframe mesh.

The wireframe mesh is plotted using rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The color of the mesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally, the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

@seealso{ezmesh, meshc, meshz, trimesh, contour, surf, surface, meshgrid, hidden, shading, colormap, caxis}
@end deftypefn
meshz
@c meshz scripts/plot/draw/meshz.m
-*- texinfo -*-
@deftypefn  {Function File} {} meshz (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} meshz (@var{z})
@deftypefnx {Function File} {} meshz (@dots{}, @var{c})
@deftypefnx {Function File} {} meshz (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} meshz (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} meshz (@dots{})
Plot a 3-D wireframe mesh with a surrounding curtain.

The wireframe mesh is plotted using rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 0:columns (@var{z}) - 1, @var{y} = 0:rows (@var{z}) - 1}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The color of the mesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

@seealso{mesh, meshc, contour, surf, surface, waterfall, meshgrid, hidden, shading, colormap, caxis}
@end deftypefn
pareto
@c pareto scripts/plot/draw/pareto.m
-*- texinfo -*-
@deftypefn  {Function File} {} pareto (@var{y})
@deftypefnx {Function File} {} pareto (@var{y}, @var{x})
@deftypefnx {Function File} {} pareto (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} pareto (@dots{})
Draw a Pareto chart.

A Pareto chart is a bar graph that arranges information in such a way
that priorities for process improvement can be established; It organizes
and displays information to show the relative importance of data.  The chart
is similar to the histogram or bar chart, except that the bars are arranged
in decreasing magnitude from left to right along the x-axis.

The fundamental idea (Pareto principle) behind the use of Pareto
diagrams is that the majority of an effect is due to a small subset of the
causes.  For quality improvement, the first few contributing causes
(leftmost bars as presented on the diagram) to a problem usually account for
the majority of the result.  Thus, targeting these "major causes" for
elimination results in the most cost-effective improvement scheme.

Typically only the magnitude data @var{y} is present in which case
@var{x} is taken to be the range @code{1 : length (@var{y})}.  If @var{x}
is given it may be a string array, a cell array of strings, or a numerical
vector.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a 2-element vector with a graphics
handle for the created bar plot and a second handle for the created line
plot.

An example of the use of @code{pareto} is

@example
@group
Cheese = @{"Cheddar", "Swiss", "Camembert", ...
          "Munster", "Stilton", "Blue"@};
Sold = [105, 30, 70, 10, 15, 20];
pareto (Sold, Cheese);
@end group
@end example
@seealso{bar, barh, hist, pie, plot}
@end deftypefn
patch
@c patch scripts/plot/draw/patch.m
-*- texinfo -*-
@deftypefn  {Function File} {} patch ()
@deftypefnx {Function File} {} patch (@var{x}, @var{y}, @var{c})
@deftypefnx {Function File} {} patch (@var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {Function File} {} patch (@var{fv})
@deftypefnx {Function File} {} patch ("Faces", @var{faces}, "Vertices", @var{verts}, @dots{})
@deftypefnx {Function File} {} patch (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} patch (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} patch (@dots{})
Create patch object in the current axes with vertices at locations
(@var{x}, @var{y}) and of color @var{c}.

If the vertices are matrices of size @nospell{MxN} then each polygon patch
has M vertices and a total of N polygons will be created.  If some polygons
do not have M vertices use NaN to represent "no vertex".  If the @var{z}
input is present then 3-D patches will be created.

The color argument @var{c} can take many forms.  To create polygons
which all share a single color use a string value (e.g., @qcode{"r"} for
red), a scalar value which is scaled by @code{caxis} and indexed into the
current colormap, or a 3-element RGB vector with the precise TrueColor.

If @var{c} is a vector of length N then the ith polygon will have a color
determined by scaling entry @var{c}(i) according to @code{caxis} and then
indexing into the current colormap.  More complicated coloring situations
require directly manipulating patch property/value pairs.

Instead of specifying polygons by matrices @var{x} and @var{y}, it is
possible to present a unique list of vertices and then a list of polygon
faces created from those vertices.  In this case the
@qcode{"Vertices"} matrix will be an @nospell{Nx2} (2-D patch) or
@nospell{Nx3} (3-D path).  The @nospell{MxN} @qcode{"Faces"} matrix
describes M polygons having N vertices---each row describes a
single polygon and each column entry is an index into the
@qcode{"Vertices"} matrix to identify a vertex.  The patch object
can be created by directly passing the property/value pairs
@qcode{"Vertices"}/@var{verts}, @qcode{"Faces"}/@var{faces} as
inputs.

A third input form is to create a structure @var{fv} with the fields
@qcode{"vertices"}, @qcode{"faces"}, and optionally
@qcode{"facevertexcdata"}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created patch
object.

Implementation Note: Patches are highly configurable objects.  To truly
customize them requires setting patch properties directly.  Useful patch
properties are: @qcode{"cdata"}, @qcode{"edgecolor"},
@qcode{"facecolor"}, @qcode{"faces"}, @qcode{"facevertexcdata"}.
@seealso{fill, get, set}
@end deftypefn
pcolor
@c pcolor scripts/plot/draw/pcolor.m
-*- texinfo -*-
@deftypefn  {Function File} {} pcolor (@var{x}, @var{y}, @var{c})
@deftypefnx {Function File} {} pcolor (@var{c})
@deftypefnx {Function File} {} pcolor (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} pcolor (@dots{})
Produce a 2-D density plot.

A @code{pcolor} plot draws rectangles with colors from the matrix @var{c}
over the two-dimensional region represented by the matrices @var{x} and
@var{y}.  @var{x} and @var{y} are the coordinates of the mesh's vertices
and are typically the output of @code{meshgrid}.  If @var{x} and @var{y} are
vectors, then a typical vertex is (@var{x}(j), @var{y}(i), @var{c}(i,j)).
Thus, columns of @var{c} correspond to different @var{x} values and rows
of @var{c} correspond to different @var{y} values.

The values in @var{c} are scaled to span the range of the current
colormap.  Limits may be placed on the color axis by the command
@code{caxis}, or by setting the @code{clim} property of the parent axis.

The face color of each cell of the mesh is determined by interpolating
the values of @var{c} for each of the cell's vertices; Contrast this with
@code{imagesc} which renders one cell for each element of @var{c}.

@code{shading} modifies an attribute determining the manner by which the
face color of each cell is interpolated from the values of @var{c},
and the visibility of the cells' edges.  By default the attribute is
@qcode{"faceted"}, which renders a single color for each cell's face with
the edge visible.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

@seealso{caxis, shading, meshgrid, contour, imagesc}
@end deftypefn
peaks
@c peaks scripts/plot/draw/peaks.m
-*- texinfo -*-
@deftypefn  {Function File} {} peaks ()
@deftypefnx {Function File} {} peaks (@var{n})
@deftypefnx {Function File} {} peaks (@var{x}, @var{y})
@deftypefnx {Function File} {@var{z} =} peaks (@dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} peaks (@dots{})
Plot a function with lots of local maxima and minima.

The function has the form

@tex
$$f(x,y) = 3 (1 - x) ^ 2 e ^ {\left(-x^2 - (y+1)^2\right)} - 10 \left({x \over 5} - x^3 - y^5\right) - {1 \over 3} e^{\left(-(x+1)^2 - y^2\right)}$$
@end tex
@ifnottex
@verbatim
f(x,y) = 3*(1-x)^2*exp(-x^2 - (y+1)^2) ...
         - 10*(x/5 - x^3 - y^5)*exp(-x^2-y^2) ...
         - 1/3*exp(-(x+1)^2 - y^2)
@end verbatim
@end ifnottex

Called without a return argument, @code{peaks} plots the surface of the
above function using @code{surf}.

If @var{n} is a scalar, @code{peaks} plots the value of the above
function on an @var{n}-by-@var{n} mesh over the range [-3,3].  The
default value for @var{n} is 49.

If @var{n} is a vector, then it represents the grid values over which
to calculate the function.  If @var{x} and @var{y} are specified then
the function value is calculated over the specified grid of vertices.

When called with output arguments, return the data for the function
evaluated over the meshgrid.  This can subsequently be plotted with
@code{surf (@var{x}, @var{y}, @var{z})}.

@seealso{sombrero, meshgrid, mesh, surf}
@end deftypefn
pie3
@c pie3 scripts/plot/draw/pie3.m
-*- texinfo -*-
@deftypefn  {Function File} {} pie3 (@var{x})
@deftypefnx {Function File} {} pie3 (@dots{}, @var{explode})
@deftypefnx {Function File} {} pie3 (@dots{}, @var{labels})
@deftypefnx {Function File} {} pie3 (@var{hax}, @dots{});
@deftypefnx {Function File} {@var{h} =} pie3 (@dots{});
Plot a 3-D pie chart.

Called with a single vector argument, produces a 3-D pie chart of the
elements in @var{x}.  The size of the ith slice is the percentage that the
element @var{x}i represents of the total sum of @var{x}:
@code{pct = @var{x}(i) / sum (@var{x})}.

The optional input @var{explode} is a vector of the same length as @var{x}
that, if nonzero, "explodes" the slice from the pie chart.

The optional input @var{labels} is a cell array of strings of the same
length as @var{x} specifying the label for each slice.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a list of graphics handles to the
patch, surface, and text objects generating the plot.

Note: If @code{sum (@var{x}) @leq{} 1} then the elements of @var{x} are
interpreted as percentages directly and are not normalized by @code{sum (x)}.
Furthermore, if the sum is less than 1 then there will be a missing slice
in the pie plot to represent the missing, unspecified percentage.

@seealso{pie, bar, hist, rose}
@end deftypefn
pie
@c pie scripts/plot/draw/pie.m
-*- texinfo -*-
@deftypefn  {Function File} {} pie (@var{x})
@deftypefnx {Function File} {} pie (@dots{}, @var{explode})
@deftypefnx {Function File} {} pie (@dots{}, @var{labels})
@deftypefnx {Function File} {} pie (@var{hax}, @dots{});
@deftypefnx {Function File} {@var{h} =} pie (@dots{});
Plot a 2-D pie chart.

When called with a single vector argument, produce a pie chart of the
elements in @var{x}.  The size of the ith slice is the percentage that the
element @var{x}i represents of the total sum of @var{x}:
@code{pct = @var{x}(i) / sum (@var{x})}.

The optional input @var{explode} is a vector of the same length as @var{x}
that, if nonzero, "explodes" the slice from the pie chart.

The optional input @var{labels} is a cell array of strings of the same
length as @var{x} specifying the label for each slice.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a list of handles to the patch
and text objects generating the plot.

Note: If @code{sum (@var{x}) @leq{} 1} then the elements of @var{x} are
interpreted as percentages directly and are not normalized by @code{sum (x)}.
Furthermore, if the sum is less than 1 then there will be a missing slice
in the pie plot to represent the missing, unspecified percentage.

@seealso{pie3, bar, hist, rose}
@end deftypefn
plot3
@c plot3 scripts/plot/draw/plot3.m
-*- texinfo -*-
@deftypefn  {Function File} {} plot3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} plot3 (@var{x}, @var{y}, @var{z}, @var{prop}, @var{value}, @dots{})
@deftypefnx {Function File} {} plot3 (@var{x}, @var{y}, @var{z}, @var{fmt})
@deftypefnx {Function File} {} plot3 (@var{x}, @var{cplx})
@deftypefnx {Function File} {} plot3 (@var{cplx})
@deftypefnx {Function File} {} plot3 (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} plot3 (@dots{})
Produce 3-D plots.

Many different combinations of arguments are possible.  The simplest
form is

@example
plot3 (@var{x}, @var{y}, @var{z})
@end example

@noindent
in which the arguments are taken to be the vertices of the points to
be plotted in three dimensions.  If all arguments are vectors of the
same length, then a single continuous line is drawn.  If all arguments
are matrices, then each column of is treated as a separate line.  No attempt
is made to transpose the arguments to make the number of rows match.

If only two arguments are given, as

@example
plot3 (@var{x}, @var{cplx})
@end example

@noindent
the real and imaginary parts of the second argument are used
as the @var{y} and @var{z} coordinates, respectively.

If only one argument is given, as

@example
plot3 (@var{cplx})
@end example

@noindent
the real and imaginary parts of the argument are used as the @var{y}
and @var{z} values, and they are plotted versus their index.

Arguments may also be given in groups of three as

@example
plot3 (@var{x1}, @var{y1}, @var{z1}, @var{x2}, @var{y2}, @var{z2}, @dots{})
@end example

@noindent
in which each set of three arguments is treated as a separate line or
set of lines in three dimensions.

To plot multiple one- or two-argument groups, separate each group
with an empty format string, as

@example
plot3 (@var{x1}, @var{c1}, "", @var{c2}, "", @dots{})
@end example

Multiple property-value pairs may be specified which will affect the line
objects drawn by @code{plot3}.  If the @var{fmt} argument is supplied it
will format the line objects in the same manner as @code{plot}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Example:

@example
@group
z = [0:0.05:5];
plot3 (cos (2*pi*z), sin (2*pi*z), z, ";helix;");
plot3 (z, exp (2i*pi*z), ";complex sinusoid;");
@end group
@end example
@seealso{ezplot3, plot}
@end deftypefn
plot
@c plot scripts/plot/draw/plot.m
-*- texinfo -*-
@deftypefn  {Function File} {} plot (@var{y})
@deftypefnx {Function File} {} plot (@var{x}, @var{y})
@deftypefnx {Function File} {} plot (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} plot (@dots{}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} plot (@var{x1}, @var{y1}, @dots{}, @var{xn}, @var{yn})
@deftypefnx {Function File} {} plot (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} plot (@dots{})
Produce 2-D plots.

Many different combinations of arguments are possible.  The simplest
form is

@example
plot (@var{y})
@end example

@noindent
where the argument is taken as the set of @var{y} coordinates and the
@var{x} coordinates are taken to be the range @code{1:numel (@var{y})}.

If more than one argument is given, they are interpreted as

@example
plot (@var{y}, @var{property}, @var{value}, @dots{})
@end example

@noindent
or

@example
plot (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@end example

@noindent
or

@example
plot (@var{x}, @var{y}, @var{fmt}, @dots{})
@end example

@noindent
and so on.  Any number of argument sets may appear.  The @var{x} and
@var{y} values are interpreted as follows:

@itemize @bullet
@item
If a single data argument is supplied, it is taken as the set of @var{y}
coordinates and the @var{x} coordinates are taken to be the indices of
the elements, starting with 1.

@item
If @var{x} and @var{y} are scalars, a single point is plotted.

@item
@code{squeeze()} is applied to arguments with more than two dimensions,
but no more than two singleton dimensions.

@item
If both arguments are vectors, the elements of @var{y} are plotted versus
the elements of @var{x}.

@item
If @var{x} is a vector and @var{y} is a matrix, then
the columns (or rows) of @var{y} are plotted versus @var{x}.
(using whichever combination matches, with columns tried first.)

@item
If the @var{x} is a matrix and @var{y} is a vector,
@var{y} is plotted versus the columns (or rows) of @var{x}.
(using whichever combination matches, with columns tried first.)

@item
If both arguments are matrices, the columns of @var{y} are plotted
versus the columns of @var{x}.  In this case, both matrices must have
the same number of rows and columns and no attempt is made to transpose
the arguments to make the number of rows match.
@end itemize

Multiple property-value pairs may be specified, but they must appear
in pairs.  These arguments are applied to the line objects drawn by
@code{plot}.  Useful properties to modify are @qcode{"linestyle"},
@qcode{"linewidth"}, @qcode{"color"}, @qcode{"marker"},
@qcode{"markersize"}, @qcode{"markeredgecolor"}, @qcode{"markerfacecolor"}.  
@xref{Line Properties}.  

The @var{fmt} format argument can also be used to control the plot style.
It is a string composed of four optional parts:
"<linestyle><marker><color><;displayname;>".
When a marker is specified, but no linestyle, only the markers are
plotted.  Similarly, if a linestyle is specified, but no marker, then
only lines are drawn.  If both are specified then lines and markers will
be plotted.  If no @var{fmt} and no @var{property}/@var{value} pairs are
given, then the default plot style is solid lines with no markers and the
color determined by the @qcode{"colororder"} property of the current axes.

Format arguments:

@table @asis
@item linestyle

@multitable @columnfractions 0.06 0.94
@item @samp{-}  @tab Use solid lines (default).
@item @samp{--} @tab Use dashed lines.
@item @samp{:}  @tab Use dotted lines.
@item @samp{-.} @tab Use dash-dotted lines.
@end multitable

@item marker

@multitable @columnfractions 0.06 0.94
@item @samp{+} @tab crosshair
@item @samp{o} @tab circle
@item @samp{*} @tab star
@item @samp{.} @tab point
@item @samp{x} @tab cross
@item @samp{s} @tab square
@item @samp{d} @tab diamond
@item @samp{^} @tab upward-facing triangle
@item @samp{v} @tab downward-facing triangle
@item @samp{>} @tab right-facing triangle
@item @samp{<} @tab left-facing triangle
@item @samp{p} @tab pentagram
@item @samp{h} @tab hexagram
@end multitable

@item color

@multitable @columnfractions 0.06 0.94
@item @samp{k} @tab blacK
@item @samp{r} @tab Red
@item @samp{g} @tab Green
@item @samp{b} @tab Blue
@item @samp{m} @tab Magenta
@item @samp{c} @tab Cyan
@item @samp{w} @tab White
@end multitable

@item @qcode{";displayname;"}
Here @qcode{"displayname"} is the label to use for the plot legend.
@end table

The @var{fmt} argument may also be used to assign legend labels.
To do so, include the desired label between semicolons after the
formatting sequence described above, e.g., @qcode{"+b;Key Title;"}.
Note that the last semicolon is required and Octave will generate
an error if it is left out.

Here are some plot examples:

@example
plot (x, y, "or", x, y2, x, y3, "m", x, y4, "+")
@end example

This command will plot @code{y} with red circles, @code{y2} with solid
lines, @code{y3} with solid magenta lines, and @code{y4} with points
displayed as @samp{+}.

@example
plot (b, "*", "markersize", 10)
@end example

This command will plot the data in the variable @code{b},
with points displayed as @samp{*} and a marker size of 10.

@example
@group
t = 0:0.1:6.3;
plot (t, cos(t), "-;cos(t);", t, sin(t), "-b;sin(t);");
@end group
@end example

This will plot the cosine and sine functions and label them accordingly
in the legend.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to
the created line objects.

To save a plot, in one of several image formats such as PostScript
or PNG, use the @code{print} command.

@seealso{axis, box, grid, hold, legend, title, xlabel, ylabel, xlim, ylim, ezplot, errorbar, fplot, line, plot3, polar, loglog, semilogx, semilogy, subplot}
@end deftypefn
plotmatrix
@c plotmatrix scripts/plot/draw/plotmatrix.m
-*- texinfo -*-
@deftypefn  {Function File} {} plotmatrix (@var{x}, @var{y})
@deftypefnx {Function File} {} plotmatrix (@var{x})
@deftypefnx {Function File} {} plotmatrix (@dots{}, @var{style})
@deftypefnx {Function File} {} plotmatrix (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{h}, @var{ax}, @var{bigax}, @var{p}, @var{pax}] =} plotmatrix (@dots{})
Scatter plot of the columns of one matrix against another.

Given the arguments @var{x} and @var{y} that have a matching number of
rows, @code{plotmatrix} plots a set of axes corresponding to

@example
plot (@var{x}(:, i), @var{y}(:, j))
@end example

When called with a single argument @var{x} this is equivalent to

@example
plotmatrix (@var{x}, @var{x})
@end example

@noindent
except that the diagonal of the set of axes will be replaced with the
histogram @code{hist (@var{x}(:, i))}.

The marker to use can be changed with the @var{style} argument, that is a
string defining a marker in the same manner as the @code{plot} command.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} provides handles to the individual
graphics objects in the scatter plots, whereas @var{ax} returns the
handles to the scatter plot axis objects.

@var{bigax} is a hidden axis object that surrounds the other axes, such
that the commands @code{xlabel}, @code{title}, etc., will be associated
with this hidden axis.

Finally, @var{p} returns the graphics objects associated with the histogram
and @var{pax} the corresponding axes objects.

Example:

@example
plotmatrix (randn (100, 3), "g+")
@end example

@seealso{scatter, plot}
@end deftypefn
plotyy
@c plotyy scripts/plot/draw/plotyy.m
-*- texinfo -*-
@deftypefn  {Function File} {} plotyy (@var{x1}, @var{y1}, @var{x2}, @var{y2})
@deftypefnx {Function File} {} plotyy (@dots{}, @var{fun})
@deftypefnx {Function File} {} plotyy (@dots{}, @var{fun1}, @var{fun2})
@deftypefnx {Function File} {} plotyy (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{ax}, @var{h1}, @var{h2}] =} plotyy (@dots{})
Plot two sets of data with independent y-axes and a common x-axis.

The arguments @var{x1} and @var{y1} define the arguments for the first plot
and @var{x1} and @var{y2} for the second.

By default the arguments are evaluated with
@code{feval (@@plot, @var{x}, @var{y})}.  However the type of plot can be
modified with the @var{fun} argument, in which case the plots are
generated by @code{feval (@var{fun}, @var{x}, @var{y})}.  @var{fun} can be
a function handle, an inline function, or a string of a function name.

The function to use for each of the plots can be independently defined
with @var{fun1} and @var{fun2}.

If the first argument @var{hax} is an axes handle, then it defines
the principal axis in which to plot the @var{x1} and @var{y1} data.

The return value @var{ax} is a vector with the axis handles of the two
y-axes.  @var{h1} and @var{h2} are handles to the objects generated by the
plot commands.

@example
@group
x = 0:0.1:2*pi;
y1 = sin (x);
y2 = exp (x - 1);
ax = plotyy (x, y1, x - 1, y2, @@plot, @@semilogy);
xlabel ("X");
ylabel (ax(1), "Axis 1");
ylabel (ax(2), "Axis 2");
@end group
@end example
@seealso{plot}
@end deftypefn
polar
@c polar scripts/plot/draw/polar.m
-*- texinfo -*-
@deftypefn  {Function File} {} polar (@var{theta}, @var{rho})
@deftypefnx {Function File} {} polar (@var{theta}, @var{rho}, @var{fmt})
@deftypefnx {Function File} {} polar (@var{cplx})
@deftypefnx {Function File} {} polar (@var{cplx}, @var{fmt})
@deftypefnx {Function File} {} polar (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} polar (@dots{})
Create a 2-D plot from polar coordinates @var{theta} and @var{rho}.

If a single complex input @var{cplx} is given then the real part is used
for @var{theta} and the imaginary part is used for @var{rho}.

The optional argument @var{fmt} specifies the line format in the same way
as @code{plot}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.

Implementation Note: The polar axis is drawn using line and text objects
encapsulated in an hggroup.  The hggroup properties are linked to the
original axes object such that altering an appearance property, for example
@code{fontname}, will update the polar axis.  Two new properties are
added to the original axes--@code{rtick}, @code{ttick}--which replace
@code{xtick}, @code{ytick}.  The first is a list of tick locations in the
radial (rho) direction; The second is a list of tick locations in the
angular (theta) direction specified in degrees, i.e., in the range 0--359.
@seealso{rose, compass, plot}
@end deftypefn
quiver3
@c quiver3 scripts/plot/draw/quiver3.m
-*- texinfo -*-
@deftypefn  {Function File} {} quiver3 (@var{u}, @var{v}, @var{w})
@deftypefnx {Function File} {} quiver3 (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w})
@deftypefnx {Function File} {} quiver3 (@dots{}, @var{s})
@deftypefnx {Function File} {} quiver3 (@dots{}, @var{style})
@deftypefnx {Function File} {} quiver3 (@dots{}, "filled")
@deftypefnx {Function File} {} quiver3 (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} quiver3 (@dots{})

Plot a 3-D vector field with arrows.

Plot the (@var{u}, @var{v}, @var{w}) components of a vector field in
an (@var{x}, @var{y}, @var{z}) meshgrid.  If the grid is uniform then
@var{x}, @var{y}, and @var{z} can be specified as vectors.

If @var{x}, @var{y}, and @var{z} are undefined they are assumed to be
@code{(1:@var{m}, 1:@var{n}, 1:@var{p})} where @code{[@var{m}, @var{n}] =
size (@var{u})} and @code{@var{p} = max (size (@var{w}))}.

The variable @var{s} is a scalar defining a scaling factor to use for
the arrows of the field relative to the mesh spacing.  A value of 0
disables all scaling.  The default value is 0.9.

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.
If a marker is specified then markers at the grid points of the vectors are
drawn rather than arrows.  If the argument @qcode{"filled"} is given then the
markers are filled.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to a quiver object.
A quiver object regroups the components of the quiver plot (body, arrow,
and marker), and allows them to be changed together.

@example
@group
[x, y, z] = peaks (25);
surf (x, y, z);
hold on;
[u, v, w] = surfnorm (x, y, z / 10);
h = quiver3 (x, y, z, u, v, w);
set (h, "maxheadsize", 0.33);
@end group
@end example

@seealso{quiver, compass, feather, plot}
@end deftypefn
quiver
@c quiver scripts/plot/draw/quiver.m
-*- texinfo -*-
@deftypefn  {Function File} {} quiver (@var{u}, @var{v})
@deftypefnx {Function File} {} quiver (@var{x}, @var{y}, @var{u}, @var{v})
@deftypefnx {Function File} {} quiver (@dots{}, @var{s})
@deftypefnx {Function File} {} quiver (@dots{}, @var{style})
@deftypefnx {Function File} {} quiver (@dots{}, "filled")
@deftypefnx {Function File} {} quiver (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} quiver (@dots{})

Plot a 2-D vector field with arrows.

Plot the (@var{u}, @var{v}) components of a vector field in
an (@var{x}, @var{y}) meshgrid.  If the grid is uniform then @var{x} and
@var{y} can be specified as vectors.

If @var{x} and @var{y} are undefined they are assumed to be
@code{(1:@var{m}, 1:@var{n})} where
@code{[@var{m}, @var{n}] = size (@var{u})}.

The variable @var{s} is a scalar defining a scaling factor to use for
the arrows of the field relative to the mesh spacing.  A value of 0
disables all scaling.  The default value is 0.9.

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.
If a marker is specified then markers at the grid points of the vectors are
drawn rather than arrows.  If the argument @qcode{"filled"} is given then
the markers are filled.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to a quiver object.
A quiver object regroups the components of the quiver plot (body, arrow,
and marker), and allows them to be changed together.

Example:

@example
@group
[x, y] = meshgrid (1:2:20);
h = quiver (x, y, sin (2*pi*x/10), sin (2*pi*y/10));
set (h, "maxheadsize", 0.33);
@end group
@end example

@seealso{quiver3, compass, feather, plot}
@end deftypefn
rectangle
@c rectangle scripts/plot/draw/rectangle.m
-*- texinfo -*-
@deftypefn  {Function File} {} rectangle ()
@deftypefnx {Function File} {} rectangle (@dots{}, "Position", @var{pos})
@deftypefnx {Function File} {} rectangle (@dots{}, "Curvature", @var{curv})
@deftypefnx {Function File} {} rectangle (@dots{}, "EdgeColor", @var{ec})
@deftypefnx {Function File} {} rectangle (@dots{}, "FaceColor", @var{fc})
@deftypefnx {Function File} {} rectangle (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} rectangle (@dots{})
Draw a rectangular patch defined by @var{pos} and @var{curv}.

The variable @code{@var{pos}(1:2)} defines the lower left-hand corner of
the patch and @code{@var{pos}(3:4)} defines its width and height.  By
default, the value of @var{pos} is @code{[0, 0, 1, 1]}.

The variable @var{curv} defines the curvature of the sides of the rectangle
and may be a scalar or two-element vector with values between 0 and 1.
A value of 0 represents no curvature of the side, whereas a value of 1
means that the side is entirely curved into the arc of a circle.
If @var{curv} is a two-element vector, then the first element is the
curvature along the x-axis of the patch and the second along y-axis.

If @var{curv} is a scalar, it represents the curvature of the shorter of the
two sides of the rectangle and the curvature of the other side is defined
by

@example
min (pos(1:2)) / max (pos(1:2)) * curv
@end example

Additional property/value pairs are passed to the underlying patch command.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
rectangle object.
@end deftypefn
@seealso{patch, line, cylinder, ellipsoid, sphere}
ribbon
@c ribbon scripts/plot/draw/ribbon.m
-*- texinfo -*-
@deftypefn  {Function File} {} ribbon (@var{y})
@deftypefnx {Function File} {} ribbon (@var{x}, @var{y})
@deftypefnx {Function File} {} ribbon (@var{x}, @var{y}, @var{width})
@deftypefnx {Function File} {} ribbon (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} ribbon (@dots{})
Draw a ribbon plot for the columns of @var{y} vs. @var{x}.

The optional parameter @var{width} specifies the width of a single ribbon
(default is 0.75).  If @var{x} is omitted, a vector containing the
row numbers is assumed (@code{1:rows (Y)}).

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to
the surface objects representing each ribbon.
@seealso{surface, waterfall}
@end deftypefn
rose
@c rose scripts/plot/draw/rose.m
-*- texinfo -*-
@deftypefn  {Function File} {} rose (@var{th})
@deftypefnx {Function File} {} rose (@var{th}, @var{nbins})
@deftypefnx {Function File} {} rose (@var{th}, @var{bins})
@deftypefnx {Function File} {} rose (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} rose (@dots{})
@deftypefnx {Function File} {[@var{thout} @var{rout}] =} rose (@dots{})
Plot an angular histogram.

With one vector argument, @var{th}, plot the histogram with 20 angular bins.
If @var{th} is a matrix then each column of @var{th} produces a separate
histogram.

If @var{nbins} is given and is a scalar, then the histogram is produced with
@var{nbin} bins.  If @var{bins} is a vector, then the center of each bin is
defined by the values of @var{bins} and the number of bins is
given by the number of elements in @var{bins}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a vector of graphics handles to the
line objects representing each histogram.

If two output arguments are requested then no plot is made and
the polar vectors necessary to plot the histogram are returned instead.

@example
@group
[th, r] = rose ([2*randn(1e5,1), pi + 2*randn(1e5,1)]);
polar (th, r);
@end group
@end example

@seealso{hist, polar}
@end deftypefn
scatter3
@c scatter3 scripts/plot/draw/scatter3.m
-*- texinfo -*-
@deftypefn  {Function File} {} scatter3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s})
@deftypefnx {Function File} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s}, @var{c})
@deftypefnx {Function File} {} scatter3 (@dots{}, @var{style})
@deftypefnx {Function File} {} scatter3 (@dots{}, "filled")
@deftypefnx {Function File} {} scatter3 (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} scatter3 (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} scatter3 (@dots{})
Draw a 3-D scatter plot.

A marker is plotted at each point defined by the coordinates in the vectors
@var{x}, @var{y}, and @var{z}.

The size of the markers is determined by @var{s}, which can be a scalar
or a vector of the same length as @var{x}, @var{y}, and @var{z}.  If @var{s}
is not given, or is an empty matrix, then a default value of 8 points is
used.

The color of the markers is determined by @var{c}, which can be a string
defining a fixed color; a 3-element vector giving the red, green, and blue
components of the color; a vector of the same length as @var{x} that gives
a scaled index into the current colormap; or an @nospell{Nx3} matrix defining
the RGB color of each marker individually.

The marker to use can be changed with the @var{style} argument, that is a
string defining a marker in the same manner as the @code{plot} command.
If no marker is specified it defaults to @qcode{"o"} or circles.
If the argument @qcode{"filled"} is given then the markers are filled.

Additional property/value pairs are passed directly to the underlying
patch object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the hggroup
object representing the points.

@example
@group
[x, y, z] = peaks (20);
scatter3 (x(:), y(:), z(:), [], z(:));
@end group
@end example

@seealso{scatter, patch, plot}
@end deftypefn
scatter
@c scatter scripts/plot/draw/scatter.m
-*- texinfo -*-
@deftypefn  {Function File} {} scatter (@var{x}, @var{y})
@deftypefnx {Function File} {} scatter (@var{x}, @var{y}, @var{s})
@deftypefnx {Function File} {} scatter (@var{x}, @var{y}, @var{s}, @var{c})
@deftypefnx {Function File} {} scatter (@dots{}, @var{style})
@deftypefnx {Function File} {} scatter (@dots{}, "filled")
@deftypefnx {Function File} {} scatter (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} scatter (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} scatter (@dots{})
Draw a 2-D scatter plot.

A marker is plotted at each point defined by the coordinates in the vectors
@var{x} and @var{y}.

The size of the markers is determined by @var{s}, which can be a scalar
or a vector of the same length as @var{x} and @var{y}.  If @var{s}
is not given, or is an empty matrix, then a default value of 8 points is
used.

The color of the markers is determined by @var{c}, which can be a string
defining a fixed color; a 3-element vector giving the red, green, and blue
components of the color; a vector of the same length as @var{x} that gives
a scaled index into the current colormap; or an @nospell{Nx3} matrix defining
the RGB color of each marker individually.

The marker to use can be changed with the @var{style} argument, that is a
string defining a marker in the same manner as the @code{plot} command.
If no marker is specified it defaults to @qcode{"o"} or circles.
If the argument @qcode{"filled"} is given then the markers are filled.

Additional property/value pairs are passed directly to the underlying
patch object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created patch
object.

Example:

@example
@group
x = randn (100, 1);
y = randn (100, 1);
scatter (x, y, [], sqrt (x.^2 + y.^2));
@end group
@end example

@seealso{scatter3, patch, plot}
@end deftypefn
semilogxerr
@c semilogxerr scripts/plot/draw/semilogxerr.m
-*- texinfo -*-
@deftypefn  {Function File} {} semilogxerr (@var{y}, @var{ey})
@deftypefnx {Function File} {} semilogxerr (@var{y}, @dots{}, @var{fmt})
@deftypefnx {Function File} {} semilogxerr (@var{x}, @var{y}, @var{ey})
@deftypefnx {Function File} {} semilogxerr (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {Function File} {} semilogxerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {Function File} {} semilogxerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {Function File} {} semilogxerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {Function File} {} semilogxerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {Function File} {} semilogxerr (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} semilogxerr (@dots{})
Produce 2-D plots using a logarithmic scale for the x-axis and errorbars
at each data point.

Many different combinations of arguments are possible.  The most common
form is

@example
semilogxerr (@var{x}, @var{y}, @var{ey}, @var{fmt})
@end example

@noindent
which produces a semi-logarithmic plot of @var{y} versus @var{x}
with errors in the @var{y}-scale defined by @var{ey} and the plot
format defined by @var{fmt}.  @xref{XREFerrorbar,,errorbar}, for available
formats and additional information.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

@seealso{errorbar, semilogyerr, loglogerr}
@end deftypefn
semilogx
@c semilogx scripts/plot/draw/semilogx.m
-*- texinfo -*-
@deftypefn  {Function File} {} semilogx (@var{y})
@deftypefnx {Function File} {} semilogx (@var{x}, @var{y})
@deftypefnx {Function File} {} semilogx (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} semilogx (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} semilogx (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} semilogx (@dots{})
Produce a 2-D plot using a logarithmic scale for the x-axis.

See the documentation of @code{plot} for a description of the
arguments that @code{semilogx} will accept.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.
@seealso{plot, semilogy, loglog}
@end deftypefn
semilogyerr
@c semilogyerr scripts/plot/draw/semilogyerr.m
-*- texinfo -*-
@deftypefn  {Function File} {} semilogyerr (@var{y}, @var{ey})
@deftypefnx {Function File} {} semilogyerr (@var{y}, @dots{}, @var{fmt})
@deftypefnx {Function File} {} semilogyerr (@var{x}, @var{y}, @var{ey})
@deftypefnx {Function File} {} semilogyerr (@var{x}, @var{y}, @var{err}, @var{fmt})
@deftypefnx {Function File} {} semilogyerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt})
@deftypefnx {Function File} {} semilogyerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt})
@deftypefnx {Function File} {} semilogyerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt})
@deftypefnx {Function File} {} semilogyerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{})
@deftypefnx {Function File} {} semilogyerr (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} semilogyerr (@dots{})
Produce 2-D plots using a logarithmic scale for the y-axis and errorbars
at each data point.

Many different combinations of arguments are possible.  The most common
form is

@example
semilogyerr (@var{x}, @var{y}, @var{ey}, @var{fmt})
@end example

@noindent
which produces a semi-logarithmic plot of @var{y} versus @var{x}
with errors in the @var{y}-scale defined by @var{ey} and the plot
format defined by @var{fmt}.  @xref{XREFerrorbar,,errorbar}, for available
formats and additional information.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

@seealso{errorbar, semilogxerr, loglogerr}
@end deftypefn
semilogy
@c semilogy scripts/plot/draw/semilogy.m
-*- texinfo -*-
@deftypefn  {Function File} {} semilogy (@var{y})
@deftypefnx {Function File} {} semilogy (@var{x}, @var{y})
@deftypefnx {Function File} {} semilogy (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} semilogy (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} semilogy (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} semilogy (@dots{})
Produce a 2-D plot using a logarithmic scale for the y-axis.

See the documentation of @code{plot} for a description of the
arguments that @code{semilogy} will accept.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created plot.
@seealso{plot, semilogx, loglog}
@end deftypefn
shrinkfaces
@c shrinkfaces scripts/plot/draw/shrinkfaces.m
-*- texinfo -*-
@deftypefn  {Function File} {} shrinkfaces (@var{p}, @var{sf})
@deftypefnx {Function File} {@var{nfv} =} shrinkfaces (@var{p}, @var{sf})
@deftypefnx {Function File} {@var{nfv} =} shrinkfaces (@var{fv}, @var{sf})
@deftypefnx {Function File} {@var{nfv} =} shrinkfaces (@var{f}, @var{v}, @var{sf})
@deftypefnx {Function File} {[@var{nf}, @var{nv}] =} shrinkfaces (@dots{})

Reduce the size of faces in a patch by the shrink factor @var{sf}.

The patch object can be specified by a graphics handle (@var{p}), a patch
structure (@var{fv}) with the fields @qcode{"faces"} and @qcode{"vertices"},
or as two separate matrices (@var{f}, @var{v}) of faces and vertices.

The shrink factor @var{sf} is a positive number specifying the percentage
of the original area the new face will occupy.  If no factor is given the
default is 0.3 (a reduction to 30% of the original size).  A factor greater
than 1.0 will result in the expansion of faces.

Given a patch handle as the first input argument and no output parameters,
perform the shrinking of the patch faces in place and redraw the patch.

If called with one output argument, return a structure with fields
@qcode{"faces"}, @qcode{"vertices"}, and @qcode{"facevertexcdata"}
containing the data after shrinking.  This structure can be used directly
as an input argument to the @code{patch} function.

@strong{Caution:}: Performing the shrink operation on faces which are not
convex can lead to undesirable results.

Example: a triangulated 3/4 circle and the corresponding shrunken version.

@example
@group
[phi r] = meshgrid (linspace (0, 1.5*pi, 16), linspace (1, 2, 4));
tri = delaunay (phi(:), r(:));
v = [r(:).*sin(phi(:)) r(:).*cos(phi(:))];
clf ()
p = patch ("Faces", tri, "Vertices", v, "FaceColor", "none");
fv = shrinkfaces (p);
patch (fv)
axis equal
grid on
@end group
@end example

@seealso{patch}
@end deftypefn
slice
@c slice scripts/plot/draw/slice.m
-*- texinfo -*-
@deftypefn  {Function File} {} slice (@var{x}, @var{y}, @var{z}, @var{v}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {Function File} {} slice (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {Function File} {} slice (@var{v}, @var{sx}, @var{sy}, @var{sz})
@deftypefnx {Function File} {} slice (@var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {Function File} {} slice (@dots{}, @var{method})
@deftypefnx {Function File} {} slice (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} slice (@dots{})
Plot slices of 3-D data/scalar fields.

Each element of the 3-dimensional array @var{v} represents a scalar value at
a location given by the parameters @var{x}, @var{y}, and @var{z}.  The
parameters @var{x}, @var{x}, and @var{z} are either 3-dimensional arrays of
the same size as the array @var{v} in the @qcode{"meshgrid"} format or
vectors.  The parameters @var{xi}, etc. respect a similar format to
@var{x}, etc., and they represent the points at which the array @var{vi}
is interpolated using interp3.  The vectors @var{sx}, @var{sy}, and
@var{sz} contain points of orthogonal slices of the respective axes.

If @var{x}, @var{y}, @var{z} are omitted, they are assumed to be
@code{x = 1:size (@var{v}, 2)}, @code{y = 1:size (@var{v}, 1)} and
@code{z = 1:size (@var{v}, 3)}.

@var{method} is one of:

@table @asis
@item @qcode{"nearest"}
Return the nearest neighbor.

@item @qcode{"linear"}
Linear interpolation from nearest neighbors.

@item @qcode{"cubic"}
Cubic interpolation from four nearest neighbors (not implemented yet).

@item @qcode{"spline"}
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

The default method is @qcode{"linear"}.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Examples:

@example
@group
[x, y, z] = meshgrid (linspace (-8, 8, 32));
v = sin (sqrt (x.^2 + y.^2 + z.^2)) ./ (sqrt (x.^2 + y.^2 + z.^2));
slice (x, y, z, v, [], 0, []);

[xi, yi] = meshgrid (linspace (-7, 7));
zi = xi + yi;
slice (x, y, z, v, xi, yi, zi);
@end group
@end example
@seealso{interp3, surface, pcolor}
@end deftypefn
sombrero
@c sombrero scripts/plot/draw/sombrero.m
-*- texinfo -*-
@deftypefn  {Function File} {} sombrero ()
@deftypefnx {Function File} {} sombrero (@var{n})
@deftypefnx {Function File} {@var{z} =} sombrero (@dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} sombrero (@dots{})
Plot the familiar 3-D sombrero function.

The function plotted is
@tex
$$z = { \rm{sin} (\sqrt {(x^2 + y^2)}) \over \sqrt {(x^2 + y^2)} }$$
@end tex
@ifnottex

@example
z = sin (sqrt (x^2 + y^2)) / (sqrt (x^2 + y^2))
@end example

@end ifnottex
Called without a return argument, @code{sombrero} plots the surface of the
above function over the meshgrid [-8,8] using @code{surf}.

If @var{n} is a scalar the plot is made with @var{n} grid lines.
The default value for @var{n} is 41.

When called with output arguments, return the data for the function
evaluated over the meshgrid.  This can subsequently be plotted with
@code{surf (@var{x}, @var{y}, @var{z})}.

@seealso{peaks, meshgrid, mesh, surf}
@end deftypefn
sphere
@c sphere scripts/plot/draw/sphere.m
-*- texinfo -*-
@deftypefn  {Function File} {} sphere ()
@deftypefnx {Function File} {} sphere (@var{n})
@deftypefnx {Function File} {} sphere (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} sphere (@dots{})
Plot a 3-D unit sphere.

The optional input @var{n} determines the number of faces around the
circumference of the sphere.  The default value is 20.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

If outputs are requested @code{sphere} returns three matrices in
@code{meshgrid} format such that @code{surf (@var{x}, @var{y}, @var{z})}
generates a unit sphere.

Example:

@example
@group
[x, y, z] = sphere (40);
surf (3*x, 3*y, 3*z);
axis equal;
title ("sphere of radius 3");
@end group
@end example
@seealso{cylinder, ellipsoid, rectangle}
@end deftypefn
stairs
@c stairs scripts/plot/draw/stairs.m
-*- texinfo -*-
@deftypefn  {Function File} {} stairs (@var{y})
@deftypefnx {Function File} {} stairs (@var{x}, @var{y})
@deftypefnx {Function File} {} stairs (@dots{}, @var{style})
@deftypefnx {Function File} {} stairs (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} stairs (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} stairs (@dots{})
@deftypefnx {Function File} {[@var{xstep}, @var{ystep}] =} stairs (@dots{})
Produce a stairstep plot.

The arguments @var{x} and @var{y} may be vectors or matrices.
If only one argument is given, it is taken as a vector of Y values
and the X coordinates are taken to be the indices of the elements.

The style to use for the plot can be defined with a line style @var{style}
of the same format as the @code{plot} command.

Multiple property/value pairs may be specified, but they must appear in
pairs.

If the first argument @var{hax} is an axis handle, then plot into this axis,
rather than the current axis handle returned by @code{gca}.

If one output argument is requested, return a graphics handle to the
created plot.  If two output arguments are specified, the data are generated
but not plotted.  For example,

@example
stairs (x, y);
@end example

@noindent
and

@example
@group
[xs, ys] = stairs (x, y);
plot (xs, ys);
@end group
@end example

@noindent
are equivalent.
@seealso{bar, hist, plot, stem}
@end deftypefn
stem3
@c stem3 scripts/plot/draw/stem3.m
-*- texinfo -*-
@deftypefn  {Function File} {} stem3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} stem3 (@dots{}, @var{linespec})
@deftypefnx {Function File} {} stem3 (@dots{}, "filled")
@deftypefnx {Function File} {} stem3 (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} stem3 (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} stem3 (@dots{})
Plot a 3-D stem graph.

Stems are drawn from the height @var{z} to the location in the x-y plane
determined by @var{x} and @var{y}.  The default color is @qcode{"b"} (blue),
the default line style is @qcode{"-"}, and the default marker is @qcode{"o"}.

The line style can be altered by the @code{linespec} argument in the same
manner as the @code{plot} command.  If the @qcode{"filled"} argument is
present the markers at the top of the stems will be filled in.

Optional property/value pairs may be specified to control the appearance
of the plot.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a handle to the @nospell{"stem series"}
hggroup containing the line and marker objects used for the plot.
@xref{XREFstem,,stem}, for a description of the @nospell{"stem series"}
object.

Example:

@example
@group
theta = 0:0.2:6;
stem3 (cos (theta), sin (theta), theta);
@end group
@end example

@noindent
plots 31 stems with heights from 0 to 6 lying on a circle.

Implementation Note: Color definitions with RGB-triples are not valid.
@seealso{stem, bar, hist, plot}
@end deftypefn
stemleaf
@c stemleaf scripts/plot/draw/stemleaf.m
-*- texinfo -*-
@deftypefn  {Function File} {} stemleaf (@var{x}, @var{caption})
@deftypefnx {Function File} {} stemleaf (@var{x}, @var{caption}, @var{stem_sz})
@deftypefnx {Function File} {@var{plotstr} =} stemleaf (@dots{})
Compute and display a stem and leaf plot of the vector @var{x}.

The input @var{x} should be a vector of integers.  Any non-integer values
will be converted to integer by @code{@var{x} = fix (@var{x})}.  By default
each element of @var{x} will be plotted with the last digit of the element
as a leaf value and the remaining digits as the stem.  For example, 123
will be plotted with the stem @samp{12} and the leaf @samp{3}.  The second
argument, @var{caption}, should be a character array which provides a
description of the data.  It is included as a heading for the output.

The optional input @var{stem_sz} sets the width of each stem.
The stem width is determined by @code{10^(@var{stem_sz} + 1)}.
The default stem width is 10.

The output of @code{stemleaf} is composed of two parts: a
"Fenced Letter Display," followed by the stem-and-leaf plot itself.
The Fenced Letter Display is described in @cite{Exploratory Data Analysis}.
Briefly, the entries are as shown:

@example
@group

        Fenced Letter Display
#% nx|___________________     nx = numel (x)
M% mi|       md         |     mi median index, md median
H% hi|hl              hu| hs  hi lower hinge index, hl,hu hinges,
1    |x(1)         x(nx)|     hs h_spreadx(1), x(nx) first
           _______            and last data value.
     ______|step |_______     step 1.5*h_spread
    f|ifl            ifh|     inner fence, lower and higher
     |nfl            nfh|     no.\ of data points within fences
    F|ofl            ofh|     outer fence, lower and higher
     |nFl            nFh|     no.\ of data points outside outer
                              fences
@end group
@end example

The stem-and-leaf plot shows on each line the stem value followed by the
string made up of the leaf digits.  If the @var{stem_sz} is not 1 the
successive leaf values are separated by ",".

With no return argument, the plot is immediately displayed.  If an output
argument is provided, the plot is returned as an array of strings.

The leaf digits are not sorted.  If sorted leaf values are desired, use
@code{@var{xs} = sort (@var{x})} before calling @code{stemleaf (@var{xs})}.

The stem and leaf plot and associated displays are described in:
Ch. 3, @cite{Exploratory Data Analysis} by J. W. Tukey, Addison-Wesley, 1977.
@seealso{hist, printd}
@end deftypefn
stem
@c stem scripts/plot/draw/stem.m
-*- texinfo -*-
@deftypefn  {Function File} {} stem (@var{y})
@deftypefnx {Function File} {} stem (@var{x}, @var{y})
@deftypefnx {Function File} {} stem (@dots{}, @var{linespec})
@deftypefnx {Function File} {} stem (@dots{}, "filled")
@deftypefnx {Function File} {} stem (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} stem (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} stem (@dots{})
Plot a 2-D stem graph.

If only one argument is given, it is taken as the y-values and the
x-coordinates are taken from the indices of the elements.

If @var{y} is a matrix, then each column of the matrix is plotted as
a separate stem graph.  In this case @var{x} can either be a vector,
the same length as the number of rows in @var{y}, or it can be a
matrix of the same size as @var{y}.

The default color is @qcode{"b"} (blue), the default line style is
@qcode{"-"}, and the default marker is @qcode{"o"}.  The line style can
be altered by the @code{linespec} argument in the same manner as the
@code{plot} command.  If the @qcode{"filled"} argument is present the
markers at the top of the stems will be filled in.  For example,

@example
@group
x = 1:10;
y = 2*x;
stem (x, y, "r");
@end group
@end example

@noindent
plots 10 stems with heights from 2 to 20 in red;

Optional property/value pairs may be specified to control the appearance
of the plot.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a handle to a @nospell{"stem series"}
hggroup.  The single hggroup handle has all of the graphical elements
comprising the plot as its children; This allows the properties of
multiple graphics objects to be changed by modifying just a single
property of the @nospell{"stem series"} hggroup.

For example,

@example
@group
x = [0:10]';
y = [sin(x), cos(x)]
h = stem (x, y);
set (h(2), "color", "g");
set (h(1), "basevalue", -1)
@end group
@end example

@noindent
changes the color of the second @nospell{"stem series"} and moves the base
line of the first.

Stem Series Properties

@table @asis
@item linestyle
The linestyle of the stem.  (Default: @qcode{"-"})

@item linewidth
The width of the stem.  (Default: 0.5)

@item color
The color of the stem, and if not separately specified, the marker.
(Default: @qcode{"b"} [blue])

@item marker
The marker symbol to use at the top of each stem.  (Default: @qcode{"o"})

@item markeredgecolor
The edge color of the marker.  (Default: @qcode{"color"} property)

@item markerfacecolor
The color to use for @nospell{"filling"} the marker.
(Default: @qcode{"none"} [unfilled])

@item markersize
The size of the marker.  (Default: 6)

@item baseline
The handle of the line object which implements the baseline.  Use @code{set}
with the returned handle to change graphic properties of the baseline.

@item basevalue
The y-value where the baseline is drawn.  (Default: 0)
@end table
@seealso{stem3, bar, hist, plot, stairs}
@end deftypefn
surface
@c surface scripts/plot/draw/surface.m
-*- texinfo -*-
@deftypefn  {Function File} {} surface (@var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {Function File} {} surface (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surface (@var{z}, @var{c})
@deftypefnx {Function File} {} surface (@var{z})
@deftypefnx {Function File} {} surface (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} surface (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} surface (@dots{})
Create a surface graphic object given matrices @var{x} and @var{y} from
@code{meshgrid} and a matrix of values @var{z} corresponding to the
@var{x} and @var{y} coordinates of the surface.

If @var{x} and @var{y} are vectors, then a typical vertex is
(@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, columns of @var{z} correspond
to different @var{x} values and rows of @var{z} correspond to different
@var{y} values.  If only a single input @var{z} is given then @var{x} is
taken to be @code{1:rows (@var{z})} and @var{y} is
@code{1:columns (@var{z})}.

Any property/value input pairs are assigned to the surface object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.
@seealso{surf, mesh, patch, line}
@end deftypefn
surfc
@c surfc scripts/plot/draw/surfc.m
-*- texinfo -*-
@deftypefn  {Function File} {} surfc (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surfc (@var{z})
@deftypefnx {Function File} {} surfc (@dots{}, @var{c})
@deftypefnx {Function File} {} surfc (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} surfc (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} surfc (@dots{})
Plot a 3-D surface mesh with underlying contour lines.

The surface mesh is plotted using shaded rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The color of the surface is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally, the color of the surface can be specified independently of
@var{z} by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Note: The exact appearance of the surface can be controlled with the
@code{shading} command or by using @code{set} to control surface object
properties.
@seealso{ezsurfc, surf, surfl, surfnorm, trisurf, contour, mesh, surface, meshgrid, hidden, shading, colormap, caxis}
@end deftypefn
surfl
@c surfl scripts/plot/draw/surfl.m
-*- texinfo -*-
@deftypefn  {Function File} {} surfl (@var{z})
@deftypefnx {Function File} {} surfl (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surfl (@dots{}, @var{lsrc})
@deftypefnx {Function File} {} surfl (@var{x}, @var{y}, @var{z}, @var{lsrc}, @var{P})
@deftypefnx {Function File} {} surfl (@dots{}, "cdata")
@deftypefnx {Function File} {} surfl (@dots{}, "light")
@deftypefnx {Function File} {} surfl (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} surfl (@dots{})
Plot a 3-D surface using shading based on various lighting models.

The surface mesh is plotted using shaded rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The default lighting mode @qcode{"cdata"}, changes the cdata property of the
surface object to give the impression of a lighted surface.
@strong{Warning:} The alternative mode @qcode{"light"} mode which creates a
light object to illuminate the surface is not implemented (yet).

The light source location can be specified using @var{lsrc}.  It can be given
as a 2-element vector [azimuth, elevation] in degrees, or as a 3-element
vector [lx, ly, lz].  The default value is rotated 45 degrees
counterclockwise to the current view.

The material properties of the surface can specified using a 4-element
vector @var{P} = [@var{AM} @var{D} @var{SP} @var{exp}] which defaults to
@var{p} = [0.55 0.6 0.4 10].

@table @asis
@item @qcode{"AM"} strength of ambient light

@item @qcode{"D"} strength of diffuse reflection

@item @qcode{"SP"} strength of specular reflection

@item @qcode{"EXP"} specular exponent
@end table

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Example:

@example
@group
colormap (bone (64));
surfl (peaks);
shading interp;
@end group
@end example
@seealso{diffuse, specular, surf, shading, colormap, caxis}
@end deftypefn
surf
@c surf scripts/plot/draw/surf.m
-*- texinfo -*-
@deftypefn  {Function File} {} surf (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surf (@var{z})
@deftypefnx {Function File} {} surf (@dots{}, @var{c})
@deftypefnx {Function File} {} surf (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} surf (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} surf (@dots{})
Plot a 3-D surface mesh.

The surface mesh is plotted using shaded rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The color of the surface is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally, the color of the surface can be specified independently of
@var{z} by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

Note: The exact appearance of the surface can be controlled with the
@code{shading} command or by using @code{set} to control surface object
properties.
@seealso{ezsurf, surfc, surfl, surfnorm, trisurf, contour, mesh, surface, meshgrid, hidden, shading, colormap, caxis}
@end deftypefn
surfnorm
@c surfnorm scripts/plot/draw/surfnorm.m
-*- texinfo -*-
@deftypefn  {Function File} {} surfnorm (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surfnorm (@var{z})
@deftypefnx {Function File} {} surfnorm (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} surfnorm (@var{hax}, @dots{})
@deftypefnx {Function File} {[@var{nx}, @var{ny}, @var{nz}] =} surfnorm (@dots{})
Find the vectors normal to a meshgridded surface.

If @var{x} and @var{y} are vectors, then a typical vertex is
(@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, columns of @var{z} correspond
to different @var{x} values and rows of @var{z} correspond to different
@var{y} values.  If only a single input @var{z} is given then @var{x} is
taken to be @code{1:rows (@var{z})} and @var{y} is
@code{1:columns (@var{z})}.

If no return arguments are requested, a surface plot with the normal
vectors to the surface is plotted.

Any property/value input pairs are assigned to the surface object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

If output arguments are requested then the components of the normal
vectors are returned in @var{nx}, @var{ny}, and @var{nz} and no plot is
made.

An example of the use of @code{surfnorm} is

@example
surfnorm (peaks (25));
@end example

Algorithm: The normal vectors are calculated by taking the cross product
of the diagonals of each of the quadrilaterals in the meshgrid to find the
normal vectors of the centers of these quadrilaterals.  The four nearest
normal vectors to the meshgrid points are then averaged to obtain the
normal to the surface at the meshgridded points.

@seealso{isonormals, quiver3, surf, meshgrid}
@end deftypefn
tetramesh
@c tetramesh scripts/plot/draw/tetramesh.m
-*- texinfo -*-
@deftypefn  {Function File} {} tetramesh (@var{T}, @var{X})
@deftypefnx {Function File} {} tetramesh (@var{T}, @var{X}, @var{C})
@deftypefnx {Function File} {} tetramesh (@dots{}, @var{property}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} tetramesh (@dots{})
Display the tetrahedrons defined in the m-by-4 matrix @var{T} as 3-D patches.

@var{T} is typically the output of a Delaunay triangulation of a 3-D set
of points.  Every row of @var{T} contains four indices into the n-by-3
matrix @var{X} of the vertices of a tetrahedron.  Every row in @var{X}
represents one point in 3-D space.

The vector @var{C} specifies the color of each tetrahedron as an index
into the current colormap.  The default value is 1:m where m is the number
of tetrahedrons; the indices are scaled to map to the full range of the
colormap.  If there are more tetrahedrons than colors in the colormap then
the values in @var{C} are cyclically repeated.

Calling @code{tetramesh (@dots{}, "property", "value", @dots{})} passes all
property/value pairs directly to the patch function as additional arguments.

The optional return value @var{h} is a vector of patch handles where each
handle represents one tetrahedron in the order given by @var{T}.
A typical use case for @var{h} is to turn the respective patch
@qcode{"visible"} property @qcode{"on"} or @qcode{"off"}.

Type @code{demo tetramesh} to see examples on using @code{tetramesh}.
@seealso{trimesh, delaunay, delaunayn, patch}
@end deftypefn
trimesh
@c trimesh scripts/plot/draw/trimesh.m
-*- texinfo -*-
@deftypefn  {Function File} {} trimesh (@var{tri}, @var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {Function File} {} trimesh (@var{tri}, @var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} trimesh (@var{tri}, @var{x}, @var{y})
@deftypefnx {Function File} {} trimesh (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} trimesh (@dots{})
Plot a 3-D triangular wireframe mesh.

In contrast to @code{mesh}, which plots a mesh using rectangles,
@code{trimesh} plots the mesh using triangles.

@var{tri} is typically the output of a Delaunay triangulation over the
grid of @var{x}, @var{y}.  Every row of @var{tri} represents one triangle
and contains three indices into [@var{x}, @var{y}] which are the
vertices of the triangles in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If no @var{z} input is given then
the triangles are plotted as a 2-D figure.

The color of the trimesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally, the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.  If @var{z} has N elements, then
@var{c} should be an Nx1 vector for colormap data or an Nx3 matrix for
RGB data.

Any property/value pairs are passed directly to the underlying patch object.

The optional return value @var{h} is a graphics handle to the created patch
object.
@seealso{mesh, tetramesh, triplot, trisurf, delaunay, patch, hidden}
@end deftypefn
triplot
@c triplot scripts/plot/draw/triplot.m
-*- texinfo -*-
@deftypefn  {Function File} {} triplot (@var{tri}, @var{x}, @var{y})
@deftypefnx {Function File} {} triplot (@var{tri}, @var{x}, @var{y}, @var{linespec})
@deftypefnx {Function File} {@var{h} =} triplot (@dots{})
Plot a 2-D triangular mesh.

@var{tri} is typically the output of a Delaunay triangulation over the
grid of @var{x}, @var{y}.  Every row of @var{tri} represents one triangle
and contains three indices into [@var{x}, @var{y}] which are the
vertices of the triangles in the x-y plane.

The linestyle to use for the plot can be defined with the argument
@var{linespec} of the same format as the @code{plot} command.

The optional return value @var{h} is a graphics handle to the created
patch object.
@seealso{plot, trimesh, trisurf, delaunay}
@end deftypefn
trisurf
@c trisurf scripts/plot/draw/trisurf.m
-*- texinfo -*-
@deftypefn  {Function File} {} trisurf (@var{tri}, @var{x}, @var{y}, @var{z}, @var{c})
@deftypefnx {Function File} {} trisurf (@var{tri}, @var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} trisurf (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} trisurf (@dots{})
Plot a 3-D triangular surface.

In contrast to @code{surf}, which plots a surface mesh using rectangles,
@code{trisurf} plots the mesh using triangles.

@var{tri} is typically the output of a Delaunay triangulation over the
grid of @var{x}, @var{y}.  Every row of @var{tri} represents one triangle
and contains three indices into [@var{x}, @var{y}] which are the
vertices of the triangles in the x-y plane.  @var{z} determines the
height above the plane of each vertex.

The color of the trimesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally, the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.  If @var{z} has N elements, then
@var{c} should be an Nx1 vector for colormap data or an Nx3 matrix for
RGB data.

Any property/value pairs are passed directly to the underlying patch object.

The optional return value @var{h} is a graphics handle to the created patch
object.
@seealso{surf, triplot, trimesh, delaunay, patch, shading}
@end deftypefn
waterfall
@c waterfall scripts/plot/draw/waterfall.m
-*- texinfo -*-
@deftypefn  {Function File} {} waterfall (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} waterfall (@var{z})
@deftypefnx {Function File} {} waterfall (@dots{}, @var{c})
@deftypefnx {Function File} {} waterfall (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} waterfall (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} waterfall (@dots{})
Plot a 3-D waterfall plot.

A waterfall plot is similar to a @code{meshz} plot except only
mesh lines for the rows of @var{z} (x-values) are shown.

The wireframe mesh is plotted using rectangles.  The vertices of the
rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
over a 2-D rectangular region in the x-y plane.  @var{z} determines the
height above the plane of each vertex.  If only a single @var{z} matrix is
given, then it is plotted over the meshgrid
@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
Thus, columns of @var{z} correspond to different @var{x} values and rows
of @var{z} correspond to different @var{y} values.

The color of the mesh is computed by linearly scaling the @var{z} values
to fit the range of the current colormap.  Use @code{caxis} and/or
change the colormap to control the appearance.

Optionally the color of the mesh can be specified independently of @var{z}
by supplying a color matrix, @var{c}.

Any property/value pairs are passed directly to the underlying surface
object.

If the first argument @var{hax} is an axes handle, then plot into this axis,
rather than the current axes returned by @code{gca}.

The optional return value @var{h} is a graphics handle to the created
surface object.

@seealso{meshz, mesh, meshc, contour, surf, surface, ribbon, meshgrid, hidden, shading, colormap, caxis}
@end deftypefn
__actual_axis_position__
@c __actual_axis_position__ scripts/plot/util/__actual_axis_position__.m
-*- texinfo -*-
@deftypefn  {Function File} {} __actual_axis_position__ (@var{h})
@deftypefnx {Function File} {} __actual_axis_position__ (@var{axis_struct})
Undocumented internal function.
@end deftypefn
allchild
@c allchild scripts/plot/util/allchild.m
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} allchild (@var{handles})
Find all children, including hidden children, of a graphics object.

This function is similar to @code{get (h, "children")}, but also returns
hidden objects (HandleVisibility = @qcode{"off"}).

If @var{handles} is a scalar, @var{h} will be a vector.  Otherwise,
@var{h} will be a cell matrix of the same size as @var{handles} and each
cell will contain a vector of handles.
@seealso{findall, findobj, get, set}
@end deftypefn
ancestor
@c ancestor scripts/plot/util/ancestor.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{parent} =} ancestor (@var{h}, @var{type})
@deftypefnx {Function File} {@var{parent} =} ancestor (@var{h}, @var{type}, "toplevel")
Return the first ancestor of handle object @var{h} whose type matches
@var{type}, where @var{type} is a character string.

If @var{type} is a cell array of strings, return the first parent whose
type matches any of the given type strings.

If the handle object @var{h} itself is of type @var{type}, return @var{h}.

If @qcode{"toplevel"} is given as a third argument, return the highest
parent in the object hierarchy that matches the condition, instead
of the first (nearest) one.
@seealso{findobj, findall, allchild}
@end deftypefn
axes
@c axes scripts/plot/util/axes.m
-*- texinfo -*-
@deftypefn  {Function File} {} axes ()
@deftypefnx {Function File} {} axes (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} axes (@var{hax})
@deftypefnx {Function File} {@var{h} =} axes (@dots{})
Create an axes object and return a handle to it, or set the current axes
to @var{hax}.

Called without any arguments, or with @var{property}/@var{value} pairs,
construct a new axes.  For accepted properties and corresponding
values, @pxref{XREFset,,set}.

Called with a single axes handle argument @var{hax}, the function makes
@var{hax} the current axis.  It also restacks the axes in the
corresponding figure so that @var{hax} is the first entry in the list
of children.  This causes @var{hax} to be displayed on top of any other
axes objects (Z-order stacking).

@seealso{gca, set, get}
@end deftypefn
cla
@c cla scripts/plot/util/cla.m
-*- texinfo -*-
@deftypefn  {Command} {} cla
@deftypefnx {Command} {} cla reset
@deftypefnx {Function File} {} cla (@var{hax})
@deftypefnx {Function File} {} cla (@var{hax}, "reset")
Clear the current axes.

@code{cla} operates by deleting child graphic objects with visible
handles (HandleVisibility = @qcode{"on"}).

If the optional argument @qcode{"reset"} is specified, delete all child
objects including those with hidden handles and reset all axis properties
to their defaults.  However, the following properties are not reset:
Position, Units.

If the first argument @var{hax} is an axes handle, then operate on
this axis rather than the current axes returned by @code{gca}.
@seealso{clf, delete, reset}
@end deftypefn
clf
@c clf scripts/plot/util/clf.m
-*- texinfo -*-
@deftypefn  {Command} {} clf
@deftypefnx {Command} {} clf reset
@deftypefnx {Function File} {} clf (@var{hfig})
@deftypefnx {Function File} {} clf (@var{hfig}, "reset")
@deftypefnx {Function File} {@var{h} =} clf (@dots{})
Clear the current figure window.

@code{clf} operates by deleting child graphics objects with visible
handles (HandleVisibility = @qcode{"on"}).

If the optional argument @qcode{"reset"} is specified, delete all child
objects including those with hidden handles and reset all figure
properties to their defaults.  However, the following properties are not
reset: Position, Units, PaperPosition, PaperUnits.

If the first argument @var{hfig} is a figure handle, then operate on
this figure rather than the current figure returned by @code{gcf}.

The optional return value @var{h} is the graphics handle of the figure
window that was cleared.
@seealso{cla, close, delete, reset}
@end deftypefn
close
@c close scripts/plot/util/close.m
-*- texinfo -*-
@deftypefn  {Command} {} close
@deftypefnx {Command} {} close (@var{h})
@deftypefnx {Command} {} close @var{h}
@deftypefnx {Command} {} close all
@deftypefnx {Command} {} close all hidden
@deftypefnx {Command} {} close all force
Close figure window(s).

When called with no arguments, close the current figure.  This is equivalent
to @code{close (gcf)}.  If the input @var{h} is a graphic handle, or vector
of graphics handles, then close each figure in @var{h}.

If the argument @qcode{"all"} is given then all figures with visible handles
(HandleVisibility = @qcode{"on"}) are closed.

If the argument @qcode{"all hidden"} is given then all figures, including
hidden ones, are closed.

If the argument @qcode{"all force"} is given then all figures are closed
even when @qcode{"closerequestfcn"} has been altered to prevent closing
the window.

Implementation Note: @code{close} operates by calling the function specified
by the @qcode{"closerequestfcn"} property for each figure.  By default, the
function @code{closereq} is used.  It is possible that the function invoked
will delay or abort removing the figure.  To remove a figure without
executing any callback functions use @code{delete}.  When writing a callback
function to close a window do not use @code{close} to avoid recursion.

@seealso{closereq, delete}
@end deftypefn
closereq
@c closereq scripts/plot/util/closereq.m
-*- texinfo -*-
@deftypefn {Function File} {} closereq ()
Close the current figure and delete all graphics objects associated with it.

By default, the @qcode{"closerequestfcn"} property of a new plot figure
points to this function.
@seealso{close, delete}
@end deftypefn
colstyle
@c colstyle scripts/plot/util/colstyle.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{style}, @var{color}, @var{marker}, @var{msg}] =} colstyle (@var{linespec})
Parse @var{linespec} and return the line style, color, and markers given.

In the case of an error, the string @var{msg} will return the text of the
error.
@end deftypefn
copyobj
@c copyobj scripts/plot/util/copyobj.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{hnew} =} copyobj (@var{horig})
@deftypefnx {Function File} {@var{hnew} =} copyobj (@var{horig}, @var{hparent})
Construct a copy of the graphic object associated with handle @var{horig}
and return a handle @var{hnew} to the new object.

If a parent handle @var{hparent} (root, figure, axes, or hggroup) is
specified, the copied object will be created as a child of @var{hparent}.
@seealso{struct2hdl, hdl2struct, findobj}
@end deftypefn
__default_plot_options__
@c __default_plot_options__ scripts/plot/util/__default_plot_options__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{options} =} __default_plot_options__ ()
Undocumented internal function.
@end deftypefn
figure
@c figure scripts/plot/util/figure.m
-*- texinfo -*-
@deftypefn  {Command} {} figure
@deftypefnx {Command} {} figure @var{n}
@deftypefnx {Function File} {} figure (@var{n})
@deftypefnx {Function File} {} figure (@dots{}, "@var{property}", @var{value}, @dots{})
@deftypefnx {Function File} {@var{h} =} figure (@dots{})
Create a new figure window for plotting.

If no arguments are specified, a new figure with the next available number
is created.

If called with an integer @var{n}, and no such numbered figure exists, then
a new figure with the specified number is created.  If the figure already
exists then it is made visible and becomes the current figure for plotting.

Multiple property-value pairs may be specified for the figure object, but
they must appear in pairs.

The optional return value @var{h} is a graphics handle to the created figure
object.
@seealso{axes, gcf, clf, close}
@end deftypefn
findall
@c findall scripts/plot/util/findall.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} findall ()
@deftypefnx {Function File} {@var{h} =} findall (@var{prop_name}, @var{prop_value}, @dots{})
@deftypefnx {Function File} {@var{h} =} findall (@var{prop_name}, @var{prop_value}, "-@var{logical_op}", @var{prop_name}, @var{prop_value})
@deftypefnx {Function File} {@var{h} =} findall ("-property", @var{prop_name})
@deftypefnx {Function File} {@var{h} =} findall ("-regexp", @var{prop_name}, @var{pattern})
@deftypefnx {Function File} {@var{h} =} findall (@var{hlist}, @dots{})
@deftypefnx {Function File} {@var{h} =} findall (@var{hlist}, "flat", @dots{})
@deftypefnx {Function File} {@var{h} =} findall (@var{hlist}, "-depth", @var{d}, @dots{})
Find graphics object, including hidden ones, with specified property values.

The return value @var{h} is a list of handles to the found graphic objects.

@code{findall} performs the same search as @code{findobj}, but it
includes hidden objects (HandleVisibility = @qcode{"off"}).  For full
documentation, @pxref{XREFfindobj,,findobj}.
@seealso{findobj, allchild, get, set}
@end deftypefn
findfigs
@c findfigs scripts/plot/util/findfigs.m
-*- texinfo -*-
@deftypefn {Function File} {} findfigs ()
Find all visible figures that are currently off the screen and move them
onto the screen.
@seealso{allchild, figure, get, set}
@end deftypefn
findobj
@c findobj scripts/plot/util/findobj.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} findobj ()
@deftypefnx {Function File} {@var{h} =} findobj (@var{prop_name}, @var{prop_value}, @dots{})
@deftypefnx {Function File} {@var{h} =} findobj (@var{prop_name}, @var{prop_value}, "-@var{logical_op}", @var{prop_name}, @var{prop_value})
@deftypefnx {Function File} {@var{h} =} findobj ("-property", @var{prop_name})
@deftypefnx {Function File} {@var{h} =} findobj ("-regexp", @var{prop_name}, @var{pattern})
@deftypefnx {Function File} {@var{h} =} findobj (@var{hlist}, @dots{})
@deftypefnx {Function File} {@var{h} =} findobj (@var{hlist}, "flat", @dots{})
@deftypefnx {Function File} {@var{h} =} findobj (@var{hlist}, "-depth", @var{d}, @dots{})
Find graphics object with specified property values.

The simplest form is

@example
findobj (@var{prop_name}, @var{prop_value})
@end example

@noindent
which returns the handles of all objects which have a property named
@var{prop_name} that has the value @var{prop_value}.  If multiple
property/value pairs are specified then only objects meeting all of the
conditions are returned.

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

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

@example
findobj (@var{hlist}, "-depth", 3, @var{prop_name}, @var{prop_value})
@end example

Specifying a depth @var{d} of 0, limits the search to the set of objects
passed in @var{hlist}.  A depth @var{d} of 0 is equivalent to the
@qcode{"flat"} argument.

A specified logical operator may be applied to the pairs of @var{prop_name}
and @var{prop_value}.  The supported logical operators are:
@qcode{"-and"}, @qcode{"-or"},
@qcode{"-xor"}, @qcode{"-not"}.

Objects may also be matched by comparing a regular expression to the
property values, where property values that match
@code{regexp (@var{prop_value}, @var{pattern})} are returned.

Finally, objects may be matched by property name only by using the
@qcode{"-property"} option.

Implementation Note: The search only includes objects with visible
handles (HandleVisibility = @qcode{"on"}).  @xref{XREFfindall,,findall}, to
search for all objects including hidden ones.
@seealso{findall, allchild, get, set}
@end deftypefn
frame2im
@c frame2im scripts/plot/util/frame2im.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{map}] =} frame2im (@var{f})
Convert movie frame to indexed image.

A movie frame is simply a struct with the fields @qcode{"cdata"} and
@qcode{"colormap"}.

Support for N-dimensional images or movies is given when @var{f} is a
struct array.  In such cases, @var{x} will be a @nospell{MxNx1xK or MxNx3xK}
for indexed and RGB movies respectively, with each frame concatenated
along the 4th dimension.

@seealso{im2frame}
@end deftypefn
gca
@c gca scripts/plot/util/gca.m
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} gca ()
Return a handle to the current axis object.

The current axis is the default target for graphics output.  In the case
of a figure with multiple axes, @code{gca} returns the last created axes
or the last axes that was clicked on with the mouse.

If no current axes object exists, create one and return its handle.  The
handle may then be used to examine or set properties of the axes.  For
example,

@example
@group
ax = gca ();
set (ax, "position", [0.5, 0.5, 0.5, 0.5]);
@end group
@end example

@noindent
creates an empty axes object and then changes its location and size in the
figure window.

Note: To find the current axis without creating a new axes object if it
does not exist, query the @qcode{"CurrentAxes"} property of a figure.

@example
get (gcf, "currentaxes");
@end example
@seealso{gcf, gco, gcbf, gcbo, get, set}
@end deftypefn
gcbf
@c gcbf scripts/plot/util/gcbf.m
-*- texinfo -*-
@deftypefn {Function File} {@var{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 @code{gcbo}.

@seealso{gcbo, gcf, gco, gca, get, set}
@end deftypefn
gcbo
@c gcbo scripts/plot/util/gcbo.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} gcbo ()
@deftypefnx {Function File} {[@var{h}, @var{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 @qcode{"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.

@seealso{gcbf, gco, gca, gcf, get, set}
@end deftypefn
gcf
@c gcf scripts/plot/util/gcf.m
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} gcf ()
Return a handle to the current figure.

The current figure is the default target for graphics output.  If multiple
figures exist, @code{gcf} returns the last created figure or the last figure
that was clicked on with the mouse.

If a current figure does not exist, create one and return its handle.  The
handle may then be used to examine or set properties of the figure.  For
example,

@example
@group
fplot (@@sin, [-10, 10]);
fig = gcf ();
set (fig, "numbertitle", "off", "name", "sin plot")
@end group
@end example

@noindent
plots a sine wave, finds the handle of the current figure, and then
renames the figure window to describe the contents.

Note: To find the current figure without creating a new one if it does not
exist, query the @qcode{"CurrentFigure"} property of the root graphics
object.

@example
get (0, "currentfigure");
@end example

@seealso{gca, gco, gcbf, gcbo, get, set}
@end deftypefn
gco
@c gco scripts/plot/util/gco.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} gco ()
@deftypefnx {Function File} {@var{h} =} gco (@var{fig})
Return a handle to the current object of the current figure, or a handle
to the current object of the figure with handle @var{fig}.

The current object of a figure is the object that was last clicked on.  It
is stored in the @qcode{"CurrentObject"} property of the target figure.

If the last mouse click did not occur on any child object of the figure,
then the current object is the figure itself.

If no mouse click occurred in the target figure, this function returns an
empty matrix.

Programming Note: The value returned by this function is not necessarily the
same as the one returned by @code{gcbo} during callback execution.  An
executing callback can be interrupted by another callback and the current
object may be changed.

@seealso{gcbo, gca, gcf, gcbf, get, set}
@end deftypefn
ginput
@c ginput scripts/plot/util/ginput.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{x}, @var{y}, @var{buttons}] =} ginput (@var{n})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{buttons}] =} ginput ()
Return the position and type of mouse button clicks and/or key strokes
in the current figure window.

If @var{n} is defined, then capture @var{n} events before returning.
When @var{n} is not defined @code{ginput} will loop until the return key
@key{RET} is pressed.

The return values @var{x}, @var{y} are the coordinates where the mouse
was clicked in the units of the current axes.  The return value @var{button}
is 1, 2, or 3 for the left, middle, or right button.  If a key is pressed
the ASCII value is returned in @var{button}.

Implementation Note: @code{ginput} is intenteded for 2-D plots.  For 3-D
plots see the @var{currentpoint} property of the current axes which can be
transformed with knowledge of the current @code{view} into data units.
@seealso{gtext, waitforbuttonpress}
@end deftypefn
__gnuplot_drawnow__
@c __gnuplot_drawnow__ scripts/plot/util/__gnuplot_drawnow__.m
-*- texinfo -*-
@deftypefn {Function File} {} __gnuplot_drawnow__ (@var{h}, @var{term}, @var{file}, @var{mono}, @var{debug_file})
Undocumented internal function.
@end deftypefn
graphics_toolkit
@c graphics_toolkit scripts/plot/util/graphics_toolkit.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{name} =} graphics_toolkit ()
@deftypefnx {Function File} {@var{name} =} graphics_toolkit (@var{hlist})
@deftypefnx {Function File} {} graphics_toolkit (@var{name})
@deftypefnx {Function File} {} graphics_toolkit (@var{hlist}, @var{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, @var{hlist}, then return the name
of the graphics toolkit in use for each figure.

When called with a single input @var{name} set the default graphics toolkit
to @var{name}.  If the toolkit is not already loaded, it is initialized by
calling the function @code{__init_@var{name}__}.  If the first input
is a list of figure handles, @var{hlist}, then the graphics toolkit is set
to @var{name} for these figures only.

@seealso{available_graphics_toolkits}
@end deftypefn
hdl2struct
@c hdl2struct scripts/plot/util/hdl2struct.m
-*- texinfo -*-
@deftypefn {Function File} {@var{s} =} hdl2struct (@var{h})
Return a structure, @var{s}, whose fields describe the properties
of the object, and its children, associated with the handle, @var{h}.

The fields of the structure @var{s} are @qcode{"type"}, @qcode{"handle"},
@qcode{"properties"}, @qcode{"children"}, and @qcode{"special"}.
@seealso{struct2hdl, hgsave, findobj}
@end deftypefn
hggroup
@c hggroup scripts/plot/util/hggroup.m
-*- texinfo -*-
@deftypefn  {Function File} {} hggroup ()
@deftypefnx {Function File} {} hggroup (@var{hax})
@deftypefnx {Function File} {} hggroup (@dots{}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{h} =} hggroup (@dots{})
Create handle graphics group object with axes parent @var{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 optional return value @var{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, @code{set (hg_handle, "visible", "off")}.

@seealso{addproperty, addlistener}
@end deftypefn
hgload
@c hgload scripts/plot/util/hgload.m
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} hgload (@var{filename})
Load the graphics object in @var{filename} into the graphics handle @var{h}.

If @var{filename} has no extension, Octave will try to find the file with
and without the standard extension of @file{.ofig}.
@seealso{hgsave, struct2hdl}
@end deftypefn
hgsave
@c hgsave scripts/plot/util/hgsave.m
-*- texinfo -*-
@deftypefn  {Function File} {} hgsave (@var{filename})
@deftypefnx {Function File} {} hgsave (@var{h}, @var{filename})
@deftypefnx {Function File} {} hgsave (@var{h}, @var{filename}, @var{fmt})
Save the graphics handle @var{h} to the file @var{filename} in the format
@var{fmt}.

If unspecified, @var{h} is the current figure as returned by @code{gcf}.

When @var{filename} does not have an extension the default filename
extension @file{.ofig} will be appended.

If present, @var{fmt} should be one of the following:

@itemize @bullet
@item @option{-binary}, @option{-float-binary}

@item @option{-hdf5}, @option{-float-hdf5}

@item @option{-V7}, @option{-v7}, @code{-7}, @option{-mat7-binary}

@item @option{-V6}, @option{-v6}, @code{-6}, @option{-mat6-binary}

@item @option{-text}

@item @option{-zip}, @option{-z}
@end itemize

When producing graphics for final publication use @code{print} or
@code{saveas}.  When it is important to be able to continue to edit a
figure as an Octave object, use @code{hgsave}/@code{hgload}.
@seealso{hgload, hdl2struct, saveas, print}
@end deftypefn
hold
@c hold scripts/plot/util/hold.m
-*- texinfo -*-
@deftypefn  {Command} {} hold
@deftypefnx {Command} {} hold on
@deftypefnx {Command} {} hold off
@deftypefnx {Command} {} hold all
@deftypefnx {Function File} {} hold (@var{hax}, @dots{})
Toggle or set the @qcode{"hold"} state of the plotting engine which
determines whether new graphic objects are added to the plot or replace
the existing objects.

@table @code
@item hold on
Retain plot data and settings so that subsequent plot commands are displayed
on a single graph.

@item hold all
Retain plot line color, line style, data, and settings so that subsequent
plot commands are displayed on a single graph with the next line color and
style.

@item hold off
Restore default graphics settings which clear the graph and reset axis
properties before each new plot command.  (default).

@item hold
Toggle the current hold state.
@end table

When given the additional argument @var{hax}, the hold state is modified
for this axis rather than the current axes returned by @code{gca}.

To query the current hold state use the @code{ishold} function.
@seealso{ishold, cla, clf, newplot}
@end deftypefn
im2frame
@c im2frame scripts/plot/util/im2frame.m
-*- texinfo -*-
@deftypefn  {Function File} {} im2frame (@var{rgb})
@deftypefnx {Function File} {} im2frame (@var{x}, @var{map})
Convert image to movie frame.

A movie frame is simply a struct with the fields @qcode{"cdata"} and
@qcode{"colormap"}.

Support for N-dimensional images is given when each image projection,
matrix sizes of @nospell{MxN and MxNx3} for RGB images, is concatenated
along the fourth dimension.  In such cases, the returned value is a struct
array.

@seealso{frame2im}
@end deftypefn
isaxes
@c isaxes scripts/plot/util/isaxes.m
-*- texinfo -*-
@deftypefn {Function File} {} isaxes (@var{h})
Return true if @var{h} is an axes graphics handle and false otherwise.

If @var{h} is a matrix then return a logical array which is true where the
elements of @var{h} are axes graphics handles and false where they are not.
@seealso{isaxes, ishandle}
@end deftypefn
isfigure
@c isfigure scripts/plot/util/isfigure.m
-*- texinfo -*-
@deftypefn {Function File} {} isfigure (@var{h})
Return true if @var{h} is a figure graphics handle and false otherwise.

If @var{h} is a matrix then return a logical array which is true where the
elements of @var{h} are figure graphics handles and false where they are not.
@seealso{isaxes, ishandle}
@end deftypefn
ishghandle
@c ishghandle scripts/plot/util/ishghandle.m
-*- texinfo -*-
@deftypefn {Function File} {} ishghandle (@var{h})
Return true if @var{h} is a graphics handle and false otherwise.

This function is equivalent to @code{ishandle} and is provided for
compatibility with @sc{matlab}.
@seealso{ishandle}
@end deftypefn
ishold
@c ishold scripts/plot/util/ishold.m
-*- texinfo -*-
@deftypefn  {Command} {} ishold
@deftypefnx {Function File} {} ishold (@var{hax})
@deftypefnx {Function File} {} ishold (@var{hfig})
Return true if the next plot will be added to the current plot, or
false if the plot device will be cleared before drawing the next plot.

If the first argument is an axes handle @var{hax} or figure handle
@var{hfig} then operate on this plot rather than the current one.
@seealso{hold, newplot}
@end deftypefn
isprop
@c isprop scripts/plot/util/isprop.m
-*- texinfo -*-
@deftypefn {Function File} {@var{res} =} isprop (@var{obj}, "@var{prop}")
Return true if @var{prop} is a property of the object @var{obj}.

@var{obj} may also be an array of objects in which case @var{res} will be a
logical array indicating whether each handle has the property @var{prop}.

For plotting, @var{obj} is a handle to a graphics object.  Otherwise,
@var{obj} should be an instance of a class.
@seealso{get, set, ismethod, isobject}
@end deftypefn
linkaxes
@c linkaxes scripts/plot/util/linkaxes.m
-*- texinfo -*-
@deftypefn  {Function File} {} linkaxes (@var{hax})
@deftypefnx {Function File} {} linkaxes (@var{hax}, @var{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 @var{hax}.

The optional second argument is a string which defines which axis limits
will be linked.  The possible values for @var{optstr} are:

@table @asis
@item @qcode{"x"}
Link x-axes

@item @qcode{"y"}
Link y-axes

@item @qcode{"xy"} (default)
Link both axes

@item @qcode{"off"}
Turn off linking
@end table

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

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

@seealso{linkprop, addproperty}
@end deftypefn
linkprop
@c linkprop scripts/plot/util/linkprop.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{hlink} =} linkprop (@var{h}, "@var{prop}")
@deftypefnx {Function File} {@var{hlink} =} linkprop (@var{h}, @{"@var{prop1}", "@var{prop2}", @dots{}@})
Link graphic object properties, such that a change in one is propagated to
the others.

The input @var{h} is a vector of graphic handles to link.

@var{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 @var{prop} will initially be set to the values that exist on
the first object in the list @var{h}.

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

An example of the use of @code{linkprop} is

@example
@group
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", "--");
@end group
@end example

@seealso{linkaxes}
@end deftypefn
meshgrid
@c meshgrid scripts/plot/util/meshgrid.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{xx}, @var{yy}] =} meshgrid (@var{x}, @var{y})
@deftypefnx {Function File} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {[@var{xx}, @var{yy}] =} meshgrid (@var{x})
@deftypefnx {Function File} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x})
Given vectors of @var{x} and @var{y} coordinates, return matrices @var{xx}
and @var{yy} corresponding to a full 2-D grid.

The rows of @var{xx} are copies of @var{x}, and the columns of @var{yy} are
copies of @var{y}.  If @var{y} is omitted, then it is assumed to be the same
as @var{x}.

If the optional @var{z} input is given, or @var{zz} is requested, then the
output will be a full 3-D grid.

@code{meshgrid} is most frequently used to produce input for a 2-D or 3-D
function that will be plotted.  The following example creates a surface
plot of the ``sombrero'' function.

@example
@group
f = @@(x,y) sin (sqrt (x.^2 + y.^2)) ./ sqrt (x.^2 + y.^2);
range = linspace (-8, 8, 41);
[@var{X}, @var{Y}] = meshgrid (range, range);
Z = f (X, Y);
surf (X, Y, Z);
@end group
@end example

Programming Note: @code{meshgrid} is restricted to 2-D or 3-D grid
generation.  The @code{ndgrid} function will generate 1-D through N-D
grids.  However, the functions are not completely equivalent.  If @var{x}
is a vector of length M and @var{y} is a vector of length N, then
@code{meshgrid} will produce an output grid which is NxM@.  @code{ndgrid}
will produce an output which is @nospell{MxN} (transpose) for the same
input.  Some core functions expect @code{meshgrid} input and others expect
@code{ndgrid} input.  Check the documentation for the function in question
to determine the proper input format.
@seealso{ndgrid, mesh, contour, surf}
@end deftypefn
ndgrid
@c ndgrid scripts/plot/util/ndgrid.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{y1}, @var{y2}, @dots{}, @var{y}n] =} ndgrid (@var{x1}, @var{x2}, @dots{}, @var{x}n)
@deftypefnx {Function File} {[@var{y1}, @var{y2}, @dots{}, @var{y}n] =} ndgrid (@var{x})
Given n vectors @var{x1}, @dots{}, @var{x}n, @code{ndgrid} returns n
arrays of dimension n.

The elements of the i-th output argument contains the elements of the
vector @var{x}i repeated over all dimensions different from the i-th
dimension.  Calling ndgrid with only one input argument @var{x} is
equivalent to calling ndgrid with all n input arguments equal to @var{x}:

[@var{y1}, @var{y2}, @dots{}, @var{y}n] = ndgrid (@var{x}, @dots{}, @var{x})

Programming Note: @code{ndgrid} is very similar to the function
@code{meshgrid} except that the first two dimensions are transposed in
comparison to @code{meshgrid}.  Some core functions expect @code{meshgrid}
input and others expect @code{ndgrid} input.  Check the documentation for
the function in question to determine the proper input format.
@seealso{meshgrid}
@end deftypefn
newplot
@c newplot scripts/plot/util/newplot.m
-*- texinfo -*-
@deftypefn  {Function File} {} newplot ()
@deftypefnx {Function File} {} newplot (@var{hfig})
@deftypefnx {Function File} {} newplot (@var{hax})
@deftypefnx {Function File} {@var{hax} =} newplot (@dots{})
Prepare graphics engine to produce a new plot.

This function is called at the beginning of all high-level plotting
functions.  It is not normally required in user programs.  @code{newplot}
queries the @qcode{"NextPlot"} field of the current figure and axis to
determine what to do.

@multitable @columnfractions .25 .75
@headitem Figure NextPlot @tab Action
@item @qcode{"new"} @tab Create a new figure and make it the current figure.

@item @qcode{"add"} (default) @tab Add new graphic objects to the current
figure.

@item @qcode{"replacechildren"} @tab Delete child objects whose
HandleVisibility is set to @qcode{"on"}.  Set NextPlot property to
@qcode{"add"}.  This typically clears a figure, but leaves in place hidden
objects such as menubars.  This is equivalent to @code{clf}.

@item @qcode{"replace"} @tab Delete all child objects of the figure and
reset all figure properties to their defaults.  However, the following
four properties are not reset: Position, Units, PaperPosition, PaperUnits.
This is equivalent to @code{clf reset}.
@end multitable

@multitable @columnfractions .25 .75
@headitem Axis NextPlot @tab Action
@item @qcode{"add"} @tab Add new graphic objects to the current axes.  This
is equivalent to @code{hold on}.

@item @qcode{"replacechildren"} @tab Delete child objects whose
HandleVisibility is set to @qcode{"on"}, but leave axis properties
unmodified.  This typically clears a plot, but preserves special settings
such as log scaling for axes.  This is equivalent to @code{cla}.

@item @qcode{"replace"} (default) @tab Delete all child objects of the
axis and reset all axis properties to their defaults.  However, the
following properties are not reset: Position, Units.  This is equivalent
to @code{cla reset}.
@end multitable

If the optional input @var{hfig} or @var{hax} is given then prepare the
specified figure or axes rather than the current figure and axes.

The optional return value @var{hax} is a graphics handle to the created
axes object (not figure).

@strong{Caution:} Calling @code{newplot} may change the current figure and
current axis.
@end deftypefn
__next_line_color__
@c __next_line_color__ scripts/plot/util/__next_line_color__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{rgb} =} __next_line_color__ (@var{reset})
Undocumented internal function.
@end deftypefn
__next_line_style__
@c __next_line_style__ scripts/plot/util/__next_line_style__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{style} =} __next_line_style__ (@var{reset})
Undocumented internal function.
@end deftypefn
pan
@c pan scripts/plot/util/pan.m
-*- texinfo -*-
@deftypefn  {Command} {} pan
@deftypefnx {Command} {} pan on
@deftypefnx {Command} {} pan off
@deftypefnx {Command} {} pan xon
@deftypefnx {Command} {} pan yon
@deftypefnx {Function File} {} pan (@var{hfig}, @var{option})
Control the interactive panning mode of a figure in the GUI.

Given the option @qcode{"on"} or @qcode{"off"}, set the interactive
pan mode on or off.

With no arguments, toggle the current pan mode on or off.

Given the option @qcode{"xon"} or @qcode{"yon"}, enable pan mode
for the x or y axis only.

If the first argument @var{hfig} is a figure, then operate on the given
figure rather than the current figure as returned by @code{gcf}.

@seealso{rotate3d, zoom}
@end deftypefn
__plt_get_axis_arg__
@c __plt_get_axis_arg__ scripts/plot/util/__plt_get_axis_arg__.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{h}, @var{varargin}, @var{narg}] =} __plt_get_axis_arg__ (@var{caller}, @var{varargin})
Undocumented internal function.
@end deftypefn
__pltopt__
@c __pltopt__ scripts/plot/util/__pltopt__.m
-*- texinfo -*-
@deftypefn {Function File} {} __pltopt__ (@var{caller}, @var{opt})
Undocumented internal function.
@end deftypefn
printd
@c printd scripts/plot/util/printd.m
-*- texinfo -*-
@deftypefn  {Function File} {} printd (@var{obj}, @var{filename})
@deftypefnx {Function File} {@var{out_file} =} printd (@dots{})

Convert any object acceptable to @code{disp} into the format selected by
the suffix of @var{filename}.

If the return argument @var{out_file} is given, the name of the created
file is returned.

This function is intended to facilitate manipulation of the output of
functions such as @code{stemleaf}.
@seealso{stemleaf}
@end deftypefn
print
@c print scripts/plot/util/print.m
-*- texinfo -*-
@deftypefn  {Function File} {} print ()
@deftypefnx {Function File} {} print (@var{options})
@deftypefnx {Function File} {} print (@var{filename}, @var{options})
@deftypefnx {Function File} {} print (@var{h}, @var{filename}, @var{options})
Print a plot, or save it to a file.

Both output formatted for printing (PDF and PostScript), and many bitmapped
and vector image formats are supported.

@var{filename} defines the name of the output file.  If the file name has
no suffix, one is inferred from the specified device and appended to the
file name.  If no filename is specified, the output is sent to the
printer.

@var{h} specifies the handle of the figure to print.  If no handle is
specified the current figure is used.

For output to a printer, PostScript file, or PDF file, the paper size is
specified by the figure's @code{papersize} property.  The location and
size of the image on the page are specified by the figure's
@code{paperposition} property.  The orientation of the page is specified
by the figure's @code{paperorientation} property.

The width and height of images are specified by the figure's
@code{paperpositon(3:4)} property values.

The @code{print} command supports many @var{options}:

@table @code
@item -f@var{h}
  Specify the handle, @var{h}, of the figure to be printed.  The default
is the current figure.

@item -P@var{printer}
  Set the @var{printer} name to which the plot is sent if no
@var{filename} is specified.

@item -G@var{ghostscript_command}
  Specify the command for calling Ghostscript.  For Unix and Windows the
defaults are @qcode{"gs"} and @qcode{"gswin32c"}, respectively.

@item  -color
@itemx -mono
  Color or monochrome output.

@item  -solid
@itemx -dashed
  Force all lines to be solid or dashed, respectively.

@item  -portrait
@itemx -landscape
  Specify the orientation of the plot for printed output.
For non-printed output the aspect ratio of the output corresponds to the
plot area defined by the @qcode{"paperposition"} property in the
orientation specified.  This option is equivalent to changing the figure's
@qcode{"paperorientation"} property.

@item  -TextAlphaBits=@var{n}
@itemx -GraphicsAlphaBits=@var{n}
  Octave is able to produce output for various printers, bitmaps, and
vector formats by using Ghostscript.  For bitmap and printer output
anti-aliasing is applied using Ghostscript's TextAlphaBits and
GraphicsAlphaBits options.  The default number of bits for each is 4.
Allowed values for @var{N} are 1, 2, or 4.

@item -d@var{device}
  The available output format is specified by the option @var{device}, and
is one of:

@table @code
@item  ps
@itemx ps2
@itemx psc
@itemx psc2
    PostScript (level 1 and 2, mono and color).  The FLTK graphics
toolkit generates PostScript level 3.0.

@item  eps
@itemx eps2
@itemx epsc
@itemx epsc2
    Encapsulated PostScript (level 1 and 2, mono and color).  The FLTK
graphic toolkit generates PostScript level 3.0.

@item  pslatex
@itemx epslatex
@itemx pdflatex
@itemx pslatexstandalone
@itemx epslatexstandalone
@itemx pdflatexstandalone
    Generate a @LaTeX{} file @file{@var{filename}.tex} for the text
portions of a plot and a file @file{@var{filename}.(ps|eps|pdf)} for the
remaining graphics.  The graphics file suffix .ps|eps|pdf is determined
by the specified device type.  The @LaTeX{} file produced by the
@samp{standalone} option can be processed directly by @LaTeX{}.  The file
generated without the @samp{standalone} option is intended to be included
from another @LaTeX{} document.  In either case, the @LaTeX{} file
contains an @code{\includegraphics} command so that the generated graphics
file is automatically included when the @LaTeX{} file is processed.  The
text that is written to the @LaTeX{} file contains the strings
@strong{exactly} as they were specified in the plot.  If any special
characters of the @TeX{} mode interpreter were used, the file must be
edited before @LaTeX{} processing.  Specifically, the special characters
must be enclosed with dollar signs (@code{$ @dots{} $}), and other
characters that are recognized by @LaTeX{} may also need editing (.e.g.,
braces).  The @samp{pdflatex} device, and any of the @samp{standalone}
formats, are not available with the Gnuplot toolkit.

@item tikz
    Generate a @LaTeX{} file using PGF/TikZ@.  For the FLTK toolkit
the result is PGF.

@item  ill
@itemx aifm
    Adobe Illustrator (Obsolete for Gnuplot versions > 4.2)

@item  cdr
@itemx @nospell{corel}
    CorelDraw

@item dxf
    AutoCAD

@item  emf
@itemx meta
    Microsoft Enhanced Metafile

@item fig
    XFig.  For the Gnuplot graphics toolkit, the additional options
@option{-textspecial} or @option{-textnormal} can be used to control whether the special flag should be set for the text in the figure.  (default is @option{-textnormal})

@item hpgl
    HP plotter language

@item mf
    Metafont

@item png
    Portable network graphics

@item  jpg
@itemx jpeg
    JPEG image

@item gif
    GIF image (only available for the Gnuplot graphics toolkit)

@item pbm
    PBMplus

@item svg
    Scalable vector graphics

@item pdf
    Portable document format
@end table

  If the device is omitted, it is inferred from the file extension,
or if there is no filename it is sent to the printer as PostScript.

@item -d@var{ghostscript_device}
  Additional devices are supported by Ghostscript.
Some examples are;

@table @code
@item pdfwrite
    Produces pdf output from eps

@item ljet2p
    HP LaserJet @nospell{IIP}

@item pcx24b
    24-bit color PCX file format

@item ppm
    Portable Pixel Map file format
@end table

  For a complete list, type @code{system ("gs -h")} to see what formats
and devices are available.

  When Ghostscript output is sent to a printer the size is determined by
the figure's @qcode{"papersize"} property.  When the output is sent to a
file the size is determined by the plot box defined by the figure's
@qcode{"paperposition"} property.

@item -append
  Append PostScript or PDF output to a pre-existing file of the same type.

@item -r@var{NUM}
  Resolution of bitmaps in pixels per inch.  For both metafiles and SVG
the default is the screen resolution; for other formats it is 150 dpi.  To
specify screen resolution, use @qcode{"-r0"}.

@item  -loose
@itemx -tight
  Force a tight or loose bounding box for eps files.  The default is loose.

@item -@var{preview}
  Add a preview to eps files.  Supported formats are:

@table @code
@item -interchange
    Provide an interchange preview.

@item -metafile
    Provide a metafile preview.

@item -pict
    Provide pict preview.

@item -tiff
    Provide a tiff preview.
@end table

@item -S@var{xsize},@var{ysize}
  Plot size in pixels for EMF, GIF, JPEG, PBM, PNG, and SVG@.
For PS, EPS, PDF, and other vector formats the plot size is in points.
This option is equivalent to changing the size of the plot box associated
with the @qcode{"paperposition"} property.  When using the command form of
the print function you must quote the @var{xsize},@var{ysize} option.  For
example, by writing @w{"-S640,480"}.

@item  -F@var{fontname}
@itemx -F@var{fontname}:@var{size}
@itemx -F:@var{size}
  Use @var{fontname} and/or @var{fontsize} for all text.
@var{fontname} is ignored for some devices: dxf, fig, hpgl, etc.
@end table

The filename and options can be given in any order.

Example: Print to a file using the pdf device.

@example
@group
figure (1);
clf ();
surf (peaks);
print figure1.pdf
@end group
@end example

Example: Print to a file using jpg device.

@example
@group
clf ();
surf (peaks);
print -djpg figure2.jpg
@end group
@end example

Example: Print to printer named PS_printer using ps format.

@example
@group
clf ();
surf (peaks);
print -dpswrite -PPS_printer
@end group
@end example

@seealso{saveas, hgsave, orient, figure}
@end deftypefn
refreshdata
@c refreshdata scripts/plot/util/refreshdata.m
-*- texinfo -*-
@deftypefn  {Function File} {} refreshdata ()
@deftypefnx {Function File} {} refreshdata (@var{h})
@deftypefnx {Function File} {} refreshdata (@var{h}, @var{workspace})
Evaluate any @samp{datasource} properties of the current figure and update
the plot if the corresponding data has changed.

If the first argument @var{h} is a list of graphic handles, then operate
on these objects rather than the current figure returned by @code{gcf}.

The optional second argument @var{workspace} can take the following values:

@table @asis
@item @qcode{"base"}
Evaluate the datasource properties in the base workspace.  (default).

@item @qcode{"caller"}
Evaluate the datasource properties in the workspace of the function
that called @code{refreshdata}.
@end table

An example of the use of @code{refreshdata} is:

@example
@group
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
@end group
@end example
@end deftypefn
refresh
@c refresh scripts/plot/util/refresh.m
-*- texinfo -*-
@deftypefn  {Function File} {} refresh ()
@deftypefnx {Function File} {} refresh (@var{h})
Refresh a figure, forcing it to be redrawn.

When called without an argument the current figure is redrawn.  Otherwise,
the figure with graphic handle @var{h} is redrawn.
@seealso{drawnow}
@end deftypefn
rotate
@c rotate scripts/plot/util/rotate.m
-*- texinfo -*-
@deftypefn  {Function File} {} rotate (@var{h}, @var{dir}, @var{alpha})
@deftypefnx {Function File} {} rotate (@dots{}, @var{origin})
Rotate the plot object @var{h} through @var{alpha} degrees around the line
with direction @var{dir} and origin @var{origin}.

The default value of @var{origin} is the center of the axes object that is
the parent of @var{h}.

If @var{h} is a vector of handles, they must all have the same parent axes
object.

Graphics objects that may be rotated are lines, surfaces, patches, and
images.
@end deftypefn
rotate3d
@c rotate3d scripts/plot/util/rotate3d.m
-*- texinfo -*-
@deftypefn  {Command} {} rotate3d
@deftypefnx {Command} {} rotate3d on
@deftypefnx {Command} {} rotate3d off
@deftypefnx {Function File} {} rotate3d (@var{hfig}, @var{option})
Control the interactive 3-D rotation mode of a figure in the GUI.

Given the option @qcode{"on"} or @qcode{"off"}, set the interactive
rotate mode on or off.

With no arguments, toggle the current rotate mode on or off.

If the first argument @var{hfig} is a figure, then operate on the given
figure rather than the current figure as returned by @code{gcf}.

@seealso{pan, zoom}
@end deftypefn
saveas
@c saveas scripts/plot/util/saveas.m
-*- texinfo -*-
@deftypefn  {Function File} {} saveas (@var{h}, @var{filename})
@deftypefnx {Function File} {} saveas (@var{h}, @var{filename}, @var{fmt})
Save graphic object @var{h} to the file @var{filename} in graphic format
@var{fmt}.

@var{fmt} should be one of the following formats:

@table @code
@item ps
    PostScript

@item eps
    Encapsulated PostScript

@item jpg
    JPEG Image

@item png
    PNG Image

@item emf
    Enhanced Meta File

@item pdf
    Portable Document Format
@end table

All device formats specified in @code{print} may also be used.  If
@var{fmt} is omitted it is extracted from the extension of @var{filename}.
The default format is @qcode{"pdf"}.

@example
@group
clf ();
surf (peaks);
saveas (1, "figure1.png");
@end group
@end example

@seealso{print, hgsave, orient}
@end deftypefn
shg
@c shg scripts/plot/util/shg.m
-*- texinfo -*-
@deftypefn {Command} {} shg
Show the graph window.

Currently, this is the same as executing @code{drawnow}.
@seealso{drawnow, figure}
@end deftypefn
struct2hdl
@c struct2hdl scripts/plot/util/struct2hdl.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} struct2hdl (@var{s})
@deftypefnx {Function File} {@var{h} =} struct2hdl (@var{s}, @var{p})
@deftypefnx {Function File} {@var{h} =} struct2hdl (@var{s}, @var{p}, @var{hilev})
Construct a graphics handle object @var{h} from the structure @var{s}.

The structure must contain the fields @qcode{"handle"}, @qcode{"type"},
@qcode{"children"}, @qcode{"properties"}, and @qcode{"special"}.

If the handle of an existing figure or axes is specified, @var{p}, the new
object will be created as a child of that object.  If no parent handle is
provided then a new figure and the necessary children will be constructed
using the default values from the root figure.

A third boolean argument @var{hilev} can be passed to specify whether the
function should preserve listeners/callbacks, e.g., for legends or
hggroups.  The default is false.
@seealso{hdl2struct, hgload, findobj}
@end deftypefn
subplot
@c subplot scripts/plot/util/subplot.m
-*- texinfo -*-
@deftypefn  {Function File} {} subplot (@var{rows}, @var{cols}, @var{index})
@deftypefnx {Function File} {} subplot (@var{rcn})
@deftypefnx {Function File} {} subplot (@var{hax})
@deftypefnx {Function File} {} subplot (@dots{}, "align")
@deftypefnx {Function File} {} subplot (@dots{}, "replace")
@deftypefnx {Function File} {} subplot (@dots{}, "position", @var{pos})
@deftypefnx {Function File} {} subplot (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{hax} =} subplot (@dots{})
Set up a plot grid with @var{rows} by @var{cols} subwindows and set the
current axes for plotting (@code{gca}) to the location given by @var{index}.

If only one numeric argument is supplied, then it must be a three digit
value specifying the number of rows in digit 1, the number of columns in
digit 2, and the plot index in digit 3.

The plot index runs row-wise; First, all columns in a row are numbered
and then the next row is filled.

For example, a plot with 2x3 grid will have plot indices running as follows:
@tex
\vskip 10pt
\hfil\vbox{\offinterlineskip\hrule
\halign{\vrule#&&\qquad\hfil#\hfil\qquad\vrule\cr
height13pt&1&2&3\cr height12pt&&&\cr\noalign{\hrule}
height13pt&4&5&6\cr height12pt&&&\cr\noalign{\hrule}}}
\hfil
\vskip 10pt
@end tex
@ifnottex

@example
@group
+-----+-----+-----+
|  1  |  2  |  3  |
+-----+-----+-----+
|  4  |  5  |  6  |
+-----+-----+-----+
@end group
@end example

@end ifnottex

@var{index} may also be a vector.  In this case, the new axis will enclose
the grid locations specified.  The first demo illustrates this:

@example
demo ("subplot", 1)
@end example

The index of the subplot to make active may also be specified by its axes
handle, @var{hax}, returned from a previous @code{subplot} command.

If the option @qcode{"align"} is given then the plot boxes of the subwindows
will align, but this may leave no room for axis tick marks or labels.

If the option @qcode{"replace"} is given then the subplot axis will be
reset, rather than just switching the current axis for plotting to the
requested subplot.

The @qcode{"position"} property can be used to exactly position the subplot
axes within the current figure.  The option @var{pos} is a 4-element vector
[x, y, width, height] that determines the location and size of the axes.
The values in @var{pos} are normalized in the range [0,1].

Any property/value pairs are passed directly to the underlying axes object.

If the output @var{hax} is requested, subplot returns the axis handle for
the subplot.  This is useful for modifying the properties of a subplot
using @code{set}.
@seealso{axes, plot, gca, set}
@end deftypefn
zoom
@c zoom scripts/plot/util/zoom.m
-*- texinfo -*-
@deftypefn  {Command} {} zoom
@deftypefnx {Command} {} zoom (@var{factor})
@deftypefnx {Command} {} zoom on
@deftypefnx {Command} {} zoom off
@deftypefnx {Command} {} zoom xon
@deftypefnx {Command} {} zoom yon
@deftypefnx {Command} {} zoom out
@deftypefnx {Command} {} zoom reset
@deftypefnx {Command} {} zoom (@var{hfig}, @var{option})
Zoom the current axes object or control the interactive zoom mode of a
figure in the GUI.

Given a numeric argument greater than zero, zoom by the given factor.  If
the zoom factor is greater than one, zoom in on the plot.  If the factor
is less than one, zoom out.  If the zoom factor is a two- or three-element
vector, then the elements specify the zoom factors for the x, y, and z
axes respectively.

Given the option @qcode{"on"} or @qcode{"off"}, set the interactive zoom
mode on or off.

With no arguments, toggle the current zoom mode on or off.

Given the option @qcode{"xon"} or @qcode{"yon"}, enable zoom mode for the
x or y-axis only.

Given the option @qcode{"out"}, zoom to the initial zoom setting.

Given the option @qcode{"reset"}, store the current zoom setting so that
@code{zoom out} will return to this zoom level.

If the first argument @var{hfig} is a figure, then operate on the given
figure rather than the current figure as returned by @code{gcf}.

@seealso{pan, rotate3d}
@end deftypefn
compan
@c compan scripts/polynomial/compan.m
-*- texinfo -*-
@deftypefn {Function File} {} compan (@var{c})
Compute the companion matrix corresponding to polynomial coefficient vector
@var{c}.

The companion matrix is
@tex
$$
A = \left[\matrix{
 -c_2/c_1 & -c_3/c_1 & \cdots & -c_N/c_1 & -c_{N+1}/c_1\cr
     1    &     0    & \cdots &     0    &         0   \cr
     0    &     1    & \cdots &     0    &         0   \cr
  \vdots  &   \vdots & \ddots &  \vdots  &      \vdots \cr
     0    &     0    & \cdots &     1    &         0}\right].
$$
@end tex
@ifnottex
@c Set example in small font to prevent overfull line

@smallexample
@group
     _                                                        _
    |  -c(2)/c(1)   -c(3)/c(1)  @dots{}  -c(N)/c(1)  -c(N+1)/c(1)  |
    |       1            0      @dots{}       0             0      |
    |       0            1      @dots{}       0             0      |
A = |       .            .      .         .             .      |
    |       .            .       .        .             .      |
    |       .            .        .       .             .      |
    |_      0            0      @dots{}       1             0     _|
@end group
@end smallexample

@end ifnottex
The eigenvalues of the companion matrix are equal to the roots of the
polynomial.
@seealso{roots, poly, eig}
@end deftypefn
conv
@c conv scripts/polynomial/conv.m
-*- texinfo -*-
@deftypefn  {Function File} {} conv (@var{a}, @var{b})
@deftypefnx {Function File} {} conv (@var{a}, @var{b}, @var{shape})
Convolve two vectors @var{a} and @var{b}.

The output convolution is a vector with length equal to
@code{length (@var{a}) + length (@var{b}) - 1}.
When @var{a} and @var{b} are the coefficient vectors of two polynomials, the
convolution represents the coefficient vector of the product polynomial.

The optional @var{shape} argument may be

@table @asis
@item @var{shape} = @qcode{"full"}
Return the full convolution.  (default)

@item @var{shape} = @qcode{"same"}
Return the central part of the convolution with the same size as @var{a}.
@end table

@seealso{deconv, conv2, convn, fftconv}
@end deftypefn
deconv
@c deconv scripts/polynomial/deconv.m
-*- texinfo -*-
@deftypefn {Function File} {} deconv (@var{y}, @var{a})
Deconvolve two vectors.

@code{[b, r] = deconv (y, a)} solves for @var{b} and @var{r} such that
@code{y = conv (a, b) + r}.

If @var{y} and @var{a} are polynomial coefficient vectors, @var{b} will
contain the coefficients of the polynomial quotient and @var{r} will be
a remainder polynomial of lowest order.
@seealso{conv, residue}
@end deftypefn
mkpp
@c mkpp scripts/polynomial/mkpp.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{pp} =} mkpp (@var{breaks}, @var{coefs})
@deftypefnx {Function File} {@var{pp} =} mkpp (@var{breaks}, @var{coefs}, @var{d})

Construct a piecewise polynomial (pp) structure from sample points
@var{breaks} and coefficients @var{coefs}.

@var{breaks} must be a vector of strictly increasing values.  The number of
intervals is given by @code{@var{ni} = length (@var{breaks}) - 1}.

When @var{m} is the polynomial order @var{coefs} must be of size:
@var{ni} x @var{m} + 1.

The i-th row of @var{coefs}, @code{@var{coefs} (@var{i},:)}, contains the
coefficients for the polynomial over the @var{i}-th interval, ordered from
highest (@var{m}) to lowest (@var{0}).

@var{coefs} may also be a multi-dimensional array, specifying a vector-valued
or array-valued polynomial.  In that case the polynomial order is defined
by the length of the last dimension of @var{coefs}.  The size of first
dimension(s) are given by the scalar or vector @var{d}.  If @var{d} is not
given it is set to @code{1}.  In any case @var{coefs} is reshaped to a 2-D
matrix of size @code{[@var{ni}*prod(@var{d} @var{m})] }

@seealso{unmkpp, ppval, spline, pchip, ppder, ppint, ppjumps}
@end deftypefn
mpoles
@c mpoles scripts/polynomial/mpoles.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{multp}, @var{idxp}] =} mpoles (@var{p})
@deftypefnx {Function File} {[@var{multp}, @var{idxp}] =} mpoles (@var{p}, @var{tol})
@deftypefnx {Function File} {[@var{multp}, @var{idxp}] =} mpoles (@var{p}, @var{tol}, @var{reorder})
Identify unique poles in @var{p} and their associated multiplicity.

The output is ordered from largest pole to smallest pole.

If the relative difference of two poles is less than @var{tol} then they are
considered to be multiples.  The default value for @var{tol} is 0.001.

If the optional parameter @var{reorder} is zero, poles are not sorted.

The output @var{multp} is a vector specifying the multiplicity of the poles.
@code{@var{multp}(n)} refers to the multiplicity of the Nth pole
@code{@var{p}(@var{idxp}(n))}.

For example:

@example
@group
p = [2 3 1 1 2];
[m, n] = mpoles (p)
   @result{} m = [1; 1; 2; 1; 2]
   @result{} n = [2; 5; 1; 4; 3]
   @result{} p(n) = [3, 2, 2, 1, 1]
@end group
@end example

@seealso{residue, poly, roots, conv, deconv}
@end deftypefn
pchip
@c pchip scripts/polynomial/pchip.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{pp} =} pchip (@var{x}, @var{y})
@deftypefnx {Function File} {@var{yi} =} pchip (@var{x}, @var{y}, @var{xi})
Return the Piecewise Cubic Hermite Interpolating Polynomial (pchip) of
points @var{x} and @var{y}.

If called with two arguments, return the piecewise polynomial @var{pp}
that may be used with @code{ppval} to evaluate the polynomial at specific
points.

When called with a third input argument, @code{pchip} evaluates the pchip
polynomial at the points @var{xi}.  The third calling form is equivalent to
@code{ppval (pchip (@var{x}, @var{y}), @var{xi})}.

The variable @var{x} must be a strictly monotonic vector (either increasing
or decreasing) of length @var{n}.

@var{y} can be either a vector or array.  If @var{y} is a vector then it
must be the same length @var{n} as @var{x}.  If @var{y} is an array then
the size of @var{y} must have the form
@tex
$$[s_1, s_2, \cdots, s_k, n]$$
@end tex
@ifnottex
@code{[@var{s1}, @var{s2}, @dots{}, @var{sk}, @var{n}]}
@end ifnottex
The array is reshaped internally to a matrix where the leading dimension is
given by
@tex
$$s_1 s_2 \cdots s_k$$
@end tex
@ifnottex
@code{@var{s1} * @var{s2} * @dots{} * @var{sk}}
@end ifnottex
and each row of this matrix is then treated separately.  Note that this is
exactly opposite to @code{interp1} but is done for @sc{matlab} compatibility.

@seealso{spline, ppval, mkpp, unmkpp}
@end deftypefn
poly
@c poly scripts/polynomial/poly.m
-*- texinfo -*-
@deftypefn  {Function File} {} poly (@var{A})
@deftypefnx {Function File} {} poly (@var{x})
If @var{A} is a square @math{N}-by-@math{N} matrix, @code{poly (@var{A})}
is the row vector of the coefficients of @code{det (z * eye (N) - A)},
the characteristic polynomial of @var{A}.

For example, the following code finds the eigenvalues of @var{A} which are
the roots of @code{poly (@var{A})}.

@example
@group
roots (poly (eye (3)))
    @result{} 1.00001 + 0.00001i
       1.00001 - 0.00001i
       0.99999 + 0.00000i
@end group
@end example

In fact, all three eigenvalues are exactly 1 which emphasizes that for
numerical performance the @code{eig} function should be used to compute
eigenvalues.

If @var{x} is a vector, @code{poly (@var{x})} is a vector of the
coefficients of the polynomial whose roots are the elements of @var{x}.
That is, if @var{c} is a polynomial, then the elements of
@code{@var{d} = roots (poly (@var{c}))} are contained in @var{c}.  The
vectors @var{c} and @var{d} are not identical, however, due to sorting and
numerical errors.
@seealso{roots, eig}
@end deftypefn
polyaffine
@c polyaffine scripts/polynomial/polyaffine.m
-*- texinfo -*-
@deftypefn {Function File} {} polyaffine (@var{f}, @var{mu})
Return the coefficients of the polynomial vector @var{f} after an affine
transformation.

If @var{f} is the vector representing the polynomial f(x), then
@code{@var{g} = polyaffine (@var{f}, @var{mu})} is the vector representing:

@example
g(x) = f( (x - @var{mu}(1)) / @var{mu}(2) )
@end example

@seealso{polyval, polyfit}
@end deftypefn
polyder
@c polyder scripts/polynomial/polyder.m
-*- texinfo -*-
@deftypefn  {Function File} {} polyder (@var{p})
@deftypefnx {Function File} {[@var{k}] =} polyder (@var{a}, @var{b})
@deftypefnx {Function File} {[@var{q}, @var{d}] =} polyder (@var{b}, @var{a})
Return the coefficients of the derivative of the polynomial whose
coefficients are given by the vector @var{p}.

If a pair of polynomials is given, return the derivative of the product
@math{@var{a}*@var{b}}.

If two inputs and two outputs are given, return the derivative of the
polynomial quotient @math{@var{b}/@var{a}}.  The quotient numerator is
in @var{q} and the denominator in @var{d}.
@seealso{polyint, polyval, polyreduce}
@end deftypefn
polyeig
@c polyeig scripts/polynomial/polyeig.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{z} =} polyeig (@var{C0}, @var{C1}, @dots{}, @var{Cl})
@deftypefnx {Function File} {[@var{v}, @var{z}] =} polyeig (@var{C0}, @var{C1}, @dots{}, @var{Cl})

Solve the polynomial eigenvalue problem of degree @var{l}.

Given an @var{n*n} matrix polynomial

@code{@var{C}(s) = @var{C0} + @var{C1} s + @dots{} + @var{Cl} s^l}

@code{polyeig} solves the eigenvalue problem

@code{(@var{C0} + @var{C1} + @dots{} + @var{Cl})v = 0}.

Note that the eigenvalues @var{z} are the zeros of the matrix polynomial.
@var{z} is a row vector with @var{n*l} elements.  @var{v} is a matrix
(@var{n} x @var{n}*@var{l}) with columns that correspond to the
eigenvectors.

@seealso{eig, eigs, compan}
@end deftypefn
polyfit
@c polyfit scripts/polynomial/polyfit.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{p} =} polyfit (@var{x}, @var{y}, @var{n})
@deftypefnx {Function File} {[@var{p}, @var{s}] =} polyfit (@var{x}, @var{y}, @var{n})
@deftypefnx {Function File} {[@var{p}, @var{s}, @var{mu}] =} polyfit (@var{x}, @var{y}, @var{n})
Return the coefficients of a polynomial @var{p}(@var{x}) of degree
@var{n} that minimizes the least-squares-error of the fit to the points
@code{[@var{x}, @var{y}]}.

If @var{n} is a logical vector, it is used as a mask to selectively force
the corresponding polynomial coefficients to be used or ignored.

The polynomial coefficients are returned in a row vector.

The optional output @var{s} is a structure containing the following fields:

@table @samp
@item R
Triangular factor R from the QR@tie{}decomposition.

@item X
The Vandermonde matrix used to compute the polynomial coefficients.

@item C
The unscaled covariance matrix, formally equal to the inverse of
@var{x'}*@var{x}, but computed in a way minimizing roundoff error
propagation.

@item df
The degrees of freedom.

@item normr
The norm of the residuals.

@item yf
The values of the polynomial for each value of @var{x}.
@end table

The second output may be used by @code{polyval} to calculate the
statistical error limits of the predicted values.  In particular, the
standard deviation of @var{p} coefficients is given by

@code{sqrt (diag (s.C)/s.df)*s.normr}.

When the third output, @var{mu}, is present the coefficients, @var{p}, are
associated with a polynomial in

@code{@var{xhat} = (@var{x} - @var{mu}(1)) / @var{mu}(2)} @*
where @var{mu}(1) = mean (@var{x}), and @var{mu}(2) = std (@var{x}).

This linear transformation of @var{x} improves the numerical stability of
the fit.
@seealso{polyval, polyaffine, roots, vander, zscore}
@end deftypefn
polygcd
@c polygcd scripts/polynomial/polygcd.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{q} =} polygcd (@var{b}, @var{a})
@deftypefnx {Function File} {@var{q} =} polygcd (@var{b}, @var{a}, @var{tol})

Find the greatest common divisor of two polynomials.

This is equivalent to the polynomial found by multiplying together all the
common roots.  Together with deconv, you can reduce a ratio of two
polynomials.

The tolerance @var{tol} defaults to @code{sqrt (eps)}.

@strong{Caution:} This is a numerically unstable algorithm and should not
be used on large polynomials.

Example code:

@example
@group
polygcd (poly (1:8), poly (3:12)) - poly (3:8)
@result{} [ 0, 0, 0, 0, 0, 0, 0 ]
deconv (poly (1:8), polygcd (poly (1:8), poly (3:12))) - poly (1:2)
@result{} [ 0, 0, 0 ]
@end group
@end example
@seealso{poly, roots, conv, deconv, residue}
@end deftypefn
polyint
@c polyint scripts/polynomial/polyint.m
-*- texinfo -*-
@deftypefn  {Function File} {} polyint (@var{p})
@deftypefnx {Function File} {} polyint (@var{p}, @var{k})
Return the coefficients of the integral of the polynomial whose
coefficients are represented by the vector @var{p}.

The variable @var{k} is the constant of integration, which by default is
set to zero.
@seealso{polyder, polyval}
@end deftypefn
polyout
@c polyout scripts/polynomial/polyout.m
-*- texinfo -*-
@deftypefn  {Function File} {} polyout (@var{c})
@deftypefnx {Function File} {} polyout (@var{c}, @var{x})
@deftypefnx {Function File} {@var{str} =} polyout (@dots{})
Display a formatted version of the polynomial @var{c}.

The formatted polynomial
@tex
$$ c(x) = c_1 x^n + \ldots + c_n x + c_{n+1} $$
@end tex
@ifnottex

@example
c(x) = c(1) * x^n + @dots{} + c(n) x + c(n+1)
@end example

@end ifnottex
is returned as a string or written to the screen if @code{nargout} is zero.

The second argument @var{x} specifies the variable name to use for each term
and defaults to the string @qcode{"s"}.
@seealso{polyreduce}
@end deftypefn
polyreduce
@c polyreduce scripts/polynomial/polyreduce.m
-*- texinfo -*-
@deftypefn {Function File} {} polyreduce (@var{c})
Reduce a polynomial coefficient vector to a minimum number of terms by
stripping off any leading zeros.
@seealso{polyout}
@end deftypefn
polyval
@c polyval scripts/polynomial/polyval.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{y} =} polyval (@var{p}, @var{x})
@deftypefnx {Function File} {@var{y} =} polyval (@var{p}, @var{x}, [], @var{mu})
@deftypefnx {Function File} {[@var{y}, @var{dy}] =} polyval (@var{p}, @var{x}, @var{s})
@deftypefnx {Function File} {[@var{y}, @var{dy}] =} polyval (@var{p}, @var{x}, @var{s}, @var{mu})

Evaluate the polynomial @var{p} at the specified values of @var{x}.

If @var{x} is a vector or matrix, the polynomial is evaluated for each of
the elements of @var{x}.

When @var{mu} is present, evaluate the polynomial for
(@var{x}-@var{mu}(1))/@var{mu}(2).

In addition to evaluating the polynomial, the second output represents the
prediction interval, @var{y} +/- @var{dy}, which contains at least 50% of
the future predictions.  To calculate the prediction interval, the
structured variable @var{s}, originating from @code{polyfit}, must be
supplied.

@seealso{polyvalm, polyaffine, polyfit, roots, poly}
@end deftypefn
polyvalm
@c polyvalm scripts/polynomial/polyvalm.m
-*- texinfo -*-
@deftypefn {Function File} {} polyvalm (@var{c}, @var{x})
Evaluate a polynomial in the matrix sense.

@code{polyvalm (@var{c}, @var{x})} will evaluate the polynomial in the
matrix sense, i.e., matrix multiplication is used instead of element by
element multiplication as used in @code{polyval}.

The argument @var{x} must be a square matrix.
@seealso{polyval, roots, poly}
@end deftypefn
ppval
@c ppval scripts/polynomial/ppval.m
-*- texinfo -*-
@deftypefn {Function File} {@var{yi} =} ppval (@var{pp}, @var{xi})
Evaluate the piecewise polynomial structure @var{pp} at the points @var{xi}.

If @var{pp} describes a scalar polynomial function, the result is an array
of the same shape as @var{xi}.  Otherwise, the size of the result is
@code{[pp.dim, length(@var{xi})]} if @var{xi} is a vector, or
@code{[pp.dim, size(@var{xi})]} if it is a multi-dimensional array.
@seealso{mkpp, unmkpp, spline, pchip}
@end deftypefn
ppder
@c ppder scripts/polynomial/ppder.m
-*- texinfo -*-
@deftypefn  {Function File} {ppd =} ppder (pp)
@deftypefnx {Function File} {ppd =} ppder (pp, m)
Compute the piecewise @var{m}-th derivative of a piecewise polynomial
struct @var{pp}.

If @var{m} is omitted the first derivative is calculated.
@seealso{mkpp, ppval, ppint}
@end deftypefn
ppint
@c ppint scripts/polynomial/ppint.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{ppi} =} ppint (@var{pp})
@deftypefnx {Function File} {@var{ppi} =} ppint (@var{pp}, @var{c})
Compute the integral of the piecewise polynomial struct @var{pp}.

@var{c}, if given, is the constant of integration.
@seealso{mkpp, ppval, ppder}
@end deftypefn
ppjumps
@c ppjumps scripts/polynomial/ppjumps.m
-*- texinfo -*-
@deftypefn {Function File} {@var{jumps} =} ppjumps (@var{pp})
Evaluate the boundary jumps of a piecewise polynomial.

If there are @math{n} intervals, and the dimensionality of @var{pp} is
@math{d}, the resulting array has dimensions @code{[d, n-1]}.
@seealso{mkpp}
@end deftypefn
residue
@c residue scripts/polynomial/residue.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{r}, @var{p}, @var{k}, @var{e}] =} residue (@var{b}, @var{a})
@deftypefnx {Function File} {[@var{b}, @var{a}] =} residue (@var{r}, @var{p}, @var{k})
@deftypefnx {Function File} {[@var{b}, @var{a}] =} residue (@var{r}, @var{p}, @var{k}, @var{e})
The first calling form computes the partial fraction expansion for the
quotient of the polynomials, @var{b} and @var{a}.

The quotient is defined as
@tex
$$
{B(s)\over A(s)} = \sum_{m=1}^M {r_m\over (s-p_m)^e_m}
  + \sum_{i=1}^N k_i s^{N-i}.
$$
@end tex
@ifnottex

@example
@group
B(s)    M       r(m)        N
---- = SUM ------------- + SUM k(i)*s^(N-i)
A(s)   m=1 (s-p(m))^e(m)   i=1
@end group
@end example

@end ifnottex
@noindent
where @math{M} is the number of poles (the length of the @var{r}, @var{p},
and @var{e}), the @var{k} vector is a polynomial of order @math{N-1}
representing the direct contribution, and the @var{e} vector specifies the
multiplicity of the m-th residue's pole.

For example,

@example
@group
b = [1, 1, 1];
a = [1, -5, 8, -4];
[r, p, k, e] = residue (b, a)
   @result{} r = [-2; 7; 3]
   @result{} p = [2; 2; 1]
   @result{} k = [](0x0)
   @result{} e = [1; 2; 1]
@end group
@end example

@noindent
which represents the following partial fraction expansion
@tex
$$
{s^2+s+1\over s^3-5s^2+8s-4} = {-2\over s-2} + {7\over (s-2)^2} + {3\over s-1}
$$
@end tex
@ifnottex

@example
@group
        s^2 + s + 1       -2        7        3
   ------------------- = ----- + ------- + -----
   s^3 - 5s^2 + 8s - 4   (s-2)   (s-2)^2   (s-1)
@end group
@end example

@end ifnottex

The second calling form performs the inverse operation and computes the
reconstituted quotient of polynomials, @var{b}(s)/@var{a}(s), from the
partial fraction expansion; represented by the residues, poles, and a direct
polynomial specified by @var{r}, @var{p} and @var{k}, and the pole
multiplicity @var{e}.

If the multiplicity, @var{e}, is not explicitly specified the multiplicity is
determined by the function @code{mpoles}.

For example:

@example
@group
r = [-2; 7; 3];
p = [2; 2; 1];
k = [1, 0];
[b, a] = residue (r, p, k)
   @result{} b = [1, -5, 9, -3, 1]
   @result{} a = [1, -5, 8, -4]

where mpoles is used to determine e = [1; 2; 1]
@end group
@end example

Alternatively the multiplicity may be defined explicitly, for example,

@example
@group
r = [7; 3; -2];
p = [2; 1; 2];
k = [1, 0];
e = [2; 1; 1];
[b, a] = residue (r, p, k, e)
   @result{} b = [1, -5, 9, -3, 1]
   @result{} a = [1, -5, 8, -4]
@end group
@end example

@noindent
which represents the following partial fraction expansion
@tex
$$
{-2\over s-2} + {7\over (s-2)^2} + {3\over s-1} + s = {s^4-5s^3+9s^2-3s+1\over s^3-5s^2+8s-4}
$$
@end tex
@ifnottex

@example
@group
 -2        7        3         s^4 - 5s^3 + 9s^2 - 3s + 1
----- + ------- + ----- + s = --------------------------
(s-2)   (s-2)^2   (s-1)          s^3 - 5s^2 + 8s - 4
@end group
@end example

@end ifnottex
@seealso{mpoles, poly, roots, conv, deconv}
@end deftypefn
roots
@c roots scripts/polynomial/roots.m
-*- texinfo -*-
@deftypefn {Function File} {} roots (@var{c})

Compute the roots of the polynomial @var{c}.

For a vector @var{c} with @math{N} components, return the roots of the
polynomial
@tex
$$
c_1 x^{N-1} + \cdots + c_{N-1} x + c_N.
$$
@end tex
@ifnottex

@example
c(1) * x^(N-1) + @dots{} + c(N-1) * x + c(N)
@end example

@end ifnottex

As an example, the following code finds the roots of the quadratic
polynomial
@tex
$$ p(x) = x^2 - 5. $$
@end tex
@ifnottex

@example
p(x) = x^2 - 5.
@end example

@end ifnottex

@example
@group
c = [1, 0, -5];
roots (c)
@result{}  2.2361
@result{} -2.2361
@end group
@end example

Note that the true result is
@tex
$\pm \sqrt{5}$
@end tex
@ifnottex
@math{+/- sqrt(5)}
@end ifnottex
which is roughly
@tex
$\pm 2.2361$.
@end tex
@ifnottex
@math{+/- 2.2361}.
@end ifnottex
@seealso{poly, compan, fzero}
@end deftypefn
spline
@c spline scripts/polynomial/spline.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{pp} =} spline (@var{x}, @var{y})
@deftypefnx {Function File} {@var{yi} =} spline (@var{x}, @var{y}, @var{xi})
Return the cubic spline interpolant of points @var{x} and @var{y}.

When called with two arguments, return the piecewise polynomial @var{pp}
that may be used with @code{ppval} to evaluate the polynomial at specific
points.

When called with a third input argument, @code{spline} evaluates the spline
at the points @var{xi}.  The third calling form
@code{spline (@var{x}, @var{y}, @var{xi})} is equivalent to
@code{ppval (spline (@var{x}, @var{y}), @var{xi})}.

The variable @var{x} must be a vector of length @var{n}.

@var{y} can be either a vector or array.  If @var{y} is a vector it must
have a length of either @var{n} or @code{@var{n} + 2}.  If the length of
@var{y} is @var{n}, then the @qcode{"not-a-knot"} end condition is used.
If the length of @var{y} is @code{@var{n} + 2}, then the first and last
values of the vector @var{y} are the values of the first derivative of the
cubic spline at the endpoints.

If @var{y} is an array, then the size of @var{y} must have the form
@tex
$$[s_1, s_2, \cdots, s_k, n]$$
@end tex
@ifnottex
@code{[@var{s1}, @var{s2}, @dots{}, @var{sk}, @var{n}]}
@end ifnottex
or
@tex
$$[s_1, s_2, \cdots, s_k, n + 2].$$
@end tex
@ifnottex
@code{[@var{s1}, @var{s2}, @dots{}, @var{sk}, @var{n} + 2]}.
@end ifnottex
The array is reshaped internally to a matrix where the leading
dimension is given by
@tex
$$s_1 s_2 \cdots s_k$$
@end tex
@ifnottex
@code{@var{s1} * @var{s2} * @dots{} * @var{sk}}
@end ifnottex
and each row of this matrix is then treated separately.  Note that this is
exactly the opposite of @code{interp1} but is done for @sc{matlab}
compatibility.

@seealso{pchip, ppval, mkpp, unmkpp}
@end deftypefn
splinefit
@c splinefit scripts/polynomial/splinefit.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{pp} =} splinefit (@var{x}, @var{y}, @var{breaks})
@deftypefnx {Function File} {@var{pp} =} splinefit (@var{x}, @var{y}, @var{p})
@deftypefnx {Function File} {@var{pp} =} splinefit (@dots{}, "periodic", @var{periodic})
@deftypefnx {Function File} {@var{pp} =} splinefit (@dots{}, "robust", @var{robust})
@deftypefnx {Function File} {@var{pp} =} splinefit (@dots{}, "beta", @var{beta})
@deftypefnx {Function File} {@var{pp} =} splinefit (@dots{}, "order", @var{order})
@deftypefnx {Function File} {@var{pp} =} splinefit (@dots{}, "constraints", @var{constraints})

Fit a piecewise cubic spline with breaks (knots) @var{breaks} to the
noisy data, @var{x} and @var{y}.

@var{x} is a vector, and @var{y} is a vector or N-D array.  If @var{y} is an
N-D array, then @var{x}(j) is matched to @var{y}(:,@dots{},:,j).

@var{p} is a positive integer defining the number of intervals along @var{x},
and @var{p}+1 is the number of breaks.  The number of points in each interval
differ by no more than 1.

The optional property @var{periodic} is a logical value which specifies
whether a periodic boundary condition is applied to the spline.  The
length of the period is @code{max (@var{breaks}) - min (@var{breaks})}.
The default value is @code{false}.

The optional property @var{robust} is a logical value which specifies
if robust fitting is to be applied to reduce the influence of outlying
data points.  Three iterations of weighted least squares are performed.
Weights are computed from previous residuals.  The sensitivity of outlier
identification is controlled by the property @var{beta}.  The value of
@var{beta} is restricted to the range, 0 < @var{beta} < 1.  The default
value is @var{beta} = 1/2.  Values close to 0 give all data equal
weighting.  Increasing values of @var{beta} reduce the influence of
outlying data.  Values close to unity may cause instability or rank
deficiency.

The fitted spline is returned as a piecewise polynomial, @var{pp}, and
may be evaluated using @code{ppval}.

The splines are constructed of polynomials with degree @var{order}.
The default is a cubic, @var{order}=3.  A spline with P pieces has
P+@var{order} degrees of freedom.  With periodic boundary conditions
the degrees of freedom are reduced to P.

The optional property, @var{constaints}, is a structure specifying linear
constraints on the fit.  The structure has three fields, @qcode{"xc"},
@qcode{"yc"}, and @qcode{"cc"}.

@table @asis
@item @qcode{"xc"}
Vector of the x-locations of the constraints.

@item @qcode{"yc"}
Constraining values at the locations @var{xc}.
The default is an array of zeros.

@item @qcode{"cc"}
Coefficients (matrix).  The default is an array of ones.  The number of
rows is limited to the order of the piecewise polynomials, @var{order}.
@end table

Constraints are linear combinations of derivatives of order 0 to
@var{order}-1 according to

@example
@group
@tex
$cc(1,j) \cdot y(xc(j)) + cc(2,j) \cdot y\prime(xc(j)) + ... = yc(:,\dots,:,j)$.
@end tex
@ifnottex
cc(1,j) * y(xc(j)) + cc(2,j) * y'(xc(j)) + ... = yc(:,...,:,j).
@end ifnottex
@end group
@end example

@seealso{interp1, unmkpp, ppval, spline, pchip, ppder, ppint, ppjumps}
@end deftypefn
unmkpp
@c unmkpp scripts/polynomial/unmkpp.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{p}, @var{n}, @var{k}, @var{d}] =} unmkpp (@var{pp})

Extract the components of a piecewise polynomial structure @var{pp}.

The components are:

@table @asis
@item @var{x}
Sample points.

@item @var{p}
Polynomial coefficients for points in sample interval.
@code{@var{p} (@var{i}, :)} contains the coefficients for the polynomial
over interval @var{i} ordered from highest to lowest.  If
@code{@var{d} > 1}, @code{@var{p} (@var{r}, @var{i}, :)} contains the
coefficients for the r-th polynomial defined on interval @var{i}.

@item @var{n}
Number of polynomial pieces.

@item @var{k}
Order of the polynomial plus 1.

@item @var{d}
Number of polynomials defined for each interval.
@end table

@seealso{mkpp, ppval, spline, pchip}
@end deftypefn
addpref
@c addpref scripts/prefs/addpref.m
-*- texinfo -*-
@deftypefn {Function File} {} addpref (@var{group}, @var{pref}, @var{val})
Add a preference @var{pref} and associated value @var{val} to the named
preference group @var{group}.

The named preference group must be a character string.

The preference @var{pref} may be a character string or a cell array of
character strings.

The corresponding value @var{val} may be any value, or, if @var{pref} is a
cell array of strings, @var{val} must be a cell array of values with the
same size as @var{pref}.
@seealso{setpref, getpref, ispref, rmpref}
@end deftypefn
getpref
@c getpref scripts/prefs/getpref.m
-*- texinfo -*-
@deftypefn  {Function File} {} getpref (@var{group}, @var{pref})
@deftypefnx {Function File} {} getpref (@var{group}, @var{pref}, @var{default})
@deftypefnx {Function File} {} getpref (@var{group})
Return the preference value corresponding to the named preference @var{pref}
in the preference group @var{group}.

The named preference group must be a character string.

If @var{pref} does not exist in @var{group} and @var{default} is
specified, return @var{default}.

The preference @var{pref} may be a character string or a cell array of
character strings.

The corresponding default value @var{default} may be any value, or, if
@var{pref} is a cell array of strings, @var{default} must be a cell array
of values with the same size as @var{pref}.

If neither @var{pref} nor @var{default} are specified, return a structure
of preferences for the preference group @var{group}.

If no arguments are specified, return a structure containing all groups of
preferences and their values.
@seealso{addpref, setpref, ispref, rmpref}
@end deftypefn
ispref
@c ispref scripts/prefs/ispref.m
-*- texinfo -*-
@deftypefn  {Function File} {} ispref (@var{group}, @var{pref})
@deftypefnx {Function File} {} ispref (@var{group})
Return true if the named preference @var{pref} exists in the preference
group @var{group}.

The named preference group must be a character string.

The preference @var{pref} may be a character string or a cell array of
character strings.

If @var{pref} is not specified, return true if the preference group
@var{group} exists.
@seealso{getpref, addpref, setpref, rmpref}
@end deftypefn
prefdir
@c prefdir scripts/prefs/prefdir.m
-*- texinfo -*-
@deftypefn  {Command} {} prefdir
@deftypefnx {Command} {@var{dir} =} prefdir
Return the directory that contains the preferences for Octave.

Examples:

Display the preferences directory

@example
prefdir
@end example

Change to the preferences folder

@example
cd (prefdir)
@end example
@seealso{getpref, setpref, addpref, rmpref, ispref}
@end deftypefn
preferences
@c preferences scripts/prefs/preferences.m
-*- texinfo -*-
@deftypefn {Command} {} preferences
Display the GUI preferences dialog window for Octave.
@end deftypefn
rmpref
@c rmpref scripts/prefs/rmpref.m
-*- texinfo -*-
@deftypefn  {Function File} {} rmpref (@var{group}, @var{pref})
@deftypefnx {Function File} {} rmpref (@var{group})
Remove the named preference @var{pref} from the preference group @var{group}.

The named preference group must be a character string.

The preference @var{pref} may be a character string or cell array of strings.

If @var{pref} is not specified, remove the preference group @var{group}.

It is an error to remove a nonexistent preference or group.
@seealso{addpref, ispref, setpref, getpref}
@end deftypefn
setpref
@c setpref scripts/prefs/setpref.m
-*- texinfo -*-
@deftypefn {Function File} {} setpref (@var{group}, @var{pref}, @var{val})
Set a preference @var{pref} to the given @var{val} in the named preference
group @var{group}.

The named preference group must be a character string.

The preference @var{pref} may be a character string or a cell array of
character strings.

The corresponding value @var{val} may be any value, or, if @var{pref} is a
cell array of strings, @var{val} must be a cell array of values with the
same size as @var{pref}.

If the named preference or group does not exist, it is added.
@seealso{addpref, getpref, ispref, rmpref}
@end deftypefn
intersect
@c intersect scripts/set/intersect.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{c} =} intersect (@var{a}, @var{b})
@deftypefnx {Function File} {@var{c} =} intersect (@var{a}, @var{b}, "rows")
@deftypefnx {Function File} {[@var{c}, @var{ia}, @var{ib}] =} intersect (@dots{})

Return the unique elements common to both @var{a} and @var{b} sorted in
ascending order.

If @var{a} and @var{b} are both row vectors then return a row vector;
Otherwise, return a column vector.  The inputs may also be cell arrays of
strings.

If the optional input @qcode{"rows"} is given then return the common rows of
@var{a} and @var{b}.  The inputs must be 2-D matrices to use this option.

If requested, return index vectors @var{ia} and @var{ib} such that
@code{@var{c} = @var{a}(@var{ia})} and @code{@var{c} = @var{b}(@var{ib})}.

@end deftypefn
@seealso{unique, union, setdiff, setxor, ismember}
ismember
@c ismember scripts/set/ismember.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{tf} =} ismember (@var{a}, @var{s})
@deftypefnx {Function File} {@var{tf} =} ismember (@var{a}, @var{s}, "rows")
@deftypefnx {Function File} {[@var{tf}, @var{s_idx}] =} ismember (@dots{})

Return a logical matrix @var{tf} with the same shape as @var{a} which is
true (1) if the element in @var{a} is found in @var{s} and false (0) if it
is not.

If a second output argument is requested then the index into @var{s} of each
matching element is also returned.

@example
@group
a = [3, 10, 1];
s = [0:9];
[tf, s_idx] = ismember (a, s)
     @result{} tf = [1, 0, 1]
     @result{} s_idx = [4, 0, 2]
@end group
@end example

The inputs @var{a} and @var{s} may also be cell arrays.

@example
@group
a = @{"abc"@};
s = @{"abc", "def"@};
[tf, s_idx] = ismember (a, s)
     @result{} tf = [1, 0]
     @result{} s_idx = [1, 0]
@end group
@end example

If the optional third argument @qcode{"rows"} is given then compare rows
in @var{a} with rows in @var{s}.  The inputs must be 2-D matrices with the
same number of columns to use this option.

@example
@group
a = [1:3; 5:7; 4:6];
s = [0:2; 1:3; 2:4; 3:5; 4:6];
[tf, s_idx] = ismember (a, s, "rows")
     @result{} tf = logical ([1; 0; 1])
     @result{} s_idx = [2; 0; 5];
@end group
@end example

@seealso{lookup, unique, union, intersect, setdiff, setxor}
@end deftypefn
powerset
@c powerset scripts/set/powerset.m
-*- texinfo -*-
@deftypefn  {Function File} {} powerset (@var{a})
@deftypefnx {Function File} {} powerset (@var{a}, "rows")
Compute the powerset (all subsets) of the set @var{a}.

The set @var{a} must be a numerical matrix or a cell array of strings.  The
output will always be a cell array of either vectors or strings.

With the optional argument @qcode{"rows"}, each row of the set @var{a} is
considered one element of the set.  The input must be a 2-D numeric matrix
to use this argument.

@seealso{unique, union, intersect, setdiff, setxor, ismember}
@end deftypefn
setdiff
@c setdiff scripts/set/setdiff.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{c} =} setdiff (@var{a}, @var{b})
@deftypefnx {Function File} {@var{c} =} setdiff (@var{a}, @var{b}, "rows")
@deftypefnx {Function File} {[@var{c}, @var{ia}] =} setdiff (@dots{})
Return the unique elements in @var{a} that are not in @var{b} sorted in
ascending order.

If @var{a} is a row vector return a column vector; Otherwise, return a
column vector.  The inputs may also be cell arrays of strings.

If the optional input @qcode{"rows"} is given then return the rows in
@var{a} that are not in @var{b}.  The inputs must be 2-D matrices to use
this option.

If requested, return the index vector @var{ia} such that
@code{@var{c} = @var{a}(@var{ia})}.
@seealso{unique, union, intersect, setxor, ismember}
@end deftypefn
setxor
@c setxor scripts/set/setxor.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{c} =} setxor (@var{a}, @var{b})
@deftypefnx {Function File} {@var{c} =} setxor (@var{a}, @var{b}, "rows")
@deftypefnx {Function File} {[@var{c}, @var{ia}, @var{ib}] =} setxor (@dots{})

Return the unique elements exclusive to sets @var{a} or @var{b} sorted in
ascending order.

If @var{a} and @var{b} are both row vectors then return a row vector;
Otherwise, return a column vector.  The inputs may also be cell arrays of
strings.

If the optional input @qcode{"rows"} is given then return the rows exclusive
to sets @var{a} and @var{b}.  The inputs must be 2-D matrices to use this
option.

If requested, return index vectors @var{ia} and @var{ib} such that
@code{@var{a}(@var{ia})} and @code{@var{b}(@var{ib})} are disjoint sets
whose union is @var{c}.

@seealso{unique, union, intersect, setdiff, ismember}
@end deftypefn
union
@c union scripts/set/union.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{c} =} union (@var{a}, @var{b})
@deftypefnx {Function File} {@var{c} =} union (@var{a}, @var{b}, "rows")
@deftypefnx {Function File} {[@var{c}, @var{ia}, @var{ib}] =} union (@dots{})

Return the unique elements that are in either @var{a} or @var{b} sorted in
ascending order.

If @var{a} and @var{b} are both row vectors then return a row vector;
Otherwise, return a column vector.  The inputs may also be cell arrays of
strings.

If the optional input @qcode{"rows"} is given then return rows that are in
either @var{a} or @var{b}.  The inputs must be 2-D matrices to use this
option.

The optional outputs @var{ia} and @var{ib} are index vectors such that
@code{@var{a}(@var{ia})} and @code{@var{b}(@var{ib})} are disjoint sets
whose union is @var{c}.

@seealso{unique, intersect, setdiff, setxor, ismember}
@end deftypefn
unique
@c unique scripts/set/unique.m
-*- texinfo -*-
@deftypefn  {Function File} {} unique (@var{x})
@deftypefnx {Function File} {} unique (@var{x}, "rows")
@deftypefnx {Function File} {[@var{y}, @var{i}, @var{j}] =} unique (@dots{})
@deftypefnx {Function File} {[@var{y}, @var{i}, @var{j}] =} unique (@dots{}, "first")
@deftypefnx {Function File} {[@var{y}, @var{i}, @var{j}] =} unique (@dots{}, "last")
Return the unique elements of @var{x} sorted in ascending order.

If the input @var{x} is a column vector then return a column vector;
Otherwise, return a row vector.  @var{x} may also be a cell array of strings.

If the optional argument @qcode{"rows"} is given then return the unique
rows of @var{x} sorted in ascending order.  The input must be a 2-D matrix
to use this option.

If requested, return index vectors @var{i} and @var{j} such that
@code{@var{y} = @var{x}(@var{i})} and @code{@var{x} = @var{y}(@var{j})}.

Additionally, if @var{i} is a requested output then one of @qcode{"first"} or
@qcode{"last"} may be given as an input.  If @qcode{"last"} is specified,
return the highest possible indices in @var{i}, otherwise, if @qcode{"first"}
is specified, return the lowest.  The default is @qcode{"last"}.
@seealso{union, intersect, setdiff, setxor, ismember}
@end deftypefn
arch_fit
@c arch_fit scripts/signal/arch_fit.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{a}, @var{b}] =} arch_fit (@var{y}, @var{x}, @var{p}, @var{iter}, @var{gamma}, @var{a0}, @var{b0})
Fit an ARCH regression model to the time series @var{y} using the scoring
algorithm in @nospell{Engle's} original ARCH paper.

The model is

@example
@group
y(t) = b(1) * x(t,1) + @dots{} + b(k) * x(t,k) + e(t),
h(t) = a(1) + a(2) * e(t-1)^2 + @dots{} + a(p+1) * e(t-p)^2
@end group
@end example

@noindent
in which @math{e(t)} is @math{N(0, h(t))}, given a time-series vector
@var{y} up to time @math{t-1} and a matrix of (ordinary) regressors @var{x}
up to @math{t}.  The order of the regression of the residual variance is
specified by @var{p}.

If invoked as @code{arch_fit (@var{y}, @var{k}, @var{p})} with a positive
integer @var{k}, fit an ARCH(@var{k}, @var{p}) process, i.e., do the above
with the @math{t}-th row of @var{x} given by

@example
[1, y(t-1), @dots{}, y(t-k)]
@end example

Optionally, one can specify the number of iterations @var{iter}, the
updating factor @var{gamma}, and initial values @math{a0} and @math{b0}
for the scoring algorithm.
@end deftypefn
arch_rnd
@c arch_rnd scripts/signal/arch_rnd.m
-*- texinfo -*-
@deftypefn {Function File} {} arch_rnd (@var{a}, @var{b}, @var{t})
Simulate an ARCH sequence of length @var{t} with AR coefficients @var{b} and
CH coefficients @var{a}.

The result @math{y(t)} follows the model
@c Set example in small font to prevent overfull line

@smallexample
y(t) = b(1) + b(2) * y(t-1) + @dots{} + b(lb) * y(t-lb+1) + e(t),
@end smallexample

@noindent
where @math{e(t)}, given @var{y} up to time @math{t-1}, is
@math{N(0, h(t))}, with
@c Set example in small font to prevent overfull line

@smallexample
h(t) = a(1) + a(2) * e(t-1)^2 + @dots{} + a(la) * e(t-la+1)^2
@end smallexample
@end deftypefn
arch_test
@c arch_test scripts/signal/arch_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{lm}] =} arch_test (@var{y}, @var{x}, @var{p})
For a linear regression model

@example
y = x * b + e
@end example

@noindent
perform a Lagrange Multiplier (LM) test of the null hypothesis of no
conditional heteroscedascity against the alternative of CH(@var{p}).

I.e., the model is

@example
y(t) = b(1) * x(t,1) + @dots{} + b(k) * x(t,k) + e(t),
@end example

@noindent
given @var{y} up to @math{t-1} and @var{x} up to @math{t},
@math{e}(t) is @math{N(0, h(t))} with

@example
h(t) = v + a(1) * e(t-1)^2 + @dots{} + a(p) * e(t-p)^2,
@end example

@noindent
and the null is @math{a(1)} == @dots{} == @math{a(p)} == 0.

If the second argument is a scalar integer, @math{k}, perform the same
test in a linear autoregression model of order @math{k}, i.e., with

@example
[1, y(t-1), @dots{}, y(t-@var{k})]
@end example

@noindent
as the @math{t}-th row of @var{x}.

Under the null, LM approximately has a chisquare distribution with
@var{p} degrees of freedom and @var{pval} is the @math{p}-value (1
minus the CDF of this distribution at LM) of the test.

If no output argument is given, the @math{p}-value is displayed.
@end deftypefn
arma_rnd
@c arma_rnd scripts/signal/arma_rnd.m
-*- texinfo -*-
@deftypefn {Function File} {} arma_rnd (@var{a}, @var{b}, @var{v}, @var{t}, @var{n})
Return a simulation of the ARMA model.

The ARMA model is defined by

@example
@group
x(n) = a(1) * x(n-1) + @dots{} + a(k) * x(n-k)
     + e(n) + b(1) * e(n-1) + @dots{} + b(l) * e(n-l)
@end group
@end example

@noindent
in which @var{k} is the length of vector @var{a}, @var{l} is the length of
vector @var{b} and @var{e} is Gaussian white noise with variance @var{v}.
The function returns a vector of length @var{t}.

The optional parameter @var{n} gives the number of dummy @var{x}(@var{i})
used for initialization, i.e., a sequence of length @var{t}+@var{n} is
generated and @var{x}(@var{n}+1:@var{t}+@var{n}) is returned.  If @var{n}
is omitted, @var{n} = 100 is used.
@end deftypefn
autoreg_matrix
@c autoreg_matrix scripts/signal/autoreg_matrix.m
-*- texinfo -*-
@deftypefn {Function File} {} autoreg_matrix (@var{y}, @var{k})
Given a time series (vector) @var{y}, return a matrix with ones in the first
column and the first @var{k} lagged values of @var{y} in the other columns.

In other words, for @var{t} > @var{k},
@code{[1, @var{y}(@var{t}-1), @dots{}, @var{y}(@var{t}-@var{k})]} is the
t-th row of the result.

The resulting matrix may be used as a regressor matrix in autoregressions.
@end deftypefn
bartlett
@c bartlett scripts/signal/bartlett.m
-*- texinfo -*-
@deftypefn {Function File} {} bartlett (@var{m})
Return the filter coefficients of a Bartlett (triangular) window of length
@var{m}.

For a definition of the Bartlett window see, e.g.,
@nospell{A.V. Oppenheim & R. W. Schafer},
@cite{Discrete-Time Signal Processing}.
@end deftypefn
blackman
@c blackman scripts/signal/blackman.m
-*- texinfo -*-
@deftypefn  {Function File} {} blackman (@var{m})
@deftypefnx {Function File} {} blackman (@var{m}, "periodic")
@deftypefnx {Function File} {} blackman (@var{m}, "symmetric")
Return the filter coefficients of a Blackman window of length @var{m}.

If the optional argument @qcode{"periodic"} is given, the periodic form
of the window is returned.  This is equivalent to the window of length
@var{m}+1 with the last coefficient removed.  The optional argument
@qcode{"symmetric"} is equivalent to not specifying a second argument.

For a definition of the Blackman window, see, e.g.,
@nospell{A.V. Oppenheim & R. W. Schafer},
@cite{Discrete-Time Signal Processing}.
@end deftypefn
detrend
@c detrend scripts/signal/detrend.m
-*- texinfo -*-
@deftypefn {Function File} {} detrend (@var{x}, @var{p})
If @var{x} is a vector, @code{detrend (@var{x}, @var{p})} removes the
best fit of a polynomial of order @var{p} from the data @var{x}.

If @var{x} is a matrix, @code{detrend (@var{x}, @var{p})} does the same
for each column in @var{x}.

The second argument @var{p} is optional.  If it is not specified, a value of
1 is assumed.  This corresponds to removing a linear trend.

The order of the polynomial can also be given as a string, in which case
@var{p} must be either @qcode{"constant"} (corresponds to @code{@var{p}=0})
or @qcode{"linear"} (corresponds to @code{@var{p}=1}).
@seealso{polyfit}
@end deftypefn
diffpara
@c diffpara scripts/signal/diffpara.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{d}, @var{dd}] =} diffpara (@var{x}, @var{a}, @var{b})
Return the estimator @var{d} for the differencing parameter of an
integrated time series.

The frequencies from @math{[2*pi*a/t, 2*pi*b/T]} are used for the
estimation.  If @var{b} is omitted, the interval
@math{[2*pi/T, 2*pi*a/T]} is used.  If both @var{b} and @var{a} are omitted
then @math{a = 0.5 * sqrt (T)} and @math{b = 1.5 * sqrt (T)} is used, where
@math{T} is the sample size.  If @var{x} is a matrix, the differencing
parameter of each column is estimated.

The estimators for all frequencies in the intervals described above is
returned in @var{dd}.

The value of @var{d} is simply the mean of @var{dd}.

Reference: @nospell{P.J. Brockwell & R.A. Davis}. @cite{Time Series:
Theory and Methods}. Springer 1987.
@end deftypefn
durbinlevinson
@c durbinlevinson scripts/signal/durbinlevinson.m
-*- texinfo -*-
@deftypefn {Function File} {} durbinlevinson (@var{c}, @var{oldphi}, @var{oldv})
Perform one step of the @nospell{Durbin-Levinson} algorithm.

The vector @var{c} specifies the autocovariances
@code{[gamma_0, @dots{}, gamma_t]} from lag 0 to @var{t}, @var{oldphi}
specifies the coefficients based on @var{c}(@var{t}-1) and @var{oldv}
specifies the corresponding error.

If @var{oldphi} and @var{oldv} are omitted, all steps from 1 to @var{t} of
the algorithm are performed.
@end deftypefn
fftconv
@c fftconv scripts/signal/fftconv.m
-*- texinfo -*-
@deftypefn  {Function File} {} fftconv (@var{x}, @var{y})
@deftypefnx {Function File} {} fftconv (@var{x}, @var{y}, @var{n})
Convolve two vectors using the FFT for computation.

@code{c = fftconv (@var{x}, @var{y})} returns a vector of length equal to
@code{length (@var{x}) + length (@var{y}) - 1}.  If @var{x} and @var{y}
are the coefficient vectors of two polynomials, the returned value is the
coefficient vector of the product polynomial.

The computation uses the FFT by calling the function @code{fftfilt}.  If
the optional argument @var{n} is specified, an N-point FFT is used.
@seealso{deconv, conv, conv2}
@end deftypefn
fftfilt
@c fftfilt scripts/signal/fftfilt.m
-*- texinfo -*-
@deftypefn  {Function File} {} fftfilt (@var{b}, @var{x})
@deftypefnx {Function File} {} fftfilt (@var{b}, @var{x}, @var{n})
Filter @var{x} with the FIR filter @var{b} using the FFT.

If @var{x} is a matrix, filter each column of the matrix.

Given the optional third argument, @var{n}, @code{fftfilt} uses the
overlap-add method to filter @var{x} with @var{b} using an N-point FFT@.
The FFT size must be an even power of 2 and must be greater than or equal to
the length of @var{b}.  If the specified @var{n} does not meet these
criteria, it is automatically adjusted to the nearest value that does.

@seealso{filter, filter2}
@end deftypefn
fftshift
@c fftshift scripts/signal/fftshift.m
-*- texinfo -*-
@deftypefn  {Function File} {} fftshift (@var{x})
@deftypefnx {Function File} {} fftshift (@var{x}, @var{dim})
Perform a shift of the vector @var{x}, for use with the @code{fft} and
@code{ifft} functions, in order the move the frequency 0 to the center of
the vector or matrix.

If @var{x} is a vector of @math{N} elements corresponding to @math{N} time
samples spaced by @nospell{@math{dt}}, then
@code{fftshift (fft (@var{x}))} corresponds to frequencies

@example
f = [ -(ceil((N-1)/2):-1:1)*df 0 (1:floor((N-1)/2))*df ]
@end example

@noindent
where @nospell{@math{df} = 1 / @math{dt}}.

If @var{x} is a matrix, the same holds for rows and columns.  If @var{x}
is an array, then the same holds along each dimension.

The optional @var{dim} argument can be used to limit the dimension along
which the permutation occurs.
@seealso{ifftshift}
@end deftypefn
filter2
@c filter2 scripts/signal/filter2.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{y} =} filter2 (@var{b}, @var{x})
@deftypefnx {Function File} {@var{y} =} filter2 (@var{b}, @var{x}, @var{shape})
Apply the 2-D FIR filter @var{b} to @var{x}.

If the argument @var{shape} is specified, return an array of the desired
shape.  Possible values are:

@table @asis
@item @qcode{"full"}
pad @var{x} with zeros on all sides before filtering.

@item @qcode{"same"}
unpadded @var{x} (default)

@item @qcode{"valid"}
trim @var{x} after filtering so edge effects are no included.
@end table

Note this is just a variation on convolution, with the parameters reversed
and @var{b} rotated 180 degrees.
@seealso{conv2}
@end deftypefn
fractdiff
@c fractdiff scripts/signal/fractdiff.m
-*- texinfo -*-
@deftypefn {Function File} {} fractdiff (@var{x}, @var{d})
Compute the fractional differences @math{(1-L)^d x} where @math{L}
denotes the lag-operator and @math{d} is greater than -1.
@end deftypefn
freqz
@c freqz scripts/signal/freqz.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{h}, @var{w}] =} freqz (@var{b}, @var{a}, @var{n}, "whole")
@deftypefnx {Function File} {[@var{h}, @var{w}] =} freqz (@var{b})
@deftypefnx {Function File} {[@var{h}, @var{w}] =} freqz (@var{b}, @var{a})
@deftypefnx {Function File} {[@var{h}, @var{w}] =} freqz (@var{b}, @var{a}, @var{n})
@deftypefnx {Function File} {@var{h} =} freqz (@var{b}, @var{a}, @var{w})
@deftypefnx {Function File} {[@var{h}, @var{w}] =} freqz (@dots{}, @var{Fs})
@deftypefnx {Function File} {} freqz (@dots{})

Return the complex frequency response @var{h} of the rational IIR filter
whose numerator and denominator coefficients are @var{b} and @var{a},
respectively.

The response is evaluated at @var{n} angular frequencies between 0 and
@ifnottex
2*pi.
@end ifnottex
@tex
$2\pi$.
@end tex

@noindent
The output value @var{w} is a vector of the frequencies.

If @var{a} is omitted, the denominator is assumed to be 1 (this
corresponds to a simple FIR filter).

If @var{n} is omitted, a value of 512 is assumed.  For fastest computation,
@var{n} should factor into a small number of small primes.

If the fourth argument, @qcode{"whole"}, is omitted the response is
evaluated at frequencies between 0 and
@ifnottex
pi.
@end ifnottex
@tex
$\pi$.
@end tex

@code{freqz (@var{b}, @var{a}, @var{w})}

Evaluate the response at the specific frequencies in the vector @var{w}.
The values for @var{w} are measured in radians.

@code{[@dots{}] = freqz (@dots{}, @var{Fs})}

Return frequencies in Hz instead of radians assuming a sampling rate
@var{Fs}.  If you are evaluating the response at specific frequencies
@var{w}, those frequencies should be requested in Hz rather than radians.

@code{freqz (@dots{})}

Plot the magnitude and phase response of @var{h} rather than returning them.

@seealso{freqz_plot}
@end deftypefn
freqz_plot
@c freqz_plot scripts/signal/freqz_plot.m
-*- texinfo -*-
@deftypefn  {Function File} {} freqz_plot (@var{w}, @var{h})
@deftypefnx {Function File} {} freqz_plot (@var{w}, @var{h}, @var{freq_norm})
Plot the magnitude and phase response of @var{h}.

If the optional @var{freq_norm} argument is true, the frequency vector
@var{w} is in units of normalized radians.  If @var{freq_norm} is false, or
not given, then @var{w} is measured in Hertz.
@seealso{freqz}
@end deftypefn
hamming
@c hamming scripts/signal/hamming.m
-*- texinfo -*-
@deftypefn  {Function File} {} hamming (@var{m})
@deftypefnx {Function File} {} hamming (@var{m}, "periodic")
@deftypefnx {Function File} {} hamming (@var{m}, "symmetric")
Return the filter coefficients of a Hamming window of length @var{m}.

If the optional argument @qcode{"periodic"} is given, the periodic form
of the window is returned.  This is equivalent to the window of length
@var{m}+1 with the last coefficient removed.  The optional argument
@qcode{"symmetric"} is equivalent to not specifying a second argument.

For a definition of the Hamming window see, e.g.,
@nospell{A.V. Oppenheim & R. W. Schafer},
@cite{Discrete-Time Signal Processing}.
@end deftypefn
hanning
@c hanning scripts/signal/hanning.m
-*- texinfo -*-
@deftypefn  {Function File} {} hanning (@var{m})
@deftypefnx {Function File} {} hanning (@var{m}, "periodic")
@deftypefnx {Function File} {} hanning (@var{m}, "symmetric")
Return the filter coefficients of a Hanning window of length @var{m}.

If the optional argument @qcode{"periodic"} is given, the periodic form
of the window is returned.  This is equivalent to the window of length
@var{m}+1 with the last coefficient removed.  The optional argument
@qcode{"symmetric"} is equivalent to not specifying a second argument.

For a definition of the Hanning window see, e.g.,
@nospell{A.V. Oppenheim & R. W. Schafer},
@cite{Discrete-Time Signal Processing}.
@end deftypefn
hurst
@c hurst scripts/signal/hurst.m
-*- texinfo -*-
@deftypefn {Function File} {} hurst (@var{x})
Estimate the Hurst parameter of sample @var{x} via the rescaled range
statistic.

If @var{x} is a matrix, the parameter is estimated for every column.
@end deftypefn
ifftshift
@c ifftshift scripts/signal/ifftshift.m
-*- texinfo -*-
@deftypefn  {Function File} {} ifftshift (@var{x})
@deftypefnx {Function File} {} ifftshift (@var{x}, @var{dim})
Undo the action of the @code{fftshift} function.

For even length @var{x}, @code{fftshift} is its own inverse, but odd lengths
differ slightly.
@seealso{fftshift}
@end deftypefn
periodogram
@c periodogram scripts/signal/periodogram.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{Pxx}, @var{w}] =} periodogram (@var{x})
@deftypefnx {Function File} {[@var{Pxx}, @var{w}] =} periodogram (@var{x}, @var{win})
@deftypefnx {Function File} {[@var{Pxx}, @var{w}] =} periodogram (@var{x}, @var{win}, @var{nfft})
@deftypefnx {Function File} {[@var{Pxx}, @var{f}] =} periodogram (@var{x}, @var{win}, @var{nfft}, @var{Fs})
@deftypefnx {Function File} {[@var{Pxx}, @var{f}] =} periodogram (@dots{}, "@var{range}")
@deftypefnx {Function File} {} periodogram (@dots{})
Return the periodogram (Power Spectral Density) of @var{x}.

The possible inputs are:

@table @var
@item x

data vector.  If @var{x} is real-valued a one-sided spectrum is estimated.
If @var{x} is complex-valued, or @qcode{"@var{range}"} specifies
@qcode{"@nospell{twosided}"}, the full spectrum is estimated.

@item win
window weight data.  If window is empty or unspecified a default rectangular
window is used.  Otherwise, the window is applied to the signal
(@code{@var{x} .* @var{win}}) before computing the periodogram.  The window
data must be a vector of the same length as @var{x}.

@item nfft
number of frequency bins.  The default is 256 or the next higher power of
2 greater than the length of @var{x}
(@code{max (256, 2.^nextpow2 (length (x)))}).  If @var{nfft} is greater
than the length of the input then @var{x} will be zero-padded to the length
of @var{nfft}.

@item Fs
sampling rate.  The default is 1.

@item range
range of spectrum.  @qcode{"@nospell{onesided}"} computes spectrum from
[0..nfft/2+1].  @qcode{"@nospell{twosided}"} computes spectrum from
[0..nfft-1].
@end table

The optional second output @var{w} are the normalized angular frequencies.
For a one-sided calculation @var{w} is in the range [0, pi] if @var{nfft}
is even and [0, pi) if @var{nfft} is odd.  Similarly, for a two-sided
calculation @var{w} is in the range [0, 2*pi] or [0, 2*pi) depending on
@var{nfft}.

If a sampling frequency is specified, @var{Fs}, then the output frequencies
@var{f} will be in the range [0, @var{Fs}/2] or [0, @var{Fs}/2) for
one-sided calculations.  For two-sided calculations the range will be
[0, @var{Fs}).

When called with no outputs the periodogram is immediately plotted in the
current figure window.
@seealso{fft}
@end deftypefn
sinc
@c sinc scripts/signal/sinc.m
-*- texinfo -*-
@deftypefn {Function File} {} sinc (@var{x})
Compute the sinc function.

Return
@tex
$ \sin (\pi x)/(\pi x)$.
@end tex
@ifnottex
sin (pi*x) / (pi*x).
@end ifnottex
@end deftypefn
sinetone
@c sinetone scripts/signal/sinetone.m
-*- texinfo -*-
@deftypefn {Function File} {} sinetone (@var{freq}, @var{rate}, @var{sec}, @var{ampl})
Return a sinetone of frequency @var{freq} with a length of @var{sec}
seconds at sampling rate @var{rate} and with amplitude @var{ampl}.

The arguments @var{freq} and @var{ampl} may be vectors of common size.

The defaults are @var{rate} = 8000, @var{sec} = 1, and @var{ampl} = 64.
@seealso{sinewave}
@end deftypefn
sinewave
@c sinewave scripts/signal/sinewave.m
-*- texinfo -*-
@deftypefn {Function File} {} sinewave (@var{m}, @var{n}, @var{d})
Return an @var{m}-element vector with @var{i}-th element given by
@code{sin (2 * pi * (@var{i}+@var{d}-1) / @var{n})}.

The default value for @var{d} is 0 and the default value for @var{n} is
@var{m}.
@seealso{sinetone}
@end deftypefn
spectral_adf
@c spectral_adf scripts/signal/spectral_adf.m
-*- texinfo -*-
@deftypefn  {Function File} {} spectral_adf (@var{c})
@deftypefnx {Function File} {} spectral_adf (@var{c}, @var{win})
@deftypefnx {Function File} {} spectral_adf (@var{c}, @var{win}, @var{b})
Return the spectral density estimator given a vector of autocovariances
@var{c}, window name @var{win}, and bandwidth, @var{b}.

The window name, e.g., @qcode{"triangle"} or @qcode{"rectangle"} is
used to search for a function called @code{@var{win}_lw}.

If @var{win} is omitted, the triangle window is used.

If @var{b} is omitted, @code{1 / sqrt (length (@var{x}))} is used.
@seealso{spectral_xdf}
@end deftypefn
spectral_xdf
@c spectral_xdf scripts/signal/spectral_xdf.m
-*- texinfo -*-
@deftypefn  {Function File} {} spectral_xdf (@var{x})
@deftypefnx {Function File} {} spectral_xdf (@var{x}, @var{win})
@deftypefnx {Function File} {} spectral_xdf (@var{x}, @var{win}, @var{b})
Return the spectral density estimator given a data vector @var{x}, window
name @var{win}, and bandwidth, @var{b}.

The window name, e.g., @qcode{"triangle"} or @qcode{"rectangle"} is used to
search for a function called @code{@var{win}_sw}.

If @var{win} is omitted, the triangle window is used.

If @var{b} is omitted, @code{1 / sqrt (length (@var{x}))} is used.
@seealso{spectral_adf}
@end deftypefn
spencer
@c spencer scripts/signal/spencer.m
-*- texinfo -*-
@deftypefn {Function File} {} spencer (@var{x})
Return Spencer's 15 point moving average of each column of @var{x}.
@end deftypefn
stft
@c stft scripts/signal/stft.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{y} =} stft (@var{x})
@deftypefnx {Function File} {@var{y} =} stft (@var{x}, @var{win_size})
@deftypefnx {Function File} {@var{y} =} stft (@var{x}, @var{win_size}, @var{inc})
@deftypefnx {Function File} {@var{y} =} stft (@var{x}, @var{win_size}, @var{inc}, @var{num_coef})
@deftypefnx {Function File} {@var{y} =} stft (@var{x}, @var{win_size}, @var{inc}, @var{num_coef}, @var{win_type})
@deftypefnx {Function File} {[@var{y}, @var{c}] =} stft (@dots{})
Compute the short-time Fourier transform of the vector @var{x} with
@var{num_coef} coefficients by applying a window of @var{win_size} data
points and an increment of @var{inc} points.

Before computing the Fourier transform, one of the following windows
is applied:

@table @asis
@item @qcode{"hanning"}
win_type = 1

@item @qcode{"hamming"}
win_type = 2

@item @qcode{"rectangle"}
win_type = 3
@end table

The window names can be passed as strings or by the @var{win_type} number.

The following defaults are used for unspecified arguments:
@var{win_size} = 80, @var{inc} = 24, @var{num_coef} = 64, and
@var{win_type} = 1.

@code{@var{y} = stft (@var{x}, @dots{})} returns the absolute values of the
Fourier coefficients according to the @var{num_coef} positive frequencies.

@code{[@var{y}, @var{c}] = stft (@code{x}, @dots{})} returns the entire
STFT-matrix @var{y} and a 3-element vector @var{c} containing the window
size, increment, and window type, which is needed by the @code{synthesis}
function.
@seealso{synthesis}
@end deftypefn
synthesis
@c synthesis scripts/signal/synthesis.m
-*- texinfo -*-
@deftypefn {Function File} {@var{x} =} synthesis (@var{y}, @var{c})
Compute a signal from its short-time Fourier transform @var{y} and a
3-element vector @var{c} specifying window size, increment, and window type.

The values @var{y} and @var{c} can be derived by

@example
[@var{y}, @var{c}] = stft (@var{x} , @dots{})
@end example
@seealso{stft}
@end deftypefn
unwrap
@c unwrap scripts/signal/unwrap.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{b} =} unwrap (@var{x})
@deftypefnx {Function File} {@var{b} =} unwrap (@var{x}, @var{tol})
@deftypefnx {Function File} {@var{b} =} unwrap (@var{x}, @var{tol}, @var{dim})

Unwrap radian phases by adding multiples of 2*pi as appropriate to remove
jumps greater than @var{tol}.

@var{tol} defaults to pi.

Unwrap will work along the dimension @var{dim}.  If @var{dim}
is unspecified it defaults to the first non-singleton dimension.
@end deftypefn
yulewalker
@c yulewalker scripts/signal/yulewalker.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{a}, @var{v}] =} yulewalker (@var{c})
Fit an AR (p)-model with Yule-Walker estimates given a vector @var{c} of
autocovariances @code{[gamma_0, @dots{}, gamma_p]}.

Returns the AR coefficients, @var{a}, and the variance of white noise,
@var{v}.
@end deftypefn
bicg
@c bicg scripts/sparse/bicg.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} bicg (@var{A}, @var{b}, @var{rtol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0})
@deftypefnx {Function File} {@var{x} =} bicg (@var{A}, @var{b}, @var{rtol}, @var{maxit}, @var{P})
@deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} bicg (@var{A}, @var{b}, @dots{})
Solve @code{A x = b} using the Bi-conjugate gradient iterative method.

@itemize @minus
@item @var{rtol} is the relative tolerance, if not given or set to [] the
default value 1e-6 is used.

@item @var{maxit} the maximum number of outer iterations, if not given or
set to [] the default value @code{min (20, numel (b))} is used.

@item @var{x0} the initial guess, if not given or set to [] the default
value @code{zeros (size (b))} is used.
@end itemize

@var{A} can be passed as a matrix or as a function handle or inline function
@code{f} such that @code{f(x, "notransp") = A*x} and
@code{f(x, "transp") = A'*x}.

The preconditioner @var{P} is given as @code{P = M1 * M2}.  Both @var{M1}
and @var{M2} can be passed as a matrix or as a function handle or inline
function @code{g} such that @code{g(x, "notransp") = M1 \ x} or
@code{g(x, "notransp") = M2 \ x} and @code{g(x, "transp") = M1' \ x} or
@code{g(x, "transp") = M2' \ x}.

If called with more than one output parameter

@itemize @minus
@item @var{flag} indicates the exit status:

@itemize @minus
@item 0: iteration converged to the within the chosen tolerance

@item 1: the maximum number of iterations was reached before convergence

@item 3: the algorithm reached stagnation
@end itemize

(the value 2 is unused but skipped for compatibility).

@item @var{relres} is the final value of the relative residual.

@item @var{iter} is the number of iterations performed.

@item @var{resvec} is a vector containing the relative residual at each
iteration.
@end itemize

@seealso{bicgstab, cgs, gmres, pcg, qmr}

@end deftypefn
bicgstab
@c bicgstab scripts/sparse/bicgstab.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} bicgstab (@var{A}, @var{b}, @var{rtol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0})
@deftypefnx {Function File} {@var{x} =} bicgstab (@var{A}, @var{b}, @var{rtol}, @var{maxit}, @var{P})
@deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} bicgstab (@var{A}, @var{b}, @dots{})
Solve @code{A x = b} using the stabilizied Bi-conjugate gradient iterative
method.

@itemize @minus
@item @var{rtol} is the relative tolerance, if not given or set to [] the
default value 1e-6 is used.

@item @var{maxit} the maximum number of outer iterations, if not given or
set to [] the default value @code{min (20, numel (b))} is used.

@item @var{x0} the initial guess, if not given or set to [] the default
value @code{zeros (size (b))} is used.
@end itemize

@var{A} can be passed as a matrix or as a function handle or inline
function @code{f} such that @code{f(x) = A*x}.

The preconditioner @var{P} is given as @code{P = M1 * M2}.  Both @var{M1}
and @var{M2} can be passed as a matrix or as a function handle or inline
function @code{g} such that @code{g(x) = M1 \ x} or @code{g(x) = M2 \ x}.

If called with more than one output parameter

@itemize @minus
@item @var{flag} indicates the exit status:

@itemize @minus
@item 0: iteration converged to the within the chosen tolerance

@item 1: the maximum number of iterations was reached before convergence

@item 3: the algorithm reached stagnation
@end itemize

(the value 2 is unused but skipped for compatibility).

@item @var{relres} is the final value of the relative residual.

@item @var{iter} is the number of iterations performed.

@item @var{resvec} is a vector containing the relative residual at each
iteration.
@end itemize

@seealso{bicg, cgs, gmres, pcg, qmr}

@end deftypefn
cgs
@c cgs scripts/sparse/cgs.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} cgs (@var{A}, @var{b}, @var{rtol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0})
@deftypefnx {Function File} {@var{x} =} cgs (@var{A}, @var{b}, @var{rtol}, @var{maxit}, @var{P})
@deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} cgs (@var{A}, @var{b}, @dots{})
Solve @code{A x = b}, where @var{A} is a square matrix, using the
Conjugate Gradients Squared method.

@itemize @minus
@item @var{rtol} is the relative tolerance, if not given or set to [] the
default value 1e-6 is used.

@item @var{maxit} the maximum number of outer iterations, if not given or
set to [] the default value @code{min (20, numel (b))} is used.

@item @var{x0} the initial guess, if not given or set to [] the default
value @code{zeros (size (b))} is used.
@end itemize

@var{A} can be passed as a matrix or as a function handle or inline
function @code{f} such that @code{f(x) = A*x}.

The preconditioner @var{P} is given as @code{P = M1 * M2}.  Both @var{M1}
and @var{M2} can be passed as a matrix or as a function handle or inline
function @code{g} such that @code{g(x) = M1 \ x} or @code{g(x) = M2 \ x}.

If called with more than one output parameter

@itemize @minus
@item @var{flag} indicates the exit status:

@itemize @minus
@item 0: iteration converged to the within the chosen tolerance

@item 1: the maximum number of iterations was reached before convergence

@item 3: the algorithm reached stagnation
@end itemize

(the value 2 is unused but skipped for compatibility).

@item @var{relres} is the final value of the relative residual.

@item @var{iter} is the number of iterations performed.

@item @var{resvec} is a vector containing the relative residual at
each iteration.
@end itemize

@seealso{pcg, bicgstab, bicg, gmres, qmr}
@end deftypefn
colperm
@c colperm scripts/sparse/colperm.m
-*- texinfo -*-
@deftypefn {Function File} {@var{p} =} colperm (@var{s})
Return the column permutations such that the columns of
@code{@var{s} (:, @var{p})} are ordered in terms of increasing number of
nonzero elements.

If @var{s} is symmetric, then @var{p} is chosen such that
@code{@var{s} (@var{p}, @var{p})} orders the rows and columns with
increasing number of nonzeros elements.
@end deftypefn
eigs
@c eigs scripts/sparse/eigs.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{d} =} eigs (@var{A})
@deftypefnx {Function File} {@var{d} =} eigs (@var{A}, @var{k})
@deftypefnx {Function File} {@var{d} =} eigs (@var{A}, @var{k}, @var{sigma})
@deftypefnx {Function File} {@var{d} =} eigs (@var{A}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {Function File} {@var{d} =} eigs (@var{A}, @var{B})
@deftypefnx {Function File} {@var{d} =} eigs (@var{A}, @var{B}, @var{k})
@deftypefnx {Function File} {@var{d} =} eigs (@var{A}, @var{B}, @var{k}, @var{sigma})
@deftypefnx {Function File} {@var{d} =} eigs (@var{A}, @var{B}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {Function File} {@var{d} =} eigs (@var{af}, @var{n})
@deftypefnx {Function File} {@var{d} =} eigs (@var{af}, @var{n}, @var{B})
@deftypefnx {Function File} {@var{d} =} eigs (@var{af}, @var{n}, @var{k})
@deftypefnx {Function File} {@var{d} =} eigs (@var{af}, @var{n}, @var{B}, @var{k})
@deftypefnx {Function File} {@var{d} =} eigs (@var{af}, @var{n}, @var{k}, @var{sigma})
@deftypefnx {Function File} {@var{d} =} eigs (@var{af}, @var{n}, @var{B}, @var{k}, @var{sigma})
@deftypefnx {Function File} {@var{d} =} eigs (@var{af}, @var{n}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {Function File} {@var{d} =} eigs (@var{af}, @var{n}, @var{B}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {Function File} {[@var{V}, @var{d}] =} eigs (@var{A}, @dots{})
@deftypefnx {Function File} {[@var{V}, @var{d}] =} eigs (@var{af}, @var{n}, @dots{})
@deftypefnx {Function File} {[@var{V}, @var{d}, @var{flag}] =} eigs (@var{A}, @dots{})
@deftypefnx {Function File} {[@var{V}, @var{d}, @var{flag}] =} eigs (@var{af}, @var{n}, @dots{})
Calculate a limited number of eigenvalues and eigenvectors of @var{A},
based on a selection criteria.

The number of eigenvalues and eigenvectors to calculate is given by
@var{k} and defaults to 6.

By default, @code{eigs} solve the equation
@tex
$A \nu = \lambda \nu$,
@end tex
@ifinfo
@code{A * v = lambda * v},
@end ifinfo
where
@tex
$\lambda$ is a scalar representing one of the eigenvalues, and $\nu$
@end tex
@ifinfo
@code{lambda} is a scalar representing one of the eigenvalues, and @code{v}
@end ifinfo
is the corresponding eigenvector.  If given the positive definite matrix
@var{B} then @code{eigs} solves the general eigenvalue equation
@tex
$A \nu = \lambda B \nu$.
@end tex
@ifinfo
@code{A * v = lambda * B * v}.
@end ifinfo

The argument @var{sigma} determines which eigenvalues are returned.
@var{sigma} can be either a scalar or a string.  When @var{sigma} is a
scalar, the @var{k} eigenvalues closest to @var{sigma} are returned.  If
@var{sigma} is a string, it must have one of the following values.

@table @asis
@item @qcode{"lm"}
Largest Magnitude (default).

@item @qcode{"sm"}
Smallest Magnitude.

@item @qcode{"la"}
Largest Algebraic (valid only for real symmetric problems).

@item @qcode{"sa"}
Smallest Algebraic (valid only for real symmetric problems).

@item @qcode{"be"}
Both Ends, with one more from the high-end if @var{k} is odd (valid only for
real symmetric problems).

@item @qcode{"lr"}
Largest Real part (valid only for complex or unsymmetric problems).

@item @qcode{"sr"}
Smallest Real part (valid only for complex or unsymmetric problems).

@item @qcode{"li"}
Largest Imaginary part (valid only for complex or unsymmetric problems).

@item @qcode{"si"}
Smallest Imaginary part (valid only for complex or unsymmetric problems).
@end table

If @var{opts} is given, it is a structure defining possible options that
@code{eigs} should use.  The fields of the @var{opts} structure are:

@table @code
@item issym
If @var{af} is given, then flags whether the function @var{af} defines a
symmetric problem.  It is ignored if @var{A} is given.  The default is false.

@item isreal
If @var{af} is given, then flags whether the function @var{af} defines a
real problem.  It is ignored if @var{A} is given.  The default is true.

@item tol
Defines the required convergence tolerance, calculated as
@code{tol * norm (A)}.  The default is @code{eps}.

@item maxit
The maximum number of iterations.  The default is 300.

@item p
The number of Lanzcos basis vectors to use.  More vectors will result in
faster convergence, but a greater use of memory.  The optimal value of
@code{p} is problem dependent and should be in the range @var{k} to @var{n}.
The default value is @code{2 * @var{k}}.

@item v0
The starting vector for the algorithm.  An initial vector close to the
final vector will speed up convergence.  The default is for @sc{arpack}
to randomly generate a starting vector.  If specified, @code{v0} must be
an @var{n}-by-1 vector where @code{@var{n} = rows (@var{A})}

@item disp
The level of diagnostic printout (0|1|2).  If @code{disp} is 0 then
diagnostics are disabled.  The default value is 0.

@item cholB
Flag if @code{chol (@var{B})} is passed rather than @var{B}.  The default is
false.

@item permB
The permutation vector of the Cholesky@tie{}factorization of @var{B} if
@code{cholB} is true.  That is @code{chol (@var{B}(permB, permB))}.  The
default is @code{1:@var{n}}.

@end table

It is also possible to represent @var{A} by a function denoted @var{af}.
@var{af} must be followed by a scalar argument @var{n} defining the length
of the vector argument accepted by @var{af}.  @var{af} can be a function
handle, an inline function, or a string.  When @var{af} is a string it
holds the name of the function to use.

@var{af} is a function of the form @code{y = af (x)} where the required
return value of @var{af} is determined by the value of @var{sigma}.  The
four possible forms are

@table @code
@item A * x
if @var{sigma} is not given or is a string other than "sm".

@item A \ x
if @var{sigma} is 0 or "sm".

@item (A - sigma * I) \ x
for the standard eigenvalue problem, where @code{I} is the identity matrix
of the same size as @var{A}.

@item (A - sigma * B) \ x
for the general eigenvalue problem.
@end table

The return arguments of @code{eigs} depend on the number of return arguments
requested.  With a single return argument, a vector @var{d} of length @var{k}
is returned containing the @var{k} eigenvalues that have been found.  With
two return arguments, @var{V} is a @var{n}-by-@var{k} matrix whose columns
are the @var{k} eigenvectors corresponding to the returned eigenvalues.  The
eigenvalues themselves are returned in @var{d} in the form of a
@var{n}-by-@var{k} matrix, where the elements on the diagonal are the
eigenvalues.

Given a third return argument @var{flag}, @code{eigs} returns the status
of the convergence.  If @var{flag} is 0 then all eigenvalues have converged.
Any other value indicates a failure to converge.

This function is based on the @sc{arpack} package, written by
@nospell{R. Lehoucq, K. Maschhoff, D. Sorensen, and C. Yang}.  For more
information see @url{http://www.caam.rice.edu/software/ARPACK/}.

@seealso{eig, svds}
@end deftypefn
etreeplot
@c etreeplot scripts/sparse/etreeplot.m
-*- texinfo -*-
@deftypefn  {Function File} {} etreeplot (@var{A})
@deftypefnx {Function File} {} etreeplot (@var{A}, @var{node_style}, @var{edge_style})
Plot the elimination tree of the matrix @var{A} or
@tcode{@var{A}+@var{A}'} if @var{A} in not symmetric.

The optional parameters @var{node_style} and @var{edge_style} define the
output style.
@seealso{treeplot, gplot}
@end deftypefn
gmres
@c gmres scripts/sparse/gmres.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} gmres (@var{A}, @var{b}, @var{m}, @var{rtol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0})
@deftypefnx {Function File} {@var{x} =} gmres (@var{A}, @var{b}, @var{m}, @var{rtol}, @var{maxit}, @var{P})
@deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} gmres (@dots{})
Solve @code{A x = b} using the Preconditioned GMRES iterative method with
restart, a.k.a. PGMRES(m).

@itemize @minus
@item @var{rtol} is the relative tolerance,
if not given or set to [] the default value 1e-6 is used.

@item @var{maxit} is the maximum number of outer iterations, if not given or
set to [] the default value @code{min (10, numel (b) / restart)} is used.

@item @var{x0} is the initial guess,
if not given or set to [] the default value @code{zeros (size (b))} is used.

@item @var{m} is the restart parameter,
if not given or set to [] the default value @code{numel (b)} is used.
@end itemize

Argument @var{A} can be passed as a matrix, function handle, or inline
function @code{f} such that @code{f(x) = A*x}.

The preconditioner @var{P} is given as @code{P = M1 * M2}.  Both @var{M1}
and @var{M2} can be passed as a matrix, function handle, or inline function
@code{g} such that @code{g(x) = M1\x} or @code{g(x) = M2\x}.

Besides the vector @var{x}, additional outputs are:

@itemize @minus
@item @var{flag} indicates the exit status:

@table @asis
@item 0 : iteration converged to within the specified tolerance

@item 1 : maximum number of iterations exceeded

@item 2 : unused, but skipped for compatibility

@item 3 : algorithm reached stagnation (no change between iterations)
@end table

@item @var{relres} is the final value of the relative residual.

@item @var{iter} is a vector containing the number of outer iterations and
total iterations performed.

@item @var{resvec} is a vector containing the relative residual at each
iteration.
@end itemize

@seealso{bicg, bicgstab, cgs, pcg, pcr, qmr}
@end deftypefn
gplot
@c gplot scripts/sparse/gplot.m
-*- texinfo -*-
@deftypefn  {Function File} {} gplot (@var{A}, @var{xy})
@deftypefnx {Function File} {} gplot (@var{A}, @var{xy}, @var{line_style})
@deftypefnx {Function File} {[@var{x}, @var{y}] =} gplot (@var{A}, @var{xy})
Plot a graph defined by @var{A} and @var{xy} in the graph theory sense.

@var{A} is the adjacency matrix of the array to be plotted and @var{xy} is
an @var{n}-by-2 matrix containing the coordinates of the nodes of the graph.

The optional parameter @var{line_style} defines the output style for the
plot.  Called with no output arguments the graph is plotted directly.
Otherwise, return the coordinates of the plot in @var{x} and @var{y}.
@seealso{treeplot, etreeplot, spy}
@end deftypefn
ichol
@c ichol scripts/sparse/ichol.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{L} =} ichol (@var{A})
@deftypefnx {Function File} {@var{L} =} ichol (@var{A}, @var{opts})

Compute the incomplete Cholesky factorization of the sparse square matrix
@var{A}.

By default, @code{ichol} uses only the lower triangle of @var{A} and
produces a lower triangular factor @var{L} such that @tcode{L*L'}
approximates @var{A}.

The factor given by this routine may be useful as a preconditioner for a
system of linear equations being solved by iterative methods such as
PCG (Preconditioned Conjugate Gradient).

The factorization may be modified by passing options in a structure
@var{opts}.  The option name is a field of the structure and the setting
is the value of field.  Names and specifiers are case sensitive.

@table @asis
@item type
Type of factorization.

@table @asis
@item @qcode{"nofill"} (default)
Incomplete Cholesky factorization with no fill-in (@nospell{IC(0)}).

@item @qcode{"ict"}
Incomplete Cholesky factorization with threshold dropping (@nospell{ICT}).
@end table

@item diagcomp
A non-negative scalar @var{alpha} for incomplete Cholesky factorization of
@code{@var{A} + @var{alpha} * diag (diag (@var{A}))} instead of @var{A}.
This can be useful when @var{A} is not positive definite.  The default value
is 0.

@item droptol
A non-negative scalar specifying the drop tolerance for factorization if
performing @nospell{ICT}@.  The default value is 0 which produces the
complete Cholesky factorization.

Non-diagonal entries of @var{L} are set to 0 unless

@code{abs (@var{L}(i,j)) >= droptol * norm (@var{A}(j:end, j), 1)}.

@item michol
Modified incomplete Cholesky factorization:

@table @asis
@item @qcode{"off"} (default)
Row and column sums are not necessarily preserved.

@item @qcode{"on"}
The diagonal of @var{L} is modified so that row (and column) sums are
preserved even when elements have been dropped during the factorization.
The relationship preserved is: @code{@var{A} * e = @var{L} * @var{L}' * e},
where e is a vector of ones.
@end table

@item shape

@table @asis
@item @qcode{"lower"} (default)
Use only the lower triangle of @var{A} and return a lower triangular factor
@var{L} such that @tcode{L*L'} approximates @var{A}.

@item @qcode{"upper"}
Use only the upper triangle of @var{A} and return an upper triangular factor
@var{U} such that @code{U'*U} approximates @var{A}.
@end table
@end table

EXAMPLES

The following problem demonstrates how to factorize a sample symmetric
positive definite matrix with the full Cholesky decomposition and with the
incomplete one.

@example
@group
A = [ 0.37, -0.05,  -0.05,  -0.07;
     -0.05,  0.116,  0.0,   -0.05;
     -0.05,  0.0,    0.116, -0.05;
     -0.07, -0.05,  -0.05,   0.202];
A = sparse (A);
nnz (tril (A))
ans =  9
L = chol (A, "lower");
nnz (L)
ans =  10
norm (A - L * L', "fro") / norm (A, "fro")
ans =  1.1993e-16
opts.type = "nofill";
L = ichol (A, opts);
nnz (L)
ans =  9
norm (A - L * L', "fro") / norm (A, "fro")
ans =  0.019736
@end group
@end example

Another example for decomposition is a finite difference matrix used to
solve a boundary value problem on the unit square.

@example
@group
nx = 400; ny = 200;
hx = 1 / (nx + 1); hy = 1 / (ny + 1);
Dxx = spdiags ([ones(nx, 1), -2*ones(nx, 1), ones(nx, 1)],
               [-1 0 1 ], nx, nx) / (hx ^ 2);
Dyy = spdiags ([ones(ny, 1), -2*ones(ny, 1), ones(ny, 1)],
               [-1 0 1 ], ny, ny) / (hy ^ 2);
A = -kron (Dxx, speye (ny)) - kron (speye (nx), Dyy);
nnz (tril (A))
ans =  239400
opts.type = "nofill";
L = ichol (A, opts);
nnz (tril (A))
ans =  239400
norm (A - L * L', "fro") / norm (A, "fro")
ans =  0.062327
@end group
@end example

References for implemented algorithms:

[1] @nospell{Y. Saad}. "Preconditioning Techniques." @cite{Iterative
Methods for Sparse Linear Systems}, @nospell{PWS} Publishing Company, 1996.

[2] @nospell{M. Jones, P. Plassmann}: @cite{An Improved Incomplete
Cholesky Factorization}, 1992.
@seealso{chol, ilu, pcg}
@end deftypefn
ilu
@c ilu scripts/sparse/ilu.m
-*- texinfo -*-
@deftypefn  {Function File} {} ilu (@var{A})
@deftypefnx {Function File} {} ilu (@var{A}, @var{opts})
@deftypefnx {Function File} {[@var{L}, @var{U}] =} ilu (@dots{})
@deftypefnx {Function File} {[@var{L}, @var{U}, @var{P}] =} ilu (@dots{})

Compute the incomplete LU factorization of the sparse square matrix @var{A}.

@code{ilu} returns a unit lower triangular matrix @var{L}, an upper
triangular matrix @var{U}, and optionally a permutation matrix @var{P}, such
that @code{@var{L}*@var{U}} approximates @code{@var{P}*@var{A}}.

The factors given by this routine may be useful as preconditioners for a
system of linear equations being solved by iterative methods such as BICG
(BiConjugate Gradients) or GMRES (Generalized Minimum Residual Method).

The factorization may be modified by passing options in a structure
@var{opts}.  The option name is a field of the structure and the setting
is the value of field.  Names and specifiers are case sensitive.

@table @code
@item type
Type of factorization.

@table @asis
@item @qcode{"nofill"}
ILU factorization with no fill-in (ILU(0)).

Additional supported options: @code{milu}.

@item @qcode{"crout"}
Crout version of ILU factorization (@nospell{ILUC}).

Additional supported options: @code{milu}, @code{droptol}.

@item @qcode{"ilutp"} (default)
ILU factorization with threshold and pivoting.

Additional supported options: @code{milu}, @code{droptol}, @code{udiag},
@code{thresh}.
@end table

@item droptol
A non-negative scalar specifying the drop tolerance for factorization.  The
default value is 0 which produces the complete LU factorization.

Non-diagonal entries of @var{U} are set to 0 unless

@code{abs (@var{U}(i,j)) >= droptol * norm (@var{A}(:,j))}.

Non-diagonal entries of @var{L} are set to 0 unless

@code{abs (@var{L}(i,j)) >= droptol * norm (@var{A}(:,j))/@var{U}(j,j)}.

@item milu
Modified incomplete LU factorization:

@table @asis
@item @qcode{"row"}
Row-sum modified incomplete LU factorization.
The factorization preserves row sums:
@code{@var{A} * e = @var{L} * @var{U} * e}, where e is a vector of ones.

@item @qcode{"col"}
Column-sum modified incomplete LU factorization.
The factorization preserves column sums:
@code{e' * @var{A} = e' * @var{L} * @var{U}}.

@item @qcode{"off"} (default)
Row and column sums are not necessarily preserved.
@end table

@item udiag
If true, any zeros on the diagonal of the upper triangular factor are
replaced by the local drop tolerance
@code{droptol * norm (@var{A}(:,j))/@var{U}(j,j)}.  The default is false.

@item thresh
Pivot threshold for factorization.  It can range between 0 (diagonal
pivoting) and 1 (default), where the maximum magnitude entry in the column
is chosen to be the pivot.
@end table

If @code{ilu} is called with just one output, the returned matrix is
@code{@var{L} + @var{U} - speye (size (@var{A}))}, where @var{L} is unit
lower triangular and @var{U} is upper triangular.

With two outputs, @code{ilu} returns a unit lower triangular matrix @var{L}
and an upper triangular matrix @var{U}.  For @var{opts}.type ==
@qcode{"ilutp"}, one of the factors is permuted based on the value of
@var{opts}.milu.  When @var{opts}.milu == @qcode{"row"}, @var{U} is a
column permuted upper triangular factor.  Otherwise, @var{L} is a
row-permuted unit lower triangular factor.

If there are three named outputs and @var{opts}.milu != @qcode{"row"},
@var{P} is returned such that @var{L} and @var{U} are incomplete factors
of @code{@var{P}*@var{A}}.  When @var{opts}.milu == @qcode{"row"}, @var{P}
is returned such that @var{L} and @var{U} are incomplete factors of
@code{@var{A}*@var{P}}.

EXAMPLES

@example
@group
A = gallery ("neumann", 1600) + speye (1600);
opts.type = "nofill";
nnz (A)
ans = 7840

nnz (lu (A))
ans = 126478

nnz (ilu (A, opts))
ans = 7840
@end group
@end example

This shows that @var{A} has 7,840 nonzeros, the complete LU factorization
has 126,478 nonzeros, and the incomplete LU factorization, with 0 level of
fill-in, has 7,840 nonzeros, the same amount as @var{A}.  Taken from:
http://www.mathworks.com/help/matlab/ref/ilu.html

@example
@group
A = gallery ("wathen", 10, 10);
b = sum (A, 2);
tol = 1e-8;
maxit = 50;
opts.type = "crout";
opts.droptol = 1e-4;
[L, U] = ilu (A, opts);
x = bicg (A, b, tol, maxit, L, U);
norm (A * x - b, inf)
@end group
@end example

This example uses ILU as preconditioner for a random FEM-Matrix, which has a
large condition number.  Without @var{L} and @var{U} BICG would not converge.

@seealso{lu, ichol, bicg, gmres}
@end deftypefn
nonzeros
@c nonzeros scripts/sparse/nonzeros.m
-*- texinfo -*-
@deftypefn {Function File} {} nonzeros (@var{s})
Return a vector of the nonzero values of the sparse matrix @var{s}.
@seealso{find, nnz}
@end deftypefn
pcg
@c pcg scripts/sparse/pcg.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} pcg (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{m1}, @var{m2}, @var{x0}, @dots{})
@deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}, @var{eigest}] =} pcg (@dots{})

Solve the linear system of equations @w{@code{@var{A} * @var{x} = @var{b}}}
by means of the Preconditioned Conjugate Gradient iterative method.

The input arguments are

@itemize
@item
@var{A} can be either a square (preferably sparse) matrix or a function
handle, inline function or string containing the name of a function which
computes @w{@code{@var{A} * @var{x}}}.  In principle, @var{A} should be
symmetric and positive definite; if @code{pcg} finds @var{A} not to be
positive definite, a warning is printed and the @var{flag} output will be
set.

@item
@var{b} is the right-hand side vector.

@item
@var{tol} is the required relative tolerance for the residual error,
@w{@code{@var{b} - @var{A} * @var{x}}}.  The iteration stops if
@w{@code{norm (@var{b} - @var{A} * @var{x})} @leq{}
@w{@var{tol} * norm (@var{b})}}.
If @var{tol} is omitted or empty then a tolerance of 1e-6 is used.

@item
@var{maxit} is the maximum allowable number of iterations; if @var{maxit}
is omitted or empty then a value of 20 is used.

@item
@var{m} = @var{m1} * @var{m2} is the (left) preconditioning matrix, so that
the iteration is (theoretically) equivalent to solving by @code{pcg}
@w{@code{@var{P} * @var{x} = @var{m} \ @var{b}}}, with
@w{@code{@var{P} = @var{m} \ @var{A}}}.
Note that a proper choice of the preconditioner may dramatically improve
the overall performance of the method.  Instead of matrices @var{m1} and
@var{m2}, the user may pass two functions which return the results of
applying the inverse of @var{m1} and @var{m2} to a vector (usually this is
the preferred way of using the preconditioner).  If @var{m1} is omitted or
empty @code{[]} then no preconditioning is applied.  If @var{m2} is
omitted, @var{m} = @var{m1} will be used as a preconditioner.

@item
@var{x0} is the initial guess.  If @var{x0} is omitted or empty then the
function sets @var{x0} to a zero vector by default.
@end itemize

The arguments which follow @var{x0} are treated as parameters, and passed in
a proper way to any of the functions (@var{A} or @var{m}) which are passed
to @code{pcg}.  See the examples below for further details.  The output
arguments are

@itemize
@item
@var{x} is the computed approximation to the solution of
@w{@code{@var{A} * @var{x} = @var{b}}}.

@item
@var{flag} reports on the convergence.  A value of 0 means the solution
converged and the tolerance criterion given by @var{tol} is satisfied.
A value of 1 means that the @var{maxit} limit for the iteration count was
reached.  A value of 3 indicates that the (preconditioned) matrix was found
not to be positive definite.

@item
@var{relres} is the ratio of the final residual to its initial value,
measured in the Euclidean norm.

@item
@var{iter} is the actual number of iterations performed.

@item
@var{resvec} describes the convergence history of the method.
@code{@var{resvec}(i,1)} is the Euclidean norm of the residual, and
@code{@var{resvec}(i,2)} is the preconditioned residual norm, after the
(@var{i}-1)-th iteration, @code{@var{i} = 1, 2, @dots{}, @var{iter}+1}.
The preconditioned residual norm is defined as
@code{norm (@var{r}) ^ 2 = @var{r}' * (@var{m} \ @var{r})} where
@code{@var{r} = @var{b} - @var{A} * @var{x}}, see also the
description of @var{m}.  If @var{eigest} is not required, only
@code{@var{resvec}(:,1)} is returned.

@item
@var{eigest} returns the estimate for the smallest @code{@var{eigest}(1)}
and largest @code{@var{eigest}(2)} eigenvalues of the preconditioned matrix
@w{@code{@var{P} = @var{m} \ @var{A}}}.  In particular, if no
preconditioning is used, the estimates for the extreme eigenvalues of
@var{A} are returned.  @code{@var{eigest}(1)} is an overestimate and
@code{@var{eigest}(2)} is an underestimate, so that
@code{@var{eigest}(2) / @var{eigest}(1)} is a lower bound for
@code{cond (@var{P}, 2)}, which nevertheless in the limit should
theoretically be equal to the actual value of the condition number.
The method which computes @var{eigest} works only for symmetric positive
definite @var{A} and @var{m}, and the user is responsible for verifying this
assumption.
@end itemize

Let us consider a trivial problem with a diagonal matrix (we exploit the
sparsity of A)

@example
@group
n = 10;
A = diag (sparse (1:n));
b = rand (n, 1);
[l, u, p] = ilu (A, struct ("droptol", 1.e-3));
@end group
@end example

@sc{Example 1:} Simplest use of @code{pcg}

@example
x = pcg (A, b)
@end example

@sc{Example 2:} @code{pcg} with a function which computes
@code{@var{A} * @var{x}}

@example
@group
function y = apply_a (x)
  y = [1:N]' .* x;
endfunction

x = pcg ("apply_a", b)
@end group
@end example

@sc{Example 3:} @code{pcg} with a preconditioner: @var{l} * @var{u}

@example
x = pcg (A, b, 1.e-6, 500, l*u)
@end example

@sc{Example 4:} @code{pcg} with a preconditioner: @var{l} * @var{u}.
Faster than @sc{Example 3} since lower and upper triangular matrices are
easier to invert

@example
x = pcg (A, b, 1.e-6, 500, l, u)
@end example

@sc{Example 5:} Preconditioned iteration, with full diagnostics.  The
preconditioner (quite strange, because even the original matrix @var{A} is
trivial) is defined as a function

@example
@group
function y = apply_m (x)
  k = floor (length (x) - 2);
  y = x;
  y(1:k) = x(1:k) ./ [1:k]';
endfunction

[x, flag, relres, iter, resvec, eigest] = ...
                   pcg (A, b, [], [], "apply_m");
semilogy (1:iter+1, resvec);
@end group
@end example

@sc{Example 6:} Finally, a preconditioner which depends on a parameter
@var{k}.

@example
@group
function y = apply_M (x, varargin)
  K = varargin@{1@};
  y = x;
  y(1:K) = x(1:K) ./ [1:K]';
endfunction

[x, flag, relres, iter, resvec, eigest] = ...
     pcg (A, b, [], [], "apply_m", [], [], 3)
@end group
@end example

References:

@enumerate
@item
C.T. Kelley, @cite{Iterative Methods for Linear and Nonlinear Equations},
SIAM, 1995. (the base PCG algorithm)

@item
@nospell{Y. Saad}, @cite{Iterative Methods for Sparse Linear Systems},
@nospell{PWS} 1996. (condition number estimate from PCG)
Revised version of this book is available online at
@url{http://www-users.cs.umn.edu/~saad/books.html}
@end enumerate

@seealso{sparse, pcr}
@end deftypefn
pcr
@c pcr scripts/sparse/pcr.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} pcr (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{m}, @var{x0}, @dots{})
@deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} pcr (@dots{})

Solve the linear system of equations @code{@var{A} * @var{x} = @var{b}} by
means of the Preconditioned Conjugate Residuals iterative method.

The input arguments are

@itemize
@item
@var{A} can be either a square (preferably sparse) matrix or a function
handle, inline function or string containing the name of a function which
computes @code{@var{A} * @var{x}}.  In principle @var{A} should be
symmetric and non-singular; if @code{pcr} finds @var{A} to be numerically
singular, you will get a warning message and the @var{flag} output
parameter will be set.

@item
@var{b} is the right hand side vector.

@item
@var{tol} is the required relative tolerance for the residual error,
@code{@var{b} - @var{A} * @var{x}}.  The iteration stops if
@code{norm (@var{b} - @var{A} * @var{x}) <=
@var{tol} * norm (@var{b} - @var{A} * @var{x0})}.
If @var{tol} is empty or is omitted, the function sets
@code{@var{tol} = 1e-6} by default.

@item
@var{maxit} is the maximum allowable number of iterations; if @code{[]} is
supplied for @code{maxit}, or @code{pcr} has less arguments, a default
value equal to 20 is used.

@item
@var{m} is the (left) preconditioning matrix, so that the iteration is
(theoretically) equivalent to solving by
@code{pcr} @code{@var{P} * @var{x} = @var{m} \ @var{b}}, with
@code{@var{P} = @var{m} \ @var{A}}.  Note that a proper choice of the
preconditioner may dramatically improve the overall performance of the
method.  Instead of matrix @var{m}, the user may pass a function which
returns the results of applying the inverse of @var{m} to a vector
(usually this is the preferred way of using the preconditioner).  If
@code{[]} is supplied for @var{m}, or @var{m} is omitted, no
preconditioning is applied.

@item
@var{x0} is the initial guess.  If @var{x0} is empty or omitted, the
function sets @var{x0} to a zero vector by default.
@end itemize

The arguments which follow @var{x0} are treated as parameters, and passed
in a proper way to any of the functions (@var{A} or @var{m}) which are
passed to @code{pcr}.  See the examples below for further details.

The output arguments are

@itemize
@item
@var{x} is the computed approximation to the solution of
@code{@var{A} * @var{x} = @var{b}}.

@item
@var{flag} reports on the convergence.  @code{@var{flag} = 0} means the
solution converged and the tolerance criterion given by @var{tol} is
satisfied.  @code{@var{flag} = 1} means that the @var{maxit} limit for the
iteration count was reached.  @code{@var{flag} = 3} reports a @code{pcr}
breakdown, see [1] for details.

@item
@var{relres} is the ratio of the final residual to its initial value,
measured in the Euclidean norm.

@item
@var{iter} is the actual number of iterations performed.

@item
@var{resvec} describes the convergence history of the method, so that
@code{@var{resvec} (i)} contains the Euclidean norms of the residual after
the (@var{i}-1)-th iteration, @code{@var{i} = 1,2, @dots{}, @var{iter}+1}.
@end itemize

Let us consider a trivial problem with a diagonal matrix (we exploit the
sparsity of A)

@example
@group
n = 10;
A = sparse (diag (1:n));
b = rand (N, 1);
@end group
@end example

@sc{Example 1:} Simplest use of @code{pcr}

@example
x = pcr (A, b)
@end example

@sc{Example 2:} @code{pcr} with a function which computes
@code{@var{A} * @var{x}}.

@example
@group
function y = apply_a (x)
  y = [1:10]' .* x;
endfunction

x = pcr ("apply_a", b)
@end group
@end example

@sc{Example 3:}  Preconditioned iteration, with full diagnostics.  The
preconditioner (quite strange, because even the original matrix
@var{A} is trivial) is defined as a function

@example
@group
function y = apply_m (x)
  k = floor (length (x) - 2);
  y = x;
  y(1:k) = x(1:k) ./ [1:k]';
endfunction

[x, flag, relres, iter, resvec] = ...
                   pcr (A, b, [], [], "apply_m")
semilogy ([1:iter+1], resvec);
@end group
@end example

@sc{Example 4:} Finally, a preconditioner which depends on a
parameter @var{k}.

@example
@group
function y = apply_m (x, varargin)
  k = varargin@{1@};
  y = x;
  y(1:k) = x(1:k) ./ [1:k]';
endfunction

[x, flag, relres, iter, resvec] = ...
                   pcr (A, b, [], [], "apply_m"', [], 3)
@end group
@end example

References:

[1] @nospell{W. Hackbusch}, @cite{Iterative Solution of Large Sparse
Systems of Equations}, section 9.5.4; Springer, 1994

@seealso{sparse, pcg}
@end deftypefn
qmr
@c qmr scripts/sparse/qmr.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} qmr (@var{A}, @var{b}, @var{rtol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0})
@deftypefnx {Function File} {@var{x} =} qmr (@var{A}, @var{b}, @var{rtol}, @var{maxit}, @var{P})
@deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} qmr (@var{A}, @var{b}, @dots{})
Solve @code{A x = b} using the Quasi-Minimal Residual iterative method
(without look-ahead).

@itemize @minus
@item @var{rtol} is the relative tolerance, if not given or set to [] the
default value 1e-6 is used.

@item @var{maxit} the maximum number of outer iterations, if not given or
set to [] the default value @code{min (20, numel (b))} is used.

@item @var{x0} the initial guess, if not given or set to [] the default
value @code{zeros (size (b))} is used.
@end itemize

@var{A} can be passed as a matrix or as a function handle or inline
function @code{f} such that @code{f(x, "notransp") = A*x} and
@code{f(x, "transp") = A'*x}.

The preconditioner @var{P} is given as @code{P = M1 * M2}.  Both @var{M1}
and @var{M2} can be passed as a matrix or as a function handle or inline
function @code{g} such that @code{g(x, "notransp") = M1 \ x} or
@code{g(x, "notransp") = M2 \ x} and @code{g(x, "transp") = M1' \ x} or
@code{g(x, "transp") = M2' \ x}.

If called with more than one output parameter

@itemize @minus
@item @var{flag} indicates the exit status:

@itemize @minus
@item 0: iteration converged to the within the chosen tolerance

@item 1: the maximum number of iterations was reached before convergence

@item 3: the algorithm reached stagnation
@end itemize

(the value 2 is unused but skipped for compatibility).

@item @var{relres} is the final value of the relative residual.

@item @var{iter} is the number of iterations performed.

@item @var{resvec} is a vector containing the residual norms at each
      iteration.
@end itemize

References:

@enumerate
@item
@nospell{R. Freund and N. Nachtigal}, @cite{QMR: a quasi-minimal residual
method for non-Hermitian linear systems}, @nospell{Numerische Mathematik},
1991, 60, pp. 315-339.

@item
@nospell{ R. Barrett, M. Berry, T. Chan, J. Demmel, J. Donato, J. Dongarra},
@nospell{ V. Eijkhour, R. Pozo, C. Romine, and H. van der Vorst},
@cite{Templates for the solution of linear systems: Building blocks
for iterative methods}, SIAM, 2nd ed., 1994.
@end enumerate

@seealso{bicg, bicgstab, cgs, gmres, pcg}
@end deftypefn
spaugment
@c spaugment scripts/sparse/spaugment.m
-*- texinfo -*-
@deftypefn {Function File} {@var{s} =} spaugment (@var{A}, @var{c})
Create the augmented matrix of @var{A}.

This is given by

@example
@group
[@var{c} * eye(@var{m}, @var{m}), @var{A};
            @var{A}', zeros(@var{n}, @var{n})]
@end group
@end example

@noindent
This is related to the least squares solution of
@code{@var{A} \ @var{b}}, by

@example
@group
@var{s} * [ @var{r} / @var{c}; x] = [ @var{b}, zeros(@var{n}, columns(@var{b})) ]
@end group
@end example

@noindent
where @var{r} is the residual error

@example
@var{r} = @var{b} - @var{A} * @var{x}
@end example

As the matrix @var{s} is symmetric indefinite it can be factorized with
@code{lu}, and the minimum norm solution can therefore be found without the
need for a @code{qr} factorization.  As the residual error will be
@code{zeros (@var{m}, @var{m})} for underdetermined problems, and example
can be

@example
@group
m = 11; n = 10; mn = max (m, n);
A = spdiags ([ones(mn,1), 10*ones(mn,1), -ones(mn,1)],
             [-1, 0, 1], m, n);
x0 = A \ ones (m,1);
s = spaugment (A);
[L, U, P, Q] = lu (s);
x1 = Q * (U \ (L \ (P  * [ones(m,1); zeros(n,1)])));
x1 = x1(end - n + 1 : end);
@end group
@end example

To find the solution of an overdetermined problem needs an estimate of the
residual error @var{r} and so it is more complex to formulate a minimum norm
solution using the @code{spaugment} function.

In general the left division operator is more stable and faster than using
the @code{spaugment} function.
@seealso{mldivide}
@end deftypefn
spconvert
@c spconvert scripts/sparse/spconvert.m
-*- texinfo -*-
@deftypefn {Function File} {@var{x} =} spconvert (@var{m})
Convert a simple sparse matrix format easily generated by other programs
into Octave's internal sparse format.

The input @var{m} is either a 3 or 4 column real matrix, containing the
row, column, real, and imaginary parts of the elements of the sparse
matrix.  An element with a zero real and imaginary part can be used to
force a particular matrix size.
@seealso{sparse}
@end deftypefn
spdiags
@c spdiags scripts/sparse/spdiags.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{B} =} spdiags (@var{A})
@deftypefnx {Function File} {[@var{B}, @var{d}] =} spdiags (@var{A})
@deftypefnx {Function File} {@var{B} =} spdiags (@var{A}, @var{d})
@deftypefnx {Function File} {@var{A} =} spdiags (@var{v}, @var{d}, @var{A})
@deftypefnx {Function File} {@var{A} =} spdiags (@var{v}, @var{d}, @var{m}, @var{n})
A generalization of the function @code{diag}.

Called with a single input argument, the nonzero diagonals @var{d} of
@var{A} are extracted.

With two arguments the diagonals to extract are given by the vector @var{d}.

The other two forms of @code{spdiags} modify the input matrix by replacing
the diagonals.  They use the columns of @var{v} to replace the diagonals
represented by the vector @var{d}.  If the sparse matrix @var{A} is
defined then the diagonals of this matrix are replaced.  Otherwise a
matrix of @var{m} by @var{n} is created with the diagonals given by the
columns of @var{v}.

Negative values of @var{d} represent diagonals below the main diagonal, and
positive values of @var{d} diagonals above the main diagonal.

For example:

@example
@group
spdiags (reshape (1:12, 4, 3), [-1 0 1], 5, 4)
   @result{} 5 10  0  0
      1  6 11  0
      0  2  7 12
      0  0  3  8
      0  0  0  4
@end group
@end example

@seealso{diag}
@end deftypefn
speye
@c speye scripts/sparse/speye.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{s} =} speye (@var{m}, @var{n})
@deftypefnx {Function File} {@var{s} =} speye (@var{m})
@deftypefnx {Function File} {@var{s} =} speye (@var{sz})
Return a sparse identity matrix of size @var{m}x@var{n}.

The implementation is significantly more efficient than
@code{sparse (eye (@var{m}))} as the full matrix is not constructed.

Called with a single argument a square matrix of size
@var{m}-by-@var{m} is created.  If called with a single vector argument
@var{sz}, this argument is taken to be the size of the matrix to create.
@seealso{sparse, spdiags, eye}
@end deftypefn
spfun
@c spfun scripts/sparse/spfun.m
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} spfun (@var{f}, @var{S})
Compute @code{f(@var{S})} for the nonzero values of @var{S}.

This results in a sparse matrix with the same structure as @var{S}.  The
function @var{f} can be passed as a string, a function handle, or an
inline function.
@seealso{arrayfun, cellfun, structfun}
@end deftypefn
spones
@c spones scripts/sparse/spones.m
-*- texinfo -*-
@deftypefn {Function File} {@var{r} =} spones (@var{S})
Replace the nonzero entries of @var{S} with ones.

This creates a sparse matrix with the same structure as @var{S}.
@seealso{sparse, sprand, sprandn, sprandsym, spfun, spy}
@end deftypefn
sprand
@c sprand scripts/sparse/sprand.m
-*- texinfo -*-
@deftypefn  {Function File} {} sprand (@var{m}, @var{n}, @var{d})
@deftypefnx {Function File} {} sprand (@var{m}, @var{n}, @var{d}, @var{rc})
@deftypefnx {Function File} {} sprand (@var{s})
Generate a sparse matrix with uniformly distributed random values.

The size of the matrix is @var{m}x@var{n} with a density of values @var{d}.
@var{d} must be between 0 and 1.  Values will be uniformly distributed on
the interval (0, 1).

If called with a single matrix argument, a sparse matrix is generated with
random values wherever the matrix @var{s} is nonzero.

If called with a scalar fourth argument @var{rc}, a random sparse matrix
with reciprocal condition number @var{rc} is generated.  If @var{rc} is
a vector, then it specifies the first singular values of the generated
matrix (@code{length (@var{rc}) <= min (@var{m}, @var{n})}).

@seealso{sprandn, sprandsym, rand}
@end deftypefn
sprandn
@c sprandn scripts/sparse/sprandn.m
-*- texinfo -*-
@deftypefn  {Function File} {} sprandn (@var{m}, @var{n}, @var{d})
@deftypefnx {Function File} {} sprandn (@var{m}, @var{n}, @var{d}, @var{rc})
@deftypefnx {Function File} {} sprandn (@var{s})
Generate a sparse matrix with normally distributed random values.

The size of the matrix is @var{m}x@var{n} with a density of values @var{d}.
@var{d} must be between 0 and 1.  Values will be normally distributed with a
mean of 0 and a variance of 1.

If called with a single matrix argument, a sparse matrix is generated with
random values wherever the matrix @var{s} is nonzero.

If called with a scalar fourth argument @var{rc}, a random sparse matrix
with reciprocal condition number @var{rc} is generated.  If @var{rc} is
a vector, then it specifies the first singular values of the generated
matrix (@code{length (@var{rc}) <= min (@var{m}, @var{n})}).

@seealso{sprand, sprandsym, randn}
@end deftypefn
sprandsym
@c sprandsym scripts/sparse/sprandsym.m
-*- texinfo -*-
@deftypefn  {Function File} {} sprandsym (@var{n}, @var{d})
@deftypefnx {Function File} {} sprandsym (@var{s})
Generate a symmetric random sparse matrix.

The size of the matrix will be @var{n}x@var{n}, with a density of values
given by @var{d}.  @var{d} must be between 0 and 1 inclusive.  Values will
be normally distributed with a mean of zero and a variance of 1.

If called with a single matrix argument, a random sparse matrix is generated
wherever the matrix @var{s} is nonzero in its lower triangular part.
@seealso{sprand, sprandn, spones, sparse}
@end deftypefn
spstats
@c spstats scripts/sparse/spstats.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{count}, @var{mean}, @var{var}] =} spstats (@var{S})
@deftypefnx {Function File} {[@var{count}, @var{mean}, @var{var}] =} spstats (@var{S}, @var{j})
Return the stats for the nonzero elements of the sparse matrix @var{S}.

@var{count} is the number of nonzeros in each column, @var{mean} is the mean
of the nonzeros in each column, and @var{var} is the variance of the
nonzeros in each column.

Called with two input arguments, if @var{S} is the data and @var{j} is the
bin number for the data, compute the stats for each bin.  In this case,
bins can contain data values of zero, whereas with
@code{spstats (@var{S})} the zeros may disappear.
@end deftypefn
spy
@c spy scripts/sparse/spy.m
-*- texinfo -*-
@deftypefn  {Function File} {} spy (@var{x})
@deftypefnx {Function File} {} spy (@dots{}, @var{markersize})
@deftypefnx {Function File} {} spy (@dots{}, @var{line_spec})
Plot the sparsity pattern of the sparse matrix @var{x}.

If the argument @var{markersize} is given as a scalar value, it is used to
determine the point size in the plot.

If the string @var{line_spec} is given it is passed to @code{plot} and
determines the appearance of the plot.
@seealso{plot, gplot}
@end deftypefn
svds
@c svds scripts/sparse/svds.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{s} =} svds (@var{A})
@deftypefnx {Function File} {@var{s} =} svds (@var{A}, @var{k})
@deftypefnx {Function File} {@var{s} =} svds (@var{A}, @var{k}, @var{sigma})
@deftypefnx {Function File} {@var{s} =} svds (@var{A}, @var{k}, @var{sigma}, @var{opts})
@deftypefnx {Function File} {[@var{u}, @var{s}, @var{v}] =} svds (@dots{})
@deftypefnx {Function File} {[@var{u}, @var{s}, @var{v}, @var{flag}] =} svds (@dots{})

Find a few singular values of the matrix @var{A}.

The singular values are calculated using

@example
@group
[@var{m}, @var{n}] = size (@var{A});
@var{s} = eigs ([sparse(@var{m}, @var{m}), @var{A};
                     @var{A}', sparse(@var{n}, @var{n})])
@end group
@end example

The eigenvalues returned by @code{eigs} correspond to the singular values
of @var{A}.  The number of singular values to calculate is given by @var{k}
and defaults to 6.

The argument @var{sigma} specifies which singular values to find.  When
@var{sigma} is the string @qcode{'L'}, the default, the largest singular
values of @var{A} are found.  Otherwise, @var{sigma} must be a real scalar
and the singular values closest to @var{sigma} are found.  As a corollary,
@code{@var{sigma} = 0} finds the smallest singular values.  Note that for
relatively small values of @var{sigma}, there is a chance that the
requested number of singular values will not be found.  In that case
@var{sigma} should be increased.

@var{opts} is a structure defining options that @code{svds} will pass
to @code{eigs}.  The possible fields of this structure are documented in
@code{eigs}.  By default, @code{svds} sets the following three fields:

@table @code
@item tol
The required convergence tolerance for the singular values.  The default
value is 1e-10.  @code{eigs} is passed @code{@var{tol} / sqrt(2)}.

@item maxit
The maximum number of iterations.  The default is 300.

@item disp
The level of diagnostic printout (0|1|2).  If @code{disp} is 0 then
diagnostics are disabled.  The default value is 0.
@end table

If more than one output is requested then @code{svds} will return an
approximation of the singular value decomposition of @var{A}

@example
@var{A}_approx = @var{u}*@var{s}*@var{v}'
@end example

@noindent
where @var{A}_approx is a matrix of size @var{A} but only rank @var{k}.

@var{flag} returns 0 if the algorithm has succesfully converged, and 1
otherwise.  The test for convergence is

@example
@group
norm (@var{A}*@var{v} - @var{u}*@var{s}, 1) <= @var{tol} * norm (@var{A}, 1)
@end group
@end example

@code{svds} is best for finding only a few singular values from a large
sparse matrix.  Otherwise, @code{svd (full (@var{A}))} will likely be more
efficient.
@end deftypefn
@seealso{svd, eigs}
treelayout
@c treelayout scripts/sparse/treelayout.m
-*- texinfo -*-
@deftypefn  {Function File} {} treelayout (@var{tree})
@deftypefnx {Function File} {} treelayout (@var{tree}, @var{permutation})
treelayout lays out a tree or a forest.

The first argument @var{tree} is a vector of predecessors.

The parameter @var{permutation} is an optional postorder permutation.

The complexity of the algorithm is O(n) in terms of time and memory
requirements.
@seealso{etreeplot, gplot, treeplot}
@end deftypefn
treeplot
@c treeplot scripts/sparse/treeplot.m
-*- texinfo -*-
@deftypefn  {Function File} {} treeplot (@var{tree})
@deftypefnx {Function File} {} treeplot (@var{tree}, @var{node_style}, @var{edge_style})
Produce a graph of tree or forest.

The first argument is vector of predecessors.

The optional parameters @var{node_style} and @var{edge_style} define the
output plot style.

The complexity of the algorithm is O(n) in terms of is time and memory
requirements.
@seealso{etreeplot, gplot}
@end deftypefn
bessel
@c bessel scripts/specfun/bessel.m
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{j}, @var{ierr}] =} besselj (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {Loadable Function} {[@var{y}, @var{ierr}] =} bessely (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {Loadable Function} {[@var{i}, @var{ierr}] =} besseli (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {Loadable Function} {[@var{k}, @var{ierr}] =} besselk (@var{alpha}, @var{x}, @var{opt})
@deftypefnx {Loadable Function} {[@var{h}, @var{ierr}] =} besselh (@var{alpha}, @var{k}, @var{x}, @var{opt})
Compute Bessel or Hankel functions of various kinds:

@table @code
@item besselj
Bessel functions of the first kind.  If the argument @var{opt} is supplied,
the result is multiplied by @code{exp (-abs (imag (x)))}.

@item bessely
Bessel functions of the second kind.  If the argument @var{opt} is supplied,
the result is multiplied by @w{@code{exp (-abs (imag (x)))}}.

@item besseli
Modified Bessel functions of the first kind.  If the argument @var{opt} is
supplied, the result is multiplied by @w{@code{exp (-abs (real (x)))}}.

@item besselk
Modified Bessel functions of the second kind.  If the argument @var{opt} is
supplied, the result is multiplied by @w{@code{exp (x)}}.

@item besselh
Compute Hankel functions of the first (@var{k} = 1) or second (@var{k} = 2)
kind.  If the argument @var{opt} is supplied, the result is multiplied by
@w{@code{exp (-I*@var{x})}} for @var{k} = 1 or @w{@code{exp (I*@var{x})}}
for @var{k} = 2.
@end table

If @var{alpha} is a scalar, the result is the same size as @var{x}.
If @var{x} is a scalar, the result is the same size as @var{alpha}.
If @var{alpha} is a row vector and @var{x} is a column vector, the
result is a matrix with @code{length (@var{x})} rows and
@code{length (@var{alpha})} columns.  Otherwise, @var{alpha} and
@var{x} must conform and the result will be the same size.

The value of @var{alpha} must be real.  The value of @var{x} may be complex.

If requested, @var{ierr} contains the following status information and is
the same size as the result.

@enumerate 0
@item
Normal return.

@item
Input error, return @code{NaN}.

@item
Overflow, return @code{Inf}.

@item
Loss of significance by argument reduction results in less than half of
machine accuracy.

@item
Complete loss of significance by argument reduction, return @code{NaN}.

@item
Error---no computation, algorithm termination condition not met,
return @code{NaN}.
@end enumerate
@end deftypefn
beta
@c beta scripts/specfun/beta.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} beta (@var{a}, @var{b})
Compute the Beta function for real inputs @var{a} and @var{b}.

The Beta function definition is
@tex
$$
 B (a, b) = {\Gamma (a) \Gamma (b) \over \Gamma (a + b)}.
$$
@end tex
@ifnottex

@example
beta (a, b) = gamma (a) * gamma (b) / gamma (a + b).
@end example

@end ifnottex

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.
@xref{XREFbetaln,,betaln}, for computing the logarithm of the Beta function
in an efficient manner.
@seealso{betaln, betainc, betaincinv}
@end deftypefn
betaln
@c betaln scripts/specfun/betaln.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} betaln (@var{a}, @var{b})
Compute the natural logarithm of the Beta function for real inputs @var{a}
and @var{b}.

@code{betaln} is defined as
@tex
$$
 {\rm betaln} (a, b) = \ln (B (a,b)) \equiv \ln ({\Gamma (a) \Gamma (b) \over \Gamma (a + b)}).
$$
@end tex
@ifnottex

@example
betaln (a, b) = log (beta (a, b))
@end example

@end ifnottex
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.
@seealso{beta, betainc, betaincinv, gammaln}
@end deftypefn
ellipke
@c ellipke scripts/specfun/ellipke.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{k} =} ellipke (@var{m})
@deftypefnx {Function File} {@var{k} =} ellipke (@var{m}, @var{tol})
@deftypefnx {Function File} {[@var{k}, @var{e}] =} ellipke (@dots{})
Compute complete elliptic integrals of the first K(@var{m}) and second
E(@var{m}) kind.

@var{m} must be a scalar or real array with -Inf @leq{} @var{m} @leq{} 1.

The optional input @var{tol} controls the stopping tolerance of the
algorithm and defaults to @code{eps (class (@var{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

@tex
$$
{\rm K} (m) = \int_0^1 {dt \over \sqrt{(1 - t^2) (1 - m t^2)}}
$$
@end tex
@ifnottex

@example
@group
         1
        /               dt
K (m) = | ------------------------------
        / sqrt ((1 - t^2)*(1 - m*t^2))
       0
@end group
@end example

@end ifnottex

Elliptic integrals of the second kind are defined as

@tex
$$
{\rm E} (m) = \int_0^1 {\sqrt{1 - m t^2} \over \sqrt{1 - t^2}} dt
$$
@end tex
@ifnottex

@example
@group
         1
        /  sqrt (1 - m*t^2)
E (m) = |  ------------------ dt
        /  sqrt (1 - t^2)
       0
@end group
@end example

@end ifnottex

Reference: Milton @nospell{Abramowitz} and Irene A. @nospell{Stegun},
@cite{Handbook of Mathematical Functions}, Chapter 17, Dover, 1965.
@seealso{ellipj}
@end deftypefn
expint
@c expint scripts/specfun/expint.m
-*- texinfo -*-
@deftypefn {Function File} {} expint (@var{x})
Compute the exponential integral:
@tex
$$
{\rm E_1} (x) = \int_x^\infty {e^{-t} \over t} dt
$$
@end tex
@ifnottex

@example
@group
           infinity
          /
E_1 (x) = | exp (-t)/t dt
          /
         x
@end group
@end example

@end ifnottex
Note: For compatibility, this functions uses the @sc{matlab} definition
of the exponential integral.  Most other sources refer to this particular
value as @math{E_1 (x)}, and the exponential integral as
@tex
$$
{\rm Ei} (x) = - \int_{-x}^\infty {e^{-t} \over t} dt.
$$
@end tex
@ifnottex

@example
@group
            infinity
           /
Ei (x) = - | exp (-t)/t dt
           /
         -x
@end group
@end example

@end ifnottex
The two definitions are related, for positive real values of @var{x}, by
@tex
$
E_1 (-x) = -{\rm Ei} (x) - i\pi.
$
@end tex
@ifnottex
@w{@code{E_1 (-x) = -Ei (x) - i*pi}}.
@end ifnottex
@end deftypefn
factor
@c factor scripts/specfun/factor.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{pf} =} factor (@var{q})
@deftypefnx {Function File} {[@var{pf}, @var{n}] =} factor (@var{q})
Return the prime factorization of @var{q}.

The prime factorization is defined as @code{prod (@var{pf}) == @var{q}}
where every element of @var{pf} is a prime number.  If @code{@var{q} == 1},
return 1.

With two output arguments, return the unique prime factors @var{pf} and
their multiplicities.  That is, @code{prod (@var{pf} .^ @var{n}) == @var{q}}.

Implementation Note: The input @var{q} must be less than
@code{bitmax} (9.0072e+15) in order to factor correctly.
@seealso{gcd, lcm, isprime, primes}
@end deftypefn
factorial
@c factorial scripts/specfun/factorial.m
-*- texinfo -*-
@deftypefn {Function File} {} factorial (@var{n})
Return the factorial of @var{n} where @var{n} is a real non-negative integer.

If @var{n} is a scalar, this is equivalent to @code{prod (1:@var{n})}.  For
vector or matrix arguments, return the factorial of each element in the
array.

For non-integers see the generalized factorial function @code{gamma}.
Note that the factorial function grows large quite quickly, and even
with double precision values overflow will occur if @var{n} > 171.  For
such cases consider @code{gammaln}.
@seealso{prod, gamma, gammaln}
@end deftypefn
isprime
@c isprime scripts/specfun/isprime.m
-*- texinfo -*-
@deftypefn {Function File} {} isprime (@var{x})
Return a logical array which is true where the elements of @var{x} are prime
numbers and false where they are not.

A prime number is conventionally defined as a positive integer greater than
1 (e.g., 2, 3, @dots{}) which is divisible only by itself and 1.  Octave
extends this definition to include both negative integers and complex
values.  A negative integer is prime if its positive counterpart is prime.
This is equivalent to @code{isprime (abs (x))}.

If @code{class (@var{x})} is complex, then primality is tested in the domain
of Gaussian integers (@url{http://en.wikipedia.org/wiki/Gaussian_integer}).
Some non-complex integers are prime in the ordinary sense, but not in the
domain of Gaussian integers.  For example, @math{5 = (1+2i)*(1-2i)} shows
that 5 is not prime because it has a factor other than itself and 1.
Exercise caution when testing complex and real values together in the same
matrix.

Examples:

@example
@group
isprime (1:6)
    @result{} [0, 1, 1, 0, 1, 0]
@end group
@end example

@example
@group
isprime ([i, 2, 3, 5])
    @result{} [0, 0, 1, 0]
@end group
@end example

Programming Note: @code{isprime} is appropriate if the maximum value in
@var{x} is not too large (< 1e15).  For larger values special purpose
factorization code should be used.

Compatibility Note: @var{matlab} does not extend the definition of prime
numbers and will produce an error if given negative or complex inputs.
@seealso{primes, factor, gcd, lcm}
@end deftypefn
lcm
@c lcm scripts/specfun/lcm.m
-*- texinfo -*-
@deftypefn  {Mapping Function} {} lcm (@var{x}, @var{y})
@deftypefnx {Mapping Function} {} lcm (@var{x}, @var{y}, @dots{})
Compute the least common multiple of @var{x} and @var{y}, or of the list of
all arguments.

All elements must be numeric and of the same size or scalar.
@seealso{factor, gcd, isprime}
@end deftypefn
legendre
@c legendre scripts/specfun/legendre.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{l} =} legendre (@var{n}, @var{x})
@deftypefnx {Function File} {@var{l} =} legendre (@var{n}, @var{x}, @var{normalization})
Compute the Legendre function of degree @var{n} and order
@var{m} = 0 @dots{} @var{n}.

The value @var{n} must be a real non-negative integer.

@var{x} is a vector with real-valued elements in the range [-1, 1].

The optional argument @var{normalization} may be one of @qcode{"unnorm"},
@qcode{"sch"}, or @qcode{"norm"}.  The default if no normalization is given
is @qcode{"unnorm"}.

When the optional argument @var{normalization} is @qcode{"unnorm"}, compute
the Legendre function of degree @var{n} and order @var{m} and return all
values for @var{m} = 0 @dots{} @var{n}.  The return value has one dimension
more than @var{x}.

The Legendre Function of degree @var{n} and order @var{m}:

@tex
$$
P^m_n(x) = (-1)^m (1-x^2)^{m/2}{d^m\over {dx^m}}P_n (x)
$$
@end tex
@ifnottex

@example
@group
 m         m      2  m/2   d^m
P(x) = (-1) * (1-x  )    * ----  P(x)
 n                         dx^m   n
@end group
@end example

@end ifnottex

@noindent
with Legendre polynomial of degree @var{n}:

@tex
$$
P(x) = {1\over{2^n n!}}\biggl({d^n\over{dx^n}}(x^2 - 1)^n\biggr)
$$
@end tex
@ifnottex

@example
@group
          1    d^n   2    n
P(x) = ------ [----(x - 1) ]
 n     2^n n!  dx^n
@end group
@end example

@end ifnottex

@noindent
@code{legendre (3, [-1.0, -0.9, -0.8])} returns the matrix:

@example
@group
 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
@end group
@end example

When the optional argument @code{normalization} is @qcode{"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 @var{n} and order 0:

@tex
$$
SP^0_n (x) = P^0_n (x)
$$
@end tex
@ifnottex

@example
@group
  0      0
SP(x) = P(x)
  n      n
@end group
@end example

@end ifnottex

For Legendre functions of degree n and order m:

@tex
$$
SP^m_n (x) = P^m_n (x)(-1)^m\biggl({2(n-m)!\over{(n+m)!}}\biggl)^{0.5}
$$
@end tex
@ifnottex

@example
@group
  m      m         m    2(n-m)! 0.5
SP(x) = P(x) * (-1)  * [-------]
  n      n              (n+m)!
@end group
@end example

@end ifnottex

When the optional argument @var{normalization} is @qcode{"norm"}, compute
the fully normalized associated Legendre function.  The fully normalized
associated Legendre function is related to the unnormalized Legendre
functions by the following:

For Legendre functions of degree @var{n} and order @var{m}

@tex
$$
NP^m_n (x) = P^m_n (x)(-1)^m\biggl({(n+0.5)(n-m)!\over{(n+m)!}}\biggl)^{0.5}
$$
@end tex
@ifnottex

@example
@group
  m      m         m    (n+0.5)(n-m)! 0.5
NP(x) = P(x) * (-1)  * [-------------]
  n      n                  (n+m)!
@end group
@end example

@end ifnottex
@end deftypefn
nchoosek
@c nchoosek scripts/specfun/nchoosek.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{c} =} nchoosek (@var{n}, @var{k})
@deftypefnx {Function File} {@var{c} =} nchoosek (@var{set}, @var{k})

Compute the binomial coefficient of @var{n} or list all possible
combinations of a @var{set} of items.

If @var{n} is a scalar then calculate the binomial coefficient
of @var{n} and @var{k} which is defined as
@tex
$$
 {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
               = {n! \over k! (n-k)!}
$$
@end tex
@ifnottex

@example
@group
 /   \
 | n |    n (n-1) (n-2) @dots{} (n-k+1)       n!
 |   |  = ------------------------- =  ---------
 | k |               k!                k! (n-k)!
 \   /
@end group
@end example

@end ifnottex
@noindent
This is the number of combinations of @var{n} items taken in groups of
size @var{k}.

If the first argument is a vector, @var{set}, then generate all
combinations of the elements of @var{set}, taken @var{k} at a time, with
one row per combination.  The result @var{c} has @var{k} columns and
@w{@code{nchoosek (length (@var{set}), @var{k})}} rows.

For example:

How many ways can three items be grouped into pairs?

@example
@group
nchoosek (3, 2)
   @result{} 3
@end group
@end example

What are the possible pairs?

@example
@group
nchoosek (1:3, 2)
   @result{}  1   2
       1   3
       2   3
@end group
@end example

Programming Note: When calculating the binomial coefficient @code{nchoosek}
works only for non-negative, integer arguments.  Use @code{bincoeff} for
non-integer and negative scalar arguments, or for computing many binomial
coefficients at once with vector inputs for @var{n} or @var{k}.

@seealso{bincoeff, perms}
@end deftypefn
nthroot
@c nthroot scripts/specfun/nthroot.m
-*- texinfo -*-
@deftypefn {Function File} {} nthroot (@var{x}, @var{n})

Compute the real (non-complex) @var{n}-th root of @var{x}.

@var{x} must have all real entries and @var{n} must be a scalar.
If @var{n} is an even integer and @var{x} has negative entries then
@code{nthroot} aborts and issues an error.

Example:

@example
@group
nthroot (-1, 3)
@result{} -1
(-1) ^ (1 / 3)
@result{} 0.50000 - 0.86603i
@end group
@end example
@seealso{realsqrt, sqrt, cbrt}
@end deftypefn
perms
@c perms scripts/specfun/perms.m
-*- texinfo -*-
@deftypefn {Function File} {} perms (@var{v})
Generate all permutations of @var{v} with one row per permutation.

The result has size @code{factorial (@var{n}) * @var{n}}, where @var{n}
is the length of @var{v}.

Example

@example
@group
perms ([1, 2, 3])
@result{}
  1   2   3
  2   1   3
  1   3   2
  2   3   1
  3   1   2
  3   2   1
@end group
@end example

Programming Note: The maximum length of @var{v} should be less than or
equal to 10 to limit memory consumption.
@seealso{permute, randperm, nchoosek}
@end deftypefn
pow2
@c pow2 scripts/specfun/pow2.m
-*- texinfo -*-
@deftypefn  {Function File} {} pow2 (@var{x})
@deftypefnx {Function File} {} pow2 (@var{f}, @var{e})
With one input argument, compute
@tex
$2^x$
@end tex
@ifnottex
2 .^ x
@end ifnottex
for each element of @var{x}.

With two input arguments, return
@tex
$f \cdot 2^e$.
@end tex
@ifnottex
f .* (2 .^ e).
@end ifnottex
@seealso{log2, nextpow2, power}
@end deftypefn
primes
@c primes scripts/specfun/primes.m
-*- texinfo -*-
@deftypefn {Function File} {} primes (@var{n})
Return all primes up to @var{n}.

The output data class (double, single, uint32, etc.) is the same as the
input class of @var{n}.  The algorithm used is the Sieve of Eratosthenes.

Notes: If you need a specific number of primes you can use the fact that the
distance from one prime to the next is, on average, proportional to the
logarithm of the prime.  Integrating, one finds that there are about
@math{k} primes less than
@tex
$k \log (5 k)$.
@end tex
@ifnottex
k*log (5*k).
@end ifnottex

See also @code{list_primes} if you need a specific number @var{n} of primes.
@seealso{list_primes, isprime}
@end deftypefn
reallog
@c reallog scripts/specfun/reallog.m
-*- texinfo -*-
@deftypefn {Function File} {} reallog (@var{x})
Return the real-valued natural logarithm of each element of @var{x}.

If any element results in a complex return value @code{reallog} aborts and
issues an error.
@seealso{log, realpow, realsqrt}
@end deftypefn
realpow
@c realpow scripts/specfun/realpow.m
-*- texinfo -*-
@deftypefn {Function File} {} realpow (@var{x}, @var{y})
Compute the real-valued, element-by-element power operator.

This is equivalent to @w{@code{@var{x} .^ @var{y}}}, except that
@code{realpow} reports an error if any return value is complex.
@seealso{power, reallog, realsqrt}
@end deftypefn
realsqrt
@c realsqrt scripts/specfun/realsqrt.m
-*- texinfo -*-
@deftypefn {Function File} {} realsqrt (@var{x})
Return the real-valued square root of each element of @var{x}.

If any element results in a complex return value @code{realsqrt} aborts and
issues an error.
@seealso{sqrt, realpow, reallog}
@end deftypefn
gallery
@c gallery scripts/special-matrix/gallery.m
-*- texinfo -*-
@deftypefn  {Function File} {} gallery (@var{name})
@deftypefnx {Function File} {} gallery (@var{name}, @var{args})
Create interesting matrices for testing.

@end deftypefn

@deftypefn  {Function File} {@var{c} =} gallery ("cauchy", @var{x})
@deftypefnx {Function File} {@var{c} =} gallery ("cauchy", @var{x}, @var{y})
Create a Cauchy matrix.

@end deftypefn

@deftypefn  {Function File} {@var{c} =} gallery ("chebspec", @var{n})
@deftypefnx {Function File} {@var{c} =} gallery ("chebspec", @var{n}, @var{k})
Create a Chebyshev spectral differentiation matrix.

@end deftypefn

@deftypefn  {Function File} {@var{c} =} gallery ("chebvand", @var{p})
@deftypefnx {Function File} {@var{c} =} gallery ("chebvand", @var{m}, @var{p})
Create a Vandermonde-like matrix for the Chebyshev polynomials.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("chow", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("chow", @var{n}, @var{alpha})
@deftypefnx {Function File} {@var{a} =} gallery ("chow", @var{n}, @var{alpha}, @var{delta})
Create a Chow matrix -- a singular Toeplitz lower Hessenberg matrix.

@end deftypefn

@deftypefn {Function File} {@var{c} =} gallery ("circul", @var{v})
Create a circulant matrix.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("clement", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("clement", @var{n}, @var{k})
Create a tridiagonal matrix with zero diagonal entries.

@end deftypefn

@deftypefn  {Function File} {@var{c} =} gallery ("compar", @var{a})
@deftypefnx {Function File} {@var{c} =} gallery ("compar", @var{a}, @var{k})
Create a comparison matrix.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("condex", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("condex", @var{n}, @var{k})
@deftypefnx {Function File} {@var{a} =} gallery ("condex", @var{n}, @var{k}, @var{theta})
Create a `counterexample' matrix to a condition estimator.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("cycol", [@var{m} @var{n}])
@deftypefnx {Function File} {@var{a} =} gallery ("cycol", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery (@dots{}, @var{k})
Create a matrix whose columns repeat cyclically.

@end deftypefn

@deftypefn  {Function File} {[@var{c}, @var{d}, @var{e}] =} gallery ("dorr", @var{n})
@deftypefnx {Function File} {[@var{c}, @var{d}, @var{e}] =} gallery ("dorr", @var{n}, @var{theta})
@deftypefnx {Function File} {@var{a} =} gallery ("dorr", @dots{})
Create a diagonally dominant, ill-conditioned, tridiagonal matrix.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("dramadah", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("dramadah", @var{n}, @var{k})
Create a (0, 1) matrix whose inverse has large integer entries.

@end deftypefn

@deftypefn {Function File} {@var{a} =} gallery ("fiedler", @var{c})
Create a symmetric @nospell{Fiedler} matrix.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("forsythe", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("forsythe", @var{n}, @var{alpha})
@deftypefnx {Function File} {@var{a} =} gallery ("forsythe", @var{n}, @var{alpha}, @var{lambda})
Create a @nospell{Forsythe} matrix (a perturbed Jordan block).

@end deftypefn

@deftypefn  {Function File} {@var{f} =} gallery ("frank", @var{n})
@deftypefnx {Function File} {@var{f} =} gallery ("frank", @var{n}, @var{k})
Create a Frank matrix (ill-conditioned eigenvalues).

@end deftypefn

@deftypefn {Function File} {@var{c} =} gallery ("gcdmat", @var{n})
Create a greatest common divisor matrix.

@var{c} is an @var{n}-by-@var{n} matrix whose values correspond to the
greatest common divisor of its coordinate values, i.e., @var{c}(i,j)
correspond @code{gcd (i, j)}.
@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("gearmat", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("gearmat", @var{n}, @var{i})
@deftypefnx {Function File} {@var{a} =} gallery ("gearmat", @var{n}, @var{i}, @var{j})
Create a Gear matrix.

@end deftypefn

@deftypefn  {Function File} {@var{g} =} gallery ("grcar", @var{n})
@deftypefnx {Function File} {@var{g} =} gallery ("grcar", @var{n}, @var{k})
Create a Toeplitz matrix with sensitive eigenvalues.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("hanowa", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("hanowa", @var{n}, @var{d})
Create a matrix whose eigenvalues lie on a vertical line in the complex
plane.

@end deftypefn

@deftypefn  {Function File} {@var{v} =} gallery ("house", @var{x})
@deftypefnx {Function File} {[@var{v}, @var{beta}] =} gallery ("house", @var{x})
Create a householder matrix.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("integerdata", @var{imax}, [@var{M} @var{N} @dots{}], @var{j})
@deftypefnx {Function File} {@var{a} =} gallery ("integerdata", @var{imax}, @var{M}, @var{N}, @dots{}, @var{j})
@deftypefnx {Function File} {@var{a} =} gallery ("integerdata", [@var{imin}, @var{imax}], [@var{M} @var{N} @dots{}], @var{j})
@deftypefnx {Function File} {@var{a} =} gallery ("integerdata", [@var{imin}, @var{imax}], @var{M}, @var{N}, @dots{}, @var{j})
@deftypefnx {Function File} {@var{a} =} gallery ("integerdata", @dots{}, "@var{class}")
Create a matrix with random integers in the range [1, @var{imax}].
If @var{imin} is given then the integers are in the range
[@var{imin}, @var{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 @var{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 @var{j} index.

The final optional argument determines the class of the resulting matrix.
Possible values for @var{class}: @qcode{"uint8"}, @qcode{"uint16"},
@qcode{"uint32"}, @qcode{"int8"}, @qcode{"int16"}, int32", @qcode{"single"},
@qcode{"double"}.  The default is @qcode{"double"}.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("invhess", @var{x})
@deftypefnx {Function File} {@var{a} =} gallery ("invhess", @var{x}, @var{y})
Create the inverse of an upper Hessenberg matrix.

@end deftypefn

@deftypefn {Function File} {@var{a} =} gallery ("invol", @var{n})
Create an involutory matrix.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("ipjfact", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("ipjfact", @var{n}, @var{k})
Create a Hankel matrix with factorial elements.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("jordbloc", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("jordbloc", @var{n}, @var{lambda})
Create a Jordan block.

@end deftypefn

@deftypefn  {Function File} {@var{u} =} gallery ("kahan", @var{n})
@deftypefnx {Function File} {@var{u} =} gallery ("kahan", @var{n}, @var{theta})
@deftypefnx {Function File} {@var{u} =} gallery ("kahan", @var{n}, @var{theta}, @var{pert})
Create a @nospell{Kahan} matrix (upper trapezoidal).

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("kms", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("kms", @var{n}, @var{rho})
Create a @nospell{Kac-Murdock-Szego} Toeplitz matrix.

@end deftypefn

@deftypefn  {Function File} {@var{b} =} gallery ("krylov", @var{a})
@deftypefnx {Function File} {@var{b} =} gallery ("krylov", @var{a}, @var{x})
@deftypefnx {Function File} {@var{b} =} gallery ("krylov", @var{a}, @var{x}, @var{j})
Create a Krylov matrix.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("lauchli", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("lauchli", @var{n}, @var{mu})
Create a @nospell{Lauchli} matrix (rectangular).

@end deftypefn

@deftypefn {Function File} {@var{a} =} gallery ("lehmer", @var{n})
Create a @nospell{Lehmer} matrix (symmetric positive definite).

@end deftypefn

@deftypefn {Function File} {@var{t} =} gallery ("lesp", @var{n})
Create a tridiagonal matrix with real, sensitive eigenvalues.

@end deftypefn

@deftypefn {Function File} {@var{a} =} gallery ("lotkin", @var{n})
Create a @nospell{Lotkin} matrix.

@end deftypefn

@deftypefn {Function File} {@var{a} =} gallery ("minij", @var{n})
Create a symmetric positive definite matrix MIN(i,j).

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("moler", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("moler", @var{n}, @var{alpha})
Create a @nospell{Moler} matrix (symmetric positive definite).

@end deftypefn

@deftypefn {Function File} {[@var{a}, @var{t}] =} gallery ("neumann", @var{n})
Create a singular matrix from the discrete Neumann problem (sparse).

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("normaldata", [@var{M} @var{N} @dots{}], @var{j})
@deftypefnx {Function File} {@var{a} =} gallery ("normaldata", @var{M}, @var{N}, @dots{}, @var{j})
@deftypefnx {Function File} {@var{a} =} gallery ("normaldata", @dots{}, "@var{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 @var{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 @var{j} index.

The final optional argument determines the class of the resulting matrix.
Possible values for @var{class}: @qcode{"single"}, @qcode{"double"}.
The default is @qcode{"double"}.

@end deftypefn

@deftypefn  {Function File} {@var{q} =} gallery ("orthog", @var{n})
@deftypefnx {Function File} {@var{q} =} gallery ("orthog", @var{n}, @var{k})
Create orthogonal and nearly orthogonal matrices.

@end deftypefn

@deftypefn {Function File} {@var{a} =} gallery ("parter", @var{n})
Create a @nospell{Parter} matrix (a Toeplitz matrix with singular values
near pi).

@end deftypefn

@deftypefn  {Function File} {@var{p} =} gallery ("pei", @var{n})
@deftypefnx {Function File} {@var{p} =} gallery ("pei", @var{n}, @var{alpha})
Create a Pei matrix.

@end deftypefn

@deftypefn {Function File} {@var{a} =} gallery ("Poisson", @var{n})
Create a block tridiagonal matrix from Poisson's equation (sparse).

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("prolate", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("prolate", @var{n}, @var{w})
Create a prolate matrix (symmetric, ill-conditioned Toeplitz matrix).

@end deftypefn

@deftypefn {Function File} {@var{h} =} gallery ("randhess", @var{x})
Create a random, orthogonal upper Hessenberg matrix.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("rando", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("rando", @var{n}, @var{k})
Create a random matrix with elements -1, 0 or 1.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("randsvd", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("randsvd", @var{n}, @var{kappa})
@deftypefnx {Function File} {@var{a} =} gallery ("randsvd", @var{n}, @var{kappa}, @var{mode})
@deftypefnx {Function File} {@var{a} =} gallery ("randsvd", @var{n}, @var{kappa}, @var{mode}, @var{kl})
@deftypefnx {Function File} {@var{a} =} gallery ("randsvd", @var{n}, @var{kappa}, @var{mode}, @var{kl}, @var{ku})
Create a random matrix with pre-assigned singular values.

@end deftypefn

@deftypefn {Function File} {@var{a} =} gallery ("redheff", @var{n})
Create a zero and ones matrix of @nospell{Redheffer} associated with the
Riemann hypothesis.

@end deftypefn

@deftypefn {Function File} {@var{a} =} gallery ("riemann", @var{n})
Create a matrix associated with the Riemann hypothesis.

@end deftypefn

@deftypefn {Function File} {@var{a} =} gallery ("ris", @var{n})
Create a symmetric Hankel matrix.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("smoke", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("smoke", @var{n}, @var{k})
Create a complex matrix, with a `smoke ring' pseudospectrum.

@end deftypefn

@deftypefn  {Function File} {@var{t} =} gallery ("toeppd", @var{n})
@deftypefnx {Function File} {@var{t} =} gallery ("toeppd", @var{n}, @var{m})
@deftypefnx {Function File} {@var{t} =} gallery ("toeppd", @var{n}, @var{m}, @var{w})
@deftypefnx {Function File} {@var{t} =} gallery ("toeppd", @var{n}, @var{m}, @var{w}, @var{theta})
Create a symmetric positive definite Toeplitz matrix.

@end deftypefn

@deftypefn  {Function File} {@var{p} =} gallery ("toeppen", @var{n})
@deftypefnx {Function File} {@var{p} =} gallery ("toeppen", @var{n}, @var{a})
@deftypefnx {Function File} {@var{p} =} gallery ("toeppen", @var{n}, @var{a}, @var{b})
@deftypefnx {Function File} {@var{p} =} gallery ("toeppen", @var{n}, @var{a}, @var{b}, @var{c})
@deftypefnx {Function File} {@var{p} =} gallery ("toeppen", @var{n}, @var{a}, @var{b}, @var{c}, @var{d})
@deftypefnx {Function File} {@var{p} =} gallery ("toeppen", @var{n}, @var{a}, @var{b}, @var{c}, @var{d}, @var{e})
Create a pentadiagonal Toeplitz matrix (sparse).

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("tridiag", @var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {@var{a} =} gallery ("tridiag", @var{n})
@deftypefnx {Function File} {@var{a} =} gallery ("tridiag", @var{n}, @var{c}, @var{d}, @var{e})
Create a tridiagonal matrix (sparse).

@end deftypefn

@deftypefn  {Function File} {@var{t} =} gallery ("triw", @var{n})
@deftypefnx {Function File} {@var{t} =} gallery ("triw", @var{n}, @var{alpha})
@deftypefnx {Function File} {@var{t} =} gallery ("triw", @var{n}, @var{alpha}, @var{k})
Create an upper triangular matrix discussed by
@nospell{Kahan, Golub, and Wilkinson}.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("uniformdata", [@var{M} @var{N} @dots{}], @var{j})
@deftypefnx {Function File} {@var{a} =} gallery ("uniformdata", @var{M}, @var{N}, @dots{}, @var{j})
@deftypefnx {Function File} {@var{a} =} gallery ("uniformdata", @dots{}, "@var{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 @var{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 @var{j} index.

The final optional argument determines the class of the resulting matrix.
Possible values for @var{class}: @qcode{"single"}, @qcode{"double"}.
The default is @qcode{"double"}.

@end deftypefn

@deftypefn  {Function File} {@var{a} =} gallery ("wathen", @var{nx}, @var{ny})
@deftypefnx {Function File} {@var{a} =} gallery ("wathen", @var{nx}, @var{ny}, @var{k})
Create the @nospell{Wathen} matrix.

@end deftypefn

@deftypefn {Function File} {[@var{a}, @var{b}] =} gallery ("wilk", @var{n})
Create various specific matrices devised/discussed by Wilkinson.

@end deftypefn
hadamard
@c hadamard scripts/special-matrix/hadamard.m
-*- texinfo -*-
@deftypefn {Function File} {} hadamard (@var{n})
Construct a Hadamard matrix (@nospell{Hn}) of size @var{n}-by-@var{n}.

The size @var{n} must be of the form @math{2^k * p} in which p is one of
1, 12, 20 or 28.  The returned matrix is normalized, meaning
@w{@code{Hn(:,1) == 1}} and @w{@code{Hn(1,:) == 1}}.

Some of the properties of Hadamard matrices are:

@itemize @bullet
@item
@code{kron (Hm, Hn)} is a Hadamard matrix of size @var{m}-by-@var{n}.

@item
@code{Hn * Hn' = @var{n} * eye (@var{n})}.

@item
The rows of @nospell{Hn} are orthogonal.

@item
@code{det (@var{A}) <= abs (det (Hn))} for all @var{A} with
@w{@code{abs (@var{A}(i, j)) <= 1}}.

@item
Multiplying any row or column by -1 and the matrix will remain a Hadamard
matrix.
@end itemize
@seealso{compan, hankel, toeplitz}
@end deftypefn
hankel
@c hankel scripts/special-matrix/hankel.m
-*- texinfo -*-
@deftypefn  {Function File} {} hankel (@var{c})
@deftypefnx {Function File} {} hankel (@var{c}, @var{r})
Return the Hankel matrix constructed from the first column @var{c}, and
(optionally) the last row @var{r}.

If the last element of @var{c} is not the same as the first element of
@var{r}, the last element of @var{c} is used.  If the second argument is
omitted, it is assumed to be a vector of zeros with the same size as @var{c}.

A Hankel matrix formed from an m-vector @var{c}, and an n-vector @var{r},
has the elements
@tex
$$
H(i, j) = \cases{c_{i+j-1},&$i+j-1\le m$;\cr r_{i+j-m},&otherwise.\cr}
$$
@end tex
@ifnottex

@example
@group
H(i,j) = c(i+j-1),  i+j-1 <= m;
H(i,j) = r(i+j-m),  otherwise
@end group
@end example

@end ifnottex
@seealso{hadamard, toeplitz}
@end deftypefn
hilb
@c hilb scripts/special-matrix/hilb.m
-*- texinfo -*-
@deftypefn {Function File} {} hilb (@var{n})
Return the Hilbert matrix of order @var{n}.

The @math{i,j} element of a Hilbert matrix is defined as
@tex
$$
H(i, j) = {1 \over (i + j - 1)}
$$
@end tex
@ifnottex

@example
H(i, j) = 1 / (i + j - 1)
@end example

@end ifnottex

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.

@example
@group
cond (rand (5))
   @result{} 14.392
cond (hilb (5))
   @result{} 4.7661e+05
@end group
@end example

@seealso{invhilb}
@end deftypefn
invhilb
@c invhilb scripts/special-matrix/invhilb.m
-*- texinfo -*-
@deftypefn {Function File} {} invhilb (@var{n})
Return the inverse of the Hilbert matrix of order @var{n}.

This can be computed exactly using
@tex
$$\eqalign{
  A_{ij} &= -1^{i+j} (i+j-1)
             \left( \matrix{n+i-1 \cr n-j } \right)
             \left( \matrix{n+j-1 \cr n-i } \right)
             \left( \matrix{i+j-2 \cr i-2 } \right)^2 \cr
         &= { p(i)p(j) \over (i+j-1) }
}$$
where
$$
  p(k) = -1^k \left( \matrix{ k+n-1 \cr k-1 } \right)
              \left( \matrix{ n \cr k } \right)
$$
@end tex
@ifnottex

@example
@group

           (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)

@end group
@end example

@noindent
where

@example
@group
         k  /k+n-1\   /n\
p(k) = -1  (       ) (   )
            \ k-1 /   \k/
@end group
@end example

@end ifnottex
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 @nospell{J. W. Demmel},
@cite{Applied Numerical Linear Algebra}, p. 92.

Compare this with the numerical calculation of @code{inverse (hilb (n))},
which suffers from the ill-conditioning of the Hilbert matrix, and the
finite precision of your computer's floating point arithmetic.
@seealso{hilb}
@end deftypefn
magic
@c magic scripts/special-matrix/magic.m
-*- texinfo -*-
@deftypefn {Function File} {} magic (@var{n})

Create an @var{n}-by-@var{n} magic square.

A magic square is an arrangement of the integers @code{1:n^2} such that the
row sums, column sums, and diagonal sums are all equal to the same value.

Note: @var{n} must be greater than 2 for the magic square to exist.
@end deftypefn
pascal
@c pascal scripts/special-matrix/pascal.m
-*- texinfo -*-
@deftypefn  {Function File} {} pascal (@var{n})
@deftypefnx {Function File} {} pascal (@var{n}, @var{t})
Return the Pascal matrix of order @var{n} if @code{@var{t} = 0}.

The default value of @var{t} is 0.

When @code{@var{t} = 1}, return the pseudo-lower triangular
Cholesky@tie{}factor of the Pascal matrix (The sign of some columns may be
negative).  This matrix is its own inverse, that is
@code{pascal (@var{n}, 1) ^ 2 == eye (@var{n})}.

If @code{@var{t} = -1}, return the true Cholesky@tie{}factor with strictly
positive values on the diagonal.

If @code{@var{t} = 2}, return a transposed and permuted version of
@code{pascal (@var{n}, 1)}, which is the cube root of the identity matrix.
That is, @code{pascal (@var{n}, 2) ^ 3 == eye (@var{n})}.

@seealso{chol}
@end deftypefn
rosser
@c rosser scripts/special-matrix/rosser.m
-*- texinfo -*-
@deftypefn {Function File} {} rosser ()
Return the Rosser matrix.

This is a difficult test case used to evaluate eigenvalue algorithms.
@seealso{wilkinson, eig}
@end deftypefn
toeplitz
@c toeplitz scripts/special-matrix/toeplitz.m
-*- texinfo -*-
@deftypefn  {Function File} {} toeplitz (@var{c})
@deftypefnx {Function File} {} toeplitz (@var{c}, @var{r})
Return the Toeplitz matrix constructed from the first column @var{c},
and (optionally) the first row @var{r}.

If the first element of @var{r} is not the same as the first element of
@var{c}, the first element of @var{c} is used.  If the second argument is
omitted, the first row is taken to be the same as the first column.

A square Toeplitz matrix has the form:
@tex
$$
\left[\matrix{c_0    & r_1     & r_2      & \cdots & r_n\cr
              c_1    & c_0     & r_1      & \cdots & r_{n-1}\cr
              c_2    & c_1     & c_0      & \cdots & r_{n-2}\cr
              \vdots & \vdots  & \vdots   & \ddots & \vdots\cr
              c_n    & c_{n-1} & c_{n-2} & \ldots & c_0}\right]
$$
@end tex
@ifnottex

@example
@group
c(0)  r(1)   r(2)  @dots{}  r(n)
c(1)  c(0)   r(1)  @dots{} r(n-1)
c(2)  c(1)   c(0)  @dots{} r(n-2)
 .     .      .   .      .
 .     .      .     .    .
 .     .      .       .  .
c(n) c(n-1) c(n-2) @dots{}  c(0)
@end group
@end example

@end ifnottex
@seealso{hankel}
@end deftypefn
vander
@c vander scripts/special-matrix/vander.m
-*- texinfo -*-
@deftypefn  {Function File} {} vander (@var{c})
@deftypefnx {Function File} {} vander (@var{c}, @var{n})
Return the Vandermonde matrix whose next to last column is @var{c}.

If @var{n} is specified, it determines the number of columns; otherwise,
@var{n} is taken to be equal to the length of @var{c}.

A Vandermonde matrix has the form:
@tex
$$
\left[\matrix{c_1^{n-1}  & \cdots & c_1^2  & c_1    & 1      \cr
              c_2^{n-1}  & \cdots & c_2^2  & c_2    & 1      \cr
              \vdots     & \ddots & \vdots & \vdots & \vdots \cr
              c_n^{n-1}  & \cdots & c_n^2  & c_n    & 1      }\right]
$$
@end tex
@ifnottex

@example
@group
c(1)^(n-1) @dots{} c(1)^2  c(1)  1
c(2)^(n-1) @dots{} c(2)^2  c(2)  1
    .     .      .      .    .
    .       .    .      .    .
    .         .  .      .    .
c(n)^(n-1) @dots{} c(n)^2  c(n)  1
@end group
@end example

@end ifnottex
@seealso{polyfit}
@end deftypefn
wilkinson
@c wilkinson scripts/special-matrix/wilkinson.m
-*- texinfo -*-
@deftypefn {Function File} {} wilkinson (@var{n})
Return the Wilkinson matrix of order @var{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.

@seealso{rosser, eig}
@end deftypefn
__finish__
@c __finish__ scripts/startup/__finish__.m
-*- texinfo -*-
@deftypefn {Script File} {} __finish__
Check for the existence of the function/script, @file{finish}, in the
path or current working directory and execute it.

This function is intended to be excecuted upon a clean exit from Octave.
This is accomplished in the system script @file{startup/octaverc} by use of
the built-in function @code{atexit}.
@seealso{atexit}
@end deftypefn
center
@c center scripts/statistics/base/center.m
-*- texinfo -*-
@deftypefn  {Function File} {} center (@var{x})
@deftypefnx {Function File} {} center (@var{x}, @var{dim})
Center data by subtracting its mean.

If @var{x} is a vector, subtract its mean.

If @var{x} is a matrix, do the above for each column.

If the optional argument @var{dim} is given, operate along this dimension.

Programming Note: @code{center} has obvious application for normalizing
statistical data.  It is also useful for improving the precision of general
numerical calculations.  Whenever there is a large value that is common
to a batch of data, the mean can be subtracted off, the calculation
performed, and then the mean added back to obtain the final answer.
@seealso{zscore}
@end deftypefn
cloglog
@c cloglog scripts/statistics/base/cloglog.m
-*- texinfo -*-
@deftypefn {Function File} {} cloglog (@var{x})
Return the complementary log-log function of @var{x}.

The complementary log-log function is defined as
@tex
$$
{\rm cloglog}(x) = - \log (- \log (x))
$$
@end tex
@ifnottex

@example
cloglog (x) = - log (- log (@var{x}))
@end example

@end ifnottex
@end deftypefn
corr
@c corr scripts/statistics/base/corr.m
-*- texinfo -*-
@deftypefn  {Function File} {} corr (@var{x})
@deftypefnx {Function File} {} corr (@var{x}, @var{y})
Compute matrix of correlation coefficients.

If each row of @var{x} and @var{y} is an observation and each column is
a variable, then the @w{(@var{i}, @var{j})-th} entry of
@code{corr (@var{x}, @var{y})} is the correlation between the
@var{i}-th variable in @var{x} and the @var{j}-th variable in @var{y}.
@tex
$$
{\rm corr}(x,y) = {{\rm cov}(x,y) \over {\rm std}(x) {\rm std}(y)}
$$
@end tex
@ifnottex

@example
corr (x,y) = cov (x,y) / (std (x) * std (y))
@end example

@end ifnottex
If called with one argument, compute @code{corr (@var{x}, @var{x})},
the correlation between the columns of @var{x}.
@seealso{cov}
@end deftypefn
cov
@c cov scripts/statistics/base/cov.m
-*- texinfo -*-
@deftypefn  {Function File} {} cov (@var{x})
@deftypefnx {Function File} {} cov (@var{x}, @var{opt})
@deftypefnx {Function File} {} cov (@var{x}, @var{y})
@deftypefnx {Function File} {} cov (@var{x}, @var{y}, @var{opt})
Compute the covariance matrix.

If each row of @var{x} and @var{y} is an observation, and each column is
a variable, then the @w{(@var{i}, @var{j})-th} entry of
@code{cov (@var{x}, @var{y})} is the covariance between the @var{i}-th
variable in @var{x} and the @var{j}-th variable in @var{y}.
@tex
$$
\sigma_{ij} = {1 \over N-1} \sum_{i=1}^N (x_i - \bar{x})(y_i - \bar{y})
$$
where $\bar{x}$ and $\bar{y}$ are the mean values of $x$ and $y$.
@end tex
@ifnottex

@example
cov (x) = 1/N-1 * SUM_i (x(i) - mean(x)) * (y(i) - mean(y))
@end example

@end ifnottex

If called with one argument, compute @code{cov (@var{x}, @var{x})}, the
covariance between the columns of @var{x}.

The argument @var{opt} determines the type of normalization to use.
Valid values are

@table @asis
@item 0:
  normalize with @math{N-1}, provides the best unbiased estimator of the
covariance [default]

@item 1:
  normalize with @math{N}, this provides the second moment around the mean
@end table

Compatibility Note:: Octave always computes the covariance matrix.
For two inputs, however, @sc{matlab} will calculate
@code{cov (@var{x}(:), @var{y}(:))} whenever the number of elements in
@var{x} and @var{y} are equal.  This will result in a scalar rather than
a matrix output.  Code relying on this odd definition will need to be
changed when running in Octave.
@seealso{corr}
@end deftypefn
gls
@c gls scripts/statistics/base/gls.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{beta}, @var{v}, @var{r}] =} gls (@var{y}, @var{x}, @var{o})
Generalized least squares model.

Perform a generalized least squares estimation for the multivariate model
@tex
$y = x b + e$
with $\bar{e} = 0$ and cov(vec($e$)) = $(s^2)o$,
@end tex
@ifnottex
@w{@math{y = x*b + e}} with @math{mean (e) = 0} and
@math{cov (vec (e)) = (s^2) o},
@end ifnottex
where
@tex
$y$ is a $t \times p$ matrix, $x$ is a $t \times k$ matrix, $b$ is a $k
\times p$ matrix, $e$ is a $t \times p$ matrix, and $o$ is a $tp \times
tp$ matrix.
@end tex
@ifnottex
@math{y} is a @math{t} by @math{p} matrix, @math{x} is a @math{t} by
@math{k} matrix, @math{b} is a @math{k} by @math{p} matrix, @math{e}
is a @math{t} by @math{p} matrix, and @math{o} is a @math{t*p} by
@math{t*p} matrix.
@end ifnottex

@noindent
Each row of @var{y} and @var{x} is an observation and each column a
variable.  The return values @var{beta}, @var{v}, and @var{r} are
defined as follows.

@table @var
@item beta
The GLS estimator for @math{b}.

@item v
The GLS estimator for @math{s^2}.

@item r
The matrix of GLS residuals, @math{r = y - x*beta}.
@end table
@seealso{ols}
@end deftypefn
histc
@c histc scripts/statistics/base/histc.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{n} =} histc (@var{x}, @var{edges})
@deftypefnx {Function File} {@var{n} =} histc (@var{x}, @var{edges}, @var{dim})
@deftypefnx {Function File} {[@var{n}, @var{idx}] =} histc (@dots{})
Compute histogram counts.

When @var{x} is a vector, the function counts the number of elements of
@var{x} that fall in the histogram bins defined by @var{edges}.  This must be
a vector of monotonically increasing values that define the edges of the
histogram bins.  @code{@var{n}(k)} contains the number of elements in
@var{x} for which @code{@var{edges}(k) <= @var{x} < @var{edges}(k+1)}.
The final element of @var{n} contains the number of elements of @var{x}
exactly equal to the last element of @var{edges}.

When @var{x} is an @math{N}-dimensional array, the computation is carried
out along dimension @var{dim}.  If not specified @var{dim} defaults to the
first non-singleton dimension.

When a second output argument is requested an index matrix is also returned.
The @var{idx} matrix has the same size as @var{x}.  Each element of @var{idx}
contains the index of the histogram bin in which the corresponding element
of @var{x} was counted.
@seealso{hist}
@end deftypefn
iqr
@c iqr scripts/statistics/base/iqr.m
-*- texinfo -*-
@deftypefn  {Function File} {} iqr (@var{x})
@deftypefnx {Function File} {} iqr (@var{x}, @var{dim})
Return the interquartile range, i.e., the difference between the upper
and lower quartile of the input data.

If @var{x} is a matrix, do the above for first non-singleton dimension of
@var{x}.

If the optional argument @var{dim} is given, operate along this dimension.

As a measure of dispersion, the interquartile range is less affected by
outliers than either @code{range} or @code{std}.
@seealso{range, std}
@end deftypefn
kendall
@c kendall scripts/statistics/base/kendall.m
-*- texinfo -*-
@deftypefn  {Function File} {} kendall (@var{x})
@deftypefnx {Function File} {} kendall (@var{x}, @var{y})
@cindex Kendall's Tau
Compute Kendall's @var{tau}.

For two data vectors @var{x}, @var{y} of common length @var{n}, Kendall's
@var{tau} is the correlation of the signs of all rank differences of
@var{x} and @var{y}; i.e., if both @var{x} and @var{y} have distinct
entries, then

@tex
$$ \tau = {1 \over n(n-1)} \sum_{i,j} {\rm sign}(q_i-q_j) {\rm sign}(r_i-r_j) $$
@end tex
@ifnottex

@example
@group
         1
tau = -------   SUM sign (q(i) - q(j)) * sign (r(i) - r(j))
      n (n-1)   i,j
@end group
@end example

@end ifnottex
@noindent
in which the
@tex
$q_i$ and $r_i$
@end tex
@ifnottex
@var{q}(@var{i}) and @var{r}(@var{i})
@end ifnottex
are the ranks of @var{x} and @var{y}, respectively.

If @var{x} and @var{y} are drawn from independent distributions,
Kendall's @var{tau} is asymptotically normal with mean 0 and variance
@tex
${2 (2n+5) \over 9n(n-1)}$.
@end tex
@ifnottex
@code{(2 * (2@var{n}+5)) / (9 * @var{n} * (@var{n}-1))}.
@end ifnottex

@code{kendall (@var{x})} is equivalent to @code{kendall (@var{x},
@var{x})}.
@seealso{ranks, spearman}
@end deftypefn
kurtosis
@c kurtosis scripts/statistics/base/kurtosis.m
-*- texinfo -*-
@deftypefn  {Function File} {} kurtosis (@var{x})
@deftypefnx {Function File} {} kurtosis (@var{x}, @var{flag})
@deftypefnx {Function File} {} kurtosis (@var{x}, @var{flag}, @var{dim})
Compute the sample kurtosis of the elements of @var{x}.

The sample kurtosis is defined as
@tex
$$
\kappa_1 = {{{1\over N}\,
         \sum_{i=1}^N (@var{x}_i - \bar{@var{x}})^4} \over \sigma^4},
$$
where $N$ is the length of @var{x}, $\bar{@var{x}}$ its mean, and $\sigma$
its (uncorrected) standard deviation.
@end tex
@ifnottex

@example
@group
     mean ((@var{x} - mean (@var{x})).^4)
k1 = ------------------------
            std (@var{x}).^4
@end group
@end example

@end ifnottex

@noindent
The optional argument @var{flag} controls which normalization is used.
If @var{flag} is equal to 1 (default value, used when @var{flag} is omitted
or empty), return the sample kurtosis as defined above.  If @var{flag} is
equal to 0, return the @w{"bias-corrected"} kurtosis coefficient instead:
@tex
$$
\kappa_0 = 3 + {\scriptstyle N - 1 \over \scriptstyle (N - 2)(N - 3)} \,
    \left( (N + 1)\, \kappa_1 - 3 (N - 1) \right)
$$
@end tex
@ifnottex

@example
@group
              N - 1
k0 = 3 + -------------- * ((N + 1) * k1 - 3 * (N - 1))
         (N - 2)(N - 3)
@end group
@end example

@end ifnottex
The bias-corrected kurtosis coefficient is obtained by replacing the sample
second and fourth central moments by their unbiased versions.  It is an
unbiased estimate of the population kurtosis for normal populations.

If @var{x} is a matrix, or more generally a multi-dimensional array, return
the kurtosis along the first non-singleton dimension.  If the optional
@var{dim} argument is given, operate along this dimension.

@seealso{var, skewness, moment}
@end deftypefn
logit
@c logit scripts/statistics/base/logit.m
-*- texinfo -*-
@deftypefn {Function File} {} logit (@var{p})
Compute the logit for each value of @var{p}

The logit is defined as
@tex
$$
{\rm logit}(p) = \log\Big({p \over 1-p}\Big)
$$
@end tex
@ifnottex

@example
logit (@var{p}) = log (@var{p} / (1-@var{p}))
@end example

@end ifnottex
@seealso{probit, logistic_cdf}
@end deftypefn
lscov
@c lscov scripts/statistics/base/lscov.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} lscov (@var{A}, @var{b})
@deftypefnx {Function File} {@var{x} =} lscov (@var{A}, @var{b}, @var{V})
@deftypefnx {Function File} {@var{x} =} lscov (@var{A}, @var{b}, @var{V}, @var{alg})
@deftypefnx {Function File} {[@var{x}, @var{stdx}, @var{mse}, @var{S}] =} lscov (@dots{})

Compute a generalized linear least squares fit.

Estimate @var{x} under the model @var{b} = @var{A}@var{x} + @var{w},
where the noise @var{w} is assumed to follow a normal distribution
with covariance matrix @math{{\sigma^2} V}.

If the size of the coefficient matrix @var{A} is n-by-p, the
size of the vector/array of constant terms @var{b} must be n-by-k.

The optional input argument @var{V} may be a n-by-1 vector of positive
weights (inverse variances), or a n-by-n symmetric positive semidefinite
matrix representing the covariance of @var{b}.  If @var{V} is not
supplied, the ordinary least squares solution is returned.

The @var{alg} input argument, a guidance on solution method to use, is
currently ignored.

Besides the least-squares estimate matrix @var{x} (p-by-k), the function
also returns @var{stdx} (p-by-k), the error standard deviation of
estimated @var{x}; @var{mse} (k-by-1), the estimated data error covariance
scale factors (@math{\sigma^2}); and @var{S} (p-by-p, or p-by-p-by-k if k
> 1), the error covariance of @var{x}.

Reference: @nospell{Golub and Van Loan} (1996),
@cite{Matrix Computations (3rd Ed.)}, Johns Hopkins, Section 5.6.3

@seealso{ols, gls, lsqnonneg}
@end deftypefn
mahalanobis
@c mahalanobis scripts/statistics/base/mahalanobis.m
-*- texinfo -*-
@deftypefn {Function File} {} mahalanobis (@var{x}, @var{y})
Return the Mahalanobis' D-square distance between the multivariate
samples @var{x} and @var{y}.

The data @var{x} and @var{y} must have the same number of components
(columns), but may have a different number of observations (rows).
@end deftypefn
mean
@c mean scripts/statistics/base/mean.m
-*- texinfo -*-
@deftypefn  {Function File} {} mean (@var{x})
@deftypefnx {Function File} {} mean (@var{x}, @var{dim})
@deftypefnx {Function File} {} mean (@var{x}, @var{opt})
@deftypefnx {Function File} {} mean (@var{x}, @var{dim}, @var{opt})
Compute the mean of the elements of the vector @var{x}.

The mean is defined as

@tex
$$ {\rm mean}(x) = \bar{x} = {1\over N} \sum_{i=1}^N x_i $$
@end tex
@ifnottex

@example
mean (x) = SUM_i x(i) / N
@end example

@end ifnottex
If @var{x} is a matrix, compute the mean for each column and return them
in a row vector.

If the optional argument @var{dim} is given, operate along this dimension.

The optional argument @var{opt} selects the type of mean to compute.
The following options are recognized:

@table @asis
@item @qcode{"a"}
Compute the (ordinary) arithmetic mean.  [default]

@item @qcode{"g"}
Compute the geometric mean.

@item @qcode{"h"}
Compute the harmonic mean.
@end table

Both @var{dim} and @var{opt} are optional.  If both are supplied, either
may appear first.
@seealso{median, mode}
@end deftypefn
meansq
@c meansq scripts/statistics/base/meansq.m
-*- texinfo -*-
@deftypefn  {Function File} {} meansq (@var{x})
@deftypefnx {Function File} {} meansq (@var{x}, @var{dim})
Compute the mean square of the elements of the vector @var{x}.

The mean square is defined as
@tex
$$
{\rm meansq} (x) = {\sum_{i=1}^N {x_i}^2 \over N}
$$
where $\bar{x}$ is the mean value of $x$.
@end tex
@ifnottex

@example
@group
meansq (x) = 1/N SUM_i x(i)^2
@end group
@end example

@end ifnottex
For matrix arguments, return a row vector containing the mean square
of each column.

If the optional argument @var{dim} is given, operate along this dimension.
@seealso{var, std, moment}
@end deftypefn
median
@c median scripts/statistics/base/median.m
-*- texinfo -*-
@deftypefn  {Function File} {} median (@var{x})
@deftypefnx {Function File} {} median (@var{x}, @var{dim})
Compute the median value of the elements of the vector @var{x}.

When the elements of @var{x} are sorted, the median is defined as
@tex
$$
{\rm median} (x) =
  \cases{x(\lceil N/2\rceil), & $N$ odd;\cr
          (x(N/2)+x(N/2+1))/2, & $N$ even.}
$$
@end tex
@ifnottex

@example
@group
              x(ceil(N/2))             N odd
median (x) =
             (x(N/2) + x((N/2)+1))/2   N even
@end group
@end example

@end ifnottex
If @var{x} is a matrix, compute the median value for each column and
return them in a row vector.

If the optional @var{dim} argument is given, operate along this dimension.
@seealso{mean, mode}
@end deftypefn
mode
@c mode scripts/statistics/base/mode.m
-*- texinfo -*-
@deftypefn  {Function File} {} mode (@var{x})
@deftypefnx {Function File} {} mode (@var{x}, @var{dim})
@deftypefnx {Function File} {[@var{m}, @var{f}, @var{c}] =} mode (@dots{})
Compute the most frequently occurring value in a dataset (mode).

@code{mode} determines the frequency of values along the first non-singleton
dimension and returns the value with the highest frequency.  If two, or
more, values have the same frequency @code{mode} returns the smallest.

If the optional argument @var{dim} is given, operate along this dimension.

The return variable @var{f} is the number of occurrences of the mode in
the dataset.

The cell array @var{c} contains all of the elements with the maximum
frequency.
@seealso{mean, median}
@end deftypefn
moment
@c moment scripts/statistics/base/moment.m
-*- texinfo -*-
@deftypefn  {Function File} {} moment (@var{x}, @var{p})
@deftypefnx {Function File} {} moment (@var{x}, @var{p}, @var{type})
@deftypefnx {Function File} {} moment (@var{x}, @var{p}, @var{dim})
@deftypefnx {Function File} {} moment (@var{x}, @var{p}, @var{type}, @var{dim})
@deftypefnx {Function File} {} moment (@var{x}, @var{p}, @var{dim}, @var{type})
Compute the @var{p}-th central moment of the vector @var{x}.

@tex
$$
{\sum_{i=1}^N (x_i - \bar{x})^p \over N}
$$
@end tex
@ifnottex

@example
@group
1/N SUM_i (x(i) - mean(x))^p
@end group
@end example

@end ifnottex

If @var{x} is a matrix, return the row vector containing the @var{p}-th
central moment of each column.

If the optional argument @var{dim} is given, operate along this dimension.

The optional string @var{type} specifies the type of moment to be computed.
Valid options are:

@table @asis
@item @qcode{"c"}
  Central Moment (default).

@item  @qcode{"a"}
@itemx @qcode{"ac"}
  Absolute Central Moment.  The moment about the mean ignoring sign
defined as
@tex
$$
{\sum_{i=1}^N {\left| x_i - \bar{x} \right|}^p \over N}
$$
@end tex
@ifnottex

@example
@group
1/N SUM_i (abs (x(i) - mean(x)))^p
@end group
@end example

@end ifnottex

@item @qcode{"r"}
  Raw Moment.  The moment about zero defined as

@tex
$$
{\rm moment} (x) = { \sum_{i=1}^N {x_i}^p \over N }
$$
@end tex
@ifnottex

@example
@group
moment (x) = 1/N SUM_i x(i)^p
@end group
@end example

@end ifnottex

@item @nospell{@qcode{"ar"}}
  Absolute Raw Moment.  The moment about zero ignoring sign defined as
@tex
$$
{\sum_{i=1}^N {\left| x_i \right|}^p \over N}
$$
@end tex
@ifnottex

@example
@group
1/N SUM_i ( abs (x(i)) )^p
@end group
@end example

@end ifnottex
@end table

If both @var{type} and @var{dim} are given they may appear in any order.
@seealso{var, skewness, kurtosis}
@end deftypefn
ols
@c ols scripts/statistics/base/ols.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{beta}, @var{sigma}, @var{r}] =} ols (@var{y}, @var{x})
Ordinary least squares estimation.

OLS applies to the multivariate model
@tex
$y = x b + e$
with
$\bar{e} = 0$, and cov(vec($e$)) = kron ($s, I$)
@end tex
@ifnottex
@w{@math{y = x*b + e}} with
@math{mean (e) = 0} and @math{cov (vec (e)) = kron (s, I)}.
@end ifnottex
where
@tex
$y$ is a $t \times p$ matrix, $x$ is a $t \times k$ matrix,
$b$ is a $k \times p$ matrix, and $e$ is a $t \times p$ matrix.
@end tex
@ifnottex
@math{y} is a @math{t} by @math{p} matrix, @math{x} is a @math{t} by @math{k}
matrix, @math{b} is a @math{k} by @math{p} matrix, and @math{e} is a
@math{t} by @math{p} matrix.
@end ifnottex

Each row of @var{y} and @var{x} is an observation and each column a variable.

The return values @var{beta}, @var{sigma}, and @var{r} are defined as
follows.

@table @var
@item beta
The OLS estimator for @math{b}.
@tex
$beta$ is calculated directly via $(x^Tx)^{-1} x^T y$ if the matrix $x^Tx$ is
of full rank.
@end tex
@ifnottex
@var{beta} is calculated directly via @code{inv (x'*x) * x' * y} if the
matrix @code{x'*x} is of full rank.
@end ifnottex
Otherwise, @code{@var{beta} = pinv (@var{x}) * @var{y}} where
@code{pinv (@var{x})} denotes the pseudoinverse of @var{x}.

@item sigma
The OLS estimator for the matrix @var{s},

@example
@group
@var{sigma} = (@var{y}-@var{x}*@var{beta})'
  * (@var{y}-@var{x}*@var{beta})
  / (@var{t}-rank(@var{x}))
@end group
@end example

@item r
The matrix of OLS residuals, @code{@var{r} = @var{y} - @var{x}*@var{beta}}.
@end table
@seealso{gls, pinv}
@end deftypefn
ppplot
@c ppplot scripts/statistics/base/ppplot.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{p}, @var{y}] =} ppplot (@var{x}, @var{dist}, @var{params})
Perform a PP-plot (probability plot).

If F is the CDF of the distribution @var{dist} with parameters
@var{params} and @var{x} a sample vector of length @var{n}, the PP-plot
graphs ordinate @var{y}(@var{i}) = F (@var{i}-th largest element of
@var{x}) versus abscissa @var{p}(@var{i}) = (@var{i} - 0.5)/@var{n}.  If
the sample comes from F, the pairs will approximately follow a straight
line.

The default for @var{dist} is the standard normal distribution.

The optional argument @var{params} contains a list of parameters of
@var{dist}.

For example, for a probability plot of the uniform distribution on [2,4]
and @var{x}, use

@example
ppplot (x, "uniform", 2, 4)
@end example

@noindent
@var{dist} can be any string for which a function @var{dist_cdf} that
calculates the CDF of distribution @var{dist} exists.

If no output is requested then the data are plotted immediately.
@end deftypefn
prctile
@c prctile scripts/statistics/base/prctile.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{q} =} prctile (@var{x})
@deftypefnx {Function File} {@var{q} =} prctile (@var{x}, @var{p})
@deftypefnx {Function File} {@var{q} =} prctile (@var{x}, @var{p}, @var{dim})
For a sample @var{x}, compute the quantiles, @var{q}, corresponding
to the cumulative probability values, @var{p}, in percent.

If @var{x} is a matrix, compute the percentiles for each column and return
them in a matrix, such that the i-th row of @var{y} contains the
@var{p}(i)th percentiles of each column of @var{x}.

If @var{p} is unspecified, return the quantiles for @code{[0 25 50 75 100]}.

The optional argument @var{dim} determines the dimension along which the
percentiles are calculated.  If @var{dim} is omitted it defaults to the
first non-singleton dimension.

Programming Note: All non-numeric values (NaNs) of @var{x} are ignored.
@seealso{quantile}
@end deftypefn
probit
@c probit scripts/statistics/base/probit.m
-*- texinfo -*-
@deftypefn {Function File} {} probit (@var{p})
Return the probit (the quantile of the standard normal distribution) for
each element of @var{p}.
@seealso{logit}
@end deftypefn
qqplot
@c qqplot scripts/statistics/base/qqplot.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{q}, @var{s}] =} qqplot (@var{x})
@deftypefnx {Function File} {[@var{q}, @var{s}] =} qqplot (@var{x}, @var{y})
@deftypefnx {Function File} {[@var{q}, @var{s}] =} qqplot (@var{x}, @var{dist})
@deftypefnx {Function File} {[@var{q}, @var{s}] =} qqplot (@var{x}, @var{y}, @var{params})
@deftypefnx {Function File} {} qqplot (@dots{})
Perform a QQ-plot (quantile plot).

If F is the CDF of the distribution @var{dist} with parameters
@var{params} and G its inverse, and @var{x} a sample vector of length
@var{n}, the QQ-plot graphs ordinate @var{s}(@var{i}) = @var{i}-th
largest element of x versus abscissa @var{q}(@var{i}f) = G((@var{i} -
0.5)/@var{n}).

If the sample comes from F, except for a transformation of location
and scale, the pairs will approximately follow a straight line.

If the second argument is a vector @var{y} the empirical CDF of @var{y}
is used as @var{dist}.

The default for @var{dist} is the standard normal distribution.  The
optional argument @var{params} contains a list of parameters of
@var{dist}.  For example, for a quantile plot of the uniform
distribution on [2,4] and @var{x}, use

@example
qqplot (x, "unif", 2, 4)
@end example

@noindent
@var{dist} can be any string for which a function @var{distinv} or
@var{dist_inv} exists that calculates the inverse CDF of distribution
@var{dist}.

If no output arguments are given, the data are plotted directly.
@end deftypefn
quantile
@c quantile scripts/statistics/base/quantile.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{q} =} quantile (@var{x})
@deftypefnx {Function File} {@var{q} =} quantile (@var{x}, @var{p})
@deftypefnx {Function File} {@var{q} =} quantile (@var{x}, @var{p}, @var{dim})
@deftypefnx {Function File} {@var{q} =} quantile (@var{x}, @var{p}, @var{dim}, @var{method})
For a sample, @var{x}, calculate the quantiles, @var{q}, corresponding to
the cumulative probability values in @var{p}.  All non-numeric values (NaNs)
of @var{x} are ignored.

If @var{x} is a matrix, compute the quantiles for each column and
return them in a matrix, such that the i-th row of @var{q} contains
the @var{p}(i)th quantiles of each column of @var{x}.

If @var{p} is unspecified, return the quantiles for
@code{[0.00 0.25 0.50 0.75 1.00]}.
The optional argument @var{dim} determines the dimension along which
the quantiles are calculated.  If @var{dim} is omitted it defaults to
the first non-singleton dimension.

The methods available to calculate sample quantiles are the nine methods
used by R (@url{http://www.r-project.org/}).  The default value is
@w{METHOD = 5}.

Discontinuous sample quantile methods 1, 2, and 3

@enumerate 1
@item Method 1: Inverse of empirical distribution function.

@item Method 2: Similar to method 1 but with averaging at discontinuities.

@item Method 3: SAS definition: nearest even order statistic.
@end enumerate

Continuous sample quantile methods 4 through 9, where p(k) is the linear
interpolation function respecting each methods' representative cdf.

@enumerate 4
@item Method 4: p(k) = k / n.  That is, linear interpolation of the
empirical cdf.

@item Method 5: p(k) = (k - 0.5) / n.  That is a piecewise linear function
where the knots are the values midway through the steps of the empirical
cdf.

@item Method 6: p(k) = k / (n + 1).

@item Method 7: p(k) = (k - 1) / (n - 1).

@item Method 8: p(k) = (k - 1/3) / (n + 1/3).  The resulting quantile
estimates are approximately median-unbiased regardless of the distribution
of @var{x}.

@item Method 9: p(k) = (k - 3/8) / (n + 1/4).  The resulting quantile
estimates are approximately unbiased for the expected order statistics if
@var{x} is normally distributed.
@end enumerate

@nospell{Hyndman and Fan} (1996) recommend method 8.  Maxima, S, and R
(versions prior to 2.0.0) use 7 as their default.  Minitab and SPSS
use method 6.  @sc{matlab} uses method 5.

References:

@itemize @bullet
@item @nospell{Becker, R. A., Chambers, J. M. and Wilks, A. R.} (1988)
The New S Language.  Wadsworth & Brooks/Cole.

@item @nospell{Hyndman, R. J. and Fan, Y.} (1996) Sample quantiles in
statistical packages, American Statistician, 50, 361--365.

@item R: A Language and Environment for Statistical Computing;
@url{http://cran.r-project.org/doc/manuals/fullrefman.pdf}.
@end itemize

Examples:
@c Set example in small font to prevent overfull line

@smallexample
@group
x = randi (1000, [10, 1]);  # Create empirical data in range 1-1000
q = quantile (x, [0, 1]);   # Return minimum, maximum of distribution
q = quantile (x, [0.25 0.5 0.75]); # Return quartiles of distribution
@end group
@end smallexample
@seealso{prctile}
@end deftypefn
range
@c range scripts/statistics/base/range.m
-*- texinfo -*-
@deftypefn  {Function File} {} range (@var{x})
@deftypefnx {Function File} {} range (@var{x}, @var{dim})
Return the range, i.e., the difference between the maximum and the minimum
of the input data.

If @var{x} is a vector, the range is calculated over the elements of
@var{x}.  If @var{x} is a matrix, the range is calculated over each column
of @var{x}.

If the optional argument @var{dim} is given, operate along this dimension.

The range is a quickly computed measure of the dispersion of a data set, but
is less accurate than @code{iqr} if there are outlying data points.
@seealso{iqr, std}
@end deftypefn
ranks
@c ranks scripts/statistics/base/ranks.m
-*- texinfo -*-
@deftypefn {Function File} {} ranks (@var{x}, @var{dim})
Return the ranks of @var{x} along the first non-singleton dimension
adjusted for ties.

If the optional argument @var{dim} is given, operate along this dimension.
@seealso{spearman, kendall}
@end deftypefn
run_count
@c run_count scripts/statistics/base/run_count.m
-*- texinfo -*-
@deftypefn  {Function File} {} run_count (@var{x}, @var{n})
@deftypefnx {Function File} {} run_count (@var{x}, @var{n}, @var{dim})
Count the upward runs along the first non-singleton dimension of @var{x}
of length 1, 2, @dots{}, @var{n}-1 and greater than or equal to @var{n}.

If the optional argument @var{dim} is given then operate along this
dimension.
@seealso{runlength}
@end deftypefn
runlength
@c runlength scripts/statistics/base/runlength.m
-*- texinfo -*-
@deftypefn  {Function File} {count =} runlength (@var{x})
@deftypefnx {Function File} {[count, value] =} runlength (@var{x})
Find the lengths of all sequences of common values.

@var{count} is a vector with the lengths of each repeated value.

The optional output @var{value} contains the value that was repeated in
the sequence.

@example
@group
runlength ([2, 2, 0, 4, 4, 4, 0, 1, 1, 1, 1])
@result{}  [2, 1, 3, 1, 4]
@end group
@end example
@seealso{run_count}
@end deftypefn
skewness
@c skewness scripts/statistics/base/skewness.m
-*- texinfo -*-
@deftypefn  {Function File} {} skewness (@var{x})
@deftypefnx {Function File} {} skewness (@var{x}, @var{flag})
@deftypefnx {Function File} {} skewness (@var{x}, @var{flag}, @var{dim})
Compute the sample skewness of the elements of @var{x}.

The sample skewness is defined as
@tex
$$
{\rm skewness} (@var{x}) = {{{1\over N}\,
         \sum_{i=1}^N (@var{x}_i - \bar{@var{x}})^3} \over \sigma^3},
$$
where $N$ is the length of @var{x}, $\bar{@var{x}}$ its mean and $\sigma$
its (uncorrected) standard deviation.
@end tex
@ifnottex

@example
@group
               mean ((@var{x} - mean (@var{x})).^3)
skewness (@var{X}) = ------------------------.
                      std (@var{x}).^3
@end group
@end example

@end ifnottex

@noindent
The optional argument @var{flag} controls which normalization is used.
If @var{flag} is equal to 1 (default value, used when @var{flag} is omitted
or empty), return the sample skewness as defined above.  If @var{flag} is
equal to 0, return the adjusted skewness coefficient instead:
@tex
$$
{\rm skewness} (@var{x}) = {\sqrt{N (N - 1)} \over N - 2} \times \,
  {{{1 \over N} \sum_{i=1}^N (@var{x}_i - \bar{@var{x}})^3} \over \sigma^3}
$$
@end tex
@ifnottex

@example
@group
                  sqrt (N*(N-1))   mean ((@var{x} - mean (@var{x})).^3)
skewness (@var{X}, 0) = -------------- * ------------------------.
                      (N - 2)             std (@var{x}).^3
@end group
@end example

@end ifnottex
The adjusted skewness coefficient is obtained by replacing the sample second
and third central moments by their bias-corrected versions.

If @var{x} is a matrix, or more generally a multi-dimensional array, return
the skewness along the first non-singleton dimension.  If the optional
@var{dim} argument is given, operate along this dimension.

@seealso{var, kurtosis, moment}
@end deftypefn
spearman
@c spearman scripts/statistics/base/spearman.m
-*- texinfo -*-
@deftypefn  {Function File} {} spearman (@var{x})
@deftypefnx {Function File} {} spearman (@var{x}, @var{y})
@cindex Spearman's Rho
Compute Spearman's rank correlation coefficient @var{rho}.

For two data vectors @var{x} and @var{y}, Spearman's @var{rho} is the
correlation coefficient of the ranks of @var{x} and @var{y}.

If @var{x} and @var{y} are drawn from independent distributions, @var{rho}
has zero mean and variance @code{1 / (n - 1)}, and is asymptotically
normally distributed.

@code{spearman (@var{x})} is equivalent to
@code{spearman (@var{x}, @var{x})}.
@seealso{ranks, kendall}
@end deftypefn
statistics
@c statistics scripts/statistics/base/statistics.m
-*- texinfo -*-
@deftypefn  {Function File} {} statistics (@var{x})
@deftypefnx {Function File} {} statistics (@var{x}, @var{dim})
Return a vector with the minimum, first quartile, median, third quartile,
maximum, mean, standard deviation, skewness, and kurtosis of the elements of
the vector @var{x}.

If @var{x} is a matrix, calculate statistics over the first non-singleton
dimension.

If the optional argument @var{dim} is given, operate along this dimension.
@seealso{min, max, median, mean, std, skewness, kurtosis}
@end deftypefn
std
@c std scripts/statistics/base/std.m
-*- texinfo -*-
@deftypefn  {Function File} {} std (@var{x})
@deftypefnx {Function File} {} std (@var{x}, @var{opt})
@deftypefnx {Function File} {} std (@var{x}, @var{opt}, @var{dim})
Compute the standard deviation of the elements of the vector @var{x}.

The standard deviation is defined as
@tex
$$
{\rm std} (x) = \sigma = \sqrt{{\sum_{i=1}^N (x_i - \bar{x})^2 \over N - 1}}
$$
where $\bar{x}$ is the mean value of $x$ and $N$ is the number of elements.
@end tex
@ifnottex

@example
@group
std (x) = sqrt ( 1/(N-1) SUM_i (x(i) - mean(x))^2 )
@end group
@end example

@noindent
where @math{N} is the number of elements.
@end ifnottex

If @var{x} is a matrix, compute the standard deviation for each column and
return them in a row vector.

The argument @var{opt} determines the type of normalization to use.
Valid values are

@table @asis
@item 0:
  normalize with @math{N-1}, provides the square root of the best unbiased
estimator of the variance [default]

@item 1:
  normalize with @math{N}, this provides the square root of the second
moment around the mean
@end table

If the optional argument @var{dim} is given, operate along this dimension.
@seealso{var, range, iqr, mean, median}
@end deftypefn
table
@c table scripts/statistics/base/table.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{t}, @var{l_x}] =} table (@var{x})
@deftypefnx {Function File} {[@var{t}, @var{l_x}, @var{l_y}] =} table (@var{x}, @var{y})
Create a contingency table @var{t} from data vectors.

The @var{l_x} and @var{l_y} vectors are the corresponding levels.

Currently, only 1- and 2-dimensional tables are supported.
@end deftypefn
var
@c var scripts/statistics/base/var.m
-*- texinfo -*-
@deftypefn  {Function File} {} var (@var{x})
@deftypefnx {Function File} {} var (@var{x}, @var{opt})
@deftypefnx {Function File} {} var (@var{x}, @var{opt}, @var{dim})
Compute the variance of the elements of the vector @var{x}.

The variance is defined as
@tex
$$
{\rm var} (x) = \sigma^2 = {\sum_{i=1}^N (x_i - \bar{x})^2 \over N - 1}
$$
where $\bar{x}$ is the mean value of $x$.
@end tex
@ifnottex

@example
@group
var (x) = 1/(N-1) SUM_i (x(i) - mean(x))^2
@end group
@end example

@end ifnottex
If @var{x} is a matrix, compute the variance for each column and return
them in a row vector.

The argument @var{opt} determines the type of normalization to use.
Valid values are

@table @asis
@item 0:
  normalize with @math{N-1}, provides the best unbiased estimator of the
variance [default]

@item 1:
  normalizes with @math{N}, this provides the second moment around the mean
@end table

If @math{N==1} the value of @var{opt} is ignored and normalization by
@math{N} is used.

If the optional argument @var{dim} is given, operate along this dimension.
@seealso{cov, std, skewness, kurtosis, moment}
@end deftypefn
zscore
@c zscore scripts/statistics/base/zscore.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{z} =} zscore (@var{x})
@deftypefnx {Function File} {@var{z} =} zscore (@var{x}, @var{opt})
@deftypefnx {Function File} {@var{z} =} zscore (@var{x}, @var{opt}, @var{dim})
@deftypefnx {Function File} {[@var{z}, @var{mu}, @var{sigma}] =} zscore (@dots{})
Compute the Z score of @var{x}

If @var{x} is a vector, subtract its mean and divide by its standard
deviation.  If the standard deviation is zero, divide by 1 instead.

The optional parameter @var{opt} determines the normalization to use when
computing the standard deviation and has the same definition as the
corresponding parameter for @code{std}.

If @var{x} is a matrix, calculate along the first non-singleton dimension.
If the third optional argument @var{dim} is given, operate along this
dimension.

The optional outputs @var{mu} and @var{sigma} contain the mean and standard
deviation.

@seealso{mean, std, center}
@end deftypefn
betacdf
@c betacdf scripts/statistics/distributions/betacdf.m
-*- texinfo -*-
@deftypefn {Function File} {} betacdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the Beta distribution with parameters @var{a} and
@var{b}.
@end deftypefn
betainv
@c betainv scripts/statistics/distributions/betainv.m
-*- texinfo -*-
@deftypefn {Function File} {} betainv (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the Beta distribution with parameters @var{a} and @var{b}.
@end deftypefn
betapdf
@c betapdf scripts/statistics/distributions/betapdf.m
-*- texinfo -*-
@deftypefn {Function File} {} betapdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the Beta distribution with parameters @var{a} and @var{b}.
@end deftypefn
betarnd
@c betarnd scripts/statistics/distributions/betarnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} betarnd (@var{a}, @var{b})
@deftypefnx {Function File} {} betarnd (@var{a}, @var{b}, @var{r})
@deftypefnx {Function File} {} betarnd (@var{a}, @var{b}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} betarnd (@var{a}, @var{b}, [@var{sz}])
Return a matrix of random samples from the Beta distribution with parameters
@var{a} and @var{b}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{a} and @var{b}.
@end deftypefn
binocdf
@c binocdf scripts/statistics/distributions/binocdf.m
-*- texinfo -*-
@deftypefn {Function File} {} binocdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the binomial distribution with parameters @var{n} and
@var{p}, where @var{n} is the number of trials and @var{p} is the
probability of success.
@end deftypefn
binoinv
@c binoinv scripts/statistics/distributions/binoinv.m
-*- texinfo -*-
@deftypefn {Function File} {} binoinv (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the binomial distribution with parameters
@var{n} and @var{p}, where @var{n} is the number of trials and
@var{p} is the probability of success.
@end deftypefn
binopdf
@c binopdf scripts/statistics/distributions/binopdf.m
-*- texinfo -*-
@deftypefn {Function File} {} binopdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the binomial distribution with parameters @var{n} and @var{p},
where @var{n} is the number of trials and @var{p} is the probability of
success.
@end deftypefn
binornd
@c binornd scripts/statistics/distributions/binornd.m
-*- texinfo -*-
@deftypefn  {Function File} {} binornd (@var{n}, @var{p})
@deftypefnx {Function File} {} binornd (@var{n}, @var{p}, @var{r})
@deftypefnx {Function File} {} binornd (@var{n}, @var{p}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} binornd (@var{n}, @var{p}, [@var{sz}])
Return a matrix of random samples from the binomial distribution with
parameters @var{n} and @var{p}, where @var{n} is the number of trials
and @var{p} is the probability of success.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{n} and @var{p}.
@end deftypefn
cauchy_cdf
@c cauchy_cdf scripts/statistics/distributions/cauchy_cdf.m
-*- texinfo -*-
@deftypefn  {Function File} {} cauchy_cdf (@var{x})
@deftypefnx {Function File} {} cauchy_cdf (@var{x}, @var{location}, @var{scale})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the Cauchy distribution with location parameter
@var{location} and scale parameter @var{scale}.

Default values are @var{location} = 0, @var{scale} = 1.
@end deftypefn
cauchy_inv
@c cauchy_inv scripts/statistics/distributions/cauchy_inv.m
-*- texinfo -*-
@deftypefn  {Function File} {} cauchy_inv (@var{x})
@deftypefnx {Function File} {} cauchy_inv (@var{x}, @var{location}, @var{scale})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the Cauchy distribution with location parameter
@var{location} and scale parameter @var{scale}.

Default values are @var{location} = 0, @var{scale} = 1.
@end deftypefn
cauchy_pdf
@c cauchy_pdf scripts/statistics/distributions/cauchy_pdf.m
-*- texinfo -*-
@deftypefn  {Function File} {} cauchy_pdf (@var{x})
@deftypefnx {Function File} {} cauchy_pdf (@var{x}, @var{location}, @var{scale})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the Cauchy distribution with location parameter
@var{location} and scale parameter @var{scale} > 0.

Default values are @var{location} = 0, @var{scale} = 1.
@end deftypefn
cauchy_rnd
@c cauchy_rnd scripts/statistics/distributions/cauchy_rnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} cauchy_rnd (@var{location}, @var{scale})
@deftypefnx {Function File} {} cauchy_rnd (@var{location}, @var{scale}, @var{r})
@deftypefnx {Function File} {} cauchy_rnd (@var{location}, @var{scale}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} cauchy_rnd (@var{location}, @var{scale}, [@var{sz}])
Return a matrix of random samples from the Cauchy distribution with
parameters @var{location} and @var{scale}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{location} and @var{scale}.
@end deftypefn
chi2cdf
@c chi2cdf scripts/statistics/distributions/chi2cdf.m
-*- texinfo -*-
@deftypefn {Function File} {} chi2cdf (@var{x}, @var{n})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the chi-square distribution with @var{n} degrees of
freedom.
@end deftypefn
chi2inv
@c chi2inv scripts/statistics/distributions/chi2inv.m
-*- texinfo -*-
@deftypefn {Function File} {} chi2inv (@var{x}, @var{n})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the chi-square distribution with @var{n} degrees of freedom.
@end deftypefn
chi2pdf
@c chi2pdf scripts/statistics/distributions/chi2pdf.m
-*- texinfo -*-
@deftypefn {Function File} {} chi2pdf (@var{x}, @var{n})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the chi-square distribution with @var{n} degrees of freedom.
@end deftypefn
chi2rnd
@c chi2rnd scripts/statistics/distributions/chi2rnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} chi2rnd (@var{n})
@deftypefnx {Function File} {} chi2rnd (@var{n}, @var{r})
@deftypefnx {Function File} {} chi2rnd (@var{n}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} chi2rnd (@var{n}, [@var{sz}])
Return a matrix of random samples from the chi-square distribution with
@var{n} degrees of freedom.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the size of
@var{n}.
@end deftypefn
discrete_cdf
@c discrete_cdf scripts/statistics/distributions/discrete_cdf.m
-*- texinfo -*-
@deftypefn {Function File} {} discrete_cdf (@var{x}, @var{v}, @var{p})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of a univariate discrete distribution which assumes the
values in @var{v} with probabilities @var{p}.
@end deftypefn
discrete_inv
@c discrete_inv scripts/statistics/distributions/discrete_inv.m
-*- texinfo -*-
@deftypefn {Function File} {} discrete_inv (@var{x}, @var{v}, @var{p})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the univariate distribution which assumes the values in
@var{v} with probabilities @var{p}.
@end deftypefn
discrete_pdf
@c discrete_pdf scripts/statistics/distributions/discrete_pdf.m
-*- texinfo -*-
@deftypefn {Function File} {} discrete_pdf (@var{x}, @var{v}, @var{p})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of a univariate discrete distribution which assumes the values
in @var{v} with probabilities @var{p}.
@end deftypefn
discrete_rnd
@c discrete_rnd scripts/statistics/distributions/discrete_rnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} discrete_rnd (@var{v}, @var{p})
@deftypefnx {Function File} {} discrete_rnd (@var{v}, @var{p}, @var{r})
@deftypefnx {Function File} {} discrete_rnd (@var{v}, @var{p}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} discrete_rnd (@var{v}, @var{p}, [@var{sz}])
Return a matrix of random samples from the univariate distribution which
assumes the values in @var{v} with probabilities @var{p}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{v} and @var{p}.
@end deftypefn
empirical_cdf
@c empirical_cdf scripts/statistics/distributions/empirical_cdf.m
-*- texinfo -*-
@deftypefn {Function File} {} empirical_cdf (@var{x}, @var{data})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the empirical distribution obtained from
the univariate sample @var{data}.
@end deftypefn
empirical_inv
@c empirical_inv scripts/statistics/distributions/empirical_inv.m
-*- texinfo -*-
@deftypefn {Function File} {} empirical_inv (@var{x}, @var{data})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the empirical distribution obtained from the
univariate sample @var{data}.
@end deftypefn
empirical_pdf
@c empirical_pdf scripts/statistics/distributions/empirical_pdf.m
-*- texinfo -*-
@deftypefn {Function File} {} empirical_pdf (@var{x}, @var{data})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the empirical distribution obtained from the
univariate sample @var{data}.
@end deftypefn
empirical_rnd
@c empirical_rnd scripts/statistics/distributions/empirical_rnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} empirical_rnd (@var{data})
@deftypefnx {Function File} {} empirical_rnd (@var{data}, @var{r})
@deftypefnx {Function File} {} empirical_rnd (@var{data}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} empirical_rnd (@var{data}, [@var{sz}])
Return a matrix of random samples from the empirical distribution obtained
from the univariate sample @var{data}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is a random ordering
of the sample @var{data}.
@end deftypefn
expcdf
@c expcdf scripts/statistics/distributions/expcdf.m
-*- texinfo -*-
@deftypefn {Function File} {} expcdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the exponential distribution with mean @var{lambda}.

The arguments can be of common size or scalars.
@end deftypefn
expinv
@c expinv scripts/statistics/distributions/expinv.m
-*- texinfo -*-
@deftypefn {Function File} {} expinv (@var{x}, @var{lambda})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the exponential distribution with mean @var{lambda}.
@end deftypefn
exppdf
@c exppdf scripts/statistics/distributions/exppdf.m
-*- texinfo -*-
@deftypefn {Function File} {} exppdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the exponential distribution with mean @var{lambda}.
@end deftypefn
exprnd
@c exprnd scripts/statistics/distributions/exprnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} exprnd (@var{lambda})
@deftypefnx {Function File} {} exprnd (@var{lambda}, @var{r})
@deftypefnx {Function File} {} exprnd (@var{lambda}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} exprnd (@var{lambda}, [@var{sz}])
Return a matrix of random samples from the exponential distribution with
mean @var{lambda}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the size of
@var{lambda}.
@end deftypefn
fcdf
@c fcdf scripts/statistics/distributions/fcdf.m
-*- texinfo -*-
@deftypefn {Function File} {} fcdf (@var{x}, @var{m}, @var{n})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the F distribution with @var{m} and @var{n} degrees of
freedom.
@end deftypefn
finv
@c finv scripts/statistics/distributions/finv.m
-*- texinfo -*-
@deftypefn {Function File} {} finv (@var{x}, @var{m}, @var{n})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the F distribution with @var{m} and @var{n} degrees of freedom.
@end deftypefn
fpdf
@c fpdf scripts/statistics/distributions/fpdf.m
-*- texinfo -*-
@deftypefn {Function File} {} fpdf (@var{x}, @var{m}, @var{n})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the F distribution with @var{m} and @var{n} degrees of freedom.
@end deftypefn
frnd
@c frnd scripts/statistics/distributions/frnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} frnd (@var{m}, @var{n})
@deftypefnx {Function File} {} frnd (@var{m}, @var{n}, @var{r})
@deftypefnx {Function File} {} frnd (@var{m}, @var{n}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} frnd (@var{m}, @var{n}, [@var{sz}])
Return a matrix of random samples from the F distribution with
@var{m} and @var{n} degrees of freedom.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{m} and @var{n}.
@end deftypefn
gamcdf
@c gamcdf scripts/statistics/distributions/gamcdf.m
-*- texinfo -*-
@deftypefn {Function File} {} gamcdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the Gamma distribution with shape parameter @var{a} and
scale @var{b}.
@end deftypefn
gaminv
@c gaminv scripts/statistics/distributions/gaminv.m
-*- texinfo -*-
@deftypefn {Function File} {} gaminv (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the Gamma distribution with shape parameter @var{a} and
scale @var{b}.
@end deftypefn
gampdf
@c gampdf scripts/statistics/distributions/gampdf.m
-*- texinfo -*-
@deftypefn {Function File} {} gampdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, return the probability density function
(PDF) at @var{x} of the Gamma distribution with shape parameter @var{a} and
scale @var{b}.
@end deftypefn
gamrnd
@c gamrnd scripts/statistics/distributions/gamrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} gamrnd (@var{a}, @var{b})
@deftypefnx {Function File} {} gamrnd (@var{a}, @var{b}, @var{r})
@deftypefnx {Function File} {} gamrnd (@var{a}, @var{b}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} gamrnd (@var{a}, @var{b}, [@var{sz}])
Return a matrix of random samples from the Gamma distribution with
shape parameter @var{a} and scale @var{b}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{a} and @var{b}.
@end deftypefn
geocdf
@c geocdf scripts/statistics/distributions/geocdf.m
-*- texinfo -*-
@deftypefn {Function File} {} geocdf (@var{x}, @var{p})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the geometric distribution with parameter @var{p}.

The geometric distribution models the number of failures (@var{x}-1) of a
Bernoulli trial with probability @var{p} before the first success (@var{x}).
@end deftypefn
geoinv
@c geoinv scripts/statistics/distributions/geoinv.m
-*- texinfo -*-
@deftypefn {Function File} {} geoinv (@var{x}, @var{p})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the geometric distribution with parameter @var{p}.

The geometric distribution models the number of failures (@var{x}-1) of a
Bernoulli trial with probability @var{p} before the first success (@var{x}).
@end deftypefn
geopdf
@c geopdf scripts/statistics/distributions/geopdf.m
-*- texinfo -*-
@deftypefn {Function File} {} geopdf (@var{x}, @var{p})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the geometric distribution with parameter @var{p}.

The geometric distribution models the number of failures (@var{x}-1) of a
Bernoulli trial with probability @var{p} before the first success (@var{x}).
@end deftypefn
geornd
@c geornd scripts/statistics/distributions/geornd.m
-*- texinfo -*-
@deftypefn  {Function File} {} geornd (@var{p})
@deftypefnx {Function File} {} geornd (@var{p}, @var{r})
@deftypefnx {Function File} {} geornd (@var{p}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} geornd (@var{p}, [@var{sz}])
Return a matrix of random samples from the geometric distribution with
parameter @var{p}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the size of
@var{p}.

The geometric distribution models the number of failures (@var{x}-1) of a
Bernoulli trial with probability @var{p} before the first success (@var{x}).
@end deftypefn
hygecdf
@c hygecdf scripts/statistics/distributions/hygecdf.m
-*- texinfo -*-
@deftypefn {Function File} {} hygecdf (@var{x}, @var{t}, @var{m}, @var{n})
Compute the cumulative distribution function (CDF) at @var{x} of the
hypergeometric distribution with parameters @var{t}, @var{m}, and @var{n}.

This is the probability of obtaining not more than @var{x} marked items
when randomly drawing a sample of size @var{n} without replacement from a
population of total size @var{t} containing @var{m} marked items.

The parameters @var{t}, @var{m}, and @var{n} must be positive integers
with @var{m} and @var{n} not greater than @var{t}.
@end deftypefn
hygeinv
@c hygeinv scripts/statistics/distributions/hygeinv.m
-*- texinfo -*-
@deftypefn {Function File} {} hygeinv (@var{x}, @var{t}, @var{m}, @var{n})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the hypergeometric distribution with parameters
@var{t}, @var{m}, and @var{n}.

This is the probability of obtaining @var{x} marked items when randomly
drawing a sample of size @var{n} without replacement from a population of
total size @var{t} containing @var{m} marked items.

The parameters @var{t}, @var{m}, and @var{n} must be positive integers
with @var{m} and @var{n} not greater than @var{t}.
@end deftypefn
hygepdf
@c hygepdf scripts/statistics/distributions/hygepdf.m
-*- texinfo -*-
@deftypefn {Function File} {} hygepdf (@var{x}, @var{t}, @var{m}, @var{n})
Compute the probability density function (PDF) at @var{x} of the
hypergeometric distribution with parameters @var{t}, @var{m}, and @var{n}.

This is the probability of obtaining @var{x} marked items when randomly
drawing a sample of size @var{n} without replacement from a population of
total size @var{t} containing @var{m} marked items.

The parameters @var{t}, @var{m}, and @var{n} must be positive integers
with @var{m} and @var{n} not greater than @var{t}.
@end deftypefn
hygernd
@c hygernd scripts/statistics/distributions/hygernd.m
-*- texinfo -*-
@deftypefn  {Function File} {} hygernd (@var{t}, @var{m}, @var{n})
@deftypefnx {Function File} {} hygernd (@var{t}, @var{m}, @var{n}, @var{r})
@deftypefnx {Function File} {} hygernd (@var{t}, @var{m}, @var{n}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} hygernd (@var{t}, @var{m}, @var{n}, [@var{sz}])
Return a matrix of random samples from the hypergeometric distribution
with parameters @var{t}, @var{m}, and @var{n}.

The parameters @var{t}, @var{m}, and @var{n} must be positive integers
with @var{m} and @var{n} not greater than @var{t}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{t}, @var{m}, and @var{n}.
@end deftypefn
kolmogorov_smirnov_cdf
@c kolmogorov_smirnov_cdf scripts/statistics/distributions/kolmogorov_smirnov_cdf.m
-*- texinfo -*-
@deftypefn {Function File} {} kolmogorov_smirnov_cdf (@var{x}, @var{tol})
Return the cumulative distribution function (CDF) at @var{x} of the
Kolmogorov-Smirnov distribution.

This is defined as
@tex
$$ Q(x) = \sum_{k=-\infty}^\infty (-1)^k \exp (-2 k^2 x^2) $$
@end tex
@ifnottex

@example
@group
         Inf
Q(x) =   SUM    (-1)^k exp (-2 k^2 x^2)
       k = -Inf
@end group
@end example

@end ifnottex
@noindent
for @var{x} > 0.

The optional parameter @var{tol} specifies the precision up to which
the series should be evaluated; the default is @var{tol} = @code{eps}.
@end deftypefn
laplace_cdf
@c laplace_cdf scripts/statistics/distributions/laplace_cdf.m
-*- texinfo -*-
@deftypefn {Function File} {} laplace_cdf (@var{x})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the Laplace distribution.
@end deftypefn
laplace_inv
@c laplace_inv scripts/statistics/distributions/laplace_inv.m
-*- texinfo -*-
@deftypefn {Function File} {} laplace_inv (@var{x})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the Laplace distribution.
@end deftypefn
laplace_pdf
@c laplace_pdf scripts/statistics/distributions/laplace_pdf.m
-*- texinfo -*-
@deftypefn {Function File} {} laplace_pdf (@var{x})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the Laplace distribution.
@end deftypefn
laplace_rnd
@c laplace_rnd scripts/statistics/distributions/laplace_rnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} laplace_rnd (@var{r})
@deftypefnx {Function File} {} laplace_rnd (@var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} laplace_rnd ([@var{sz}])
Return a matrix of random samples from the Laplace distribution.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.
@end deftypefn
logistic_cdf
@c logistic_cdf scripts/statistics/distributions/logistic_cdf.m
-*- texinfo -*-
@deftypefn {Function File} {} logistic_cdf (@var{x})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the logistic distribution.
@end deftypefn
logistic_inv
@c logistic_inv scripts/statistics/distributions/logistic_inv.m
-*- texinfo -*-
@deftypefn {Function File} {} logistic_inv (@var{x})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the logistic distribution.
@end deftypefn
logistic_pdf
@c logistic_pdf scripts/statistics/distributions/logistic_pdf.m
-*- texinfo -*-
@deftypefn {Function File} {} logistic_pdf (@var{x})
For each element of @var{x}, compute the PDF at @var{x} of the
logistic distribution.
@end deftypefn
logistic_rnd
@c logistic_rnd scripts/statistics/distributions/logistic_rnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} logistic_rnd (@var{r})
@deftypefnx {Function File} {} logistic_rnd (@var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} logistic_rnd ([@var{sz}])
Return a matrix of random samples from the logistic distribution.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.
@end deftypefn
logncdf
@c logncdf scripts/statistics/distributions/logncdf.m
-*- texinfo -*-
@deftypefn  {Function File} {} logncdf (@var{x})
@deftypefnx {Function File} {} logncdf (@var{x}, @var{mu}, @var{sigma})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the lognormal distribution with parameters
@var{mu} and @var{sigma}.

If a random variable follows this distribution, its logarithm is normally
distributed with mean @var{mu} and standard deviation @var{sigma}.

Default values are @var{mu} = 0, @var{sigma} = 1.
@end deftypefn
logninv
@c logninv scripts/statistics/distributions/logninv.m
-*- texinfo -*-
@deftypefn  {Function File} {} logninv (@var{x})
@deftypefnx {Function File} {} logninv (@var{x}, @var{mu}, @var{sigma})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the lognormal distribution with parameters
@var{mu} and @var{sigma}.

If a random variable follows this distribution, its logarithm is normally
distributed with mean @var{mu} and standard deviation @var{sigma}.

Default values are @var{mu} = 0, @var{sigma} = 1.
@end deftypefn
lognpdf
@c lognpdf scripts/statistics/distributions/lognpdf.m
-*- texinfo -*-
@deftypefn  {Function File} {} lognpdf (@var{x})
@deftypefnx {Function File} {} lognpdf (@var{x}, @var{mu}, @var{sigma})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the lognormal distribution with parameters
@var{mu} and @var{sigma}.

If a random variable follows this distribution, its logarithm is normally
distributed with mean @var{mu} and standard deviation @var{sigma}.

Default values are @var{mu} = 0, @var{sigma} = 1.
@end deftypefn
lognrnd
@c lognrnd scripts/statistics/distributions/lognrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} lognrnd (@var{mu}, @var{sigma})
@deftypefnx {Function File} {} lognrnd (@var{mu}, @var{sigma}, @var{r})
@deftypefnx {Function File} {} lognrnd (@var{mu}, @var{sigma}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} lognrnd (@var{mu}, @var{sigma}, [@var{sz}])
Return a matrix of random samples from the lognormal distribution with
parameters @var{mu} and @var{sigma}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{mu} and @var{sigma}.
@end deftypefn
nbincdf
@c nbincdf scripts/statistics/distributions/nbincdf.m
-*- texinfo -*-
@deftypefn {Function File} {} nbincdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the negative binomial distribution with parameters
@var{n} and @var{p}.

When @var{n} is integer this is the Pascal distribution.
When @var{n} is extended to real numbers this is the Polya distribution.

The number of failures in a Bernoulli experiment with success probability
@var{p} before the @var{n}-th success follows this distribution.
@end deftypefn
nbininv
@c nbininv scripts/statistics/distributions/nbininv.m
-*- texinfo -*-
@deftypefn {Function File} {} nbininv (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the negative binomial distribution with parameters
@var{n} and @var{p}.

When @var{n} is integer this is the Pascal distribution.
When @var{n} is extended to real numbers this is the Polya distribution.

The number of failures in a Bernoulli experiment with success probability
@var{p} before the @var{n}-th success follows this distribution.
@end deftypefn
nbinpdf
@c nbinpdf scripts/statistics/distributions/nbinpdf.m
-*- texinfo -*-
@deftypefn {Function File} {} nbinpdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the negative binomial distribution with parameters
@var{n} and @var{p}.

When @var{n} is integer this is the Pascal distribution.
When @var{n} is extended to real numbers this is the Polya distribution.

The number of failures in a Bernoulli experiment with success probability
@var{p} before the @var{n}-th success follows this distribution.
@end deftypefn
nbinrnd
@c nbinrnd scripts/statistics/distributions/nbinrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} nbinrnd (@var{n}, @var{p})
@deftypefnx {Function File} {} nbinrnd (@var{n}, @var{p}, @var{r})
@deftypefnx {Function File} {} nbinrnd (@var{n}, @var{p}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} nbinrnd (@var{n}, @var{p}, [@var{sz}])
Return a matrix of random samples from the negative binomial distribution
with parameters @var{n} and @var{p}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{n} and @var{p}.
@end deftypefn
normcdf
@c normcdf scripts/statistics/distributions/normcdf.m
-*- texinfo -*-
@deftypefn  {Function File} {} normcdf (@var{x})
@deftypefnx {Function File} {} normcdf (@var{x}, @var{mu}, @var{sigma})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the normal distribution with mean @var{mu} and
standard deviation @var{sigma}.

Default values are @var{mu} = 0, @var{sigma} = 1.
@end deftypefn
norminv
@c norminv scripts/statistics/distributions/norminv.m
-*- texinfo -*-
@deftypefn  {Function File} {} norminv (@var{x})
@deftypefnx {Function File} {} norminv (@var{x}, @var{mu}, @var{sigma})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the normal distribution with mean @var{mu} and
standard deviation @var{sigma}.

Default values are @var{mu} = 0, @var{sigma} = 1.
@end deftypefn
normpdf
@c normpdf scripts/statistics/distributions/normpdf.m
-*- texinfo -*-
@deftypefn  {Function File} {} normpdf (@var{x})
@deftypefnx {Function File} {} normpdf (@var{x}, @var{mu}, @var{sigma})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the normal distribution with mean @var{mu} and
standard deviation @var{sigma}.

Default values are @var{mu} = 0, @var{sigma} = 1.
@end deftypefn
normrnd
@c normrnd scripts/statistics/distributions/normrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} normrnd (@var{mu}, @var{sigma})
@deftypefnx {Function File} {} normrnd (@var{mu}, @var{sigma}, @var{r})
@deftypefnx {Function File} {} normrnd (@var{mu}, @var{sigma}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} normrnd (@var{mu}, @var{sigma}, [@var{sz}])
Return a matrix of random samples from the normal distribution with
parameters mean @var{mu} and standard deviation @var{sigma}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{mu} and @var{sigma}.
@end deftypefn
poisscdf
@c poisscdf scripts/statistics/distributions/poisscdf.m
-*- texinfo -*-
@deftypefn {Function File} {} poisscdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the Poisson distribution with parameter @var{lambda}.
@end deftypefn
poissinv
@c poissinv scripts/statistics/distributions/poissinv.m
-*- texinfo -*-
@deftypefn {Function File} {} poissinv (@var{x}, @var{lambda})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the Poisson distribution with parameter @var{lambda}.
@end deftypefn
poisspdf
@c poisspdf scripts/statistics/distributions/poisspdf.m
-*- texinfo -*-
@deftypefn {Function File} {} poisspdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the Poisson distribution with parameter @var{lambda}.
@end deftypefn
poissrnd
@c poissrnd scripts/statistics/distributions/poissrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} poissrnd (@var{lambda})
@deftypefnx {Function File} {} poissrnd (@var{lambda}, @var{r})
@deftypefnx {Function File} {} poissrnd (@var{lambda}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} poissrnd (@var{lambda}, [@var{sz}])
Return a matrix of random samples from the Poisson distribution with
parameter @var{lambda}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the size of
@var{lambda}.
@end deftypefn
stdnormal_cdf
@c stdnormal_cdf scripts/statistics/distributions/stdnormal_cdf.m
-*- texinfo -*-
@deftypefn {Function File} {} stdnormal_cdf (@var{x})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the standard normal distribution
(mean = 0, standard deviation = 1).
@end deftypefn
stdnormal_inv
@c stdnormal_inv scripts/statistics/distributions/stdnormal_inv.m
-*- texinfo -*-
@deftypefn {Function File} {} stdnormal_inv (@var{x})
For each element of @var{x}, compute the quantile (the
inverse of the CDF) at @var{x} of the standard normal distribution
(mean = 0, standard deviation = 1).
@end deftypefn
stdnormal_pdf
@c stdnormal_pdf scripts/statistics/distributions/stdnormal_pdf.m
-*- texinfo -*-
@deftypefn {Function File} {} stdnormal_pdf (@var{x})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the standard normal distribution
(mean = 0, standard deviation = 1).
@end deftypefn
stdnormal_rnd
@c stdnormal_rnd scripts/statistics/distributions/stdnormal_rnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} stdnormal_rnd (@var{r})
@deftypefnx {Function File} {} stdnormal_rnd (@var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} stdnormal_rnd ([@var{sz}])
Return a matrix of random samples from the standard normal distribution
(mean = 0, standard deviation = 1).

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.
@end deftypefn
tcdf
@c tcdf scripts/statistics/distributions/tcdf.m
-*- texinfo -*-
@deftypefn {Function File} {} tcdf (@var{x}, @var{n})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the t (Student) distribution with
@var{n} degrees of freedom.
@end deftypefn
tinv
@c tinv scripts/statistics/distributions/tinv.m
-*- texinfo -*-
@deftypefn {Function File} {} tinv (@var{x}, @var{n})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the t (Student) distribution with @var{n}
degrees of freedom.

This function is analogous to looking in a table for the t-value of a
single-tailed distribution.
@end deftypefn
tpdf
@c tpdf scripts/statistics/distributions/tpdf.m
-*- texinfo -*-
@deftypefn {Function File} {} tpdf (@var{x}, @var{n})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the @var{t} (Student) distribution with
@var{n} degrees of freedom.
@end deftypefn
trnd
@c trnd scripts/statistics/distributions/trnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} trnd (@var{n})
@deftypefnx {Function File} {} trnd (@var{n}, @var{r})
@deftypefnx {Function File} {} trnd (@var{n}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} trnd (@var{n}, [@var{sz}])
Return a matrix of random samples from the t (Student) distribution with
@var{n} degrees of freedom.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the size of
@var{n}.
@end deftypefn
unidrnd
@c unidrnd scripts/statistics/distributions/unidrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} unidrnd (@var{n})
@deftypefnx {Function File} {} unidrnd (@var{n}, @var{r})
@deftypefnx {Function File} {} unidrnd (@var{n}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} unidrnd (@var{n}, [@var{sz}])
Return a matrix of random samples from the discrete uniform distribution
which assumes the integer values 1--@var{n} with equal probability.

@var{n} may be a scalar or a multi-dimensional array.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the size of
@var{n}.
@end deftypefn
unidcdf
@c unidcdf scripts/statistics/distributions/unidcdf.m
-*- texinfo -*-
@deftypefn {Function File} {} unidcdf (@var{x}, @var{n})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of a discrete uniform distribution which assumes
the integer values 1--@var{n} with equal probability.
@end deftypefn
unidinv
@c unidinv scripts/statistics/distributions/unidinv.m
-*- texinfo -*-
@deftypefn {Function File} {} unidinv (@var{x}, @var{n})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the discrete uniform distribution which assumes
the integer values 1--@var{n} with equal probability.
@end deftypefn
unidpdf
@c unidpdf scripts/statistics/distributions/unidpdf.m
-*- texinfo -*-
@deftypefn {Function File} {} unidpdf (@var{x}, @var{n})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of a discrete uniform distribution which assumes
the integer values 1--@var{n} with equal probability.

Warning: The underlying implementation uses the double class and will only
be accurate for @var{n} @leq{} @code{bitmax} (@w{@math{2^{53} - 1}} on
IEEE 754 compatible systems).
@end deftypefn
unifrnd
@c unifrnd scripts/statistics/distributions/unifrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} unifrnd (@var{a}, @var{b})
@deftypefnx {Function File} {} unifrnd (@var{a}, @var{b}, @var{r})
@deftypefnx {Function File} {} unifrnd (@var{a}, @var{b}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} unifrnd (@var{a}, @var{b}, [@var{sz}])
Return a matrix of random samples from the uniform distribution on
[@var{a}, @var{b}].

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{a} and @var{b}.
@end deftypefn
unifcdf
@c unifcdf scripts/statistics/distributions/unifcdf.m
-*- texinfo -*-
@deftypefn  {Function File} {} unifcdf (@var{x})
@deftypefnx {Function File} {} unifcdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the cumulative distribution function
(CDF) at @var{x} of the uniform distribution on the interval
[@var{a}, @var{b}].

Default values are @var{a} = 0, @var{b} = 1.
@end deftypefn
unifinv
@c unifinv scripts/statistics/distributions/unifinv.m
-*- texinfo -*-
@deftypefn  {Function File} {} unifinv (@var{x})
@deftypefnx {Function File} {} unifinv (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the quantile (the inverse of the CDF)
at @var{x} of the uniform distribution on the interval [@var{a}, @var{b}].

Default values are @var{a} = 0, @var{b} = 1.
@end deftypefn
unifpdf
@c unifpdf scripts/statistics/distributions/unifpdf.m
-*- texinfo -*-
@deftypefn  {Function File} {} unifpdf (@var{x})
@deftypefnx {Function File} {} unifpdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the probability density function (PDF)
at @var{x} of the uniform distribution on the interval [@var{a}, @var{b}].

Default values are @var{a} = 0, @var{b} = 1.
@end deftypefn
wblcdf
@c wblcdf scripts/statistics/distributions/wblcdf.m
-*- texinfo -*-
@deftypefn  {Function File} {} wblcdf (@var{x})
@deftypefnx {Function File} {} wblcdf (@var{x}, @var{scale})
@deftypefnx {Function File} {} wblcdf (@var{x}, @var{scale}, @var{shape})
Compute the cumulative distribution function (CDF) at @var{x} of the
Weibull distribution with scale parameter @var{scale} and shape
parameter @var{shape}.

This is defined as
@tex
$$ 1 - e^{-({x \over scale})^{shape}} $$
for $x \geq 0$.
@end tex
@ifnottex

@example
1 - exp (-(x/scale)^shape)
@end example

@noindent
for @var{x} @geq{} 0.

Default values are @var{scale} = 1, @var{shape} = 1.
@end ifnottex
@end deftypefn
wblinv
@c wblinv scripts/statistics/distributions/wblinv.m
-*- texinfo -*-
@deftypefn  {Function File} {} wblinv (@var{x})
@deftypefnx {Function File} {} wblinv (@var{x}, @var{scale})
@deftypefnx {Function File} {} wblinv (@var{x}, @var{scale}, @var{shape})
Compute the quantile (the inverse of the CDF) at @var{x} of the
Weibull distribution with scale parameter @var{scale} and
shape parameter @var{shape}.

Default values are @var{scale} = 1, @var{shape} = 1.
@end deftypefn
wblpdf
@c wblpdf scripts/statistics/distributions/wblpdf.m
-*- texinfo -*-
@deftypefn  {Function File} {} wblpdf (@var{x})
@deftypefnx {Function File} {} wblpdf (@var{x}, @var{scale})
@deftypefnx {Function File} {} wblpdf (@var{x}, @var{scale}, @var{shape})
Compute the probability density function (PDF) at @var{x} of the
Weibull distribution with scale parameter @var{scale} and
shape parameter @var{shape}.

This is given by
@tex
$$  {shape \over scale^{shape}} \cdot x^{shape-1} \cdot e^{-({x \over scale})^{shape}} $$
@end tex
@ifnottex

@example
shape * scale^(-shape) * x^(shape-1) * exp (-(x/scale)^shape)
@end example

@end ifnottex
@noindent
for @var{x} @geq{} 0.

Default values are @var{scale} = 1, @var{shape} = 1.
@end deftypefn
wblrnd
@c wblrnd scripts/statistics/distributions/wblrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} wblrnd (@var{scale}, @var{shape})
@deftypefnx {Function File} {} wblrnd (@var{scale}, @var{shape}, @var{r})
@deftypefnx {Function File} {} wblrnd (@var{scale}, @var{shape}, @var{r}, @var{c}, @dots{})
@deftypefnx {Function File} {} wblrnd (@var{scale}, @var{shape}, [@var{sz}])
Return a matrix of random samples from the Weibull distribution with
parameters @var{scale} and @var{shape}.

When called with a single size argument, return a square matrix with
the dimension specified.  When called with more than one scalar argument the
first two arguments are taken as the number of rows and columns and any
further arguments specify additional matrix dimensions.  The size may also
be specified with a vector of dimensions @var{sz}.

If no size arguments are given then the result matrix is the common size of
@var{scale} and @var{shape}.
@end deftypefn
wienrnd
@c wienrnd scripts/statistics/distributions/wienrnd.m
-*- texinfo -*-
@deftypefn {Function File} {} wienrnd (@var{t}, @var{d}, @var{n})
Return a simulated realization of the @var{d}-dimensional Wiener Process
on the interval [0, @var{t}].

If @var{d} is omitted, @var{d} = 1 is used.  The first column of the
return matrix contains time, the remaining columns contain the Wiener
process.

The optional parameter @var{n} defines the number of summands used for
simulating the process over an interval of length 1.  If @var{n} is
omitted, @var{n} = 1000 is used.
@end deftypefn
logistic_regression
@c logistic_regression scripts/statistics/models/logistic_regression.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{theta}, @var{beta}, @var{dev}, @var{dl}, @var{d2l}, @var{p}] =} logistic_regression (@var{y}, @var{x}, @var{print}, @var{theta}, @var{beta})
Perform ordinal logistic regression.

Suppose @var{y} takes values in @var{k} ordered categories, and let
@code{gamma_i (@var{x})} be the cumulative probability that @var{y}
falls in one of the first @var{i} categories given the covariate
@var{x}.  Then

@example
[theta, beta] = logistic_regression (y, x)
@end example

@noindent
fits the model

@example
logit (gamma_i (x)) = theta_i - beta' * x,   i = 1 @dots{} k-1
@end example

The number of ordinal categories, @var{k}, is taken to be the number
of distinct values of @code{round (@var{y})}.  If @var{k} equals 2,
@var{y} is binary and the model is ordinary logistic regression.  The
matrix @var{x} is assumed to have full column rank.

Given @var{y} only, @code{theta = logistic_regression (y)}
fits the model with baseline logit odds only.

The full form is

@example
@group
[theta, beta, dev, dl, d2l, gamma]
   = logistic_regression (y, x, print, theta, beta)
@end group
@end example

@noindent
in which all output arguments and all input arguments except @var{y}
are optional.

Setting @var{print} to 1 requests summary information about the fitted
model to be displayed.  Setting @var{print} to 2 requests information
about convergence at each iteration.  Other values request no
information to be displayed.  The input arguments @var{theta} and
@var{beta} give initial estimates for @var{theta} and @var{beta}.

The returned value @var{dev} holds minus twice the log-likelihood.

The returned values @var{dl} and @var{d2l} are the vector of first
and the matrix of second derivatives of the log-likelihood with
respect to @var{theta} and @var{beta}.

@var{p} holds estimates for the conditional distribution of @var{y}
given @var{x}.
@end deftypefn
anova
@c anova scripts/statistics/tests/anova.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{f}, @var{df_b}, @var{df_w}] =} anova (@var{y}, @var{g})
Perform a one-way analysis of variance (ANOVA).

The goal is to test whether the population means of data taken from
@var{k} different groups are all equal.

Data may be given in a single vector @var{y} with groups specified by a
corresponding vector of group labels @var{g} (e.g., numbers from 1 to
@var{k}).  This is the general form which does not impose any restriction
on the number of data in each group or the group labels.

If @var{y} is a matrix and @var{g} is omitted, each column of @var{y} is
treated as a group.  This form is only appropriate for balanced ANOVA in
which the numbers of samples from each group are all equal.

Under the null of constant means, the statistic @var{f} follows an F
distribution with @var{df_b} and @var{df_w} degrees of freedom.

The p-value (1 minus the CDF of this distribution at @var{f}) is returned
in @var{pval}.

If no output argument is given, the standard one-way ANOVA table is printed.
@seealso{manova}
@end deftypefn
bartlett_test
@c bartlett_test scripts/statistics/tests/bartlett_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{chisq}, @var{df}] =} bartlett_test (@var{x1}, @dots{})
Perform a Bartlett test for the homogeneity of variances in the data
vectors @var{x1}, @var{x2}, @dots{}, @var{xk}, where @var{k} > 1.

Under the null of equal variances, the test statistic @var{chisq}
approximately follows a chi-square distribution with @var{df} degrees of
freedom.

The p-value (1 minus the CDF of this distribution at @var{chisq}) is
returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn
chisquare_test_homogeneity
@c chisquare_test_homogeneity scripts/statistics/tests/chisquare_test_homogeneity.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{chisq}, @var{df}] =} chisquare_test_homogeneity (@var{x}, @var{y}, @var{c})
Given two samples @var{x} and @var{y}, perform a chisquare test for
homogeneity of the null hypothesis that @var{x} and @var{y} come from
the same distribution, based on the partition induced by the
(strictly increasing) entries of @var{c}.

For large samples, the test statistic @var{chisq} approximately follows a
chisquare distribution with @var{df} = @code{length (@var{c})} degrees of
freedom.

The p-value (1 minus the CDF of this distribution at @var{chisq}) is
returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn
chisquare_test_independence
@c chisquare_test_independence scripts/statistics/tests/chisquare_test_independence.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{chisq}, @var{df}] =} chisquare_test_independence (@var{x})
Perform a chi-square test for independence based on the contingency table
@var{x}.

Under the null hypothesis of independence, @var{chisq} approximately has a
chi-square distribution with @var{df} degrees of freedom.

The p-value (1 minus the CDF of this distribution at chisq) of the test is
returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn
cor_test
@c cor_test scripts/statistics/tests/cor_test.m
-*- texinfo -*-
@deftypefn {Function File} {} cor_test (@var{x}, @var{y}, @var{alt}, @var{method})
Test whether two samples @var{x} and @var{y} come from uncorrelated
populations.

The optional argument string @var{alt} describes the alternative
hypothesis, and can be @qcode{"!="} or @qcode{"<>"} (nonzero), @qcode{">"}
(greater than 0), or @qcode{"<"} (less than 0).  The default is the
two-sided case.

The optional argument string @var{method} specifies which correlation
coefficient to use for testing.  If @var{method} is @qcode{"pearson"}
(default), the (usual) Pearson's produt moment correlation coefficient is
used.  In this case, the data should come from a bivariate normal
distribution.  Otherwise, the other two methods offer nonparametric
alternatives.  If @var{method} is @qcode{"kendall"}, then Kendall's rank
correlation tau is used.  If @var{method} is @qcode{"spearman"}, then
Spearman's rank correlation rho is used.  Only the first character is
necessary.

The output is a structure with the following elements:

@table @var
@item pval
The p-value of the test.

@item stat
The value of the test statistic.

@item dist
The distribution of the test statistic.

@item params
The parameters of the null distribution of the test statistic.

@item alternative
The alternative hypothesis.

@item method
The method used for testing.
@end table

If no output argument is given, the p-value is displayed.
@end deftypefn
f_test_regression
@c f_test_regression scripts/statistics/tests/f_test_regression.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{f}, @var{df_num}, @var{df_den}] =} f_test_regression (@var{y}, @var{x}, @var{rr}, @var{r})
Perform an F test for the null hypothesis @nospell{rr * b = r} in a
classical normal regression model y = X * b + e.

Under the null, the test statistic @var{f} follows an F distribution with
@var{df_num} and @var{df_den} degrees of freedom.

The p-value (1 minus the CDF of this distribution at @var{f}) is returned
in @var{pval}.

If not given explicitly, @var{r} = 0.

If no output argument is given, the p-value is displayed.
@end deftypefn
hotelling_test
@c hotelling_test scripts/statistics/tests/hotelling_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{tsq}] =} hotelling_test (@var{x}, @var{m})
For a sample @var{x} from a multivariate normal distribution with unknown
mean and covariance matrix, test the null hypothesis that
@code{mean (@var{x}) == @var{m}}.

Hotelling's @math{T^2} is returned in @var{tsq}.  Under the null,
@math{(n-p) T^2 / (p(n-1))} has an F distribution with @math{p} and
@math{n-p} degrees of freedom, where @math{n} and @math{p} are the
numbers of samples and variables, respectively.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
hotelling_test_2
@c hotelling_test_2 scripts/statistics/tests/hotelling_test_2.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{tsq}] =} hotelling_test_2 (@var{x}, @var{y})
For two samples @var{x} from multivariate normal distributions with
the same number of variables (columns), unknown means and unknown
equal covariance matrices, test the null hypothesis @code{mean
(@var{x}) == mean (@var{y})}.

Hotelling's two-sample @math{T^2} is returned in @var{tsq}.  Under the null,
@tex
$$
{(n_x+n_y-p-1) T^2 \over p(n_x+n_y-2)}
$$
@end tex
@ifnottex

@example
(n_x+n_y-p-1) T^2 / (p(n_x+n_y-2))
@end example

@end ifnottex
@noindent
has an F distribution with @math{p} and @math{n_x+n_y-p-1} degrees of
freedom, where @math{n_x} and @math{n_y} are the sample sizes and
@math{p} is the number of variables.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
kolmogorov_smirnov_test
@c kolmogorov_smirnov_test scripts/statistics/tests/kolmogorov_smirnov_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{ks}] =} kolmogorov_smirnov_test (@var{x}, @var{dist}, @var{params}, @var{alt})
Perform a Kolmogorov-Smirnov test of the null hypothesis that the
sample @var{x} comes from the (continuous) distribution @var{dist}.

if F and G are the CDFs corresponding to the sample and dist,
respectively, then the null is that F == G.

The optional argument @var{params} contains a list of parameters of
@var{dist}.  For example, to test whether a sample @var{x} comes from
a uniform distribution on [2,4], use

@example
kolmogorov_smirnov_test (x, "unif", 2, 4)
@end example

@noindent
@var{dist} can be any string for which a function @var{distcdf}
that calculates the CDF of distribution @var{dist} exists.

With the optional argument string @var{alt}, the alternative of interest
can be selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
is tested against the two-sided alternative F != G@.  In this case, the
test statistic @var{ks} follows a two-sided Kolmogorov-Smirnov
distribution.  If @var{alt} is @qcode{">"}, the one-sided alternative F >
G is considered.  Similarly for @qcode{"<"}, the one-sided alternative F >
G is considered.  In this case, the test statistic @var{ks} has a
one-sided Kolmogorov-Smirnov distribution.  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn
kolmogorov_smirnov_test_2
@c kolmogorov_smirnov_test_2 scripts/statistics/tests/kolmogorov_smirnov_test_2.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{ks}, @var{d}] =} kolmogorov_smirnov_test_2 (@var{x}, @var{y}, @var{alt})
Perform a 2-sample Kolmogorov-Smirnov test of the null hypothesis that the
samples @var{x} and @var{y} come from the same (continuous) distribution.

If F and G are the CDFs corresponding to the @var{x} and @var{y} samples,
respectively, then the null is that F == G.

With the optional argument string @var{alt}, the alternative of interest
can be selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
is tested against the two-sided alternative F != G@.  In this case, the
test statistic @var{ks} follows a two-sided Kolmogorov-Smirnov
distribution.  If @var{alt} is @qcode{">"}, the one-sided alternative F >
G is considered.  Similarly for @qcode{"<"}, the one-sided alternative F <
G is considered.  In this case, the test statistic @var{ks} has a
one-sided Kolmogorov-Smirnov distribution.  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

The third returned value, @var{d}, is the test statistic, the maximum
vertical distance between the two cumulative distribution functions.

If no output argument is given, the p-value is displayed.
@end deftypefn
kruskal_wallis_test
@c kruskal_wallis_test scripts/statistics/tests/kruskal_wallis_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{k}, @var{df}] =} kruskal_wallis_test (@var{x1}, @dots{})
Perform a @nospell{Kruskal-Wallis} one-factor analysis of variance.

Suppose a variable is observed for @var{k} > 1 different groups, and let
@var{x1}, @dots{}, @var{xk} be the corresponding data vectors.

Under the null hypothesis that the ranks in the pooled sample are not
affected by the group memberships, the test statistic @var{k} is
approximately chi-square with @var{df} = @var{k} - 1 degrees of freedom.

If the data contains ties (some value appears more than once)
@var{k} is divided by

1 - @var{sum_ties} / (@var{n}^3 - @var{n})

where @var{sum_ties} is the sum of @var{t}^2 - @var{t} over each group of
ties where @var{t} is the number of ties in the group and @var{n} is the
total number of values in the input data.  For more info on this
adjustment see @nospell{William H. Kruskal and W. Allen Wallis},
@cite{Use of Ranks in One-Criterion Variance Analysis},
Journal of the American Statistical Association, Vol. 47, No. 260 (Dec 1952).

The p-value (1 minus the CDF of this distribution at @var{k}) is returned
in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn
manova
@c manova scripts/statistics/tests/manova.m
-*- texinfo -*-
@deftypefn {Function File} {} manova (@var{x}, @var{g})
Perform a one-way multivariate analysis of variance (MANOVA).

The goal is to test whether the p-dimensional population means of data
taken from @var{k} different groups are all equal.  All data are assumed
drawn independently from p-dimensional normal distributions with the same
covariance matrix.

The data matrix is given by @var{x}.  As usual, rows are observations and
columns are variables.  The vector @var{g} specifies the corresponding
group labels (e.g., numbers from 1 to @var{k}).

The LR test statistic (@nospell{Wilks' Lambda}) and approximate p-values are
computed and displayed.
@seealso{anova}
@end deftypefn
mcnemar_test
@c mcnemar_test scripts/statistics/tests/mcnemar_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{chisq}, @var{df}] =} mcnemar_test (@var{x})
For a square contingency table @var{x} of data cross-classified on the row
and column variables, @nospell{McNemar's} test can be used for testing the
null hypothesis of symmetry of the classification probabilities.

Under the null, @var{chisq} is approximately distributed as chisquare with
@var{df} degrees of freedom.

The p-value (1 minus the CDF of this distribution at @var{chisq}) is
returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
prop_test_2
@c prop_test_2 scripts/statistics/tests/prop_test_2.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{z}] =} prop_test_2 (@var{x1}, @var{n1}, @var{x2}, @var{n2}, @var{alt})
If @var{x1} and @var{n1} are the counts of successes and trials in one
sample, and @var{x2} and @var{n2} those in a second one, test the null
hypothesis that the success probabilities @var{p1} and @var{p2} are the
same.

Under the null, the test statistic @var{z} approximately follows a
standard normal distribution.

With the optional argument string @var{alt}, the alternative of interest
can be selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
is tested against the two-sided alternative @var{p1} != @var{p2}.  If
@var{alt} is @qcode{">"}, the one-sided alternative @var{p1} > @var{p2} is
used.  Similarly for @qcode{"<"}, the one-sided alternative
@var{p1} < @var{p2} is used.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
run_test
@c run_test scripts/statistics/tests/run_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{chisq}] =} run_test (@var{x})
Perform a chi-square test with 6 degrees of freedom based on the upward
runs in the columns of @var{x}.

@code{run_test} can be used to decide whether @var{x} contains independent
data.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn
sign_test
@c sign_test scripts/statistics/tests/sign_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{b}, @var{n}] =} sign_test (@var{x}, @var{y}, @var{alt})
For two matched-pair samples @var{x} and @var{y}, perform a sign test
of the null hypothesis
PROB (@var{x} > @var{y}) == PROB (@var{x} < @var{y}) == 1/2.

Under the null, the test statistic @var{b} roughly follows a
binomial distribution with parameters
@code{@var{n} = sum (@var{x} != @var{y})} and @var{p} = 1/2.

With the optional argument @code{alt}, the alternative of interest can be
selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
hypothesis is tested against the two-sided alternative
PROB (@var{x} < @var{y}) != 1/2.  If @var{alt} is @qcode{">"}, the one-sided
alternative PROB (@var{x} > @var{y}) > 1/2 ("x is stochastically greater
than y") is considered.  Similarly for @qcode{"<"}, the one-sided
alternative PROB (@var{x} > @var{y}) < 1/2 ("x is stochastically less than
y") is considered.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
t_test
@c t_test scripts/statistics/tests/t_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{t}, @var{df}] =} t_test (@var{x}, @var{m}, @var{alt})
For a sample @var{x} from a normal distribution with unknown mean and
variance, perform a t-test of the null hypothesis
@code{mean (@var{x}) == @var{m}}.

Under the null, the test statistic @var{t} follows a Student distribution
with @code{@var{df} = length (@var{x}) - 1} degrees of freedom.

With the optional argument string @var{alt}, the alternative of interest
can be selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
is tested against the two-sided alternative @code{mean (@var{x}) !=
@var{m}}.  If @var{alt} is @qcode{">"}, the one-sided alternative
@code{mean (@var{x}) > @var{m}} is considered.  Similarly for @var{"<"},
the one-sided alternative @code{mean (@var{x}) < @var{m}} is considered.
The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
t_test_2
@c t_test_2 scripts/statistics/tests/t_test_2.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{t}, @var{df}] =} t_test_2 (@var{x}, @var{y}, @var{alt})
For two samples x and y from normal distributions with unknown means and
unknown equal variances, perform a two-sample t-test of the null
hypothesis of equal means.

Under the null, the test statistic @var{t} follows a Student distribution
with @var{df} degrees of freedom.

With the optional argument string @var{alt}, the alternative of interest
can be selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
is tested against the two-sided alternative @code{mean (@var{x}) != mean
(@var{y})}.  If @var{alt} is @qcode{">"}, the one-sided alternative
@code{mean (@var{x}) > mean (@var{y})} is used.  Similarly for
@qcode{"<"}, the one-sided alternative @code{mean (@var{x}) < mean
(@var{y})} is used.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
t_test_regression
@c t_test_regression scripts/statistics/tests/t_test_regression.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{t}, @var{df}] =} t_test_regression (@var{y}, @var{x}, @var{rr}, @var{r}, @var{alt})
Perform a t test for the null hypothesis
@nospell{@code{@var{rr} * @var{b} = @var{r}}} in a classical normal
regression model @code{@var{y} = @var{x} * @var{b} + @var{e}}.

Under the null, the test statistic @var{t} follows a @var{t} distribution
with @var{df} degrees of freedom.

If @var{r} is omitted, a value of 0 is assumed.

With the optional argument string @var{alt}, the alternative of interest
can be selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
is tested against the two-sided alternative @nospell{@code{@var{rr} *
@var{b} != @var{r}}}.  If @var{alt} is @qcode{">"}, the one-sided
alternative @nospell{@code{@var{rr} * @var{b} > @var{r}}} is used.
Similarly for @var{"<"}, the one-sided alternative @nospell{@code{@var{rr}
* @var{b} < @var{r}}} is used.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
u_test
@c u_test scripts/statistics/tests/u_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{z}] =} u_test (@var{x}, @var{y}, @var{alt})
For two samples @var{x} and @var{y}, perform a Mann-Whitney U-test of
the null hypothesis
PROB (@var{x} > @var{y}) == 1/2 == PROB (@var{x} < @var{y}).

Under the null, the test statistic @var{z} approximately follows a
standard normal distribution.  Note that this test is equivalent to the
Wilcoxon rank-sum test.

With the optional argument string @var{alt}, the alternative of interest
can be selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
is tested against the two-sided alternative
PROB (@var{x} > @var{y}) != 1/2.  If @var{alt} is @qcode{">"}, the one-sided
alternative PROB (@var{x} > @var{y}) > 1/2 is considered.  Similarly for
@qcode{"<"}, the one-sided alternative PROB (@var{x} > @var{y}) < 1/2 is
considered.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
var_test
@c var_test scripts/statistics/tests/var_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{f}, @var{df_num}, @var{df_den}] =} var_test (@var{x}, @var{y}, @var{alt})
For two samples @var{x} and @var{y} from normal distributions with
unknown means and unknown variances, perform an F-test of the null
hypothesis of equal variances.

Under the null, the test statistic @var{f} follows an F-distribution with
@var{df_num} and @var{df_den} degrees of freedom.

With the optional argument string @var{alt}, the alternative of interest
can be selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
is tested against the two-sided alternative @code{var (@var{x}) != var
(@var{y})}.  If @var{alt} is @qcode{">"}, the one-sided alternative
@code{var (@var{x}) > var (@var{y})} is used.  Similarly for "<", the
one-sided alternative @code{var (@var{x}) > var (@var{y})} is used.  The
default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
welch_test
@c welch_test scripts/statistics/tests/welch_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{t}, @var{df}] =} welch_test (@var{x}, @var{y}, @var{alt})
For two samples @var{x} and @var{y} from normal distributions with
unknown means and unknown and not necessarily equal variances,
perform a Welch test of the null hypothesis of equal means.

Under the null, the test statistic @var{t} approximately follows a
Student distribution with @var{df} degrees of freedom.

With the optional argument string @var{alt}, the alternative of interest
can be selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
is tested against the two-sided alternative
@code{mean (@var{x}) != @var{m}}.  If @var{alt} is @qcode{">"}, the
one-sided alternative mean(x) > @var{m} is considered.  Similarly for
@qcode{"<"}, the one-sided alternative mean(x) < @var{m} is considered.
The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
wilcoxon_test
@c wilcoxon_test scripts/statistics/tests/wilcoxon_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{z}] =} wilcoxon_test (@var{x}, @var{y}, @var{alt})
For two matched-pair sample vectors @var{x} and @var{y}, perform a
Wilcoxon signed-rank test of the null hypothesis
PROB (@var{x} > @var{y}) == 1/2.

Under the null, the test statistic @var{z} approximately follows a
standard normal distribution when @var{n} > 25.

@strong{Caution:} This function assumes a normal distribution for @var{z}
and thus is invalid for @var{n} @leq{} 25.

With the optional argument string @var{alt}, the alternative of interest
can be selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
is tested against the two-sided alternative
PROB (@var{x} > @var{y}) != 1/2.  If alt is @qcode{">"}, the one-sided
alternative PROB (@var{x} > @var{y}) > 1/2 is considered.  Similarly for
@qcode{"<"}, the one-sided alternative PROB (@var{x} > @var{y}) < 1/2 is
considered.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
z_test
@c z_test scripts/statistics/tests/z_test.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{z}] =} z_test (@var{x}, @var{m}, @var{v}, @var{alt})
Perform a Z-test of the null hypothesis @code{mean (@var{x}) == @var{m}}
for a sample @var{x} from a normal distribution with unknown mean and known
variance @var{v}.

Under the null, the test statistic @var{z} follows a standard normal
distribution.

With the optional argument string @var{alt}, the alternative of interest
can be selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
is tested against the two-sided alternative
@code{mean (@var{x}) != @var{m}}.  If @var{alt} is @qcode{">"}, the
one-sided alternative @code{mean (@var{x}) > @var{m}} is considered.
Similarly for @qcode{"<"}, the one-sided alternative
@code{mean (@var{x}) < @var{m}} is considered.  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed along
with some information.
@end deftypefn
z_test_2
@c z_test_2 scripts/statistics/tests/z_test_2.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{z}] =} z_test_2 (@var{x}, @var{y}, @var{v_x}, @var{v_y}, @var{alt})
For two samples @var{x} and @var{y} from normal distributions with unknown
means and known variances @var{v_x} and @var{v_y}, perform a Z-test of the
hypothesis of equal means.

Under the null, the test statistic @var{z} follows a standard normal
distribution.

With the optional argument string @var{alt}, the alternative of interest
can be selected.  If @var{alt} is @qcode{"!="} or @qcode{"<>"}, the null
is tested against the two-sided alternative
@code{mean (@var{x}) != mean (@var{y})}.  If alt is @qcode{">"}, the
one-sided alternative @code{mean (@var{x}) > mean (@var{y})} is used.
Similarly for @qcode{"<"}, the one-sided alternative
@code{mean (@var{x}) < mean (@var{y})} is used.  The default is the
two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed along
with some information.
@end deftypefn
base2dec
@c base2dec scripts/strings/base2dec.m
-*- texinfo -*-
@deftypefn {Function File} {} base2dec (@var{s}, @var{base})
Convert @var{s} from a string of digits in base @var{base} to a decimal
integer (base 10).

@example
@group
base2dec ("11120", 3)
   @result{} 123
@end group
@end example

If @var{s} is a string matrix, return a column vector with one value per
row of @var{s}.  If a row contains invalid symbols then the corresponding
value will be NaN@.

If @var{s} is a cell array of strings, return a column vector with one
value per cell element in @var{s}.

If @var{base} is a string, the characters of @var{base} are used as the
symbols for the digits of @var{s}.  Space (' ') may not be used as a symbol.

@example
@group
base2dec ("yyyzx", "xyz")
   @result{} 123
@end group
@end example
@seealso{dec2base, bin2dec, hex2dec}
@end deftypefn
bin2dec
@c bin2dec scripts/strings/bin2dec.m
-*- texinfo -*-
@deftypefn {Function File} {} bin2dec (@var{s})
Return the decimal number corresponding to the binary number represented
by the string @var{s}.

For example:

@example
@group
bin2dec ("1110")
     @result{} 14
@end group
@end example

Spaces are ignored during conversion and may be used to make the binary
number more readable.

@example
@group
bin2dec ("1000 0001")
     @result{} 129
@end group
@end example

If @var{s} is a string matrix, return a column vector with one converted
number per row of @var{s}; Invalid rows evaluate to NaN@.

If @var{s} is a cell array of strings, return a column vector with one
converted number per cell element in @var{s}.
@seealso{dec2bin, base2dec, hex2dec}
@end deftypefn
blanks
@c blanks scripts/strings/blanks.m
-*- texinfo -*-
@deftypefn {Function File} {} blanks (@var{n})
Return a string of @var{n} blanks.

For example:

@example
@group
blanks (10);
whos ans
     @result{}
      Attr Name        Size                     Bytes  Class
      ==== ====        ====                     =====  =====
           ans         1x10                        10  char
@end group
@end example
@seealso{repmat}
@end deftypefn
cstrcat
@c cstrcat scripts/strings/cstrcat.m
-*- texinfo -*-
@deftypefn {Function File} {} cstrcat (@var{s1}, @var{s2}, @dots{})
Return a string containing all the arguments concatenated horizontally
with trailing white space preserved.

For example:

@example
@group
cstrcat ("ab   ", "cd")
      @result{} "ab   cd"
@end group
@end example

@example
@group
s = [ "ab"; "cde" ];
cstrcat (s, s, s)
      @result{} "ab ab ab "
         "cdecdecde"
@end group
@end example
@seealso{strcat, char, strvcat}
@end deftypefn
deblank
@c deblank scripts/strings/deblank.m
-*- texinfo -*-
@deftypefn {Function File} {} deblank (@var{s})
Remove trailing whitespace and nulls from @var{s}.

If @var{s} is a matrix, @var{deblank} trims each row to the length of
longest string.  If @var{s} is a cell array of strings, operate
recursively on each string element.

Examples:

@example
@group
deblank ("    abc  ")
     @result{}  "    abc"

deblank ([" abc   "; "   def   "])
     @result{}  [" abc  " ; "   def"]
@end group
@end example
@seealso{strtrim}
@end deftypefn
dec2base
@c dec2base scripts/strings/dec2base.m
-*- texinfo -*-
@deftypefn  {Function File} {} dec2base (@var{d}, @var{base})
@deftypefnx {Function File} {} dec2base (@var{d}, @var{base}, @var{len})
Return a string of symbols in base @var{base} corresponding to the
non-negative integer @var{d}.

@example
@group
dec2base (123, 3)
   @result{} "11120"
@end group
@end example

If @var{d} is a matrix or cell array, return a string matrix with one row
per element in @var{d}, padded with leading zeros to the width of the
largest value.

If @var{base} is a string then the characters of @var{base} are used as
the symbols for the digits of @var{d}.  Space (' ') may not be used as a
symbol.

@example
@group
dec2base (123, "aei")
   @result{} "eeeia"
@end group
@end example

The optional third argument, @var{len}, specifies the minimum number of
digits in the result.
@seealso{base2dec, dec2bin, dec2hex}
@end deftypefn
dec2bin
@c dec2bin scripts/strings/dec2bin.m
-*- texinfo -*-
@deftypefn {Function File} {} dec2bin (@var{d}, @var{len})
Return a binary number corresponding to the non-negative integer @var{d},
as a string of ones and zeros.

For example:

@example
@group
dec2bin (14)
     @result{} "1110"
@end group
@end example

If @var{d} is a matrix or cell array, return a string matrix with one row
per element in @var{d}, padded with leading zeros to the width of the
largest value.

The optional second argument, @var{len}, specifies the minimum number of
digits in the result.
@seealso{bin2dec, dec2base, dec2hex}
@end deftypefn
dec2hex
@c dec2hex scripts/strings/dec2hex.m
-*- texinfo -*-
@deftypefn {Function File} {} dec2hex (@var{d}, @var{len})
Return the hexadecimal string corresponding to the non-negative integer
@var{d}.

For example:

@example
@group
dec2hex (2748)
     @result{} "ABC"
@end group
@end example

If @var{d} is a matrix or cell array, return a string matrix with one row
per element in @var{d}, padded with leading zeros to the width of the
largest value.

The optional second argument, @var{len}, specifies the minimum number of
digits in the result.
@seealso{hex2dec, dec2base, dec2bin}
@end deftypefn
findstr
@c findstr scripts/strings/findstr.m
-*- texinfo -*-
@deftypefn  {Function File} {} findstr (@var{s}, @var{t})
@deftypefnx {Function File} {} findstr (@var{s}, @var{t}, @var{overlap})
Return the vector of all positions in the longer of the two strings @var{s}
and @var{t} where an occurrence of the shorter of the two starts.

If the optional argument @var{overlap} is true (default), the returned
vector can include overlapping positions.  For example:

@example
@group
findstr ("ababab", "a")
     @result{} [1, 3, 5];
findstr ("abababa", "aba", 0)
     @result{} [1, 5]
@end group
@end example

@strong{Caution:} @code{findstr} is scheduled for deprecation.  Use
@code{strfind} in all new code.
@seealso{strfind, strmatch, strcmp, strncmp, strcmpi, strncmpi, find}
@end deftypefn
hex2dec
@c hex2dec scripts/strings/hex2dec.m
-*- texinfo -*-
@deftypefn {Function File} {} hex2dec (@var{s})
Return the integer corresponding to the hexadecimal number represented by
the string @var{s}.

For example:

@example
@group
hex2dec ("12B")
      @result{} 299
hex2dec ("12b")
      @result{} 299
@end group
@end example

If @var{s} is a string matrix, return a column vector with one converted
number per row of @var{s}; Invalid rows evaluate to NaN@.

If @var{s} is a cell array of strings, return a column vector with one
converted number per cell element in @var{s}.

@seealso{dec2hex, base2dec, bin2dec}
@end deftypefn
index
@c index scripts/strings/index.m
-*- texinfo -*-
@deftypefn  {Function File} {} index (@var{s}, @var{t})
@deftypefnx {Function File} {} index (@var{s}, @var{t}, @var{direction})
Return the position of the first occurrence of the string @var{t} in the
string @var{s}, or 0 if no occurrence is found.

@var{s} may also be a string array or cell array of strings.

For example:

@example
@group
index ("Teststring", "t")
    @result{} 4
@end group
@end example

If @var{direction} is @qcode{"first"}, return the first element found.
If @var{direction} is @qcode{"last"}, return the last element found.

@seealso{find, rindex}
@end deftypefn
isletter
@c isletter scripts/strings/isletter.m
-*- texinfo -*-
@deftypefn {Function File} {} isletter (@var{s})
Return a logical array which is true where the elements of @var{s}
are letters and false where they are not.

This is an alias for the @code{isalpha} function.
@seealso{isalpha, isdigit, ispunct, isspace, iscntrl, isalnum}
@end deftypefn
isstrprop
@c isstrprop scripts/strings/isstrprop.m
-*- texinfo -*-
@deftypefn {Function File} {} isstrprop (@var{str}, @var{prop})
Test character string properties.

For example:

@example
@group
isstrprop ("abc123", "alpha")
@result{} [1, 1, 1, 0, 0, 0]
@end group
@end example

If @var{str} is a cell array, @code{isstrpop} is applied recursively to
each element of the cell array.

Numeric arrays are converted to character strings.

The second argument @var{prop} must be one of

@table @asis
@item @qcode{"alpha"}
True for characters that are alphabetic (letters).

@item  @qcode{"alnum"}
@itemx @qcode{"alphanum"}
True for characters that are alphabetic or digits.

@item @qcode{"lower"}
True for lowercase letters.

@item @qcode{"upper"}
True for uppercase letters.

@item @qcode{"digit"}
True for decimal digits (0-9).

@item @qcode{"xdigit"}
True for hexadecimal digits (@nospell{a-fA-F0-9}).

@item  @qcode{"space"}
@itemx @qcode{"wspace"}
True for whitespace characters (space, formfeed, newline, carriage return,
tab, vertical tab).

@item @qcode{"punct"}
True for punctuation characters (printing characters except space or
letter or digit).

@item @qcode{"cntrl"}
True for control characters.

@item  @qcode{"graph"}
@itemx @qcode{"graphic"}
True for printing characters except space.

@item @qcode{"print"}
True for printing characters including space.

@item @qcode{"ascii"}
True for characters that are in the range of ASCII encoding.

@end table

@seealso{isalpha, isalnum, islower, isupper, isdigit, isxdigit,
isspace, ispunct, iscntrl, isgraph, isprint, isascii}
@end deftypefn
mat2str
@c mat2str scripts/strings/mat2str.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{s} =} mat2str (@var{x}, @var{n})
@deftypefnx {Function File} {@var{s} =} mat2str (@var{x}, @var{n}, "class")
Format real, complex, and logical matrices as strings.

The returned string may be used to reconstruct the original matrix by using
the @code{eval} function.

The precision of the values is given by @var{n}.  If @var{n} is a scalar
then both real and imaginary parts of the matrix are printed to the same
precision.  Otherwise @code{@var{n}(1)} defines the precision of the real
part and @code{@var{n}(2)} defines the precision of the imaginary part.
The default for @var{n} is 15.

If the argument @qcode{"class"} is given then the class of @var{x} is
included in the string in such a way that @code{eval} will result in the
construction of a matrix of the same class.

@example
@group
mat2str ([ -1/3 + i/7; 1/3 - i/7 ], [4 2])
     @result{} "[-0.3333+0.14i;0.3333-0.14i]"

mat2str ([ -1/3 +i/7; 1/3 -i/7 ], [4 2])
     @result{} "[-0.3333+0i 0+0.14i;0.3333+0i -0-0.14i]"

mat2str (int16 ([1 -1]), "class")
     @result{} "int16([1 -1])"

mat2str (logical (eye (2)))
     @result{} "[true false;false true]"

isequal (x, eval (mat2str (x)))
     @result{} 1
@end group
@end example

@seealso{sprintf, num2str, int2str}
@end deftypefn
ostrsplit
@c ostrsplit scripts/strings/ostrsplit.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{cstr}] =} ostrsplit (@var{s}, @var{sep})
@deftypefnx {Function File} {[@var{cstr}] =} ostrsplit (@var{s}, @var{sep}, @var{strip_empty})
Split the string @var{s} using one or more separators @var{sep} and return
a cell array of strings.

Consecutive separators and separators at boundaries result in empty
strings, unless @var{strip_empty} is true.  The default value of
@var{strip_empty} is false.

2-D character arrays are split at separators and at the original column
boundaries.

Example:

@example
@group
ostrsplit ("a,b,c", ",")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

ostrsplit (["a,b" ; "cde"], ",")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = cde
          @}
@end group
@end example
@seealso{strsplit, strtok}
@end deftypefn
regexptranslate
@c regexptranslate scripts/strings/regexptranslate.m
-*- texinfo -*-
@deftypefn {Function File} {} regexptranslate (@var{op}, @var{s})
Translate a string for use in a regular expression.

This may include either wildcard replacement or special character escaping.

The behavior is controlled by @var{op} which can take the following
values

@table @asis
@item @qcode{"wildcard"}
The wildcard characters @code{.}, @code{*}, and @code{?} are replaced with
wildcards that are appropriate for a regular expression.  For example:

@example
@group
regexptranslate ("wildcard", "*.m")
     @result{} ".*\.m"
@end group
@end example

@item @qcode{"escape"}
The characters @code{$.?[]}, that have special meaning for regular
expressions are escaped so that they are treated literally.  For example:

@example
@group
regexptranslate ("escape", "12.5")
     @result{} "12\.5"
@end group
@end example

@end table
@seealso{regexp, regexpi, regexprep}
@end deftypefn
rindex
@c rindex scripts/strings/rindex.m
-*- texinfo -*-
@deftypefn {Function File} {} rindex (@var{s}, @var{t})
Return the position of the last occurrence of the character string
@var{t} in the character string @var{s}, or 0 if no occurrence is
found.

@var{s} may also be a string array or cell array of strings.

For example:

@example
@group
rindex ("Teststring", "t")
     @result{} 6
@end group
@end example

The @code{rindex} function is equivalent to @code{index} with
@var{direction} set to @qcode{"last"}.

@seealso{find, index}
@end deftypefn
str2num
@c str2num scripts/strings/str2num.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{x} =} str2num (@var{s})
@deftypefnx {Function File} {[@var{x}, @var{state}] =} str2num (@var{s})
Convert the string (or character array) @var{s} to a number (or an array).

Examples:

@example
@group
str2num ("3.141596")
      @result{} 3.141596

str2num (["1, 2, 3"; "4, 5, 6"])
      @result{} 1  2  3
         4  5  6
@end group
@end example

The optional second output, @var{state}, is logically true when the
conversion is successful.  If the conversion fails the numeric output,
@var{x}, is empty and @var{state} is false.

@strong{Caution:} As @code{str2num} uses the @code{eval} function to do the
conversion, @code{str2num} will execute any code contained in the string
@var{s}.  Use @code{str2double} for a safer and faster conversion.

For cell array of strings use @code{str2double}.
@seealso{str2double, eval}
@end deftypefn
strcat
@c strcat scripts/strings/strcat.m
-*- texinfo -*-
@deftypefn {Function File} {} strcat (@var{s1}, @var{s2}, @dots{})
Return a string containing all the arguments concatenated
horizontally.

If the arguments are cell strings, @code{strcat} returns a cell string
with the individual cells concatenated.  For numerical input, each element
is converted to the corresponding ASCII character.  Trailing white space
for any character string input is eliminated before the strings are
concatenated.  Note that cell string values do @strong{not} have
whitespace trimmed.

For example:

@example
@group
strcat ("|", " leading space is preserved", "|")
    @result{} | leading space is preserved|
@end group
@end example

@example
@group
strcat ("|", "trailing space is eliminated ", "|")
    @result{} |trailing space is eliminated|
@end group
@end example

@example
@group
strcat ("homogeneous space |", "  ", "| is also eliminated")
    @result{} homogeneous space || is also eliminated
@end group
@end example

@example
@group
s = [ "ab"; "cde" ];
strcat (s, s, s)
    @result{}
        "ababab   "
        "cdecdecde"
@end group
@end example

@example
@group
s = @{ "ab"; "cd " @};
strcat (s, s, s)
    @result{}
        @{
          [1,1] = ababab
          [2,1] = cd cd cd
        @}
@end group
@end example

@seealso{cstrcat, char, strvcat}
@end deftypefn
strchr
@c strchr scripts/strings/strchr.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{idx} =} strchr (@var{str}, @var{chars})
@deftypefnx {Function File} {@var{idx} =} strchr (@var{str}, @var{chars}, @var{n})
@deftypefnx {Function File} {@var{idx} =} strchr (@var{str}, @var{chars}, @var{n}, @var{direction})
@deftypefnx {Function File} {[@var{i}, @var{j}] =} strchr (@dots{})
Search for the string @var{str} for occurrences of characters from
the set @var{chars}.

The return value(s), as well as the @var{n} and @var{direction} arguments
behave identically as in @code{find}.

This will be faster than using regexp in most cases.

@seealso{find}
@end deftypefn
strjoin
@c strjoin scripts/strings/strjoin.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{str} =} strjoin (@var{cstr})
@deftypefnx {Function File} {@var{str} =} strjoin (@var{cstr}, @var{delimiter})
Join the elements of the cell string array, @var{cstr}, into a single
string.

If no @var{delimiter} is specified, the elements of @var{cstr} are
separated by a space.

If @var{delimiter} is specified as a string, the cell string array is
joined using the string.  Escape sequences are supported.

If @var{delimiter} is a cell string array whose length is one less than
@var{cstr}, then the elements of @var{cstr} are joined by interleaving the
cell string elements of @var{delimiter}.  Escape sequences are not
supported.

@example
@group
strjoin (@{'Octave','Scilab','Lush','Yorick'@}, '*')
      @result{} 'Octave*Scilab*Lush*Yorick'
@end group
@end example
@seealso{strsplit}
@end deftypefn
strjust
@c strjust scripts/strings/strjust.m
-*- texinfo -*-
@deftypefn  {Function File} {} strjust (@var{s})
@deftypefnx {Function File} {} strjust (@var{s}, @var{pos})
Return the text, @var{s}, justified according to @var{pos}, which may
be @qcode{"left"}, @qcode{"center"}, or @qcode{"right"}.

If @var{pos} is omitted it defaults to @qcode{"right"}.

Null characters are replaced by spaces.  All other character data are
treated as non-white space.

Example:

@example
@group
strjust (["a"; "ab"; "abc"; "abcd"])
     @result{}
        "   a"
        "  ab"
        " abc"
        "abcd"
@end group
@end example
@seealso{deblank, strrep, strtrim, untabify}
@end deftypefn
strmatch
@c strmatch scripts/strings/strmatch.m
-*- texinfo -*-
@deftypefn  {Function File} {} strmatch (@var{s}, @var{A})
@deftypefnx {Function File} {} strmatch (@var{s}, @var{A}, "exact")
Return indices of entries of @var{A} which begin with the string @var{s}.

The second argument @var{A} must be a string, character matrix, or a cell
array of strings.

If the third argument @qcode{"exact"} is not given, then @var{s} only
needs to match @var{A} up to the length of @var{s}.  Trailing spaces and
nulls in @var{s} and @var{A} are ignored when matching.

For example:

@example
@group
strmatch ("apple", "apple juice")
     @result{} 1

strmatch ("apple", ["apple  "; "apple juice"; "an apple"])
     @result{} [1; 2]

strmatch ("apple", ["apple  "; "apple juice"; "an apple"], "exact")
     @result{} [1]
@end group
@end example

@strong{Caution:} @code{strmatch} is scheduled for deprecation.  Use
@code{strncmp} (normal case), or @code{strcmp} (@qcode{"exact"} case), or
@code{regexp} in all new code.
@seealso{strfind, findstr, strcmp, strncmp, strcmpi, strncmpi, find}
@end deftypefn
strsplit
@c strsplit scripts/strings/strsplit.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{cstr}] =} strsplit (@var{str})
@deftypefnx {Function File} {[@var{cstr}] =} strsplit (@var{str}, @var{del})
@deftypefnx {Function File} {[@var{cstr}] =} strsplit (@dots{}, @var{name}, @var{value})
@deftypefnx {Function File} {[@var{cstr}, @var{matches}] =} strsplit (@dots{})
Split the string @var{str} using the delimiters specified by @var{del} and
return a cell string array of substrings.

If a delimiter is not specified the string is split at whitespace
@code{@{" ", "\f", "\n", "\r", "\t", "\v"@}}.  Otherwise, the delimiter,
@var{del} must be a string or cell array of strings.  By default,
consecutive delimiters in the input string @var{s} are collapsed into one
resulting in a single split.

Supported @var{name}/@var{value} pair arguments are:

@itemize
@item @var{collapsedelimiters} which may take the value of @code{true}
(default) or @code{false}.

@item @var{delimitertype} which may take the value of @qcode{"simple"}
(default) or @nospell{@qcode{"regularexpression"}}.  A simple delimiter
matches the text exactly as written.  Otherwise, the syntax for regular
expressions outlined in @code{regexp} is used.
@end itemize

The optional second output, @var{matches}, returns the delimiters which were
matched in the original string.

Examples with simple delimiters:

@example
strsplit ("a b c")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

strsplit ("a,b,c", ",")
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

strsplit ("a foo b,bar c", @{" ", ",", "foo", "bar"@})
      @result{}
          @{
            [1,1] = a
            [1,2] = b
            [1,3] = c
          @}

strsplit ("a,,b, c", @{",", " "@}, "collapsedelimiters", false)
      @result{}
          @{
            [1,1] = a
            [1,2] =
            [1,3] = b
            [1,4] =
            [1,5] = c
          @}

@end example

Examples with @nospell{regularexpression} delimiters:

@smallexample
strsplit ("a foo b,bar c", ',|\s|foo|bar', "delimitertype", "regularexpression")
@result{}
@{
            [1,1] = a
            [1,2] = b
            [1,3] = c
@}

strsplit ("a,,b, c", '[, ]', "collapsedelimiters", false, "delimitertype", "regularexpression")
@result{}
@{
            [1,1] = a
            [1,2] =
            [1,3] = b
            [1,4] =
            [1,5] = c
@}

strsplit ("a,\t,b, c", @{',', '\s'@}, "delimitertype", "regularexpression")
@result{}
@{
            [1,1] = a
            [1,2] = b
            [1,3] = c
@}

strsplit ("a,\t,b, c", @{',', ' ', '\t'@}, "collapsedelimiters", false)
@result{}
@{
            [1,1] = a
            [1,2] =
            [1,3] =
            [1,4] = b
            [1,5] =
            [1,6] = c
@}
@end smallexample

@seealso{ostrsplit, strjoin, strtok, regexp}
@end deftypefn
strtok
@c strtok scripts/strings/strtok.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{tok}, @var{rem}] =} strtok (@var{str})
@deftypefnx {Function File} {[@var{tok}, @var{rem}] =} strtok (@var{str}, @var{delim})

Find all characters in the string @var{str} up to, but not including, the
first character which is in the string @var{delim}.

@var{str} may also be a cell array of strings in which case the function
executes on every individual string and returns a cell array of tokens and
remainders.

Leading delimiters are ignored.  If @var{delim} is not specified,
whitespace is assumed.

If @var{rem} is requested, it contains the remainder of the string, starting
at the first delimiter.

Examples:

@example
@group
strtok ("this is the life")
     @result{} "this"

[tok, rem] = strtok ("14*27+31", "+-*/")
     @result{}
        tok = 14
        rem = *27+31
@end group
@end example
@seealso{index, strsplit, strchr, isspace}
@end deftypefn
strtrim
@c strtrim scripts/strings/strtrim.m
-*- texinfo -*-
@deftypefn {Function File} {} strtrim (@var{s})
Remove leading and trailing whitespace from @var{s}.

If @var{s} is a matrix, @var{strtrim} trims each row to the length of
longest string.  If @var{s} is a cell array of strings, operate recursively
on each string element.

For example:

@example
@group
strtrim ("    abc  ")
     @result{}  "abc"

strtrim ([" abc   "; "   def   "])
     @result{}  ["abc  "  ; "  def"]
@end group
@end example
@seealso{deblank}
@end deftypefn
strtrunc
@c strtrunc scripts/strings/strtrunc.m
-*- texinfo -*-
@deftypefn {Function File} {} strtrunc (@var{s}, @var{n})
Truncate the character string @var{s} to length @var{n}.

If @var{s} is a character matrix, then the number of columns is adjusted.

If @var{s} is a cell array of strings, then the operation is performed
on each cell element and the new cell array is returned.
@end deftypefn
substr
@c substr scripts/strings/substr.m
-*- texinfo -*-
@deftypefn  {Function File} {} substr (@var{s}, @var{offset})
@deftypefnx {Function File} {} substr (@var{s}, @var{offset}, @var{len})
Return the substring of @var{s} which starts at character number
@var{offset} and is @var{len} characters long.

Position numbering for offsets begins with 1.  If @var{offset} is negative,
extraction starts that far from the end of the string.

If @var{len} is omitted, the substring extends to the end of @var{s}.  A
negative value for @var{len} extracts to within @var{len} characters of
the end of the string

Examples:

@example
@group
substr ("This is a test string", 6, 9)
     @result{} "is a test"
substr ("This is a test string", -11)
     @result{} "test string"
substr ("This is a test string", -11, -7)
     @result{} "test"
@end group
@end example

This function is patterned after the equivalent function in Perl.
@end deftypefn
untabify
@c untabify scripts/strings/untabify.m
-*- texinfo -*-
@deftypefn  {Function File} {} untabify (@var{t})
@deftypefnx {Function File} {} untabify (@var{t}, @var{tw})
@deftypefnx {Function File} {} untabify (@var{t}, @var{tw}, @var{deblank})
Replace TAB characters in @var{t} with spaces.

The input, @var{t}, may be either a 2-D character array, or a cell array of
character strings.  The output is the same class as the input.

The tab width is specified by @var{tw}, and defaults to eight.

If the optional argument @var{deblank} is true, then the spaces will be
removed from the end of the character data.

The following example reads a file and writes an untabified version of the
same file with trailing spaces stripped.

@example
@group
fid = fopen ("tabbed_script.m");
text = char (fread (fid, "uchar")');
fclose (fid);
fid = fopen ("untabified_script.m", "w");
text = untabify (strsplit (text, "\n"), 8, true);
fprintf (fid, "%s\n", text@{:@});
fclose (fid);
@end group
@end example

@seealso{strjust, strsplit, deblank}
@end deftypefn
validatestring
@c validatestring scripts/strings/validatestring.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{validstr} =} validatestring (@var{str}, @var{strarray})
@deftypefnx {Function File} {@var{validstr} =} validatestring (@var{str}, @var{strarray}, @var{funcname})
@deftypefnx {Function File} {@var{validstr} =} validatestring (@var{str}, @var{strarray}, @var{funcname}, @var{varname})
@deftypefnx {Function File} {@var{validstr} =} validatestring (@dots{}, @var{position})
Verify that @var{str} is an element, or substring of an element, in
@var{strarray}.

When @var{str} is a character string to be tested, and @var{strarray} is a
cellstr of valid values, then @var{validstr} will be the validated form
of @var{str} where validation is defined as @var{str} being a member
or substring of @var{validstr}.  This is useful for both verifying
and expanding short options, such as @qcode{"r"}, to their longer forms,
such as @qcode{"red"}.  If @var{str} is a substring of @var{validstr}, and
there are multiple matches, the shortest match will be returned if all
matches are substrings of each other.  Otherwise, an error will be raised
because the expansion of @var{str} is ambiguous.  All comparisons are case
insensitive.

The additional inputs @var{funcname}, @var{varname}, and @var{position}
are optional and will make any generated validation error message more
specific.

Examples:
@c Set example in small font to prevent overfull line

@smallexample
@group
validatestring ("r", @{"red", "green", "blue"@})
@result{} "red"

validatestring ("b", @{"red", "green", "blue", "black"@})
@result{} error: validatestring: multiple unique matches were found for 'b':
   blue, black
@end group
@end smallexample

@seealso{strcmp, strcmpi, validateattributes, inputParser}
@end deftypefn
__have_feature__
@c __have_feature__ scripts/testfun/__have_feature__.m
-*- texinfo -*-
@deftypefn {Function File} {} __have_feature__ (feature)
Undocumented internal function.
@end deftypefn
__printf_assert__
@c __printf_assert__ scripts/testfun/__printf_assert__.m
-*- texinfo -*-
@deftypefn {Function File} {} __printf_assert__ (@dots{})
Undocumented internal function.
@end deftypefn
__prog_output_assert__
@c __prog_output_assert__ scripts/testfun/__prog_output_assert__.m
-*- texinfo -*-
@deftypefn {Function File} {} __prog_output_assert__ (@var{str})
Undocumented internal function.
@end deftypefn
__run_test_suite__
@c __run_test_suite__ scripts/testfun/__run_test_suite__.m
-*- texinfo -*-
@deftypefn {Function File} {} __run_test_suite__ (@var{fcndirs}, @var{fixedtestdirs})
Undocumented internal function.
@end deftypefn
assert
@c assert scripts/testfun/assert.m
-*- texinfo -*-
@deftypefn  {Function File} {} assert (@var{cond})
@deftypefnx {Function File} {} assert (@var{cond}, @var{errmsg})
@deftypefnx {Function File} {} assert (@var{cond}, @var{errmsg}, @dots{})
@deftypefnx {Function File} {} assert (@var{cond}, @var{msg_id}, @var{errmsg}, @dots{})
@deftypefnx {Function File} {} assert (@var{observed}, @var{expected})
@deftypefnx {Function File} {} assert (@var{observed}, @var{expected}, @var{tol})

Produce an error if the specified condition is not met.

@code{assert} can be called in three different ways.

@table @code
@item  assert (@var{cond})
@itemx assert (@var{cond}, @var{errmsg})
@itemx assert (@var{cond}, @var{errmsg}, @dots{})
@itemx assert (@var{cond}, @var{msg_id}, @var{errmsg}, @dots{})
Called with a single argument @var{cond}, @code{assert} produces an error if
@var{cond} is false (numeric zero).

Any additional arguments are passed to the @code{error} function for
processing.

@item assert (@var{observed}, @var{expected})
Produce an error if observed is not the same as expected.

Note that @var{observed} and @var{expected} can be scalars, vectors,
matrices, strings, cell arrays, or structures.

@item assert (@var{observed}, @var{expected}, @var{tol})
Produce an error if observed is not the same as expected but equality
comparison for numeric data uses a tolerance @var{tol}.

If @var{tol} is positive then it is an absolute tolerance which will produce
an error if @code{abs (@var{observed} - @var{expected}) > abs (@var{tol})}.

If @var{tol} is negative then it is a relative tolerance which will produce
an error if @code{abs (@var{observed} - @var{expected}) >
abs (@var{tol} * @var{expected})}.

If @var{expected} is zero @var{tol} will always be interpreted as an
absolute tolerance.

If @var{tol} is not scalar its dimensions must agree with those of
@var{observed} and @var{expected} and tests are performed on an
element-by-element basis.
@end table
@seealso{fail, test, error, isequal}
@end deftypefn
demo
@c demo scripts/testfun/demo.m
-*- texinfo -*-
@deftypefn  {Command} {} demo @var{name}
@deftypefnx {Command} {} demo @var{name} @var{n}
@deftypefnx {Function File} {} demo ("@var{name}")
@deftypefnx {Function File} {} demo ("@var{name}", @var{n})

Run example code block @var{n} associated with the function @var{name}.

If @var{n} is not specified, all examples are run.

The preferred location for example code blocks is embedded within the script
m-file immediately following the code that it exercises.  Alternatively,
the examples may be stored in a file with the same name but no extension
located on Octave's load path.  To separate examples from regular script
code all lines are prefixed by @code{%!}.  Each example must also be
introduced by the keyword @qcode{"demo"} flush left to the prefix with no
intervening spaces.  The remainder of the example can contain arbitrary
Octave code.  For example:

@example
@group
%!demo
%! t = 0:0.01:2*pi;
%! x = sin (t);
%! plot (t, x);
%! title ("one cycle of a sine wave");
%! #-------------------------------------------------
%! # the figure window shows one cycle of a sine wave
@end group
@end example

Note that the code is displayed before it is executed so that a simple
comment at the end suffices for labeling what is being shown.  For plots,
labeling can also be done with @code{title} or @code{text}.  It is generally
@strong{not} necessary to use @code{disp} or @code{printf} within the demo.

Demos are run in a stand-alone function environment with no access to
external variables.  This means that every demo must have separate
initialization code.  Alternatively, all demos can be combined into a single
large demo with the code

@example
%! input ("Press <enter> to continue: ", "s");
@end example

@noindent
between the sections, but this usage is discouraged.  Other techniques to
avoid multiple initialization blocks include using multiple plots with a new
@code{figure} command between each plot, or using @code{subplot} to put
multiple plots in the same window.

Finally, because @code{demo} evaluates within a function context it is not
possible to define new functions within the code.  Anonymous functions make
a good substitute in most instances.  If function blocks @strong{must} be
used then the code @code{eval (example ("function", n))} will allow Octave
to see them.  This has its own problems, however, as @code{eval} only
evaluates one line or statement at a time.  In this case the function
declaration must be wrapped with @qcode{"if 1 <demo stuff> endif"} where
@qcode{"if"} is on the same line as @qcode{"demo"}.  For example:

@example
@group
%!demo if 1
%!  function y = f(x)
%!    y = x;
%!  endfunction
%!  f(3)
%! endif
@end group
@end example

@seealso{rundemos, example, test}
@end deftypefn
example
@c example scripts/testfun/example.m
-*- texinfo -*-
@deftypefn  {Command} {} example @var{name}
@deftypefnx {Command} {} example @var{name} @var{n}
@deftypefnx {Function File} {} example ("@var{name}")
@deftypefnx {Function File} {} example ("@var{name}", @var{n})
@deftypefnx {Function File} {[@var{s}, @var{idx}] =} example (@dots{})

Display the code for example @var{n} associated with the function
@var{name}, but do not run it.

If @var{n} is not specified, all examples are displayed.

When called with output arguments, the examples are returned in the form of
a string @var{s}, with @var{idx} indicating the ending position of the
various examples.

See @code{demo} for a complete explanation.
@seealso{demo, test}
@end deftypefn
fail
@c fail scripts/testfun/fail.m
-*- texinfo -*-
@deftypefn  {Function File} {} fail (@var{code})
@deftypefnx {Function File} {} fail (@var{code}, @var{pattern})
@deftypefnx {Function File} {} fail (@var{code}, "warning")
@deftypefnx {Function File} {} fail (@var{code}, "warning", @var{pattern})

Return true if @var{code} fails with an error message matching
@var{pattern}, otherwise produce an error.

@var{code} must be in the form of a string that is passed to the Octave
interpreter via the @code{evalin} function, i.e., a (quoted) string constant
or a string variable.

Note that if @var{code} runs successfully, rather than failing, the error
printed is:

@example
          expected error <.> but got none
@end example

If called with two arguments, the return value will be true only if
@var{code} fails with an error message containing @var{pattern}
(case sensitive).  If the code fails with a different error than the one
specified in @var{pattern} then the message produced is:

@example
@group
          expected <@var{pattern}>
          but got <text of actual error>
@end group
@end example

The angle brackets are not part of the output.

When called with the @qcode{"warning"} option @code{fail} will produce an
error if executing the code produces no warning.
@seealso{assert, error}
@end deftypefn
rundemos
@c rundemos scripts/testfun/rundemos.m
-*- texinfo -*-
@deftypefn  {Function File} {} rundemos ()
@deftypefnx {Function File} {} rundemos (@var{directory})
Execute built-in demos for all m-files in the specified @var{directory}.

Demo blocks in any C++ source files (@file{*.cc}) will also be executed
for use with dynamically linked oct-file functions.

If no directory is specified, operate on all directories in Octave's search
path for functions.
@seealso{demo, runtests, path}
@end deftypefn
runtests
@c runtests scripts/testfun/runtests.m
-*- texinfo -*-
@deftypefn  {Function File} {} runtests ()
@deftypefnx {Function File} {} runtests (@var{directory})
Execute built-in tests for all m-files in the specified @var{directory}.

Test blocks in any C++ source files (@file{*.cc}) will also be executed
for use with dynamically linked oct-file functions.

If no directory is specified, operate on all directories in Octave's search
path for functions.
@seealso{rundemos, test, path}
@end deftypefn
speed
@c speed scripts/testfun/speed.m
-*- texinfo -*-
@deftypefn  {Function File} {} speed (@var{f}, @var{init}, @var{max_n}, @var{f2}, @var{tol})
@deftypefnx {Function File} {[@var{order}, @var{n}, @var{T_f}, @var{T_f2}] =} speed (@dots{})

Determine the execution time of an expression (@var{f}) for various input
values (@var{n}).

The @var{n} are log-spaced from 1 to @var{max_n}.  For each @var{n}, an
initialization expression (@var{init}) is computed to create any data needed
for the test.  If a second expression (@var{f2}) is given then the
execution times of the two expressions are compared.  When called without
output arguments the results are printed to stdout and displayed
graphically.

@table @code
@item @var{f}
The code expression to evaluate.

@item @var{max_n}
The maximum test length to run.  The default value is 100.  Alternatively,
use @code{[min_n, max_n]} or specify the @var{n} exactly with
@code{[n1, n2, @dots{}, nk]}.

@item @var{init}
Initialization expression for function argument values.  Use @var{k} for
the test number and @var{n} for the size of the test.  This should compute
values for all variables used by @var{f}.  Note that @var{init} will be
evaluated first for @math{k = 0}, so things which are constant throughout
the test series can be computed once.  The default value is
@code{@var{x} = randn (@var{n}, 1)}.

@item @var{f2}
An alternative expression to evaluate, so that the speed of two
expressions can be directly compared.  The default is @code{[]}.

@item @var{tol}
Tolerance used to compare the results of expression @var{f} and expression
@var{f2}.  If @var{tol} is positive, the tolerance is an absolute one.
If @var{tol} is negative, the tolerance is a relative one.  The default is
@code{eps}.  If @var{tol} is @code{Inf}, then no comparison will be made.

@item @var{order}
The time complexity of the expression @math{O(a*n^p)}.  This is a
structure with fields @code{a} and @code{p}.

@item @var{n}
The values @var{n} for which the expression was calculated @strong{AND}
the execution time was greater than zero.

@item @var{T_f}
The nonzero execution times recorded for the expression @var{f} in seconds.

@item @var{T_f2}
The nonzero execution times recorded for the expression @var{f2} in seconds.
If required, the mean time ratio is simply @code{mean (T_f ./ T_f2)}.

@end table

The slope of the execution time graph shows the approximate power of the
asymptotic running time @math{O(n^p)}.  This power is plotted for the
region over which it is approximated (the latter half of the graph).  The
estimated power is not very accurate, but should be sufficient to
determine the general order of an algorithm.  It should indicate if, for
example, the implementation is unexpectedly @math{O(n^2)} rather than
@math{O(n)} because it extends a vector each time through the loop rather
than pre-allocating storage.  In the current version of Octave, the
following is not the expected @math{O(n)}.

@example
speed ("for i = 1:n, y@{i@} = x(i); endfor", "", [1000, 10000])
@end example

@noindent
But it is if you preallocate the cell array @code{y}:

@example
@group
speed ("for i = 1:n, y@{i@} = x(i); endfor", ...
       "x = rand (n, 1); y = cell (size (x));", [1000, 10000])
@end group
@end example

An attempt is made to approximate the cost of individual operations, but
it is wildly inaccurate.  You can improve the stability somewhat by doing
more work for each @code{n}.  For example:

@example
speed ("airy(x)", "x = rand (n, 10)", [10000, 100000])
@end example

When comparing two different expressions (@var{f}, @var{f2}), the slope of
the line on the speedup ratio graph should be larger than 1 if the new
expression is faster.  Better algorithms have a shallow slope.  Generally,
vectorizing an algorithm will not change the slope of the execution time
graph, but will shift it relative to the original.  For example:

@example
@group
speed ("sum (x)", "", [10000, 100000], ...
       "v = 0; for i = 1:length (x), v += x(i); endfor")
@end group
@end example

The following is a more complex example.  If there was an original version
of @code{xcorr} using for loops and a second version using an FFT, then
one could compare the run speed for various lags as follows, or for a fixed
lag with varying vector lengths as follows:

@example
@group
speed ("xcorr (x, n)", "x = rand (128, 1);", 100,
       "xcorr_orig (x, n)", -100*eps)
speed ("xcorr (x, 15)", "x = rand (20+n, 1);", 100,
       "xcorr_orig (x, n)", -100*eps)
@end group
@end example

Assuming one of the two versions is in xcorr_orig, this would compare their
speed and their output values.  Note that the FFT version is not exact, so
one must specify an acceptable tolerance on the comparison @code{100*eps}.
In this case, the comparison should be computed relatively, as
@code{abs ((@var{x} - @var{y}) ./ @var{y})} rather than absolutely as
@code{abs (@var{x} - @var{y})}.

Type @kbd{example ("speed")} to see some real examples or
@kbd{demo ("speed")} to run them.
@end deftypefn
test
@c test scripts/testfun/test.m
-*- texinfo -*-
@deftypefn  {Command} {} test @var{name}
@deftypefnx {Command} {} test @var{name} quiet|normal|verbose
@deftypefnx {Function File} {} test ("@var{name}", "quiet|normal|verbose", @var{fid})
@deftypefnx {Function File} {} test ("@var{name}", "quiet|normal|verbose", @var{fname})
@deftypefnx {Function File} {@var{success} =} test (@dots{})
@deftypefnx {Function File} {[@var{n}, @var{nmax}, @var{nxfail}, @var{nskip}] =} test (@dots{})
@deftypefnx {Function File} {[@var{code}, @var{idx}] =} test ("@var{name}", "grabdemo")
@deftypefnx {Function File} {} test ([], "explain", @var{fid})
@deftypefnx {Function File} {} test ([], "explain", @var{fname})

Perform built-in self-tests from the first file in the loadpath matching
@var{name}.

@code{test} can be called in either command or functional form.  The exact
operation of test is determined by a combination of mode (interactive or
batch), reporting level (@qcode{"quiet"}, @qcode{"normal"},
@qcode{"verbose"}), and whether a logfile or summary output variable is
used.

The default mode when @code{test} is called from the command line is
interactive.  In this mode, tests will be run until the first error is
encountered, or all tests complete successfully.  In batch mode, all tests
are run regardless of any failures, and the results are collected for
reporting.  Tests which require user interaction, i.e., demo blocks,
are never run in batch mode.

Batch mode is enabled by either 1) specifying a logfile using the third
argument @var{fname} or @var{fid}, or 2) requesting an output argument
such as @var{success}, @var{n}, etc.

The optional second argument determines the amount of output to generate and
which types of tests to run.  The default value is @qcode{"normal"}.
Requesting an output argument will suppress printing the final summary
message and any intermediate warnings, unless verbose reporting is
enabled.

@table @asis
@item @qcode{"quiet"}
Print a summary message when all tests pass, or print an error with the
results of the first bad test when a failure occurs.  Don't run tests which
require user interaction.

@item @qcode{"normal"}
Display warning messages about skipped tests or failing xtests during test
execution.
Print a summary message when all tests pass, or print an error with the
results of the first bad test when a failure occurs.  Don't run tests which
require user interaction.

@item @qcode{"verbose"}
Display tests before execution.  Print all warning messages.  In interactive
mode, run all tests including those which require user interaction.
@end table

The optional third input argument specifies a logfile where results of the
tests should be written.  The logfile may be a character string
(@var{fname}) or an open file descriptor ID (@var{fid}).  To enable batch
processing, but still print the results to the screen, use @code{stdout} for
@var{fid}.

When called with just a single output argument @var{success}, @code{test}
returns true if all of the tests were successful.  If called with more
than one output argument then the number of successful tests (@var{n}),
the total number of tests in the file (@var{nmax}), the number of xtest
failures (@var{nxfail}), and the number of skipped tests (@var{nskip} are
returned.

Example

@example
@group
test sind
@result{}
PASSES 5 out of 5 tests

[n, nmax] = test ("sind")
@result{}
n =  5
nmax =  5
@end group
@end example

Additional Calling Syntaxes

If the second argument is the string @qcode{"grabdemo"}, the contents of
any built-in demo blocks are extracted but not executed.  The text for all
code blocks is concatenated and returned as @var{code} with @var{idx} being
a vector of positions of the ends of each demo block.  For an easier way to
extract demo blocks from files, @xref{XREFexample,,example}.

If the second argument is @qcode{"explain"} then @var{name} is ignored and
an explanation of the line markers used in @code{test} output reports is
written to the file specified by @var{fname} or @var{fid}.

@seealso{assert, fail, demo, example, error}
@end deftypefn
addtodate
@c addtodate scripts/time/addtodate.m
-*- texinfo -*-
@deftypefn {Function File} {@var{d} =} addtodate (@var{d}, @var{q}, @var{f})
Add @var{q} amount of time (with units @var{f}) to the serial datenum,
@var{d}.

@var{f} must be one of @qcode{"year"}, @qcode{"month"}, @qcode{"day"},
@qcode{"hour"}, @qcode{"minute"}, @qcode{"second"}, or
@qcode{"millisecond"}.
@seealso{datenum, datevec, etime}
@end deftypefn
asctime
@c asctime scripts/time/asctime.m
-*- texinfo -*-
@deftypefn {Function File} {} asctime (@var{tm_struct})
Convert a time structure to a string using the following
format: @qcode{"ddd mmm mm HH:MM:SS yyyy@xbackslashchar{}n"}.

For example:

@example
@group
asctime (localtime (time ()))
     @result{} "Mon Feb 17 01:15:06 1997@xbackslashchar{}n"
@end group
@end example

This is equivalent to @code{ctime (time ())}.
@seealso{ctime, localtime, time}
@end deftypefn
calendar
@c calendar scripts/time/calendar.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{c} =} calendar ()
@deftypefnx {Function File} {@var{c} =} calendar (@var{d})
@deftypefnx {Function File} {@var{c} =} calendar (@var{y}, @var{m})
@deftypefnx {Function File} {} calendar (@dots{})
Return the current monthly calendar in a 6x7 matrix.

If @var{d} is specified, return the calendar for the month containing the
date @var{d}, which must be a serial date number or a date string.

If @var{y} and @var{m} are specified, return the calendar for year @var{y}
and month @var{m}.

If no output arguments are specified, print the calendar on the screen
instead of returning a matrix.
@seealso{datenum, datestr}
@end deftypefn
clock
@c clock scripts/time/clock.m
-*- texinfo -*-
@deftypefn {Function File} {} clock ()
Return the current local date and time as a date vector.

The date vector contains the following fields: current year, month (1-12),
day (1-31), hour (0-23), minute (0-59), and second (0-61).  The seconds
field has a fractional part after the decimal point for extended accuracy.

For example:

@example
@group
fix (clock ())
     @result{} [ 1993, 8, 20, 4, 56, 1 ]
@end group
@end example

@code{clock} is more accurate on systems that have the @code{gettimeofday}
function.
@seealso{now, date, datevec}
@end deftypefn
ctime
@c ctime scripts/time/ctime.m
-*- texinfo -*-
@deftypefn {Function File} {} ctime (@var{t})
Convert a value returned from @code{time} (or any other non-negative
integer), to the local time and return a string of the same form as
@code{asctime}.

The function @code{ctime (time)} is equivalent to
@code{asctime (localtime (time))}.  For example:

@example
@group
ctime (time ())
   @result{} "Mon Feb 17 01:15:06 1997@xbackslashchar{}n"
@end group
@end example
@seealso{asctime, time, localtime}
@end deftypefn
date
@c date scripts/time/date.m
-*- texinfo -*-
@deftypefn {Function File} {} date ()
Return the current date as a character string in the form DD-MMM-YYYY@.

For example:

@example
@group
date ()
  @result{} "20-Aug-1993"
@end group
@end example
@seealso{now, clock, datestr, localtime}
@end deftypefn
datenum
@c datenum scripts/time/datenum.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{days} =} datenum (@var{datevec})
@deftypefnx {Function File} {@var{days} =} datenum (@var{year}, @var{month}, @var{day})
@deftypefnx {Function File} {@var{days} =} datenum (@var{year}, @var{month}, @var{day}, @var{hour})
@deftypefnx {Function File} {@var{days} =} datenum (@var{year}, @var{month}, @var{day}, @var{hour}, @var{minute})
@deftypefnx {Function File} {@var{days} =} datenum (@var{year}, @var{month}, @var{day}, @var{hour}, @var{minute}, @var{second})
@deftypefnx {Function File} {@var{days} =} datenum ("datestr")
@deftypefnx {Function File} {@var{days} =} datenum ("datestr", @var{f})
@deftypefnx {Function File} {@var{days} =} datenum ("datestr", @var{p})
@deftypefnx {Function File} {[@var{days}, @var{secs}] =} datenum (@dots{})
Return the date/time input as a serial day number, with Jan 1, 0000
defined as day 1.

The integer part, @code{floor (@var{days})} counts the number of
complete days in the date input.

The fractional part, @code{rem (@var{days}, 1)} corresponds to the time
on the given day.

The input may be a date vector (see @code{datevec}),
datestr (see @code{datestr}), or directly specified as input.

When processing input datestrings, @var{f} is the format string used to
interpret date strings (see @code{datestr}).  If no format @var{f} is
specified, then a relatively slow search is performed through various
formats.  It is always preferable to specify the format string @var{f} if
it is known.  Formats which do not specify a particular time component
will have the value set to zero.  Formats which do not specify a date
will default to January 1st of the current year.

@var{p} is the year at the start of the century to which two-digit years
will be referenced.  If not specified, it defaults to the current year
minus 50.

The optional output @var{secs} holds the time on the specified day with
greater precision than @var{days}.

Notes:

@itemize
@item
Years can be negative and/or fractional.

@item
Months below 1 are considered to be January.

@item
Days of the month start at 1.

@item
Days beyond the end of the month go into subsequent months.

@item
Days before the beginning of the month go to the previous month.

@item
Days can be fractional.
@end itemize

@strong{Caution:} this function does not attempt to handle Julian calendars
so dates before October 15, 1582 are wrong by as much as eleven days.  Also,
be aware that only Roman Catholic countries adopted the calendar in 1582.
It took until 1924 for it to be adopted everywhere.  See the Wikipedia entry
on the Gregorian calendar for more details.

@strong{Warning:} leap seconds are ignored.  A table of leap seconds is
available on the Wikipedia entry for leap seconds.
@seealso{datestr, datevec, now, clock, date}
@end deftypefn
datestr
@c datestr scripts/time/datestr.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{str} =} datestr (@var{date})
@deftypefnx {Function File} {@var{str} =} datestr (@var{date}, @var{f})
@deftypefnx {Function File} {@var{str} =} datestr (@var{date}, @var{f}, @var{p})
Format the given date/time according to the format @code{f} and return
the result in @var{str}.

@var{date} is a serial date number (see @code{datenum}) or a date vector
(see @code{datevec}).  The value of @var{date} may also be a string or cell
array of strings.

@var{f} can be an integer which corresponds to one of the codes in the table
below, or a date format string.

@var{p} is the year at the start of the century in which two-digit years are
to be interpreted in.  If not specified, it defaults to the current year
minus 50.

For example, the date 730736.65149 (2000-09-07 15:38:09.0934) would be
formatted as follows:

@multitable @columnfractions 0.1 0.45 0.35
@headitem Code @tab Format @tab Example
@item 0 @tab dd-mmm-yyyy HH:MM:SS    @tab 07-Sep-2000 15:38:09
@item 1 @tab dd-mmm-yyyy             @tab 07-Sep-2000
@item 2 @tab mm/dd/yy                @tab 09/07/00
@item 3 @tab mmm                     @tab Sep
@item 4 @tab m                       @tab S
@item 5 @tab mm                      @tab 09
@item 6 @tab mm/dd                   @tab 09/07
@item 7 @tab dd                      @tab 07
@item 8 @tab ddd                     @tab Thu
@item 9 @tab d                       @tab T
@item 10 @tab yyyy                   @tab 2000
@item 11 @tab yy                     @tab 00
@item 12 @tab mmmyy                  @tab Sep00
@item 13 @tab HH:MM:SS               @tab 15:38:09
@item 14 @tab HH:MM:SS PM            @tab 03:38:09 PM
@item 15 @tab HH:MM                  @tab 15:38
@item 16 @tab HH:MM PM               @tab 03:38 PM
@item 17 @tab QQ-YY                  @tab Q3-00
@item 18 @tab QQ                     @tab Q3
@item 19 @tab dd/mm                  @tab 07/09
@item 20 @tab dd/mm/yy               @tab 07/09/00
@item 21 @tab mmm.dd,yyyy HH:MM:SS   @tab Sep.07,2000 15:38:08
@item 22 @tab mmm.dd,yyyy            @tab Sep.07,2000
@item 23 @tab mm/dd/yyyy             @tab 09/07/2000
@item 24 @tab dd/mm/yyyy             @tab 07/09/2000
@item 25 @tab yy/mm/dd               @tab 00/09/07
@item 26 @tab yyyy/mm/dd             @tab 2000/09/07
@item 27 @tab QQ-YYYY                @tab Q3-2000
@item 28 @tab mmmyyyy                @tab Sep2000
@item 29 @tab yyyy-mm-dd             @tab 2000-09-07
@item 30 @tab yyyymmddTHHMMSS        @tab 20000907T153808
@item 31 @tab yyyy-mm-dd HH:MM:SS    @tab 2000-09-07 15:38:08
@end multitable

If @var{f} is a format string, the following symbols are recognized:

@multitable @columnfractions 0.1 0.7 0.2
@headitem Symbol @tab Meaning @tab Example
@item yyyy @tab Full year                                    @tab 2005
@item yy   @tab Two-digit year                               @tab 05
@item mmmm @tab Full month name                              @tab December
@item mmm  @tab Abbreviated month name                       @tab Dec
@item mm   @tab Numeric month number (padded with zeros)     @tab 01, 08, 12
@item m    @tab First letter of month name (capitalized)     @tab D
@item dddd @tab Full weekday name                            @tab Sunday
@item ddd  @tab Abbreviated weekday name                     @tab Sun
@item dd   @tab Numeric day of month (padded with zeros)     @tab 11
@item d    @tab First letter of weekday name (capitalized)   @tab S
@item HH   @tab Hour of day, padded with zeros if PM is set  @tab 09:00
@item      @tab and not padded with zeros otherwise          @tab 9:00 AM
@item MM   @tab Minute of hour (padded with zeros)           @tab 10:05
@item SS   @tab Second of minute (padded with zeros)         @tab 10:05:03
@item FFF  @tab Milliseconds of second (padded with zeros)   @tab 10:05:03.012
@item AM   @tab Use 12-hour time format                      @tab 11:30 AM
@item PM   @tab Use 12-hour time format                      @tab 11:30 PM
@end multitable

If @var{f} is not specified or is @code{-1}, then use 0, 1 or 16, depending
on whether the date portion or the time portion of @var{date} is empty.

If @var{p} is nor specified, it defaults to the current year minus 50.

If a matrix or cell array of dates is given, a column vector of date strings
is returned.

@seealso{datenum, datevec, date, now, clock}
@end deftypefn
datevec
@c datevec scripts/time/datevec.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{v} =} datevec (@var{date})
@deftypefnx {Function File} {@var{v} =} datevec (@var{date}, @var{f})
@deftypefnx {Function File} {@var{v} =} datevec (@var{date}, @var{p})
@deftypefnx {Function File} {@var{v} =} datevec (@var{date}, @var{f}, @var{p})
@deftypefnx {Function File} {[@var{y}, @var{m}, @var{d}, @var{h}, @var{mi}, @var{s}] =} datevec (@dots{})
Convert a serial date number (see @code{datenum}) or date string (see
@code{datestr}) into a date vector.

A date vector is a row vector with six members, representing the year,
month, day, hour, minute, and seconds respectively.

@var{f} is the format string used to interpret date strings
(see @code{datestr}).  If @var{date} is a string, but no format is
specified, then a relatively slow search is performed through various
formats.  It is always preferable to specify the format string @var{f} if it
is known.  Formats which do not specify a particular time component will
have the value set to zero.  Formats which do not specify a date will
default to January 1st of the current year.

@var{p} is the year at the start of the century to which two-digit years
will be referenced.  If not specified, it defaults to the current year minus
50.
@seealso{datenum, datestr, clock, now, date}
@end deftypefn
eomday
@c eomday scripts/time/eomday.m
-*- texinfo -*-
@deftypefn {Function File} {@var{e} =} eomday (@var{y}, @var{m})
Return the last day of the month @var{m} for the year @var{y}.
@seealso{weekday, datenum, datevec, is_leap_year, calendar}
@end deftypefn
etime
@c etime scripts/time/etime.m
-*- texinfo -*-
@deftypefn {Function File} {} etime (@var{t2}, @var{t1})
Return the difference in seconds between two time values returned from
@code{clock} (@math{@var{t2} - @var{t1}}).

For example:

@example
@group
t0 = clock ();
# many computations later@dots{}
elapsed_time = etime (clock (), t0);
@end group
@end example

@noindent
will set the variable @code{elapsed_time} to the number of seconds since the
variable @code{t0} was set.
@seealso{tic, toc, clock, cputime, addtodate}
@end deftypefn
is_leap_year
@c is_leap_year scripts/time/is_leap_year.m
-*- texinfo -*-
@deftypefn  {Function File} {} is_leap_year ()
@deftypefnx {Function File} {} is_leap_year (@var{year})
Return true if @var{year} is a leap year and false otherwise.

If no year is specified, @code{is_leap_year} uses the current year.

For example:

@example
@group
is_leap_year (2000)
   @result{} 1
@end group
@end example
@seealso{weekday, eomday, calendar}
@end deftypefn
now
@c now scripts/time/now.m
-*- texinfo -*-
@deftypefn {Function File} {t =} now ()
Return the current local date/time as a serial day number
(see @code{datenum}).

The integral part, @code{floor (now)} corresponds to the number of days
between today and Jan 1, 0000.

The fractional part, @code{rem (now, 1)} corresponds to the current time.
@seealso{clock, date, datenum}
@end deftypefn
weekday
@c weekday scripts/time/weekday.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{n}, @var{s}] =} weekday (@var{d})
@deftypefnx {Function File} {[@var{n}, @var{s}] =} weekday (@var{d}, @var{format})
Return the day of the week as a number in @var{n} and as a string in @var{s}.

The days of the week are numbered 1--7 with the first day being Sunday.

@var{d} is a serial date number or a date string.

If the string @var{format} is not present or is equal to @qcode{"short"}
then @var{s} will contain the abbreviated name of the weekday.  If
@var{format} is @qcode{"long"} then @var{s} will contain the full name.

Table of return values based on @var{format}:

@multitable @columnfractions .06 .13 .16
@headitem @var{n} @tab @qcode{"short"} @tab @qcode{"long"}
@item 1 @tab Sun @tab Sunday
@item 2 @tab Mon @tab Monday
@item 3 @tab Tue @tab Tuesday
@item 4 @tab Wed @tab Wednesday
@item 5 @tab Thu @tab Thursday
@item 6 @tab Fri @tab Friday
@item 7 @tab Sat @tab Saturday
@end multitable

@seealso{eomday, is_leap_year, calendar, datenum, datevec}
@end deftypefn
gnuplot_binary
@c gnuplot_binary scripts/plot/util/gnuplot_binary.m
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{prog}, @var{args}] =} gnuplot_binary ()
@deftypefnx {Loadable Function} {[@var{old_prog}, @var{old_args}] =} gnuplot_binary (@var{new_prog}, @var{arg1}, @dots{})
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 @qcode{"gnuplot"} with no additional arguments.
@xref{Installation}.
@seealso{graphics_toolkit}
@end deftypefn
