### DO NOT EDIT!
###
### This file is generated automatically from the Octave sources.
### Edit those files instead and run make to update this file.

@ftp/ascii
@c @ftp/ascii scripts/@ftp/ascii.m
-*- texinfo -*-
@deftypefn {Function File} {} ascii (@var{f})
Put the FTP connection @var{f} into ascii mode.
@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})
Put the FTP connection @var{f} into binary mode.
@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}, @var{path})
Set the remote directory to @var{path} on the FTP connection @var{f}.
@var{f} is an FTP object returned by the @code{ftp} function.
@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 given 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 "anonymous"
with no password is used.  The returned FTP object @var{f} represents the
established FTP connection.
@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 (@dots{}, @var{target})
Downloads 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 with the name @var{target} to the local
directory.
@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 by the @dfn{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, loadaudio, saveaudio}
@end deftypefn
loadaudio
@c loadaudio scripts/audio/loadaudio.m
-*- texinfo -*-
@deftypefn {Function File} {} loadaudio (@var{name}, @var{ext}, @var{bps})
Loads 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
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, loadaudio, saveaudio}
@end deftypefn
playaudio
@c playaudio scripts/audio/playaudio.m
-*- texinfo -*-
@deftypefn  {Function File} {} playaudio (@var{name}, @var{ext})
@deftypefnx {Function File} {} playaudio (@var{x})
Plays 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
record
@c record scripts/audio/record.m
-*- texinfo -*-
@deftypefn {Function File} {} record (@var{sec}, @var{sampling_rate})
Records @var{sec} seconds of audio input into the vector @var{x}.  The
default value for @var{sampling_rate} is 8000 samples per second, or
8kHz.  The program waits until the user types @key{RET} and then
immediately starts to record.
@seealso{lin2mu, mu2lin, loadaudio, saveaudio, playaudio, setaudio}
@end deftypefn
saveaudio
@c saveaudio scripts/audio/saveaudio.m
-*- texinfo -*-
@deftypefn {Function File} {} saveaudio (@var{name}, @var{x}, @var{ext}, @var{bps})
Saves 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
setaudio
@c setaudio scripts/audio/setaudio.m
-*- texinfo -*-
@deftypefn  {Function File} {} setaudio ()
@deftypefnx {Function File} {} setaudio (@var{w_type})
@deftypefnx {Function File} {} setaudio (@var{w_type}, @var{value})
Execute the shell command @samp{mixer}, possibly with optional
arguments @var{w_type} and @var{value}.
@end deftypefn
wavread
@c wavread scripts/audio/wavread.m
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} wavread (@var{filename})
Load the RIFF/WAVE sound file @var{filename}, and return the samples
in vector @var{y}.  If the file contains multichannel data, then
@var{y} is a matrix with the channels represented as columns.

@deftypefnx {Function File} {[@var{y}, @var{Fs}, @var{bits}] =} wavread (@var{filename})
Additionally return the sample rate (@var{fs}) in Hz and the number of bits
per sample (@var{bits}).

@deftypefnx {Function File} {[@dots{}] =} wavread (@var{filename}, @var{n})
Read only the first @var{n} samples from each channel.

@deftypefnx {Function File} {[@dots{}] =} wavread (@var{filename}, @var{n1} @var{n2})
Read only samples @var{n1} through @var{n2} from each channel.

@deftypefnx {Function File} {[@var{samples}, @var{channels}] =} wavread (@var{filename}, "size")
Return the number of samples (@var{n}) and channels (@var{ch})
instead of the audio data.
@seealso{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{bits}, @var{filename})
Write @var{y} to the canonical RIFF/WAVE sound file @var{filename}
with sample rate @var{fs} and bits per sample @var{bits}.  The
default sample rate is 8000 Hz with 16-bits per sample.  Each column
of the data represents a separate channel.
@seealso{wavread}
@end deftypefn
autocor
@c autocor scripts/deprecated/autocor.m
-*- texinfo -*-
@deftypefn {Function File} {} autocor (@var{x}, @var{h})
Return the autocorrelations from lag 0 to @var{h} of vector @var{x}.
If @var{h} is omitted, all autocorrelations are computed.
If @var{x} is a matrix, the autocorrelations of each column are
computed.
The particular algorithm used is from the field of statistics and
differs from the definition used in signal processing.
@end deftypefn
autocov
@c autocov scripts/deprecated/autocov.m
-*- texinfo -*-
@deftypefn {Function File} {} autocov (@var{x}, @var{h})
Return the autocovariances from lag 0 to @var{h} of vector @var{x}.
If @var{h} is omitted, all autocovariances are computed.
If @var{x} is a matrix, the autocovariances of each column are
computed.
The particular algorithm used is from the field of statistics and
differs from the definition used in signal processing.
@end deftypefn
betai
@c betai scripts/deprecated/betai.m
-*- texinfo -*-
@deftypefn {Function File} {} betai (@var{a}, @var{b}, @var{x})
This function is provided for compatibility with older versions of
Octave.  New programs should use betainc instead.

@code{betai (@var{a}, @var{b}, @var{x})} is the same as
@code{betainc (@var{x}, @var{a}, @var{b})}.
@end deftypefn
cellidx
@c cellidx scripts/deprecated/cellidx.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{idxvec}, @var{errmsg}] =} cellidx (@var{listvar}, @var{strlist})
Return indices of string entries in @var{listvar} that match strings
in @var{strlist}.

Both @var{listvar} and @var{strlist} may be passed as strings or
string matrices.  If they are passed as string matrices, each entry
is processed by @code{deblank} prior to searching for the entries.

The first output is the vector of indices in @var{listvar}.

If @var{strlist} contains a string not in @var{listvar}, then
an error message is returned in @var{errmsg}.  If only one output
argument is requested, then @var{cellidx} prints @var{errmsg} to the
screen and exits with an error.
@end deftypefn
clg
@c clg scripts/deprecated/clg.m
-*- texinfo -*-
@deftypefn {Function File} {} clg ()
This function has been deprecated.  Use clf instead.
@end deftypefn
complement
@c complement scripts/deprecated/complement.m
-*- texinfo -*-
@deftypefn {Function File} {} complement (@var{x}, @var{y})
Return the elements of set @var{y} that are not in set @var{x}.  For
example:

@example
@group
complement ([ 1, 2, 3 ], [ 2, 3, 5 ])
     @result{} 5
@end group
@end example
@seealso{union, intersect, unique}
@end deftypefn
create_set
@c create_set scripts/deprecated/create_set.m
-*- texinfo -*-
@deftypefn  {Function File} {} create_set (@var{x})
@deftypefnx {Function File} {} create_set (@var{x}, "rows")
This function has been deprecated.  Use unique instead.
@end deftypefn
dispatch
@c dispatch scripts/deprecated/dispatch.m
-*- texinfo -*-
@deftypefn {Loadable Function} {} dispatch (@var{f}, @var{r}, @var{type})

Replace the function @var{f} with a dispatch so that function @var{r}
is called when @var{f} is called with the first argument of the named
@var{type}.  If the type is @var{any} then call @var{r} if no other type
matches.  The original function @var{f} is accessible using
@code{builtin (@var{f}, @dots{})}.

If @var{r} is omitted, clear dispatch function associated with @var{type}.

If both @var{r} and @var{type} are omitted, list dispatch functions
for @var{f}.
@seealso{builtin}
@end deftypefn
dmult
@c dmult scripts/deprecated/dmult.m
-*- texinfo -*-
@deftypefn {Function File} {} dmult (@var{a}, @var{b})
This function has been deprecated.  Use the direct syntax @code{diag(A)*B}
which is more readable and now also more efficient.
@end deftypefn
fstat
@c fstat scripts/deprecated/fstat.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{info}, @var{err}, @var{msg}] =} fstat (fid)
This function has been deprecated.  Use stat instead.
@end deftypefn
gammai
@c gammai scripts/deprecated/gammai.m
-*- texinfo -*-
@deftypefn {Function File} {} gammai (@var{a}, @var{x})
This function is provided for compatibility with older versions of
Octave.  New programs should use @code{gammainc} instead.

@code{gammai (@var{a}, @var{x})} is the same as
@code{gammainc (@var{x}, @var{a})}.
@end deftypefn
glpkmex
@c glpkmex scripts/deprecated/glpkmex.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{xopt}, @var{fmin}, @var{status}, @var{extra}] =} glpkmex (@var{sense}, @var{c}, @var{A}, @var{b}, @var{ctype}, @var{lb}, @var{ub}, @var{vartype}, @var{param}, @var{lpsolver}, @var{save_pb})
This function is provided for compatibility with the old @sc{matlab}
interface to the GNU @sc{glpk} library.  For Octave code, you should use
the @code{glpk} function instead.
@seealso{glpk}
@end deftypefn
intwarning
@c intwarning scripts/deprecated/intwarning.m
-*- texinfo -*-
@deftypefn  {Function File} {} intwarning (@var{action})
@deftypefnx {Function File} {} intwarning (@var{s})
@deftypefnx {Function File} {@var{s} =} intwarning (@dots{})
Control the state of the warning for integer conversions and math
operations.

@table @asis
@item "query"
With an output argument, return the current state of the integer
conversion and math warnings.  With no output arguments, print the
current state.
@c Set example in small font to prevent overfull line

@smallexample
@group
intwarning ("query")
The state of warning "Octave:int-convert-nan" is "off"
The state of warning "Octave:int-convert-non-int-val" is "off"
The state of warning "Octave:int-convert-overflow" is "off"
The state of warning "Octave:int-math-overflow" is "off"
@end group
@end smallexample

@item "on"
@itemx "off"
Turn integer conversion and math warnings on (or off).  If there is
no output argument, then nothing is printed.  Otherwise the original
state of the state of the integer conversion and math warnings is
returned in a structure array.
@end table

The original state of the integer warnings can be restored by passing
the structure array returned by @code{intwarning} to a later call to
@code{intwarning}.  For example:

@example
@group
s = intwarning ("off");
@dots{}
intwarning (s);
@end group
@end example
@seealso{warning}
@end deftypefn
iscommand
@c iscommand scripts/deprecated/iscommand.m
-*- texinfo -*-
@deftypefn {Built-in Function} {} iscommand (@var{name})
This function is obsolete and will be removed from a future
version of Octave.
@end deftypefn
is_global
@c is_global scripts/deprecated/is_global.m
-*- texinfo -*-
@deftypefn {Function File} {} is_global (@var{name})
This function is provided for compatibility with older versions of
Octave.  New programs should use isglobal instead.
@end deftypefn
israwcommand
@c israwcommand scripts/deprecated/israwcommand.m
-*- texinfo -*-
@deftypefn {Built-in Function} {} israwcommand (@var{name})
This function is obsolete and will be removed from a future
version of Octave.
@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
lchol
@c lchol scripts/deprecated/lchol.m
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{l} =} lchol (@var{a})
@deftypefnx {Loadable Function} {[@var{l}, @var{p}] =} lchol (@var{a})
This function has been deprecated.  Use @code{chol (@dots{},'lower')}
instead.
@end deftypefn
loadimage
@c loadimage scripts/deprecated/loadimage.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{map}] =} loadimage (@var{file})
Load an image file and its associated color map from the specified
@var{file}.  The image must be stored in Octave's image format.
@seealso{saveimage, load, save}
@end deftypefn
krylovb
@c krylovb scripts/deprecated/krylovb.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{u}, @var{ucols}] =} krylovb (@var{A}, @var{V}, @var{k}, @var{eps1}, @var{pflg})
See @code{krylov}.
@end deftypefn
mark_as_command
@c mark_as_command scripts/deprecated/mark_as_command.m
-*- texinfo -*-
@deftypefn {Built-in Function} {} mark_as_command (@var{name})
This function is obsolete and will be removed from a future
version of Octave.
@end deftypefn
mark_as_rawcommand
@c mark_as_rawcommand scripts/deprecated/mark_as_rawcommand.m
-*- texinfo -*-
@deftypefn {Built-in Function} {} mark_as_rawcommand (@var{name})
This function is obsolete and will be removed from a future
version of Octave.
@end deftypefn
replot
@c replot scripts/deprecated/replot.m
-*- texinfo -*-
@deftypefn {Function File} {} replot ()
Refresh the plot window.
@end deftypefn
saveimage
@c saveimage scripts/deprecated/saveimage.m
-*- texinfo -*-
@deftypefn  {Function File} {} saveimage (@var{fname}, @var{img}, @var{fmt})
@deftypefnx {Function File} {} saveimage (@var{fname}, @var{img}, @var{fmt}, @var{map})
Save the matrix @var{img} to file @var{fname} in image format @var{fmt}.
Valid values for @var{fmt} are

@table @asis
@item "img"
Octave's image format.  The current colormap is also saved in the file.

@item "ppm"
Portable pixmap format.

@item "ps"
PostScript format.  Note that images saved in PostScript format cannot
be read back into Octave with loadimage.
@end table

If the fourth argument is supplied, the specified colormap will also be
saved along with the image.

Note: if the colormap contains only two entries and these entries are
black and white, the bitmap ppm and PostScript formats are used.  If the
image is a gray scale image (the entries within each row of the colormap
are equal) the gray scale ppm and PostScript image formats are used,
otherwise the full color formats are used.
@seealso{loadimage, save, load, colormap}
@end deftypefn
setstr
@c setstr scripts/deprecated/setstr.m
-*- texinfo -*-
@deftypefn {Function File} {} setstr (@var{s})
This function has been deprecated.  Use char instead.
@end deftypefn
spatan2
@c spatan2 scripts/deprecated/spatan2.m
-*- texinfo -*-
@deftypefn {Function File} {} spatan2 (@var{y}, @var{x})
This function has been deprecated.  Use @code{atan2} instead.
@end deftypefn
spchol2inv
@c spchol2inv scripts/deprecated/spchol2inv.m
-*- texinfo -*-
@deftypefn {Function File} {} spchol2inv (@var{u})
This function has been deprecated.  Use @code{chol2inv} instead.
@end deftypefn
spcholinv
@c spcholinv scripts/deprecated/spcholinv.m
-*- texinfo -*-
@deftypefn {Function File} {} spcholinv (@var{u})
This function has been deprecated.  Use @code{cholinv} instead.
@end deftypefn
spchol
@c spchol scripts/deprecated/spchol.m
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{r} =} spchol (@var{a})
@deftypefnx {Loadable Function} {[@var{r}, @var{p}] =} spchol (@var{a})
@deftypefnx {Loadable Function} {[@var{r}, @var{p}, @var{q}] =} spchol (@var{a})
This function has been deprecated.  Use @code{chol} instead.
@end deftypefn
spcumprod
@c spcumprod scripts/deprecated/spcumprod.m
-*- texinfo -*-
@deftypefn {Function File} {} spcumprod (@var{x}, @var{dim})
This function has been deprecated.  Use @code{cumprod} instead.
@end deftypefn
spcumsum
@c spcumsum scripts/deprecated/spcumsum.m
-*- texinfo -*-
@deftypefn {Function File} {} spcumsum (@var{x}, @var{dim})
This function has been deprecated.  Use @code{cumsum} instead.
@end deftypefn
spdet
@c spdet scripts/deprecated/spdet.m
-*- texinfo -*-
@deftypefn {Loadable Function} {[@var{d}, @var{rcond}] =} spdet (@var{a})
This function has been deprecated.  Use @code{det} instead.
@end deftypefn
spdiag
@c spdiag scripts/deprecated/spdiag.m
-*- texinfo -*-
@deftypefn {Function File} {} spdiag (@var{v}, @var{k})
This function has been deprecated.  Use @code{sparse (diag (@dots{}))}
instead.
@end deftypefn
spfind
@c spfind scripts/deprecated/spfind.m
-*- texinfo -*-
@deftypefn  {Loadable Function} {} spfind (@var{x})
@deftypefnx {Loadable Function} {} spfind (@var{x}, @var{n})
@deftypefnx {Loadable Function} {} spfind (@var{x}, @var{n}, @var{direction})
@deftypefnx {Loadable Function} {[@var{i}, @var{j}, @var{v}} spfind (@dots{})
This function has been deprecated.  Use @code{find} instead.
@end deftypefn
sphcat
@c sphcat scripts/deprecated/sphcat.m
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} sphcat (@var{a1}, @var{a2}, @dots{}, @var{aN})
Return the horizontal concatenation of sparse matrices.  This function
is obselete and @code{horzcat} should be used instead.
@seealso {horzcat, spvcat, vertcat, cat}
@end deftypefn
spinv
@c spinv scripts/deprecated/spinv.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{rcond}] =} spinv (@var{a})
This function has been deprecated.  Use @code{inv} instead.
@end deftypefn
spkron
@c spkron scripts/deprecated/spkron.m
-*- texinfo -*-
@deftypefn {Function File} {} spkron (@var{a}, @var{b})
This function has been deprecated.  Use @code{kron} instead.
@end deftypefn
splchol
@c splchol scripts/deprecated/splchol.m
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{l} =} splchol (@var{a})
@deftypefnx {Loadable Function} {[@var{l}, @var{p}] =} splchol (@var{a})
@deftypefnx {Loadable Function} {[@var{l}, @var{p}, @var{q}] =} splchol (@var{a})
This function has been deprecated.  Use @code{chol (@dots{},'lower')}
instead.
@end deftypefn
split
@c split scripts/deprecated/split.m
-*- texinfo -*-
@deftypefn {Function File} {} split (@var{s}, @var{t}, @var{n})
This function has been deprecated.  Use @code{char (strsplit (s, t))}
instead.
@end deftypefn
splu
@c splu scripts/deprecated/splu.m
-*- texinfo -*-
@deftypefn  {Loadable Function} {[@var{l}, @var{u}] =} splu (@var{a})
@deftypefnx {Loadable Function} {[@var{l}, @var{u}, @var{P}] =} splu (@var{a})
@deftypefnx {Loadable Function} {[@var{l}, @var{u}, @var{P}, @var{Q}] =} splu (@var{a})
@deftypefnx {Loadable Function} {[@var{l}, @var{u}, @var{P}, @var{Q}] =} splu (@dots{}, @var{thres})
@deftypefnx {Loadable Function} {[@var{l}, @var{u}, @var{P}] =} splu (@dots{}, @var{Q})
This function has been deprecated.  Use @code{lu} instead.
@end deftypefn
spmax
@c spmax scripts/deprecated/spmax.m
-*- texinfo -*-
@deftypefn  {Mapping Function} {} spmax (@var{x}, @var{y}, @var{dim})
@deftypefnx {Mapping Function} {[@var{w}, @var{iw}] =} spmax (@var{x})
This function has been deprecated.  Use @code{max} instead.
@end deftypefn
spmin
@c spmin scripts/deprecated/spmin.m
-*- texinfo -*-
@deftypefn  {Mapping Function} {} spmin (@var{x}, @var{y}, @var{dim})
@deftypefnx {Mapping Function} {[@var{w}, @var{iw}] =} spmin (@var{x})
This function has been deprecated.  Use @code{min} instead.
@end deftypefn
spprod
@c spprod scripts/deprecated/spprod.m
-*- texinfo -*-
@deftypefn {Function File} {} spprod (@var{x}, @var{dim})
This function has been deprecated.  Use @code{prod} instead.
@end deftypefn
spqr
@c spqr scripts/deprecated/spqr.m
-*- texinfo -*-
@deftypefn  {Loadable Function} {@var{r} =} spqr (@var{a})
@deftypefnx {Loadable Function} {@var{r} =} spqr (@var{a}, 0)
@deftypefnx {Loadable Function} {[@var{c}, @var{r}] =} spqr (@var{a}, @var{b})
@deftypefnx {Loadable Function} {[@var{c}, @var{r}] =} spqr (@var{a}, @var{b}, 0)
This function has been deprecated.  Use @code{qr} instead.
@end deftypefn
spsum
@c spsum scripts/deprecated/spsum.m
-*- texinfo -*-
@deftypefn {Function File} {} spsum (@var{x}, @var{dim})
This function has been deprecated.  Use @code{sum} instead.
@end deftypefn
spsumsq
@c spsumsq scripts/deprecated/spsumsq.m
-*- texinfo -*-
@deftypefn {Function File} {} spsumsq (@var{x}, @var{dim})
This function has been deprecated.  Use @code{sumsq} instead.
@end deftypefn
spvcat
@c spvcat scripts/deprecated/spvcat.m
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} spvcat (@var{a1}, @var{a2}, @dots{}, @var{aN})
Return the vertical concatenation of sparse matrices.  This function
is obselete and @code{vertcat} should be used instead.
@seealso{vertcat, sphcat, horzcat, cat}
@end deftypefn
str2mat
@c str2mat scripts/deprecated/str2mat.m
-*- texinfo -*-
@deftypefn {Function File} {} str2mat (@var{s_1}, @dots{}, @var{s_n})
Return a matrix containing the strings @var{s_1}, @dots{}, @var{s_n} as
its rows.  Each string is padded with blanks in order to form a valid
matrix.

This function is modelled after @sc{matlab}.  In Octave, you can create
a matrix of strings by @code{[@var{s_1}; @dots{}; @var{s_n}]} even if
the strings are not all the same length.
@end deftypefn
unmark_command
@c unmark_command scripts/deprecated/unmark_command.m
-*- texinfo -*-
@deftypefn {Built-in Function} {} unmark_command (@var{name})
This function is obsolete and will be removed from a future
version of Octave.
@end deftypefn
unmark_rawcommand
@c unmark_rawcommand scripts/deprecated/unmark_rawcommand.m
-*- texinfo -*-
@deftypefn {Built-in Function} {} unmark_rawcommand (@var{name})
This function is obsolete and will be removed from a future
version of Octave.
@end deftypefn
values
@c values scripts/deprecated/values.m
-*- texinfo -*-
@deftypefn {Function File} {} values (@var{x})
Return the different values in a column vector, arranged in ascending
order.

As an example, @code{values([1, 2, 3, 1])} returns the vector
@code{[1, 2, 3]}.
@end deftypefn
weibcdf
@c weibcdf scripts/deprecated/weibcdf.m
-*- texinfo -*-
@deftypefn {Function File} {} weibcdf (@var{x}, @var{scale}, @var{shape})
Compute the cumulative distribution function (CDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape}, which is

@example
1 - exp(-(x/shape)^scale)
@end example

@noindent
for @var{x} @geq{} 0.
@end deftypefn
weibinv
@c weibinv scripts/deprecated/weibinv.m
-*- texinfo -*-
@deftypefn {Function File} {} weibinv (@var{x}, @var{scale}, @var{shape})
Compute the quantile (the inverse of the CDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape}.
@end deftypefn
weibpdf
@c weibpdf scripts/deprecated/weibpdf.m
-*- texinfo -*-
@deftypefn {Function File} {} weibpdf (@var{x}, @var{scale}, @var{shape})
Compute the probability density function (PDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape} which is given by

@example
   scale * shape^(-scale) * x^(scale-1) * exp(-(x/shape)^scale)
@end example

@noindent
for @var{x} > 0.
@end deftypefn
weibrnd
@c weibrnd scripts/deprecated/weibrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} weibrnd (@var{scale}, @var{shape}, @var{r}, @var{c})
@deftypefnx {Function File} {} weibrnd (@var{scale}, @var{shape}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
Weibull distribution with parameters @var{scale} and @var{shape}
which must be scalar or of size @var{r} by @var{c}.  Or if @var{sz}
is a vector return a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{alpha} and @var{sigma}.
@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
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
lcm
@c lcm scripts/elfun/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 the same size or
scalar.
@seealso{factor, gcd}
@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{csubs}, @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}.

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

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.

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

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

@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]
   ans(:,:,2) = [0, 0, 0; 206, 0, 208]
@end group
@end example

The complexity in 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}
@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 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{} ans = [-10,-11,-1;-15,-3,5]
@end group
@end example

@seealso{accumarray}
@end deftypefn
arrayfun
@c arrayfun scripts/general/arrayfun.m
-*- texinfo -*-
@deftypefn  {Function File} {} arrayfun (@var{func}, @var{A})
@deftypefnx {Function File} {@var{x} =} arrayfun (@var{func}, @var{A})
@deftypefnx {Function File} {@var{x} =} arrayfun (@var{func}, @var{A}, @var{b}, @dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @dots{}] =} arrayfun (@var{func}, @var{A}, @dots{})
@deftypefnx {Function File} {} arrayfun (@dots{}, "UniformOutput", @var{val})
@deftypefnx {Function File} {} arrayfun (@dots{}, "ErrorHandler", @var{errfunc})

Execute a function on each element of an array.  This is useful for
functions that do not accept array arguments.  If the function does
accept array arguments it is better to call the function directly.

The first input argument @var{func} can be a string, a function
handle, an inline function or an anonymous function.  The input
argument @var{A} can be a logic array, a numeric array, a string
array, a structure array or a cell array.  By a call of the function
@command{arrayfun} all elements of @var{A} are passed on to the named
function @var{func} individually.

The named function can also take more than two input arguments, with
the input arguments given as third input argument @var{b}, fourth
input argument @var{c}, @dots{}  If given more than one array input
argument then all input arguments must have the same sizes, for
example:

@example
@group
arrayfun (@@atan2, [1, 0], [0, 1])
@result{} ans = [1.5708   0.0000]
@end group
@end example

If the parameter @var{val} after a further string input argument
"UniformOutput" is set @code{true} (the default), then the named
function @var{func} must return a single element which then will be
concatenated into the return value and is of type matrix.  Otherwise,
if that parameter is set to @code{false}, then the outputs are
concatenated in a cell array.  For example:

@example
@group
arrayfun (@@(x,y) x:y, "abc", "def", "UniformOutput", false)
@result{} ans =
@{
  [1,1] = abcd
  [1,2] = bcde
  [1,3] = cdef
@}
@end group
@end example

If more than one output arguments are given then the named function
must return the number of return values that also are expected, for
example:

@example
@group
[A, B, C] = arrayfun (@@find, [10; 0], "UniformOutput", false)
@result{}
A =
@{
  [1,1] =  1
  [2,1] = [](0x0)
@}
B =
@{
  [1,1] =  1
  [2,1] = [](0x0)
@}
C =
@{
  [1,1] =  10
  [2,1] = [](0x0)
@}
@end group
@end example

If the parameter @var{errfunc} after a further string input argument
"ErrorHandler" is another string, a function handle, an inline
function or an anonymous function, then @var{errfunc} defines a
function to call in the case that @var{func} generates an error.
The definition of the function must be of the form

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

@noindent
where there is an additional input argument to @var{errfunc}
relative to @var{func}, given by @var{s}.  This is a structure with
the elements "identifier", "message" and "index", giving
respectively the error identifier, the error message and the index of
the array elements that caused the error.  The size of the output
argument of @var{errfunc} must have the same size as the output
argument of @var{func}, otherwise a real error is thrown.  For
example:

@example
@group
function y = ferr (s, x), y = "MyString"; endfunction
arrayfun (@@str2num, [1234], \
          "UniformOutput", false, "ErrorHandler", @@ferr)
@result{} ans =
@{
 [1,1] = MyString
@}
@end group
@end example

@seealso{spfun, cellfun, structfun}
@end deftypefn
bicubic
@c bicubic scripts/general/bicubic.m
-*- texinfo -*-
@deftypefn {Function File} {@var{zi} =} bicubic (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi}, @var{extrapval})

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
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 unsigned integers in @var{A}
the lowest 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 unsigned integers in @var{A}.
@var{val} = 0 resets and @var{val} = 1 sets the bits.
The lowest significant bit is: @var{n} = 1

@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 the arguments must be numeric and are two-dimensional matrices or
scalars.
@seealso{diag, horzcat, vertcat}
@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 to polar or cylindrical coordinates.

@var{theta} describes the angle relative to the positive x-axis.
@var{r} is the distance to the z-axis @w{(0, 0, z)}.
@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})).

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 to spherical coordinates.

@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)}.
@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}).

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, 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}, @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 shifts 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
colon
@c colon scripts/general/colon.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{r} =} colon (@var{a}, @var{b})
@deftypefnx {Function File} {@var{r} =} colon (@var{a}, @var{b}, @var{c})
Method of a class to construct a range with the @code{:} operator.  For
example:

@example
@group
a = myclass (@dots{})
b = myclass (@dots{})
c = a : b
@end group
@end example

@seealso{class, subsref, subsasgn}
@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 so, @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.  Place the negative imaginary complex number
first within each pair.  Place all the real numbers (those with
@code{abs (imag (@var{z}) / @var{z}) < @var{tol})}) 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{z} =} cumtrapz (@var{y})
@deftypefnx {Function File} {@var{z} =} cumtrapz (@var{x}, @var{y})
@deftypefnx {Function File} {@var{z} =} cumtrapz (@dots{}, @var{dim})

Cumulative numerical integration using trapezoidal method.
@code{cumtrapz (@var{y})} computes the cumulative integral of the
@var{y} along the first non-singleton dimension.  If the argument
@var{x} is omitted an equally spaced vector is assumed.  @code{cumtrapz
(@var{x}, @var{y})} evaluates the cumulative integral with respect
to @var{x}.

@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, dot}
@end deftypefn
dblquad
@c dblquad scripts/general/dblquad.m
-*- texinfo -*-
@deftypefn {Function File} {} dblquad (@var{f}, @var{xa}, @var{xb}, @var{ya}, @var{yb}, @var{tol}, @var{quadf}, @dots{})
Numerically evaluate a double integral.  The function over with to
integrate is defined by @code{@var{f}}, and the interval for the
integration is defined by @code{[@var{xa}, @var{xb}, @var{ya},
@var{yb}]}.  The function @var{f} must accept a vector @var{x} and a
scalar @var{y}, and return a vector of the same length as @var{x}.

If defined, @var{tol} defines the absolute tolerance to which to
which to integrate each sub-integral.

Additional arguments, are passed directly to @var{f}.  To use the default
value for @var{tol} one may pass 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 one 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
@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 "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 "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, cross, dot}
@end deftypefn
flipdim
@c flipdim scripts/general/flipdim.m
-*- texinfo -*-
@deftypefn  {Function File} {} flipdim (@var{x})
@deftypefnx {Function File} {} flipdim (@var{x}, @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
flipdim ([1, 2; 3, 4], 2)
     @result{}  2  1
         4  3
@end group
@end example
@seealso{fliplr, flipud, rot90, rotdim}
@end deftypefn
fliplr
@c fliplr scripts/general/fliplr.m
-*- texinfo -*-
@deftypefn {Function File} {} fliplr (@var{x})
Return a copy of @var{x} with the order of the columns reversed.  For
example:

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

Note that @code{fliplr} only work with 2-D arrays.  To flip N-d arrays
use @code{flipdim} instead.
@seealso{flipud, flipdim, rot90, rotdim}
@end deftypefn
flipud
@c flipud scripts/general/flipud.m
-*- texinfo -*-
@deftypefn {Function File} {} flipud (@var{x})
Return a copy of @var{x} with the order of the rows reversed.  For
example:

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

Due to the difficulty of defining which axis about which to flip the
matrix @code{flipud} only work with 2-d arrays.  To flip N-d arrays
use @code{flipdim} instead.
@seealso{fliplr, flipdim, rot90, rotdim}
@end deftypefn
genvarname
@c genvarname scripts/general/genvarname.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{varname} =} genvarname (@var{str})
@deftypefnx {Function File} {@var{varname} =} genvarname (@var{str}, @var{exclusions})
Create unique variable(s) from @var{str}.  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).

If @var{str} is a cellstr, then a unique variable is created for each
cell in @var{str}.

@example
@group
x = 3.141;
genvarname ("x", who ())
@result{} x1
@end group
@end example

If @var{wanted} is a cell array, genvarname will make sure the returned
strings are distinct:

@example
@group
genvarname (@{"foo", "foo"@})
@result{}
@{
  [1,1] = foo
  [1,2] = foo1
@}
@end group
@end example

Note that the result is a char array/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

Also, 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,
genvarname replaces any sequence of disallowed characters with
an underscore.  Also, variables may not begin with a digit; in this
case an underscore is added before the variable name.

Variable names beginning and ending with two underscores "__" are valid but
they are used internally by octave and should generally be avoided, therefore
genvarname will not generate such names.

genvarname will also make sure that returned names do not clash with
keywords such as "for" and "if".  A number will be appended if necessary.
Note, however, that this does @strong{not} include function names,
such as "sin".  Such names should be included in @var{avoid} if necessary.
@seealso{isvarname, exist, tmpnam, eval}
@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 "fix"
Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
towards zero.

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

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

@item "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 @code{"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
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{} s =
      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{pp} =} interp1 (@dots{}, 'pp')

One-dimensional interpolation.  Interpolate @var{y}, defined at the
points @var{x}, at the points @var{xi}.  The sample points @var{x}
must be monotonic.  If not specified, @var{x} is taken to be the
indices of @var{y}.  If @var{y} is an array, treat the columns
of @var{y} separately.

Method is one of:

@table @asis
@item 'nearest'
Return the nearest neighbor.

@item 'linear'
Linear interpolation from nearest neighbors

@item 'pchip'
Piecewise cubic Hermite interpolating polynomial

@item 'cubic'
Cubic interpolation from four nearest neighbors

@item 'spline'
Cubic spline interpolation---smooth first and second derivatives
throughout the curve
@end table

Appending '*' to the start of the above method 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 'linear'.

If @var{extrap} is the string 'extrap', then extrapolate values beyond
the endpoints.  If @var{extrap} is a number, replace values beyond the
endpoints with that number.  If @var{extrap} is missing, assume NA.

If the string argument 'pp' is specified, then @var{xi} should not be
supplied and @code{interp1} returns the piecewise polynomial that
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}, 'pp'), @var{xi}) == interp1 (@var{x}, @var{y},
@var{xi}, @var{method}, 'extrap')}.

Duplicate points in @var{x} specify a discontinuous interpolant.  There
should be at most 2 consecutive points with the same value.
The discontinuous interpolant is right-continuous if @var{x} is increasing,
left-continuous if it is decreasing.
Discontinuities are (currently) only allowed for "nearest" and "linear"
methods; in all other cases, @var{x} must be strictly monotonic.

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);
spl = interp1 (xp, yp, xf, "spline");
cub = interp1 (xp, yp, xf, "cubic");
near = interp1 (xp, yp, xf, "nearest");
plot (xf, yf, "r", xf, lin, "g", xf, spl, "b",
      xf, cub, "c", xf, near, "m", xp, yp, "r*");
legend ("original", "linear", "spline", "cubic", "nearest")
@end group
@end example

@seealso{interpft}
@end deftypefn
interp1q
@c interp1q scripts/general/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 an array, treat the columns
of @var{y} separately.  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
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 (@dots{}, @var{method})
@deftypefnx {Function File} {@var{zi} =} interp2 (@dots{}, @var{method}, @var{extrapval})

Two-dimensional interpolation.  @var{x}, @var{y} and @var{z} describe a
surface function.  If @var{x} and @var{y} are vectors their length
must correspondent to the size of @var{z}.  @var{x} and @var{y} must be
monotonic.  If they are matrices they must have the @code{meshgrid}
format.

@table @code
@item interp2 (@var{x}, @var{y}, @var{Z}, @var{xi}, @var{yi}, @dots{})
Returns a matrix corresponding to the points described by the
matrices @var{xi}, @var{yi}.

If the last argument is a string, the interpolation method can
be specified.  The method can be 'linear', 'nearest' or 'cubic'.
If it is omitted 'linear' interpolation is assumed.

@item interp2 (@var{z}, @var{xi}, @var{yi})
Assumes @code{@var{x} = 1:rows (@var{z})} and @code{@var{y} =
1:columns (@var{z})}

@item interp2 (@var{z}, @var{n})
Interleaves the matrix @var{z} n-times.  If @var{n} is omitted a value
of @code{@var{n} = 1} is assumed.
@end table

The variable @var{method} defines the method to use for the
interpolation.  It can take one of the following values

@table @asis
@item 'nearest'
Return the nearest neighbor.

@item 'linear'
Linear interpolation from nearest neighbors.

@item 'pchip'
Piecewise cubic Hermite interpolating polynomial.

@item 'cubic'
Cubic interpolation from four nearest neighbors.

@item 'spline'
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

If a scalar value @var{extrapval} is defined as the final value, then
values outside the mesh as set to this value.  Note that in this case
@var{method} must be defined as well.  If @var{extrapval} is not
defined then NA is assumed.

@seealso{interp1}
@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{m})
@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})

Perform 3-dimensional interpolation.  Each element of the 3-dimensional
array @var{v} represents a 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 '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.

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)}.  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}.

Method is one of:

@table @asis
@item 'nearest'
Return the nearest neighbor.

@item 'linear'
Linear interpolation from nearest neighbors.

@item 'cubic'
Cubic interpolation from four nearest neighbors (not implemented yet).

@item 'spline'
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

The default method is 'linear'.

If @var{extrap} is the string 'extrap', then extrapolate values beyond
the endpoints.  If @var{extrap} is a number, replace values beyond the
endpoints with that number.  If @var{extrap} is missing, assume NA.
@seealso{interp1, interp2, spline, meshgrid}
@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 '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}.

Method is one of:

@table @asis
@item 'nearest'
Return the nearest neighbor.

@item 'linear'
Linear interpolation from nearest neighbors.

@item 'cubic'
Cubic interpolation from four nearest neighbors (not implemented yet).

@item 'spline'
Cubic spline interpolation---smooth first and second derivatives
throughout the curve.
@end table

The default method is 'linear'.

If @var{extrapval} is the scalar value, use it to replace the values
beyond the endpoints with that number.  If @var{extrapval} is missing,
assume NA.
@seealso{interp1, interp2, spline, ndgrid}
@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 an array, then operate along each column of
the array separately.  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 end points of the interpolation.

@seealso{interp1}
@end deftypefn
is_duplicate_entry
@c is_duplicate_entry scripts/general/is_duplicate_entry.m
-*- texinfo -*-
@deftypefn {Function File} {} is_duplicate_entry (@var{x})
Return non-zero if any entries in @var{x} are duplicates of one
another.
@seealso{unique}
@end deftypefn
isa
@c isa scripts/general/isa.m
-*- texinfo -*-
@deftypefn {Function File} {} isa (@var{obj}, @var{class})
Return true if @var{obj} is an object from the class @var{class}.
@seealso{class, typeinfo}
@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{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{isequalwithequalnans}
@end deftypefn
isequalwithequalnans
@c isequalwithequalnans scripts/general/isequalwithequalnans.m
-*- texinfo -*-
@deftypefn {Function File} {} isequalwithequalnans (@var{x1}, @var{x2}, @dots{})
Assuming NaN == NaN, return true if all of @var{x1}, @var{x2}, @dots{}
are equal.
@seealso{isequal}
@end deftypefn
isscalar
@c isscalar scripts/general/isscalar.m
-*- texinfo -*-
@deftypefn {Function File} {} isscalar (@var{x})
Return true if @var{x} is a scalar.
@seealso{isvector, ismatrix}
@end deftypefn
issquare
@c issquare scripts/general/issquare.m
-*- texinfo -*-
@deftypefn {Function File} {} issquare (@var{x})
Return true if @var{x} is a square matrix.
@seealso{isscalar, isvector, ismatrix, size}
@end deftypefn
isvector
@c isvector scripts/general/isvector.m
-*- texinfo -*-
@deftypefn {Function File} {} isvector (@var{x})
Return true if @var{x} is a vector.  A vector is a 2-D array
where one of the dimensions is equal to 1.  As a consequence a
1x1 array, or scalar, is also a vector.
@seealso{isscalar, ismatrix, size, rows, columns, length}
@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{base}, @var{limit})
@deftypefnx {Function File} {} logspace (@var{base}, @var{limit}, @var{n})
Similar to @code{linspace} except that the values are logarithmically
spaced from
@tex
$10^{base}$ to $10^{limit}$.
@end tex
@ifnottex
10^base to 10^limit.
@end ifnottex

If @var{limit} is equal to
@tex
$\pi$,
@end tex
@ifnottex
pi,
@end ifnottex
the points are between
@tex
$10^{base}$ and $\pi$,
@end tex
@ifnottex
10^base and pi,
@end ifnottex
@emph{not}
@tex
$10^{base}$ and $10^{\pi}$,
@end tex
@ifnottex
10^base and 10^pi,
@end ifnottex
in order to be compatible with the corresponding @sc{matlab}
function.
If @var{n} is unspecified it defaults to 50.

Also for compatibility with @sc{matlab}, return the second argument if
fewer than two values are requested.
@seealso{linspace}
@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.
@seealso{nargoutchk, error, nargin, nargout}
@end deftypefn
nargoutchk
@c nargoutchk scripts/general/nargoutchk.m
-*- texinfo -*-
@deftypefn  {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")
Return an appropriate error message string (or structure) if the
number of outputs requested is invalid.

This is useful for checking to see that the number of output
arguments supplied to a function is within an acceptable range.
@seealso{nargchk, error, nargout, nargin}
@end deftypefn
nextpow2
@c nextpow2 scripts/general/nextpow2.m
-*- texinfo -*-
@deftypefn {Function File} {} nextpow2 (@var{x})
If @var{x} is a scalar, return the first integer @var{n} such that
@tex
$2^n \ge |x|$.
@end tex
@ifnottex
2^n @geq{} abs (x).
@end ifnottex

If @var{x} is a vector, return @code{nextpow2 (length (@var{x}))}.
@seealso{pow2, log2}
@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 handle complex numbers.  For
example:

@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

The @code{num2str} function is not very flexible.  For better control
over the results, use @code{sprintf} (@pxref{Formatted Output}).
Note that for complex @var{x}, the format string may only contain one
output conversion specification and nothing else.  Otherwise, you
will get unpredictable results.
@seealso{sprintf, int2str, mat2str}
@end deftypefn
perror
@c perror scripts/general/perror.m
-*- texinfo -*-
@deftypefn {Function File} {} perror (@var{funcname}, @var{num})
Print the error message for function @var{funcname} corresponding to the
error number @var{num}.  This function is intended to be used to print
useful error messages for those functions that return numeric error
codes.
@seealso{strerror}
@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 to Cartesian coordinates.

@var{theta}, @var{r}, (and @var{z}) must be the same shape, or scalar.
@var{theta} describes the angle relative to the positive x-axis.
@var{r} is the distance to the z-axis (0, 0, z).
If called with a single matrix argument then each row of @var{p}
represents the polar/(cylindrical) coordinate (@var{x}, @var{y} (, @var{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})

Determines 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 the third argument is not
supplied, 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.
@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 the third argument is not
supplied, 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.
@seealso{postpad, cat, resize}
@end deftypefn
quadgk
@c quadgk scripts/general/quadgk.m
-*- texinfo -*-
@deftypefn  {Function File} {} quadgk (@var{f}, @var{a}, @var{b}, @var{abstol}, @var{trace})
@deftypefnx {Function File} {} quadgk (@var{f}, @var{a}, @var{b}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {[@var{q}, @var{err}] =} quadgk (@dots{})
Numerically evaluate integral using adaptive Gauss-Konrod quadrature.
The formulation is based on a proposal by L.F. Shampine,
@cite{"Vectorized adaptive quadrature in @sc{matlab}", Journal of
Computational and Applied Mathematics, pp131-140, Vol 211, Issue 2,
Feb 2008} where all function evaluations at an iteration are
calculated with a single call to @var{f}.  Therefore the function
@var{f} must be of the form @code{@var{f} (@var{x})} and accept
vector values of @var{x} and return a vector of the same length
representing the function evaluations at the given values of @var{x}.
The function @var{f} can be defined in terms of a function handle,
inline function or string.

The bounds of the quadrature @code{[@var{a}, @var{b}]} can be finite
or infinite and contain weak end singularities.  Variable
transformation will be used to treat 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 absolute tolerance can be passed as a fourth argument in a manner
compatible with @code{quadv}.  Equally the user can request that
information on the convergence can be printed is the fifth argument
is logically true.

Alternatively, certain properties of @code{quadgk} can be passed as
pairs @code{@var{prop}, @var{val}}.  Valid properties are

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

@item RelTol
Defines 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.  Sub-intervals that have an
unacceptable error are sub-divided and re-evaluated.  If the number of
sub-intervals exceeds at any point 650 sub-intervals then a poor
convergence is signaled and the current estimate of the integral is
returned.  The property 'MaxIntervalCount' can be used to alter the
number of sub-intervals that can exist before exiting.

@item WayPoints
If there exists discontinuities in the first derivative of the
function to integrate, then these can be flagged with the
@code{"WayPoints"} property.  This forces the ends of a sub-interval
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, then @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]}

If two output arguments are requested, then @var{err} returns the
approximate bounds on the error in the integral @code{abs (@var{q} -
@var{i})}, where @var{i} is the exact value of the integral.

@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 integral using adaptive Lobatto rule.
@code{quadl (@var{f}, @var{a}, @var{b})} approximates the integral of
@code{@var{f}(@var{x})} to machine precision.  @var{f} is either a
function handle, inline function or string containing the name of
the function to evaluate.  The function @var{f} must return a vector
of output values if given a vector of input values.

If defined, @var{tol} defines the relative tolerance to which to
which to integrate @code{@var{f}(@var{x})}.  While if @var{trace} is
defined, displays the left end point of the current interval, the
interval length, and the partial integral.

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

Reference: 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{fcnt}] =} quadv (@dots{})

Numerically evaluate the integral of @var{f} from @var{a} to @var{b}
using adaptive Simpson's rule.
@var{f} is either a function handle, inline function or string
containing the name of the function to evaluate.
The function defined by @var{f} may be a scalar, vector or array-valued.

If a value for @var{tol} is given, it defines the tolerance used to stop
the adaptation procedure, otherwise the default value of 1e-6 is used.

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

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

@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 "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 "double" to represent numbers.  This limits the maximum
integer (@var{imax}) and range (@var{imax} - @var{imin}) to the value
returned by the @code{bitmax} function.  For IEEE floating point numbers
this value is @w{@code{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

Called with two arguments returns 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}, @var{n})
@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.
@seealso{repelems}
@end deftypefn
rot90
@c rot90 scripts/general/rot90.m
-*- texinfo -*-
@deftypefn {Function File} {} rot90 (@var{A}, @var{k})
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

Due to the difficulty of defining an axis about which to rotate the
matrix @code{rot90} only work with 2-D arrays.  To rotate N-d arrays
use @code{rotdim} instead.
@seealso{rotdim, flipud, fliplr, flipdim}
@end deftypefn
rotdim
@c rotdim scripts/general/rotdim.m
-*- texinfo -*-
@deftypefn {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 is optional, and specifies
how many 90-degree rotations are to be applied (the default value is 1).
The third argument is also optional and defines the plane of the
rotation.  As such @var{plane} is a two element vector containing two
different valid dimensions of the matrix.  If @var{plane} is not given
Then the first two non-singleton dimensions are used.

Negative values of @var{n} rotate the matrix in a clockwise direction.
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, flipud, fliplr, flipdim}
@end deftypefn
runlength
@c runlength scripts/general/runlength.m
-*- texinfo -*-
@deftypefn {Function File} {} runlength (@var{x})
Find the lengths of all sequences of common values.  Return the
vector of lengths and the value that was repeated.

@example
@group
runlength ([2, 2, 0, 4, 4, 4, 0, 1, 1, 1, 1])
@result{}  [2, 1, 3, 1, 4]
@end group
@end example
@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})
Shifts the dimension 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} {} 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.
@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} {C =} sph2cart (@dots{})
Transform spherical to Cartesian coordinates.

@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)}.
@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}).

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
strerror
@c strerror scripts/general/strerror.m
-*- texinfo -*-
@deftypefn {Function File} {} strerror (@var{name}, @var{num})
Return the text of an error message for function @var{name}
corresponding to the error number @var{num}.  This function is intended
to be used to print useful error messages for those functions that
return numeric error codes.
@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 "UniformOutput" is set to true (the default), then the
function
must return a single element which will be concatenated into the
return value.  If "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 "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 @var{se}.  This is a structure with the elements
"identifier", "message" and "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{doc-cellfun, @code{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 "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
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}, @var{tol}, @var{quadf}, @dots{})
Numerically evaluate a triple integral.  The function over which to
integrate is defined by @code{@var{f}}, and the interval for the
integration is defined by @code{[@var{xa}, @var{xb}, @var{ya},
@var{yb}, @var{za}, @var{zb}]}.  The function @var{f} must accept a
vector @var{x} and a scalar @var{y}, and return a vector of the same
length as @var{x}.

If defined, @var{tol} defines the absolute tolerance to which to
which to integrate each sub-integral.

Additional arguments, are passed directly to @var{f}.  To use the default
value for @var{tol} one may pass an empty matrix.
@seealso{dblquad,quad,quadv,quadl,quadgk,quadcc,trapz}
@end deftypefn
trapz
@c trapz scripts/general/trapz.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{z} =} trapz (@var{y})
@deftypefnx {Function File} {@var{z} =} trapz (@var{x}, @var{y})
@deftypefnx {Function File} {@var{z} =} trapz (@dots{}, @var{dim})

Numerical integration using trapezoidal method.  @code{trapz
(@var{y})} computes the integral of the @var{y} along the first
non-singleton dimension.  If the argument @var{x} is omitted a
equally spaced vector is assumed.  @code{trapz (@var{x}, @var{y})}
evaluates the integral with respect to @var{x}.

@seealso{cumtrapz}
@end deftypefn
__isequal__
@c __isequal__ scripts/general/private/__isequal__.m
Undocumented internal function.
__splinen__
@c __splinen__ scripts/general/private/__splinen__.m
Undocumented internal function.
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{opt})
Returns the index vector to the points of the enclosing convex hull.  The
data points are defined by the x and y vectors.

A third optional argument, which must be a string, contains extra options
passed to the underlying qhull command.  See the documentation for the
Qhull library for details.

@seealso{delaunay, convhulln}
@end deftypefn
delaunay3
@c delaunay3 scripts/geometry/delaunay3.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{T} =} delaunay3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {@var{T} =} delaunay3 (@var{x}, @var{y}, @var{z}, @var{opt})
A matrix of size [n, 4] is returned.  Each row contains a
set of tetrahedron which are
described by the indices to the data point vectors (x,y,z).

A fourth optional argument, which must be a string or cell array of strings,
contains extra options passed to the underlying qhull command.  See the
documentation for the Qhull library for details.
@seealso{delaunay,delaunayn}
@end deftypefn
delaunayn
@c delaunayn scripts/geometry/delaunayn.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{t} =} delaunayn (@var{p})
@deftypefnx {Function File} {@var{t} =} delaunayn (@var{p}, @var{opt})
Form the Delaunay triangulation for a set of points.
The Delaunay triangulation is a tessellation of the convex hull of the
points such that no n-sphere defined by the n-triangles contains
any other points from the set.
The input matrix @var{p} of size @code{[n, dim]} contains @math{n}
points in a space of dimension dim.  The return matrix @var{t} has the
size @code{[m, dim+1]}.  It contains for each row a set of indices to
the points, which describes a simplex of dimension dim.  For example,
a 2-D simplex is a triangle and 3-D simplex is a tetrahedron.

Extra options for the underlying Qhull command can be specified by the
second argument.  This argument is a cell array of strings.  The default
options depend on the dimension of the input:

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

@item 4D and higher: @var{opt} = @code{@{"Qt", "Qbb", "Qc", "Qz"@}}
@end itemize

If @var{opt} is [], then the default arguments are used.  If @var{opt}
is @code{@{"@w{}"@}}, then none of the default arguments are used by Qhull.
See the Qhull documentation for the available options.

All options can also be specified as single string, for example
@code{"Qt Qbb Qc Qz"}.

@end deftypefn
delaunay
@c delaunay scripts/geometry/delaunay.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{tri} =} delaunay (@var{x}, @var{y})
@deftypefnx {Function File} {@var{tri} =} delaunay (@var{x}, @var{y}, @var{opt})
The return matrix of size [n, 3] contains a set triangles which are
described by the indices to the data point x and y vector.
The triangulation satisfies the Delaunay circum-circle criterion.
No other data point is in the circum-circle of the defining triangle.

A third optional argument, which must be a string, contains extra options
passed to the underlying qhull command.  See the documentation for the
Qhull library for details.

@example
@group
x = rand (1, 10);
y = rand (size (x));
T = delaunay (x, y);
X = [x(T(:,1)); x(T(:,2)); x(T(:,3)); x(T(:,1))];
Y = [y(T(:,1)); y(T(:,2)); y(T(:,3)); y(T(:,1))];
axis ([0,1,0,1]);
plot (X, Y, "b", x, y, "r*");
@end group
@end example
@seealso{voronoi, delaunay3, delaunayn}
@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})
Returns the index @var{idx} or 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{})
Returns the index @var{idx} or 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}, @var{method})
@deftypefnx {Function File} {[@var{xi}, @var{yi}, @var{zi}] =} griddata (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi}, @var{method})

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 @code{"nearest"}, @code{"cubic"} or
@code{"linear"}.  If method is omitted it defaults to @code{"linear"}.
@seealso{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}, @var{method}, @var{options})

Generate a regular mesh from irregular data using interpolation.
The function is defined by @code{@var{y} = f (@var{x},@var{y},@var{z})}.
The interpolation points are all @var{xi}.

The interpolation method can be @code{"nearest"} or @code{"linear"}.
If method is omitted it defaults to @code{"linear"}.
@seealso{griddata, delaunayn}
@end deftypefn
griddatan
@c griddatan scripts/geometry/griddatan.m
-*- texinfo -*-
@deftypefn {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 @code{"nearest"} or @code{"linear"}.
If method is omitted it defaults to @code{"linear"}.
@seealso{griddata, delaunayn}
@end deftypefn
inpolygon
@c inpolygon scripts/geometry/inpolygon.m
-*- texinfo -*-
@deftypefn {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})}, determine
if the points @code{(@var{x}, @var{y})} are inside or outside the polygon.
The variables @var{x}, @var{y}, must have the same dimension.  The optional
output @var{on} gives the points that are on the polygon.

@end deftypefn
rectint
@c rectint scripts/geometry/rectint.m
-*- texinfo -*-
@deftypefn {Function File} {@var{area} =} rectint (@var{a}, @var{b})

Compute the area of intersection of rectangles in @var{a} and
rectangles in @var{b}.  Rectangles are defined as [x y width height]
where x and y are the minimum values of the two orthogonal
dimensions.

If @var{a} or @var{b} are matrices, 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
trimesh
@c trimesh scripts/geometry/trimesh.m
-*- texinfo -*-
@deftypefn  {Function File} {} trimesh (@var{tri}, @var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {@var{h} =} trimesh (@dots{})
Plot a triangular mesh in 3D@.  The variable @var{tri} is the triangular
meshing of the points @code{(@var{x}, @var{y})} which is returned
from @code{delaunay}.  The variable @var{z} is value at the point
@code{(@var{x}, @var{y})}.  The output argument @var{h} is the graphic
handle of the plot.
@seealso{triplot, trisurf, delaunay3}
@end deftypefn
triplot
@c triplot scripts/geometry/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 triangular mesh in 2D@.  The variable @var{tri} is the triangular
meshing of the points @code{(@var{x}, @var{y})} which is returned from
@code{delaunay}.  If given, the @var{linespec} determines the properties
to use for the lines.  The output argument @var{h} is the graphic handle
of the plot.
@seealso{plot, trimesh, trisurf, delaunay}
@end deftypefn
trisurf
@c trisurf scripts/geometry/trisurf.m
-*- texinfo -*-
@deftypefn  {Function File} {} trisurf (@var{tri}, @var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {@var{h} =} trisurf (@dots{})
Plot a triangular surface in 3D@.  The variable @var{tri} is the triangular
meshing of the points @code{(@var{x}, @var{y})} which is returned
from @code{delaunay}.  The variable @var{z} is value at the point
@code{(@var{x}, @var{y})}.  The output argument @var{h} is the graphic
handle of the plot.
@seealso{triplot, trimesh, delaunay3}
@end deftypefn
tsearchn
@c tsearchn scripts/geometry/tsearchn.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{idx}, @var{p}] =} tsearchn (@var{x}, @var{t}, @var{xi})
Searches 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}, "plotstyle")
@deftypefnx {Function File} {} voronoi (@var{x}, @var{y}, "plotstyle", @var{options})
@deftypefnx {Function File} {[@var{vx}, @var{vy}] =} voronoi (@dots{})
plots Voronoi diagram of points @code{(@var{x}, @var{y})}.
The Voronoi facets with points at infinity are not drawn.
[@var{vx}, @var{vy}] = voronoi(@dots{}) returns the vertices instead of
plotting the
diagram. plot (@var{vx}, @var{vy}) shows the Voronoi diagram.

A fourth optional argument, which must be a string, contains extra options
passed to the underlying qhull command.  See the documentation for the
Qhull library for details.

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

A second optional argument, which must be a string, contains extra options
passed to the underlying qhull command.  See the documentation for the
Qhull library for details.
@seealso{voronoin, delaunay, convhull}
@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
__strip_html_tags__
@c __strip_html_tags__ scripts/help/__strip_html_tags__.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{text}, @var{status}] =} __strip_html_tags__ (@var{html_text})
Undocumented internal function.
@end deftypefn
doc
@c doc scripts/help/doc.m
-*- texinfo -*-
@deftypefn {Command} {} doc @var{function_name}
Display documentation for the function @var{function_name}
directly from an on-line version of
the printed manual, using the GNU Info browser.  If invoked without
any arguments, 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 on-line 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
gen_doc_cache
@c gen_doc_cache scripts/help/gen_doc_cache.m
-*- texinfo -*-
@deftypefn {Function File} {} gen_doc_cache (@var{out_file}, @var{directory})
Generate documentation caches for all functions in a given directory.

A documentation cache is generated for all functions in @var{directory}.
The
resulting cache is saved in the file @var{out_file}.
The cache is used to speed up @code{lookfor}.

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

@seealso{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{retval}, @var{status}] =} get_first_help_sentence (@var{name}, @var{max_len})
Return the first sentence of a function help text.

The function reads the first sentence of the help text of the function
@var{name}.  The first sentence is defined as the text after the function
declaration until either the first period (".") or the first appearance of
two consecutive end-lines ("\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 non-zero, 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 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}
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.

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

The help command can give you information about operators, but not the
comma and semicolons that are used as command separators.  To get help
for those, you must type @kbd{help comma} or @kbd{help semicolon}.
@seealso{doc, lookfor, which}
@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{func}, @var{helpstring}] =} lookfor (@var{str})
@deftypefnx {Function File} {[@var{func}, @var{helpstring}] =} lookfor ('-all', @var{str})
Search for the string @var{str} in all functions found in the current
function search path.  By default, @code{lookfor} searches for @var{str}
in the first sentence of the help string of each function found.  The entire
help text of each function can be searched if the '-all' argument is
supplied.  All searches are case insensitive.

Called with no output arguments, @code{lookfor} prints the list of
matching functions to the terminal.  Otherwise, the output arguments
@var{func} and @var{helpstring} define the matching functions and the
first sentence of each of their help strings.

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 '-all' argument may
be necessary to find related functions that are not a part of Octave.
@seealso{help, doc, which}
@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 a function.  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} {dfns =} type ("@var{name}", @dots{})
Display the definition of each @var{name} that refers to a function.

Normally also displays whether each @var{name} is user-defined or built-in;
the @option{-q} option suppresses this behavior.

If an output argument is requested nothing is displayed.  Instead, a cell
array of strings is returned, where each element corresponds to the
definition 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
__additional_help_message__
@c __additional_help_message__ scripts/help/private/__additional_help_message__.m
-*- texinfo -*-
@deftypefn {Function File} {} __additional_help_message__ ()
Undocumented internal function.
@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{map}, @var{beta})
@deftypefnx {Function File} {@var{map_out} =} brighten (@var{h}, @var{beta})
@deftypefnx {Function File} {@var{map_out} =} brighten (@var{beta})
Darkens or brightens the given 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.

Should the resulting colormap @var{map_out} not be assigned, it will be
written to the current colormap.

The argument @var{beta} should be a scalar between -1 and 1,
where a negative value darkens and a positive value brightens
the colormap.
@seealso{colormap}
@end deftypefn
colormap
@c colormap scripts/image/colormap.m
-*- texinfo -*-
@deftypefn  {Function File} {} colormap (@var{map})
@deftypefnx {Function File} {} colormap ("default")
Set the current colormap.

@code{colormap (@var{map})} sets the current colormap to @var{map}.  The
color map should be an @var{n} row by 3 column matrix.  The columns
contain red, green, and blue intensities respectively.  All entries
should 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.

With no arguments, @code{colormap} returns the current color map.
@seealso{jet}
@end deftypefn
contrast
@c contrast scripts/image/contrast.m
-*- texinfo -*-
@deftypefn {Function File} {} 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 instead.
@seealso{colormap}
@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
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
gmap40
@c gmap40 scripts/image/gmap40.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{map} =} gmap40 ()
@deftypefnx {Function File} {@var{map} =} gmap40 (@var{n})
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
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.
@end deftypefn
gray2ind
@c gray2ind scripts/image/gray2ind.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{img}, @var{map}] =} gray2ind (@var{I}, @var{n})
Convert a gray scale intensity image to an Octave indexed image.
The indexed image will consist of @var{n} different intensity values.  If not
given @var{n} will default to 64.
@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.  It is obtained by linearly
varying the hue through all possible values while keeping constant maximum
saturation and value and is equivalent to
@code{hsv2rgb ([linspace(0,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})
Transform a colormap or image from the HSV space to the RGB space.
@seealso{rgb2hsv}
@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})
Display a matrix as a color image.  The elements of @var{x} are indices
into the current colormap, and the colormap will be scaled so that the
extremes of @var{x} are mapped to the extremes of the colormap.

The axis values corresponding to the matrix elements are specified in
@var{x} and @var{y}.  If you're not using gnuplot 4.2 or later, these
variables are ignored.

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 @code{"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,1)}.
@seealso{imshow, imagesc, colormap}
@end deftypefn
imagesc
@c imagesc scripts/image/imagesc.m
-*- texinfo -*-
@deftypefn  {Function File} {} imagesc (@var{A})
@deftypefnx {Function File} {} imagesc (@var{x}, @var{y}, @var{A})
@deftypefnx {Function File} {} imagesc (@dots{}, @var{limits})
@deftypefnx {Function File} {} imagesc (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} imagesc (@dots{})
Display a scaled version of the matrix @var{A} as a color image.  The
colormap is scaled so that the entries of the matrix occupy the entire
colormap.  If @var{limits} = [@var{lo}, @var{hi}] are given, then that
range is set to the '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{A}.

@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})
Read image information from a file.

@code{imfinfo} returns a structure containing information about the image
stored in the file @var{filename}.  The output structure contains the
following fields.

@table @samp
@item Filename
The full name of the image file.

@item FileSize
Number of bytes of the image on disk

@item FileModDate
Date of last modification to the file.

@item Height
Image height in pixels.

@item Width
Image Width in pixels.

@item BitDepth
Number of bits per channel per pixel.

@item Format
Image format (e.g., @code{"jpeg"}).

@item LongFormat
Long form image format description.

@item XResolution
X resolution of the image.

@item YResolution
Y resolution of the image.

@item TotalColors
Number of unique colors in the image.

@item TileName
Tile name.

@item AnimationDelay
Time in 1/100ths of a second (0 to 65535) which must expire before displaying
the next image in an animated sequence.

@item AnimationIterations
Number of iterations to loop an animation (e.g., Netscape loop extension)
for.

@item ByteOrder
Endian option for formats that support it.  Is either @code{"little-endian"},
@code{"big-endian"}, or @code{"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 Matte
@code{true} if the image has transparency.

@item ModulusDepth
Image modulus depth (minimum number of bits required to support
red/green/blue
components without loss of accuracy).

@item Quality
JPEG/MIFF/PNG compression level.

@item QuantizeColors
Preferred number of colors in the image.

@item ResolutionUnits
Units of image resolution.  Is either @code{"pixels per inch"},
@code{"pixels per centimeter"}, or @code{"undefined"}.

@item ColorType
Image type.  Is either @code{"grayscale"}, @code{"indexed"},
@code{"truecolor"},
or @code{"undefined"}.

@item View
FlashPix viewing parameters.
@end table

@seealso{imread, imwrite}
@end deftypefn
imread
@c imread scripts/image/imread.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{img}, @var{map}, @var{alpha}] =} imread (@var{filename})
Read images from various file formats.

The size and numeric 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}.
The color depth of the image determines the numeric
class of the output: "uint8" or "uint16" for gray
and color, and "logical" for black and white.

@seealso{imwrite, imfinfo}
@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{})
Display the image @var{im}, where @var{im} can be a 2-dimensional
(gray-scale 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 "displayrange"
@var{value1} is the display range as described above.
@end table
@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{fmt})
@deftypefnx {Function File} {} imwrite (@var{img}, @var{filename}, @var{fmt}, @var{p1}, @var{v1}, @dots{})
@deftypefnx {Function File} {} imwrite (@var{img}, @var{map}, @var{filename}, @dots{})
Write images in various file formats.

If @var{fmt} is not supplied, the file extension of @var{filename} is used
to determine the format.

The parameter-value pairs (@var{p1}, @var{v1}, @dots{}) are optional.
Currently the following options are supported for @t{JPEG} images:

@table @samp
@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.
@end table

@strong{Supported Formats}
@multitable @columnfractions .33 .66
@headitem Extension @tab Format
@item bmp @tab Windows Bitmap
@item gif @tab Graphics Interchange Format
@item jpg and jpeg @tab Joint Photographic Experts Group
@item pbm @tab Portable Bitmap
@item pcx @tab
@item pgm @tab Portable Graymap
@item png @tab Portable Network Graphics
@item pnm @tab Portable Anymap
@item ppm @tab Portable Pixmap
@item ras @tab Sun Raster
@item tif and tiff @tab Tagged Image File Format
@item xwd @tab X11 Dump
@end multitable

@strong{Unsupported Formats}
@multitable @columnfractions .33 .66
@headitem Extension @tab Format
@item hdf @tab Hierarchical Data Format V4
@item @nospell{jp2} and jpx @tab Joint Photographic Experts Group 2000
@end multitable

@seealso{imread, imfinfo}
@end deftypefn
ind2gray
@c ind2gray scripts/image/ind2gray.m
-*- texinfo -*-
@deftypefn {Function File} {} ind2gray (@var{x}, @var{map})
Convert an Octave indexed image to a gray scale intensity image.
If @var{map} is omitted, the current colormap is used to determine the
intensities.
@seealso{gray2ind, rgb2ntsc, image, colormap}
@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{R}, @var{R}] =} ind2rgb (@var{x}, @var{map})
Convert an indexed image to red, green, and blue color components.
If the colormap doesn't contain enough colors, pad it with the
last color in the map.
If @var{map} is omitted, the current colormap is used for the conversion.
@seealso{rgb2ind, image, imshow, ind2gray, gray2ind}
@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
ntsc2rgb
@c ntsc2rgb scripts/image/ntsc2rgb.m
-*- texinfo -*-
@deftypefn {Function File} {} ntsc2rgb (@var{yiq})
Transform a colormap or image from NTSC to RGB.
@seealso{rgb2ntsc}
@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.
@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.  It 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})
Transform a colormap or image from the RGB space to the HSV space.

A color in the RGB space consists of the red, green and blue intensities.

In the HSV space each color is represented by their hue, saturation
and value (brightness).  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}
@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 RGB image to an Octave indexed image.
@seealso{ind2rgb, rgb2ntsc}
@end deftypefn
rgb2ntsc
@c rgb2ntsc scripts/image/rgb2ntsc.m
-*- texinfo -*-
@deftypefn {Function File} {} rgb2ntsc (@var{rgb})
Transform a colormap or image from RGB to NTSC.
@seealso{ntsc2rgb}
@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} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@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).
@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{})
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 @code{"-append"} is given, append to the end of the
@var{file}.

In addition, the following keyword value pairs may appear at the end
of the argument list:
@table @asis
@item "append"
Either @samp{"on"} or @samp{"off"}.  See @samp{"-append"} above.

@item "delimiter"
See @var{delim} above.

@item "newline"
The character(s) to use to separate each row.  Three special cases
exist for this option.  @samp{"unix"} is changed into '\n',
@samp{"pc"} is changed into '\r\n', and @samp{"mac"} is changed
into '\r'.  Other values for this option are kept as is.

@item "roffset"
See @var{r} above.

@item "coffset"
See @var{c} above.

@item "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 a file and return it as a string.
@seealso{fread, textread}
@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{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{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 %d
@itemx %f
The word is parsed as a number.

@item %*
The word is skipped.
@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}.

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

The behavior of @code{strread} can be changed via property-value
pairs.  The following properties are recognized:

@table @asis
@item "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 "shell"
Everything from @code{#} characters to the nearest end-line is skipped.

@item "c"
Everything between @code{/*} and @code{*/} is skipped.

@item "c++"
Everything from @code{//} characters to the nearest end-line is skipped.

@item "matlab"
Everything from @code{%} characters to the nearest end-line is skipped.
@end itemize

@item "delimiter"
Any character in @var{value} will be used to split @var{str} into words.

@item "emptyvalue"
Parts of the output where no word is available is filled with @var{value}.
@end table

@seealso{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 (@dots{})
Read data from a text file.

The file associated with @var{fid} 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 one more:
@itemize
@item "headerlines":
@end itemize
The first @var{value} number of lines of @var{str} are skipped.

The optional input, @var{n}, specifes the number of lines to be read from
the file, associated with @var{fid}.

The output, @var{C}, is a cell array whose length is given by the number
of format specifiers.

The second output, @var{position}, provides the position, in characters,
from the beginning 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{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 one more:
@itemize
@item "headerlines":
@end itemize
The first @var{value} number of lines of @var{str} are skipped.
@seealso{strread, load, dlmread, fscanf}
@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 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.
@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
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
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}.

@example
@group
cross ([1,1,0], [0,1,1])
     @result{} [ 1; -1; 1 ]
@end group
@end example

If @var{x} and @var{y} are matrices, the cross product is applied
along the first dimension with 3 elements.  The optional argument
@var{dim} forces the cross product to be calculated along
the specified dimension.
@seealso{dot}
@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
@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
@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 Magnus and Neudecker (1988), 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, 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
The Taylor series is @emph{not} the way to compute the matrix
exponential; see 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.
@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(1) < 0,
(I - beta*housv*housv')x = -norm(x)*e(j) if x(1) >= 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 Golub and Van Loan):

@table @var
@item beta
If beta = 0, then no reflection need be applied (zer set to 0)

@item housv
householder vector
@end table
@end deftypefn
isdefinite
@c isdefinite scripts/linear-algebra/isdefinite.m
-*- texinfo -*-
@deftypefn  {Function File} {} isdefinite (@var{x})
@deftypefnx {Function File} {} isdefinite (@var{x}, @var{tol})
Return 1 if @var{x} is symmetric positive definite within the
tolerance specified by @var{tol} or 0 if @var{x} is symmetric
positive semidefinite.  Otherwise, return -1.  If @var{tol}
is omitted, use a tolerance of
@code{100 * eps * norm (@var{x}, "fro")}
@seealso{issymmetric, ishermitian}
@end deftypefn
ishermitian
@c ishermitian scripts/linear-algebra/ishermitian.m
-*- texinfo -*-
@deftypefn  {Function File} {} ishermitian (@var{x})
@deftypefnx {Function File} {} ishermitian (@var{x}, @var{tol})
Return true if @var{x} is Hermitian within the tolerance specified by
@var{tol}.
The default tolerance is zero (uses faster code).
Matrix @var{x} is considered symmetric if
@code{norm (@var{x} - @var{x}', Inf) / norm (@var{x}, Inf) < @var{tol}}.
@seealso{issymmetric, isdefinite}
@end deftypefn
issymmetric
@c issymmetric scripts/linear-algebra/issymmetric.m
-*- texinfo -*-
@deftypefn  {Function File} {} issymmetric (@var{x})
@deftypefnx {Function File} {} issymmetric (@var{x}, @var{tol})
Return true if @var{x} is a symmetric matrix within the tolerance specified
by @var{tol}.  The default tolerance is zero (uses faster code).
Matrix @var{x} is considered symmetric if
@code{norm (@var{x} - @var{x}.', Inf) / norm (@var{x}, Inf) < @var{tol}}.
@seealso{ishermitian, isdefinite}
@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 @code{a*u == u*h+rk*ek'}, in which @code{rk =
a*u(:,k)-u*h(:,k)}, and @code{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: 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
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 argument @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.

@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.  @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}, @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 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
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
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}, @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, returns 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
Moler and Stewart's QZ@tie{}decomposition algorithm.

Algorithm taken from Golub and Van Loan, @cite{Matrix Computations, 2nd
edition}.
@end deftypefn
rank
@c rank scripts/linear-algebra/rank.m
-*- texinfo -*-
@deftypefn {Function File} {} rank (@var{A}, @var{tol})
Compute the rank of @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}.
@end deftypefn
rref
@c rref scripts/linear-algebra/rref.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{r}, @var{k}] =} rref (@var{A}, @var{tol})

Returns the reduced row echelon form of @var{A}.  @var{tol} defaults
to @code{eps * max (size (@var{A})) * norm (@var{A}, inf)}.

Called with two return arguments, @var{k} returns 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}, @code{sum (diag (@var{A}))}.
@end deftypefn
vech
@c vech scripts/linear-algebra/vech.m
-*- texinfo -*-
@deftypefn {Function File} {} vech (@var{x})
Return the vector obtained by eliminating all supradiagonal elements of
the square matrix @var{x} and stacking the result one column above the
other.
@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
bincoeff
@c bincoeff scripts/miscellaneous/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
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} {} bunzip2 (@var{bzfile}, @var{dir})
Unpack the bzip2 archive @var{bzfile} to the directory @var{dir}.  If
@var{dir} is not specified, it defaults to the current directory.
@seealso{unpack, bzip2, tar, untar, gzip, gunzip, zip, unzip}
@end deftypefn
bzip2
@c bzip2 scripts/miscellaneous/bzip2.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{entries} =} bzip2 (@var{files})
@deftypefnx {Function File} {@var{entries} =} bzip2 (@var{files}, @var{outdir})
Compress the list of files specified in @var{files}.
Each file is compressed separately and a new file with a '.bz2' extension
is created.  The original files are not touched.  Existing compressed files
are silently overwritten.If @var{outdir} is defined the compressed versions
of the files are placed in this directory.
@seealso{bunzip2, 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}.
@seealso{int8, uint8, int16, uint16, int32, uint32, int64, uint64, double}
@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., "1.2.3", "0.3",
"0.1.2+", or "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., "1.1" would be
padded to be "1.1.0" when being compared with "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
"=="
equal

@item
"<"
less than

@item
"<="
less than or equal to

@item
">"
greater than

@item
">="
greater than or equal to

@item
"!="
not equal

@item
"~="
not equal
@end itemize

Note that version "1.1-test2" will compare as greater than
"1.1-test10".  Also, since the numeric part is compared first, "a"
compares less than "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} {[@var{c}, @var{maxsize}, @var{endian}] =} computer ()
Print or return a string of the form @var{cpu}-@var{vendor}-@var{os}
that identifies the kind of computer 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

x = computer ()
     @result{} x = "i586-pc-linux-gnu"
@end group
@end example

If two output arguments are requested, also return the maximum number
of elements for an array.

If three output arguments are requested, also return the byte order
of the current system as a character (@code{"B"} for big-endian or
@code{"L"} for little-endian).
@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 file @var{f1} to the new name @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 the force flag 'f' is given then
existing destination files will be overwritten without prompting.

If successful, @var{status} is 1, with @var{msg} and @var{msgid} empty
character strings.  Otherwise, @var{status} is 0, @var{msg} contains a
system-dependent error message, and @var{msgid} contains a unique
message identifier.
@seealso{movefile}
@end deftypefn
debug
@c debug scripts/miscellaneous/debug.m
-*- texinfo -*-
@deftypefn {Function File} {} debug ()
Summary of the debugging commands.  The debugging commands that are
available in Octave are

@table @code
@item keyboard
Force entry into debug mode.

@item dbstop
Add a breakpoint.

@item dbclear
Remove a breakpoint.

@item dbstatus
List all breakpoints.

@item dbcont
Continue execution from the debug prompt.

@item dbstack
Print a backtrace of the execution stack.

@item dbstep
Execute one or more lines and re-enter debug mode

@item dbtype
List the function where execution is currently stopped, enumerating
the lines.

@item dbup
The workspace up the execution stack.

@item dbdown
The workspace down the execution stack.

@item dbquit
Quit debugging mode and return to the main prompt.

@item debug_on_error
Flag whether to enter debug mode in case Octave encounters an error.

@item debug_on_warning
Flag whether to enter debug mode in case Octave encounters a warning.

@item debug_on_interrupt
Flag whether to enter debug mode in case Octave encounters an interupt.

@end table

@noindent
when Octave encounters a breakpoint or other reason to enter debug
mode, the prompt changes to @code{"debug>"}.  The workspace of the function
where the breakpoint was encountered becomes available and any Octave
command that works within that workspace may be executed.

@seealso{dbstop, dbclear, dbstatus, dbcont, dbstack, dbstep, dbtype,
dbup, dbdown, dbquit, debug_on_error, debug_on_warning,
debug_on_interrupt}
@end deftypefn
delete
@c delete scripts/miscellaneous/delete.m
-*- texinfo -*-
@deftypefn  {Function File} {} delete (@var{file})
@deftypefnx {Function File} {} delete (@var{handle})
Delete the named file or graphics handle.

Deleting graphics objects is the proper way to remove
features from a plot without clearing the entire figure.
@seealso{clf, cla}
@end deftypefn
dir
@c dir scripts/miscellaneous/dir.m
-*- texinfo -*-
@deftypefn  {Function File} {} dir (@var{directory})
@deftypefnx {Function File} {[@var{list}] =} dir (@var{directory})
Display file listing for directory @var{directory}.  If a return
value is requested, return a structure array with the fields

@example
@group
name
bytes
date
isdir
statinfo
@end group
@end example

@noindent
in which @code{statinfo} is the structure returned from @code{stat}.

If @var{directory} is not a directory, return information about the
named @var{filename}.  @var{directory} may be a list of directories
specified either by name or with wildcard characters (like * and ?)
which will be expanded with glob.

Note that for symbolic links, @code{dir} returns information about
the file that a symbolic link points to instead of the link itself.
However, if the link points to a nonexistent file, @code{dir} returns
information about the link.
@seealso{ls, stat, lstat, readdir, glob, filesep}
@end deftypefn
dos
@c dos scripts/miscellaneous/dos.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{status}, @var{text}] =} dos (@var{command})
@deftypefnx {Function File} {[@var{status}, @var{text}] =} dos (@var{command}, "-echo")
Execute a system command if running under a Windows-like operating
system, otherwise do nothing.  Return the exit status of the program
in @var{status} and any output sent to the standard output in
@var{text}.  If the optional second argument @code{"-echo"} is given,
then also send the output from the command to the standard output.
@seealso{unix, isunix, ispc, system}
@end deftypefn
dump_prefs
@c dump_prefs scripts/miscellaneous/dump_prefs.m
-*- texinfo -*-
@deftypefn {Function File} {} dump_prefs (@var{file})
Have Octave dump all the current user preference variables to
@var{file} in a format that can be parsed by Octave later.  If
@var{file} is omitted, the listing is printed to stdout.
@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 a text 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 further down) and then edited.
If no file is found, then the m-file
variant, ending with ".m", will be considered.  If still no file
is found, then variants with a leading "@@" and then with both a
leading "@@" and trailing ".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{name.cc} is specified, then it will search for @code{name.cc}
in the path and try to modify it, otherwise it will create a new
@file{.cc} file in @env{HOME}.  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 @var{name.ext} is on your path then it will be edited, otherwise
the editor will be started with @file{HOME/name.ext} as the
filename.  If @file{name.ext} is not modifiable, it will be copied to
@env{HOME} before editing.

@strong{WARNING!} You may need to clear name before the new definition
is available.  If you are editing a .cc file, you will need
to mkoctfile @file{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 @var{value}.
If an output argument is requested and the first 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 editor
This is the editor to use to modify the functions.  By default it uses
Octave's @env{EDITOR} built-in function, which comes from
@code{getenv("EDITOR")} and defaults to @code{emacs}.  Use @code{%s}
In place of the function name.  For example,
@table @samp
@item [EDITOR, " %s"]
Use the editor which Octave uses for @code{bug_report}.

@item "xedit %s &"
pop up simple X11 editor in a separate window

@item "gnudoit -q \"(find-file \\\"%s\\\")\""
Send it to current Emacs; must have @code{(gnuserv-start)} in @file{.emacs}.
@end table

See also field 'mode', which controls how the editor is run by Octave.

On Cygwin, you will need to convert the Cygwin path to a Windows
path if you are using a native Windows editor.  For example:
@c Set example in small font to prevent overfull line in TeX

@smallexample
@exdent '"C:/Program Files/Good Editor/Editor.exe" "$(cygpath -wa %s)"'
@end smallexample

@item home
This is the location of user local m-files.  Be 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 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 @code{<user@@host>} as your format.

@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 "async" to start the editor
in async mode.  The default is "sync" (see also "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
fileattrib
@c fileattrib scripts/miscellaneous/fileattrib.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{status}, @var{msg}, @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}, @var{ver}] =} fileparts (@var{filename})
Return the directory, name, extension, and version components of
@var{filename}.
@seealso{fullfile}
@end deftypefn
fullfile
@c fullfile scripts/miscellaneous/fullfile.m
-*- texinfo -*-
@deftypefn {Function File} {@var{filename} =} fullfile (@var{dir1}, @var{dir2}, @dots{}, @var{file})
Return a complete filename constructed from the given components.
@seealso{fileparts}
@end deftypefn
getappdata
@c getappdata scripts/miscellaneous/getappdata.m
-*- texinfo -*-
@deftypefn {Function File} {@var{value} =} getappdata (@var{h}, @var{name})
Returns the @var{value} for named application data for the object(s) with
handle(s) @var{h}.
@end deftypefn
getfield
@c getfield scripts/miscellaneous/getfield.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{v1}, @dots{}] =} getfield (@var{s}, @var{key}, @dots{})
Extract a field from a structure (or a nested structure).  For example:

@example
@group
ss(1,2).fd(3).b = 5;
getfield (ss, @{1,2@}, "fd", @{3@}, "b")
     @result{} ans = 5
@end group
@end example

Note that the function call in the previous example is equivalent to
the expression

@example
@group
i1 = @{1,2@}; i2 = "fd"; i3 = @{3@}; i4= "b";
ss(i1@{:@}).(i2)(i3@{:@}).(i4)
     @result{} ans = 5

@end group
@end example
@seealso{setfield, rmfield, isfield, isstruct, fieldnames, struct}
@end deftypefn
gunzip
@c gunzip scripts/miscellaneous/gunzip.m
-*- texinfo -*-
@deftypefn {Function File} {} gunzip (@var{gzfile}, @var{dir})
Unpack the gzip archive @var{gzfile} to the directory @var{dir}.  If
@var{dir} is not specified, it defaults to the current directory.  If
the @var{gzfile} is a directory, all gzfile in the directory will be
recursively gunzipped.
@seealso{unpack, bunzip2, tar, untar, gzip, gunzip, zip, unzip}
@end deftypefn
gzip
@c gzip scripts/miscellaneous/gzip.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{entries} =} gzip (@var{files})
@deftypefnx {Function File} {@var{entries} =} gzip (@var{files}, @var{outdir})
Compress the list of files and/or directories specified in @var{files}.
Each file is compressed separately and a new file with a '.gz' extension
is created.  The original files are not touched.  Existing compressed
files are silently overwritten.  If @var{outdir} is defined the compressed
versions of the files are placed in this directory.
@seealso{gunzip, 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.
@end deftypefn
isappdata
@c isappdata scripts/miscellaneous/isappdata.m
-*- texinfo -*-
@deftypefn {Function File} {@var{V} =} isappdata (@var{h}, @var{name})
Return true if the named application data, @var{name}, exists for the
object with handle @var{h}.
@seealso{getappdata, setappdata, rmappdata}
@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 {Function File} {} license
Display the license of Octave.

@deftypefnx {Function File} {} license ("inuse")
Display a list of packages currently being used.

@deftypefnx {Function File} {@var{retval} =} license ("inuse")
Return a structure containing the fields @code{feature} and @code{user}.

@deftypefnx {Function File} {@var{retval} =} license ("test", @var{feature})
Return 1 if a license exists for the product identified by the string
@var{feature} and 0 otherwise.  The argument @var{feature} is case
insensitive and only the first 27 characters are checked.

@deftypefnx {Function File} {} license ("test", @var{feature}, @var{toggle})
Enable or disable license testing for @var{feature}, depending on
@var{toggle}, which may be one of:

@table @asis
@item "enable"
Future tests for the specified license of @var{feature} are conducted
as usual.

@item "disable"
Future tests for the specified license of @var{feature} return 0.
@end table

@deftypefnx {Function File} {@var{retval} =} license ("checkout", @var{feature})
Check out a license for @var{feature}, returning 1 on success and 0
on failure.

This function is provided for compatibility with @sc{matlab}.
@seealso{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.

The algorithm used is from page 218 of the @TeX{}book.
@seealso{primes, isprime}
@end deftypefn
ls
@c ls scripts/miscellaneous/ls.m
-*- texinfo -*-
@deftypefn {Command} {} ls options
List directory contents.  For example:

@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

The @code{dir} and @code{ls} commands are implemented by calling your
system's directory listing command, so the available options may vary
from system to system.
@seealso{dir, stat, readdir, glob, filesep, ls_command}
@end deftypefn
ls_command
@c ls_command scripts/miscellaneous/ls_command.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{old_cmd} =} ls_command (@var{cmd})
Set or return the shell command used by Octave's @code{ls} command.
The value of @var{cmd} must be a character string.
With no arguments, simply return the previous value.
@seealso{ls}
@end deftypefn
menu
@c menu scripts/miscellaneous/menu.m
-*- texinfo -*-
@deftypefn {Function File} {} menu (@var{title}, @var{opt1}, @dots{})
Print a title string followed by a series of options.  Each option will
be printed along with a number.  The return value is the number of the
option selected by the user.  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{disp, printf, input}
@end deftypefn
mex
@c mex scripts/miscellaneous/mex.m
-*- texinfo -*-
@deftypefn {Function File} {} 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}
@end deftypefn
mexext
@c mexext scripts/miscellaneous/mexext.m
-*- texinfo -*-
@deftypefn {Function File} {} mexext ()
Return the filename extension used for MEX files.
@end deftypefn
mkoctfile
@c mkoctfile scripts/miscellaneous/mkoctfile.m
-*- texinfo -*-
@deftypefn {Command} {} mkoctfile [-options] file @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.

@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 -Wl,@dots{}
Pass flags though the linker like "-Wl,-rpath=@dots{}".
The quotes are needed since commas are interpreted as command
separators.

@item -W@dots{}
Pass flags though the compiler like "-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                FFTW_LIBS
   ALL_CXXFLAGS              FLIBS
   ALL_FFLAGS                FPICFLAG
   ALL_LDFLAGS               INCFLAGS
   BLAS_LIBS                 LDFLAGS
   CC                        LD_CXX
   CFLAGS                    LD_STATIC_FLAG
   CPICFLAG                  LFLAGS
   CPPFLAGS                  LIBCRUFT
   CXX                       LIBOCTAVE
   CXXFLAGS                  LIBOCTINTERP
   CXXPICFLAG                LIBREADLINE
   DEPEND_EXTRA_SED_PATTERN  LIBS
   DEPEND_FLAGS              OCTAVE_LIBS
   DL_LD                     RDYNAMIC_FLAG
   DL_LDFLAGS                RLD_FLAG
   F2C                       SED
   F2CFLAGS                  XTRA_CFLAGS
   F77                       XTRA_CXXFLAGS
   FFLAGS
@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} {[@var{status}, @var{msg}, @var{msgid}] =} movefile (@var{f1}, @var{f2})
@deftypefnx {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} movefile (@var{f1}, @var{f2}, 'f')
Move the file @var{f1} to the new name @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 the force flag 'f' is given
then any existing files will be overwritten without prompting.

If successful, @var{status} is 1, with @var{msg} and @var{msgid} empty
character strings.  Otherwise, @var{status} is 0, @var{msg} contains a
system-dependent error message, and @var{msgid} contains a unique
message identifier.
@seealso{rename, copyfile}
@end deftypefn
namelengthmax
@c namelengthmax scripts/miscellaneous/namelengthmax.m
-*- texinfo -*-
@deftypefn {Function File} {} namelengthmax ()
Returns the @sc{matlab} compatible maximum variable name length.  Octave is
capable of storing strings up to
@tex
$2^{31} - 1$
@end tex
@ifnottex
@code{2 ^ 31 - 1}
@end ifnottex
in length.  However for @sc{matlab} compatibility all variable, function
and structure field names should be shorter than the length supplied by
@code{namelengthmax}.  In particular variables stored to a @sc{matlab} file
format will have their names truncated to this length.
@end deftypefn
news
@c news scripts/miscellaneous/news.m
-*- texinfo -*-
@deftypefn {Function File} {} news ()
Display the current NEWS file for Octave.
@end deftypefn
orderfields
@c orderfields scripts/miscellaneous/orderfields.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{t}, @var{p}] =} orderfields (@var{s1})
@deftypefnx {Function File} {[@var{t}, @var{p}] =} orderfields (@var{s1}, @var{s2})
Return a copy of @var{s1} with fields arranged alphabetically or
as specified by @var{s2}.

Given one struct, arrange field names in @var{s1} alphabetically.

If the second argument is a struct, arrange field names in @var{s1}
as they appear in @var{s2}.  The second argument may also specify the
order in a permutation vector or a cell array of strings containing
the fieldnames of @var{s1} in the desired order.

The optional second output argument @var{p} is assigned the permutation
vector
which converts the original name order into 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{getfield, rmfield, isfield, isstruct, fieldnames, struct}
@end deftypefn
pack
@c pack scripts/miscellaneous/pack.m
-*- texinfo -*-
@deftypefn {Function File} {} pack ()
This function is provided for compatibility with @sc{matlab}, but it
doesn't actually do anything.
@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'
arguments and 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 a m-file function, the error is prefixed with the
name of the caller function.
The matching of options is case-insensitive.

@seealso{varargin}
@end deftypefn
perl
@c perl scripts/miscellaneous/perl.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{output}, @var{status}] =} perl (@var{scriptfile})
@deftypefnx {Function File} {[@var{output}, @var{status}] =} perl (@var{scriptfile}, @var{argument1}, @var{argument2}, @dots{})
Invoke Perl script @var{scriptfile} with possibly a list of
command line arguments.
Returns output in @var{output} and status
in @var{status}.
@seealso{system}
@end deftypefn
rmappdata
@c rmappdata scripts/miscellaneous/rmappdata.m
-*- texinfo -*-
@deftypefn {Function File} {} rmappdata (@var{h}, @var{name})
Deletes the named application data for the object(s) with
handle(s) @var{h}.
@end deftypefn
run
@c run scripts/miscellaneous/run.m
-*- texinfo -*-
@deftypefn  {Command} {} run @var{script}
@deftypefnx {Function File} {} run (@var{script})
Run scripts in the current workspace that are not necessarily on the
path.  If @var{script} is the script to run, including its path, then
@code{run} changes the directory to the directory where @var{script} is
found.  @code{run} then executes the script, and returns to the original
directory.
@seealso{system}
@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})
Sets the named application data to @var{value} for the object(s) with
handle(s) @var{h}.  If the application data with the specified name does
not exist, it is created.
@end deftypefn
setfield
@c setfield scripts/miscellaneous/setfield.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{k1}, @dots{}, @var{v1}] =} setfield (@var{s}, @var{k1}, @var{v1}, @dots{})
Set a field member in a (nested) structure array.  For example:

@example
@group
oo(1,1).f0 = 1;
oo = setfield (oo, @{1,2@}, "fd", @{3@}, "b", 6);
oo(1,2).fd(3).b == 6
     @result{} ans = 1
@end group
@end example

Note that the same result as in the above example could be achieved by:

@example
@group
i1 = @{1,2@}; i2 = "fd"; i3 = @{3@}; i4 = "b";
oo(i1@{:@}).(i2)(i3@{:@}).(i4) == 6
     @result{} ans = 1
@end group
@end example
@seealso{getfield, rmfield, isfield, isstruct, fieldnames, 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{} ans =
        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})
Swaps 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} {} symvar (@var{s})
Identifies the argument names in the function defined by a string.
Common constant names such as @code{pi}, @code{NaN}, @code{Inf},
@code{eps}, @code{i} or @code{j} are ignored.  The arguments that are
found are returned in a cell array of strings.  If no variables are
found then the returned cell array is empty.
@end deftypefn
tar
@c tar scripts/miscellaneous/tar.m
-*- texinfo -*-
@deftypefn {Function File} {@var{entries} =} tar (@var{tarfile}, @var{files}, @var{root})
Pack @var{files} @var{files} into the TAR archive @var{tarfile}.  The
list of files must be a string or a cell array of strings.

The optional argument @var{root} changes the relative path of @var{files}
from the current directory.

If an output argument is requested the entries in the archive are
returned in a cell array.
@seealso{untar, gzip, gunzip, zip, unzip}
@end deftypefn
tempdir
@c tempdir scripts/miscellaneous/tempdir.m
-*- texinfo -*-
@deftypefn {Function File} {@var{dir} =} tempdir ()
Return the name of the system's directory for temporary files.
@end deftypefn
tempname
@c tempname scripts/miscellaneous/tempname.m
-*- texinfo -*-
@deftypefn  {Function File} {} tempname ()
@deftypefnx {Function File} {} tempname (@var{dir})
@deftypefnx {Function File} {} tempname (@var{dir}, @var{prefix})
This function is an alias for @code{tmpnam}.
@seealso{tmpnam}
@end deftypefn
unimplemented
@c unimplemented scripts/miscellaneous/unimplemented.m
-*- texinfo -*-
@deftypefn {Function File} {} unimplemented ()
Undocumented internal function.
@end deftypefn
unix
@c unix scripts/miscellaneous/unix.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{status}, @var{text}] =} unix (@var{command})
@deftypefnx {Function File} {[@var{status}, @var{text}] =} unix (@var{command}, "-echo")
Execute a system command if running under a Unix-like operating
system, otherwise do nothing.  Return the exit status of the program
in @var{status} and any output sent to the standard output in
@var{text}.  If the optional second argument @code{"-echo"} is given,
then also send the output from the command to the standard output.
@seealso{isunix, ispc, system}
@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 cellstr, then all files will be
handled individually.  If @var{dir} is not specified, it defaults to
the current directory.  It returns a list of @var{files}
unpacked.  If a directory is in the file list, then the
@var{filetype} to unpack must also be specified.

The @var{files} includes the entire path to the output files.
@seealso{bunzip2, tar, untar, gzip, gunzip, zip, unzip}
@end deftypefn
untar
@c untar scripts/miscellaneous/untar.m
-*- texinfo -*-
@deftypefn {Function File} {} untar (@var{tarfile}, @var{dir})
Unpack the TAR archive @var{tarfile} to the directory @var{dir}.
If @var{dir} is not specified, it defaults to the current directory.
@seealso{unpack, bunzip2, tar, gzip, gunzip, zip, unzip}
@end deftypefn
unzip
@c unzip scripts/miscellaneous/unzip.m
-*- texinfo -*-
@deftypefn  {Function File} {} unzip (@var{zipfile})
@deftypefnx {Function File} {} unzip (@var{zipfile}, @var{dir})
Unpack the ZIP archive @var{zipfile} to the directory @var{dir}.
If @var{dir} is not specified, it defaults to the current directory.
@seealso{unpack, bunzip2, tar, untar, gzip, gunzip, zip}
@end deftypefn
ver
@c ver scripts/miscellaneous/ver.m
-*- texinfo -*-
@deftypefn {Function File} {} ver ()
Display a header containing the current Octave version number, license
string and operating system, followed by the installed package names,
versions, and installation directories.

@deftypefnx {Function File} {v =} ver ()
Return a vector of structures, respecting 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 respecting the version/revision.
@end table

@deftypefnx {Function File} {v =} ver (@code{"Octave"})
Return version information for Octave only.

@deftypefnx {Function File} {v =} ver (@var{package})
Return version information for @var{package}.

@seealso{version, octave_config_info}
@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 @code{OCTAVE_VERSION} provided for
compatibility
@seealso{OCTAVE_VERSION}.
@end deftypefn
warning_ids
@c warning_ids scripts/miscellaneous/warning_ids.m
-*- texinfo -*-
@table @code
@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: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:empty-list-elements
If the @code{Octave:empty-list-elements} warning is enabled, a
warning is issued when an empty matrix is found in a matrix list.
For example:

@example
a = [1, [], 3, [], 5]
@end example

@noindent
By default, the @code{Octave:empty-list-elements} warning is enabled.

@item Octave:fortran-indexing
If the @code{Octave:fortran-indexing} warning is enabled, a warning is
printed for expressions which select elements of a two-dimensional matrix
using a single index.  By default, the @code{Octave:fortran-indexing}
warning is disabled.

@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: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:matlab-incompatible
Print warnings for Octave language features that may cause
compatibility problems with @sc{matlab}.

@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: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: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: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: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.

@item Octave:single-quote-string
Print warning if a single quote character is used to introduce a
string constant.

@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:string-concat
If the @code{Octave:string-concat} warning is enabled, print a
warning when concatenating a mixture of double and single quoted strings.
By default, the @code{Octave:string-concat} 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 a directory.  If the variable @var{dir}
is given then check that directory rather than the current directory.  If
a return argument is requested, the files found are returned in the
structure @var{w}.
@seealso{which}
@end deftypefn
xor
@c xor scripts/miscellaneous/xor.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} xor (@var{x}, @var{y})
Return the `exclusive or' of the entries 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 @var{x} or @var{y}
is true, but not if both @var{x} and @var{y} are true.
@end deftypefn
zip
@c zip scripts/miscellaneous/zip.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{entries} =} zip (@var{zipfile}, @var{files})
@deftypefnx {Function File} {@var{entries} =} zip (@var{zipfile}, @var{files}, @var{rootdir})
Compress the list of files and/or directories specified in @var{files}
into the archive @var{zipfiles} in the same directory.  If @var{rootdir}
is defined the @var{files} is located relative to @var{rootdir} rather
than the current directory
@seealso{unzip,tar}
@end deftypefn
__xzip__
@c __xzip__ scripts/miscellaneous/private/__xzip__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{entries} =} __xzip__ (@var{commandname}, @var{extension}, @var{commandtemplate}, @var{files}, @var{outdir})
Undocumented internal function.
@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: @code{"FunValCheck"}, @code{"OutputFcn"},
@code{"TolX"}, @code{"MaxIter"}, @code{"MaxFunEvals"}.
For description of these options, see @ref{doc-optimset,,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
@seealso{optimset, fzero, fminunc}
@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{fvec}, @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 accepts a vector (array) defining the unknown variables,
and return the objective function value, optionally with gradient.
In other words, this function 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:
@code{"FunValCheck"}, @code{"OutputFcn"}, @code{"TolX"},
@code{"TolFun"}, @code{"MaxIter"}, @code{"MaxFunEvals"},
@code{"GradObj"}, @code{"FinDiffType"},
@code{"TypicalX"}, @code{"AutoScaling"}.

If @code{"GradObj"} is @code{"on"}, it specifies that @var{fcn},
called with 2 output arguments, also returns the Jacobian matrix
of right-hand sides at the requested point.  @code{"TolX"} specifies
the termination tolerance in the unknown variables, while
@code{"TolFun"} is a tolerance for equations.  Default is @code{1e-7}
for both @code{"TolX"} and @code{"TolFun"}.

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}, and @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 TolFun.

@item 2
Last relative step size was less that TolX.

@item 3
Last relative decrease in func value was less than TolF.

@item 0
Iteration limit exceeded.

@item -3
The trust region radius became excessively small.
@end table

Optionally, fminunc can also yield a structure with convergence statistics
(@var{output}), the output gradient (@var{grad}) and approximate Hessian
(@var{hess}).

Note: If you only have a single nonlinear equation of one variable, using
@code{fminbnd} is usually a much better idea.
@seealso{fminbnd, 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:
@code{"FunValCheck"}, @code{"OutputFcn"}, @code{"TolX"},
@code{"TolFun"}, @code{"MaxIter"}, @code{"MaxFunEvals"},
@code{"Jacobian"}, @code{"Updating"}, @code{"ComplexEqn"}
@code{"TypicalX"}, @code{"AutoScaling"} and @code{"FinDiffType"}.

If @code{"Jacobian"} is @code{"on"}, it specifies that @var{fcn},
called with 2 output arguments, also returns the Jacobian matrix
of right-hand sides at the requested point.  @code{"TolX"} specifies
the termination tolerance in the unknown variables, while
@code{"TolFun"} is a tolerance for equations.  Default is @code{1e-7}
for both @code{"TolX"} and @code{"TolFun"}.

If @code{"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 @code{"Updating"} is "on", the function will attempt to use 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), this option provides no advantage and should be set to
false.

@code{"ComplexEqn"} is @code{"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,
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}, and @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.
@seealso{fzero, optimset}

Note about user-supplied Jacobians:
As an inherent property of the algorithm, 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
@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} should be a function handle or name.  @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: @code{"FunValCheck"}, @code{"OutputFcn"},
@code{"TolX"}, @code{"MaxIter"}, @code{"MaxFunEvals"}.
For a description of these options, see @ref{doc-optimset,,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{status}, @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 "F"
A free (unbounded) constraint (the constraint is ignored).

@item "U"
An inequality constraint with an upper bound (@code{A(i,:)*x <= b(i)}).

@item "S"
An equality constraint (@code{A(i,:)*x = b(i)}).

@item "L"
An inequality with a lower bound (@code{A(i,:)*x >= b(i)}).

@item "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 "C"
A continuous variable.

@item "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 (@w{@code{LPX_K_MSGLEV}}, default: 1)
Level of messages output by solver routines:
@table @asis
@item 0
No output.

@item 1
Error messages only.

@item 2
Normal output.

@item 3
Full output (includes informational messages).
@end table

@item scale (@w{@code{LPX_K_SCALE}}, default: 1)
Scaling option:
@table @asis
@item 0
No scaling.

@item 1
Equilibration scaling.

@item 2
Geometric mean scaling, then equilibration scaling.
@end table

@item dual    (@w{@code{LPX_K_DUAL}}, default: 0)
Dual simplex option:
@table @asis
@item 0
Do not use the dual simplex.

@item 1
If initial basic solution is dual feasible, use the dual simplex.
@end table

@item price   (@w{@code{LPX_K_PRICE}}, default: 1)
Pricing option (for both primal and dual simplex):
@table @asis
@item 0
Textbook pricing.

@item 1
Steepest edge pricing.
@end table

@item round   (@w{@code{LPX_K_ROUND}}, default: 0)
Solution rounding option:
@table @asis
@item 0
Report all primal and dual values "as is".

@item 1
Replace tiny primal and dual values by exact zero.
@end table

@item itlim   (@w{@code{LPX_K_ITLIM}}, default: -1)
Simplex iterations limit.  If this value is positive, 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.  Negative
value means no iterations limit.

@item itcnt (@w{@code{LPX_K_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 (@w{@code{LPX_K_BRANCH}}, default: 2)
Branching heuristic option (for MIP only):
@table @asis
@item 0
Branch on the first variable.

@item 1
Branch on the last variable.

@item 2
Branch using a heuristic by Driebeck and Tomlin.
@end table

@item btrack (@w{@code{LPX_K_BTRACK}}, default: 2)
Backtracking heuristic option (for MIP only):
@table @asis
@item 0
Depth first search.

@item 1
Breadth first search.

@item 2
Backtrack using the best projection heuristic.
@end table

@item presol (@w{@code{LPX_K_PRESOL}}, default: 1)
If this flag is set, the routine lpx_simplex solves the problem using
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 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 relax (@w{@code{LPX_K_RELAX}}, default: 0.07)
Relaxation parameter used in the ratio test.  If it is zero, the textbook
ratio test is used.  If it is non-zero (should be positive), Harris'
two-pass ratio test is used.  In the latter case on the first pass of the
ratio test basic variables (in the case of primal simplex) or reduced
costs of non-basic variables (in the case of dual simplex) are allowed
to slightly violate their bounds, but not more than
@code{relax*tolbnd} or @code{relax*toldj (thus, @code{relax} is a
percentage of @code{tolbnd} or @code{toldj}}.

@item tolbnd (@w{@code{LPX_K_TOLBND}}, default: 10e-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 (@w{@code{LPX_K_TOLDJ}}, default: 10e-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 (@w{@code{LPX_K_TOLPIV}}, default: 10e-9)
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 (@w{@code{LPX_K_OBJLL}}, default: -DBL_MAX)
Lower limit of the objective function.  If on the phase II 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 (@w{@code{LPX_K_OBJUL}}, default: +DBL_MAX)
Upper limit of the objective function.  If on the phase II the objective
function reaches this limit and continues increasing, the solver stops
the search.  This parameter is used in the dual simplex only.

@item tmlim (@w{@code{LPX_K_TMLIM}}, default: -1.0)
Searching time limit, in seconds.  If this value is positive, it is
decreased each time when one simplex iteration has been performed by the
amount of time spent for the iteration, and reaching zero value signals
the solver to stop the search.  Negative value means no time limit.

@item outdly (@w{@code{LPX_K_OUTDLY}}, default: 0.0)
Output delay, in seconds.  This parameter specifies how long the solver
should delay sending information about the solution to the standard
output.  Non-positive value means no delay.

@item tolint (@w{@code{LPX_K_TOLINT}}, default: 10e-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 (@w{@code{LPX_K_TOLOBJ}}, default: 10e-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 status
Status of the optimization.

Simplex Method:
@table @asis
@item 180 (@w{@code{LPX_OPT}})
Solution is optimal.
@item 181 (@w{@code{LPX_FEAS}})
Solution is feasible.
@item 182 (@w{@code{LPX_INFEAS}})
Solution is infeasible.
@item 183 (@w{@code{LPX_NOFEAS}})
Problem has no feasible solution.
@item 184 (@w{@code{LPX_UNBND}})
Problem has no unbounded solution.
@item 185 (@w{@code{LPX_UNDEF}})
Solution status is undefined.
@end table
Interior Point Method:
@table @asis
@item 150 (@w{@code{LPX_T_UNDEF}})
The interior point method is undefined.
@item 151 (@w{@code{LPX_T_OPT}})
The interior point method is optimal.
@end table
Mixed Integer Method:
@table @asis
@item 170 (@w{@code{LPX_I_UNDEF}})
The status is undefined.
@item 171 (@w{@code{LPX_I_OPT}})
The solution is integer optimal.
@item 172 (@w{@code{LPX_I_FEAS}})
Solution integer feasible but its optimality has not been proven
@item 173 (@w{@code{LPX_I_NOFEAS}})
No integer feasible solution.
@end table
@noindent
If an error occurs, @var{status} will contain one of the following
codes:

@table @asis
@item 204 (@w{@code{LPX_E_FAULT}})
Unable to start the search.
@item 205 (@w{@code{LPX_E_OBJLL}})
Objective function lower limit reached.
@item 206 (@w{@code{LPX_E_OBJUL}})
Objective function upper limit reached.
@item 207 (@w{@code{LPX_E_ITLIM}})
Iterations limit exhausted.
@item 208 (@w{@code{LPX_E_TMLIM}})
Time limit exhausted.
@item 209 (@w{@code{LPX_E_NOFEAS}})
No feasible solution.
@item 210 (@w{@code{LPX_E_INSTAB}})
Numerical instability.
@item 211 (@w{@code{LPX_E_SING}})
Problems with basis matrix.
@item 212 (@w{@code{LPX_E_NOCONV}})
No convergence (interior).
@item 213 (@w{@code{LPX_E_NOPFS}})
No primal feasible solution (LP presolver).
@item 214 (@w{@code{LPX_E_NODFS}})
No dual feasible solution (LP presolver).
@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 mem
Memory (in bytes) used for solving LP/MIP problem (this is not
available if the version of @sc{glpk} is 4.15 or later).
@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}, @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}.

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 "algorithm": The algorithm used ("nnls")

@item "iterations": The number of iterations taken.
@end itemize

@item lambda

Not implemented.
@end itemize
@seealso{optimset, pqpnonneg}
@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 a specific option from a structure created by
@code{optimset}.  If @var{parname} is not a field of the @var{options}
structure, return @var{default} if supplied, otherwise return an
empty matrix.
@end deftypefn
optimset
@c optimset scripts/optimization/optimset.m
-*- texinfo -*-
@deftypefn  {Function File} {} optimset ()
@deftypefnx {Function File} {} optimset (@var{par}, @var{val}, @dots{})
@deftypefnx {Function File} {} optimset (@var{old}, @var{par}, @var{val}, @dots{})
@deftypefnx {Function File} {} optimset (@var{old}, @var{new})
Create options struct for optimization functions.
@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 "algorithm": The algorithm used ("nnls")

@item "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 the quadratic program
@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{tolerance})
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.  The objective function must be of the form

@example
     @var{y} = phi (@var{x})
@end example

@noindent
in which @var{x} is a vector and @var{y} is 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 must be of the form

@example
@var{g} = gradient (@var{x})
@end example

@noindent
in which @var{x} is a vector and @var{g} is a vector.

When supplied, the Hessian function must be of the form

@example
@var{h} = hessian (@var{x})
@end example

@noindent
in which @var{x} is a vector and @var{h} is a matrix.

The third and fourth arguments 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{cef} (or @var{cif}).

When supplied, the equality and inequality constraint functions must be
of the form

@example
@var{r} = f (@var{x})
@end example

@noindent
in which @var{x} is a vector and @var{r} is 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 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 specifies the maximum number of iterations.
The default value is 100.

The eighth argument 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.
Either all constraints meet the requested tolerance, or the stepsize,
@tex
$\Delta x,$
@end tex
@ifnottex
delta @var{x},
@end ifnottex
is less than @code{tol * norm (x)}.

@item 102
The BFGS update failed.

@item 103
The maximum number of iterations was reached.
@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
__fdjac__
@c __fdjac__ scripts/optimization/private/__fdjac__.m
-*- texinfo -*-
@deftypefn {Function File} {} __fdjac__ (@var{fcn}, @var{x}, @var{fvec}, @var{err})
Undocumented internal function.
@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 @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 three sources.
In order of preference, those are;

@enumerate
@item @file{~/.octaverc}

@item @file{<octave-home>/@dots{}/<version>/m/startup/octaverc}

@item Octave's path prior to changes by any octaverc.
@end enumerate
@seealso{path, addpath, rmpath, genpath, savepath, pathsep}
@end deftypefn
savepath
@c savepath scripts/path/savepath.m
-*- texinfo -*-
@deftypefn {Function File} {} savepath (@var{file})
Save the portion of the current function search path, that is
not set during Octave's initialization process, to @var{file}.
If @var{file} is omitted, @file{~/.octaverc} is used.  If successful,
@code{savepath} returns 0.
@seealso{path, addpath, rmpath, genpath, pathdef, pathsep}
@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}
This command interacts with the package manager.  Different actions will
be taken depending on the value of @var{command}.

@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 the dependency checking.  That way it
is possible to install a package even if it depends on another package
that's 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, even if the package requests that it is.

@item -auto
The package manager will automatically load the installed package when
starting Octave, even if the package requests that it isn't.

@item -local
A local installation is forced, even if the user has system privileges.

@item -global
A global installation is forced, even if the user doesn't normally have
system privileges

@item -verbose
The package manager will print the output of all of the commands that are
performed.
@end table

@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 command

@example
pkg load all
@end example

@item unload
Removes named packages from the path.  After unloading a package it is
no longer possible to use the functions provided by the package.
This command behaves like the @code{load} command.

@item list
Show a list of the currently installed packages.  By requesting one or two
output argument it is possible to get a list of the currently installed
packages.  For example,

@example
installed_packages = pkg list;
@end example

@noindent
returns a cell array containing a structure for each installed package.
The command

@example
[@var{user_packages}, @var{system_packages}] = pkg list
@end example

@noindent
splits the list of installed packages into those who are installed by
the current user, and those installed by the system administrator.

@item describe
Show a short description of the named installed packages, with the option
'-verbose' also list functions provided by the package, e.g.:

@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, 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 "Not installed", "Loaded" or
"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
p = pkg prefix
@end example

The location in which to install the architecture dependent files can be
independent 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 the locally
installed packages.  Locally installed packages are those that are
typically 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, for information on the globally
installed packages.  Globally installed packages are those that are
typically 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 rebuild
Rebuilds the package database from the installed directories.  This can
be used in cases where for some reason the package database is 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.

@item build
Builds 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
the other options are ignored.
@end table
@end deftypefn
get_forge_pkg
@c get_forge_pkg scripts/pkg/get_forge_pkg.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{ver}, @var{url}] =} get_forge_pkg (@var{name})
Tries to discover the current version of an OctaveForge package from the web,
using a working internet connection and the urlread function.
If two output arguments are requested, returns also an address to download
the file.
@end deftypefn
__fltk_ginput__
@c __fltk_ginput__ scripts/plot/__fltk_ginput__.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{y}, @var{buttons}] =} __fltk_ginput__ (@var{f}, @var{n})
Undocumented internal function.
@end deftypefn
__fltk_print__
@c __fltk_print__ scripts/plot/__fltk_print__.m
-*- texinfo -*-
@deftypefn {Function File} {} __fltk_print__ (@var{@dots{}})
Undocumented internal function.
@end deftypefn
__gnuplot_drawnow__
@c __gnuplot_drawnow__ scripts/plot/__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
__gnuplot_get_var__
@c __gnuplot_get_var__ scripts/plot/__gnuplot_get_var__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{value} =} __gnuplot_get_var__ (@var{h}, @var{name}, @var{fmt})
Undocumented internal function.
@end deftypefn
__gnuplot_ginput__
@c __gnuplot_ginput__ scripts/plot/__gnuplot_ginput__.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{y}, @var{buttons}] =} __gnuplot_ginput__ (@var{f}, @var{n})
Undocumented internal function.
@end deftypefn
__gnuplot_has_feature__
@c __gnuplot_has_feature__ scripts/plot/__gnuplot_has_feature__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{has_feature} =} __gnuplot_has_feature__ (@var{feature})
Undocumented internal function.
@end deftypefn
__gnuplot_open_stream__
@c __gnuplot_open_stream__ scripts/plot/__gnuplot_open_stream__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{stream} =} __gnuplot_open_stream__ (@var{npipes}, @var{h})
Undocumented internal function.
@end deftypefn
__gnuplot_print__
@c __gnuplot_print__ scripts/plot/__gnuplot_print__.m
-*- texinfo -*-
@deftypefn {Function File} {} __gnuplot_print__ (@var{@dots{}})
Undocumented internal function.
@end deftypefn
__gnuplot_version__
@c __gnuplot_version__ scripts/plot/__gnuplot_version__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{version} =} __gnuplot_version__ ()
Undocumented internal function.
@end deftypefn
__go_close_all__
@c __go_close_all__ scripts/plot/__go_close_all__.m
-*- texinfo -*-
@deftypefn {Function File} {} __go_close_all__ ()
Undocumented internal function.
@end deftypefn
__go_draw_axes__
@c __go_draw_axes__ scripts/plot/__go_draw_axes__.m
-*- texinfo -*-
@deftypefn {Function File} {} __go_draw_axes__ (@var{h}, @var{plot_stream}, @var{enhanced}, @var{mono})
Undocumented internal function.
@end deftypefn
__go_draw_figure__
@c __go_draw_figure__ scripts/plot/__go_draw_figure__.m
-*- texinfo -*-
@deftypefn {Function File} {} __go_draw_figure__ (@var{h}, @var{plot_stream}, @var{enhanced}, @var{mono})
Undocumented internal function.
@end deftypefn
__marching_cube__
@c __marching_cube__ scripts/plot/__marching_cube__.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{t}, @var{p}] =} __marching_cube__ (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso})
@deftypefnx {Function File} {[@var{t}, @var{p}, @var{c}] =} __marching_cube__ (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso}, @var{col})
Undocumented internal function.
@end deftypefn
__next_line_color__
@c __next_line_color__ scripts/plot/__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/__next_line_style__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{style} =} __next_line_style__ (@var{reset})
Undocumented internal function.
@end deftypefn
__plt_get_axis_arg__
@c __plt_get_axis_arg__ scripts/plot/__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
__print_parse_opts__
@c __print_parse_opts__ scripts/plot/__print_parse_opts__.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{y}, @var{buttons}] =} ginput (@var{n})
Return which mouse buttons were pressed and keys were hit on the current
figure.  If @var{n} is defined, then wait for @var{n} mouse clicks
before returning.  If @var{n} is not defined, then @code{ginput} will
loop until the return key is pressed.
@end deftypefn
allchild
@c allchild scripts/plot/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.  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{get, set, findall, findobj}
@end deftypefn
ancestor
@c ancestor scripts/plot/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} is of type @var{type}, return @var{h}.

If @code{"toplevel"} is given as a 3rd argument, return the highest
parent in the object hierarchy that matches the condition, instead
of the first (nearest) one.
@seealso{get, set}
@end deftypefn
area
@c area scripts/plot/area.m
-*- texinfo -*-
@deftypefn  {Function File} {} area (@var{x}, @var{y})
@deftypefnx {Function File} {} area (@var{x}, @var{y}, @var{lvl})
@deftypefnx {Function File} {} area (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {} area (@var{y}, @dots{})
@deftypefnx {Function File} {} area (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} area (@dots{})
Area plot of cumulative sum of the columns of @var{y}.  This shows the
contributions of a value to a sum, and 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 is assumed to be given by
@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.

Additional arguments to the @code{area} function are passed to the
@code{patch}.  The optional return value @var{h} provides a handle to
area series object representing the patches of the areas.
@seealso{plot, patch}
@end deftypefn
axes
@c axes scripts/plot/axes.m
-*- texinfo -*-
@deftypefn  {Function File} {} axes ()
@deftypefnx {Function File} {} axes (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} axes (@var{h})
Create an axes object and return a handle to it.
@end deftypefn
axis
@c axis scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{limits} =} axis ()
Set axis limits for plots.

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.

Without any arguments, @code{axis} turns autoscaling on.

With one output argument, @code{x = axis} returns the current axes.

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 "square"
Force a square aspect ratio.

@item "equal"
Force x distance to equal y-distance.

@item "normal"
Restore the balance.
@end table

@noindent
The following options control the way axis limits are interpreted.

@table @asis
@item "auto"
Set the specified axes to have nice limits around the data
or all if no axes are specified.

@item "manual"
Fix the current axes limits.

@item "tight"
Fix axes to the limits of the data.
@end table

@noindent
The option @code{"image"} is equivalent to @code{"tight"} and
@code{"equal"}.

@noindent
The following options affect the appearance of tic marks.

@table @asis
@item "on"
Turn tic marks and labels on for all axes.

@item "off"
Turn tic marks off for all axes.

@item "tic[xyz]"
Turn tic marks on for all axes, or turn them on for the
specified axes and off for the remainder.

@item "label[xyz]"
Turn tic labels on for all axes, or turn them on for the
specified axes and off for the remainder.

@item "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 "ij"
Reverse y-axis, so lower values are nearer the top.

@item "xy"
Restore y-axis, so higher values are nearer the top.
@end table

If an axes handle is passed as the first argument, then operate on
this axes rather than the current axes.
@end deftypefn
bar
@c bar scripts/plot/bar.m
-*- texinfo -*-
@deftypefn  {Function File} {} bar (@var{x}, @var{y})
@deftypefnx {Function File} {} bar (@var{y})
@deftypefnx {Function File} {} bar (@var{x}, @var{y}, @var{w})
@deftypefnx {Function File} {} bar (@var{x}, @var{y}, @var{w}, @var{style})
@deftypefnx {Function File} {@var{h} =} bar (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} bar (@var{h}, @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 taken to be the indices of the elements.

The default width of 0.8 for the bars can be changed using @var{w}.

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 values @code{"grouped"} (the default),
or @code{"stacked"}.

The optional return value @var{h} provides a handle to the "bar series"
object with one handle per column of the variable @var{y}.  This
series allows common elements of the group of bar series objects to
be changed in a single bar series and the same properties are changed
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 optional input handle @var{h} allows an axis handle to be passed.

The bar graph's appearance may be modified by specifying property/value
pairs.  The following example modifies the face and edge colors.

@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 ())
@end group
@end example

@noindent
will change the colors used for the bars.  The color of bars can also be set
manually using the "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, plot}
@end deftypefn
barh
@c barh scripts/plot/barh.m
-*- texinfo -*-
@deftypefn  {Function File} {} barh (@var{x}, @var{y})
@deftypefnx {Function File} {} barh (@var{y})
@deftypefnx {Function File} {} barh (@var{x}, @var{y}, @var{w})
@deftypefnx {Function File} {} barh (@var{x}, @var{y}, @var{w}, @var{style})
@deftypefnx {Function File} {@var{h} =} barh (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} barh (@var{h}, @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 taken to be the indices of the elements.

The default width of 0.8 for the bars can be changed using @var{w}.

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 values @code{"grouped"} (the default),
or @code{"stacked"}.

The optional return value @var{h} provides a handle to the bar series
object.  See @code{bar} for a description of the use of the bar series.

The optional input handle @var{h} allows an axis handle to be passed.
Properties of the patch graphics object can be changed using
@var{prop}, @var{val} pairs.

@seealso{bar, plot}
@end deftypefn
box
@c box scripts/plot/box.m
-*- texinfo -*-
@deftypefn  {Function File} {} box (@var{arg})
@deftypefnx {Function File} {} box (@var{h}, @dots{})
Control the display of a border around the plot.
The argument may be either @code{"on"} or @code{"off"}.  If it is
omitted, the current box state is toggled.
@seealso{grid}
@end deftypefn
caxis
@c caxis scripts/plot/caxis.m
-*- texinfo -*-
@deftypefn  {Function File} {} caxis (@var{limits})
@deftypefnx {Function File} {} caxis (@var{h}, @dots{})
Set color axis limits for plots.

The argument @var{limits} should be a 2-element vector specifying the
lower and upper limits to assign to the first and last value in the
colormap.  Values outside this range are clamped to the first and last
colormap entries.

If @var{limits} is 'auto', then automatic colormap scaling is applied,
whereas if @var{limits} is 'manual' the colormap scaling is set to manual.

Called without any arguments to current color axis limits are returned.

If an axes handle is passed as the first argument, then operate on
this axes rather than the current axes.
@end deftypefn
cla
@c cla scripts/plot/cla.m
-*- texinfo -*-
@deftypefn  {Function File} {} cla ()
@deftypefnx {Function File} {} cla ("reset")
@deftypefnx {Function File} {} cla (@var{hax})
@deftypefnx {Function File} {} cla (@var{hax}, "reset")
Delete the children of the current axes with visible handles.
If @var{hax} is specified and is an axes object handle, operate on it
instead of the current axes.  If the optional argument @code{"reset"}
is specified, also delete the children with hidden handles.
@seealso{clf}
@end deftypefn
clabel
@c clabel scripts/plot/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 (@var{c}, @var{h})
@deftypefnx {Function File} {} clabel (@dots{}, @var{prop}, @var{val}, @dots{})
@deftypefnx {Function File} {@var{h} =} clabel (@dots{})
Adds labels to the contours of a contour plot.  The contour plot is specified
by the contour matrix @var{c} and optionally the contourgroup object @var{h}
that are returned by @code{contour}, @code{contourf} and @code{contour3}.
The contour labels are rotated and placed in the contour itself.

By default, all contours are labeled.  However, the contours to label can be
specified by the vector @var{v}.  If the "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.  Additionally,
the property "LabelSpacing" is available allowing the spacing between labels
on a contour (in points) to be specified.  The default is 144 points, or 2
inches.

The returned value @var{h} is the set of text object that represent the
contour labels.  The "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
clf
@c clf scripts/plot/clf.m
-*- texinfo -*-
@deftypefn  {Function File} {} clf ()
@deftypefnx {Function File} {} clf ("reset")
@deftypefnx {Function File} {} clf (@var{hfig})
@deftypefnx {Function File} {} clf (@var{hfig}, "reset")
Clear the current figure window.  @code{clf} operates by deleting child
graphics objects with visible handles (@code{handlevisibility} = on).
If @var{hfig} is specified operate on it instead of the current figure.
If the optional argument @code{"reset"} is specified, all objects including
those with hidden handles are deleted.
@seealso{cla, close, delete}
@end deftypefn
close
@c close scripts/plot/close.m
-*- texinfo -*-
@deftypefn  {Command} {} close
@deftypefnx {Command} {} close (@var{n})
@deftypefnx {Command} {} close all
@deftypefnx {Command} {} close all hidden
Close figure window(s) by calling the function specified by the
@code{"closerequestfcn"} property for each figure.  By default, the
function @code{closereq} is used.
@seealso{closereq}
@end deftypefn
closereq
@c closereq scripts/plot/closereq.m
-*- texinfo -*-
@deftypefn {Function File} {} closereq ()
Close the current figure and delete all graphics objects associated
with it.
@seealso{close, delete}
@end deftypefn
colorbar
@c colorbar scripts/plot/colorbar.m
-*- texinfo -*-
@deftypefn  {Function File} {} colorbar (@var{s})
@deftypefnx {Function File} {} colorbar ("peer", @var{h}, @dots{})
Adds a colorbar to the current axes.  Valid values for @var{s} are

@table @asis
@item "EastOutside"
Place the colorbar outside the plot to the right.  This is the default.

@item "East"
Place the colorbar inside the plot to the right.

@item "WestOutside"
Place the colorbar outside the plot to the left.

@item "West"
Place the colorbar inside the plot to the left.

@item "NorthOutside"
Place the colorbar above the plot.

@item "North"
Place the colorbar at the top of the plot.

@item "SouthOutside"
Place the colorbar under the plot.

@item "South"
Place the colorbar at the bottom of the plot.

@item "Off", "None"
Remove any existing colorbar from the plot.
@end table

If the argument "peer" is given, then the following argument is treated
as the axes handle on which to add the colorbar.
@end deftypefn
comet
@c comet scripts/plot/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{ax}, @dots{})
Produce a simple comet style animation along the trajectory provided by
the input coordinate vectors (@var{x}, @var{y}), where @var{x} will default
to the indices of @var{y}.

The speed of the comet may be controlled by @var{p}, which represents the
time which passes as the animation passes from one point to the next.  The
default for @var{p} is 0.1 seconds.

If @var{ax} is specified the animation is produced in that axis rather than
the @code{gca}.
@end deftypefn
comet3
@c comet3 scripts/plot/comet3.m
-*- texinfo -*-
@deftypefn  {Function File} {} comet3 (@var{z})
@deftypefnx {Function File} {} comet3 (@var{x}, @var{y}, @var{z}, @var{p})
@deftypefnx {Function File} {} comet3 (@var{ax}, @dots{})
Produce a simple comet style animation along the trajectory provided by
the input coordinate vectors (@var{x}, @var{y}), where @var{x} will default
to the indices of @var{y}.

The speed of the comet may be controlled by @var{p}, which represents the
time which passes as the animation passes from one point to the next.  The
default for @var{p} is 0.1 seconds.

If @var{ax} is specified the animation is produced in that axis rather than
the @code{gca}.
@end deftypefn
compass
@c compass scripts/plot/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{h}, @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.  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}
in a similar manner to the line styles used with the @code{plot} command.

The optional return value @var{h} provides a list of handles to the
the parts of the vector field (body, arrow and marker).

@example
@group
a = toeplitz([1;randn(9,1)],[1,randn(1,9)]);
compass (eig (a))
@end group
@end example

@seealso{plot, polar, quiver, feather}
@end deftypefn
contour
@c contour scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contour (@dots{})
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 set of
contour levels, @var{c}, is only returned if requested.  For example:

@example
@group
x = 0:2;
y = x;
z = x' * y;
contour (x, y, z, 2:3)
@end group
@end example

The style to use for the plot can be defined with a line style @var{style}
in a similar manner to the line styles used with the @code{plot} command.
Any markers defined by @var{style} are ignored.

The optional input and output argument @var{h} allows an axis handle to
be passed to @code{contour} and the handles to the contour objects to be
returned.
@seealso{contourc, patch, plot}
@end deftypefn
contour3
@c contour3 scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contour3 (@dots{})
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 contours are
plotted at the Z level corresponding to their contour.  The set of
contour levels, @var{c}, is only returned if requested.  For example:

@example
@group
contour3 (peaks (19));
hold on
surface (peaks (19), "facecolor", "none", "EdgeColor", "black")
colormap hot
@end group
@end example

The style to use for the plot can be defined with a line style @var{style}
in a similar manner to the line styles used with the @code{plot} command.
Any markers defined by @var{style} are ignored.

The optional input and output argument @var{h} allows an axis handle to
be passed to @code{contour} and the handles to the contour objects to be
returned.
@seealso{contourc, patch, plot}
@end deftypefn
contourc
@c contourc scripts/plot/contourc.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{c}, @var{lev}] =} contourc (@var{x}, @var{y}, @var{z}, @var{vn})
Compute isolines (contour lines) of the matrix @var{z}.
Parameters @var{x}, @var{y} and @var{vn} are optional.

The return value @var{lev} is a vector of the contour levels.
The return value @var{c} is a 2 by @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}.

If @var{x} and @var{y} are omitted they are taken as the row/column
index of @var{z}.  @var{vn} is either a scalar denoting the number of lines
to compute or a vector containing the values of the lines.  If only one
value is wanted, set @code{@var{vn} = [val, val]};
If @var{vn} is omitted it defaults to 10.

For 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}
@end deftypefn
contourf
@c contourf scripts/plot/contourf.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{c}, @var{h}] =} contourf (@var{x}, @var{y}, @var{z}, @var{lvl})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@var{x}, @var{y}, @var{z}, @var{n})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@var{z}, @var{n})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@var{z}, @var{lvl})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@var{z})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@var{ax}, @dots{})
@deftypefnx {Function File} {[@var{c}, @var{h}] =} contourf (@dots{}, @var{"property"}, @var{val})
Compute and plot filled contours of the matrix @var{z}.
Parameters @var{x}, @var{y} and @var{n} or @var{lvl} are optional.

The return value @var{c} is a 2xn matrix containing the contour lines
as described in the help to the contourc function.

The return value @var{h} is handle-vector to the patch objects creating
the filled contours.

If @var{x} and @var{y} are omitted they are taken as the row/column
index of @var{z}.  @var{n} is a scalar denoting the number of lines
to compute.  Alternatively @var{lvl} is a vector containing the
contour levels.  If only one value (e.g., lvl0) is wanted, set
@var{lvl} to [lvl0, lvl0].  If both @var{n} or @var{lvl} are omitted
a default value of 10 contour level is assumed.

If provided, the filled contours are added to the axes object
@var{ax} instead of the current axis.

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{contour, contourc, patch}
@end deftypefn
cylinder
@c cylinder scripts/plot/cylinder.m
-*- texinfo -*-
@deftypefn  {Function File} {} cylinder
@deftypefnx {Function File} {} cylinder (@var{r})
@deftypefnx {Function File} {} cylinder (@var{r}, @var{n})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} cylinder (@dots{})
@deftypefnx {Function File} {} cylinder (@var{ax}, @dots{})
Generates three matrices in @code{meshgrid} format, such that
@code{surf (@var{x}, @var{y}, @var{z})} generates a unit cylinder.
The matrices are of size @code{@var{n}+1}-by-@code{@var{n}+1}.
@var{r} is a vector containing the radius along the z-axis.
If @var{n} or @var{r} are omitted then default values of 20 or [1 1]
are assumed.

Called with no return arguments, @code{cylinder} calls directly
@code{surf (@var{x}, @var{y}, @var{z})}.  If an axes handle @var{ax}
is passed as the first argument, the surface is plotted to this set
of axes.

Examples:

@example
@group
[x, y, z] = cylinder (10:-1:0,50);
surf (x, y, z);
title ("a cone")
@end group
@end example
@seealso{sphere}
@end deftypefn
daspect
@c daspect scripts/plot/daspect.m
-*- texinfo -*-
@deftypefn {Function File} {} daspect (@var{data_aspect_ratio})
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-axes limits.
@deftypefnx {Function File} {@var{data_aspect_ratio} =} daspect ( )
Return the data aspect ratio of the current axes.
@deftypefnx {Function File} {} daspect (@var{mode})
Set the data aspect ratio mode of the current axes.
@deftypefnx {Function File} {@var{data_aspect_ratio_mode} =} daspect ("mode")
Return the data aspect ratio mode of the current axes.
@deftypefnx {Function File} {} daspect (@var{hax}, @dots{})
Uses the axes, with handle @var{hax}, instead of the current axes.

@seealso{axis, pbaspect, xlim, ylim, zlim}
@end deftypefn
diffuse
@c diffuse scripts/plot/diffuse.m
-*- texinfo -*-
@deftypefn {Function File} {} diffuse (@var{sx}, @var{sy}, @var{sz}, @var{lv})
Calculate diffuse reflection strength of a surface defined by the normal
vector elements @var{sx}, @var{sy}, @var{sz}.
The light vector can be specified using parameter @var{lv}.  It can be
given as 2-element vector [azimuth, elevation] in degrees or as 3-element
vector [lx, ly, lz].
@seealso{specular, surfl}
@end deftypefn
ellipsoid
@c ellipsoid scripts/plot/ellipsoid.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{x}, @var{y}, @var{z}] =} ellipsoid (@var{xc}, @var{yc}, @var{zc}, @var{xr}, @var{yr}, @var{zr}, @var{n})
@deftypefnx {Function File} {} ellipsoid (@var{h}, @dots{})
Generate three matrices in @code{meshgrid} format that define an
ellipsoid.  Called with no return arguments, @code{ellipsoid} calls
directly @code{surf (@var{x}, @var{y}, @var{z})}.  If an axes handle
is passed as the first argument, the surface is plotted to this
set of axes.
@seealso{sphere}
@end deftypefn
errorbar
@c errorbar scripts/plot/errorbar.m
-*- texinfo -*-
@deftypefn {Function File} {} errorbar (@var{args})
This function produces two-dimensional plots 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
and the second argument @var{ey} is taken as the errors of the
@var{y} values.  @var{x} coordinates are taken to be the indices
of the elements, starting with 1.

If more than two arguments are given, they are interpreted as

@example
errorbar (@var{x}, @var{y}, @dots{}, @var{fmt}, @dots{})
@end example

@noindent
where after @var{x} and @var{y} there can be up to four error
parameters such as @var{ey}, @var{ex}, @var{ly}, @var{uy}, etc.,
depending on the plot type.  Any number of argument sets may appear,
as long as they are separated with a format string @var{fmt}.

If @var{y} is a matrix, @var{x} and error parameters must also be matrices
having same dimensions.  The columns of @var{y} are plotted versus the
corresponding columns of @var{x} and errorbars are drawn from
the corresponding columns of error parameters.

If @var{fmt} is missing, yerrorbars ("~") plot style is assumed.

If the @var{fmt} argument is supplied, it is interpreted as in
normal plots.  In addition, @var{fmt} may include an errorbar style
which must precede the line and marker format.  The following plot
styles are supported by errorbar:

@table @samp
@item ~
Set yerrorbars plot style (default).

@item >
Set xerrorbars plot style.

@item ~>
Set xyerrorbars plot style.

@item #
Set boxes plot style.

@item #~
Set boxerrorbars plot style.

@item #~>
Set boxxyerrorbars plot style.
@end table

Examples:

@example
errorbar (@var{x}, @var{y}, @var{ex}, ">")
@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}.

@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}
@end deftypefn
ezcontour
@c ezcontour scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezcontour (@dots{})

Plots 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 domain @code{-2*pi < @var{x} < 2*pi} and @code{-2*pi <
@var{y} < 2*pi} with 60 points in each dimension.

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum value of @var{x} and @var{y} are specify
separately.

@var{n} is a scalar defining the number of points to use in each dimension.

The optional return value @var{h} provides a list of handles to the
the parts of the vector field (body, arrow and marker).

@example
@group
f = @@(x,y) sqrt(abs(x .* y)) ./ (1 + x.^2 + y.^2);
ezcontour (f, [-3, 3]);
@end group
@end example

@seealso{ezplot, ezcontourf, ezsurfc, ezmeshc}
@end deftypefn
ezcontourf
@c ezcontourf scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezcontourf (@dots{})

Plots 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 domain @code{-2*pi < @var{x} < 2*pi} and
@code{-2*pi < @var{y} < 2*pi} with 60 points in each dimension.

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum value of @var{x} and @var{y} are specify
separately.

@var{n} is a scalar defining the number of points to use in each dimension.

The optional return value @var{h} provides a list of handles to the
the parts of the vector field (body, arrow and marker).

@example
@group
f = @@(x,y) sqrt(abs(x .* y)) ./ (1 + x.^2 + y.^2);
ezcontourf (f, [-3, 3]);
@end group
@end example

@seealso{ezplot, ezcontour, ezsurfc, ezmeshc}
@end deftypefn
ezmesh
@c ezmesh scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezmesh (@dots{})

Plots 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 domain @code{-2*pi < @var{x} < 2*pi} and
@code{-2*pi < @var{y} < 2*pi} with 60 points in each dimension.

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum value of @var{x} and @var{y} are specify
separately.

@var{n} is a scalar defining the number of points to use 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 the argument 'circ' is given, then the function is plotted over a disk
centered on the middle of the domain @var{dom}.

The optional return value @var{h} provides a list of handles to the
the parts of the vector field (body, arrow and marker).

@example
@group
f = @@(x,y) sqrt(abs(x .* y)) ./ (1 + x.^2 + y.^2);
ezmesh (f, [-3, 3]);
@end group
@end example

An example of a parametrically defined function is

@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{ezplot, ezsurf, ezsurfc, ezmeshc}
@end deftypefn
ezmeshc
@c ezmeshc scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezmeshc (@dots{})

Plots 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 domain @code{-2*pi < @var{x} < 2*pi} and
@code{-2*pi < @var{y} < 2*pi} with 60 points in each dimension.

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum value of @var{x} and @var{y} are specify
separately.

@var{n} is a scalar defining the number of points to use 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 the argument 'circ' is given, then the function is plotted over a disk
centered on the middle of the domain @var{dom}.

The optional return value @var{h} provides a list of handles to the
the parts of the vector field (body, arrow and marker).

@example
@group
f = @@(x,y) sqrt(abs(x .* y)) ./ (1 + x.^2 + y.^2);
ezmeshc (f, [-3, 3]);
@end group
@end example

@seealso{ezplot, ezsurfc, ezsurf, ezmesh}
@end deftypefn
ezplot
@c ezplot scripts/plot/ezplot.m
-*- texinfo -*-
@deftypefn  {Function File} {} ezplot (@var{f})
@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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezplot (@dots{})

Plots in two-dimensions the curve defined by @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{f} has two variables then @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 by 60 in the mesh.  For example:

@example
ezplot (@@(@var{x}, @var{y}) @var{x} .^ 2 - @var{y} .^ 2 - 1)
@end example

If two functions are passed as strings, inline functions or function
handles, 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
value of @var{x}, @var{y} and @var{t}.  If it is a four element
vector, then the minimum and maximum values of @var{x} and @var{t}
are determined by the first two elements and the minimum and maximum
of @var{y} by the second pair of elements.

@var{n} is a scalar defining the number of points to use in plotting
the function.

The optional return value @var{h} provides a list of handles to the
the line objects plotted.

@seealso{plot, ezplot3}
@end deftypefn
ezplot3
@c ezplot3 scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezplot3 (@dots{})

Plots in three-dimensions the curve defined parametrically.
@var{fx}, @var{fy}, and @var{fz} are strings, inline functions
or function handles with one arguments defining the function.  By
default the plot is over the domain @code{-2*pi < @var{x} < 2*pi}
with 60 points.

If @var{dom} is a two element vector, it represents the minimum and maximum
value of @var{t}.  @var{n} is a scalar defining the number of points to use.

The optional return value @var{h} provides a list of handles to the
the parts of the vector field (body, arrow and marker).

@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, ezsurf, ezmesh}
@end deftypefn
ezpolar
@c ezpolar scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezpolar (@dots{})

Plots in polar plot defined by a function.  The function @var{f} is either
a string, inline function or function handle with one arguments defining
the function.  By default the plot is over the domain @code{0 < @var{x} <
2*pi} with 60 points.

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{t}.  @var{n} is a scalar defining the number of points to
use.

The optional return value @var{h} provides a list of handles to the
the parts of the vector field (body, arrow and marker).

@example
ezpolar (@@(t) 1 + sin (t));
@end example

@seealso{polar, ezplot, ezsurf, ezmesh}
@end deftypefn
ezsurf
@c ezsurf scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezsurf (@dots{})

Plots 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 domain @code{-2*pi < @var{x} < 2*pi} and
@code{-2*pi < @var{y} < 2*pi} with 60 points in each dimension.

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum value of @var{x} and @var{y} are specify
separately.

@var{n} is a scalar defining the number of points to use 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 the argument 'circ' is given, then the function is plotted over a disk
centered on the middle of the domain @var{dom}.

The optional return value @var{h} provides a list of handles to the
the parts of the vector field (body, arrow and marker).

@example
@group
f = @@(x,y) sqrt(abs(x .* y)) ./ (1 + x.^2 + y.^2);
ezsurf (f, [-3, 3]);
@end group
@end example

An example of a parametrically defined function is

@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{ezplot, ezmesh, ezsurfc, ezmeshc}
@end deftypefn
ezsurfc
@c ezsurfc scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} ezsurfc (@dots{})

Plots 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 domain @code{-2*pi < @var{x} <
2*pi} and @code{-2*pi < @var{y} < 2*pi} with 60 points in each dimension.

If @var{dom} is a two element vector, it represents the minimum and maximum
value of both @var{x} and @var{y}.  If @var{dom} is a four element vector,
then the minimum and maximum value of @var{x} and @var{y} are specify
separately.

@var{n} is a scalar defining the number of points to use 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 the argument 'circ' is given, then the function is plotted over a disk
centered on the middle of the domain @var{dom}.

The optional return value @var{h} provides a list of handles to the
the parts of the vector field (body, arrow and marker).

@example
@group
f = @@(x,y) sqrt(abs(x .* y)) ./ (1 + x.^2 + y.^2);
ezsurfc (f, [-3, 3]);
@end group
@end example

@seealso{ezplot, ezmeshc, ezsurf, ezmesh}
@end deftypefn
feather
@c feather scripts/plot/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{h}, @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}
in a similar manner to the line styles used with the @code{plot} command.

The optional return value @var{h} provides a list of handles to the
the parts of the vector field (body, arrow and marker).

@example
@group
phi = [0 : 15 : 360] * pi / 180;
feather (sin (phi), cos (phi))
@end group
@end example

@seealso{plot, quiver, compass}
@end deftypefn
figure
@c figure scripts/plot/figure.m
-*- texinfo -*-
@deftypefn  {Function File} {} figure (@var{n})
@deftypefnx {Function File} {} figure (@var{n}, @var{property}, @var{value}, @dots{})
Set the current plot window to plot window @var{n}.  If no arguments are
specified, the next available window number is chosen.

Multiple property-value pairs may be specified for the figure, but they
must appear in pairs.
@end deftypefn
fill
@c fill scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} fill (@dots{})
Create one or more filled patch objects, returning a patch object for each.
@end deftypefn
findall
@c findall scripts/plot/findall.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} findall ()
@deftypefnx {Function File} {@var{h} =} findall (@var{prop_name}, @var{prop_value})
@deftypefnx {Function File} {@var{h} =} findall (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} findall (@var{h}, "-depth", @var{d}, @dots{})
Find object with specified property values including hidden handles.

This function performs the same function as @code{findobj}, but it
includes hidden objects in its search.  For full documentation, see
@code{findobj}.
@seealso{get, set, findobj, allchild}
@end deftypefn
findobj
@c findobj scripts/plot/findobj.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} findobj ()
@deftypefnx {Function File} {@var{h} =} findobj (@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 ('flat', @dots{})
@deftypefnx {Function File} {@var{h} =} findobj (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} findobj (@var{h}, '-depth', @var{d}, @dots{})
Find object with specified property values.  The simplest form is

@example
findobj (@var{prop_name}, @var{prop_Value})
@end example

@noindent
which returns all of the handles to the objects with the name
@var{prop_name} and the name @var{prop_Value}.  The search can be limited
to a particular object or set of objects and their descendants by
passing a handle or set of handles @var{h} as the first argument to
@code{findobj}.

The depth of hierarchy of objects to which to search to can be limited
with the '-depth' argument.  To limit the number depth of the hierarchy
to search to @var{d} generations of children, and example is

@example
findobj (@var{h}, '-depth', @var{d}, @var{prop_Name}, @var{prop_Value})
@end example

Specifying a depth @var{d} of 0, limits the search to the set of object
passed in @var{h}.  A depth @var{d} of 0 is equivalent to the '-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 '-and', '-or',
'-xor', '-not'.

The 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, using the '-property' option.
@seealso{get, set}
@end deftypefn
fplot
@c fplot scripts/plot/fplot.m
-*- texinfo -*-
@deftypefn  {Function File} {} fplot (@var{fn}, @var{limits})
@deftypefnx {Function File} {} fplot (@var{fn}, @var{limits}, @var{tol})
@deftypefnx {Function File} {} fplot (@var{fn}, @var{limits}, @var{n})
@deftypefnx {Function File} {} fplot (@dots{}, @var{fmt})
Plot a function @var{fn}, within the defined limits.  @var{fn}
an be either a string, a function handle or an inline function.
The limits of the plot are given by @var{limits} of the form
@code{[@var{xlo}, @var{xhi}]} or @code{[@var{xlo}, @var{xhi},
@var{ylo}, @var{yhi}]}.  @var{tol} is the default tolerance to use for the
plot, and if @var{tol} is an integer it is assumed that it defines the
number points to use in the plot.  The @var{fmt} argument is passed
to the plot command.

@example
@group
   fplot ("cos", [0, 2*pi])
   fplot ("[cos(x), sin(x)]", [0, 2*pi])
@end group
@end example
@seealso{plot}
@end deftypefn
gca
@c gca scripts/plot/gca.m
-*- texinfo -*-
@deftypefn {Function File} {} gca ()
Return a handle to the current axis object.  If no axis 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, then changes its location and size in
the figure window.
@seealso{get, set}
@end deftypefn
gcbf
@c gcbf scripts/plot/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 gcbo.

@seealso{gcf, gca, gcbo}
@end deftypefn
gcbo
@c gcbo scripts/plot/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
"CallbackObject".

Additionally 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{gcf, gca, gcbf}
@end deftypefn
gcf
@c gcf scripts/plot/gcf.m
-*- texinfo -*-
@deftypefn {Function File} {} gcf ()
Return the current figure handle.  If a 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, "visible", "off");
@end group
@end example

@noindent
plots a sine wave, finds the handle of the current figure, and then
makes that figure invisible.  Setting the visible property of the
figure to @code{"on"} will cause it to be displayed again.
@seealso{get, set}
@end deftypefn
ginput
@c ginput scripts/plot/ginput.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{y}, @var{buttons}] =} ginput (@var{n})
Return which mouse buttons were pressed and keys were hit on the current
figure.  If @var{n} is defined, then wait for @var{n} mouse clicks
before returning.  If @var{n} is not defined, then @code{ginput} will
loop until the return key is pressed.
@end deftypefn
graphics_toolkit
@c graphics_toolkit scripts/plot/graphics_toolkit.m
-*- texinfo -*-
@deftypefn  {Function File} {} graphics_toolkit (@var{name})
@deftypefnx {Function File} {} graphics_toolkit (@var{hlist}, @var{name})
Change the default graphics toolkit to @var{name}.  If the
toolkit is not already loaded, it is first initialized by calling the
function @code{__init_@var{name}__}.

When called with a list of figure handles, @var{hlist}, the graphics
toolkit is changed only for the listed figures.
@seealso{available_graphics_toolkits}
@end deftypefn
grid
@c grid scripts/plot/grid.m
-*- texinfo -*-
@deftypefn  {Function File} {} grid (@var{arg})
@deftypefnx {Function File} {} grid ("minor", @var{arg2})
@deftypefnx {Function File} {} grid (@var{hax}, @dots{})
Force the display of a grid on the plot.
The argument may be either @code{"on"}, or @code{"off"}.
If it is omitted, the current grid state is toggled.

If @var{arg} is @code{"minor"} then the minor grid is toggled.  When
using a minor grid a second argument @var{arg2} is allowed, which can
be either @code{"on"} or @code{"off"} to explicitly set the state of
the minor grid.

If the first argument is an axis handle, @var{hax}, operate on the
specified axis object.
@seealso{plot}
@end deftypefn
gtext
@c gtext scripts/plot/gtext.m
-*- texinfo -*-
@deftypefn  {Function File} {} gtext (@var{s})
@deftypefnx {Function File} {} gtext (@{@var{s1}; @var{s2}; @dots{}@})
@deftypefnx {Function File} {} gtext (@dots{}, @var{prop}, @var{val})
Place text on the current figure using the mouse.  The text is defined
by the string @var{s}.  If @var{s} is a cell array, each element of the cell
array is written to a separate line.  Additional arguments are passed to
the underlying text object as properties.
@seealso{ginput, text}
@end deftypefn
hggroup
@c hggroup scripts/plot/hggroup.m
-*- texinfo -*-
@deftypefn  {Function File} {} hggroup ()
@deftypefnx {Function File} {} hggroup (@var{h})
@deftypefnx {Function File} {} hggroup (@dots{}, @var{property}, @var{value}, @dots{})
Create group object with parent @var{h}.  If no parent is specified,
the group is created in the current axes.  Return the handle of the
group object created.

Multiple property-value pairs may be specified for the group, but they
must appear in pairs.
@end deftypefn
hidden
@c hidden scripts/plot/hidden.m
-*- texinfo -*-
@deftypefn  {Function File} {} hidden (@var{mode})
@deftypefnx {Function File} {} hidden ()
Manipulation the mesh hidden line removal.  Called with no argument
the hidden line removal is toggled.  The argument @var{mode} can be either
'on' or 'off' and the set of the hidden line removal is set accordingly.
@seealso{mesh, meshc, surf}
@end deftypefn
hist
@c hist scripts/plot/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} {[@var{nn}, @var{xx}] =} hist (@dots{})
@deftypefnx {Function File} {[@dots{}] =} hist (@dots{}, @var{prop}, @var{val})

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 in the first and last bins.

With two output arguments, produce the values @var{nn} and @var{xx} such
that @code{bar (@var{xx}, @var{nn})} will plot the histogram.

The histogram's appearance may be modified by specifying property/value
pairs, @var{prop} and @var{val} 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 histograms colors also depend upon the colormap.

@example
@group
hist (rand (10, 3))
colormap (summer ())
@end group
@end example

@seealso{bar}
@end deftypefn
hold
@c hold scripts/plot/hold.m
-*- texinfo -*-
@deftypefn  {Command} {} hold
@deftypefnx {Command} {} hold @var{state}
@deftypefnx {Function File} {} hold (@var{hax}, @dots{})
Toggle or set the '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
Clear plot and restore default graphics settings 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
only for the given axis handle.

To query the current 'hold' state use the @code{ishold} function.
@seealso{ishold, cla, newplot, clf}
@end deftypefn
isfigure
@c isfigure scripts/plot/isfigure.m
-*- texinfo -*-
@deftypefn {Function File} {} isfigure (@var{h})
Return true if @var{h} is a graphics handle that contains a figure
object.
@seealso{ishandle}
@end deftypefn
ishghandle
@c ishghandle scripts/plot/ishghandle.m
-*- texinfo -*-
@deftypefn {Function File} {} ishghandle (@var{h})
Return true if @var{h} is a graphics handle and false otherwise.
@end deftypefn
ishold
@c ishold scripts/plot/ishold.m
-*- texinfo -*-
@deftypefn {Command} {} ishold
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.
@seealso{hold}
@end deftypefn
isocolors
@c isocolors scripts/plot/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{})

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, isocaps}

@end deftypefn
isonormals
@c isonormals scripts/plot/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})

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 "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:

@example
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 example

@seealso {isosurface, isocolors, isocaps, marching_cube}

@end deftypefn
isosurface
@c isosurface scripts/plot/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})

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 "noshare" is only for compatibility and
has no effect.  If given the string input argument
"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 seperate 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

@example
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 example

@seealso{isocolors, isonormals, isocaps}

@end deftypefn
isprop
@c isprop scripts/plot/isprop.m
-*- texinfo -*-
@deftypefn {Function File} {@var{res} =} isprop (@var{h}, @var{prop})
Return true if @var{prop} is a property of the object with handle @var{h}.
@seealso{get, set}
@end deftypefn
legend
@c legend scripts/plot/legend.m
-*- texinfo -*-
@deftypefn  {Function File} {} legend (@var{str1}, @var{str2}, @dots{})
@deftypefnx {Function File} {} legend (@var{matstr})
@deftypefnx {Function File} {} legend (@var{cell})
@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}")

Display a legend for the axes with handle @var{hax}, or 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 handles, @var{hobjs}, are not specified
then the legend's strings will be associated with the axes' descendants.
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

@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 "vertical"
or "horizontal" with the default being "vertical".

The following customizations are available using @var{option}:

@table @asis
@item "show"
  Show legend on the plot

@item "hide"
  Hide legend on the plot

@itemx "toggle"
  Toggles between "hide" and "show"

@item "boxon"
  Show a box around legend

@item "boxoff"
  Hide the box around legend

@item "left"
  Place text to the left of the keys

@item "right"
  Place text to the right of the keys

@itemx "off"
  Delete the legend object
@end table
@end deftypefn
line
@c line scripts/plot/line.m
-*- texinfo -*-
@deftypefn  {Function File} {} line ()
@deftypefnx {Function File} {} line (@var{x}, @var{y})
@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{})
Create line object from @var{x} and @var{y} and insert in current
axes object.  Return a handle (or vector of handles) to the line
objects created.

Multiple property-value pairs may be specified for the line, but they
must appear in pairs.
@end deftypefn
linkprop
@c linkprop scripts/plot/linkprop.m
-*- texinfo -*-
@deftypefn {Function File} {@var{hlink} =} linkprop (@var{h}, @var{prop})
Links graphics object properties, such that a change in one is
propagated to the others.  The properties to link are given as a
string of cell string array by @var{prop} and the objects containing
these properties by the handle array @var{h}.

An example of the use of 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

@end deftypefn
loglog
@c loglog scripts/plot/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{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} loglog (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} loglog (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} loglog (@dots{})
Produce a two-dimensional plot using log scales for both axes.  See
the documentation of @code{plot} for a description of the arguments
that @code{loglog} will accept.
@seealso{plot, semilogx, semilogy}
@end deftypefn
loglogerr
@c loglogerr scripts/plot/loglogerr.m
-*- texinfo -*-
@deftypefn {Function File} {} loglogerr (@var{args})
Produce two-dimensional plots on double logarithm axis with
errorbars.  Many different combinations of arguments are possible.
The most used 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}.  See errorbar for available formats and
additional information.
@seealso{errorbar, semilogxerr, semilogyerr}
@end deftypefn
mesh
@c mesh scripts/plot/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 (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} mesh (@dots{})
Plot a mesh given matrices @var{x}, and @var{y} from @code{meshgrid} and
a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of
the mesh.  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.

The color of the mesh is derived from the @code{colormap}
and the value of @var{z}.  Optionally the color of the mesh can be
specified independent of @var{z}, by adding a fourth matrix, @var{c}.
@seealso{colormap, contour, meshgrid, surf}
@end deftypefn
meshc
@c meshc scripts/plot/meshc.m
-*- texinfo -*-
@deftypefn {Function File} {} meshc (@var{x}, @var{y}, @var{z})
Plot a mesh and contour given matrices @var{x}, and @var{y} from
@code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and
@var{y} coordinates of the mesh.  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.
@seealso{meshgrid, mesh, contour}
@end deftypefn
meshgrid
@c meshgrid scripts/plot/meshgrid.m
-*- texinfo -*-
@deftypefn  {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}, @var{y})
@deftypefnx {Function File} {[@var{xx}, @var{yy}] =} meshgrid (@var{x})
Given vectors of @var{x} and @var{y} and @var{z} coordinates, and
returning 3 arguments, return three-dimensional arrays corresponding
to the @var{x}, @var{y}, and @var{z} coordinates of a mesh.  When
returning only 2 arguments, return matrices corresponding to the
@var{x} and @var{y} coordinates of a mesh.  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},
and @var{z} is assumed the same as @var{y}.
@seealso{mesh, contour}
@end deftypefn
meshz
@c meshz scripts/plot/meshz.m
-*- texinfo -*-
@deftypefn {Function File} {} meshz (@var{x}, @var{y}, @var{z})
Plot a curtain mesh given matrices @var{x}, and @var{y} from
@code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and
@var{y} coordinates of the mesh.  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.
@seealso{meshgrid, mesh, contour}
@end deftypefn
ndgrid
@c ndgrid scripts/plot/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 of 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})
@seealso{meshgrid}
@end deftypefn
newplot
@c newplot scripts/plot/newplot.m
-*- texinfo -*-
@deftypefn {Function File} {} newplot ()
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.
@end deftypefn
orient
@c orient scripts/plot/orient.m
-*- texinfo -*-
@deftypefn {Function File} {} orient (@var{orientation})
Set the default print orientation.  Valid values for
@var{orientation} include @code{"landscape"}, @code{"portrait"},
and @code{"tall"}.

The @code{"tall"} option sets the orientation to portait and fills
the page with the plot, while leaving a 0.25in border.

If called with no arguments, return the default print orientation.
@end deftypefn
pareto
@c pareto scripts/plot/pareto.m
-*- texinfo -*-
@deftypefn  {Function File} {} pareto (@var{x})
@deftypefnx {Function File} {} pareto (@var{x}, @var{y})
@deftypefnx {Function File} {} pareto (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} pareto (@dots{})
Draw a Pareto chart, also called ABC chart.  A Pareto chart is a bar graph
used to arrange 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
order from left to right along the abscissa.

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, so for quality improvement the first few (as presented on the
diagram) contributing causes 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.

The data are passed as @var{x} and the abscissa as @var{y}.  If @var{y} is
absent, then the abscissa are assumed to be @code{1 : length (@var{x})}.
@var{y} can be a string array, a cell array of strings or a numerical
vector.

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
@end deftypefn
patch
@c patch scripts/plot/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{f}, 'Vertices', @var{v}, @dots{})
@deftypefnx {Function File} {} patch (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} patch (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} patch (@dots{})
Create patch object from @var{x} and @var{y} with color @var{c} and
insert in the current axes object.  Return handle to patch object.

For a uniform colored patch, @var{c} can be given as an RGB vector,
scalar value referring to the current colormap, or string value (for
example, "r" or "red").

If passed a structure @var{fv} contain the fields "vertices", "faces"
and optionally "facevertexcdata", create the patch based on these
properties.
@end deftypefn
pbaspect
@c pbaspect scripts/plot/pbaspect.m
-*- texinfo -*-
@deftypefn {Function File} {} pbaspect (@var{plot_box_aspect_ratio})
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.
@deftypefnx {Function File} {@var{plot_box_aspect_ratio} =} pbaspect ( )
Return the plot box aspect ratio of the current axes.
@deftypefnx {Function File} {} pbaspect (@var{mode})
Set the plot box aspect ratio mode of the current axes.
@deftypefnx {Function File} {@var{plot_box_aspect_ratio_mode} =} pbaspect ("mode")
Return the plot box aspect ratio mode of the current axes.
@deftypefnx {Function File} {} pbaspect (@var{hax}, @dots{})
Uses the axes, with handle @var{hax}, instead of the current axes.

@seealso{axis, daspect, xlim, ylim, zlim}
@end deftypefn
pcolor
@c pcolor scripts/plot/pcolor.m
-*- texinfo -*-
@deftypefn  {Function File} {} pcolor (@var{x}, @var{y}, @var{c})
@deftypefnx {Function File} {} pcolor (@var{c})
Density plot for given matrices @var{x}, and @var{y} from @code{meshgrid} and
a matrix @var{c} corresponding to the @var{x} and @var{y} coordinates of
the mesh's vertices.  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 @code{colormap} is scaled to the extents of @var{c}.
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 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
"faceted", which renders a single color for each cell's face with the edge
visible.

@var{h} is the handle to the surface object.

@seealso{caxis, contour, meshgrid, imagesc, shading}
@end deftypefn
peaks
@c peaks scripts/plot/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{})
Generate 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{mesh}.  If @var{n} is a scalar, the @code{peaks}
returns the values of the above function on a @var{n}-by-@var{n} mesh over
the range @code{[-3,3]}.  The default value for @var{n} is 49.

If @var{n} is a vector, then it represents the @var{x} and @var{y} values
of the grid on which to calculate the above function.  The @var{x} and
@var{y} values can be specified separately.
@seealso{surf, mesh, meshgrid}
@end deftypefn
pie
@c pie scripts/plot/pie.m
-*- texinfo -*-
@deftypefn  {Function File} {} pie (@var{x})
@deftypefnx {Function File} {} pie (@var{x}, @var{explode})
@deftypefnx {Function File} {} pie (@dots{}, @var{labels})
@deftypefnx {Function File} {} pie (@var{h}, @dots{});
@deftypefnx {Function File} {@var{h} =} pie (@dots{});
Produce a pie chart.

Called with a single vector argument, produces a pie chart of the
elements in @var{x}, with the size of the slice determined by percentage
size of the values of @var{x}.

The variable @var{explode} is a vector of the same length as @var{x} that
if non zero 'explodes' the slice from the pie chart.

If given @var{labels} is a cell array of strings of the same length as
@var{x}, giving the labels of each of the slices of the pie chart.

The optional return value @var{h} provides a handle to the patch object.

@seealso{pie3, bar, stem}
@end deftypefn
pie3
@c pie3 scripts/plot/pie3.m
-*- texinfo -*-
@deftypefn  {Function File} {} pie3 (@var{x})
@deftypefnx {Function File} {} pie3 (@var{x}, @var{explode})
@deftypefnx {Function File} {} pie3 (@dots{}, @var{labels})
@deftypefnx {Function File} {} pie3 (@var{h}, @dots{});
@deftypefnx {Function File} {@var{h} =} pie3 (@dots{});
Draw a 3-D pie chart.

Called with a single vector argument, produces a 3-D pie chart of the
elements in @var{x}, with the size of the slice determined by percentage
size of the values of @var{x}.

The variable @var{explode} is a vector of the same length as @var{x} that
if non zero 'explodes' the slice from the pie chart.

If given @var{labels} is a cell array of strings of the same length as
@var{x}, giving the labels of each of the slices of the pie chart.

The optional return value @var{h} provides a handle list to patch, surface
and text objects generating this plot.

@seealso{pie, bar, stem}
@end deftypefn
plot
@c plot scripts/plot/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{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} plot (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} plot (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} plot (@dots{})
Produce two-dimensional 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 indices of the elements
starting with 1.

To save a plot, in one of several image formats such as PostScript
or PNG, use the @code{print} command.

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 the @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 vectors, the elements of @var{y} are plotted versus
the elements of @var{x}.

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

If both arguments are scalars, a single point is plotted.
@end itemize

Multiple property-value pairs may be specified, but they must appear
in pairs.  These arguments are applied to the lines drawn by
@code{plot}.

If the @var{fmt} argument is supplied, it is interpreted as
follows.  If @var{fmt} is missing, the default gnuplot line style
is assumed.

@table @samp
@item -
Set lines plot style (default).

@item .
Set dots plot style.

@item @var{n}
Interpreted as the plot color if @var{n} is an integer in the range 1 to
6.

@item @var{nm}
If @var{nm} is a two digit integer and @var{m} is an integer in the
range 1 to 6, @var{m} is interpreted as the point style.  This is only
valid in combination with the @code{@@} or @code{-@@} specifiers.

@item @var{c}
If @var{c} is one of @code{"k"} (black), @code{"r"} (red), @code{"g"}
(green), @code{"b"} (blue), @code{"m"} (magenta), @code{"c"} (cyan),
or @code{"w"} (white), it is interpreted as the line plot color.

@item ";title;"
Here @code{"title"} is the label for the key.

@item +
@itemx *
@itemx o
@itemx x
@itemx ^
Used in combination with the points or linespoints styles, set the point
style.

@item @@
Select the next unused point style.
@end table

The @var{fmt} argument may also be used to assign key titles.
To do so, include the desired title between semi-colons after the
formatting sequence described above, e.g., "+3;Key Title;"
Note that the last semi-colon is required and will generate an error if
it is left out.

Here are some plot examples:

@example
plot (x, y, "@@12", x, y2, x, y3, "4", x, y4, "+")
@end example

This command will plot @code{y} with points of type 2 (displayed as
@samp{+}) and color 1 (red), @code{y2} with lines, @code{y3} with lines of
color 4 (magenta) and @code{y4} with points displayed as @samp{+}.

@example
plot (b, "*", "markersize", 3)
@end example

This command will plot the data in the variable @code{b},
with points displayed as @samp{*} with a marker size of 3.

@example
@group
t = 0:0.1:6.3;
plot (t, cos(t), "-;cos(t);", t, sin(t), "+3;sin(t);");
@end group
@end example

This will plot the cosine and sine functions and label them accordingly
in the key.

If the first argument is an axis handle, then plot into these axes,
rather than the current axis handle returned by @code{gca}.

@seealso{semilogx, semilogy, loglog, polar, mesh, contour, bar,
stairs, errorbar, xlabel, ylabel, title, print}
@end deftypefn
plot3
@c plot3 scripts/plot/plot3.m
-*- texinfo -*-
@deftypefn {Function File} {} plot3 (@var{args})
Produce three-dimensional 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 the matrices 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{c})
@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{c})
@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

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

@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{plot, xlabel, ylabel, zlabel, title, print}
@end deftypefn
plotmatrix
@c plotmatrix scripts/plot/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{h}, @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

Given a single argument @var{x}, then 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 a leading axes handle @var{h} is passed to
@code{plotmatrix}, then this axis will be used for the plot.

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
@group
plotmatrix (randn (100, 3), 'g+')
@end group
@end example

@end deftypefn
plotyy
@c plotyy scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {[@var{ax}, @var{h1}, @var{h2}] =} plotyy (@dots{})
Plots two sets of data with independent y-axes.  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 given, @var{h} defines the principal axis in which to plot the @var{x1}
and @var{y1} data.  The return value @var{ax} is a two element vector with
the axis handles of the two plots.  @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
@end deftypefn
polar
@c polar scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} polar (@dots{})
Make a two-dimensional plot given the polar coordinates @var{theta} and
@var{rho}.

The optional third argument specifies the line type.
@seealso{plot}
@end deftypefn
print
@c print scripts/plot/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 graph, or save it to a file

@var{filename} defines the file 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 figure handle.  If no handle is specified
the handle for the current figure is used.

@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 graph 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 'gs' and 'gswin32c', respectively.

@item -color
@itemx -mono
  Monochrome or color output.

@item -solid
@itemx -dashed
  Forces 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 "paperposition" property in the
orientation specified.  This options is equivalent to changing
the figure's "paperorientation" property.

@item -d@var{device}
  Output device, where @var{device} 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 tex
@itemx epslatex
@itemx epslatexstandalone
@itemx pstex
@itemx pslatex
@itemx pdflatex
    Generate a @LaTeX{} (or @TeX{}) file for labels, and eps/ps/pdf
for graphics.  The file produced by @code{epslatexstandalone} can be
processed directly by @LaTeX{}.  The other formats are intended to
be included in a @LaTeX{} (or @TeX{}) document.  The @code{tex} device
is the same as the @code{epslatex} device.  The @code{pdflatex} device
is only available for the FLTK graphics toolkit.

@item tikz
    Generate a @LaTeX{} file using PGF/TikZ@.  For the FLTK 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 ljet2p
    HP LaserJet IIP

@item ljet3
    HP LaserJet III

@item deskjet
    HP DeskJet and DeskJet Plus

@item cdj550
    HP DeskJet 550C

@item paintjet
    HP PointJet

@item pcx24b
    24-bit color PCX file format

@item ppm
    Portable Pixel Map file format

@item pdfwrite
    Produces pdf output from eps
@end table

  For a complete list, type `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 "papersize" property.  When the output
is sent to a file the size is determined by the plot box defined by
the figure's "paperposition" property.

@itemx -append
  Appends the PS, or PDF output to a pre-existing file of the
same type.

@itemx -r@var{NUM}
  Resolution of bitmaps in pixels per inch.  For both metafiles and
SVG the default is the screen resolution, for other it is 150 dpi.
To specify screen resolution, use "-r0".

@item -tight
  Forces a tight bounding box for eps-files.

@item -@var{preview}
  Adds a preview to eps-files.  Supported formats are;

@table @code
@item -interchange
    Provides an interchange preview.

@item -metalfile
    Provides a metafile preview.

@item -pict
    Provides pict preview.

@item -tiff
    Provides 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 "paperposition" property.  Using the command form of
the print function, you must quote the @var{xsize},@var{ysize}
option.  For example, by writing @w{@code{"-S640,480"}}.

@item -F@var{fontname}
@itemx -F@var{fontname}:@var{size}
@itemx -F:@var{size}
  Associates all text with the @var{fontname} and/or @var{fontsize}.
@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 svg device.

@example
@group
figure (1)
clf ()
surf (peaks)
print -dsvg figure1.svg
@end group
@end example

Example: Print to an HP Deskjet 550C.

@example
@group
figure (1)
clf ()
surf (peaks)
print -dcdj550
@end group
@end example

@seealso{figure, orient, saveas}
@end deftypefn
quiver
@c quiver scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} quiver (@dots{})

Plot the @code{(@var{u}, @var{v})} components of a vector field in
an @code{(@var{x}, @var{y})} meshgrid.  If the grid is uniform, you can
specify @var{x} and @var{y} 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 1.

The style to use for the plot can be defined with a line style @var{style}
in a similar manner to the line styles used with the @code{plot} command.
If a marker is specified then markers at the grid points of the vectors are
printed rather than arrows.  If the argument 'filled' is given then the
markers as filled.

The optional return value @var{h} provides a quiver group that
regroups the components of the quiver plot (body, arrow and marker),
and allows them to be changed together

@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{plot}
@end deftypefn
quiver3
@c quiver3 scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} quiver3 (@dots{})

Plot the @code{(@var{u}, @var{v}, @var{w})} components of a vector field in
an @code{(@var{x}, @var{y}), @var{z}} meshgrid.  If the grid is uniform, you
can specify @var{x}, @var{y} @var{z} 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 1.

The style to use for the plot can be defined with a line style @var{style}
in a similar manner to the line styles used with the @code{plot} command.
If a marker is specified then markers at the grid points of the vectors are
printed rather than arrows.  If the argument 'filled' is given then the
markers as filled.

The optional return value @var{h} provides a quiver group that
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{plot}
@end deftypefn
refresh
@c refresh scripts/plot/refresh.m
-*- texinfo -*-
@deftypefn  {Function File} {} refresh ()
@deftypefnx {Function File} {} refresh (@var{h})
Refresh a figure, forcing it to be redrawn.  Called without an
argument the current figure is redrawn, otherwise the figure pointed
to by @var{h} is redrawn.
@seealso{drawnow}
@end deftypefn
refreshdata
@c refreshdata scripts/plot/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 called with one or more
arguments @var{h} is a scalar or array of figure handles to refresh.  The
optional second argument @var{workspace} can take the following values.

@table @asis
@item "base"
Evaluate the datasource properties in the base workspace.  (default).

@item "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
ribbon
@c ribbon scripts/plot/ribbon.m
-*- texinfo -*-
@deftypefn  {Function File} {} ribbon (@var{x}, @var{y}, @var{width})
@deftypefnx {Function File} {} ribbon (@var{y})
@deftypefnx {Function File} {@var{h} =} ribbon (@dots{})
Plot 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 (1:rows(Y)).  If requested, return a vector
@var{h} of the handles to the surface objects.
@seealso{gca, colorbar}
@end deftypefn
rose
@c rose scripts/plot/rose.m
-*- texinfo -*-
@deftypefn  {Function File} {} rose (@var{th}, @var{r})
@deftypefnx {Function File} {} rose (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} rose (@dots{})
@deftypefnx {Function File} {[@var{r}, @var{th}] =} rose (@dots{})

Plot an angular histogram.  With one vector argument @var{th}, plots the
histogram with 20 angular bins.  If @var{th} is a matrix, then each column
of @var{th} produces a separate histogram.

If @var{r} is given and is a scalar, then the histogram is produced with
@var{r} bins.  If @var{r} is a vector, then the center of each bin are
defined by the values of @var{r}.

The optional return value @var{h} provides a list of handles to the
the parts of the vector field (body, arrow and marker).

If two output arguments are requested, then rather than plotting the
histogram, the polar vectors necessary to plot the histogram are
returned.

@example
@group
[r, t] = rose ([2*randn(1e5,1), pi + 2 * randn(1e5,1)]);
polar (r, t);
@end group
@end example


@seealso{plot, compass, polar, hist}
@end deftypefn
saveas
@c saveas scripts/plot/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 @code{"pdf"}.

@example
@group
figure (1);
clf ();
surf (peaks);
saveas(1, "figure1.png");
@end group
@end example

@seealso{print}
@end deftypefn
scatter
@c scatter scripts/plot/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{c})
@deftypefnx {Function File} {} scatter (@var{x}, @var{y}, @var{s}, @var{c})
@deftypefnx {Function File} {} scatter (@var{x}, @var{y}, @var{s}, @var{c}, @var{style})
@deftypefnx {Function File} {} scatter (@var{x}, @var{y}, @var{s}, @var{c}, @var{prop}, @var{val})
@deftypefnx {Function File} {} scatter (@dots{}, "filled")
@deftypefnx {Function File} {} scatter (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} scatter (@dots{})

Plot a scatter plot of the data.  A marker is plotted at each point
defined by the points in the vectors @var{x} and @var{y}.  The size of
the markers used is determined by the @var{s}, which can be a scalar,
a vector of the same length of @var{x} and @var{y}.  If @var{s} is not
given or is an empty matrix, then the 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 a @var{n}-by-3 matrix defining
the colors of each of the markers 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 the argument @code{"filled"} is given then the markers as filled.  All
additional arguments are passed to the underlying patch command.

The optional return value @var{h} provides a handle to the patch object

@example
@group
x = randn (100, 1);
y = randn (100, 1);
scatter (x, y, [], sqrt(x.^2 + y.^2));
@end group
@end example

@seealso{plot, patch, scatter3}
@end deftypefn
scatter3
@c scatter3 scripts/plot/scatter3.m
-*- texinfo -*-
@deftypefn  {Function File} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s}, @var{c})
@deftypefnx {Function File} {} scatter3 (@dots{}, 'filled')
@deftypefnx {Function File} {} scatter3 (@dots{}, @var{style})
@deftypefnx {Function File} {} scatter3 (@dots{}, @var{prop}, @var{val})
@deftypefnx {Function File} {} scatter3 (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} scatter3 (@dots{})

Plot a scatter plot of the data in 3D@.  A marker is plotted at each point
defined by the points in the vectors @var{x}, @var{y} and @var{z}.  The size
of the markers used is determined by @var{s}, which can be a scalar or
a vector of the same length of @var{x}, @var{y} and @var{z}.  If @var{s} is
not given or is an empty matrix, then the 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 a @var{n}-by-3 matrix defining
the colors of each of the markers 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 the argument 'filled' is given then the markers as filled.  All
additional arguments are passed to the underlying patch command.

The optional return value @var{h} provides a handle to the patch object

@example
@group
[x, y, z] = peaks (20);
scatter3 (x(:), y(:), z(:), [], z(:));
@end group
@end example

@seealso{plot, patch, scatter}
@end deftypefn
semilogx
@c semilogx scripts/plot/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{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} semilogx (@dots{})
Produce a two-dimensional plot using a logarithmic scale for the @var{x}
axis.  See the documentation of @code{plot} for a description of the
arguments that @code{semilogx} will accept.
@seealso{plot, semilogy, loglog}
@end deftypefn
semilogxerr
@c semilogxerr scripts/plot/semilogxerr.m
-*- texinfo -*-
@deftypefn {Function File} {} semilogxerr (@var{args})
Produce two-dimensional plots using a logarithmic scale for the @var{x}
axis and errorbars at each data point.  Many different combinations of
arguments are possible.  The most used 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}.  See @code{errorbar} for available formats and
additional information.
@seealso{errorbar, loglogerr semilogyerr}
@end deftypefn
semilogy
@c semilogy scripts/plot/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 two-dimensional plot using a logarithmic scale for the @var{y}
axis.  See the documentation of @code{plot} for a description of the
arguments that @code{semilogy} will accept.
@seealso{plot, semilogx, loglog}
@end deftypefn
semilogyerr
@c semilogyerr scripts/plot/semilogyerr.m
-*- texinfo -*-
@deftypefn {Function File} {} semilogyerr (@var{args})
Produce two-dimensional plots using a logarithmic scale for the @var{y}
axis and errorbars at each data point.  Many different combinations of
arguments are possible.  The most used 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}.  See @code{errorbar} for available formats and
additional information.
@seealso{errorbar, loglogerr semilogxerr}
@end deftypefn
shading
@c shading scripts/plot/shading.m
-*- texinfo -*-
@deftypefn  {Function File} {} shading (@var{type})
@deftypefnx {Function File} {} shading (@var{ax}, @dots{})
Set the shading of surface or patch graphic objects.  Valid arguments
for @var{type} are

@table @asis
@item "flat"
Single colored patches with invisible edges.

@item "faceted"
Single colored patches with visible edges.

@item "interp"
Color between patch vertices are interpolated and the patch edges are
invisible.
@end table

If @var{ax} is given the shading is applied to axis @var{ax} instead
of the current axis.
@end deftypefn
shg
@c shg scripts/plot/shg.m
-*- texinfo -*-
@deftypefn {Command} {} shg
Show the graph window.  Currently, this is the same as executing
@code{drawnow}.
@seealso{drawnow, figure}
@end deftypefn
slice
@c slice scripts/plot/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} {@var{h} =} slice (@dots{})
@deftypefnx {Function File} {@var{h} =} slice (@dots{}, @var{method})
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 "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 "nearest"
Return the nearest neighbor.

@item "linear"
Linear interpolation from nearest neighbors.

@item "cubic"
Cubic interpolation from four nearest neighbors (not implemented yet).

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

The default method is @code{"linear"}.
The optional return value @var{h} is a vector of handles to the
surface graphic objects.

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/sombrero.m
-*- texinfo -*-
@deftypefn {Function File} {} sombrero (@var{n})
Produce the familiar three-dimensional sombrero plot using @var{n}
grid lines.  If @var{n} is omitted, a value of 41 is assumed.

The function plotted is

@example
z = sin (sqrt (x^2 + y^2)) / (sqrt (x^2 + y^2))
@end example
@seealso{surf, meshgrid, mesh}
@end deftypefn
specular
@c specular scripts/plot/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 specular reflection strength of a surface defined by the normal
vector elements @var{sx}, @var{sy}, @var{sz} using Phong's approximation.
The light and view vectors can be specified using parameter @var{lv} and
@var{vv} respectively.
Both can be given as 2-element vectors [azimuth, elevation] in degrees or as
3-element
vector [x, y, z].  An optional 6th argument describes the specular exponent
(spread) @var{se}.
@seealso{surfl, diffuse}
@end deftypefn
sphere
@c sphere scripts/plot/sphere.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{x}, @var{y}, @var{z}] =} sphere (@var{n})
@deftypefnx {Function File} {} sphere (@var{h}, @dots{})
Generates three matrices in @code{meshgrid} format, such that
@code{surf (@var{x}, @var{y}, @var{z})} generates a unit sphere.
The matrices of @code{@var{n}+1}-by-@code{@var{n}+1}.  If @var{n} is
omitted then a default value of 20 is assumed.

Called with no return arguments, @code{sphere} call directly
@code{surf (@var{x}, @var{y}, @var{z})}.  If an axes handle is passed
as the first argument, the surface is plotted to this set of axes.
@seealso{peaks}
@end deftypefn
spinmap
@c spinmap scripts/plot/spinmap.m
-*- texinfo -*-
@deftypefn {Function File} {} spinmap (@var{t}, @var{inc})
Cycle the colormap for @var{t} seconds with an increment
of @var{inc}.  Both parameters are optional.  The default cycle time
is 5 seconds and the default increment is 2.

A higher value of @var{inc} causes a faster cycle through the
colormap.
@seealso{gca, colorbar}
@end deftypefn
stairs
@c stairs scripts/plot/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})
@deftypefnx {Function File} {} stairs (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} stairs (@dots{})
@deftypefnx {Function File} {[@var{xstep}, @var{ystep}] =} stairs (@dots{})
Produce a stairstep plot.  The arguments 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.

If one output argument is requested, return a graphics handle to the 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{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, xlabel, ylabel, title}
@end deftypefn
stem
@c stem scripts/plot/stem.m
-*- texinfo -*-
@deftypefn  {Function File} {} stem (@var{x})
@deftypefnx {Function File} {} stem (@var{x}, @var{y})
@deftypefnx {Function File} {} stem (@var{x}, @var{y}, @var{linespec})
@deftypefnx {Function File} {} stem (@dots{}, "filled")
@deftypefnx {Function File} {@var{h} =} stem (@dots{})
Plot a stem graph from two vectors of x-y data.  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 @code{"b"} (blue).  The default line style is
@code{"-"} and the default marker is @code{"o"}.  The line style can
be altered by the @code{linespec} argument in the same manner as the
@code{plot} command.  For example,

@example
@group
x = 1:10;
y = ones (1, length (x))*2.*x;
stem (x, y, "r");
@end group
@end example

@noindent
plots 10 stems with heights from 2 to 20 in red;

The return value of @code{stem} is a vector of "stem series" graphics
handles, with one handle per column of the variable @var{y}.  This
handle regroups the elements of the stem graph together as the
children of the "stem series" handle, allowing them to be altered
together.  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 "stem series"  and moves the base line
of the first.
@seealso{bar, barh, plot}
@end deftypefn
stem3
@c stem3 scripts/plot/stem3.m
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} stem3 (@var{x}, @var{y}, @var{z}, @var{linespec})
Plot a three-dimensional stem graph and return the handles of the line
and marker objects used to draw the stems as "stem series" object.
The default color is @code{"r"} (red).  The default line style is
@code{"-"} and the default marker is @code{"o"}.

For 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.  Color
definitions with RGB-triples are not valid!
@seealso{bar, barh, stem, plot}
@end deftypefn
subplot
@c subplot scripts/plot/subplot.m
-*- texinfo -*-
@deftypefn  {Function File} {} subplot (@var{rows}, @var{cols}, @var{index})
@deftypefnx {Function File} {} subplot (@var{rcn})
Set up a plot grid with @var{rows} by @var{cols} subwindows and plot
in location given by @var{index}.

If only one argument is supplied, then it must be a three digit value
specifying the location in digits 1 (rows) and 2 (columns) and the plot
index in digit 3.

The plot index runs row-wise.  First all the columns in a row are filled
and then the next row is filled.

For example, a plot with 2 by 3 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
@seealso{plot}
@end deftypefn
surf
@c surf scripts/plot/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 (@var{hax}, @dots{})
@deftypefnx {Function File} {@var{h} =} surf (@dots{})
Plot a surface given matrices @var{x}, and @var{y} from @code{meshgrid} and
a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of
the mesh.  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.

The color of the surface is derived from the @code{colormap} and
the value of @var{z}.  Optionally the color of the surface can be
specified independent of @var{z}, by adding a fourth matrix, @var{c}.
@seealso{colormap, contour, meshgrid, mesh}
@end deftypefn
surface
@c surface scripts/plot/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})
@deftypefnx {Function File} {} surface (@var{h}, @dots{})
@deftypefnx {Function File} {@var{h} =} surface (@dots{})
Plot a surface graphic object given matrices @var{x}, and @var{y} from
@code{meshgrid} and a matrix @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 @var{x} and @var{y}
are missing, they are constructed from size of the matrix @var{z}.

Any additional properties passed are assigned to the surface.
@seealso{surf, mesh, patch, line}
@end deftypefn
surfc
@c surfc scripts/plot/surfc.m
-*- texinfo -*-
@deftypefn {Function File} {} surfc (@var{x}, @var{y}, @var{z})
Plot a surface and contour given matrices @var{x}, and @var{y} from
@code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and
@var{y} coordinates of the mesh.  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.
@seealso{meshgrid, surf, contour}
@end deftypefn
surfl
@c surfl scripts/plot/surfl.m
-*- texinfo -*-
@deftypefn  {Function File} {} surfl (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surfl (@var{z})
@deftypefnx {Function File} {} surfl (@var{x}, @var{y}, @var{z}, @var{L})
@deftypefnx {Function File} {} surfl (@var{x}, @var{y}, @var{z}, @var{L}, @var{P})
@deftypefnx {Function File} {} surfl (@dots{}, "light")
Plot a lighted surface given matrices @var{x}, and @var{y} from
@code{meshgrid} and
a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of
the mesh.  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.

The light direction can be specified using @var{L}.  It can be
given as 2-element vector [azimuth, elevation] in degrees or as 3-element
vector [lx, ly, lz].
The default value is rotated 45° counter-clockwise from 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 "AM" strength of ambient light

@item "D" strength of diffuse reflection

@item "SP" strength of specular reflection

@item "EXP" specular exponent
@end table

The default lighting mode "cdata", changes the cdata property to give the
impression
of a lighted surface.  Please note: the alternative "light" mode, which
creates a light
object to illuminate the surface is not implemented (yet).

Example:

@example
@group
colormap(bone);
surfl(peaks);
shading interp;
@end group
@end example
@seealso{surf, diffuse, specular, surface}
@end deftypefn
surfnorm
@c surfnorm scripts/plot/surfnorm.m
-*- texinfo -*-
@deftypefn  {Function File} {} surfnorm (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} surfnorm (@var{z})
@deftypefnx {Function File} {[@var{nx}, @var{ny}, @var{nz}] =} surfnorm (@dots{})
@deftypefnx {Function File} {} surfnorm (@var{h}, @dots{})
Find the vectors normal to a meshgridded surface.  The meshed gridded
surface is defined by @var{x}, @var{y}, and @var{z}.  If @var{x} and
@var{y} are not defined, then it is assumed that they are given by

@example
@group
[@var{x}, @var{y}] = meshgrid (1:size(@var{z}, 1),
                     1:size(@var{z}, 2));
@end group
@end example

If no return arguments are requested, a surface plot with the normal
vectors to the surface is plotted.  Otherwise the components of the normal
vectors at the mesh gridded points are returned in @var{nx}, @var{ny},
and @var{nz}.

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.

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

@example
surfnorm (peaks (25));
@end example
@seealso{surf, quiver3}
@end deftypefn
text
@c text scripts/plot/text.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{label})
@deftypefnx {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{z}, @var{label})
@deftypefnx {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{label}, @var{p1}, @var{v1}, @dots{})
@deftypefnx {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{z}, @var{label}, @var{p1}, @var{v1}, @dots{})
Create a text object with text @var{label} at position @var{x},
@var{y}, @var{z} on the current axes.  Property-value pairs following
@var{label} may be used to specify the appearance of the text.
@end deftypefn
title
@c title scripts/plot/title.m
-*- texinfo -*-
@deftypefn  {Function File} {} title (@var{string})
@deftypefnx {Function File} {} title (@var{string}, @var{p1}, @var{v1}, @dots{})
Create a title object and return a handle to it.
@end deftypefn
uigetdir
@c uigetdir scripts/plot/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 to select a directory.  If @var{init_path} is not given
the current working directory is used.  @var{dialog_name} optionally be
used to customize the dialog title.
@end deftypefn
uigetfile
@c uigetfile scripts/plot/uigetfile.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uigetfile (@var{flt})
@deftypefnx {Function File} {[@dots{}] =} uigetfile (@var{flt}, @var{dialog_name}, @var{default_file})
@deftypefnx {Function File} {[@dots{}] =} uigetfile (@var{flt}, @var{dialog_name})
@deftypefnx {Function File} {[@dots{}] =} uigetfile (@dots{}, "Position", [@var{px}, @var{py}])
@deftypefnx {Function File} {[@dots{}] =} uigetfile (@dots{}, "Multiselect", @var{mode})

Open a GUI dialog to select a file.  It returns 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 "/path/to/filename.ext"
If a filename is given the file extension is extracted and used as filter.
In addtion the path is selected as current path and the filname is selected
as default file.
Example: @code{uigetfile ("myfun.m")}

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

@item A 2-column cell array
containing the 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 it is selected in the GUI dialog.
If in addtion a path is given it is also used as current path.

The screen position of the GUI dialog can be set using the "Position" key
and a 2-element vector containing the pixel coordinates.
Two or more files can be selected when setting the "Multiselect" key to "on".
In that case @var{fname} is a cell array containing the files.
@end deftypefn
uimenu
@c uimenu scripts/plot/uimenu.m
-*- texinfo -*-
@deftypefn  {Function File} {} uimenu (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} uimenu (@var{h}, @var{property}, @var{value}, @dots{})
Create an uimenu object and return a handle to it.  If @var{h} is ommited
then a top level menu entry 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 "accelerator"
A string containg the key combination together with CTRL to execute this
menu entry (e.g., "x" for CTRL+x).

@item "callback"
Is the function called when this menu entry is executed.  It can be either a
function string (e.g., "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 "checked"
Can be set "on" or "off".  Sets a mark at this menu entry.

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

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

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

@item "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 "separator"
Can be set "on" or "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
uiputfile
@c uiputfile scripts/plot/uiputfile.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt}, @var{dialog_name}, @var{default_file})
@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})
@deftypefnx {Function File} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile ())
Open a GUI dialog to select a file.  @var{flt} contains a (list of) file
filter string(s) in one of the following formats:

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

@item "*.ext"
A single file extension.
Example: uiputfile("*.ext");

@item @{"*.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: uiputfile(@{"*.ext","My Description";"*.xyz","XYZ-Format"@});
@end table

The filter string can also contain a semicolon separated list of filter
extensions.
Example: 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 addtion a path is given it is also used as current path.
@end deftypefn
view
@c view scripts/plot/view.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{azimuth}, @var{elevation}] =} view ()
@deftypefnx  {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 (@var{dims})
@deftypefnx {Function File} {} view (@var{ax}, @dots{})
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 given with Cartesian coordinates @var{x},
@var{y}, and @var{z}.
The call @code{view (2)} sets the viewpoint to @var{azimuth} = 0
and @var{elevation} = 90, which is the default for 2-D graphs.
The call @code{view (3)} sets the viewpoint to @var{azimuth} = -37.5
and @var{elevation} = 30, which is the default for 3-D graphs.
If @var{ax} is given, the viewpoint is set for this axes, otherwise
it is set for the current axes.
@end deftypefn
waitforbuttonpress
@c waitforbuttonpress scripts/plot/waitforbuttonpress.m
-*- texinfo -*-
@deftypefn {Function File} {@var{b} =} waitforbuttonpress ()
Wait for button or mouse press.over a figure window.  The value of
@var{b} returns 0 if a mouse button was pressed or 1 is a key was
pressed.
@seealso{ginput}
@end deftypefn
whitebg
@c whitebg scripts/plot/whitebg.m
-*- texinfo -*-
@deftypefn  {Function File} {} whitebg ()
@deftypefnx {Function File} {} whitebg (@var{color})
@deftypefnx {Function File} {} whitebg ("none")
@deftypefnx {Function File} {} whitebg (@var{fig})
@deftypefnx {Function File} {} whitebg (@var{fig}, @var{color})
@deftypefnx {Function File} {} whitebg (@var{fig}, "none")
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 defined, @var{fig} is the handle to the figure to be inverted.  In
this case only the specified figure has its color properties changed.

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 "none" restores the plot to the default colors.
@seealso{reset}
@end deftypefn
xlabel
@c xlabel scripts/plot/xlabel.m
-*- texinfo -*-
@deftypefn  {Function File} {} xlabel (@var{string})
@deftypefnx {Function File} {} xlabel (@var{h}, @var{string})
@deftypefnx {Function File} {@var{h} =} xlabel (@dots{})
@deftypefnx {Function File} {} ylabel (@dots{})
@deftypefnx {Function File} {} zlabel (@dots{})
Specify x-, y-, or z-axis labels for the current axis.  If @var{h} is
specified then label the axis defined by @var{h}.  The optional return
value @var{h} provides a handle to the created label.
@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, stairs, title}
@end deftypefn
xlim
@c xlim scripts/plot/xlim.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{xl} =} xlim ()
@deftypefnx {Function File} {} xlim (@var{xl})
@deftypefnx {Function File} {@var{m} =} xlim ('mode')
@deftypefnx {Function File} {} xlim (@var{m})
@deftypefnx {Function File} {} xlim (@var{h}, @dots{})
Get or set the limits of the x-axis of the current plot.  Called without
arguments @code{xlim} returns the x-axis limits of the current plot.
If passed a two element vector @var{xl}, the limits of the x-axis are set
to this value.

The current mode for calculation of the x-axis can be returned with a
call @code{xlim ('mode')}, and can be either 'auto' or 'manual'.  The
current plotting mode can be set by passing either 'auto' or 'manual'
as the argument.

If passed a handle as the first argument, then operate on this handle
rather than the current axes handle.
@seealso{ylim, zlim, set, get, gca}
@end deftypefn
ylabel
@c ylabel scripts/plot/ylabel.m
-*- texinfo -*-
@deftypefn  {Function File} {} ylabel (@var{string})
@deftypefnx {Function File} {} ylabel (@var{h}, @var{string})
@deftypefnx {Function File} {@var{h} =} ylabel (@dots{})
@seealso{xlabel}
@end deftypefn
ylim
@c ylim scripts/plot/ylim.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{yl} =} ylim ()
@deftypefnx {Function File} {} ylim (@var{yl})
@deftypefnx {Function File} {@var{m} =} ylim ('mode')
@deftypefnx {Function File} {} ylim (@var{m})
@deftypefnx {Function File} {} ylim (@var{h}, @dots{})
Get or set the limits of the y-axis of the current plot.  Called without
arguments @code{ylim} returns the y-axis limits of the current plot.
If passed a two element vector @var{yl}, the limits of the y-axis are set
to this value.

The current mode for calculation of the y-axis can be returned with a
call @code{ylim ('mode')}, and can be either 'auto' or 'manual'.  The
current plotting mode can be set by passing either 'auto' or 'manual'
as the argument.

If passed a handle as the first argument, then operate on this handle
rather than the current axes handle.
@seealso{xlim, zlim, set, get, gca}
@end deftypefn
zlabel
@c zlabel scripts/plot/zlabel.m
-*- texinfo -*-
@deftypefn  {Function File} {} zlabel (@var{string})
@deftypefnx {Function File} {} zlabel (@var{h}, @var{string})
@deftypefnx {Function File} {@var{h} =} zlabel (@dots{})
@seealso{xlabel}
@end deftypefn
zlim
@c zlim scripts/plot/zlim.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{zl} =} zlim ()
@deftypefnx {Function File} {} zlim (@var{zl})
@deftypefnx {Function File} {@var{m} =} zlim ('mode')
@deftypefnx {Function File} {} zlim (@var{m})
@deftypefnx {Function File} {} zlim (@var{h}, @dots{})
Get or set the limits of the z-axis of the current plot.  Called without
arguments @code{zlim} returns the z-axis limits of the current plot.
If passed a two element vector @var{zl}, the limits of the z-axis are set
to this value.

The current mode for calculation of the z-axis can be returned with a
call @code{zlim ('mode')}, and can be either 'auto' or 'manual'.  The
current plotting mode can be set by passing either 'auto' or 'manual'
as the argument.

If passed a handle as the first argument, then operate on this handle
rather than the current axes handle.
@seealso{xlim, ylim, set, get, gca}
@end deftypefn
__actual_axis_position__
@c __actual_axis_position__ scripts/plot/private/__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
__add_datasource__
@c __add_datasource__ scripts/plot/private/__add_datasource__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{newargs} =} __add_datasource__ (@var{fcn}, @var{h}, @var{data}, @var{varargin})
Undocumented internal function.
@end deftypefn
__add_default_menu__
@c __add_default_menu__ scripts/plot/private/__add_default_menu__.m
-*- texinfo -*-
@deftypefn {Function File} {} __add_default_menu__ (@var{fig})
Adds default menu to figure.  All uimenu handles have
set their property "handlevisibility" to "off".
@end deftypefn
__axes_limits__
@c __axes_limits__ scripts/plot/private/__axes_limits__.m
-*- texinfo -*-
@deftypefn {Function File} {} __axes_limits__ (@var{fcn}, @dots{})
Undocumented internal function.
@end deftypefn
__axis_label__
@c __axis_label__ scripts/plot/private/__axis_label__.m
-*- texinfo -*-
@deftypefn {Function File} {} __axis_label__ (@var{caller}, @var{txt}, @dots{})
Undocumented internal function.
@end deftypefn
__bar__
@c __bar__ scripts/plot/private/__bar__.m
-*- texinfo -*-
@deftypefn {Function File} {} __bar__ (@var{vertical}, @var{func}, @dots{})
Undocumented internal function.
@end deftypefn
__clabel__
@c __clabel__ scripts/plot/private/__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
__color_str_rgb__
@c __color_str_rgb__ scripts/plot/private/__color_str_rgb__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{rgb} =} __color_str_rgb__ (@var{str})
Undocumented internal function.
@end deftypefn
__contour__
@c __contour__ scripts/plot/private/__contour__.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{c}, @var{hg}] =} __contour__ (@dots{})
Undocumented internal function.
@end deftypefn
__default_plot_options__
@c __default_plot_options__ scripts/plot/private/__default_plot_options__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{options} =} __default_plot_options__ ()
Undocumented internal function.
@end deftypefn
__errcomm__
@c __errcomm__ scripts/plot/private/__errcomm__.m
-*- texinfo -*-
@deftypefn {Function File} {} __errcomm__ (@var{caller}, @var{p}, @dots{})
Undocumented internal function.
@end deftypefn
__errplot__
@c __errplot__ scripts/plot/private/__errplot__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} __errplot__ (@var{fstr}, @var{p}, @dots{})
Undocumented internal function.
@end deftypefn
__ezplot__
@c __ezplot__ scripts/plot/private/__ezplot__.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{h}, @var{needusage}] =} __ezplot__ (@var{pfunc}, @var{varargin})
Undocumented internal function.
@end deftypefn
__fltk_file_filter__
@c __fltk_file_filter__ scripts/plot/private/__fltk_file_filter__.m
-*- texinfo -*-
@deftypefn {Function File} {} __fltk_file_filter__ (@var{file_filter})
Undocumented internal function.
@end deftypefn
__ghostscript__
@c __ghostscript__ scripts/plot/private/__ghostscript__.m
-*- texinfo -*-
@deftypefn {Function File} {} __ghostscript__ (@var{@dots{}})
Undocumented internal function.
@end deftypefn
__getlegenddata__
@c __getlegenddata__ scripts/plot/private/__getlegenddata__.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{hplots}, @var{strings}]} = __getlegenddata__ (@var{h})
Undocumented internal function.
@end deftypefn
__gnuplot_has_terminal__
@c __gnuplot_has_terminal__ scripts/plot/private/__gnuplot_has_terminal__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{has_terminal} =} __gnuplot_has_terminal__ (@var{terminal})
Undocumented internal function.
@end deftypefn
__interp_cube__
@c __interp_cube__ scripts/plot/private/__interp_cube__.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{vxyz}, @var{idx}, @var{frac}] =} __interp_cube__ (@var{x}, @var{y}, @var{z}, @var{val}, @var{v})
Undocumented internal function.
@end deftypefn
__line__
@c __line__ scripts/plot/private/__line__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} __line__ (@var{p}, @dots{})
Undocumented internal function.
@end deftypefn
__patch__
@c __patch__ scripts/plot/private/__patch__.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{h}, @var{fail}] =} __patch__ (@var{p}, @dots{})
Undocumented internal function.
@end deftypefn
__pie__
@c __pie__ scripts/plot/private/__pie__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{hlist} =} __pie__ (caller, @dots{})
Undocumented internal function.
@end deftypefn
__plt__
@c __plt__ scripts/plot/private/__plt__.m
-*- texinfo -*-
@deftypefn {Function File} {} __plt__ (@var{caller}, @var{h}, @var{varargin})
Undocumented internal function.
@end deftypefn
__pltopt__
@c __pltopt__ scripts/plot/private/__pltopt__.m
-*- texinfo -*-
@deftypefn {Function File} {} __pltopt__ (@var{caller}, @var{opt})
Undocumented internal function.
@end deftypefn
__quiver__
@c __quiver__ scripts/plot/private/__quiver__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{hg} =} __quiver__ (@dots{})
Undocumented internal function.
@end deftypefn
__scatter__
@c __scatter__ scripts/plot/private/__scatter__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{hg} =} __scatter__ (@dots{})
Undocumented internal function.
@end deftypefn
__stem__
@c __stem__ scripts/plot/private/__stem__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} __stem__ (@var{have_z}, @var{varargin})
Undocumented internal function.
@end deftypefn
__tight_eps_bbox__
@c __tight_eps_bbox__ scripts/plot/private/__tight_eps_bbox__.m
-*- texinfo -*-
@deftypefn {Function File} {@var{bbox} =} __tight_eps_bbox__ (@var{@dots{}})
Undocumented internal function.
@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{poly, roots, residue, conv, deconv, polyval, polyderiv,
polyint}
@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.

@code{c = conv (@var{a}, @var{b})} returns a vector of length equal to
@code{length (@var{a}) + length (@var{b}) - 1}.
If @var{a} and @var{b} are the coefficient vectors of two polynomials, the
returned value is the coefficient vector of the product polynomial.

The optional @var{shape} argument may be

@table @asis
@item @var{shape} = "full"
Return the full convolution.  (default)

@item @var{shape} = "same"
Return the central part of the convolution with the same size as @var{a}.
@end table

@seealso{deconv, fftconv, conv2, poly}
@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, poly, roots, residue, polyval, polyderiv, polyint}
@end deftypefn
mkpp
@c mkpp scripts/polynomial/mkpp.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{pp} =} mkpp (@var{x}, @var{p})
@deftypefnx {Function File} {@var{pp} =} mkpp (@var{x}, @var{p}, @var{d})

Construct a piecewise polynomial structure from sample points
@var{x} and coefficients @var{p}.  The i-th row of @var{p},
@code{@var{p} (@var{i},:)}, contains the coefficients for the polynomial
over the @var{i}-th interval, ordered from highest to
lowest.  There must be one row for each interval in @var{x}, so
@code{rows (@var{p}) == length (@var{x}) - 1}.

@var{p} may also be a multi-dimensional array, specifying a vector-valued
or array-valued polynomial.  The shape is determined by @var{d}.  If @var{d}
is
not given, the default is @code{size (p)(1:end-2)}.  If @var{d} is given, the
leading dimensions of @var{p} are reshaped to conform to @var{d}.

@seealso{unmkpp, ppval, spline}
@end deftypefn
mpoles
@c mpoles scripts/polynomial/mpoles.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{multp}, @var{indx}] =} mpoles (@var{p})
@deftypefnx {Function File} {[@var{multp}, @var{indx}] =} mpoles (@var{p}, @var{tol})
@deftypefnx {Function File} {[@var{multp}, @var{indx}] =} mpoles (@var{p}, @var{tol}, @var{reorder})
Identify unique poles in @var{p} and associates their multiplicity,
ordering them from largest to smallest.

If the relative difference of the 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 value @var{multp} is a vector specifying the multiplicity of the
poles.  @var{multp}(:) refers to multiplicity of @var{p}(@var{indx}(:)).

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{poly, roots, conv, deconv, polyval, polyderiv, polyint, residue}
@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})

Piecewise Cubic Hermite interpolating polynomial.  Called with two
arguments, the piecewise polynomial @var{pp} is returned, that may
later be used with @code{ppval} to evaluate the polynomial at
specific points.

The variable @var{x} must be a strictly monotonic vector (either
increasing or decreasing).  While @var{y} can be either a vector or
array.  In the case where @var{y} is a vector, it must have a length
of @var{n}.  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 then 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 in this matrix is then treated separately.  Note that this
is exactly the opposite treatment than @code{interp1} and is done
for compatibility.

Called with a third input argument, @code{pchip} evaluates the
piecewise polynomial at the points @var{xi}.  There is an equivalence
between @code{ppval (pchip (@var{x}, @var{y}), @var{xi})} and
@code{pchip (@var{x}, @var{y}, @var{xi})}.

@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
@result{} 1.00001 - 0.00001i
@result{} 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{eig, roots}
@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}
@end deftypefn
polyder
@c polyder scripts/polynomial/polyder.m
-*- texinfo -*-
@deftypefn  {Function File} {} polyderiv (@var{p})
@deftypefnx {Function File} {[@var{k}] =} polyderiv (@var{a}, @var{b})
@deftypefnx {Function File} {[@var{q}, @var{d}] =} polyderiv (@var{b}, @var{a})
An alias for @code{polyderiv}.
@seealso{polyderiv}
@end deftypefn
polyderiv
@c polyderiv scripts/polynomial/polyderiv.m
-*- texinfo -*-
@deftypefn  {Function File} {} polyderiv (@var{p})
@deftypefnx {Function File} {[@var{k}] =} polyderiv (@var{a}, @var{b})
@deftypefnx {Function File} {[@var{q}, @var{d}] =} polyderiv (@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{poly, polyint, polyreduce, roots, conv, deconv, residue,
filter, polygcd, polyval, polyvalm}
@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.

The polynomial coefficients are returned in a row vector.

The second output 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 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.

When the third output, @var{mu}, is present the
coefficients, @var{p}, are associated with a polynomial in
@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, residue}
@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.
Tolerance defaults to @code{sqrt(eps)}.

Note that this is a numerically unstable algorithm, and should not be used
on large polynomials.

Example:

@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, polyint, polyderiv, polyreduce, roots, conv, deconv,
residue, filter, polyval, polyvalm}
@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{poly, polyderiv, polyreduce, roots, conv, deconv, residue,
filter, polyval, polyvalm}
@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{})
Write 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
and return it as a string or write it to the screen (if
@var{nargout} is zero).
@var{x} defaults to the string @code{"s"}.
@seealso{polyval, polyvalm, poly, roots, conv, deconv, residue,
filter, polyderiv, polyint}
@end deftypefn
polyreduce
@c polyreduce scripts/polynomial/polyreduce.m
-*- texinfo -*-
@deftypefn {Function File} {} polyreduce (@var{c})
Reduces a polynomial coefficient vector to a minimum number of terms by
stripping off any leading zeros.
@seealso{poly, roots, conv, deconv, residue, filter, polyval,
polyvalm, polyderiv, polyint}
@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})
Evaluate the polynomial @var{p} at the specified values of @var{x}.  When
@var{mu} is present evaluate the polynomial for
(@var{x}-@var{mu}(1))/@var{mu}(2).
If @var{x} is a vector or matrix, the polynomial is evaluated for each of
the elements of @var{x}.
@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})
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
form `polyfit', must be present.
@seealso{polyfit, polyvalm, poly, roots, conv, deconv, residue, filter,
polyderiv, polyint}
@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 is used in polyval.

The argument @var{x} must be a square matrix.
@seealso{polyval, poly, roots, conv, deconv, residue, filter,
polyderiv, polyint}
@end deftypefn
ppval
@c ppval scripts/polynomial/ppval.m
-*- texinfo -*-
@deftypefn {Function File} {@var{yi} =} ppval (@var{pp}, @var{xi})
Evaluate piecewise polynomial @var{pp} at the points @var{xi}.
If @var{pp} is scalar-valued, the result is an array of the same shape as
@var{xi}.
Otherwise, the size of the result is @code{[pp.d, length(@var{xi})]} if
@var{xi} is a vector, or @code{[pp.d, size(@var{xi})]} if it is a
multi-dimensional array.  If pp.orient is 1, the dimensions are permuted as
in interp1, to
@code{[pp.d, length(@var{xi})]} and @code{[pp.d, size(@var{xi})]}
respectively.
@seealso{mkpp, unmkpp, spline}
@end deftypefn
ppder
@c ppder scripts/polynomial/ppder.m
-*- texinfo -*-
@deftypefn {Function File} {@var{ppd} =} ppder (@var{pp})
Compute the piecewise derivative of the piecewise polynomial struct @var{pp}.
@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})
Compute the partial fraction expansion for the quotient of the
polynomials, @var{b} and @var{a}.
@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

@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})
Compute 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{poly, roots, conv, deconv, mpoles, polyval, polyderiv, polyint}
@end deftypefn
roots
@c roots scripts/polynomial/roots.m
-*- texinfo -*-
@deftypefn {Function File} {} roots (@var{v})

For a vector @var{v} with @math{N} components, return
the roots of the polynomial
@tex
$$
v_1 z^{N-1} + \cdots + v_{N-1} z + v_N.
$$
@end tex
@ifnottex

@example
v(1) * z^(N-1) + @dots{} + v(N-1) * z + v(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{compan}
@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 @var{y} at points @var{x}.
If called with two arguments, @code{spline} returns the piecewise
polynomial @var{pp} that may later be used with @code{ppval} to
evaluate the polynomial at specific points.
If called with a third input argument, @code{spline} evaluates the
spline at the points @var{xi}.  There is an equivalence
between @code{ppval (spline (@var{x}, @var{y}), @var{xi})} and
@code{spline (@var{x}, @var{y}, @var{xi})}.

The variable @var{x} must be a vector of length @var{n}, and @var{y}
can be either a vector or array.  In the case where @var{y} is a
vector, it can have a length of either @var{n} or @code{@var{n} + 2}.
If the length of @var{y} is @var{n}, then the '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 end-points.

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 then 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 treatment than @code{interp1} and is done
for compatibility.
@seealso{ppval, mkpp, unmkpp}
@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}.
These are as follows:

@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}
@end deftypefn
intersect
@c intersect scripts/set/intersect.m
-*- texinfo -*-
@deftypefn  {Function File} {} intersect (@var{a}, @var{b})
@deftypefnx {Function File} {[@var{c}, @var{ia}, @var{ib}] =} intersect (@var{a}, @var{b})

Return the elements in both @var{a} and @var{b}, sorted in ascending
order.  If @var{a} and @var{b} are both column vectors return a column
vector, otherwise return a row vector.
@var{a}, @var{b} may be cell arrays of string(s).

Return index vectors @var{ia} and @var{ib} such that @code{a(ia)==c} and
@code{b(ib)==c}.

@end deftypefn
@seealso{unique, union, setxor, setdiff, ismember}
ismember
@c ismember scripts/set/ismember.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{tf} =} ismember (@var{A}, @var{s})
@deftypefnx {Function File} {[@var{tf}, @var{S_idx}] =} ismember (@var{A}, @var{s})
@deftypefnx {Function File} {[@var{tf}, @var{S_idx}] =} ismember (@var{A}, @var{s}, "rows")
Return a logical matrix @var{tf} with the same shape as @var{A} which is
true (1) if @code{A(i,j)} is in @var{s} and false (0) if it is not.  If a
second output argument is requested, the index into @var{s} of each of the
matching elements 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

With the optional third argument @code{"rows"}, and matrices
@var{A} and @var{s} with the same number of columns, compare rows in
@var{A} with the rows in @var{s}.

@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{unique, union, intersect, setxor, setdiff}
@end deftypefn
powerset
@c powerset scripts/set/powerset.m
-*- texinfo -*-
@deftypefn  {Function File} {} powerset (@var{a})
@deftypefnx {Function File} {} powerset (@var{a}, "rows")

Return a cell array containing all subsets of the set @var{a}.

@end deftypefn
@seealso{unique, union, setxor, setdiff, ismember}
setdiff
@c setdiff scripts/set/setdiff.m
-*- texinfo -*-
@deftypefn  {Function File} {} setdiff (@var{a}, @var{b})
@deftypefnx {Function File} {} setdiff (@var{a}, @var{b}, "rows")
@deftypefnx {Function File} {[@var{c}, @var{i}] =} setdiff (@var{a}, @var{b})
Return the elements in @var{a} that are not in @var{b}, sorted in
ascending order.  If @var{a} and @var{b} are both column vectors
return a column vector, otherwise return a row vector.
@var{a}, @var{b} may be cell arrays of string(s).

Given the optional third argument @samp{"rows"}, return the rows in
@var{a} that are not in @var{b}, sorted in ascending order by rows.

If requested, return @var{i} such that @code{c = a(i)}.
@seealso{unique, union, intersect, setxor, ismember}
@end deftypefn
setxor
@c setxor scripts/set/setxor.m
-*- texinfo -*-
@deftypefn  {Function File} {} setxor (@var{a}, @var{b})
@deftypefnx {Function File} {} setxor (@var{a}, @var{b}, 'rows')

Return the elements exclusive to @var{a} or @var{b}, sorted in ascending
order.  If @var{a} and @var{b} are both column vectors return a column
vector, otherwise return a row vector.
@var{a}, @var{b} may be cell arrays of string(s).

@deftypefnx {Function File} {[@var{c}, @var{ia}, @var{ib}] =} setxor (@var{a}, @var{b})

Return index vectors @var{ia} and @var{ib} such that @code{a(ia)} and
@code{b(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} {} union (@var{a}, @var{b})
@deftypefnx {Function File} {} union (@var{a}, @var{b}, "rows")
Return the set of elements that are in either of the sets @var{a} and
@var{b}.  @var{a}, @var{b} may be cell arrays of string(s).
For example:

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

If the optional third input argument is the string "rows" each row of
the matrices @var{a} and @var{b} will be considered an element of sets.
For example:

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

@deftypefnx {Function File} {[@var{c}, @var{ia}, @var{ib}] =} union (@var{a}, @var{b})

Return index vectors @var{ia} and @var{ib} such that @code{a(ia)} and
@code{b(ib)} are
disjoint sets whose union is @var{c}.

@seealso{intersect, setdiff, unique}
@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} {} unique (@dots{}, "first")
@deftypefnx {Function File} {} unique (@dots{}, "last")
@deftypefnx {Function File} {[@var{y}, @var{i}, @var{j}] =} unique (@dots{})
Return the unique elements of @var{x}, sorted in ascending order.
If the input @var{x} is a vector then the output is also a vector with the
same orientation (row or column) as the input.  For a matrix input the
output is always a column vector.  @var{x} may also be a cell array of
strings.

If the optional argument @code{"rows"} is supplied, return the unique
rows of @var{x}, sorted in ascending order.

If requested, return index vectors @var{i} and @var{j} such that
@code{x(i)==y} and @code{y(j)==x}.

Additionally, if @var{i} is a requested output then one of @code{"first"} or
@code{"last"} may be given as an input.  If @code{"last"} is specified,
return the highest possible indices in @var{i}, otherwise, if @code{"first"}
is specified, return the lowest.  The default is @code{"last"}.
@seealso{union, intersect, setdiff, setxor, ismember}
@end deftypefn
validargs
@c validargs scripts/set/private/validargs.m
Validate arguments for binary set operation.
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 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}.  I.e., 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

@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.  I.e., 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., 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})
Return the filter coefficients of a Blackman window of length @var{m}.

For a definition of the Blackman window, see e.g., 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 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 @t{"constant"} (corresponds to @code{@var{p}=0}) or
@t{"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: 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 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}, @var{n})

With two arguments, @code{fftfilt} filters @var{x} with the FIR filter
@var{b} using the FFT.

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.

If @var{x} is a matrix, filter each column of the matrix.
@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 of @math{Dt} each, then @code{fftshift (fft
(@var{x}))} corresponds to frequencies

@example
f = ((1:N) - ceil(N/2)) / N / Dt
@end example

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.
@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 'full'
pad @var{x} with zeros on all sides before filtering.

@item 'same'
unpadded @var{x} (default)

@item '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")
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 the fourth argument is omitted, the response is evaluated at
frequencies between 0 and
@ifnottex
 pi.
@end ifnottex
@tex
 $\pi$.
@end tex

If @var{n} is omitted, a value of 512 is assumed.

If @var{a} is omitted, the denominator is assumed to be 1 (this
corresponds to a simple FIR filter).

For fastest computation, @var{n} should factor into a small number of
small primes.

@deftypefnx {Function File} {@var{h} =} 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.

@deftypefnx {Function File} {[@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.

@deftypefnx {Function File} {} freqz (@dots{})
Plot the pass band, stop band and phase response of @var{h} rather
than returning them.
@end deftypefn
freqz_plot
@c freqz_plot scripts/signal/freqz_plot.m
-*- texinfo -*-
@deftypefn {Function File} {} freqz_plot (@var{w}, @var{h})
Plot the pass band, stop band and phase response of @var{h}.
@end deftypefn
hamming
@c hamming scripts/signal/hamming.m
-*- texinfo -*-
@deftypefn {Function File} {} hamming (@var{m})
Return the filter coefficients of a Hamming window of length @var{m}.

For a definition of the Hamming window, see e.g., 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})
Return the filter coefficients of a Hanning window of length @var{m}.

For a definition of this window type, see e.g., 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 single 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.
@end deftypefn
periodogram
@c periodogram scripts/signal/periodogram.m
-*- texinfo -*-
@deftypefn {Function File} {[Pxx, @var{w}] =} periodogram (@var{x})
For a data matrix @var{x} from a sample of size @var{n}, return the
periodogram.  The angular frequency is returned in @var{w}.

[Pxx,w] = periodogram (@var{x}).

[Pxx,w] = periodogram (@var{x},win).

[Pxx,w] = periodogram (@var{x},win,nfft).

[Pxx,f] = periodogram (@var{x},win,nfft,Fs).

[Pxx,f] = periodogram (@var{x},win,nfft,Fs,"range").

@itemize
@item x: data; if real-valued a one-sided spectrum is estimated,
if complex-valued or range indicates "@nospell{twosided}", the full
spectrum is estimated.

@item win: weight data with window, x.*win is used for further computation,
if window is empty, a rectangular window is used.

@item nfft: number of frequency bins, default max(256, 2.^ceil(log2(length(x)))).

@item Fs: sampling rate, default 1.

@item range: "@nospell{onesided}" computes spectrum from [0..nfft/2+1].
"@nospell{twosided}" computes spectrum from [0..nfft-1].  These strings
can appear at any  position in the list input arguments after window.

@item Pxx: one-, or two-sided power spectrum.

@item w: angular frequency [0..2*pi) (two-sided) or [0..pi] one-sided.

@item f: frequency [0..Fs) (two-sided) or [0..Fs/2] one-sided.
@end itemize
@end deftypefn
rectangle_lw
@c rectangle_lw scripts/signal/rectangle_lw.m
-*- texinfo -*-
@deftypefn {Function File} {} rectangle_lw (@var{n}, @var{b})
Rectangular lag window.  Subfunction used for spectral density
estimation.
@end deftypefn
rectangle_sw
@c rectangle_sw scripts/signal/rectangle_sw.m
-*- texinfo -*-
@deftypefn {Function File} {} rectangle_sw (@var{n}, @var{b})
Rectangular spectral window.  Subfunction used for spectral density
estimation.
@end deftypefn
sinc
@c sinc scripts/signal/sinc.m
-*- texinfo -*-
@deftypefn {Function File} {} sinc (@var{x})
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 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.

Defaults are @var{rate} = 8000, @var{sec} = 1 and @var{ampl} = 64.
@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}.
@end deftypefn
spectral_adf
@c spectral_adf scripts/signal/spectral_adf.m
-*- texinfo -*-
@deftypefn {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., @code{"triangle"} or @code{"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.
@end deftypefn
spectral_xdf
@c spectral_xdf scripts/signal/spectral_xdf.m
-*- texinfo -*-
@deftypefn {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., @code{"triangle"} or @code{"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.
@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}, @var{c}] =} stft (@var{x}, @var{win_size}, @var{inc}, @var{num_coef}, @var{win_type})
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 @nospell{hanning}
win_type = 1

@item @nospell{hamming}
win_type = 2

@item rectangle
win_type = 3
@end table

The window names can be passed as strings or by the @var{win_type} number.

If not all arguments are specified, the following defaults are used:
@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
synthesis function.
@end deftypefn
synthesis
@c synthesis scripts/signal/synthesis.m
-*- texinfo -*-
@deftypefn {Function File} {} 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
@end deftypefn
triangle_lw
@c triangle_lw scripts/signal/triangle_lw.m
-*- texinfo -*-
@deftypefn {Function File} {} triangle_lw (@var{n}, @var{b})
Triangular lag window.  Subfunction used for spectral density
estimation.
@end deftypefn
triangle_sw
@c triangle_sw scripts/signal/triangle_sw.m
-*- texinfo -*-
@deftypefn {Function File} {} triangle_sw (@var{n}, @var{b})
Triangular spectral window.  Subfunction used for spectral density
estimation.
@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
bicgstab
@c bicgstab scripts/sparse/bicgstab.m
-*- texinfo -*-
@deftypefn  {Function File} {} bicgstab (@var{A}, @var{b})
@deftypefnx {Function File} {} bicgstab (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0})
This procedure attempts to solve a system of linear equations A*x = b for x.
The @var{A} must be square, symmetric and positive definite real matrix N*N.
The @var{b} must be a one column vector with a length of N.
The @var{tol} specifies the tolerance of the method, the default value is
1e-6.
The @var{maxit} specifies the maximum number of iterations, the default value
is min(20,N).
The @var{M1} specifies a preconditioner, can also be a function handler which
returns M\X.
The @var{M2} combined with @var{M1} defines preconditioner as
preconditioner=M1*M2.
The @var{x0} is the initial guess, the default value is zeros(N,1).

The value @var{x} is a computed result of this procedure.
The value @var{flag} can be 0 when we reach tolerance in @var{maxit}
iterations, 1 when
we don't reach tolerance in @var{maxit} iterations and 3 when the procedure
stagnates.
The value @var{relres} is a relative residual - norm(b-A*x)/norm(b).
The value @var{iter} is an iteration number in which x was computed.
The value @var{resvec} is a vector of @var{relres} for each iteration.

@end deftypefn
cgs
@c cgs scripts/sparse/cgs.m
-*- texinfo -*-
@deftypefn  {Function File} {} cgs (@var{A}, @var{b})
@deftypefnx {Function File} {} cgs (@var{A}, @var{b}, @var{tol}, @var{maxit}, @var{M1}, @var{M2}, @var{x0})
This procedure attempts to solve a system of linear equations A*x = b for x.
The @var{A} must be square, symmetric and positive definite real matrix N*N.
The @var{b} must be a one column vector with a length of N.
The @var{tol} specifies the tolerance of the method, default value is 1e-6.
The @var{maxit} specifies the maximum number of iteration, default value is
MIN(20,N).
The @var{M1} specifies a preconditioner, can also be a function handler which
returns M\X.
The @var{M2} combined with @var{M1} defines preconditioner as
preconditioner=M1*M2.
The @var{x0} is initial guess, default value is zeros(N,1).

@end deftypefn
colperm
@c colperm scripts/sparse/colperm.m
-*- texinfo -*-
@deftypefn {Function File} {@var{p} =} colperm (@var{s})
Returns the column permutations such that the columns of
@code{@var{s} (:, @var{p})} are ordered in terms of increase number
of non-zero 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 non zeros elements.
@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
@code{@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
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
nonzeros
@c nonzeros scripts/sparse/nonzeros.m
-*- texinfo -*-
@deftypefn {Function File} {} nonzeros (@var{s})
Returns a vector of the non-zero values of the sparse matrix @var{s}.
@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{})

Solves the linear system of equations @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 @code{@var{A} * @var{x}}.  In principle
@var{A} should be symmetric and positive definite; if @code{pcg}
finds @var{A} to not be positive definite, 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{pcg} has less
arguments, a default value equal to 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}
@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 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 @code{[]} is supplied for @var{m1}, or @var{m1} is omitted, no
preconditioning is applied.  If @var{m2} is omitted, @var{m} = @var{m1}
will be used as preconditioner.

@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{pcg}.  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 that
the (preconditioned) matrix was found not 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 @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, q] = luinc (A, 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
Y. Saad, @cite{Iterative Methods for Sparse Linear Systems}, 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{})

Solves 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 t
@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] W. Hackbusch, @cite{Iterative Solution of Large Sparse Systems of
     Equations}, section 9.5.4; Springer, 1994

@seealso{sparse, pcg}
@end deftypefn
spaugment
@c spaugment scripts/sparse/spaugment.m
-*- texinfo -*-
@deftypefn {Function File} {@var{s} =} spaugment (@var{A}, @var{c})
Creates 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 under determined
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.
@end deftypefn
spconvert
@c spconvert scripts/sparse/spconvert.m
-*- texinfo -*-
@deftypefn {Function File} {@var{x} =} spconvert (@var{m})
This function converts for a simple sparse matrix format easily
produced by other programs into Octave's internal sparse format.  The
input @var{x} 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.
@end deftypefn
spdiags
@c spdiags scripts/sparse/spdiags.m
-*- texinfo -*-
@deftypefn  {Function File} {[@var{b}, @var{c}] =} spdiags (@var{A})
@deftypefnx {Function File} {@var{b} =} spdiags (@var{A}, @var{c})
@deftypefnx {Function File} {@var{b} =} spdiags (@var{v}, @var{c}, @var{A})
@deftypefnx {Function File} {@var{b} =} spdiags (@var{v}, @var{c}, @var{m}, @var{n})
A generalization of the function @code{diag}.  Called with a single
input argument, the non-zero diagonals @var{c} of @var{A} are extracted.
With two arguments the diagonals to extract are given by the vector
@var{c}.

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 columns represented by the vector @var{c}.  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 @var{v}.

Negative values of @var{c} represent diagonals below the main
diagonal, and positive values of @var{c} 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

@end deftypefn
speye
@c speye scripts/sparse/speye.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{y} =} speye (@var{m})
@deftypefnx {Function File} {@var{y} =} speye (@var{m}, @var{n})
@deftypefnx {Function File} {@var{y} =} speye (@var{sz})
Returns a sparse identity matrix.  This 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.  Otherwise a matrix of @var{m} by @var{n} is
created.  If called with a single vector argument, this argument
is taken to be the size of the matrix to create.
@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 non-zero 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 non-zero entries of @var{S} with ones.  This creates a
sparse matrix with the same structure as @var{S}.
@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{s})
Generate a random sparse matrix.  The size of the matrix will be
@var{m} by @var{n}, with a density of values given by @var{d}.
@var{d} should be between 0 and 1.  Values will be uniformly
distributed between 0 and 1.

Note: sometimes the actual density may be a bit smaller than @var{d}.
This is unlikely to happen for large, truly sparse, matrices.

If called with a single matrix argument, a random sparse matrix is
generated wherever the matrix @var{S} is non-zero.
@seealso{sprandn}
@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{s})
Generate a random sparse matrix.  The size of the matrix will be
@var{m} by @var{n}, with a density of values given by @var{d}.
@var{d} should be between 0 and 1. Values will be normally
distributed with mean of zero and variance 1.

Note: sometimes the actual density may be a bit smaller than @var{d}.
This is unlikely to happen for large really sparse matrices.

If called with a single matrix argument, a random sparse matrix is
generated wherever the matrix @var{S} is non-zero.
@seealso{sprand}
@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} by @var{n}, with a density of values given by @var{d}.
@var{d} should be between 0 and 1. Values will be normally
distributed with mean of zero and variance 1.

Note: sometimes the actual density may be a bit smaller than @var{d}.
This is unlikely to happen for large really sparse matrices.

If called with a single matrix argument, a random sparse matrix is
generated wherever the matrix @var{S} is non-zero in its lower
triangular part.
@seealso{sprand, sprandn}
@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 non-zero elements of the sparse matrix @var{S}.
@var{count} is the number of non-zeros in each column, @var{mean}
is the mean of the non-zeros in each column, and @var{var} is the
variance of the non-zeros 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 an 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}
@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 '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, optional 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})
Produces a graph of tree or forest.  The first argument is vector of
predecessors, optional parameters @var{node_style} and @var{edge_style}
define the output 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 @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 @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 @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
@code{exp (-I*@var{x})} for @var{k} = 1 or @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})
For real inputs, return the Beta function,
@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
@end deftypefn
betaln
@c betaln scripts/specfun/betaln.m
-*- texinfo -*-
@deftypefn {Mapping Function} {} betaln (@var{a}, @var{b})
Return the natural logarithm of the Beta function,
@tex
$$
 B (a, b) = \log {\Gamma (a) \Gamma (b) \over \Gamma (a + b)}.
$$
@end tex
@ifnottex

@example
betaln (a, b) = gammaln (a) + gammaln (b) - gammaln (a + b)
@end example

@end ifnottex
@seealso{beta, betainc, gammaln}
@end deftypefn
factor
@c factor scripts/specfun/factor.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{p} =} factor (@var{q})
@deftypefnx {Function File} {[@var{p}, @var{n}] =} factor (@var{q})

Return prime factorization of @var{q}.  That is,
@code{prod (@var{p}) == @var{q}} and every element of @var{p} is a prime
number.  If @code{@var{q} == 1}, return 1.

With two output arguments, return the unique primes @var{p} and
their multiplicities.  That is, @code{prod (@var{p} .^ @var{n}) ==
@var{q}}.
@seealso{gcd, lcm}
@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 positive 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}.
@seealso{prod, gamma}
@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.

If the maximum value in @var{x} is very large, then you should be using
special purpose factorization code.

@example
@group
isprime (1:6)
    @result{} [0, 1, 1, 0, 1, 0]
@end group
@end example
@seealso{primes, factor, gcd, lcm}
@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{} N@.  The optional argument, @var{normalization},
may be one of @code{"unnorm"}, @code{"sch"}, or @code{"norm"}.
The default is @code{"unnorm"}.  The value of @var{n} must be a
non-negative scalar integer.

If the optional argument @var{normalization} is missing or is
@code{"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

If the optional argument @code{normalization} is @code{"sch"},
compute the Schmidt semi-normalized associated Legendre function.
The Schmidt semi-normalized associated Legendre function is related
to the unnormalized Legendre functions by the following:

For Legendre functions of degree n and order 0:

@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

If the optional argument @var{normalization} is @code{"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})

Compute the binomial coefficient or all combinations of @var{n}.
If @var{n} is a scalar then, calculate 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!}
               = {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

If @var{n} is a vector generate all combinations of the elements
of @var{n}, taken @var{k} at a time, one row per combination.  The
resulting @var{c} has size @code{[nchoosek (length (@var{n}),
@var{k}), @var{k}]}.

@code{nchoosek} works only for non-negative integer arguments; use
@code{bincoeff} for non-integer scalar arguments and for using vector
arguments to compute many coefficients at once.

@seealso{bincoeff}
@end deftypefn
nthroot
@c nthroot scripts/specfun/nthroot.m
-*- texinfo -*-
@deftypefn {Function File} {} nthroot (@var{x}, @var{n})

Compute the n-th root of @var{x}, returning real results for real
components of @var{x}.  For example:

@example
@group
nthroot (-1, 3)
@result{} -1
(-1) ^ (1 / 3)
@result{} 0.50000 - 0.86603i
@end group
@end example

@var{n} must be a scalar.  If @var{n} is not an even integer and @var{X} has
negative entries, an error is produced.
@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}, one row per permutation.  The
result has size @code{factorial (@var{n}) * @var{n}}, where @var{n}
is the length of @var{v}.

As an example, @code{perms([1, 2, 3])} returns the matrix

@example
@group
  1   2   3
  2   1   3
  1   3   2
  2   3   1
  3   1   2
  3   2   1
@end group
@end example
@end deftypefn
pow2
@c pow2 scripts/specfun/pow2.m
-*- texinfo -*-
@deftypefn  {Mapping Function} {} pow2 (@var{x})
@deftypefnx {Mapping Function} {} pow2 (@var{f}, @var{e})
With one argument, computes
@tex
$2^x$
@end tex
@ifnottex
2 .^ x
@end ifnottex
for each element of @var{x}.

With two arguments, returns
@tex
$f \cdot 2^e$.
@end tex
@ifnottex
f .* (2 .^ e).
@end ifnottex
@seealso{log2, nextpow2}
@end deftypefn
primes
@c primes scripts/specfun/primes.m
-*- texinfo -*-
@deftypefn {Function File} {} primes (@var{n})

Return all primes up to @var{n}.

The algorithm used is the Sieve of Eratosthenes.

Note that 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
@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}.  Report
an error if any element results in a complex return value.
@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{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}.  Report an
error if any element results in a complex return value.
@seealso{sqrt, realpow, reallog}
@end deftypefn
hadamard
@c hadamard scripts/special-matrix/hadamard.m
-*- texinfo -*-
@deftypefn {Function File} {} hadamard (@var{n})
Construct a Hadamard matrix @var{Hn} of size @var{n}-by-@var{n}.  The
size @var{n} must be of the form @code{2 ^ @var{k} * @var{p}} in which
@var{p} is one of 1, 12, 20 or 28.  The returned matrix is normalized,
meaning @code{Hn(:,1) == 1} and @code{Hn(1,:) == 1}.

Some of the properties of Hadamard matrices are:

@itemize @bullet
@item
@code{kron (@var{Hm}, @var{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 @var{Hn} are orthogonal.

@item
@code{det (@var{A}) <= abs(det (@var{Hn}))} for all @var{A} with
@code{abs (@var{A} (@var{i}, @var{j})) <= 1}.

@item
Multiply any row or column by -1 and still have a Hadamard matrix.
@end itemize

@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 given 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{vander, sylvester_matrix, hilb, invhilb, 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
@tex
$i,\,j$
@end tex
@ifnottex
i, j
@end ifnottex
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
@seealso{hankel, vander, sylvester_matrix, invhilb, toeplitz}
@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 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, hankel, vander, sylvester_matrix, toeplitz}
@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.  Note that @code{magic
(@var{2})} is undefined since there is no 2-by-2 magic square.

@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}.
@var{t} defaults to 0.  Return lower triangular Cholesky@tie{}factor of
the Pascal matrix if @code{@var{t} = 1}.  This matrix is its own
inverse, that is @code{pascal (@var{n}, 1) ^ 2 == eye (@var{n})}.
If @code{@var{t} = -1}, return its absolute value.  This is the
standard Pascal triangle as a lower-triangular matrix.
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{hankel, vander, sylvester_matrix, hilb, invhilb, toeplitz
         hadamard, wilkinson, compan, rosser}
@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{hankel, vander, sylvester_matrix, hilb, invhilb, toeplitz
         hadamard, wilkinson, compan, pascal}
@end deftypefn
sylvester_matrix
@c sylvester_matrix scripts/special-matrix/sylvester_matrix.m
-*- texinfo -*-
@deftypefn {Function File} {} sylvester_matrix (@var{k})
Return the Sylvester matrix of order
@tex
$n = 2^k$.
@end tex
@ifnottex
n = 2^k.
@end ifnottex
@seealso{hankel, vander, hilb, invhilb, toeplitz}
@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 given the first column @var{c},
and (optionally) the first row @var{r}.  If the first element of @var{c}
is not the same as the first element of @var{r}, 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, vander, sylvester_matrix, hilb, invhilb}
@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{hankel, sylvester_matrix, hilb, invhilb, toeplitz}
@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.

@seealso{hankel, vander, sylvester_matrix, hilb, invhilb, toeplitz
          hadamard, rosser, compan, pascal}
@end deftypefn
__finish__
@c __finish__ scripts/startup/__finish__.m
-*- texinfo -*-
@deftypefn {Function File} {} __finish__ ()
Undocumented internal function.
@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})
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.
@seealso{studentize}
@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}, 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
cor
@c cor scripts/statistics/base/cor.m
-*- texinfo -*-
@deftypefn  {Function File} {} cor (@var{x})
@deftypefnx {Function File} {} cor (@var{x}, @var{y})
Compute matrix of correlation coefficients.

This is an alias for @code{corrcoef}.
@seealso{corrcoef}
@end deftypefn
corrcoef
@c corrcoef scripts/statistics/base/corrcoef.m
-*- texinfo -*-
@deftypefn  {Function File} {} corrcoef (@var{x})
@deftypefnx {Function File} {} corrcoef (@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{corrcoef (@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 corrcoef}(x,y) = {{\rm cov}(x,y) \over {\rm std}(x) {\rm std}(y)}
$$
@end tex
@ifnottex

@example
corrcoef(x,y) = cov(x,y)/(std(x)*std(y))
@end example

@end ifnottex
If called with one argument, compute @code{corrcoef (@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
@seealso{corrcoef, cor}
@end deftypefn
cut
@c cut scripts/statistics/base/cut.m
-*- texinfo -*-
@deftypefn {Function File} {} cut (@var{x}, @var{breaks})
Create categorical data from numerical or continuous data by
cutting into intervals.

If @var{breaks} is a scalar, the data is cut into that many
equal-width intervals.  If @var{breaks} is a vector of break points,
the category has @code{length (@var{breaks}) - 1} groups.

The returned value is a vector of the same size as @var{x} telling
which group each point in @var{x} belongs to.  Groups are labelled
from 1 to the number of groups; points outside the range of
@var{breaks} are labelled by @code{NaN}.
@seealso{histc}
@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 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{})
Produce 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{dim})
Compute the kurtosis of the elements of the vector @var{x}.
@tex
$$
 {\rm kurtosis} (x) = {1\over N \sigma^4} \sum_{i=1}^N (x_i-\bar{x})^4 - 3
$$
where $\bar{x}$ is the mean value of $x$.
@end tex
@ifnottex

@example
kurtosis (x) = N^(-1) std(x)^(-4) sum ((x - mean(x)).^4) - 3
@end example

@end ifnottex
If @var{x} is a matrix, return the kurtosis over the
first non-singleton dimension of the matrix.  If the optional
@var{dim} argument is given, operate along this dimension.

Note: The definition of kurtosis above yields a kurtosis of zero for the
stdnormal distribution and is sometimes referred to as "excess kurtosis".
To calculate kurtosis without the normalization factor of @math{-3} use
@code{moment (@var{x}, 4, 'c') / std (@var{x})^4}.
@seealso{var,skewness,moment}
@end deftypefn
logit
@c logit scripts/statistics/base/logit.m
-*- texinfo -*-
@deftypefn {Function File} {} logit (@var{p})
For each component of @var{p}, return the logit of @var{p} 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{logistic_cdf}
@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}, which 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}.
@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.

The optional argument @var{opt} selects the type of mean to compute.
The following options are recognized:

@table @asis
@item "a"
Compute the (ordinary) arithmetic mean.  [default]

@item "g"
Compute the geometric mean.

@item "h"
Compute the harmonic mean.
@end table

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

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}.
@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
std (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}.
If 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
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 moment of the vector @var{x} about zero.
@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

If @var{x} is a matrix, return the row vector containing the
@var{p}-th moment of each column.

The optional string @var{type} specifies the type of moment to be computed.
Valid options are:
@table @asis
@item "c"
  Central Moment.  The moment about the mean defined as
@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

@item "a"
  Absolute 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

@item "ac"
  Absolute Central Moment.  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
@end table

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

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 for 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 arguments are given, the data are plotted directly.
@end deftypefn
prctile
@c prctile scripts/statistics/base/prctile.m
-*- texinfo -*-
@deftypefn  {Function File} {@var{y} =} 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{y}, corresponding
to the cumulative probability values, @var{p}, in percent.  All non-numeric
values (NaNs) of @var{x} are ignored.

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

The optional argument @var{dim} determines the dimension along which
the percentiles are calculated.  If @var{dim} is omitted, and @var{x} is
a vector or matrix, it defaults to 1 (column-wise quantiles).  When
@var{x} is an N-d array, @var{dim} defaults to the first non-singleton
dimension.
@seealso{quantile}
@end deftypefn
probit
@c probit scripts/statistics/base/probit.m
-*- texinfo -*-
@deftypefn {Function File} {} probit (@var{p})
For each component of @var{p}, return the probit (the quantile of the
standard normal distribution) of @var{p}.
@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{dist})
@deftypefnx {Function File} {[@var{q}, @var{s}] =} qqplot (@var{x}, @var{dist}, @var{params})
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.

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, "uniform", 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}, @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}.

The optional argument @var{dim} determines the dimension along which
the quantiles are calculated.  If @var{dim} is omitted, and @var{x} is
a vector or matrix, it defaults to 1 (column-wise quantiles).  If
@var{x} is an N-d array, @var{dim} defaults to the first non-singleton
dimension.

The methods available to calculate sample quantiles are the nine methods
used by R (http://www.r-project.org/).  The default value is 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

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 Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New
S Language.  Wadsworth & Brooks/Cole.

@item 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
@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.
@end deftypefn
skewness
@c skewness scripts/statistics/base/skewness.m
-*- texinfo -*-
@deftypefn  {Function File} {} skewness (@var{x})
@deftypefnx {Function File} {} skewness (@var{x}, @var{dim})
Compute the skewness of the elements of the vector @var{x}.
@tex
$$
{\rm skewness} (x) = {1\over N \sigma^3} \sum_{i=1}^N (x_i-\bar{x})^3
$$
where $\bar{x}$ is the mean value of $x$.
@end tex
@ifnottex

@example
skewness (x) = N^(-1) std(x)^(-3) sum ((x - mean(x)).^3)
@end example

@end ifnottex

@noindent
If @var{x} is a matrix, return the skewness along the
first non-singleton dimension of the matrix.  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}.
@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
studentize
@c studentize scripts/statistics/base/studentize.m
-*- texinfo -*-
@deftypefn  {Function File} {} studentize (@var{x})
@deftypefnx {Function File} {} studentize (@var{x}, @var{dim})
If @var{x} is a vector, subtract its mean and divide by its standard
deviation.

If @var{x} is a matrix, do the above along the first non-singleton
dimension.
If the optional argument @var{dim} is given, operate along this dimension.
@seealso{center}
@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}.
@tex
$$
{\rm std} (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
std (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 the optional argument @var{dim} is given, operate along this dimension.
@seealso{cov,std,skewness,kurtosis,moment}
@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}, returns the CDF at @var{x} of the beta
distribution with parameters @var{a} and @var{b}, i.e.,
PROB (beta (@var{a}, @var{b}) @leq{} @var{x}).
@end deftypefn
betainv
@c betainv scripts/statistics/distributions/betainv.m
-*- texinfo -*-
@deftypefn {Function File} {} betainv (@var{x}, @var{a}, @var{b})
For each component 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}, returns the 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}, @var{r}, @var{c})
@deftypefnx {Function File} {} betarnd (@var{a}, @var{b}, @var{sz})
Return an @var{r} by @var{c} or @code{size (@var{sz})} matrix of
random samples from the Beta distribution with parameters @var{a} and
@var{b}.  Both @var{a} and @var{b} must be scalar or of size @var{r}
 by @var{c}.

If @var{r} and @var{c} are omitted, the size of 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 CDF at @var{x} of the
binomial distribution with parameters @var{n} and @var{p}.
@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 at @var{x} of the
binomial distribution with parameters @var{n} and @var{p}.
@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}.
@end deftypefn
binornd
@c binornd scripts/statistics/distributions/binornd.m
-*- texinfo -*-
@deftypefn  {Function File} {} binornd (@var{n}, @var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} binornd (@var{n}, @var{p}, @var{sz})
Return an @var{r} by @var{c}  or a @code{size (@var{sz})} matrix of
random samples from the binomial distribution with parameters @var{n}
and @var{p}.  Both @var{n} and @var{p} must be scalar or of size
@var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of 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}, @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}, @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}, @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}, @var{r}, @var{c})
@deftypefnx {Function File} {} cauchy_rnd (@var{location}, @var{scale}, @var{sz})
Return an @var{r} by @var{c} or a @code{size (@var{sz})} matrix of
random samples from the Cauchy distribution with parameters @var{location}
and @var{scale} which must both be scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of 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 chisquare 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 chisquare 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 chisquare distribution with @var{n} degrees
of freedom.
@end deftypefn
chi2rnd
@c chi2rnd scripts/statistics/distributions/chi2rnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} chi2rnd (@var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} chi2rnd (@var{n}, @var{sz})
Return an @var{r} by @var{c}  or a @code{size (@var{sz})} matrix of
random samples from the chisquare distribution with @var{n} degrees
of freedom.  @var{n} must be a scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of 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 component 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{n}, @var{v}, @var{p})
@deftypefnx {Function File} {} discrete_rnd (@var{v}, @var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} discrete_rnd (@var{v}, @var{p}, @var{sz})
Generate a row vector containing a random sample of size @var{n} from
the univariate distribution which assumes the values in @var{v} with
probabilities @var{p}.  @var{n} must be a scalar.

If @var{r} and @var{c} are given create a matrix with @var{r} rows and
@var{c} columns.  Or if @var{sz} is a vector, create a matrix of size
@var{sz}.
@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{n}, @var{data})
@deftypefnx {Function File} {} empirical_rnd (@var{data}, @var{r}, @var{c})
@deftypefnx {Function File} {} empirical_rnd (@var{data}, @var{sz})
Generate a bootstrap sample of size @var{n} from the empirical
distribution obtained from the univariate sample @var{data}.

If @var{r} and @var{c} are given create a matrix with @var{r} rows and
@var{c} columns.  Or if @var{sz} is a vector, create a matrix of size
@var{sz}.
@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 scalar.
@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) 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}, @var{r}, @var{c})
@deftypefnx {Function File} {} exprnd (@var{lambda}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
exponential distribution with mean @var{lambda}, which must be a
scalar or of size @var{r} by @var{c}.  Or if @var{sz} is a vector,
create a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of 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 CDF at @var{x} of the F
distribution with @var{m} and @var{n} degrees of freedom, i.e.,
PROB (F (@var{m}, @var{n}) @leq{} @var{x}).
@end deftypefn
finv
@c finv scripts/statistics/distributions/finv.m
-*- texinfo -*-
@deftypefn {Function File} {} finv (@var{x}, @var{m}, @var{n})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the F distribution with parameters @var{m} and
@var{n}.
@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}, @var{r}, @var{c})
@deftypefnx {Function File} {} frnd (@var{m}, @var{n}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the F
distribution with @var{m} and @var{n} degrees of freedom.  Both
@var{m} and @var{n} must be scalar or of size @var{r} by @var{c}.
If @var{sz} is a vector the random samples are in a matrix of
size @var{sz}.

If @var{r} and @var{c} are omitted, the size of 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 parameters
@var{a} and @var{b}.
@seealso{gamma, gammaln, gammainc, gampdf, gaminv, gamrnd}
@end deftypefn
gaminv
@c gaminv scripts/statistics/distributions/gaminv.m
-*- texinfo -*-
@deftypefn {Function File} {} gaminv (@var{x}, @var{a}, @var{b})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the Gamma distribution with parameters @var{a}
and @var{b}.
@seealso{gamma, gammaln, gammainc, gampdf, gamcdf, gamrnd}
@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 parameters @var{a}
and @var{b}.
@seealso{gamma, gammaln, gammainc, gamcdf, gaminv, gamrnd}
@end deftypefn
gamrnd
@c gamrnd scripts/statistics/distributions/gamrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} gamrnd (@var{a}, @var{b}, @var{r}, @var{c})
@deftypefnx {Function File} {} gamrnd (@var{a}, @var{b}, @var{sz})
Return an @var{r} by @var{c} or a @code{size (@var{sz})} matrix of
random samples from the Gamma distribution with parameters @var{a}
and @var{b}.  Both @var{a} and @var{b} must be scalar or of size
@var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{a} and @var{b}.
@seealso{gamma, gammaln, gammainc, gampdf, gamcdf, gaminv}
@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 CDF at @var{x} of the
geometric distribution with parameter @var{p}.
@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 at @var{x} of the
geometric distribution with parameter @var{p}.
@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}.
@end deftypefn
geornd
@c geornd scripts/statistics/distributions/geornd.m
-*- texinfo -*-
@deftypefn  {Function File} {} geornd (@var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} geornd (@var{p}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
geometric distribution with parameter @var{p}, which must be a scalar
or of size @var{r} by @var{c}.

If @var{r} and @var{c} are given create a matrix with @var{r} rows and
@var{c} columns.  Or if @var{sz} is a vector, create a matrix of size
@var{sz}.
@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 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 at @var{x} of the
hypergeometric distribution with parameters @var{t}, @var{m}, and
@var{n}.

The parameters @var{t}, @var{m}, and @var{n} must 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 arguments must be of common size or scalar.
@end deftypefn
hygernd
@c hygernd scripts/statistics/distributions/hygernd.m
-*- texinfo -*-
@deftypefn  {Function File} {} hygernd (@var{t}, @var{m}, @var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} hygernd (@var{t}, @var{m}, @var{n}, @var{sz})
@deftypefnx {Function File} {} hygernd (@var{t}, @var{m}, @var{n})
Return an @var{r} by @var{c} 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 positive integers
with @var{m} and @var{n} not greater than @var{t}.

The parameter @var{sz} must be scalar or a vector of matrix
dimensions.  If @var{sz} is scalar, then a @var{sz} by @var{sz}
matrix of random samples is generated.
@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 CDF at @var{x} of the Kolmogorov-Smirnov distribution,
@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}, @var{c})
@deftypefnx {Function File} {} laplace_rnd (@var{sz});
Return an @var{r} by @var{c} matrix of random numbers from the
Laplace distribution.  Or if @var{sz} is a vector, create a matrix of
@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 component of @var{x}, compute the 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 component 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 component 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}, @var{c})
@deftypefnx {Function File} {} logistic_rnd (@var{sz})
Return an @var{r} by @var{c} matrix of random numbers from the
logistic distribution.  Or if @var{sz} is a vector, create a matrix of
@var{sz}.
@end deftypefn
logncdf
@c logncdf scripts/statistics/distributions/logncdf.m
-*- texinfo -*-
@deftypefn {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} = 1, @var{sigma} = 1.
@end deftypefn
logninv
@c logninv scripts/statistics/distributions/logninv.m
-*- texinfo -*-
@deftypefn {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 @code{log (@var{mu})} and
variance @var{sigma}.

Default values are @var{mu} = 1, @var{sigma} = 1.
@end deftypefn
lognpdf
@c lognpdf scripts/statistics/distributions/lognpdf.m
-*- texinfo -*-
@deftypefn {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} = 1, @var{sigma} = 1.
@end deftypefn
lognrnd
@c lognrnd scripts/statistics/distributions/lognrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} lognrnd (@var{mu}, @var{sigma}, @var{r}, @var{c})
@deftypefnx {Function File} {} lognrnd (@var{mu}, @var{sigma}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
lognormal distribution with parameters @var{mu} and @var{sigma}.  Both
@var{mu} and @var{sigma} must be scalar or of size @var{r} by @var{c}.
Or if @var{sz} is a vector, create a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of 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 CDF at x of the Pascal
(negative binomial) distribution with parameters @var{n} and @var{p}.

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 at @var{x} of the
Pascal (negative binomial) distribution with parameters @var{n} and
@var{p}.

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 Pascal (negative binomial) distribution with
parameters @var{n} and @var{p}.

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}, @var{r}, @var{c})
@deftypefnx {Function File} {} nbinrnd (@var{n}, @var{p}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the Pascal
(negative binomial) distribution with parameters @var{n} and @var{p}.
Both @var{n} and @var{p} must be scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{n} and @var{p}.  Or if @var{sz} is a vector,
create a matrix of size @var{sz}.
@end deftypefn
normcdf
@c normcdf scripts/statistics/distributions/normcdf.m
-*- texinfo -*-
@deftypefn {Function File} {} normcdf (@var{x}, @var{m}, @var{s})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the normal distribution with mean
@var{m} and standard deviation @var{s}.

Default values are @var{m} = 0, @var{s} = 1.
@end deftypefn
norminv
@c norminv scripts/statistics/distributions/norminv.m
-*- texinfo -*-
@deftypefn {Function File} {} norminv (@var{x}, @var{m}, @var{s})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the normal distribution with mean @var{m} and
standard deviation @var{s}.

Default values are @var{m} = 0, @var{s} = 1.
@end deftypefn
normpdf
@c normpdf scripts/statistics/distributions/normpdf.m
-*- texinfo -*-
@deftypefn {Function File} {} normpdf (@var{x}, @var{m}, @var{s})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the normal distribution with mean @var{m} and
standard deviation @var{s}.

Default values are @var{m} = 0, @var{s} = 1.
@end deftypefn
normrnd
@c normrnd scripts/statistics/distributions/normrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} normrnd (@var{m}, @var{s}, @var{r}, @var{c})
@deftypefnx {Function File} {} normrnd (@var{m}, @var{s}, @var{sz})
Return an @var{r} by @var{c}  or @code{size (@var{sz})} matrix of
random samples from the normal distribution with parameters mean @var{m}
and standard deviation @var{s}.  Both @var{m} and @var{s} must be scalar
or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{m} and @var{s}.
@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
lambda.
@end deftypefn
poissinv
@c poissinv scripts/statistics/distributions/poissinv.m
-*- texinfo -*-
@deftypefn {Function File} {} poissinv (@var{x}, @var{lambda})
For each component 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}, @var{r}, @var{c})
Return an @var{r} by @var{c} matrix of random samples from the
Poisson distribution with parameter @var{lambda}, which must be a
scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of 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 component of @var{x}, compute the CDF of the standard normal
distribution at @var{x}.
@end deftypefn
stdnormal_inv
@c stdnormal_inv scripts/statistics/distributions/stdnormal_inv.m
-*- texinfo -*-
@deftypefn {Function File} {} stdnormal_inv (@var{x})
For each component of @var{x}, compute the quantile (the
inverse of the CDF) at @var{x} of the standard normal distribution.
@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) of the standard normal distribution at @var{x}.
@end deftypefn
stdnormal_rnd
@c stdnormal_rnd scripts/statistics/distributions/stdnormal_rnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} stdnormal_rnd (@var{r}, @var{c})
@deftypefnx {Function File} {} stdnormal_rnd (@var{sz})
Return an @var{r} by @var{c} or @code{size (@var{sz})} matrix of
random numbers from the standard normal distribution.
@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, i.e., PROB (t(@var{n}) @leq{} @var{x}).
@end deftypefn
tinv
@c tinv scripts/statistics/distributions/tinv.m
-*- texinfo -*-
@deftypefn {Function File} {} tinv (@var{x}, @var{n})
For each probability value @var{x}, compute the inverse of the
cumulative distribution function (CDF) of the t (Student)
distribution with degrees of freedom @var{n}.  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}, @var{r}, @var{c})
@deftypefnx {Function File} {} trnd (@var{n}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the t
(Student) distribution with @var{n} degrees of freedom.  @var{n} must
be a scalar or of size @var{r} by @var{c}.  Or if @var{sz} is a
vector create a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of 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{mx});
@deftypefnx {Function File} {} unidrnd (@var{mx}, @var{v});
@deftypefnx {Function File} {} unidrnd (@var{mx}, @var{m}, @var{n}, @dots{});
Return random values from discrete uniform distribution, with maximum
value(s) given by the integer @var{mx}, which may be a scalar or
multi-dimensional array.

If @var{mx} is a scalar, the size of the result is specified by
the vector @var{v}, or by the optional arguments @var{m}, @var{n},
@dots{}.  Otherwise, the size of the result is the same as the size
of @var{mx}.
@end deftypefn
unidcdf
@c unidcdf scripts/statistics/distributions/unidcdf.m
-*- texinfo -*-
@deftypefn {Function File} {} unidcdf (@var{x}, @var{v})
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 equal probability.
@end deftypefn
unidinv
@c unidinv scripts/statistics/distributions/unidinv.m
-*- texinfo -*-
@deftypefn {Function File} {} unidinv (@var{x}, @var{v})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the univariate discrete distribution which assumes the
values in @var{v} with equal probability
@end deftypefn
unidpdf
@c unidpdf scripts/statistics/distributions/unidpdf.m
-*- texinfo -*-
@deftypefn {Function File} {} unidpdf (@var{x}, @var{v})
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 equal probability.
@end deftypefn
unifrnd
@c unifrnd scripts/statistics/distributions/unifrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} unifrnd (@var{a}, @var{b}, @var{r}, @var{c})
@deftypefnx {Function File} {} unifrnd (@var{a}, @var{b}, @var{sz})
Return an @var{r} by @var{c} or a @code{size (@var{sz})} matrix of
random samples from the uniform distribution on [@var{a}, @var{b}].
Both @var{a} and @var{b} must be scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of 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}, @var{a}, @var{b})
Return the CDF at @var{x} of the uniform distribution on [@var{a},
@var{b}], i.e., PROB (uniform (@var{a}, @var{b}) @leq{} x).

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}, @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 [@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}, @var{a}, @var{b})
For each element of @var{x}, compute the PDF at @var{x} of the uniform
distribution on [@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}, @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}, which is
@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.
@end ifnottex
@end deftypefn
wblinv
@c wblinv scripts/statistics/distributions/wblinv.m
-*- texinfo -*-
@deftypefn {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}.
@end deftypefn
wblpdf
@c wblpdf scripts/statistics/distributions/wblpdf.m
-*- texinfo -*-
@deftypefn {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} which 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.
@end deftypefn
wblrnd
@c wblrnd scripts/statistics/distributions/wblrnd.m
-*- texinfo -*-
@deftypefn  {Function File} {} wblrnd (@var{scale}, @var{shape}, @var{r}, @var{c})
@deftypefnx {Function File} {} wblrnd (@var{scale}, @var{shape}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
Weibull distribution with parameters @var{scale} and @var{shape}
which must be scalar or of size @var{r} by @var{c}.  Or if @var{sz}
is a vector return a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{alpha} and @var{sigma}.
@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} gives 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
logistic_regression_derivatives
@c logistic_regression_derivatives scripts/statistics/models/logistic_regression_derivatives.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{dl}, @var{d2l}] =} logistic_regression_derivatives (@var{x}, @var{z}, @var{z1}, @var{g}, @var{g1}, @var{p})
Called by logistic_regression.  Calculates derivates of the
log-likelihood for ordinal logistic regression model.
@end deftypefn
logistic_regression_likelihood
@c logistic_regression_likelihood scripts/statistics/models/logistic_regression_likelihood.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{g}, @var{g1}, @var{p}, @var{dev}] =} logistic_regression_likelihood (@var{y}, @var{x}, @var{beta}, @var{z}, @var{z1})
Calculates likelihood for the ordinal logistic regression model.
Called by logistic_regression.
@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.
@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 @code{"!="} or @code{"<>"} (non-zero),
@code{">"} (greater than 0), or @code{"<"} (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
@code{"pearson"} (default), the (usual) Pearson's product 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
@code{"kendall"}, then Kendall's rank correlation tau is used.  If
@var{method} is @code{"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 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 dist.  I.e.,
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{dist_cdf}
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 @code{"!="} or
@code{"<>"}, 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 @code{">"}, the
one-sided alternative F > G is considered.  Similarly for @code{"<"},
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.  I.e., 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 @code{"!="} or
@code{"<>"}, 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 @code{">"}, the
one-sided alternative F > G is considered.  Similarly for @code{"<"},
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 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 "Use of Ranks in One-Criterion Variance Analysis"
in Journal of the American Statistical Association, Vol. 47,
No. 260 (Dec 1952) by William H. Kruskal and W. Allen Wallis.

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 (Wilks' Lambda) and approximate p-values are
computed and displayed.
@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, 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 @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@var{p1} != @var{p2}.  If @var{alt} is @code{">"}, the one-sided
alternative @var{p1} > @var{p2} is used.  Similarly for @code{"<"},
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}.  Can be used to test 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 @code{"!="} or @code{"<>"}, the
null hypothesis is tested against the two-sided alternative PROB
(@var{x} < @var{y}) != 1/2.  If @var{alt} is @code{">"}, the
one-sided alternative PROB (@var{x} > @var{y}) > 1/2 ("x is
stochastically greater than y") is considered.  Similarly for
@code{"<"}, 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 @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != @var{m}}.  If @var{alt} is @code{">"}, 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 @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != mean (@var{y})}.  If @var{alt} is @code{">"},
the one-sided alternative @code{mean (@var{x}) > mean (@var{y})} is
used.  Similarly for @code{"<"}, 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 an t test for the null hypothesis @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 @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{@var{rr} * @var{b} != @var{r}}.  If @var{alt} is @code{">"}, the
one-sided alternative @code{@var{rr} * @var{b} > @var{r}} is used.
Similarly for @var{"<"}, the one-sided alternative @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 @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
PROB (@var{x} > @var{y}) != 1/2.  If @var{alt} is @code{">"}, the
one-sided alternative PROB (@var{x} > @var{y}) > 1/2 is considered.
Similarly for @code{"<"}, 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 @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{var (@var{x}) != var (@var{y})}.  If @var{alt} is @code{">"},
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 @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != @var{m}}.  If @var{alt} is @code{">"}, the
one-sided alternative mean(x) > @var{m} is considered.  Similarly for
@code{"<"}, 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{Warning}: 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 @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
PROB (@var{x} > @var{y}) != 1/2.  If alt is @code{">"}, the one-sided
alternative PROB (@var{x} > @var{y}) > 1/2 is considered.  Similarly
for @code{"<"}, 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 @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != @var{m}}.  If @var{alt} is @code{">"}, the
one-sided alternative @code{mean (@var{x}) > @var{m}} is considered.
Similarly for @code{"<"}, 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 @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != mean (@var{y})}.  If alt is @code{">"}, the
one-sided alternative @code{mean (@var{x}) > mean (@var{y})} is used.
Similarly for @code{"<"}, 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 matrix, returns a column vector with one value per
row of @var{s}.  If a row contains invalid symbols then the
corresponding value will be NaN@.  Rows are right-justified before
converting so that trailing spaces are ignored.

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

If @var{s} is a string matrix, return a column vector of converted
numbers, one per row of @var{s}.  Invalid rows evaluate to NaN.
@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
deblank
@c deblank scripts/strings/deblank.m
-*- texinfo -*-
@deftypefn {Function File} {} deblank (@var{s})
Remove trailing blanks 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, operate recursively on each
element of the cell array.
@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 vector, return a string matrix with one row per value,
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 vector, returns a string matrix, one row per value,
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 vector, return a string matrix, one row per value,
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}, @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 nonzero, the returned vector
can include overlapping positions (this is the default).  For example:

@example
@group
findstr ("ababab", "a")
     @result{} [1, 3, 5]
findstr ("abababa", "aba", 0)
     @result{} [1, 5]
@end group
@end example
@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, returns a column vector of converted
numbers, one per row of @var{s}.  Invalid rows evaluate to NaN.
@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.  For example:

@example
@group
index ("Teststring", "t")
     @result{} 4
@end group
@end example

If @var{direction} is @samp{"first"}, return the first element found.
If @var{direction} is @samp{"last"}, return the last element found.
The @code{rindex} function is equivalent to @code{index} with
@var{direction} set to @samp{"last"}.

@strong{Caution:}  This function does not work for arrays of
character strings.
@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 "alpha"
True for characters that are alphabetic (letters).

@item "alnum"
@itemx "alphanum"
True for characters that are alphabetic or digits.

@item "lower"
True for lower-case letters.

@item "upper"
True for upper-case letters.

@item "digit"
True for decimal digits (0-9).

@item "xdigit"
True for hexadecimal digits (@nospell{a-fA-F0-9}).

@item "space"
@itemx "wspace"
True for whitespace characters (space, formfeed, newline, carriage
return, tab, vertical tab).

@item "punct"
True for punctuation characters (printing characters except space
or letter or digit).

@item "cntrl"
True for control characters.

@item "graph"
@itemx "graphic"
True for printing characters except space.

@item "print"
True for printing characters including space.

@item "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 (@dots{}, 'class')

Format real/complex numerical matrices as strings.  This function
returns values that are suitable for the use of 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 17.

If the argument 'class' is given, then the class of @var{x} is
included in the string in such a way that the 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])"
@end group
@end example

@seealso{sprintf, num2str, int2str}
@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 might
include either wildcard replacement or special character escaping.
The behavior can be controlled by the @var{op} that can have the
values

@table @asis
@item "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 "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.  For example:

@example
@group
rindex ("Teststring", "t")
     @result{} 6
@end group
@end example

@strong{Caution:} This function does not work for arrays of
character strings.
@seealso{find, index}
@end deftypefn
strsplit
@c strsplit scripts/strings/strsplit.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{s}] =} strsplit (@var{p}, @var{sep}, @var{strip_empty})
Split a single string using one or more delimiters and return a cell
array of strings.  Consecutive delimiters and delimiters at
boundaries result in empty strings, unless @var{strip_empty} is true.
The default value of @var{strip_empty} is false.
@seealso{strtok}
@end deftypefn
str2num
@c str2num scripts/strings/str2num.m
-*- texinfo -*-
@deftypefn {Function File} {} 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{} ans =
        1  2  3
        4  5  6
@end group
@end example

@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} instead if you want to
avoid the use of @code{eval}.
@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 cells 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 is eliminated.
For example:

@example
@group
s = [ "ab"; "cde" ];
strcat (s, s, s)
     @result{} ans =
        "ab ab ab "
        "cdecdecde"
@end group
@end example

@example
@group
s = @{ "ab"; "cde" @};
strcat (s, s, s)
     @result{} ans =
        @{
          [1,1] = ababab
          [2,1] = cdecdecde
        @}
@end group
@end example

@seealso{cstrcat, char, strvcat}
@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.  Trailing white space is 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{} ans =
        "ab ab ab "
        "cdecdecde"
@end group
@end example
@seealso{strcat, 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})
Search for the string @var{str} for occurrences of characters from
the set @var{chars}.  The return value, 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
strjust
@c strjust scripts/strings/strjust.m
-*- texinfo -*-
@deftypefn {Function File} {} strjust (@var{s}, @var{pos})
Return the text, @var{s}, justified according to @var{pos}, which may
be @samp{"left"}, @samp{"center"}, or @samp{"right"}.  If @var{pos}
is omitted, @samp{"right"} is assumed.

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{} ans =
           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}, "exact")
Return indices of entries of @var{A} that match the string @var{s}.
The second argument @var{A} may be a string matrix or a cell array of
strings.  If the third argument @code{"exact"} is not given, then
@var{s} only needs to match @var{A} up to the length of @var{s}.
Trailing whitespace is ignored.
Results are returned as a column vector.
For example:

@example
@group
strmatch ("apple", "apple juice")
     @result{} 1

strmatch ("apple", ["apple pie"; "apple juice"; "an apple"])
     @result{} [1; 2]

strmatch ("apple", @{"apple pie"; "apple juice"; "tomato"@})
     @result{} [1; 2]
@end group
@end example
@seealso{strfind, findstr, strcmp, strncmp, strcmpi, strncmpi, find}
@end deftypefn
strtok
@c strtok scripts/strings/strtok.m
-*- texinfo -*-
@deftypefn {Function File} {[@var{tok}, @var{rem}] =} strtok (@var{str}, @var{delim})

Find all characters up to but not including the first character which
is in the string delim.  If @var{rem} is requested, it contains the
remainder of the string, starting at the first delimiter.  Leading
delimiters are ignored.  If @var{delim} is not specified, space is
assumed.  For example:

@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}
@end deftypefn
strtrim
@c strtrim scripts/strings/strtrim.m
-*- texinfo -*-
@deftypefn {Function File} {} strtrim (@var{s})
Remove leading and trailing blanks and nulls 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, operate recursively on
each element of the cell array.  For example:

@example
@group
strtrim ("    abc  ")
     @result{} "abc"

strtrim ([" abc   "; "   def   "])
     @result{} ["abc  "; "  def"]
@end group
@end example
@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 char matrix, then the number of columns is adjusted.

If @var{s} is a cell array of strings, then the operation is performed
on its members 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}, @var{len})
Return the substring of @var{s} which starts at character number
@var{offset} and is @var{len} characters long.

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

For example:

@example
@group
substr ("This is a test string", 6, 9)
     @result{} "is a test"
@end group
@end example

This function is patterned after AWK@.  You can get the same result by
@code{@var{s}(@var{offset} : (@var{offset} + @var{len} - 1))}.
@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 tab width is specified by @var{tw}, or defaults to eight.
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.

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 a string or substring of an element of
@var{strarray}.

@var{str} is a character string to be tested, and @var{strarray} is a
cellstr of valid values.  @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}.  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, and an
error will be raised if the matches are not substrings of each other.

All comparisons are case insensitive.
@seealso{strcmp, strcmpi}
@end deftypefn
assert
@c assert scripts/testfun/assert.m
-*- texinfo -*-
@deftypefn  {Function File} {} assert (@var{cond})
@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})

Produces an error if the 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}, @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 zero.  If called with a single argument a
generic error message.  With more than one argument, the additional
arguments are passed to the @code{error} function.

@item assert (@var{observed}, @var{expected})
Produce an error if observed is not the same as expected.  Note that
observed and expected can be strings, scalars, vectors, matrices,
lists or structures.

@item assert(@var{observed}, @var{expected}, @var{tol})
Accept a tolerance when comparing numbers.
If @var{tol} is positive use it as an absolute tolerance, will produce an
error if
@code{abs(@var{observed} - @var{expected}) > abs(@var{tol})}.
If @var{tol} is negative use it as a relative tolerance, 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 used as
an absolute tolerance.
@end table
@seealso{test}
@end deftypefn
demo
@c demo scripts/testfun/demo.m
-*- texinfo -*-
@deftypefn {Function File} {} demo ('@var{name}', @var{n})

Runs any examples associated with the function '@var{name}'.
Examples are stored in the script file, or in a file with the same
name but no extension somewhere on your path.  To keep them separate
from the usual script code, all lines are prefixed by @code{%!}.  Each
example is introduced by the keyword '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)
   %! %-------------------------------------------------
   %! % 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 a simple
comment at the end suffices.  It is generally not necessary to use
disp or printf within the demo.

Demos are run in a function environment with no access to external
variables.  This means that all demos in your function must use
separate initialization code.  Alternatively, you can combine your
demos into one huge demo, with the code:

@example
   %! input("Press <enter> to continue: ","s");
@end example

@noindent
between the sections, but this is discouraged.  Other techniques
include using multiple plots by saying figure between each, or
using subplot to put multiple plots in the same window.

Also, since demo evaluates inside a function context, you cannot
define new functions inside a demo.  Instead you will have to
use @code{eval(example('function',n))} to see them.  Because eval only
evaluates one line, or one statement if the statement crosses
multiple lines, you must wrap your demo in "if 1 <demo stuff> endif"
with the 'if' on the same line as 'demo'.  For example:

@example
@group
  %!demo if 1
  %!  function y=f(x)
  %!    y=x;
  %!  endfunction
  %!  f(3)
  %! endif
@end group
@end example
@seealso{test, example}
@end deftypefn
example
@c example scripts/testfun/example.m
-*- texinfo -*-
@deftypefn  {Function File} {} example ('@var{name}', @var{n})
@deftypefnx {Function File} {[@var{x}, @var{idx}] =} example ('@var{name}', @var{n})

 Display the code for example @var{n} associated with the function
'@var{name}', but do not run it.  If @var{n} is not given, all examples
are displayed.

Called with output arguments, the examples are returned in the form of
a string @var{x}, 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}, @var{pattern})
@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.  Note that @var{code}
is a string and if @var{code} runs successfully, the error produced is:

@example
          expected error but got none
@end example

If the code fails with a different error, the message produced is:

@example
@group
          expected <pattern>
          but got <text of actual error>
@end group
@end example

The angle brackets are not part of the output.

Called with three arguments, the behavior is similar to
@code{fail(@var{code}, @var{pattern})}, but produces an error if no
warning is given during code execution or if the code fails.

@end deftypefn
rundemos
@c rundemos scripts/testfun/rundemos.m
-*- texinfo -*-
@deftypefn {Function File} {} rundemos (@var{directory})
@end deftypefn
runtests
@c runtests scripts/testfun/runtests.m
-*- texinfo -*-
@deftypefn {Function File} {} runtests (@var{directory})
Execute built-in tests for all function files in the specified directory.
@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 displayed graphically.

@table @code
@item @var{f}
The expression to evaluate.

@item @var{max_n}
The maximum test length to run.  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 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 ("v = sum (x)", "", [10000, 100000], ...
       "v = 0; for i = 1:length (x), v += x(i); end")
@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 ("v = xcorr (x, n)", "x = rand (128, 1);", 100,
       "v2 = xcorr_orig (x, n)", -100*eps)
speed ("v = xcorr (x, 15)", "x = rand (20+n, 1);", 100,
       "v2 = 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 we specify an acceptable tolerance on
the comparison @code{100*eps}, and that the errors should be computed
relatively, as @code{abs ((@var{x} - @var{y}) ./ @var{y})} rather than
absolutely as @code{abs (@var{x} - @var{y})}.

Type @code{example('speed')} to see some real examples.  Note that for
obscure reasons, examples 1 and 2 can not be run directly using
@code{demo('speed')}.  Instead use, @code{eval ( example('speed', 1) )}
or @code{eval ( example('speed', 2) )}.
@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 ([], 'explain', @var{fid})
@deftypefnx {Function File} {@var{success} =} test (@dots{})
@deftypefnx {Function File} {[@var{n}, @var{max}] =} test (@dots{})
@deftypefnx {Function File} {[@var{code}, @var{idx}] =} test ('@var{name}', 'grabdemo')

Perform tests from the first file in the loadpath matching @var{name}.
@code{test} can be called as a command or as a function.  Called with
a single argument @var{name}, the tests are run interactively and stop
after the first error is encountered.

With a second argument the tests which are performed and the amount of
output is selected.

@table @asis
@item 'quiet'
 Don't report all the tests as they happen, just the errors.

@item 'normal'
Report all tests as they happen, but don't do tests which require
user interaction.

@item 'verbose'
Do tests which require user interaction.
@end table

The argument @var{fid} can be used to allow batch processing.  Errors
can be written to the already open file defined by @var{fid}, and
hopefully when Octave crashes this file will tell you what was happening
when it did.  You can use @code{stdout} if you want to see the results as
they happen.  You can also give a file name rather than an @var{fid}, in
which case the contents of the file will be replaced with the log from
the current test.

Called with a single output argument @var{success}, @code{test} returns
true if all of the tests were successful.  Called with two output arguments
@var{n} and @var{max}, the number of successful tests and the total number
of tests in the file @var{name} are returned.

If the second argument is the string 'grabdemo', the contents of the demo
blocks are extracted but not executed.  Code for all code blocks is
concatenated and returned as @var{code} with @var{idx} being a vector of
positions of the ends of the demo blocks.

If the second argument is 'explain', then @var{name} is ignored and an
explanation of the line markers used is written to the file @var{fid}.
@seealso{assert, fail, error, demo, example}
@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 datenum, @var{d}.

@var{f} must be one of "year", "month", "day", "hour", "minute", or
"second".
@seealso{datenum, datevec}
@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 five-field
format: Thu Mar 28 08:40:14 1996.  For example:

@example
@group
asctime (localtime (time ()))
     @result{} "Mon Feb 17 01:15:06 1997\n"
@end group
@end example

This is equivalent to @code{ctime (time ())}.
@end deftypefn
calendar
@c calendar scripts/time/calendar.m
-*- texinfo -*-
@deftypefn  {Function File} {} calendar (@dots{})
@deftypefnx {Function File} {@var{c} =} calendar ()
@deftypefnx {Function File} {@var{c} =} calendar (@var{d})
@deftypefnx {Function File} {@var{c} =} calendar (@var{y}, @var{m})
If called with no arguments, return the current monthly calendar in
a 6x7 matrix.

If @var{d} is specified, return the calendar for the month containing
the day @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}
@end deftypefn
clock
@c clock scripts/time/clock.m
-*- texinfo -*-
@deftypefn {Function File} {} clock ()
Return a vector containing the current year, month (1-12), day (1-31),
hour (0-23), minute (0-59) and second (0-61).  For example:

@example
@group
clock ()
     @result{} [ 1993, 8, 20, 4, 56, 1 ]
@end group
@end example

The function clock is more accurate on systems that have the
@code{gettimeofday} function.
@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\n"
@end group
@end example
@end deftypefn
date
@c date scripts/time/date.m
-*- texinfo -*-
@deftypefn {Function File} {} date ()
Return the date as a character string in the form DD-MMM-YY@.  For
example:

@example
@group
date ()
     @result{} "20-Aug-93"
@end group
@end example
@end deftypefn
datenum
@c datenum scripts/time/datenum.m
-*- texinfo -*-
@deftypefn  {Function File} {} datenum (@var{year}, @var{month}, @var{day})
@deftypefnx {Function File} {} datenum (@var{year}, @var{month}, @var{day}, @var{hour})
@deftypefnx {Function File} {} datenum (@var{year}, @var{month}, @var{day}, @var{hour}, @var{minute})
@deftypefnx {Function File} {} datenum (@var{year}, @var{month}, @var{day}, @var{hour}, @var{minute}, @var{second})
@deftypefnx {Function File} {} datenum (@code{"date"})
@deftypefnx {Function File} {} datenum (@code{"date"}, @var{p})
Returns the specified local time as a day number, with Jan 1, 0000
being day 1.  By this reckoning, Jan 1, 1970 is day number 719529.
The fractional portion, @var{p}, corresponds to the portion of the
specified day.

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{Warning:} this function does not attempt to handle Julian
calendars so dates before Octave 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{date, clock, now, datestr, datevec, calendar, weekday}
@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 13/03
@item 20 @tab dd/mm/yy               @tab 13/03/95
@item 21 @tab mmm.dd.yyyy HH:MM:SS   @tab Mar.03.1962 13:53:06
@item 22 @tab mmm.dd.yyyy            @tab Mar.03.1962
@item 23 @tab mm/dd/yyyy             @tab 03/13/1962
@item 24 @tab dd/mm/yyyy             @tab 12/03/1962
@item 25 @tab yy/mm/dd               @tab 95/03/13
@item 26 @tab yyyy/mm/dd             @tab 1995/03/13
@item 27 @tab QQ-YYYY                @tab Q4-2132
@item 28 @tab mmmyyyy                @tab Mar2047
@item 29 @tab yyyymmdd               @tab 20470313
@item 30 @tab yyyymmddTHHMMSS        @tab 20470313T132603
@item 31 @tab yyyy-mm-dd HH:MM:SS    @tab 1047-03-13 13:26:03
@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 2005
@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 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 vector of date strings is
returned.

@seealso{datenum, datevec, date, clock, now, datetick}
@end deftypefn
datetick
@c datetick scripts/time/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 (@dots{ax}, @dots{})
Adds date formatted tick labels to an axis.  The axis the apply the
ticks to is determined by @var{axis} that can take the values "x",
"y" or "z".  The default value is "x".  The formatting of the labels is
determined by the variable @var{form}, that can either be a string in
the format needed by @code{dateform}, or a positive integer that can
be accepted by @code{datestr}.
@seealso{datenum, datestr}
@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}).

@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.
@seealso{datenum, datestr, date, clock, now}
@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{datenum, datevec, weekday}
@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}
@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 the given year is a leap year and false otherwise.  If no
year is provided, @code{is_leap_year} will use the current year.
For example:

@example
@group
is_leap_year (2000)
     @result{} 1
@end group
@end example
@end deftypefn
now
@c now scripts/time/now.m
-*- texinfo -*-
@deftypefn {Function File} {t =} now ()
Returns the current local time as the number of days since Jan 1, 0000.
By this reckoning, Jan 1, 1970 is day number 719529.

The integral part, @code{floor (now)} corresponds to 00:00:00 today.

The fractional part, @code{rem (now, 1)} corresponds to the current
time on Jan 1, 0000.

The returned value is also called a "serial date number"
(see @code{datenum}).
@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 week as a number in @var{n} and a string in @var{s},
for example @code{[1, "Sun"]}, @code{[2, "Mon"]}, @dots{}, or
@code{[7, "Sat"]}.

@var{d} is a serial date number or a date string.

If the string @var{format} is given and is @code{"long"}, @var{s} will
contain the full name of the weekday; otherwise (or if @var{format} is
@code{"short"}), @var{s} will contain the abbreviated name of the weekday.
@seealso{datenum, datevec, eomday}
@end deftypefn
gnuplot_binary
@c gnuplot_binary scripts/plot/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 @code{"gnuplot"} without additional arguments.
@xref{Installation}.
@end deftypefn
