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

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

END-INFO-DIR-ENTRY

   Copyright (C) 1996-2013 John W. Eaton.

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

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

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


File: octave.info,  Node: Real Life Example,  Prev: Iterative Techniques,  Up: Sparse Matrices

22.4 Real Life Example using Sparse Matrices
============================================

A common application for sparse matrices is in the solution of Finite
Element Models.  Finite element models allow numerical solution of
partial differential equations that do not have closed form solutions,
typically because of the complex shape of the domain.

   In order to motivate this application, we consider the boundary value
Laplace equation.  This system can model scalar potential fields, such
as heat or electrical potential.  Given a medium Omega with boundary
dOmega.  At all points on the dOmega the boundary conditions are known,
and we wish to calculate the potential in Omega.  Boundary conditions
may specify the potential (Dirichlet boundary condition), its normal
derivative across the boundary (Neumann boundary condition), or a
weighted sum of the potential and its derivative (Cauchy boundary
condition).

   In a thermal model, we want to calculate the temperature in Omega and
know the boundary temperature (Dirichlet condition) or heat flux (from
which we can calculate the Neumann condition by dividing by the thermal
conductivity at the boundary).  Similarly, in an electrical model, we
want to calculate the voltage in Omega and know the boundary voltage
(Dirichlet) or current (Neumann condition after diving by the electrical
conductivity).  In an electrical model, it is common for much of the
boundary to be electrically isolated; this is a Neumann boundary
condition with the current equal to zero.

   The simplest finite element models will divide Omega into simplexes
(triangles in 2D, pyramids in 3D).

   The following example creates a simple rectangular 2-D electrically
conductive medium with 10 V and 20 V imposed on opposite sides
(Dirichlet boundary conditions).  All other edges are electrically
isolated.

        node_y = [1;1.2;1.5;1.8;2]*ones(1,11);
        node_x = ones(5,1)*[1,1.05,1.1,1.2, ...
                  1.3,1.5,1.7,1.8,1.9,1.95,2];
        nodes = [node_x(:), node_y(:)];

        [h,w] = size (node_x);
        elems = [];
        for idx = 1:w-1
          widx = (idx-1)*h;
          elems = [elems; ...
            widx+[(1:h-1);(2:h);h+(1:h-1)]'; ...
            widx+[(2:h);h+(2:h);h+(1:h-1)]' ];
        endfor

        E = size (elems,1); # No. of simplices
        N = size (nodes,1); # No. of vertices
        D = size (elems,2); # dimensions+1

   This creates a N-by-2 matrix 'nodes' and a E-by-3 matrix 'elems' with
values, which define finite element triangles:

       nodes(1:7,:)'
         1.00 1.00 1.00 1.00 1.00 1.05 1.05 ...
         1.00 1.20 1.50 1.80 2.00 1.00 1.20 ...

       elems(1:7,:)'
         1    2    3    4    2    3    4 ...
         2    3    4    5    7    8    9 ...
         6    7    8    9    6    7    8 ...

   Using a first order FEM, we approximate the electrical conductivity
distribution in Omega as constant on each simplex (represented by the
vector 'conductivity').  Based on the finite element geometry, we first
calculate a system (or stiffness) matrix for each simplex (represented
as 3-by-3 elements on the diagonal of the element-wise system matrix
'SE'.  Based on 'SE' and a N-by-DE connectivity matrix 'C', representing
the connections between simplices and vertices, the global connectivity
matrix 'S' is calculated.

       ## Element conductivity
       conductivity = [1*ones(1,16), ...
              2*ones(1,48), 1*ones(1,16)];

       ## Connectivity matrix
       C = sparse ((1:D*E), reshape (elems', ...
              D*E, 1), 1, D*E, N);

       ## Calculate system matrix
       Siidx = floor ([0:D*E-1]'/D) * D * ...
              ones(1,D) + ones(D*E,1)*(1:D) ;
       Sjidx = [1:D*E]'*ones (1,D);
       Sdata = zeros (D*E,D);
       dfact = factorial (D-1);
       for j = 1:E
          a = inv ([ones(D,1), ...
              nodes(elems(j,:), :)]);
          const = conductivity(j) * 2 / ...
              dfact / abs (det (a));
          Sdata(D*(j-1)+(1:D),:) = const * ...
              a(2:D,:)' * a(2:D,:);
       endfor
       ## Element-wise system matrix
       SE = sparse(Siidx,Sjidx,Sdata);
       ## Global system matrix
       S = C'* SE *C;

   The system matrix acts like the conductivity 'S' in Ohm's law 'S * V
= I'.  Based on the Dirichlet and Neumann boundary conditions, we are
able to solve for the voltages at each vertex 'V'.

       ## Dirichlet boundary conditions
       D_nodes = [1:5, 51:55];
       D_value = [10*ones(1,5), 20*ones(1,5)];

       V = zeros (N,1);
       V(D_nodes) = D_value;
       idx = 1:N; # vertices without Dirichlet
                  # boundary condns
       idx(D_nodes) = [];

       ## Neumann boundary conditions.  Note that
       ## N_value must be normalized by the
       ## boundary length and element conductivity
       N_nodes = [];
       N_value = [];

       Q = zeros (N,1);
       Q(N_nodes) = N_value;

       V(idx) = S(idx,idx) \ ( Q(idx) - ...
                 S(idx,D_nodes) * V(D_nodes));

   Finally, in order to display the solution, we show each solved
voltage value in the z-axis for each simplex vertex.

       elemx = elems(:,[1,2,3,1])';
       xelems = reshape (nodes(elemx, 1), 4, E);
       yelems = reshape (nodes(elemx, 2), 4, E);
       velems = reshape (V(elemx), 4, E);
       plot3 (xelems,yelems,velems,"k");
       print "grid.eps";


File: octave.info,  Node: Numerical Integration,  Next: Differential Equations,  Prev: Sparse Matrices,  Up: Top

23 Numerical Integration
************************

Octave comes with several built-in functions for computing the integral
of a function numerically (termed quadrature).  These functions all
solve 1-dimensional integration problems.

* Menu:

* Functions of One Variable::
* Orthogonal Collocation::
* Functions of Multiple Variables::


File: octave.info,  Node: Functions of One Variable,  Next: Orthogonal Collocation,  Up: Numerical Integration

23.1 Functions of One Variable
==============================

Octave supports five different algorithms for computing the integral of
a function f over the interval from a to b.  These are

'quad'
     Numerical integration based on Gaussian quadrature.

'quadv'
     Numerical integration using an adaptive vectorized Simpson's rule.

'quadl'
     Numerical integration using an adaptive Lobatto rule.

'quadgk'
     Numerical integration using an adaptive Gauss-Konrod rule.

'quadcc'
     Numerical integration using adaptive Clenshaw-Curtis rules.

'trapz, cumtrapz'
     Numerical integration of data using the trapezoidal method.

The best quadrature algorithm to use depends on the integrand.  If you
have empirical data, rather than a function, the choice is 'trapz' or
'cumtrapz'.  If you are uncertain about the characteristics of the
integrand, 'quadcc' will be the most robust as it can handle
discontinuities, singularities, oscillatory functions, and infinite
intervals.  When the integrand is smooth 'quadgk' may be the fastest of
the algorithms.

     Function    Characteristics
----------------------------------------------------------------------------
     quad        Low accuracy with nonsmooth integrands
     quadv       Medium accuracy with smooth integrands
     quadl       Medium accuracy with smooth integrands.  Slower than
                 quadgk.
     quadgk      Medium accuracy (1e^{-6}-1e^{-9}) with smooth
                 integrands.
                 Handles oscillatory functions and infinite bounds
     quadcc      Low to High accuracy with nonsmooth/smooth integrands
                 Handles oscillatory functions, singularities, and
                 infinite bounds

   Here is an example of using 'quad' to integrate the function

       F(X) = X * sin (1/X) * sqrt (abs (1 - X))

from X = 0 to X = 3.

   This is a fairly difficult integration (plot the function over the
range of integration to see why).

   The first step is to define the function:

     function y = f (x)
       y = x .* sin (1./x) .* sqrt (abs (1 - x));
     endfunction

   Note the use of the 'dot' forms of the operators.  This is not
necessary for the 'quad' integrator, but is required by the other
integrators.  In any case, it makes it much easier to generate a set of
points for plotting because it is possible to call the function with a
vector argument to produce a vector result.

   The second step is to call quad with the limits of integration:

     [q, ier, nfun, err] = quad ("f", 0, 3)
          => 1.9819
          => 1
          => 5061
          => 1.1522e-07

   Although 'quad' returns a nonzero value for IER, the result is
reasonably accurate (to see why, examine what happens to the result if
you move the lower bound to 0.1, then 0.01, then 0.001, etc.).

   The function "f" can be the string name of a function, a function
handle, or an inline function.  These options make it quite easy to do
integration without having to fully define a function in an m-file.  For
example:

     # Verify integral (x^3) = x^4/4
     f = inline ("x.^3");
     quadgk (f, 0, 1)
          => 0.25000

     # Verify gamma function = (n-1)! for n = 4
     f = @(x) x.^3 .* exp (-x);
     quadcc (f, 0, Inf)
          => 6.0000

 -- Built-in Function: Q = quad (F, A, B)
 -- Built-in Function: Q = quad (F, A, B, TOL)
 -- Built-in Function: Q = quad (F, A, B, TOL, SING)
 -- Built-in Function: [Q, IER, NFUN, ERR] = quad (...)
     Numerically evaluate the integral of F from A to B using Fortran
     routines from QUADPACK.  F is a function handle, inline function,
     or a string containing the name of the function to evaluate.  The
     function must have the form 'y = f (x)' where Y and X are scalars.

     A and B are the lower and upper limits of integration.  Either or
     both may be infinite.

     The optional argument TOL is a vector that specifies the desired
     accuracy of the result.  The first element of the vector is the
     desired absolute tolerance, and the second element is the desired
     relative tolerance.  To choose a relative test only, set the
     absolute tolerance to zero.  To choose an absolute test only, set
     the relative tolerance to zero.  Both tolerances default to 'sqrt
     (eps)' or approximately 1.5e^{-8}.

     The optional argument SING is a vector of values at which the
     integrand is known to be singular.

     The result of the integration is returned in Q.  IER contains an
     integer error code (0 indicates a successful integration).  NFUN
     indicates the number of function evaluations that were made, and
     ERR contains an estimate of the error in the solution.

     The function 'quad_options' can set other optional parameters for
     'quad'.

     Note: because 'quad' is written in Fortran it cannot be called
     recursively.  This prevents its use in integrating over more than
     one variable by routines 'dblquad' and 'triplequad'.

     See also: *note quad_options: XREFquad_options, *note quadv:
     XREFquadv, *note quadl: XREFquadl, *note quadgk: XREFquadgk, *note
     quadcc: XREFquadcc, *note trapz: XREFtrapz, *note dblquad:
     XREFdblquad, *note triplequad: XREFtriplequad.

 -- Built-in Function: quad_options ()
 -- Built-in Function: val = quad_options (OPT)
 -- Built-in Function: quad_options (OPT, VAL)
     Query or set options for the function 'quad'.  When called with no
     arguments, the names of all available options and their current
     values are displayed.  Given one argument, return the value of the
     corresponding option.  When called with two arguments,
     'quad_options' set the option OPT to value VAL.

     Options include

     '"absolute tolerance"'
          Absolute tolerance; may be zero for pure relative error test.

     '"relative tolerance"'
          Non-negative relative tolerance.  If the absolute tolerance is
          zero, the relative tolerance must be greater than or equal to
          'max (50*eps, 0.5e-28)'.

     '"single precision absolute tolerance"'
          Absolute tolerance for single precision; may be zero for pure
          relative error test.

     '"single precision relative tolerance"'
          Non-negative relative tolerance for single precision.  If the
          absolute tolerance is zero, the relative tolerance must be
          greater than or equal to 'max (50*eps, 0.5e-28)'.

 -- Function File: Q = quadv (F, A, B)
 -- Function File: Q = quadv (F, A, B, TOL)
 -- Function File: Q = quadv (F, A, B, TOL, TRACE)
 -- Function File: Q = quadv (F, A, B, TOL, TRACE, P1, P2, ...)
 -- Function File: [Q, NFUN] = quadv (...)

     Numerically evaluate the integral of F from A to B using an
     adaptive Simpson's rule.  F is a function handle, inline function,
     or string containing the name of the function to evaluate.  'quadv'
     is a vectorized version of 'quad' and the function defined by F
     must accept a scalar or vector as input and return a scalar,
     vector, or array as output.

     A and B are the lower and upper limits of integration.  Both limits
     must be finite.

     The optional argument TOL defines the tolerance used to stop the
     adaptation procedure.  The default value is 1e^{-6}.

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

     Additional arguments P1, etc., are passed directly to the function
     F.  To use default values for TOL and TRACE, one may pass empty
     matrices ([]).

     The result of the integration is returned in Q.  NFUN indicates the
     number of function evaluations that were made.

     Note: 'quadv' is written in Octave's scripting language and can be
     used recursively in 'dblquad' and 'triplequad', unlike the similar
     'quad' function.

     See also: *note quad: XREFquad, *note quadl: XREFquadl, *note
     quadgk: XREFquadgk, *note quadcc: XREFquadcc, *note trapz:
     XREFtrapz, *note dblquad: XREFdblquad, *note triplequad:
     XREFtriplequad.

 -- Function File: Q = quadl (F, A, B)
 -- Function File: Q = quadl (F, A, B, TOL)
 -- Function File: Q = quadl (F, A, B, TOL, TRACE)
 -- Function File: Q = quadl (F, A, B, TOL, TRACE, P1, P2, ...)

     Numerically evaluate the integral of F from A to B using an
     adaptive Lobatto rule.  F is a function handle, inline function, or
     string containing the name of the function to evaluate.  The
     function F must be vectorized and return a vector of output values
     if given a vector of input values.

     A and B are the lower and upper limits of integration.  Both limits
     must be finite.

     The optional argument TOL defines the relative tolerance with which
     to perform the integration.  The default value is 'eps'.

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

     Additional arguments P1, etc., are passed directly to the function
     F.  To use default values for TOL and TRACE, one may pass empty
     matrices ([]).

     Reference: W. Gander and W. Gautschi, 'Adaptive Quadrature -
     Revisited', BIT Vol.  40, No.  1, March 2000, pp.  84-101.
     <http://www.inf.ethz.ch/personal/gander/>

     See also: *note quad: XREFquad, *note quadv: XREFquadv, *note
     quadgk: XREFquadgk, *note quadcc: XREFquadcc, *note trapz:
     XREFtrapz, *note dblquad: XREFdblquad, *note triplequad:
     XREFtriplequad.

 -- Function File: Q = quadgk (F, A, B)
 -- Function File: Q = quadgk (F, A, B, ABSTOL)
 -- Function File: Q = quadgk (F, A, B, ABSTOL, TRACE)
 -- Function File: Q = quadgk (F, A, B, PROP, VAL, ...)
 -- Function File: [Q, ERR] = quadgk (...)

     Numerically evaluate the integral of F from A to B using adaptive
     Gauss-Konrod quadrature.  F is a function handle, inline function,
     or string containing the name of the function to evaluate.  The
     formulation is based on a proposal by L.F. Shampine, '"Vectorized
     adaptive quadrature in 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 F.  Therefore, the function F must be vectorized and
     must accept a vector of input values X and return an output vector
     representing the function evaluations at the given values of X.

     A and B are the lower and upper limits of integration.  Either or
     both limits may be infinite or contain weak end singularities.
     Variable transformation will be used to treat any infinite
     intervals and weaken the singularities.  For example:

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

     Note that the formulation of the integrand uses the
     element-by-element operator './' and all user functions to 'quadgk'
     should do the same.

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

     The algorithm used by 'quadgk' involves subdividing the integration
     interval and evaluating each subinterval.  If TRACE is true then
     after computing each of these partial integrals display: (1) the
     number of subintervals at this step, (2) the current estimate of
     the error ERR, (3) the current estimate for the integral Q.

     Alternatively, properties of 'quadgk' can be passed to the function
     as pairs "PROP", VAL.  Valid properties are

     'AbsTol'
          Define the absolute error tolerance for the quadrature.  The
          default absolute tolerance is 1e-10.

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

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

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

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

          signals the breakpoint in the integrand at 'X = 1'.

     'Trace'
          If logically true 'quadgk' prints information on the
          convergence of the quadrature at each iteration.

     If any of A, B, or 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,

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

     integrates 'log (z)' along the square defined by '[1+1i, 1-1i,
     -1-1i, -1+1i]'

     The result of the integration is returned in Q.  ERR is an
     approximate bound on the error in the integral 'abs (Q - I)', where
     I is the exact value of the integral.

     See also: *note quad: XREFquad, *note quadv: XREFquadv, *note
     quadl: XREFquadl, *note quadcc: XREFquadcc, *note trapz: XREFtrapz,
     *note dblquad: XREFdblquad, *note triplequad: XREFtriplequad.

 -- Function File: Q = quadcc (F, A, B)
 -- Function File: Q = quadcc (F, A, B, TOL)
 -- Function File: Q = quadcc (F, A, B, TOL, SING)
 -- Function File: [Q, ERR, NR_POINTS] = quadcc (...)
     Numerically evaluate the integral of F from A to B using the
     doubly-adaptive Clenshaw-Curtis quadrature described by P. Gonnet
     in 'Increasing the Reliability of Adaptive Quadrature Using
     Explicit Interpolants'.  F is a function handle, inline function,
     or string containing the name of the function to evaluate.  The
     function F must be vectorized and must return a vector of output
     values if given a vector of input values.  For example,

          f = @(x) x .* sin (1./x) .* sqrt (abs (1 - x));

     which uses the element-by-element "dot" form for all operators.

     A and B are the lower and upper limits of integration.  Either or
     both limits may be infinite.  'quadcc' handles an inifinite limit
     by substituting the variable of integration with 'x = tan
     (pi/2*u)'.

     The optional argument TOL defines the relative tolerance used to
     stop the integration procedure.  The default value is 1e^{-6}.

     The optional argument SING contains a list of points where the
     integrand has known singularities, or discontinuities in any of its
     derivatives, inside the integration interval.  For the example
     above, which has a discontinuity at x=1, the call to 'quadcc' would
     be as follows

          int = quadcc (f, a, b, 1.0e-6, [ 1 ]);

     The result of the integration is returned in Q.  ERR is an estimate
     of the absolute integration error and NR_POINTS is the number of
     points at which the integrand was evaluated.  If the adaptive
     integration did not converge, the value of ERR will be larger than
     the requested tolerance.  Therefore, it is recommended to verify
     this value for difficult integrands.

     'quadcc' is capable of dealing with non-numeric values of the
     integrand such as 'NaN' or 'Inf'.  If the integral diverges, and
     'quadcc' detects this, then a warning is issued and 'Inf' or '-Inf'
     is returned.

     Note: 'quadcc' is a general purpose quadrature algorithm and, as
     such, may be less efficient for a smooth or otherwise well-behaved
     integrand than other methods such as 'quadgk'.

     The algorithm uses Clenshaw-Curtis quadrature rules of increasing
     degree in each interval and bisects the interval if either the
     function does not appear to be smooth or a rule of maximum degree
     has been reached.  The error estimate is computed from the L2-norm
     of the difference between two successive interpolations of the
     integrand over the nodes of the respective quadrature rules.

     Reference: P. Gonnet, 'Increasing the Reliability of Adaptive
     Quadrature Using Explicit Interpolants', ACM Transactions on
     Mathematical Software, Vol.  37, Issue 3, Article No.  3, 2010.

     See also: *note quad: XREFquad, *note quadv: XREFquadv, *note
     quadl: XREFquadl, *note quadgk: XREFquadgk, *note trapz: XREFtrapz,
     *note dblquad: XREFdblquad, *note triplequad: XREFtriplequad.

   Sometimes one does not have the function, but only the raw (x, y)
points from which to perform an integration.  This can occur when
collecting data in an experiment.  The 'trapz' function can integrate
these values as shown in the following example where "data" has been
collected on the cosine function over the range [0, pi/2).

     x = 0:0.1:pi/2;  # Uniformly spaced points
     y = cos (x);
     trapz (x, y)
          => 0.99666

   The answer is reasonably close to the exact value of 1.  Ordinary
quadrature is sensitive to the characteristics of the integrand.
Empirical integration depends not just on the integrand, but also on the
particular points chosen to represent the function.  Repeating the
example above with the sine function over the range [0, pi/2) produces
far inferior results.

     x = 0:0.1:pi/2;  # Uniformly spaced points
     y = sin (x);
     trapz (x, y)
          => 0.92849

   However, a slightly different choice of data points can change the
result significantly.  The same integration, with the same number of
points, but spaced differently produces a more accurate answer.

     x = linspace (0, pi/2, 16);  # Uniformly spaced, but including endpoint
     y = sin (x);
     trapz (x, y)
          => 0.99909

   In general there may be no way of knowing the best distribution of
points ahead of time.  Or the points may come from an experiment where
there is no freedom to select the best distribution.  In any case, one
must remain aware of this issue when using 'trapz'.

 -- Function File: Q = trapz (Y)
 -- Function File: Q = trapz (X, Y)
 -- Function File: Q = trapz (..., DIM)

     Numerically evaluate the integral of points Y using the trapezoidal
     method.  'trapz (Y)' computes the integral of Y along the first
     non-singleton dimension.  When the argument X is omitted an equally
     spaced X vector with unit spacing (1) is assumed.  'trapz (X, Y)'
     evaluates the integral with respect to the spacing in X and the
     values in Y.  This is useful if the points in Y have been sampled
     unevenly.  If the optional DIM argument is given, operate along
     this dimension.

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

          x = 0:0.1:1;
          y = x.^3;
          q = trapz (y)
            => q = 2.525   # No scaling
          q * 0.1
            => q = 0.2525  # Approximation to integral by scaling
          trapz (x, y)
            => q = 0.2525  # Same result by specifying X

     See also: *note cumtrapz: XREFcumtrapz.

 -- Function File: Q = cumtrapz (Y)
 -- Function File: Q = cumtrapz (X, Y)
 -- Function File: Q = cumtrapz (..., DIM)

     Cumulative numerical integration of points Y using the trapezoidal
     method.  'cumtrapz (Y)' computes the cumulative integral of Y along
     the first non-singleton dimension.  Where 'trapz' reports only the
     overall integral sum, 'cumtrapz' reports the current partial sum
     value at each point of Y.  When the argument X is omitted an
     equally spaced X vector with unit spacing (1) is assumed.
     'cumtrapz (X, Y)' evaluates the integral with respect to the
     spacing in X and the values in Y.  This is useful if the points in
     Y have been sampled unevenly.  If the optional DIM argument is
     given, operate along this dimension.

     If X is not specified then unit spacing will be used.  To scale the
     integral to the correct value you must multiply by the actual
     spacing value (deltaX).

     See also: *note trapz: XREFtrapz, *note cumsum: XREFcumsum.


File: octave.info,  Node: Orthogonal Collocation,  Next: Functions of Multiple Variables,  Prev: Functions of One Variable,  Up: Numerical Integration

23.2 Orthogonal Collocation
===========================

 -- Built-in Function: [R, AMAT, BMAT, Q] = colloc (N, "left", "right")
     Compute derivative and integral weight matrices for orthogonal
     collocation using the subroutines given in J. Villadsen and M. L.
     Michelsen, 'Solution of Differential Equation Models by Polynomial
     Approximation'.

   Here is an example of using 'colloc' to generate weight matrices for
solving the second order differential equation U' - ALPHA * U" = 0 with
the boundary conditions U(0) = 0 and U(1) = 1.

   First, we can generate the weight matrices for N points (including
the endpoints of the interval), and incorporate the boundary conditions
in the right hand side (for a specific value of ALPHA).

     n = 7;
     alpha = 0.1;
     [r, a, b] = colloc (n-2, "left", "right");
     at = a(2:n-1,2:n-1);
     bt = b(2:n-1,2:n-1);
     rhs = alpha * b(2:n-1,n) - a(2:n-1,n);

   Then the solution at the roots R is

     u = [ 0; (at - alpha * bt) \ rhs; 1]
          => [ 0.00; 0.004; 0.01 0.00; 0.12; 0.62; 1.00 ]


File: octave.info,  Node: Functions of Multiple Variables,  Prev: Orthogonal Collocation,  Up: Numerical Integration

23.3 Functions of Multiple Variables
====================================

Octave does not have built-in functions for computing the integral of
functions of multiple variables directly.  It is possible, however, to
compute the integral of a function of multiple variables using the
existing functions for one-dimensional integrals.

   To illustrate how the integration can be performed, we will integrate
the function

     f(x, y) = sin(pi*x*y)*sqrt(x*y)

   for x and y between 0 and 1.

   The first approach creates a function that integrates f with respect
to x, and then integrates that function with respect to y.  Because
'quad' is written in Fortran it cannot be called recursively.  This
means that 'quad' cannot integrate a function that calls 'quad', and
hence cannot be used to perform the double integration.  Any of the
other integrators, however, can be used which is what the following code
demonstrates.

     function q = g(y)
       q = ones (size (y));
       for i = 1:length (y)
         f = @(x) sin (pi*x.*y(i)) .* sqrt (x.*y(i));
         q(i) = quadgk (f, 0, 1);
       endfor
     endfunction

     I = quadgk ("g", 0, 1)
           => 0.30022

   The above process can be simplified with the 'dblquad' and
'triplequad' functions for integrals over two and three variables.  For
example:

     I = dblquad (@(x, y) sin (pi*x.*y) .* sqrt (x.*y), 0, 1, 0, 1)
           => 0.30022

 -- Function File: dblquad (F, XA, XB, YA, YB)
 -- Function File: dblquad (F, XA, XB, YA, YB, TOL)
 -- Function File: dblquad (F, XA, XB, YA, YB, TOL, QUADF)
 -- Function File: dblquad (F, XA, XB, YA, YB, TOL, QUADF, ...)
     Numerically evaluate the double integral of F.  F is a function
     handle, inline function, or string containing the name of the
     function to evaluate.  The function F must have the form z = f(x,y)
     where X is a vector and Y is a scalar.  It should return a vector
     of the same length and orientation as X.

     XA, YA and XB, YB are the lower and upper limits of integration for
     x and y respectively.  The underlying integrator determines whether
     infinite bounds are accepted.

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

     The optional argument QUADF specifies which underlying integrator
     function to use.  Any choice but 'quad' is available and the
     default is 'quadcc'.

     Additional arguments, are passed directly to F.  To use the default
     value for TOL or QUADF one may pass ':' or an empty matrix ([]).

     See also: *note triplequad: XREFtriplequad, *note quad: XREFquad,
     *note quadv: XREFquadv, *note quadl: XREFquadl, *note quadgk:
     XREFquadgk, *note quadcc: XREFquadcc, *note trapz: XREFtrapz.

 -- Function File: triplequad (F, XA, XB, YA, YB, ZA, ZB)
 -- Function File: triplequad (F, XA, XB, YA, YB, ZA, ZB, TOL)
 -- Function File: triplequad (F, XA, XB, YA, YB, ZA, ZB, TOL, QUADF)
 -- Function File: triplequad (F, XA, XB, YA, YB, ZA, ZB, TOL, QUADF,
          ...)
     Numerically evaluate the triple integral of F.  F is a function
     handle, inline function, or string containing the name of the
     function to evaluate.  The function F must have the form w =
     f(x,y,z) where either X or Y is a vector and the remaining inputs
     are scalars.  It should return a vector of the same length and
     orientation as X or Y.

     XA, YA, ZA and XB, YB, ZB are the lower and upper limits of
     integration for x, y, and z respectively.  The underlying
     integrator determines whether infinite bounds are accepted.

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

     The optional argument QUADF specifies which underlying integrator
     function to use.  Any choice but 'quad' is available and the
     default is 'quadcc'.

     Additional arguments, are passed directly to F.  To use the default
     value for TOL or QUADF one may pass ':' or an empty matrix ([]).

     See also: *note dblquad: XREFdblquad, *note quad: XREFquad, *note
     quadv: XREFquadv, *note quadl: XREFquadl, *note quadgk: XREFquadgk,
     *note quadcc: XREFquadcc, *note trapz: XREFtrapz.

   The above mentioned approach works, but is fairly slow, and that
problem increases exponentially with the dimensionality of the integral.
Another possible solution is to use Orthogonal Collocation as described
in the previous section (*note Orthogonal Collocation::).  The integral
of a function f(x,y) for x and y between 0 and 1 can be approximated
using n points by the sum over 'i=1:n' and 'j=1:n' of
'q(i)*q(j)*f(r(i),r(j))', where q and r is as returned by 'colloc (n)'.
The generalization to more than two variables is straight forward.  The
following code computes the studied integral using n=8 points.

     f = @(x,y) sin (pi*x*y') .* sqrt (x*y');
     n = 8;
     [t, ~, ~, q] = colloc (n);
     I = q'*f(t,t)*q;
           => 0.30022

It should be noted that the number of points determines the quality of
the approximation.  If the integration needs to be performed between a
and b, instead of 0 and 1, then a change of variables is needed.


File: octave.info,  Node: Differential Equations,  Next: Optimization,  Prev: Numerical Integration,  Up: Top

24 Differential Equations
*************************

Octave has built-in functions for solving ordinary differential
equations, and differential-algebraic equations.  All solvers are based
on reliable ODE routines written in Fortran.

* Menu:

* Ordinary Differential Equations::
* Differential-Algebraic Equations::


File: octave.info,  Node: Ordinary Differential Equations,  Next: Differential-Algebraic Equations,  Up: Differential Equations

24.1 Ordinary Differential Equations
====================================

The function 'lsode' can be used to solve ODEs of the form

     dx
     -- = f (x, t)
     dt

using Hindmarsh's ODE solver LSODE.

 -- Built-in Function: [X, ISTATE, MSG] = lsode (FCN, X_0, T)
 -- Built-in Function: [X, ISTATE, MSG] = lsode (FCN, X_0, T, T_CRIT)
     Solve the set of differential equations

          dx
          -- = f (x, t)
          dt

     with

          x(t_0) = x_0

     The solution is returned in the matrix X, with each row
     corresponding to an element of the vector T.  The first element of
     T should be t_0 and should correspond to the initial state of the
     system X_0, so that the first row of the output is X_0.

     The first argument, FCN, is a string, inline, or function handle
     that names the function f to call to compute the vector of right
     hand sides for the set of equations.  The function must have the
     form

          XDOT = f (X, T)

     in which XDOT and X are vectors and T is a scalar.

     If FCN is a two-element string array or a two-element cell array of
     strings, inline functions, or function handles, the first element
     names the function f described above, and the second element names
     a function to compute the Jacobian of f.  The Jacobian function
     must have the form

          JAC = j (X, T)

     in which JAC is the matrix of partial derivatives

                       | df_1  df_1       df_1 |
                       | ----  ----  ...  ---- |
                       | dx_1  dx_2       dx_N |
                       |                       |
                       | df_2  df_2       df_2 |
                       | ----  ----  ...  ---- |
                df_i   | dx_1  dx_2       dx_N |
          jac = ---- = |                       |
                dx_j   |  .    .     .    .    |
                       |  .    .      .   .    |
                       |  .    .       .  .    |
                       |                       |
                       | df_N  df_N       df_N |
                       | ----  ----  ...  ---- |
                       | dx_1  dx_2       dx_N |

     The second and third arguments specify the initial state of the
     system, x_0, and the initial value of the independent variable t_0.

     The fourth argument is optional, and may be used to specify a set
     of times that the ODE solver should not integrate past.  It is
     useful for avoiding difficulties with singularities and points
     where there is a discontinuity in the derivative.

     After a successful computation, the value of ISTATE will be 2
     (consistent with the Fortran version of LSODE).

     If the computation is not successful, ISTATE will be something
     other than 2 and MSG will contain additional information.

     You can use the function 'lsode_options' to set optional parameters
     for 'lsode'.

     See also: *note daspk: XREFdaspk, *note dassl: XREFdassl, *note
     dasrt: XREFdasrt.

 -- Built-in Function: lsode_options ()
 -- Built-in Function: val = lsode_options (OPT)
 -- Built-in Function: lsode_options (OPT, VAL)
     Query or set options for the function 'lsode'.  When called with no
     arguments, the names of all available options and their current
     values are displayed.  Given one argument, return the value of the
     corresponding option.  When called with two arguments,
     'lsode_options' set the option OPT to value VAL.

     Options include

     '"absolute tolerance"'
          Absolute tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector.

     '"relative tolerance"'
          Relative tolerance parameter.  Unlike the absolute tolerance,
          this parameter may only be a scalar.

          The local error test applied at each integration step is

                 abs (local error in x(i)) <= ...
                     rtol * abs (y(i)) + atol(i)

     '"integration method"'
          A string specifying the method of integration to use to solve
          the ODE system.  Valid values are

          "adams"
          "non-stiff"
               No Jacobian used (even if it is available).

          "bdf"
          "stiff"
               Use stiff backward differentiation formula (BDF) method.
               If a function to compute the Jacobian is not supplied,
               'lsode' will compute a finite difference approximation of
               the Jacobian matrix.

     '"initial step size"'
          The step size to be attempted on the first step (default is
          determined automatically).

     '"maximum order"'
          Restrict the maximum order of the solution method.  If using
          the Adams method, this option must be between 1 and 12.
          Otherwise, it must be between 1 and 5, inclusive.

     '"maximum step size"'
          Setting the maximum stepsize will avoid passing over very
          large regions (default is not specified).

     '"minimum step size"'
          The minimum absolute step size allowed (default is 0).

     '"step limit"'
          Maximum number of steps allowed (default is 100000).

   Here is an example of solving a set of three differential equations
using 'lsode'.  Given the function

     ## oregonator differential equation
     function xdot = f (x, t)

       xdot = zeros (3,1);

       xdot(1) = 77.27 * (x(2) - x(1)*x(2) + x(1) \
                 - 8.375e-06*x(1)^2);
       xdot(2) = (x(3) - x(1)*x(2) - x(2)) / 77.27;
       xdot(3) = 0.161*(x(1) - x(3));

     endfunction

and the initial condition 'x0 = [ 4; 1.1; 4 ]', the set of equations can
be integrated using the command

     t = linspace (0, 500, 1000);

     y = lsode ("f", x0, t);

   If you try this, you will see that the value of the result changes
dramatically between T = 0 and 5, and again around T = 305.  A more
efficient set of output points might be

     t = [0, logspace(-1, log10(303), 150), \
             logspace(log10(304), log10(500), 150)];

   See Alan C. Hindmarsh, 'ODEPACK, A Systematized Collection of ODE
Solvers', in Scientific Computing, R. S. Stepleman, editor, (1983) for
more information about the inner workings of 'lsode'.

   An m-file for the differential equation used above is included with
the Octave distribution in the examples directory under the name
'oregonator.m'.


File: octave.info,  Node: Differential-Algebraic Equations,  Prev: Ordinary Differential Equations,  Up: Differential Equations

24.2 Differential-Algebraic Equations
=====================================

The function 'daspk' can be used to solve DAEs of the form

     0 = f (x-dot, x, t),    x(t=0) = x_0, x-dot(t=0) = x-dot_0

where x-dot is the derivative of x.  The equation is solved using
Petzold's DAE solver DASPK.

 -- Built-in Function: [X, XDOT, ISTATE, MSG] = daspk (FCN, X_0, XDOT_0,
          T, T_CRIT)
     Solve the set of differential-algebraic equations

          0 = f (x, xdot, t)

     with

          x(t_0) = x_0, xdot(t_0) = xdot_0

     The solution is returned in the matrices X and XDOT, with each row
     in the result matrices corresponding to one of the elements in the
     vector T.  The first element of T should be t_0 and correspond to
     the initial state of the system X_0 and its derivative XDOT_0, so
     that the first row of the output X is X_0 and the first row of the
     output XDOT is XDOT_0.

     The first argument, FCN, is a string, inline, or function handle
     that names the function f to call to compute the vector of
     residuals for the set of equations.  It must have the form

          RES = f (X, XDOT, T)

     in which X, XDOT, and RES are vectors, and T is a scalar.

     If FCN is a two-element string array or a two-element cell array of
     strings, inline functions, or function handles, the first element
     names the function f described above, and the second element names
     a function to compute the modified Jacobian

                df       df
          jac = -- + c ------
                dx     d xdot

     The modified Jacobian function must have the form


          JAC = j (X, XDOT, T, C)


     The second and third arguments to 'daspk' specify the initial
     condition of the states and their derivatives, and the fourth
     argument specifies a vector of output times at which the solution
     is desired, including the time corresponding to the initial
     condition.

     The set of initial states and derivatives are not strictly required
     to be consistent.  If they are not consistent, you must use the
     'daspk_options' function to provide additional information so that
     'daspk' can compute a consistent starting point.

     The fifth argument is optional, and may be used to specify a set of
     times that the DAE solver should not integrate past.  It is useful
     for avoiding difficulties with singularities and points where there
     is a discontinuity in the derivative.

     After a successful computation, the value of ISTATE will be greater
     than zero (consistent with the Fortran version of DASPK).

     If the computation is not successful, the value of ISTATE will be
     less than zero and MSG will contain additional information.

     You can use the function 'daspk_options' to set optional parameters
     for 'daspk'.

     See also: *note dassl: XREFdassl.

 -- Built-in Function: daspk_options ()
 -- Built-in Function: val = daspk_options (OPT)
 -- Built-in Function: daspk_options (OPT, VAL)
     Query or set options for the function 'daspk'.  When called with no
     arguments, the names of all available options and their current
     values are displayed.  Given one argument, return the value of the
     corresponding option.  When called with two arguments,
     'daspk_options' set the option OPT to value VAL.

     Options include

     '"absolute tolerance"'
          Absolute tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the relative tolerance must also be a vector of the same
          length.

     '"relative tolerance"'
          Relative tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the absolute tolerance must also be a vector of the same
          length.

          The local error test applied at each integration step is

                 abs (local error in x(i))
                      <= rtol(i) * abs (Y(i)) + atol(i)

     '"compute consistent initial condition"'
          Denoting the differential variables in the state vector by
          'Y_d' and the algebraic variables by 'Y_a', 'ddaspk' can solve
          one of two initialization problems:

            1. Given Y_d, calculate Y_a and Y'_d

            2. Given Y', calculate Y.

          In either case, initial values for the given components are
          input, and initial guesses for the unknown components must
          also be provided as input.  Set this option to 1 to solve the
          first problem, or 2 to solve the second (the default is 0, so
          you must provide a set of initial conditions that are
          consistent).

          If this option is set to a nonzero value, you must also set
          the "algebraic variables" option to declare which variables in
          the problem are algebraic.

     '"use initial condition heuristics"'
          Set to a nonzero value to use the initial condition heuristics
          options described below.

     '"initial condition heuristics"'
          A vector of the following parameters that can be used to
          control the initial condition calculation.

          'MXNIT'
               Maximum number of Newton iterations (default is 5).

          'MXNJ'
               Maximum number of Jacobian evaluations (default is 6).

          'MXNH'
               Maximum number of values of the artificial stepsize
               parameter to be tried if the "compute consistent initial
               condition" option has been set to 1 (default is 5).

               Note that the maximum total number of Newton iterations
               allowed is 'MXNIT*MXNJ*MXNH' if the "compute consistent
               initial condition" option has been set to 1 and
               'MXNIT*MXNJ' if it is set to 2.

          'LSOFF'
               Set to a nonzero value to disable the linesearch
               algorithm (default is 0).

          'STPTOL'
               Minimum scaled step in linesearch algorithm (default is
               eps^(2/3)).

          'EPINIT'
               Swing factor in the Newton iteration convergence test.
               The test is applied to the residual vector, premultiplied
               by the approximate Jacobian.  For convergence, the
               weighted RMS norm of this vector (scaled by the error
               weights) must be less than 'EPINIT*EPCON', where 'EPCON'
               = 0.33 is the analogous test constant used in the time
               steps.  The default is 'EPINIT' = 0.01.

     '"print initial condition info"'
          Set this option to a nonzero value to display detailed
          information about the initial condition calculation (default
          is 0).

     '"exclude algebraic variables from error test"'
          Set to a nonzero value to exclude algebraic variables from the
          error test.  You must also set the "algebraic variables"
          option to declare which variables in the problem are algebraic
          (default is 0).

     '"algebraic variables"'
          A vector of the same length as the state vector.  A nonzero
          element indicates that the corresponding element of the state
          vector is an algebraic variable (i.e., its derivative does not
          appear explicitly in the equation set.

          This option is required by the compute consistent initial
          condition" and "exclude algebraic variables from error test"
          options.

     '"enforce inequality constraints"'
          Set to one of the following values to enforce the inequality
          constraints specified by the "inequality constraint types"
          option (default is 0).

            1. To have constraint checking only in the initial condition
               calculation.

            2. To enforce constraint checking during the integration.

            3. To enforce both options 1 and 2.

     '"inequality constraint types"'
          A vector of the same length as the state specifying the type
          of inequality constraint.  Each element of the vector
          corresponds to an element of the state and should be assigned
          one of the following codes

          -2
               Less than zero.

          -1
               Less than or equal to zero.

          0
               Not constrained.

          1
               Greater than or equal to zero.

          2
               Greater than zero.

          This option only has an effect if the "enforce inequality
          constraints" option is nonzero.

     '"initial step size"'
          Differential-algebraic problems may occasionally suffer from
          severe scaling difficulties on the first step.  If you know a
          great deal about the scaling of your problem, you can help to
          alleviate this problem by specifying an initial stepsize
          (default is computed automatically).

     '"maximum order"'
          Restrict the maximum order of the solution method.  This
          option must be between 1 and 5, inclusive (default is 5).

     '"maximum step size"'
          Setting the maximum stepsize will avoid passing over very
          large regions (default is not specified).

   Octave also includes DASSL, an earlier version of DASPK, and DASRT,
which can be used to solve DAEs with constraints (stopping conditions).

 -- Built-in Function: [X, XDOT, ISTATE, MSG] = dassl (FCN, X_0, XDOT_0,
          T, T_CRIT)
     Solve the set of differential-algebraic equations

          0 = f (x, xdot, t)

     with

          x(t_0) = x_0, xdot(t_0) = xdot_0

     The solution is returned in the matrices X and XDOT, with each row
     in the result matrices corresponding to one of the elements in the
     vector T.  The first element of T should be t_0 and correspond to
     the initial state of the system X_0 and its derivative XDOT_0, so
     that the first row of the output X is X_0 and the first row of the
     output XDOT is XDOT_0.

     The first argument, FCN, is a string, inline, or function handle
     that names the function f to call to compute the vector of
     residuals for the set of equations.  It must have the form

          RES = f (X, XDOT, T)

     in which X, XDOT, and RES are vectors, and T is a scalar.

     If FCN is a two-element string array or a two-element cell array of
     strings, inline functions, or function handles, the first element
     names the function f described above, and the second element names
     a function to compute the modified Jacobian

                df       df
          jac = -- + c ------
                dx     d xdot

     The modified Jacobian function must have the form


          JAC = j (X, XDOT, T, C)


     The second and third arguments to 'dassl' specify the initial
     condition of the states and their derivatives, and the fourth
     argument specifies a vector of output times at which the solution
     is desired, including the time corresponding to the initial
     condition.

     The set of initial states and derivatives are not strictly required
     to be consistent.  In practice, however, DASSL is not very good at
     determining a consistent set for you, so it is best if you ensure
     that the initial values result in the function evaluating to zero.

     The fifth argument is optional, and may be used to specify a set of
     times that the DAE solver should not integrate past.  It is useful
     for avoiding difficulties with singularities and points where there
     is a discontinuity in the derivative.

     After a successful computation, the value of ISTATE will be greater
     than zero (consistent with the Fortran version of DASSL).

     If the computation is not successful, the value of ISTATE will be
     less than zero and MSG will contain additional information.

     You can use the function 'dassl_options' to set optional parameters
     for 'dassl'.

     See also: *note daspk: XREFdaspk, *note dasrt: XREFdasrt, *note
     lsode: XREFlsode.

 -- Built-in Function: dassl_options ()
 -- Built-in Function: val = dassl_options (OPT)
 -- Built-in Function: dassl_options (OPT, VAL)
     Query or set options for the function 'dassl'.  When called with no
     arguments, the names of all available options and their current
     values are displayed.  Given one argument, return the value of the
     corresponding option.  When called with two arguments,
     'dassl_options' set the option OPT to value VAL.

     Options include

     '"absolute tolerance"'
          Absolute tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the relative tolerance must also be a vector of the same
          length.

     '"relative tolerance"'
          Relative tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the absolute tolerance must also be a vector of the same
          length.

          The local error test applied at each integration step is

                 abs (local error in x(i))
                      <= rtol(i) * abs (Y(i)) + atol(i)

     '"compute consistent initial condition"'
          If nonzero, 'dassl' will attempt to compute a consistent set
          of initial conditions.  This is generally not reliable, so it
          is best to provide a consistent set and leave this option set
          to zero.

     '"enforce nonnegativity constraints"'
          If you know that the solutions to your equations will always
          be non-negative, it may help to set this parameter to a
          nonzero value.  However, it is probably best to try leaving
          this option set to zero first, and only setting it to a
          nonzero value if that doesn't work very well.

     '"initial step size"'
          Differential-algebraic problems may occasionally suffer from
          severe scaling difficulties on the first step.  If you know a
          great deal about the scaling of your problem, you can help to
          alleviate this problem by specifying an initial stepsize.

     '"maximum order"'
          Restrict the maximum order of the solution method.  This
          option must be between 1 and 5, inclusive.

     '"maximum step size"'
          Setting the maximum stepsize will avoid passing over very
          large regions (default is not specified).

     '"step limit"'
          Maximum number of integration steps to attempt on a single
          call to the underlying Fortran code.

 -- Built-in Function: [X, XDOT, T_OUT, ISTAT, MSG] = dasrt (FCN, [],
          X_0, XDOT_0, T)
 -- Built-in Function: ... = dasrt (FCN, G, X_0, XDOT_0, T)
 -- Built-in Function: ... = dasrt (FCN, [], X_0, XDOT_0, T, T_CRIT)
 -- Built-in Function: ... = dasrt (FCN, G, X_0, XDOT_0, T, T_CRIT)
     Solve the set of differential-algebraic equations

          0 = f (x, xdot, t)

     with

          x(t_0) = x_0, xdot(t_0) = xdot_0

     with functional stopping criteria (root solving).

     The solution is returned in the matrices X and XDOT, with each row
     in the result matrices corresponding to one of the elements in the
     vector T_OUT.  The first element of T should be t_0 and correspond
     to the initial state of the system X_0 and its derivative XDOT_0,
     so that the first row of the output X is X_0 and the first row of
     the output XDOT is XDOT_0.

     The vector T provides an upper limit on the length of the
     integration.  If the stopping condition is met, the vector T_OUT
     will be shorter than T, and the final element of T_OUT will be the
     point at which the stopping condition was met, and may not
     correspond to any element of the vector T.

     The first argument, FCN, is a string, inline, or function handle
     that names the function f to call to compute the vector of
     residuals for the set of equations.  It must have the form

          RES = f (X, XDOT, T)

     in which X, XDOT, and RES are vectors, and T is a scalar.

     If FCN is a two-element string array or a two-element cell array of
     strings, inline functions, or function handles, the first element
     names the function f described above, and the second element names
     a function to compute the modified Jacobian

                df       df
          jac = -- + c ------
                dx     d xdot

     The modified Jacobian function must have the form


          JAC = j (X, XDOT, T, C)


     The optional second argument names a function that defines the
     constraint functions whose roots are desired during the
     integration.  This function must have the form

          G_OUT = g (X, T)

     and return a vector of the constraint function values.  If the
     value of any of the constraint functions changes sign, DASRT will
     attempt to stop the integration at the point of the sign change.

     If the name of the constraint function is omitted, 'dasrt' solves
     the same problem as 'daspk' or 'dassl'.

     Note that because of numerical errors in the constraint functions
     due to round-off and integration error, DASRT may return false
     roots, or return the same root at two or more nearly equal values
     of T.  If such false roots are suspected, the user should consider
     smaller error tolerances or higher precision in the evaluation of
     the constraint functions.

     If a root of some constraint function defines the end of the
     problem, the input to DASRT should nevertheless allow integration
     to a point slightly past that root, so that DASRT can locate the
     root by interpolation.

     The third and fourth arguments to 'dasrt' specify the initial
     condition of the states and their derivatives, and the fourth
     argument specifies a vector of output times at which the solution
     is desired, including the time corresponding to the initial
     condition.

     The set of initial states and derivatives are not strictly required
     to be consistent.  In practice, however, DASSL is not very good at
     determining a consistent set for you, so it is best if you ensure
     that the initial values result in the function evaluating to zero.

     The sixth argument is optional, and may be used to specify a set of
     times that the DAE solver should not integrate past.  It is useful
     for avoiding difficulties with singularities and points where there
     is a discontinuity in the derivative.

     After a successful computation, the value of ISTATE will be greater
     than zero (consistent with the Fortran version of DASSL).

     If the computation is not successful, the value of ISTATE will be
     less than zero and MSG will contain additional information.

     You can use the function 'dasrt_options' to set optional parameters
     for 'dasrt'.

     See also: *note dasrt_options: XREFdasrt_options, *note daspk:
     XREFdaspk, *note dasrt: XREFdasrt, *note lsode: XREFlsode.

 -- Built-in Function: dasrt_options ()
 -- Built-in Function: val = dasrt_options (OPT)
 -- Built-in Function: dasrt_options (OPT, VAL)
     Query or set options for the function 'dasrt'.  When called with no
     arguments, the names of all available options and their current
     values are displayed.  Given one argument, return the value of the
     corresponding option.  When called with two arguments,
     'dasrt_options' set the option OPT to value VAL.

     Options include

     '"absolute tolerance"'
          Absolute tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the relative tolerance must also be a vector of the same
          length.

     '"relative tolerance"'
          Relative tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the absolute tolerance must also be a vector of the same
          length.

          The local error test applied at each integration step is

                 abs (local error in x(i)) <= ...
                     rtol(i) * abs (Y(i)) + atol(i)

     '"initial step size"'
          Differential-algebraic problems may occasionally suffer from
          severe scaling difficulties on the first step.  If you know a
          great deal about the scaling of your problem, you can help to
          alleviate this problem by specifying an initial stepsize.

     '"maximum order"'
          Restrict the maximum order of the solution method.  This
          option must be between 1 and 5, inclusive.

     '"maximum step size"'
          Setting the maximum stepsize will avoid passing over very
          large regions.

     '"step limit"'
          Maximum number of integration steps to attempt on a single
          call to the underlying Fortran code.

   See K. E. Brenan, et al., 'Numerical Solution of Initial-Value
Problems in Differential-Algebraic Equations', North-Holland (1989) for
more information about the implementation of DASSL.


File: octave.info,  Node: Optimization,  Next: Statistics,  Prev: Differential Equations,  Up: Top

25 Optimization
***************

Octave comes with support for solving various kinds of optimization
problems.  Specifically Octave can solve problems in Linear Programming,
Quadratic Programming, Nonlinear Programming, and Linear Least Squares
Minimization.

* Menu:

* Linear Programming::
* Quadratic Programming::
* Nonlinear Programming::
* Linear Least Squares::


File: octave.info,  Node: Linear Programming,  Next: Quadratic Programming,  Up: Optimization

25.1 Linear Programming
=======================

Octave can solve Linear Programming problems using the 'glpk' function.
That is, Octave can solve

     min C'*x

   subject to the linear constraints A*x = b where x >= 0.

The 'glpk' function also supports variations of this problem.

 -- Function File: [XOPT, FMIN, ERRNUM, EXTRA] = glpk (C, A, B, LB, UB,
          CTYPE, VARTYPE, SENSE, PARAM)
     Solve a linear program using the GNU GLPK library.  Given three
     arguments, 'glpk' solves the following standard LP:

          min C'*x

     subject to

          A*x  = b
            x >= 0

     but may also solve problems of the form

          [ min | max ] C'*x

     subject to

          A*x [ "=" | "<=" | ">=" ] b
            x >= LB
            x <= UB

     Input arguments:

     C
          A column array containing the objective function coefficients.

     A
          A matrix containing the constraints coefficients.

     B
          A column array containing the right-hand side value for each
          constraint in the constraint matrix.

     LB
          An array containing the lower bound on each of the variables.
          If LB is not supplied, the default lower bound for the
          variables is zero.

     UB
          An array containing the upper bound on each of the variables.
          If UB is not supplied, the default upper bound is assumed to
          be infinite.

     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

          "F"
               A free (unbounded) constraint (the constraint is
               ignored).

          "U"
               An inequality constraint with an upper bound ('A(i,:)*x
               <= b(i)').

          "S"
               An equality constraint ('A(i,:)*x = b(i)').

          "L"
               An inequality with a lower bound ('A(i,:)*x >= b(i)').

          "D"
               An inequality constraint with both upper and lower bounds
               ('A(i,:)*x >= -b(i)' _and_ ('A(i,:)*x <= b(i)').

     VARTYPE
          A column array containing the types of the variables.

          "C"
               A continuous variable.

          "I"
               An integer variable.

     SENSE
          If SENSE is 1, the problem is a minimization.  If SENSE is -1,
          the problem is a maximization.  The default value is 1.

     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:

          'msglev (default: 1)'
               Level of messages output by solver routines:

               0 ('GLP_MSG_OFF')
                    No output.

               1 ('GLP_MSG_ERR')
                    Error and warning messages only.

               2 ('GLP_MSG_ON')
                    Normal output.

               3 ('GLP_MSG_ALL')
                    Full output (includes informational messages).

          'scale (default: 16)'
               Scaling option.  The values can be combined with the
               bitwise OR operator and may be the following:

               1 ('GLP_SF_GM')
                    Geometric mean scaling.

               16 ('GLP_SF_EQ')
                    Equilibration scaling.

               32 ('GLP_SF_2N')
                    Round scale factors to power of two.

               64 ('GLP_SF_SKIP')
                    Skip if problem is well scaled.

               Alternatively, a value of 128 ('GLP_SF_AUTO') may be also
               specified, in which case the routine chooses the scaling
               options automatically.

          'dual (default: 1)'
               Simplex method option:

               1 ('GLP_PRIMAL')
                    Use two-phase primal simplex.

               2 ('GLP_DUALP')
                    Use two-phase dual simplex, and if it fails, switch
                    to the primal simplex.

               3 ('GLP_DUAL')
                    Use two-phase dual simplex.

          'price (default: 34)'
               Pricing option (for both primal and dual simplex):

               17 ('GLP_PT_STD')
                    Textbook pricing.

               34 ('GLP_PT_PSE')
                    Steepest edge pricing.

          'itlim (default: intmax)'
               Simplex iterations limit.  It is decreased by one each
               time when one simplex iteration has been performed, and
               reaching zero value signals the solver to stop the
               search.

          'outfrq (default: 200)'
               Output frequency, in iterations.  This parameter
               specifies how frequently the solver sends information
               about the solution to the standard output.

          'branch (default: 4)'
               Branching technique option (for MIP only):

               1 ('GLP_BR_FFV')
                    First fractional variable.

               2 ('GLP_BR_LFV')
                    Last fractional variable.

               3 ('GLP_BR_MFV')
                    Most fractional variable.

               4 ('GLP_BR_DTH')
                    Heuristic by Driebeck and Tomlin.

               5 ('GLP_BR_PCH')
                    Hybrid pseudocost heuristic.

          'btrack (default: 4)'
               Backtracking technique option (for MIP only):

               1 ('GLP_BT_DFS')
                    Depth first search.

               2 ('GLP_BT_BFS')
                    Breadth first search.

               3 ('GLP_BT_BLB')
                    Best local bound.

               4 ('GLP_BT_BPH')
                    Best projection heuristic.

          'presol (default: 1)'
               If this flag is set, the simplex solver uses the built-in
               LP presolver.  Otherwise the LP presolver is not used.

          'lpsolver (default: 1)'
               Select which solver to use.  If the problem is a MIP
               problem this flag will be ignored.

               1
                    Revised simplex method.

               2
                    Interior point method.

          'rtest (default: 34)'
               Ratio test technique:

               17 ('GLP_RT_STD')
                    Standard ("textbook").

               34 ('GLP_RT_HAR')
                    Harris' two-pass ratio test.

          'tmlim (default: intmax)'
               Searching time limit, in milliseconds.

          'outdly (default: 0)'
               Output delay, in seconds.  This parameter specifies how
               long the solver should delay sending information about
               the solution to the standard output.

          'save (default: 0)'
               If this parameter is nonzero, save a copy of the problem
               in CPLEX LP format to the file '"outpb.lp"'.  There is
               currently no way to change the name of the output file.

          Real parameters:

          'tolbnd (default: 1e-7)'
               Relative tolerance used to check if the current basic
               solution is primal feasible.  It is not recommended that
               you change this parameter unless you have a detailed
               understanding of its purpose.

          'toldj (default: 1e-7)'
               Absolute tolerance used to check if the current basic
               solution is dual feasible.  It is not recommended that
               you change this parameter unless you have a detailed
               understanding of its purpose.

          'tolpiv (default: 1e-10)'
               Relative tolerance used to choose eligible pivotal
               elements of the simplex table.  It is not recommended
               that you change this parameter unless you have a detailed
               understanding of its purpose.

          'objll (default: -DBL_MAX)'
               Lower limit of the objective function.  If the objective
               function reaches this limit and continues decreasing, the
               solver stops the search.  This parameter is used in the
               dual simplex method only.

          'objul (default: +DBL_MAX)'
               Upper limit of the objective function.  If the objective
               function reaches this limit and continues increasing, the
               solver stops the search.  This parameter is used in the
               dual simplex only.

          'tolint (default: 1e-5)'
               Relative tolerance used to check if the current basic
               solution is integer feasible.  It is not recommended that
               you change this parameter unless you have a detailed
               understanding of its purpose.

          'tolobj (default: 1e-7)'
               Relative tolerance used to check if the value of the
               objective function is not better than in the best known
               integer feasible solution.  It is not recommended that
               you change this parameter unless you have a detailed
               understanding of its purpose.

     Output values:

     XOPT
          The optimizer (the value of the decision variables at the
          optimum).

     FOPT
          The optimum value of the objective function.

     ERRNUM
          Error code.

          0
               No error.

          1 ('GLP_EBADB')
               Invalid basis.

          2 ('GLP_ESING')
               Singular matrix.

          3 ('GLP_ECOND')
               Ill-conditioned matrix.

          4 ('GLP_EBOUND')
               Invalid bounds.

          5 ('GLP_EFAIL')
               Solver failed.

          6 ('GLP_EOBJLL')
               Objective function lower limit reached.

          7 ('GLP_EOBJUL')
               Objective function upper limit reached.

          8 ('GLP_EITLIM')
               Iterations limit exhausted.

          9 ('GLP_ETMLIM')
               Time limit exhausted.

          10 ('GLP_ENOPFS')
               No primal feasible solution.

          11 ('GLP_ENODFS')
               No dual feasible solution.

          12 ('GLP_EROOT')
               Root LP optimum not provided.

          13 ('GLP_ESTOP')
               Search terminated by application.

          14 ('GLP_EMIPGAP')
               Relative MIP gap tolerance reached.

          15 ('GLP_ENOFEAS')
               No primal/dual feasible solution.

          16 ('GLP_ENOCVG')
               No convergence.

          17 ('GLP_EINSTAB')
               Numerical instability.

          18 ('GLP_EDATA')
               Invalid data.

          19 ('GLP_ERANGE')
               Result out of range.

     EXTRA
          A data structure containing the following fields:

          'lambda'
               Dual variables.

          'redcosts'
               Reduced Costs.

          'time'
               Time (in seconds) used for solving LP/MIP problem.

          'status'
               Status of the optimization.

               1 ('GLP_UNDEF')
                    Solution status is undefined.

               2 ('GLP_FEAS')
                    Solution is feasible.

               3 ('GLP_INFEAS')
                    Solution is infeasible.

               4 ('GLP_NOFEAS')
                    Problem has no feasible solution.

               5 ('GLP_OPT')
                    Solution is optimal.

               6 ('GLP_UNBND')
                    Problem has no unbounded solution.

     Example:

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


File: octave.info,  Node: Quadratic Programming,  Next: Nonlinear Programming,  Prev: Linear Programming,  Up: Optimization

25.2 Quadratic Programming
==========================

Octave can also solve Quadratic Programming problems, this is

     min 0.5 x'*H*x + x'*q

   subject to

          A*x = b
          lb <= x <= ub
          A_lb <= A_in*x <= A_ub

 -- Function File: [X, OBJ, INFO, LAMBDA] = qp (X0, H)
 -- Function File: [X, OBJ, INFO, LAMBDA] = qp (X0, H, Q)
 -- Function File: [X, OBJ, INFO, LAMBDA] = qp (X0, H, Q, A, B)
 -- Function File: [X, OBJ, INFO, LAMBDA] = qp (X0, H, Q, A, B, LB, UB)
 -- Function File: [X, OBJ, INFO, LAMBDA] = qp (X0, H, Q, A, B, LB, UB,
          A_LB, A_IN, A_UB)
 -- Function File: [X, OBJ, INFO, LAMBDA] = qp (..., OPTIONS)
     Solve the quadratic program

          min 0.5 x'*H*x + x'*q
           x

     subject to

          A*x = b
          lb <= x <= ub
          A_lb <= A_in*x <= A_ub

     using a null-space active-set method.

     Any bound (A, B, LB, UB, A_LB, A_UB) may be set to the empty matrix
     ('[]') if not present.  If the initial guess is feasible the
     algorithm is faster.

     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.

          'MaxIter (default: 200)'
               Maximum number of iterations.

     INFO
          Structure containing run-time information about the algorithm.
          The following fields are defined:

          'solveiter'
               The number of iterations required to find the solution.

          'info'
               An integer indicating the status of the solution.

               0
                    The problem is feasible and convex.  Global solution
                    found.

               1
                    The problem is not convex.  Local solution found.

               2
                    The problem is not convex and unbounded.

               3
                    Maximum number of iterations reached.

               6
                    The problem is infeasible.

 -- Function File: X = pqpnonneg (C, D)
 -- Function File: X = pqpnonneg (C, D, X0)
 -- Function File: [X, MINVAL] = pqpnonneg (...)
 -- Function File: [X, MINVAL, EXITFLAG] = pqpnonneg (...)
 -- Function File: [X, MINVAL, EXITFLAG, OUTPUT] = pqpnonneg (...)
 -- Function File: [X, MINVAL, EXITFLAG, OUTPUT, LAMBDA] = pqpnonneg
          (...)
     Minimize '1/2*x'*c*x + d'*x' subject to 'X >= 0'.  C and D must be
     real, and C must be symmetric and positive definite.  X0 is an
     optional initial guess for X.

     Outputs:

        * minval

          The minimum attained model value, 1/2*xmin'*c*xmin + d'*xmin

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

        * output

          A structure with two fields:

             * "algorithm": The algorithm used ("nnls")

             * "iterations": The number of iterations taken.

        * lambda

          Not implemented.

     See also: *note optimset: XREFoptimset, *note lsqnonneg:
     XREFlsqnonneg, *note qp: XREFqp.


File: octave.info,  Node: Nonlinear Programming,  Next: Linear Least Squares,  Prev: Quadratic Programming,  Up: Optimization

25.3 Nonlinear Programming
==========================

Octave can also perform general nonlinear minimization using a
successive quadratic programming solver.

 -- Function File: [X, OBJ, INFO, ITER, NF, LAMBDA] = sqp (X0, PHI)
 -- Function File: [...] = sqp (X0, PHI, G)
 -- Function File: [...] = sqp (X0, PHI, G, H)
 -- Function File: [...] = sqp (X0, PHI, G, H, LB, UB)
 -- Function File: [...] = sqp (X0, PHI, G, H, LB, UB, MAXITER)
 -- Function File: [...] = sqp (X0, PHI, G, H, LB, UB, MAXITER, TOL)
     Solve the nonlinear program

          min phi (x)
           x

     subject to

          g(x)  = 0
          h(x) >= 0
          lb <= x <= ub

     using a sequential quadratic programming method.

     The first argument is the initial guess for the vector X0.

     The second argument is a function handle pointing to the objective
     function PHI.  The objective function must accept one vector
     argument and return a scalar.

     The second argument may also be a 2- or 3-element cell array of
     function handles.  The first element should point to the objective
     function, the second should point to a function that computes the
     gradient of the objective function, and the third should point to a
     function that computes the Hessian of the objective function.  If
     the gradient function is not supplied, the gradient is computed by
     finite differences.  If the Hessian function is not supplied, a
     BFGS update formula is used to approximate the Hessian.

     When supplied, the gradient function 'PHI{2}' must accept one
     vector argument and return a vector.  When supplied, the Hessian
     function 'PHI{3}' must accept one vector argument and return a
     matrix.

     The third and fourth arguments G and H are function handles
     pointing to functions that compute the equality constraints and the
     inequality constraints, respectively.  If the problem does not have
     equality (or inequality) constraints, then use an empty matrix ([])
     for G (or H).  When supplied, these equality and inequality
     constraint functions must accept one vector argument and return a
     vector.

     The third and fourth arguments may also be 2-element cell arrays of
     function handles.  The first element should point to the constraint
     function and the second should point to a function that computes
     the gradient of the constraint function:

                      [ d f(x)   d f(x)        d f(x) ]
          transpose ( [ ------   -----   ...   ------ ] )
                      [  dx_1     dx_2          dx_N  ]

     The fifth and sixth arguments, LB and UB, contain lower and upper
     bounds on X.  These must be consistent with the equality and
     inequality constraints G and H.  If the arguments are vectors then
     X(i) is bound by LB(i) and UB(i).  A bound can also be a scalar in
     which case all elements of X will share the same bound.  If only
     one bound (lb, ub) is specified then the other will default to
     (-REALMAX, +REALMAX).

     The seventh argument MAXITER specifies the maximum number of
     iterations.  The default value is 100.

     The eighth argument TOL specifies the tolerance for the stopping
     criteria.  The default value is 'sqrt (eps)'.

     The value returned in INFO may be one of the following:

     101
          The algorithm terminated normally.  Either all constraints
          meet the requested tolerance, or the stepsize, delta X, is
          less than 'TOL * norm (x)'.

     102
          The BFGS update failed.

     103
          The maximum number of iterations was reached.

     An example of calling 'sqp':

          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

     See also: *note qp: XREFqp.


File: octave.info,  Node: Linear Least Squares,  Prev: Nonlinear Programming,  Up: Optimization

25.4 Linear Least Squares
=========================

Octave also supports linear least squares minimization.  That is, Octave
can find the parameter b such that the model y = x*b fits data (x,y) as
well as possible, assuming zero-mean Gaussian noise.  If the noise is
assumed to be isotropic the problem can be solved using the '\' or '/'
operators, or the 'ols' function.  In the general case where the noise
is assumed to be anisotropic the 'gls' is needed.

 -- Function File: [BETA, SIGMA, R] = ols (Y, X)
     Ordinary least squares estimation for the multivariate model y = x*b + e
     with mean (e) = 0 and cov (vec (e)) = kron (s, I).  where y is a t
     by p matrix, x is a t by k matrix, b is a k by p matrix, and e is a
     t by p matrix.

     Each row of Y and X is an observation and each column a variable.

     The return values BETA, SIGMA, and R are defined as follows.

     BETA
          The OLS estimator for b.  BETA is calculated directly via 'inv
          (x'*x) * x' * y' if the matrix 'x'*x' is of full rank.
          Otherwise, 'BETA = pinv (X) * Y' where 'pinv (X)' denotes the
          pseudoinverse of X.

     SIGMA
          The OLS estimator for the matrix S,

               SIGMA = (Y-X*BETA)'
                 * (Y-X*BETA)
                 / (T-rank(X))

     R
          The matrix of OLS residuals, 'R = Y - X*BETA'.

     See also: *note gls: XREFgls, *note pinv: XREFpinv.

 -- Function File: [BETA, V, R] = gls (Y, X, O)
     Generalized least squares estimation for the multivariate model y = x*b + e
     with mean (e) = 0 and cov (vec (e)) = (s^2) o, where y is a t by p
     matrix, x is a t by k matrix, b is a k by p matrix, e is a t by p
     matrix, and o is a t*p by t*p matrix.

     Each row of Y and X is an observation and each column a variable.
     The return values BETA, V, and R are defined as follows.

     BETA
          The GLS estimator for b.

     V
          The GLS estimator for s^2.

     R
          The matrix of GLS residuals, r = y - x*beta.

     See also: *note ols: XREFols.

 -- Function File: X = lsqnonneg (C, D)
 -- Function File: X = lsqnonneg (C, D, X0)
 -- Function File: X = lsqnonneg (C, D, X0, OPTIONS)
 -- Function File: [X, RESNORM] = lsqnonneg (...)
 -- Function File: [X, RESNORM, RESIDUAL] = lsqnonneg (...)
 -- Function File: [X, RESNORM, RESIDUAL, EXITFLAG] = lsqnonneg (...)
 -- Function File: [X, RESNORM, RESIDUAL, EXITFLAG, OUTPUT] = lsqnonneg
          (...)
 -- Function File: [X, RESNORM, RESIDUAL, EXITFLAG, OUTPUT, LAMBDA] =
          lsqnonneg (...)
     Minimize 'norm (C*X - d)' subject to 'X >= 0'.  C and D must be
     real.  X0 is an optional initial guess for X.  Currently,
     'lsqnonneg' recognizes these options: "MaxIter", "TolX". For a
     description of these options, see *note optimset: XREFoptimset.

     Outputs:

        * resnorm

          The squared 2-norm of the residual: norm (C*X-D)^2

        * residual

          The residual: D-C*X

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

        * output

          A structure with two fields:

             * "algorithm": The algorithm used ("nnls")

             * "iterations": The number of iterations taken.

        * lambda

          Not implemented.

     See also: *note optimset: XREFoptimset, *note pqpnonneg:
     XREFpqpnonneg.

 -- Function File: optimset ()
 -- Function File: optimset (PAR, VAL, ...)
 -- Function File: optimset (OLD, PAR, VAL, ...)
 -- Function File: optimset (OLD, NEW)
     Create options struct for optimization functions.

     Valid parameters are:

     AutoScaling

     ComplexEqn

     Display
          Request verbose display of results from optimizations.  Values
          are:

          "off" [default]
               No display.

          "iter"
               Display intermediate results for every loop iteration.

          "final"
               Display the result of the final loop iteration.

          "notify"
               Display the result of the final loop iteration if the
               function has failed to converge.

     FinDiffType

     FunValCheck
          When enabled, display an error if the objective function
          returns an invalid value (a complex number, NaN, or Inf).
          Must be set to "on" or "off" [default].  Note: the functions
          'fzero' and 'fminbnd' correctly handle Inf values and only
          complex values or NaN will cause an error in this case.

     GradObj
          When set to "on", the function to be minimized must return a
          second argument which is the gradient, or first derivative, of
          the function at the point X.  If set to "off" [default], the
          gradient is computed via finite differences.

     Jacobian
          When set to "on", the function to be minimized must return a
          second argument which is the Jacobian, or first derivative, of
          the function at the point X.  If set to "off" [default], the
          Jacobian is computed via finite differences.

     MaxFunEvals
          Maximum number of function evaluations before optimization
          stops.  Must be a positive integer.

     MaxIter
          Maximum number of algorithm iterations before optimization
          stops.  Must be a positive integer.

     OutputFcn
          A user-defined function executed once per algorithm iteration.

     TolFun
          Termination criterion for the function output.  If the
          difference in the calculated objective function between one
          algorithm iteration and the next is less than 'TolFun' the
          optimization stops.  Must be a positive scalar.

     TolX
          Termination criterion for the function input.  If the
          difference in X, the current search point, between one
          algorithm iteration and the next is less than 'TolX' the
          optimization stops.  Must be a positive scalar.

     TypicalX

     Updating

 -- Function File: optimget (OPTIONS, PARNAME)
 -- Function File: optimget (OPTIONS, PARNAME, DEFAULT)
     Return a specific option from a structure created by 'optimset'.
     If PARNAME is not a field of the OPTIONS structure, return DEFAULT
     if supplied, otherwise return an empty matrix.


File: octave.info,  Node: Statistics,  Next: Sets,  Prev: Optimization,  Up: Top

26 Statistics
*************

Octave has support for various statistical methods.  This includes basic
descriptive statistics, probability distributions, statistical tests,
random number generation, and much more.

   The functions that analyze data all assume that multi-dimensional
data is arranged in a matrix where each row is an observation, and each
column is a variable.  Thus, the matrix defined by

     a = [ 0.9, 0.7;
           0.1, 0.1;
           0.5, 0.4 ];

contains three observations from a two-dimensional distribution.  While
this is the default data arrangement, most functions support different
arrangements.

   It should be noted that the statistics functions don't test for data
containing NaN, NA, or Inf.  These values need to be detected and dealt
with explicitly.  See *note isnan: XREFisnan, *note isna: XREFisna,
*note isinf: XREFisinf, *note isfinite: XREFisfinite.

* Menu:

* Descriptive Statistics::
* Basic Statistical Functions::
* Statistical Plots::
* Correlation and Regression Analysis::
* Distributions::
* Tests::
* Random Number Generation::


File: octave.info,  Node: Descriptive Statistics,  Next: Basic Statistical Functions,  Up: Statistics

26.1 Descriptive Statistics
===========================

One principal goal of descriptive statistics is to represent the essence
of a large data set concisely.  Octave provides the mean, median, and
mode functions which all summarize a data set with just a single number
corresponding to the central tendency of the data.

 -- Function File: mean (X)
 -- Function File: mean (X, DIM)
 -- Function File: mean (X, OPT)
 -- Function File: mean (X, DIM, OPT)
     Compute the mean of the elements of the vector X.

          mean (x) = SUM_i x(i) / N

     If X is a matrix, compute the mean for each column and return them
     in a row vector.

     The optional argument OPT selects the type of mean to compute.  The
     following options are recognized:

     "a"
          Compute the (ordinary) arithmetic mean.  [default]

     "g"
          Compute the geometric mean.

     "h"
          Compute the harmonic mean.

     If the optional argument DIM is given, operate along this
     dimension.

     Both DIM and OPT are optional.  If both are supplied, either may
     appear first.

     See also: *note median: XREFmedian, *note mode: XREFmode.

 -- Function File: median (X)
 -- Function File: median (X, DIM)
     Compute the median value of the elements of the vector X.  If the
     elements of X are sorted, the median is defined as

                        x(ceil(N/2))             N odd
          median (x) =
                       (x(N/2) + x((N/2)+1))/2   N even

     If X is a matrix, compute the median value for each column and
     return them in a row vector.  If the optional DIM argument is
     given, operate along this dimension.

     See also: *note mean: XREFmean, *note mode: XREFmode.

 -- Function File: mode (X)
 -- Function File: mode (X, DIM)
 -- Function File: [M, F, C] = mode (...)
     Compute the most frequently occurring value in a dataset (mode).
     '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 'mode'
     returns the smallest.

     If the optional argument DIM is given, operate along this
     dimension.

     The return variable F is the number of occurrences of the mode in
     in the dataset.  The cell array C contains all of the elements with
     the maximum frequency.

     See also: *note mean: XREFmean, *note median: XREFmedian.

   Using just one number, such as the mean, to represent an entire data
set may not give an accurate picture of the data.  One way to
characterize the fit is to measure the dispersion of the data.  Octave
provides several functions for measuring dispersion.

 -- Function File: range (X)
 -- Function File: range (X, DIM)
     Return the range, i.e., the difference between the maximum and the
     minimum of the input data.  If X is a vector, the range is
     calculated over the elements of X.  If X is a matrix, the range is
     calculated over each column of X.

     If the optional argument 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 'iqr' if there are outlying data
     points.

     See also: *note iqr: XREFiqr, *note std: XREFstd.

 -- Function File: iqr (X)
 -- Function File: iqr (X, DIM)
     Return the interquartile range, i.e., the difference between the
     upper and lower quartile of the input data.  If X is a matrix, do
     the above for first non-singleton dimension of X.

     If the optional argument DIM is given, operate along this
     dimension.

     As a measure of dispersion, the interquartile range is less
     affected by outliers than either 'range' or 'std'.

     See also: *note range: XREFrange, *note std: XREFstd.

 -- Function File: meansq (X)
 -- Function File: meansq (X, DIM)
     Compute the mean square of the elements of the vector X.

          std (x) = 1/N SUM_i x(i)^2

     For matrix arguments, return a row vector containing the mean
     square of each column.

     If the optional argument DIM is given, operate along this
     dimension.

     See also: *note var: XREFvar, *note std: XREFstd, *note moment:
     XREFmoment.

 -- Function File: std (X)
 -- Function File: std (X, OPT)
 -- Function File: std (X, OPT, DIM)
     Compute the standard deviation of the elements of the vector X.

          std (x) = sqrt ( 1/(N-1) SUM_i (x(i) - mean(x))^2 )

     where N is the number of elements.

     If X is a matrix, compute the standard deviation for each column
     and return them in a row vector.

     The argument OPT determines the type of normalization to use.
     Valid values are

     0:
          normalize with N-1, provides the square root of the best
          unbiased estimator of the variance [default]

     1:
          normalize with N, this provides the square root of the second
          moment around the mean

     If the optional argument DIM is given, operate along this
     dimension.

     See also: *note var: XREFvar, *note range: XREFrange, *note iqr:
     XREFiqr, *note mean: XREFmean, *note median: XREFmedian.

   In addition to knowing the size of a dispersion it is useful to know
the shape of the data set.  For example, are data points massed to the
left or right of the mean?  Octave provides several common measures to
describe the shape of the data set.  Octave can also calculate moments
allowing arbitrary shape measures to be developed.

 -- Function File: var (X)
 -- Function File: var (X, OPT)
 -- Function File: var (X, OPT, DIM)
     Compute the variance of the elements of the vector X.

          var (x) = 1/(N-1) SUM_i (x(i) - mean(x))^2

     If X is a matrix, compute the variance for each column and return
     them in a row vector.

     The argument OPT determines the type of normalization to use.
     Valid values are

     0:
          normalize with N-1, provides the best unbiased estimator of
          the variance [default]

     1:
          normalizes with N, this provides the second moment around the
          mean

     If N==1 the value of OPT is ignored and normalization by N is used.

     If the optional argument DIM is given, operate along this
     dimension.

     See also: *note cov: XREFcov, *note std: XREFstd, *note skewness:
     XREFskewness, *note kurtosis: XREFkurtosis, *note moment:
     XREFmoment.

 -- Function File: skewness (X)
 -- Function File: skewness (X, FLAG)
 -- Function File: skewness (X, FLAG, DIM)
     Compute the sample skewness of the elements of X:

                         mean ((X - mean (X)).^3)
          skewness (X) = ------------------------.
                                std (X).^3

     The optional argument FLAG controls which normalization is used.
     If FLAG is equal to 1 (default value, used when FLAG is omitted or
     empty), return the sample skewness as defined above.  If FLAG is
     equal to 0, return the adjusted skewness coefficient instead:

                            sqrt (N*(N-1))   mean ((X - mean (X)).^3)
          skewness (X, 0) = -------------- * ------------------------.
                                (N - 2)             std (X).^3

     The adjusted skewness coefficient is obtained by replacing the
     sample second and third central moments by their bias-corrected
     versions.

     If X is a matrix, or more generally a multi-dimensional array,
     return the skewness along the first non-singleton dimension.  If
     the optional DIM argument is given, operate along this dimension.

     See also: *note var: XREFvar, *note kurtosis: XREFkurtosis, *note
     moment: XREFmoment.

 -- Function File: kurtosis (X)
 -- Function File: kurtosis (X, FLAG)
 -- Function File: kurtosis (X, FLAG, DIM)
     Compute the sample kurtosis of the elements of X:

               mean ((X - mean (X)).^4)
          k1 = ------------------------
                      std (X).^4

     The optional argument FLAG controls which normalization is used.
     If FLAG is equal to 1 (default value, used when FLAG is omitted or
     empty), return the sample kurtosis as defined above.  If FLAG is
     equal to 0, return the "bias-corrected" kurtosis coefficient
     instead:

                        N - 1
          k0 = 3 + -------------- * ((N + 1) * k1 - 3 * (N - 1))
                   (N - 2)(N - 3)

     The bias-corrected kurtosis coefficient is obtained by replacing
     the sample second and fourth central moments by their unbiased
     versions.  It is an unbiased estimate of the population kurtosis
     for normal populations.

     If X is a matrix, or more generally a multi-dimensional array,
     return the kurtosis along the first non-singleton dimension.  If
     the optional DIM argument is given, operate along this dimension.

     See also: *note var: XREFvar, *note skewness: XREFskewness, *note
     moment: XREFmoment.

 -- Function File: moment (X, P)
 -- Function File: moment (X, P, TYPE)
 -- Function File: moment (X, P, DIM)
 -- Function File: moment (X, P, TYPE, DIM)
 -- Function File: moment (X, P, DIM, TYPE)
     Compute the P-th central moment of the vector X.

          1/N SUM_i (x(i) - mean(x))^p

     If X is a matrix, return the row vector containing the P-th central
     moment of each column.

     The optional string TYPE specifies the type of moment to be
     computed.  Valid options are:

     "c"
          Central Moment (default).

     "a"
     "ac"
          Absolute Central Moment.  The moment about the mean ignoring
          sign defined as

               1/N SUM_i (abs (x(i) - mean(x)))^p

     "r"
          Raw Moment.  The moment about zero defined as

               moment (x) = 1/N SUM_i x(i)^p

     "ar"
          Absolute Raw Moment.  The moment about zero ignoring sign
          defined as

               1/N SUM_i ( abs (x(i)) )^p

     If the optional argument DIM is given, operate along this
     dimension.

     If both TYPE and DIM are given they may appear in any order.

     See also: *note var: XREFvar, *note skewness: XREFskewness, *note
     kurtosis: XREFkurtosis.

 -- Function File: Q = quantile (X)
 -- Function File: Q = quantile (X, P)
 -- Function File: Q = quantile (X, P, DIM)
 -- Function File: Q = quantile (X, P, DIM, METHOD)
     For a sample, X, calculate the quantiles, Q, corresponding to the
     cumulative probability values in P.  All non-numeric values (NaNs)
     of X are ignored.

     If X is a matrix, compute the quantiles for each column and return
     them in a matrix, such that the i-th row of Q contains the P(i)th
     quantiles of each column of X.

     If P is unspecified, return the quantiles for '[0.00 0.25 0.50 0.75
     1.00]'.  The optional argument DIM determines the dimension along
     which the quantiles are calculated.  If DIM is omitted, and X is a
     vector or matrix, it defaults to 1 (column-wise quantiles).  If X
     is an N-D array, 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

       1. Method 1: Inverse of empirical distribution function.

       2. Method 2: Similar to method 1 but with averaging at
          discontinuities.

       3. Method 3: SAS definition: nearest even order statistic.

     Continuous sample quantile methods 4 through 9, where p(k) is the
     linear interpolation function respecting each methods'
     representative cdf.

       4. Method 4: p(k) = k / n.  That is, linear interpolation of the
          empirical cdf.

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

       6. Method 6: p(k) = k / (n + 1).

       7. Method 7: p(k) = (k - 1) / (n - 1).

       8. Method 8: p(k) = (k - 1/3) / (n + 1/3).  The resulting
          quantile estimates are approximately median-unbiased
          regardless of the distribution of X.

       9. Method 9: p(k) = (k - 3/8) / (n + 1/4).  The resulting
          quantile estimates are approximately unbiased for the expected
          order statistics if X is normally distributed.

     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.  MATLAB uses method 5.

     References:

        * Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New
          S Language.  Wadsworth & Brooks/Cole.

        * Hyndman, R. J. and Fan, Y. (1996) Sample quantiles in
          statistical packages, American Statistician, 50, 361-365.

        * R: A Language and Environment for Statistical Computing;
          <http://cran.r-project.org/doc/manuals/fullrefman.pdf>.

     Examples:

          x = randi (1000, [10, 1]);  # Create empirical data in range 1-1000
          q = quantile (x, [0, 1]);   # Return minimum, maximum of distribution
          q = quantile (x, [0.25 0.5 0.75]); # Return quartiles of distribution

     See also: *note prctile: XREFprctile.

 -- Function File: Q = prctile (X)
 -- Function File: Q = prctile (X, P)
 -- Function File: Q = prctile (X, P, DIM)
     For a sample X, compute the quantiles, Q, corresponding to the
     cumulative probability values, P, in percent.  All non-numeric
     values (NaNs) of X are ignored.

     If X is a matrix, compute the percentiles for each column and
     return them in a matrix, such that the i-th row of Y contains the
     P(i)th percentiles of each column of X.

     If P is unspecified, return the quantiles for '[0 25 50 75 100]'.
     The optional argument DIM determines the dimension along which the
     percentiles are calculated.  If DIM is omitted, and X is a vector
     or matrix, it defaults to 1 (column-wise quantiles).  When X is an
     N-D array, DIM defaults to the first non-singleton dimension.

     See also: *note quantile: XREFquantile.

   A summary view of a data set can be generated quickly with the
'statistics' function.

 -- Function File: statistics (X)
 -- Function File: statistics (X, 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 X.

     If X is a matrix, calculate statistics over the first non-singleton
     dimension.  If the optional argument DIM is given, operate along
     this dimension.

     See also: *note min: XREFmin, *note max: XREFmax, *note median:
     XREFmedian, *note mean: XREFmean, *note std: XREFstd, *note
     skewness: XREFskewness, *note kurtosis: XREFkurtosis.


File: octave.info,  Node: Basic Statistical Functions,  Next: Statistical Plots,  Prev: Descriptive Statistics,  Up: Statistics

26.2 Basic Statistical Functions
================================

Octave supports various helpful statistical functions.  Many are useful
as initial steps to prepare a data set for further analysis.  Others
provide different measures from those of the basic descriptive
statistics.

 -- Function File: center (X)
 -- Function File: center (X, DIM)
     If X is a vector, subtract its mean.  If X is a matrix, do the
     above for each column.  If the optional argument DIM is given,
     operate along this dimension.

     See also: *note zscore: XREFzscore.

 -- Function File: [Z, MU, SIGMA] = zscore (X)
 -- Function File: [Z, MU, SIGMA] = zscore (X, OPT)
 -- Function File: [Z, MU, SIGMA] = zscore (X, OPT, DIM)
     If X is a vector, subtract its mean and divide by its standard
     deviation.  If the standard deviation is zero, divide by 1 instead.
     The optional parameter OPT determines the normalization to use when
     computing the standard deviation and is the same as the
     corresponding parameter for 'std'.

     If X is a matrix, do the above along the first non-singleton
     dimension.  If the third optional argument DIM is given, operate
     along this dimension.

     The mean and standard deviation along DIM are given in MU and SIGMA
     respectively.

     See also: *note mean: XREFmean, *note std: XREFstd, *note center:
     XREFcenter.

 -- Function File: N = histc (X, EDGES)
 -- Function File: N = histc (X, EDGES, DIM)
 -- Function File: [N, IDX] = histc (...)
     Produce histogram counts.

     When X is a vector, the function counts the number of elements of X
     that fall in the histogram bins defined by EDGES.  This must be a
     vector of monotonically increasing values that define the edges of
     the histogram bins.  'N(k)' contains the number of elements in X
     for which 'EDGES(k) <= X < EDGES(k+1)'.  The final element of N
     contains the number of elements of X exactly equal to the last
     element of EDGES.

     When X is an N-dimensional array, the computation is carried out
     along dimension DIM.  If not specified DIM defaults to the first
     non-singleton dimension.

     When a second output argument is requested an index matrix is also
     returned.  The IDX matrix has the same size as X.  Each element of
     IDX contains the index of the histogram bin in which the
     corresponding element of X was counted.

     See also: *note hist: XREFhist.

 -- Function File: C = nchoosek (N, K)
 -- Function File: C = nchoosek (SET, K)

     Compute the binomial coefficient or all combinations of a set of
     items.

     If N is a scalar then calculate the binomial coefficient of N and K
     which is defined as

           /   \
           | n |    n (n-1) (n-2) ... (n-k+1)       n!
           |   |  = ------------------------- =  ---------
           | k |               k!                k! (n-k)!
           \   /

     This is the number of combinations of N items taken in groups of
     size K.

     If the first argument is a vector, SET, then generate all
     combinations of the elements of SET, taken K at a time, with one
     row per combination.  The result C has K columns and 'nchoosek (length (SET), K)'
     rows.

     For example:

     How many ways can three items be grouped into pairs?

          nchoosek (3, 2)
             => 3

     What are the possible pairs?

          nchoosek (1:3, 2)
             =>  1   2
                 1   3
                 2   3

     'nchoosek' works only for non-negative, integer arguments.  Use
     'bincoeff' for non-integer and negative scalar arguments, or for
     computing many binomial coefficients at once with vector inputs for
     N or K.

     See also: *note bincoeff: XREFbincoeff, *note perms: XREFperms.

 -- Function File: perms (V)

     Generate all permutations of V, one row per permutation.  The
     result has size 'factorial (N) * N', where N is the length of V.

     As an example, 'perms ([1, 2, 3])' returns the matrix

            1   2   3
            2   1   3
            1   3   2
            2   3   1
            3   1   2
            3   2   1

 -- Function File: ranks (X, DIM)
     Return the ranks of X along the first non-singleton dimension
     adjusted for ties.  If the optional argument DIM is given, operate
     along this dimension.

     See also: *note spearman: XREFspearman, *note kendall: XREFkendall.

 -- Function File: run_count (X, N)
 -- Function File: run_count (X, N, DIM)
     Count the upward runs along the first non-singleton dimension of X
     of length 1, 2, ..., N-1 and greater than or equal to N.

     If the optional argument DIM is given then operate along this
     dimension.

 -- Function File: [count, value] = runlength (X)
     Find the lengths of all sequences of common values.  Return the
     vector of lengths and the value that was repeated.

          runlength ([2, 2, 0, 4, 4, 4, 0, 1, 1, 1, 1])
          =>  [2, 1, 3, 1, 4]

 -- Function File: probit (P)
     For each component of P, return the probit (the quantile of the
     standard normal distribution) of P.

 -- Function File: logit (P)
     For each component of P, return the logit of P defined as

          logit (P) = log (P / (1-P))

     See also: *note logistic_cdf: XREFlogistic_cdf.

 -- Function File: cloglog (X)
     Return the complementary log-log function of X, defined as

          cloglog (x) = - log (- log (X))

 -- Function File: mahalanobis (X, Y)
     Return the Mahalanobis' D-square distance between the multivariate
     samples X and Y, which must have the same number of components
     (columns), but may have a different number of observations (rows).

 -- Function File: [T, L_X] = table (X)
 -- Function File: [T, L_X, L_Y] = table (X, Y)
     Create a contingency table T from data vectors.  The L_X and L_Y
     vectors are the corresponding levels.

     Currently, only 1- and 2-dimensional tables are supported.


File: octave.info,  Node: Statistical Plots,  Next: Correlation and Regression Analysis,  Prev: Basic Statistical Functions,  Up: Statistics

26.3 Statistical Plots
======================

Octave can create Quantile Plots (QQ-Plots), and Probability Plots
(PP-Plots).  These are simple graphical tests for determining if a data
set comes from a certain distribution.

   Note that Octave can also show histograms of data using the 'hist'
function as described in *note Two-Dimensional Plots::.

 -- Function File: [Q, S] = qqplot (X)
 -- Function File: [Q, S] = qqplot (X, Y)
 -- Function File: [Q, S] = qqplot (X, DIST)
 -- Function File: [Q, S] = qqplot (X, Y, PARAMS)
 -- Function File: qqplot (...)
     Perform a QQ-plot (quantile plot).

     If F is the CDF of the distribution DIST with parameters PARAMS and
     G its inverse, and X a sample vector of length N, the QQ-plot
     graphs ordinate S(I) = I-th largest element of x versus abscissa
     Q(If) = G((I - 0.5)/N).

     If the sample comes from F, except for a transformation of location
     and scale, the pairs will approximately follow a straight line.

     If the second argument is a vector Y the empirical CDF of Y is used
     as DIST.

     The default for DIST is the standard normal distribution.  The
     optional argument PARAMS contains a list of parameters of DIST.
     For example, for a quantile plot of the uniform distribution on
     [2,4] and X, use

          qqplot (x, "unif", 2, 4)

     DIST can be any string for which a function DISTINV or DIST_INV
     exists that calculates the inverse CDF of distribution DIST.

     If no output arguments are given, the data are plotted directly.

 -- Function File: [P, Y] = ppplot (X, DIST, PARAMS)
     Perform a PP-plot (probability plot).

     If F is the CDF of the distribution DIST with parameters PARAMS and
     X a sample vector of length N, the PP-plot graphs ordinate Y(I) = F
     (I-th largest element of X) versus abscissa P(I) = (I - 0.5)/N.  If
     the sample comes from F, the pairs will approximately follow a
     straight line.

     The default for DIST is the standard normal distribution.  The
     optional argument PARAMS contains a list of parameters of DIST.
     For example, for a probability plot of the uniform distribution on
     [2,4] and X, use

          ppplot (x, "uniform", 2, 4)

     DIST can be any string for which a function DIST_CDF that
     calculates the CDF of distribution DIST exists.

     If no output arguments are given, the data are plotted directly.


File: octave.info,  Node: Correlation and Regression Analysis,  Next: Distributions,  Prev: Statistical Plots,  Up: Statistics

26.4 Correlation and Regression Analysis
========================================

 -- Function File: cov (X)
 -- Function File: cov (X, OPT)
 -- Function File: cov (X, Y)
 -- Function File: cov (X, Y, OPT)
     Compute the covariance matrix.

     If each row of X and Y is an observation, and each column is a
     variable, then the (I, J)-th entry of 'cov (X, Y)' is the
     covariance between the I-th variable in X and the J-th variable in
     Y.

          cov (x) = 1/N-1 * SUM_i (x(i) - mean(x)) * (y(i) - mean(y))

     If called with one argument, compute 'cov (X, X)', the covariance
     between the columns of X.

     The argument OPT determines the type of normalization to use.
     Valid values are

     0:
          normalize with N-1, provides the best unbiased estimator of
          the covariance [default]

     1:
          normalize with N, this provides the second moment around the
          mean

     See also: *note corr: XREFcorr.

 -- Function File: corr (X)
 -- Function File: corr (X, Y)
     Compute matrix of correlation coefficients.

     If each row of X and Y is an observation and each column is a
     variable, then the (I, J)-th entry of 'corr (X, Y)' is the
     correlation between the I-th variable in X and the J-th variable in
     Y.

          corr (x,y) = cov (x,y) / (std (x) * std (y))

     If called with one argument, compute 'corr (X, X)', the correlation
     between the columns of X.

     See also: *note cov: XREFcov.

 -- Function File: spearman (X)
 -- Function File: spearman (X, Y)
     Compute Spearman's rank correlation coefficient RHO.

     For two data vectors X and Y, Spearman's RHO is the correlation
     coefficient of the ranks of X and Y.

     If X and Y are drawn from independent distributions, RHO has zero
     mean and variance '1 / (n - 1)', and is asymptotically normally
     distributed.

     'spearman (X)' is equivalent to 'spearman (X, X)'.

     See also: *note ranks: XREFranks, *note kendall: XREFkendall.

 -- Function File: kendall (X)
 -- Function File: kendall (X, Y)
     Compute Kendall's TAU.

     For two data vectors X, Y of common length N, Kendall's TAU is the
     correlation of the signs of all rank differences of X and Y; i.e.,
     if both X and Y have distinct entries, then

                   1
          tau = -------   SUM sign (q(i) - q(j)) * sign (r(i) - r(j))
                n (n-1)   i,j

     in which the Q(I) and R(I) are the ranks of X and Y, respectively.

     If X and Y are drawn from independent distributions, Kendall's TAU
     is asymptotically normal with mean 0 and variance '(2 * (2N+5)) /
     (9 * N * (N-1))'.

     'kendall (X)' is equivalent to 'kendall (X, X)'.

     See also: *note ranks: XREFranks, *note spearman: XREFspearman.

 -- Function File: [THETA, BETA, DEV, DL, D2L, P] = logistic_regression
          (Y, X, PRINT, THETA, BETA)
     Perform ordinal logistic regression.

     Suppose Y takes values in K ordered categories, and let 'gamma_i
     (X)' be the cumulative probability that Y falls in one of the first
     I categories given the covariate X.  Then

          [theta, beta] = logistic_regression (y, x)

     fits the model

          logit (gamma_i (x)) = theta_i - beta' * x,   i = 1 ... k-1

     The number of ordinal categories, K, is taken to be the number of
     distinct values of 'round (Y)'.  If K equals 2, Y is binary and the
     model is ordinary logistic regression.  The matrix X is assumed to
     have full column rank.

     Given Y only, 'theta = logistic_regression (y)' fits the model with
     baseline logit odds only.

     The full form is

          [theta, beta, dev, dl, d2l, gamma]
             = logistic_regression (y, x, print, theta, beta)

     in which all output arguments and all input arguments except Y are
     optional.

     Setting PRINT to 1 requests summary information about the fitted
     model to be displayed.  Setting PRINT to 2 requests information
     about convergence at each iteration.  Other values request no
     information to be displayed.  The input arguments THETA and BETA
     give initial estimates for THETA and BETA.

     The returned value DEV holds minus twice the log-likelihood.

     The returned values DL and D2L are the vector of first and the
     matrix of second derivatives of the log-likelihood with respect to
     THETA and BETA.

     P holds estimates for the conditional distribution of Y given X.


File: octave.info,  Node: Distributions,  Next: Tests,  Prev: Correlation and Regression Analysis,  Up: Statistics

26.5 Distributions
==================

Octave has functions for computing the Probability Density Function
(PDF), the Cumulative Distribution function (CDF), and the quantile (the
inverse of the CDF) for a large number of distributions.

   The following table summarizes the supported distributions (in
alphabetical order).

Distribution           PDF               CDF               Quantile
-----------------------------------------------------------------------------
Beta Distribution      'betapdf'         'betacdf'         'betainv'
Binomial               'binopdf'         'binocdf'         'binoinv'
Distribution
Cauchy Distribution    'cauchy_pdf'      'cauchy_cdf'      'cauchy_inv'
Chi-Square             'chi2pdf'         'chi2cdf'         'chi2inv'
Distribution
Univariate Discrete    'discrete_pdf'    'discrete_cdf'    'discrete_inv'
Distribution
Empirical              'empirical_pdf'   'empirical_cdf'   'empirical_inv'
Distribution
Exponential            'exppdf'          'expcdf'          'expinv'
Distribution
F Distribution         'fpdf'            'fcdf'            'finv'
Gamma Distribution     'gampdf'          'gamcdf'          'gaminv'
Geometric              'geopdf'          'geocdf'          'geoinv'
Distribution
Hypergeometric         'hygepdf'         'hygecdf'         'hygeinv'
Distribution
Kolmogorov Smirnov     _Not Available_   'kolmogorov_smirnov_cdf'_Not Available_
Distribution
Laplace Distribution   'laplace_pdf'     'laplace_cdf'     'laplace_inv'
Logistic               'logistic_pdf'    'logistic_cdf'    'logistic_inv'
Distribution
Log-Normal             'lognpdf'         'logncdf'         'logninv'
Distribution
Univariate Normal      'normpdf'         'normcdf'         'norminv'
Distribution
Pascal Distribution    'nbinpdf'         'nbincdf'         'nbininv'
Poisson Distribution   'poisspdf'        'poisscdf'        'poissinv'
Standard Normal        'stdnormal_pdf'   'stdnormal_cdf'   'stdnormal_inv'
Distribution
t (Student)            'tpdf'            'tcdf'            'tinv'
Distribution
Univariate Discrete    'unidpdf'         'unidcdf'         'unidinv'
Distribution
Uniform Distribution   'unifpdf'         'unifcdf'         'unifinv'
Weibull Distribution   'wblpdf'          'wblcdf'          'wblinv'

 -- Function File: betapdf (X, A, B)
     For each element of X, compute the probability density function
     (PDF) at X of the Beta distribution with parameters A and B.

 -- Function File: betacdf (X, A, B)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the Beta distribution with parameters A and B.

 -- Function File: betainv (X, A, B)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the Beta distribution with parameters A and B.

 -- Function File: binopdf (X, N, P)
     For each element of X, compute the probability density function
     (PDF) at X of the binomial distribution with parameters N and P,
     where N is the number of trials and P is the probability of
     success.

 -- Function File: binocdf (X, N, P)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the binomial distribution with parameters N and P,
     where N is the number of trials and P is the probability of
     success.

 -- Function File: binoinv (X, N, P)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the binomial distribution with parameters N and P,
     where N is the number of trials and P is the probability of
     success.

 -- Function File: cauchy_pdf (X)
 -- Function File: cauchy_pdf (X, LOCATION, SCALE)
     For each element of X, compute the probability density function
     (PDF) at X of the Cauchy distribution with location parameter
     LOCATION and scale parameter SCALE > 0.  Default values are
     LOCATION = 0, SCALE = 1.

 -- Function File: cauchy_cdf (X)
 -- Function File: cauchy_cdf (X, LOCATION, SCALE)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the Cauchy distribution with location parameter
     LOCATION and scale parameter SCALE.  Default values are LOCATION =
     0, SCALE = 1.

 -- Function File: cauchy_inv (X)
 -- Function File: cauchy_inv (X, LOCATION, SCALE)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the Cauchy distribution with location parameter
     LOCATION and scale parameter SCALE.  Default values are LOCATION =
     0, SCALE = 1.

 -- Function File: chi2pdf (X, N)
     For each element of X, compute the probability density function
     (PDF) at X of the chi-square distribution with N degrees of
     freedom.

 -- Function File: chi2cdf (X, N)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the chi-square distribution with N degrees of
     freedom.

 -- Function File: chi2inv (X, N)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the chi-square distribution with N degrees of freedom.

 -- Function File: discrete_pdf (X, V, P)
     For each element of X, compute the probability density function
     (PDF) at X of a univariate discrete distribution which assumes the
     values in V with probabilities P.

 -- Function File: discrete_cdf (X, V, P)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of a univariate discrete distribution which assumes the
     values in V with probabilities P.

 -- Function File: discrete_inv (X, V, P)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the univariate distribution which assumes the values
     in V with probabilities P.

 -- Function File: empirical_pdf (X, DATA)
     For each element of X, compute the probability density function
     (PDF) at X of the empirical distribution obtained from the
     univariate sample DATA.

 -- Function File: empirical_cdf (X, DATA)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the empirical distribution obtained from the
     univariate sample DATA.

 -- Function File: empirical_inv (X, DATA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the empirical distribution obtained from the
     univariate sample DATA.

 -- Function File: exppdf (X, LAMBDA)
     For each element of X, compute the probability density function
     (PDF) at X of the exponential distribution with mean LAMBDA.

 -- Function File: expcdf (X, LAMBDA)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the exponential distribution with mean LAMBDA.

     The arguments can be of common size or scalars.

 -- Function File: expinv (X, LAMBDA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the exponential distribution with mean LAMBDA.

 -- Function File: fpdf (X, M, N)
     For each element of X, compute the probability density function
     (PDF) at X of the F distribution with M and N degrees of freedom.

 -- Function File: fcdf (X, M, N)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the F distribution with M and N degrees of freedom.

 -- Function File: finv (X, M, N)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the F distribution with M and N degrees of freedom.

 -- Function File: gampdf (X, A, B)
     For each element of X, return the probability density function
     (PDF) at X of the Gamma distribution with shape parameter A and
     scale B.

 -- Function File: gamcdf (X, A, B)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the Gamma distribution with shape parameter A and
     scale B.

 -- Function File: gaminv (X, A, B)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the Gamma distribution with shape parameter A and
     scale B.

 -- Function File: geopdf (X, P)
     For each element of X, compute the probability density function
     (PDF) at X of the geometric distribution with parameter P.

     The geometric distribution models the number of failures (X-1) of a
     Bernoulli trial with probability P before the first success (X).

 -- Function File: geocdf (X, P)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the geometric distribution with parameter P.

     The geometric distribution models the number of failures (X-1) of a
     Bernoulli trial with probability P before the first success (X).

 -- Function File: geoinv (X, P)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the geometric distribution with parameter P.

     The geometric distribution models the number of failures (X-1) of a
     Bernoulli trial with probability P before the first success (X).

 -- Function File: hygepdf (X, T, M, N)
     Compute the probability density function (PDF) at X of the
     hypergeometric distribution with parameters T, M, and N.  This is
     the probability of obtaining X marked items when randomly drawing a
     sample of size N without replacement from a population of total
     size T containing M marked items.

     The parameters T, M, and N must be positive integers with M and N
     not greater than T.

 -- Function File: hygecdf (X, T, M, N)
     Compute the cumulative distribution function (CDF) at X of the
     hypergeometric distribution with parameters T, M, and N.  This is
     the probability of obtaining not more than X marked items when
     randomly drawing a sample of size N without replacement from a
     population of total size T containing M marked items.

     The parameters T, M, and N must be positive integers with M and N
     not greater than T.

 -- Function File: hygeinv (X, T, M, N)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the hypergeometric distribution with parameters T, M,
     and N.  This is the probability of obtaining X marked items when
     randomly drawing a sample of size N without replacement from a
     population of total size T containing M marked items.

     The parameters T, M, and N must be positive integers with M and N
     not greater than T.

 -- Function File: kolmogorov_smirnov_cdf (X, TOL)
     Return the cumulative distribution function (CDF) at X of the
     Kolmogorov-Smirnov distribution,

                   Inf
          Q(x) =   SUM    (-1)^k exp (-2 k^2 x^2)
                 k = -Inf

     for X > 0.

     The optional parameter TOL specifies the precision up to which the
     series should be evaluated; the default is TOL = 'eps'.

 -- Function File: laplace_pdf (X)
     For each element of X, compute the probability density function
     (PDF) at X of the Laplace distribution.

 -- Function File: laplace_cdf (X)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the Laplace distribution.

 -- Function File: laplace_inv (X)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the Laplace distribution.

 -- Function File: logistic_pdf (X)
     For each element of X, compute the PDF at X of the logistic
     distribution.

 -- Function File: logistic_cdf (X)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the logistic distribution.

 -- Function File: logistic_inv (X)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the logistic distribution.

 -- Function File: lognpdf (X)
 -- Function File: lognpdf (X, MU, SIGMA)
     For each element of X, compute the probability density function
     (PDF) at X of the lognormal distribution with parameters MU and
     SIGMA.  If a random variable follows this distribution, its
     logarithm is normally distributed with mean MU and standard
     deviation SIGMA.

     Default values are MU = 1, SIGMA = 1.

 -- Function File: logncdf (X)
 -- Function File: logncdf (X, MU, SIGMA)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the lognormal distribution with parameters MU and
     SIGMA.  If a random variable follows this distribution, its
     logarithm is normally distributed with mean MU and standard
     deviation SIGMA.

     Default values are MU = 1, SIGMA = 1.

 -- Function File: logninv (X)
 -- Function File: logninv (X, MU, SIGMA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the lognormal distribution with parameters MU and
     SIGMA.  If a random variable follows this distribution, its
     logarithm is normally distributed with mean 'log (MU)' and variance
     SIGMA.

     Default values are MU = 1, SIGMA = 1.

 -- Function File: nbinpdf (X, N, P)
     For each element of X, compute the probability density function
     (PDF) at X of the negative binomial distribution with parameters N
     and P.

     When N is integer this is the Pascal distribution.  When N is
     extended to real numbers this is the Polya distribution.

     The number of failures in a Bernoulli experiment with success
     probability P before the N-th success follows this distribution.

 -- Function File: nbincdf (X, N, P)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the negative binomial distribution with parameters N
     and P.

     When N is integer this is the Pascal distribution.  When N is
     extended to real numbers this is the Polya distribution.

     The number of failures in a Bernoulli experiment with success
     probability P before the N-th success follows this distribution.

 -- Function File: nbininv (X, N, P)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the negative binomial distribution with parameters N
     and P.

     When N is integer this is the Pascal distribution.  When N is
     extended to real numbers this is the Polya distribution.

     The number of failures in a Bernoulli experiment with success
     probability P before the N-th success follows this distribution.

 -- Function File: normpdf (X)
 -- Function File: normpdf (X, MU, SIGMA)
     For each element of X, compute the probability density function
     (PDF) at X of the normal distribution with mean MU and standard
     deviation SIGMA.

     Default values are MU = 0, SIGMA = 1.

 -- Function File: normcdf (X)
 -- Function File: normcdf (X, MU, SIGMA)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the normal distribution with mean MU and standard
     deviation SIGMA.

     Default values are MU = 0, SIGMA = 1.

 -- Function File: norminv (X)
 -- Function File: norminv (X, MU, SIGMA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the normal distribution with mean MU and standard
     deviation SIGMA.

     Default values are MU = 0, SIGMA = 1.

 -- Function File: poisspdf (X, LAMBDA)
     For each element of X, compute the probability density function
     (PDF) at X of the Poisson distribution with parameter LAMBDA.

 -- Function File: poisscdf (X, LAMBDA)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the Poisson distribution with parameter lambda.

 -- Function File: poissinv (X, LAMBDA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the Poisson distribution with parameter LAMBDA.

 -- Function File: stdnormal_pdf (X)
     For each element of X, compute the probability density function
     (PDF) at X of the standard normal distribution (mean = 0, standard
     deviation = 1).

 -- Function File: stdnormal_cdf (X)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the standard normal distribution (mean = 0, standard
     deviation = 1).

 -- Function File: stdnormal_inv (X)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the standard normal distribution (mean = 0, standard
     deviation = 1).

 -- Function File: tpdf (X, N)
     For each element of X, compute the probability density function
     (PDF) at X of the T (Student) distribution with N degrees of
     freedom.

 -- Function File: tcdf (X, N)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the t (Student) distribution with N degrees of
     freedom, i.e., PROB (t(N) <= X).

 -- Function File: tinv (X, N)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the t (Student) distribution with N degrees of
     freedom.  This function is analogous to looking in a table for the
     t-value of a single-tailed distribution.

 -- Function File: unidpdf (X, N)
     For each element of X, compute the probability density function
     (PDF) at X of a discrete uniform distribution which assumes the
     integer values 1-N with equal probability.

     Warning: The underlying implementation uses the double class and
     will only be accurate for N <= 'bitmax' (2^{53} - 1 on IEEE-754
     compatible systems).

 -- Function File: unidcdf (X, N)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of a discrete uniform distribution which assumes the
     integer values 1-N with equal probability.

 -- Function File: unidinv (X, N)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the discrete uniform distribution which assumes the
     integer values 1-N with equal probability.

 -- Function File: unifpdf (X)
 -- Function File: unifpdf (X, A, B)
     For each element of X, compute the probability density function
     (PDF) at X of the uniform distribution on the interval [A, B].

     Default values are A = 0, B = 1.

 -- Function File: unifcdf (X)
 -- Function File: unifcdf (X, A, B)
     For each element of X, compute the cumulative distribution function
     (CDF) at X of the uniform distribution on the interval [A, B].

     Default values are A = 0, B = 1.

 -- Function File: unifinv (X)
 -- Function File: unifinv (X, A, B)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the uniform distribution on the interval [A, B].

     Default values are A = 0, B = 1.

 -- Function File: wblpdf (X)
 -- Function File: wblpdf (X, SCALE)
 -- Function File: wblpdf (X, SCALE, SHAPE)
     Compute the probability density function (PDF) at X of the Weibull
     distribution with scale parameter SCALE and shape parameter SHAPE
     which is given by

          shape * scale^(-shape) * x^(shape-1) * exp (-(x/scale)^shape)

     for X >= 0.

     Default values are SCALE = 1, SHAPE = 1.

 -- Function File: wblcdf (X)
 -- Function File: wblcdf (X, SCALE)
 -- Function File: wblcdf (X, SCALE, SHAPE)
     Compute the cumulative distribution function (CDF) at X of the
     Weibull distribution with scale parameter SCALE and shape parameter
     SHAPE, which is

          1 - exp (-(x/scale)^shape)

     for X >= 0.

     Default values are SCALE = 1, SHAPE = 1.

 -- Function File: wblinv (X)
 -- Function File: wblinv (X, SCALE)
 -- Function File: wblinv (X, SCALE, SHAPE)
     Compute the quantile (the inverse of the CDF) at X of the Weibull
     distribution with scale parameter SCALE and shape parameter SHAPE.

     Default values are SCALE = 1, SHAPE = 1.


File: octave.info,  Node: Tests,  Next: Random Number Generation,  Prev: Distributions,  Up: Statistics

26.6 Tests
==========

Octave can perform many different statistical tests.  The following
table summarizes the available tests.

Hypothesis                    Test Functions
-------------------------------------------------------------------
Equal mean values             'anova', 'hotelling_test2',
                              't_test_2', 'welch_test',
                              'wilcoxon_test', 'z_test_2'
Equal medians                 'kruskal_wallis_test', 'sign_test'
Equal variances               'bartlett_test', 'manova',
                              'var_test'
Equal distributions           'chisquare_test_homogeneity',
                              'kolmogorov_smirnov_test_2',
                              'u_test'
Equal marginal frequencies    'mcnemar_test'
Equal success probabilities   'prop_test_2'
Independent observations      'chisquare_test_independence',
                              'run_test'
Uncorrelated observations     'cor_test'
Given mean value              'hotelling_test', 't_test',
                              'z_test'
Observations from given       'kolmogorov_smirnov_test'
distribution
Regression                    'f_test_regression',
                              't_test_regression'

   The tests return a p-value that describes the outcome of the test.
Assuming that the test hypothesis is true, the p-value is the
probability of obtaining a worse result than the observed one.  So large
p-values corresponds to a successful test.  Usually a test hypothesis is
accepted if the p-value exceeds 0.05.

 -- Function File: [PVAL, F, DF_B, DF_W] = anova (Y, G)
     Perform a one-way analysis of variance (ANOVA). The goal is to test
     whether the population means of data taken from K different groups
     are all equal.

     Data may be given in a single vector Y with groups specified by a
     corresponding vector of group labels G (e.g., numbers from 1 to 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 Y is a matrix and G is omitted, each column of 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 F follows an F
     distribution with DF_B and DF_W degrees of freedom.

     The p-value (1 minus the CDF of this distribution at F) is returned
     in PVAL.

     If no output argument is given, the standard one-way ANOVA table is
     printed.

 -- Function File: [PVAL, CHISQ, DF] = bartlett_test (X1, ...)
     Perform a Bartlett test for the homogeneity of variances in the
     data vectors X1, X2, ..., XK, where K > 1.

     Under the null of equal variances, the test statistic CHISQ
     approximately follows a chi-square distribution with DF degrees of
     freedom.

     The p-value (1 minus the CDF of this distribution at CHISQ) is
     returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, CHISQ, DF] = chisquare_test_homogeneity (X, Y,
          C)
     Given two samples X and Y, perform a chisquare test for homogeneity
     of the null hypothesis that X and Y come from the same
     distribution, based on the partition induced by the (strictly
     increasing) entries of C.

     For large samples, the test statistic CHISQ approximately follows a
     chisquare distribution with DF = 'length (C)' degrees of freedom.

     The p-value (1 minus the CDF of this distribution at CHISQ) is
     returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, CHISQ, DF] = chisquare_test_independence (X)
     Perform a chi-square test for independence based on the contingency
     table X.  Under the null hypothesis of independence, CHISQ
     approximately has a chi-square distribution with DF degrees of
     freedom.

     The p-value (1 minus the CDF of this distribution at chisq) of the
     test is returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: cor_test (X, Y, ALT, METHOD)
     Test whether two samples X and Y come from uncorrelated
     populations.

     The optional argument string ALT describes the alternative
     hypothesis, and can be "!=" or "<>" (non-zero), ">" (greater than
     0), or "<" (less than 0).  The default is the two-sided case.

     The optional argument string METHOD specifies which correlation
     coefficient to use for testing.  If METHOD is "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 METHOD is "kendall", then Kendall's rank
     correlation tau is used.  If METHOD is "spearman", then Spearman's
     rank correlation rho is used.  Only the first character is
     necessary.

     The output is a structure with the following elements:

     PVAL
          The p-value of the test.

     STAT
          The value of the test statistic.

     DIST
          The distribution of the test statistic.

     PARAMS
          The parameters of the null distribution of the test statistic.

     ALTERNATIVE
          The alternative hypothesis.

     METHOD
          The method used for testing.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, F, DF_NUM, DF_DEN] = f_test_regression (Y, X,
          RR, 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 F follows an F distribution with
     DF_NUM and DF_DEN degrees of freedom.

     The p-value (1 minus the CDF of this distribution at F) is returned
     in PVAL.

     If not given explicitly, R = 0.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, TSQ] = hotelling_test (X, M)
     For a sample X from a multivariate normal distribution with unknown
     mean and covariance matrix, test the null hypothesis that 'mean (X)
     == M'.

     Hotelling's T^2 is returned in TSQ.  Under the null, (n-p) T^2 /
     (p(n-1)) has an F distribution with p and n-p degrees of freedom,
     where n and p are the numbers of samples and variables,
     respectively.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, TSQ] = hotelling_test_2 (X, Y)
     For two samples X from multivariate normal distributions with the
     same number of variables (columns), unknown means and unknown equal
     covariance matrices, test the null hypothesis 'mean (X) == mean
     (Y)'.

     Hotelling's two-sample T^2 is returned in TSQ.  Under the null,

          (n_x+n_y-p-1) T^2 / (p(n_x+n_y-2))

     has an F distribution with p and n_x+n_y-p-1 degrees of freedom,
     where n_x and n_y are the sample sizes and p is the number of
     variables.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, KS] = kolmogorov_smirnov_test (X, DIST,
          PARAMS, ALT)
     Perform a Kolmogorov-Smirnov test of the null hypothesis that the
     sample 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 PARAMS contains a list of parameters of DIST.
     For example, to test whether a sample X comes from a uniform
     distribution on [2,4], use

          kolmogorov_smirnov_test (x, "unif", 2, 4)

     DIST can be any string for which a function DIST_CDF that
     calculates the CDF of distribution DIST exists.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is "!=" or "<>", the null is tested
     against the two-sided alternative F != G.  In this case, the test
     statistic KS follows a two-sided Kolmogorov-Smirnov distribution.
     If ALT is ">", the one-sided alternative F > G is considered.
     Similarly for "<", the one-sided alternative F > G is considered.
     In this case, the test statistic KS has a one-sided
     Kolmogorov-Smirnov distribution.  The default is the two-sided
     case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, KS, D] = kolmogorov_smirnov_test_2 (X, Y, ALT)
     Perform a 2-sample Kolmogorov-Smirnov test of the null hypothesis
     that the samples X and Y come from the same (continuous)
     distribution.  I.e., if F and G are the CDFs corresponding to the X
     and Y samples, respectively, then the null is that F == G.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is "!=" or "<>", the null is tested
     against the two-sided alternative F != G.  In this case, the test
     statistic KS follows a two-sided Kolmogorov-Smirnov distribution.
     If ALT is ">", the one-sided alternative F > G is considered.
     Similarly for "<", the one-sided alternative F < G is considered.
     In this case, the test statistic KS has a one-sided
     Kolmogorov-Smirnov distribution.  The default is the two-sided
     case.

     The p-value of the test is returned in PVAL.

     The third returned value, 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.

 -- Function File: [PVAL, K, DF] = kruskal_wallis_test (X1, ...)
     Perform a Kruskal-Wallis one-factor analysis of variance.

     Suppose a variable is observed for K > 1 different groups, and let
     X1, ..., 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 K is
     approximately chi-square with DF = K - 1 degrees of freedom.

     If the data contains ties (some value appears more than once) K is
     divided by

     1 - SUM_TIES / (N^3 - N)

     where SUM_TIES is the sum of T^2 - T over each group of ties where
     T is the number of ties in the group and N is the total number of
     values in the input data.  For more info on this adjustment see
     William H. Kruskal and W. Allen Wallis, 'Use of Ranks in
     One-Criterion Variance Analysis', Journal of the American
     Statistical Association, Vol.  47, No.  260 (Dec 1952).

     The p-value (1 minus the CDF of this distribution at K) is returned
     in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: manova (X, 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 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 X.  As usual, rows are observations and
     columns are variables.  The vector G specifies the corresponding
     group labels (e.g., numbers from 1 to K).

     The LR test statistic (Wilks' Lambda) and approximate p-values are
     computed and displayed.

 -- Function File: [PVAL, CHISQ, DF] = mcnemar_test (X)
     For a square contingency table 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, CHISQ is approximately distributed as chisquare
     with DF degrees of freedom.

     The p-value (1 minus the CDF of this distribution at CHISQ) is
     returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, Z] = prop_test_2 (X1, N1, X2, N2, ALT)
     If X1 and N1 are the counts of successes and trials in one sample,
     and X2 and N2 those in a second one, test the null hypothesis that
     the success probabilities P1 and P2 are the same.  Under the null,
     the test statistic Z approximately follows a standard normal
     distribution.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is "!=" or "<>", the null is tested
     against the two-sided alternative P1 != P2.  If ALT is ">", the
     one-sided alternative P1 > P2 is used.  Similarly for "<", the
     one-sided alternative P1 < P2 is used.  The default is the
     two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, CHISQ] = run_test (X)
     Perform a chi-square test with 6 degrees of freedom based on the
     upward runs in the columns of X.  Can be used to test whether X
     contains independent data.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, B, N] = sign_test (X, Y, ALT)
     For two matched-pair samples X and Y, perform a sign test of the
     null hypothesis PROB (X > Y) == PROB (X < Y) == 1/2.  Under the
     null, the test statistic B roughly follows a binomial distribution
     with parameters 'N = sum (X != Y)' and P = 1/2.

     With the optional argument 'alt', the alternative of interest can
     be selected.  If ALT is "!=" or "<>", the null hypothesis is tested
     against the two-sided alternative PROB (X < Y) != 1/2.  If ALT is
     ">", the one-sided alternative PROB (X > Y) > 1/2 ("x is
     stochastically greater than y") is considered.  Similarly for "<",
     the one-sided alternative PROB (X > 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 PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, T, DF] = t_test (X, M, ALT)
     For a sample X from a normal distribution with unknown mean and
     variance, perform a t-test of the null hypothesis 'mean (X) == M'.
     Under the null, the test statistic T follows a Student distribution
     with 'DF = length (X) - 1' degrees of freedom.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is "!=" or "<>", the null is tested
     against the two-sided alternative 'mean (X) != M'.  If ALT is ">",
     the one-sided alternative 'mean (X) > M' is considered.  Similarly
     for "<", the one-sided alternative 'mean (X) < M' is considered.
     The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, T, DF] = t_test_2 (X, Y, 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 T follows a Student distribution with DF degrees of
     freedom.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is "!=" or "<>", the null is tested
     against the two-sided alternative 'mean (X) != mean (Y)'.  If ALT
     is ">", the one-sided alternative 'mean (X) > mean (Y)' is used.
     Similarly for "<", the one-sided alternative 'mean (X) < mean (Y)'
     is used.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, T, DF] = t_test_regression (Y, X, RR, R, ALT)
     Perform a t test for the null hypothesis 'RR * B = R' in a
     classical normal regression model 'Y = X * B + E'.  Under the null,
     the test statistic T follows a T distribution with DF degrees of
     freedom.

     If R is omitted, a value of 0 is assumed.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is "!=" or "<>", the null is tested
     against the two-sided alternative 'RR * B != R'.  If ALT is ">",
     the one-sided alternative 'RR * B > R' is used.  Similarly for "<",
     the one-sided alternative 'RR * B < R' is used.  The default is the
     two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, Z] = u_test (X, Y, ALT)
     For two samples X and Y, perform a Mann-Whitney U-test of the null
     hypothesis PROB (X > Y) == 1/2 == PROB (X < Y).  Under the null,
     the test statistic Z approximately follows a standard normal
     distribution.  Note that this test is equivalent to the Wilcoxon
     rank-sum test.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is "!=" or "<>", the null is tested
     against the two-sided alternative PROB (X > Y) != 1/2.  If ALT is
     ">", the one-sided alternative PROB (X > Y) > 1/2 is considered.
     Similarly for "<", the one-sided alternative PROB (X > Y) < 1/2 is
     considered.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, F, DF_NUM, DF_DEN] = var_test (X, Y, ALT)
     For two samples X and 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
     F follows an F-distribution with DF_NUM and DF_DEN degrees of
     freedom.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is "!=" or "<>", the null is tested
     against the two-sided alternative 'var (X) != var (Y)'.  If ALT is
     ">", the one-sided alternative 'var (X) > var (Y)' is used.
     Similarly for "<", the one-sided alternative 'var (X) > var (Y)' is
     used.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, T, DF] = welch_test (X, Y, ALT)
     For two samples X and 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 T approximately follows a Student distribution
     with DF degrees of freedom.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is "!=" or "<>", the null is tested
     against the two-sided alternative 'mean (X) != M'.  If ALT is ">",
     the one-sided alternative mean(x) > M is considered.  Similarly for
     "<", the one-sided alternative mean(x) < M is considered.  The
     default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, Z] = wilcoxon_test (X, Y, ALT)
     For two matched-pair sample vectors X and Y, perform a Wilcoxon
     signed-rank test of the null hypothesis PROB (X > Y) == 1/2.  Under
     the null, the test statistic Z approximately follows a standard
     normal distribution when N > 25.

     *Caution:* This function assumes a normal distribution for Z and
     thus is invalid for N <= 25.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is "!=" or "<>", the null is tested
     against the two-sided alternative PROB (X > Y) != 1/2.  If alt is
     ">", the one-sided alternative PROB (X > Y) > 1/2 is considered.
     Similarly for "<", the one-sided alternative PROB (X > Y) < 1/2 is
     considered.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, Z] = z_test (X, M, V, ALT)
     Perform a Z-test of the null hypothesis 'mean (X) == M' for a
     sample X from a normal distribution with unknown mean and known
     variance V.  Under the null, the test statistic Z follows a
     standard normal distribution.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is "!=" or "<>", the null is tested
     against the two-sided alternative 'mean (X) != M'.  If ALT is ">",
     the one-sided alternative 'mean (X) > M' is considered.  Similarly
     for "<", the one-sided alternative 'mean (X) < M' is considered.
     The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed along with some information.

 -- Function File: [PVAL, Z] = z_test_2 (X, Y, V_X, V_Y, ALT)
     For two samples X and Y from normal distributions with unknown
     means and known variances V_X and V_Y, perform a Z-test of the
     hypothesis of equal means.  Under the null, the test statistic Z
     follows a standard normal distribution.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is "!=" or "<>", the null is tested
     against the two-sided alternative 'mean (X) != mean (Y)'.  If alt
     is ">", the one-sided alternative 'mean (X) > mean (Y)' is used.
     Similarly for "<", the one-sided alternative 'mean (X) < mean (Y)'
     is used.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed along with some information.


File: octave.info,  Node: Random Number Generation,  Prev: Tests,  Up: Statistics

26.7 Random Number Generation
=============================

Octave can generate random numbers from a large number of distributions.
The random number generators are based on the random number generators
described in *note Special Utility Matrices::.

   The following table summarizes the available random number generators
(in alphabetical order).

Distribution                  Function
-----------------------------------------------------
Beta Distribution             'betarnd'
Binomial Distribution         'binornd'
Cauchy Distribution           'cauchy_rnd'
Chi-Square Distribution       'chi2rnd'
Univariate Discrete           'discrete_rnd'
Distribution
Empirical Distribution        'empirical_rnd'
Exponential Distribution      'exprnd'
F Distribution                'frnd'
Gamma Distribution            'gamrnd'
Geometric Distribution        'geornd'
Hypergeometric Distribution   'hygernd'
Laplace Distribution          'laplace_rnd'
Logistic Distribution         'logistic_rnd'
Log-Normal Distribution       'lognrnd'
Pascal Distribution           'nbinrnd'
Univariate Normal             'normrnd'
Distribution
Poisson Distribution          'poissrnd'
Standard Normal               'stdnormal_rnd'
Distribution
t (Student) Distribution      'trnd'
Univariate Discrete           'unidrnd'
Distribution
Uniform Distribution          'unifrnd'
Weibull Distribution          'wblrnd'
Wiener Process                'wienrnd'

 -- Function File: betarnd (A, B)
 -- Function File: betarnd (A, B, R)
 -- Function File: betarnd (A, B, R, C, ...)
 -- Function File: betarnd (A, B, [SZ])
     Return a matrix of random samples from the Beta distribution with
     parameters A and B.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of A and B.

 -- Function File: binornd (N, P)
 -- Function File: binornd (N, P, R)
 -- Function File: binornd (N, P, R, C, ...)
 -- Function File: binornd (N, P, [SZ])
     Return a matrix of random samples from the binomial distribution
     with parameters N and P, where N is the number of trials and P is
     the probability of success.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of N and P.

 -- Function File: cauchy_rnd (LOCATION, SCALE)
 -- Function File: cauchy_rnd (LOCATION, SCALE, R)
 -- Function File: cauchy_rnd (LOCATION, SCALE, R, C, ...)
 -- Function File: cauchy_rnd (LOCATION, SCALE, [SZ])
     Return a matrix of random samples from the Cauchy distribution with
     parameters LOCATION and SCALE.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of LOCATION and SCALE.

 -- Function File: chi2rnd (N)
 -- Function File: chi2rnd (N, R)
 -- Function File: chi2rnd (N, R, C, ...)
 -- Function File: chi2rnd (N, [SZ])
     Return a matrix of random samples from the chi-square distribution
     with N degrees of freedom.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the size
     of N.

 -- Function File: discrete_rnd (V, P)
 -- Function File: discrete_rnd (V, P, R)
 -- Function File: discrete_rnd (V, P, R, C, ...)
 -- Function File: discrete_rnd (V, P, [SZ])
     Return a matrix of random samples from the univariate distribution
     which assumes the values in V with probabilities P.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of V and P.

 -- Function File: empirical_rnd (DATA)
 -- Function File: empirical_rnd (DATA, R)
 -- Function File: empirical_rnd (DATA, R, C, ...)
 -- Function File: empirical_rnd (DATA, [SZ])
     Return a matrix of random samples from the empirical distribution
     obtained from the univariate sample DATA.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is a random
     ordering of the sample DATA.

 -- Function File: exprnd (LAMBDA)
 -- Function File: exprnd (LAMBDA, R)
 -- Function File: exprnd (LAMBDA, R, C, ...)
 -- Function File: exprnd (LAMBDA, [SZ])
     Return a matrix of random samples from the exponential distribution
     with mean LAMBDA.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the size
     of LAMBDA.

 -- Function File: frnd (M, N)
 -- Function File: frnd (M, N, R)
 -- Function File: frnd (M, N, R, C, ...)
 -- Function File: frnd (M, N, [SZ])
     Return a matrix of random samples from the F distribution with M
     and N degrees of freedom.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of M and N.

 -- Function File: gamrnd (A, B)
 -- Function File: gamrnd (A, B, R)
 -- Function File: gamrnd (A, B, R, C, ...)
 -- Function File: gamrnd (A, B, [SZ])
     Return a matrix of random samples from the Gamma distribution with
     shape parameter A and scale B.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of A and B.

 -- Function File: geornd (P)
 -- Function File: geornd (P, R)
 -- Function File: geornd (P, R, C, ...)
 -- Function File: geornd (P, [SZ])
     Return a matrix of random samples from the geometric distribution
     with parameter P.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the size
     of P.

     The geometric distribution models the number of failures (X-1) of a
     Bernoulli trial with probability P before the first success (X).

 -- Function File: hygernd (T, M, N)
 -- Function File: hygernd (T, M, N, R)
 -- Function File: hygernd (T, M, N, R, C, ...)
 -- Function File: hygernd (T, M, N, [SZ])
     Return a matrix of random samples from the hypergeometric
     distribution with parameters T, M, and N.

     The parameters T, M, and N must be positive integers with M and N
     not greater than T.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of T, M, and N.

 -- Function File: laplace_rnd (R)
 -- Function File: laplace_rnd (R, C, ...)
 -- Function File: laplace_rnd ([SZ])
     Return a matrix of random samples from the Laplace distribution.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

 -- Function File: logistic_rnd (R)
 -- Function File: logistic_rnd (R, C, ...)
 -- Function File: logistic_rnd ([SZ])
     Return a matrix of random samples from the logistic distribution.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

 -- Function File: lognrnd (MU, SIGMA)
 -- Function File: lognrnd (MU, SIGMA, R)
 -- Function File: lognrnd (MU, SIGMA, R, C, ...)
 -- Function File: lognrnd (MU, SIGMA, [SZ])
     Return a matrix of random samples from the lognormal distribution
     with parameters MU and SIGMA.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of MU and SIGMA.

 -- Function File: nbinrnd (N, P)
 -- Function File: nbinrnd (N, P, R)
 -- Function File: nbinrnd (N, P, R, C, ...)
 -- Function File: nbinrnd (N, P, [SZ])
     Return a matrix of random samples from the negative binomial
     distribution with parameters N and P.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of N and P.

 -- Function File: normrnd (MU, SIGMA)
 -- Function File: normrnd (MU, SIGMA, R)
 -- Function File: normrnd (MU, SIGMA, R, C, ...)
 -- Function File: normrnd (MU, SIGMA, [SZ])
     Return a matrix of random samples from the normal distribution with
     parameters mean MU and standard deviation SIGMA.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of MU and SIGMA.

 -- Function File: poissrnd (LAMBDA)
 -- Function File: poissrnd (LAMBDA, R)
 -- Function File: poissrnd (LAMBDA, R, C, ...)
 -- Function File: poissrnd (LAMBDA, [SZ])
     Return a matrix of random samples from the Poisson distribution
     with parameter LAMBDA.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the size
     of LAMBDA.

 -- Function File: stdnormal_rnd (R)
 -- Function File: stdnormal_rnd (R, C, ...)
 -- Function File: stdnormal_rnd ([SZ])
     Return a matrix of random samples from the standard normal
     distribution (mean = 0, standard deviation = 1).

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

 -- Function File: trnd (N)
 -- Function File: trnd (N, R)
 -- Function File: trnd (N, R, C, ...)
 -- Function File: trnd (N, [SZ])
     Return a matrix of random samples from the t (Student) distribution
     with N degrees of freedom.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the size
     of N.

 -- Function File: unidrnd (N)
 -- Function File: unidrnd (N, R)
 -- Function File: unidrnd (N, R, C, ...)
 -- Function File: unidrnd (N, [SZ])
     Return a matrix of random samples from the discrete uniform
     distribution which assumes the integer values 1-N with equal
     probability.  N may be a scalar or a multi-dimensional array.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the size
     of N.

 -- Function File: unifrnd (A, B)
 -- Function File: unifrnd (A, B, R)
 -- Function File: unifrnd (A, B, R, C, ...)
 -- Function File: unifrnd (A, B, [SZ])
     Return a matrix of random samples from the uniform distribution on
     [A, B].

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of A and B.

 -- Function File: wblrnd (SCALE, SHAPE)
 -- Function File: wblrnd (SCALE, SHAPE, R)
 -- Function File: wblrnd (SCALE, SHAPE, R, C, ...)
 -- Function File: wblrnd (SCALE, SHAPE, [SZ])
     Return a matrix of random samples from the Weibull distribution
     with parameters SCALE and SHAPE.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of SCALE and SHAPE.

 -- Function File: wienrnd (T, D, N)
     Return a simulated realization of the D-dimensional Wiener Process
     on the interval [0, T].  If D is omitted, D = 1 is used.  The first
     column of the return matrix contains time, the remaining columns
     contain the Wiener process.

     The optional parameter N gives the number of summands used for
     simulating the process over an interval of length 1.  If N is
     omitted, N = 1000 is used.


File: octave.info,  Node: Sets,  Next: Polynomial Manipulations,  Prev: Statistics,  Up: Top

27 Sets
*******

Octave has a limited number of functions for managing sets of data,
where a set is defined as a collection of unique elements.  In Octave a
set is represented as a vector of numbers.

 -- Function File: unique (X)
 -- Function File: unique (X, "rows")
 -- Function File: unique (..., "first")
 -- Function File: unique (..., "last")
 -- Function File: [Y, I, J] = unique (...)
     Return the unique elements of X, sorted in ascending order.  If the
     input 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.  X may also be a cell array of
     strings.

     If the optional argument "rows" is supplied, return the unique rows
     of X, sorted in ascending order.

     If requested, return index vectors I and J such that 'x(i)==y' and
     'y(j)==x'.

     Additionally, if I is a requested output then one of "first" or
     "last" may be given as an input.  If "last" is specified, return
     the highest possible indices in I, otherwise, if "first" is
     specified, return the lowest.  The default is "last".

     See also: *note union: XREFunion, *note intersect: XREFintersect,
     *note setdiff: XREFsetdiff, *note setxor: XREFsetxor, *note
     ismember: XREFismember.

* Menu:

* Set Operations::


File: octave.info,  Node: Set Operations,  Up: Sets

27.1 Set Operations
===================

Octave supports the basic set operations.  That is, Octave can compute
the union, intersection, and difference of two sets.  Octave also
supports the _Exclusive Or_ set operation, and membership determination.
The functions for set operations all work in pretty much the same way.
As an example, assume that 'x' and 'y' contains two sets, then

     union (x, y)

computes the union of the two sets.

 -- Function File: TF = ismember (A, S)
 -- Function File: [TF, S_IDX] = ismember (A, S)
 -- Function File: [TF, S_IDX] = ismember (A, S, "rows")
     Return a logical matrix TF with the same shape as A which is true
     (1) if 'A(i,j)' is in S and false (0) if it is not.  If a second
     output argument is requested, the index into S of each of the
     matching elements is also returned.

          a = [3, 10, 1];
          s = [0:9];
          [tf, s_idx] = ismember (a, s)
               => tf = [1, 0, 1]
               => s_idx = [4, 0, 2]

     The inputs, A and S, may also be cell arrays.

          a = {"abc"};
          s = {"abc", "def"};
          [tf, s_idx] = ismember (a, s)
               => tf = [1, 0]
               => s_idx = [1, 0]

     With the optional third argument "rows", and matrices A and S with
     the same number of columns, compare rows in A with the rows in S.

          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")
               => tf = logical ([1; 0; 1])
               => s_idx = [2; 0; 5];

     See also: *note unique: XREFunique, *note union: XREFunion, *note
     intersect: XREFintersect, *note setxor: XREFsetxor, *note setdiff:
     XREFsetdiff.

 -- Function File: union (A, B)
 -- Function File: union (A, B, "rows")
 -- Function File: [C, IA, IB] = union (A, B)

     Return the set of elements that are in either of the sets A and B.
     A, B may be cell arrays of strings.  For example:

          union ([1, 2, 4], [2, 3, 5])
              => [1, 2, 3, 4, 5]

     If the optional third input argument is the string "rows" then each
     row of the matrices A and B will be considered as a single set
     element.  For example:

          union ([1, 2; 2, 3], [1, 2; 3, 4], "rows")
             =>  1   2
                 2   3
                 3   4

     The optional outputs IA and IB are index vectors such that 'a(ia)'
     and 'b(ib)' are disjoint sets whose union is C.

     See also: *note intersect: XREFintersect, *note setdiff:
     XREFsetdiff, *note unique: XREFunique.

 -- Function File: intersect (A, B)
 -- Function File: [C, IA, IB] = intersect (A, B)

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

     Return index vectors IA and IB such that 'a(ia)==c' and 'b(ib)==c'.

See also: *note unique: XREFunique, *note union: XREFunion, *note
setxor: XREFsetxor, *note setdiff: XREFsetdiff, *note ismember:
XREFismember.

 -- Function File: setdiff (A, B)
 -- Function File: setdiff (A, B, "rows")
 -- Function File: [C, I] = setdiff (A, B)
     Return the elements in A that are not in B, sorted in ascending
     order.  If A and B are both column vectors return a column vector,
     otherwise return a row vector.  A, B may be cell arrays of
     string(s).

     Given the optional third argument "rows", return the rows in A that
     are not in B, sorted in ascending order by rows.

     If requested, return I such that 'c = a(i)'.

     See also: *note unique: XREFunique, *note union: XREFunion, *note
     intersect: XREFintersect, *note setxor: XREFsetxor, *note ismember:
     XREFismember.

 -- Function File: setxor (A, B)
 -- Function File: setxor (A, B, "rows")
 -- Function File: [C, IA, IB] = setxor (A, B)

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

     With three output arguments, return index vectors IA and IB such
     that 'a(ia)' and 'b(ib)' are disjoint sets whose union is C.

     See also: *note unique: XREFunique, *note union: XREFunion, *note
     intersect: XREFintersect, *note setdiff: XREFsetdiff, *note
     ismember: XREFismember.

 -- Function File: powerset (A)
 -- Function File: powerset (A, "rows")
     Compute the powerset (all subsets) of the set A.

     The set A must be a numerical matrix or a cell array of strings.
     The output will always be a cell array of either vectors or
     strings.

     With the optional second argument "rows", each row of the set A is
     considered one element of the set.  As a result, A must then be a
     numerical 2-D matrix.

     See also: *note unique: XREFunique, *note union: XREFunion, *note
     setxor: XREFsetxor, *note setdiff: XREFsetdiff, *note ismember:
     XREFismember.


File: octave.info,  Node: Polynomial Manipulations,  Next: Interpolation,  Prev: Sets,  Up: Top

28 Polynomial Manipulations
***************************

In Octave, a polynomial is represented by its coefficients (arranged in
descending order).  For example, a vector C of length N+1 corresponds to
the following polynomial of order N

     p(x) = C(1) x^N + ... + C(N) x + C(N+1).

* Menu:

* Evaluating Polynomials::
* Finding Roots::
* Products of Polynomials::
* Derivatives / Integrals / Transforms::
* Polynomial Interpolation::
* Miscellaneous Functions::


File: octave.info,  Node: Evaluating Polynomials,  Next: Finding Roots,  Up: Polynomial Manipulations

28.1 Evaluating Polynomials
===========================

The value of a polynomial represented by the vector C can be evaluated
at the point X very easily, as the following example shows:

     N = length (c) - 1;
     val = dot (x.^(N:-1:0), c);

While the above example shows how easy it is to compute the value of a
polynomial, it isn't the most stable algorithm.  With larger polynomials
you should use more elegant algorithms, such as Horner's Method, which
is exactly what the Octave function 'polyval' does.

   In the case where X is a square matrix, the polynomial given by C is
still well-defined.  As when X is a scalar the obvious implementation is
easily expressed in Octave, but also in this case more elegant
algorithms perform better.  The 'polyvalm' function provides such an
algorithm.

 -- Function File: Y = polyval (P, X)
 -- Function File: Y = polyval (P, X, [], MU)
 -- Function File: [Y, DY] = polyval (P, X, S)
 -- Function File: [Y, DY] = polyval (P, X, S, MU)

     Evaluate the polynomial P at the specified values of X.  When MU is
     present, evaluate the polynomial for (X-MU(1))/MU(2).  If X is a
     vector or matrix, the polynomial is evaluated for each of the
     elements of X.

     In addition to evaluating the polynomial, the second output
     represents the prediction interval, Y +/- DY, which contains at
     least 50% of the future predictions.  To calculate the prediction
     interval, the structured variable S, originating from 'polyfit',
     must be supplied.

     See also: *note polyvalm: XREFpolyvalm, *note polyaffine:
     XREFpolyaffine, *note polyfit: XREFpolyfit, *note roots: XREFroots,
     *note poly: XREFpoly.

 -- Function File: polyvalm (C, X)
     Evaluate a polynomial in the matrix sense.

     'polyvalm (C, X)' will evaluate the polynomial in the matrix sense,
     i.e., matrix multiplication is used instead of element by element
     multiplication as used in 'polyval'.

     The argument X must be a square matrix.

     See also: *note polyval: XREFpolyval, *note roots: XREFroots, *note
     poly: XREFpoly.


File: octave.info,  Node: Finding Roots,  Next: Products of Polynomials,  Prev: Evaluating Polynomials,  Up: Polynomial Manipulations

28.2 Finding Roots
==================

Octave can find the roots of a given polynomial.  This is done by
computing the companion matrix of the polynomial (see the 'compan'
function for a definition), and then finding its eigenvalues.

 -- Function File: roots (V)

     For a vector V with N components, return the roots of the
     polynomial

          v(1) * z^(N-1) + ... + v(N-1) * z + v(N)

     As an example, the following code finds the roots of the quadratic
     polynomial

          p(x) = x^2 - 5.

          c = [1, 0, -5];
          roots (c)
          =>  2.2361
          => -2.2361

     Note that the true result is +/- sqrt(5) which is roughly +/-
     2.2361.

     See also: *note poly: XREFpoly, *note compan: XREFcompan, *note
     fzero: XREFfzero.

 -- Function File: Z = polyeig (C0, C1, ..., CL)
 -- Function File: [V, Z] = polyeig (C0, C1, ..., CL)

     Solve the polynomial eigenvalue problem of degree L.

     Given an N*N matrix polynomial 'C(s) = C0 + C1 s + ... + CL s^l'
     polyeig solves the eigenvalue problem '(C0 + C1 + ... + CL)v = 0'.
     Note that the eigenvalues Z are the zeros of the matrix polynomial.
     Z is an LXN vector and V is an (N x N)l matrix with columns that
     correspond to the eigenvectors.

     See also: *note eig: XREFeig, *note eigs: XREFeigs, *note compan:
     XREFcompan.

 -- Function File: compan (C)
     Compute the companion matrix corresponding to polynomial
     coefficient vector C.

     The companion matrix is

               _                                                        _
              |  -c(2)/c(1)   -c(3)/c(1)  ...  -c(N)/c(1)  -c(N+1)/c(1)  |
              |       1            0      ...       0             0      |
              |       0            1      ...       0             0      |
          A = |       .            .      .         .             .      |
              |       .            .       .        .             .      |
              |       .            .        .       .             .      |
              |_      0            0      ...       1             0     _|

     The eigenvalues of the companion matrix are equal to the roots of
     the polynomial.

     See also: *note roots: XREFroots, *note poly: XREFpoly, *note eig:
     XREFeig.

 -- Function File: [MULTP, IDXP] = mpoles (P)
 -- Function File: [MULTP, IDXP] = mpoles (P, TOL)
 -- Function File: [MULTP, IDXP] = mpoles (P, TOL, REORDER)
     Identify unique poles in P and their associated multiplicity.  The
     output is ordered from largest pole to smallest pole.

     If the relative difference of two poles is less than TOL then they
     are considered to be multiples.  The default value for TOL is
     0.001.

     If the optional parameter REORDER is zero, poles are not sorted.

     The output MULTP is a vector specifying the multiplicity of the
     poles.  'MULTP(n)' refers to the multiplicity of the Nth pole
     'P(IDXP(n))'.

     For example:

          p = [2 3 1 1 2];
          [m, n] = mpoles (p)
             => m = [1; 1; 2; 1; 2]
             => n = [2; 5; 1; 4; 3]
             => p(n) = [3, 2, 2, 1, 1]

     See also: *note residue: XREFresidue, *note poly: XREFpoly, *note
     roots: XREFroots, *note conv: XREFconv, *note deconv: XREFdeconv.


File: octave.info,  Node: Products of Polynomials,  Next: Derivatives / Integrals / Transforms,  Prev: Finding Roots,  Up: Polynomial Manipulations

28.3 Products of Polynomials
============================

 -- Function File: conv (A, B)
 -- Function File: conv (A, B, SHAPE)
     Convolve two vectors A and B.

     The output convolution is a vector with length equal to 'length (A)
     + length (B) - 1'.  When A and B are the coefficient vectors of two
     polynomials, the convolution represents the coefficient vector of
     the product polynomial.

     The optional SHAPE argument may be

     SHAPE = "full"
          Return the full convolution.  (default)

     SHAPE = "same"
          Return the central part of the convolution with the same size
          as A.

     See also: *note deconv: XREFdeconv, *note conv2: XREFconv2, *note
     convn: XREFconvn, *note fftconv: XREFfftconv.

 -- Built-in Function: C = convn (A, B)
 -- Built-in Function: C = convn (A, B, SHAPE)
     Return the n-D convolution of A and B.  The size of the result is
     determined by the optional SHAPE argument which takes the following
     values

     SHAPE = "full"
          Return the full convolution.  (default)

     SHAPE = "same"
          Return central part of the convolution with the same size as
          A.  The central part of the convolution begins at the indices
          'floor ([size(B)/2] + 1)'.

     SHAPE = "valid"
          Return only the parts which do not include zero-padded edges.
          The size of the result is 'max (size (A) - size (B) + 1, 0)'.

     See also: *note conv2: XREFconv2, *note conv: XREFconv.

 -- Function File: deconv (Y, A)
     Deconvolve two vectors.

     '[b, r] = deconv (y, a)' solves for B and R such that 'y = conv (a,
     b) + r'.

     If Y and A are polynomial coefficient vectors, B will contain the
     coefficients of the polynomial quotient and R will be a remainder
     polynomial of lowest order.

     See also: *note conv: XREFconv, *note residue: XREFresidue.

 -- Built-in Function: conv2 (A, B)
 -- Built-in Function: conv2 (V1, V2, M)
 -- Built-in Function: conv2 (..., SHAPE)
     Return the 2-D convolution of A and B.  The size of the result is
     determined by the optional SHAPE argument which takes the following
     values

     SHAPE = "full"
          Return the full convolution.  (default)

     SHAPE = "same"
          Return the central part of the convolution with the same size
          as A.  The central part of the convolution begins at the
          indices 'floor ([size(B)/2] + 1)'.

     SHAPE = "valid"
          Return only the parts which do not include zero-padded edges.
          The size of the result is 'max (size (A) - size (B) + 1, 0)'.

     When the third argument is a matrix, return the convolution of the
     matrix M by the vector V1 in the column direction and by the vector
     V2 in the row direction.

     See also: *note conv: XREFconv, *note convn: XREFconvn.

 -- Function File: Q = polygcd (B, A)
 -- Function File: Q = polygcd (B, A, TOL)

     Find the greatest common divisor of two polynomials.  This is
     equivalent to the polynomial found by multiplying together all the
     common roots.  Together with deconv, you can reduce a ratio of two
     polynomials.  The tolerance TOL defaults to 'sqrt (eps)'.

     *Caution:* This is a numerically unstable algorithm and should not
     be used on large polynomials.

     Example code:

          polygcd (poly (1:8), poly (3:12)) - poly (3:8)
          => [ 0, 0, 0, 0, 0, 0, 0 ]
          deconv (poly (1:8), polygcd (poly (1:8), poly (3:12))) - poly (1:2)
          => [ 0, 0, 0 ]

     See also: *note poly: XREFpoly, *note roots: XREFroots, *note conv:
     XREFconv, *note deconv: XREFdeconv, *note residue: XREFresidue.

 -- Function File: [R, P, K, E] = residue (B, A)
 -- Function File: [B, A] = residue (R, P, K)
 -- Function File: [B, A] = residue (R, P, K, E)
     The first calling form computes the partial fraction expansion for
     the quotient of the polynomials, B and A.

          B(s)    M       r(m)         N
          ---- = SUM -------------  + SUM k(i)*s^(N-i)
          A(s)   m=1 (s-p(m))^e(m)    i=1

     where M is the number of poles (the length of the R, P, and E), the
     K vector is a polynomial of order N-1 representing the direct
     contribution, and the E vector specifies the multiplicity of the
     m-th residue's pole.

     For example,

          b = [1, 1, 1];
          a = [1, -5, 8, -4];
          [r, p, k, e] = residue (b, a)
             => r = [-2; 7; 3]
             => p = [2; 2; 1]
             => k = [](0x0)
             => e = [1; 2; 1]

     which represents the following partial fraction expansion

                  s^2 + s + 1       -2        7        3
             ------------------- = ----- + ------- + -----
             s^3 - 5s^2 + 8s - 4   (s-2)   (s-2)^2   (s-1)

     The second calling form performs the inverse operation and computes
     the reconstituted quotient of polynomials, B(s)/A(s), from the
     partial fraction expansion; represented by the residues, poles, and
     a direct polynomial specified by R, P and K, and the pole
     multiplicity E.

     If the multiplicity, E, is not explicitly specified the
     multiplicity is determined by the function 'mpoles'.

     For example:

          r = [-2; 7; 3];
          p = [2; 2; 1];
          k = [1, 0];
          [b, a] = residue (r, p, k)
             => b = [1, -5, 9, -3, 1]
             => a = [1, -5, 8, -4]

          where mpoles is used to determine e = [1; 2; 1]

     Alternatively the multiplicity may be defined explicitly, for
     example,

          r = [7; 3; -2];
          p = [2; 1; 2];
          k = [1, 0];
          e = [2; 1; 1];
          [b, a] = residue (r, p, k, e)
             => b = [1, -5, 9, -3, 1]
             => a = [1, -5, 8, -4]

     which represents the following partial fraction expansion

           -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

     See also: *note mpoles: XREFmpoles, *note poly: XREFpoly, *note
     roots: XREFroots, *note conv: XREFconv, *note deconv: XREFdeconv.


File: octave.info,  Node: Derivatives / Integrals / Transforms,  Next: Polynomial Interpolation,  Prev: Products of Polynomials,  Up: Polynomial Manipulations

28.4 Derivatives / Integrals / Transforms
=========================================

Octave comes with functions for computing the derivative and the
integral of a polynomial.  The functions 'polyder' and 'polyint' both
return new polynomials describing the result.  As an example we'll
compute the definite integral of p(x) = x^2 + 1 from 0 to 3.

     c = [1, 0, 1];
     integral = polyint (c);
     area = polyval (integral, 3) - polyval (integral, 0)
     => 12

 -- Function File: polyder (P)
 -- Function File: [K] = polyder (A, B)
 -- Function File: [Q, D] = polyder (B, A)
     Return the coefficients of the derivative of the polynomial whose
     coefficients are given by the vector P.  If a pair of polynomials
     is given, return the derivative of the product A*B.  If two inputs
     and two outputs are given, return the derivative of the polynomial
     quotient B/A.  The quotient numerator is in Q and the denominator
     in D.

     See also: *note polyint: XREFpolyint, *note polyval: XREFpolyval,
     *note polyreduce: XREFpolyreduce.

 -- Function File: polyint (P)
 -- Function File: polyint (P, K)
     Return the coefficients of the integral of the polynomial whose
     coefficients are represented by the vector P.  The variable K is
     the constant of integration, which by default is set to zero.

     See also: *note polyder: XREFpolyder, *note polyval: XREFpolyval.

 -- Function File: polyaffine (F, MU)
     Return the coefficients of the polynomial vector F after an affine
     transformation.  If F is the vector representing the polynomial
     f(x), then 'G = polyaffine (F, MU)' is the vector representing:

          g(x) = f( (x - MU(1)) / MU(2) )

     See also: *note polyval: XREFpolyval, *note polyfit: XREFpolyfit.


File: octave.info,  Node: Polynomial Interpolation,  Next: Miscellaneous Functions,  Prev: Derivatives / Integrals / Transforms,  Up: Polynomial Manipulations

28.5 Polynomial Interpolation
=============================

Octave comes with good support for various kinds of interpolation, most
of which are described in *note Interpolation::.  One simple alternative
to the functions described in the aforementioned chapter, is to fit a
single polynomial, or a piecewise polynomial (spline) to some given data
points.  To avoid a highly fluctuating polynomial, one most often wants
to fit a low-order polynomial to data.  This usually means that it is
necessary to fit the polynomial in a least-squares sense, which just is
what the 'polyfit' function does.

 -- Function File: P = polyfit (X, Y, N)
 -- Function File: [P, S] = polyfit (X, Y, N)
 -- Function File: [P, S, MU] = polyfit (X, Y, N)
     Return the coefficients of a polynomial P(X) of degree N that
     minimizes the least-squares-error of the fit to the points '[X,
     Y]'.  If N is a logical vector, it is used as a mask to selectively
     force the corresponding polynomial coefficients to be used or
     ignored.

     The polynomial coefficients are returned in a row vector.

     The optional output S is a structure containing the following
     fields:

     'R'
          Triangular factor R from the QR decomposition.

     'X'
          The Vandermonde matrix used to compute the polynomial
          coefficients.

     'C'
          The unscaled covariance matrix, formally equal to the inverse
          of X'*X, but computed in a way minimizing roundoff error
          propagation.

     'df'
          The degrees of freedom.

     'normr'
          The norm of the residuals.

     'yf'
          The values of the polynomial for each value of X.

     The second output may be used by 'polyval' to calculate the
     statistical error limits of the predicted values.  In particular,
     the standard deviation of P coefficients is given by
     'sqrt (diag (s.C)/s.df)*s.normr'.

     When the third output, MU, is present the coefficients, P, are
     associated with a polynomial in XHAT = (X-MU(1))/MU(2).  Where
     MU(1) = mean (X), and MU(2) = std (X).  This linear transformation
     of X improves the numerical stability of the fit.

     See also: *note polyval: XREFpolyval, *note polyaffine:
     XREFpolyaffine, *note roots: XREFroots, *note vander: XREFvander,
     *note zscore: XREFzscore.

   In situations where a single polynomial isn't good enough, a solution
is to use several polynomials pieced together.  The function 'splinefit'
fits a peicewise polynomial (spline) to a set of data.

 -- Function File: PP = splinefit (X, Y, BREAKS)
 -- Function File: PP = splinefit (X, Y, P)
 -- Function File: PP = splinefit (..., "periodic", PERIODIC)
 -- Function File: PP = splinefit (..., "robust", ROBUST)
 -- Function File: PP = splinefit (..., "beta", BETA)
 -- Function File: PP = splinefit (..., "order", ORDER)
 -- Function File: PP = splinefit (..., "constraints", CONSTRAINTS)

     Fit a piecewise cubic spline with breaks (knots) BREAKS to the
     noisy data, X and Y.  X is a vector, and Y is a vector or N-D
     array.  If Y is an N-D array, then X(j) is matched to Y(:,...,:,j).

     The fitted spline is returned as a piecewise polynomial, PP, and
     may be evaluated using 'ppval'.

     P is a positive integer defining the number of intervals along X,
     and P+1 is the number of breaks.  The number of points in each
     interval differ by no more than 1.

     The optional property PERIODIC is a logical value which specifies
     whether a periodic boundary condition is applied to the spline.
     The length of the period is 'max (BREAKS) - min (BREAKS)'.  The
     default value is 'false'.

     The optional property ROBUST is a logical value which specifies if
     robust fitting is to be applied to reduce the influence of outlying
     data points.  Three iterations of weighted least squares are
     performed.  Weights are computed from previous residuals.  The
     sensitivity of outlier identification is controlled by the property
     BETA.  The value of BETA is stricted to the range, 0 < BETA < 1.
     The default value is BETA = 1/2.  Values close to 0 give all data
     equal weighting.  Increasing values of BETA reduce the influence of
     outlying data.  Values close to unity may cause instability or rank
     deficiency.

     The splines are constructed of polynomials with degree ORDER.  The
     default is a cubic, ORDER=3.  A spline with P pieces has P+ORDER
     degrees of freedom.  With periodic boundary conditions the degrees
     of freedom are reduced to P.

     The optional property, CONSTAINTS, is a structure specifying linear
     constraints on the fit.  The structure has three fields, "xc",
     "yc", and "cc".

     "xc"
          Vector of the x-locations of the constraints.

     "yc"
          Constraining values at the locations XC.  The default is an
          array of zeros.

     "cc"
          Coefficients (matrix).  The default is an array of ones.  The
          number of rows is limited to the order of the piecewise
          polynomials, ORDER.

     Constraints are linear combinations of derivatives of order 0 to
     ORDER-1 according to

          cc(1,j) * y(xc(j)) + cc(2,j) * y'(xc(j)) + ... = yc(:,...,:,j).

     See also: *note interp1: XREFinterp1, *note unmkpp: XREFunmkpp,
     *note ppval: XREFppval, *note spline: XREFspline, *note pchip:
     XREFpchip, *note ppder: XREFppder, *note ppint: XREFppint, *note
     ppjumps: XREFppjumps.

   The number of BREAKS (or knots) used to construct the piecewise
polynomial is a significant factor in suppressing the noise present in
the input data, X and Y.  This is demonstrated by the example below.

     x = 2 * pi * rand (1, 200);
     y = sin (x) + sin (2 * x) + 0.2 * randn (size (x));
     ## Uniform breaks
     breaks = linspace (0, 2 * pi, 41); % 41 breaks, 40 pieces
     pp1 = splinefit (x, y, breaks);
     ## Breaks interpolated from data
     pp2 = splinefit (x, y, 10);  % 11 breaks, 10 pieces
     ## Plot
     xx = linspace (0, 2 * pi, 400);
     y1 = ppval (pp1, xx);
     y2 = ppval (pp2, xx);
     plot (x, y, ".", xx, [y1; y2])
     axis tight
     ylim auto
     legend ({"data", "41 breaks, 40 pieces", "11 breaks, 10 pieces"})

   The piecewise polynomial fit, provided by 'splinefit', has continuous
derivatives up to the ORDER-1.  For example, a cubic fit has continuous
first and second derivatives.  This is demonstrated by the code

     ## Data (200 points)
     x = 2 * pi * rand (1, 200);
     y = sin (x) + sin (2 * x) + 0.1 * randn (size (x));
     ## Piecewise constant
     pp1 = splinefit (x, y, 8, "order", 0);
     ## Piecewise linear
     pp2 = splinefit (x, y, 8, "order", 1);
     ## Piecewise quadratic
     pp3 = splinefit (x, y, 8, "order", 2);
     ## Piecewise cubic
     pp4 = splinefit (x, y, 8, "order", 3);
     ## Piecewise quartic
     pp5 = splinefit (x, y, 8, "order", 4);
     ## Plot
     xx = linspace (0, 2 * pi, 400);
     y1 = ppval (pp1, xx);
     y2 = ppval (pp2, xx);
     y3 = ppval (pp3, xx);
     y4 = ppval (pp4, xx);
     y5 = ppval (pp5, xx);
     plot (x, y, ".", xx, [y1; y2; y3; y4; y5])
     axis tight
     ylim auto
     legend ({"data", "order 0", "order 1", "order 2", "order 3", "order 4"})

   When the underlying function to provide a fit to is periodic,
'splinefit' is able to apply the boundary conditions needed to manifest
a periodic fit.  This is demonstrated by the code below.

     ## Data (100 points)
     x = 2 * pi * [0, (rand (1, 98)), 1];
     y = sin (x) - cos (2 * x) + 0.2 * randn (size (x));
     ## No constraints
     pp1 = splinefit (x, y, 10, "order", 5);
     ## Periodic boundaries
     pp2 = splinefit (x, y, 10, "order", 5, "periodic", true);
     ## Plot
     xx = linspace (0, 2 * pi, 400);
     y1 = ppval (pp1, xx);
     y2 = ppval (pp2, xx);
     plot (x, y, ".", xx, [y1; y2])
     axis tight
     ylim auto
     legend ({"data", "no constraints", "periodic"})

   More complex constraints may be added as well.  For example, the code
below illustrates a periodic fit with values that have been clamped at
the endpoints, and a second periodic fit which is hinged at the
endpoints.

     ## Data (200 points)
     x = 2 * pi * rand (1, 200);
     y = sin (2 * x) + 0.1 * randn (size (x));
     ## Breaks
     breaks = linspace (0, 2 * pi, 10);
     ## Clamped endpoints, y = y' = 0
     xc = [0, 0, 2*pi, 2*pi];
     cc = [(eye (2)), (eye (2))];
     con = struct ("xc", xc, "cc", cc);
     pp1 = splinefit (x, y, breaks, "constraints", con);
     ## Hinged periodic endpoints, y = 0
     con = struct ("xc", 0);
     pp2 = splinefit (x, y, breaks, "constraints", con, "periodic", true);
     ## Plot
     xx = linspace (0, 2 * pi, 400);
     y1 = ppval (pp1, xx);
     y2 = ppval (pp2, xx);
     plot (x, y, ".", xx, [y1; y2])
     axis tight
     ylim auto
     legend ({"data", "clamped", "hinged periodic"})

   The 'splinefit' function also provides the convenience of a ROBUST
fitting, where the effect of outlying data is reduced.  In the example
below, three different fits are provided.  Two with differing levels of
outlier suppression and a third illustrating the non-robust solution.

     ## Data
     x = linspace (0, 2*pi, 200);
     y = sin (x) + sin (2 * x) + 0.05 * randn (size (x));
     ## Add outliers
     x = [x, linspace(0,2*pi,60)];
     y = [y, -ones(1,60)];
     ## Fit splines with hinged conditions
     con = struct ("xc", [0, 2*pi]);
     ## Robust fitting, beta = 0.25
     pp1 = splinefit (x, y, 8, "constraints", con, "beta", 0.25);
     ## Robust fitting, beta = 0.75
     pp2 = splinefit (x, y, 8, "constraints", con, "beta", 0.75);
     ## No robust fitting
     pp3 = splinefit (x, y, 8, "constraints", con);
     ## Plot
     xx = linspace (0, 2*pi, 400);
     y1 = ppval (pp1, xx);
     y2 = ppval (pp2, xx);
     y3 = ppval (pp3, xx);
     plot (x, y, ".", xx, [y1; y2; y3])
     legend ({"data with outliers","robust, beta = 0.25", ...
              "robust, beta = 0.75", "no robust fitting"})
     axis tight
     ylim auto

   The function, 'ppval', evaluates the piecewise polynomials, created
by 'mkpp' or other means, and 'unmkpp' returns detailed information
about the piecewise polynomial.

   The following example shows how to combine two linear functions and a
quadratic into one function.  Each of these functions is expressed on
adjoined intervals.

     x = [-2, -1, 1, 2];
     p = [ 0,  1, 0;
           1, -2, 1;
           0, -1, 1 ];
     pp = mkpp (x, p);
     xi = linspace (-2, 2, 50);
     yi = ppval (pp, xi);
     plot (xi, yi);

 -- Function File: PP = mkpp (BREAKS, COEFS)
 -- Function File: PP = mkpp (BREAKS, COEFS, D)

     Construct a piecewise polynomial (pp) structure from sample points
     BREAKS and coefficients COEFS.  BREAKS must be a vector of strictly
     increasing values.  The number of intervals is given by 'NI =
     length (BREAKS) - 1'.  When M is the polynomial order COEFS must be
     of size: NI x M + 1.

     The i-th row of COEFS, 'COEFS (I,:)', contains the coefficients for
     the polynomial over the I-th interval, ordered from highest (M) to
     lowest (0).

     COEFS may also be a multi-dimensional array, specifying a
     vector-valued or array-valued polynomial.  In that case the
     polynomial order is defined by the length of the last dimension of
     COEFS.  The size of first dimension(s) are given by the scalar or
     vector D.  If D is not given it is set to '1'.  In any case COEFS
     is reshaped to a 2-D matrix of size '[NI*prod(D M)] '

     See also: *note unmkpp: XREFunmkpp, *note ppval: XREFppval, *note
     spline: XREFspline, *note pchip: XREFpchip, *note ppder: XREFppder,
     *note ppint: XREFppint, *note ppjumps: XREFppjumps.

 -- Function File: [X, P, N, K, D] = unmkpp (PP)

     Extract the components of a piecewise polynomial structure PP.  The
     components are:

     X
          Sample points.

     P
          Polynomial coefficients for points in sample interval.  'P (I,
          :)' contains the coefficients for the polynomial over interval
          I ordered from highest to lowest.  If 'D > 1', 'P (R, I, :)'
          contains the coefficients for the r-th polynomial defined on
          interval I.

     N
          Number of polynomial pieces.

     K
          Order of the polynomial plus 1.

     D
          Number of polynomials defined for each interval.

     See also: *note mkpp: XREFmkpp, *note ppval: XREFppval, *note
     spline: XREFspline, *note pchip: XREFpchip.

 -- Function File: YI = ppval (PP, XI)
     Evaluate the piecewise polynomial structure PP at the points XI.
     If PP describes a scalar polynomial function, the result is an
     array of the same shape as XI.  Otherwise, the size of the result
     is '[pp.dim, length(XI)]' if XI is a vector, or '[pp.dim,
     size(XI)]' if it is a multi-dimensional array.

     See also: *note mkpp: XREFmkpp, *note unmkpp: XREFunmkpp, *note
     spline: XREFspline, *note pchip: XREFpchip.

 -- Function File: ppd = ppder (pp)
 -- Function File: ppd = ppder (pp, m)
     Compute the piecewise M-th derivative of a piecewise polynomial
     struct PP.  If M is omitted the first derivative is calculated.

     See also: *note mkpp: XREFmkpp, *note ppval: XREFppval, *note
     ppint: XREFppint.

 -- Function File: PPI = ppint (PP)
 -- Function File: PPI = ppint (PP, C)
     Compute the integral of the piecewise polynomial struct PP.  C, if
     given, is the constant of integration.

     See also: *note mkpp: XREFmkpp, *note ppval: XREFppval, *note
     ppder: XREFppder.

 -- Function File: JUMPS = ppjumps (PP)
     Evaluate the boundary jumps of a piecewise polynomial.  If there
     are n intervals, and the dimensionality of PP is d, the resulting
     array has dimensions '[d, n-1]'.

     See also: *note mkpp: XREFmkpp.


File: octave.info,  Node: Miscellaneous Functions,  Prev: Polynomial Interpolation,  Up: Polynomial Manipulations

28.6 Miscellaneous Functions
============================

 -- Function File: poly (A)
 -- Function File: poly (X)
     If A is a square N-by-N matrix, 'poly (A)' is the row vector of the
     coefficients of 'det (z * eye (N) - A)', the characteristic
     polynomial of A.  For example, the following code finds the
     eigenvalues of A which are the roots of 'poly (A)'.

          roots (poly (eye (3)))
              => 1.00001 + 0.00001i
                 1.00001 - 0.00001i
                 0.99999 + 0.00000i

     In fact, all three eigenvalues are exactly 1 which emphasizes that
     for numerical performance the 'eig' function should be used to
     compute eigenvalues.

     If X is a vector, 'poly (X)' is a vector of the coefficients of the
     polynomial whose roots are the elements of X.  That is, if C is a
     polynomial, then the elements of 'D = roots (poly (C))' are
     contained in C.  The vectors C and D are not identical, however,
     due to sorting and numerical errors.

     See also: *note roots: XREFroots, *note eig: XREFeig.

 -- Function File: polyout (C)
 -- Function File: polyout (C, X)
 -- Function File: STR = polyout (...)
     Write formatted polynomial

          c(x) = c(1) * x^n + ... + c(n) x + c(n+1)

     and return it as a string or write it to the screen (if NARGOUT is
     zero).  X defaults to the string "s".

     See also: *note polyreduce: XREFpolyreduce.

 -- Function File: polyreduce (C)
     Reduce a polynomial coefficient vector to a minimum number of terms
     by stripping off any leading zeros.

     See also: *note polyout: XREFpolyout.


File: octave.info,  Node: Interpolation,  Next: Geometry,  Prev: Polynomial Manipulations,  Up: Top

29 Interpolation
****************

* Menu:

* One-dimensional Interpolation::
* Multi-dimensional Interpolation::


File: octave.info,  Node: One-dimensional Interpolation,  Next: Multi-dimensional Interpolation,  Up: Interpolation

29.1 One-dimensional Interpolation
==================================

Octave supports several methods for one-dimensional interpolation, most
of which are described in this section.  *note Polynomial
Interpolation:: and *note Interpolation on Scattered Data:: describe
additional methods.

 -- Function File: YI = interp1 (X, Y, XI)
 -- Function File: YI = interp1 (Y, XI)
 -- Function File: YI = interp1 (..., METHOD)
 -- Function File: YI = interp1 (..., EXTRAP)
 -- Function File: PP = interp1 (..., "pp")

     One-dimensional interpolation.  Interpolates to determine the value
     of YI at the points, XI.  If not specified, X is taken to be the
     indices of Y.  If Y is a matrix or an N-dimensional array, the
     interpolation is performed on each column of Y.

     Method is one of:

     "nearest"
          Return the nearest neighbor.

     "linear"
          Linear interpolation from nearest neighbors

     "pchip"
          Piecewise cubic Hermite interpolating polynomial

     "cubic"
          Cubic interpolation (same as 'pchip')

     "spline"
          Cubic spline interpolation--smooth first and second
          derivatives throughout the curve

     Appending '*' to the start of the above method forces 'interp1' to
     assume that X is uniformly spaced, and only 'X(1)' and 'X(2)' are
     referenced.  This is usually faster, and is never slower.  The
     default method is "linear".

     If EXTRAP is the string "extrap", then extrapolate values beyond
     the endpoints.  If EXTRAP is a number, replace values beyond the
     endpoints with that number.  If EXTRAP is missing, assume NA.

     If the string argument "pp" is specified, then XI should not be
     supplied and 'interp1' returns the piecewise polynomial that can
     later be used with 'ppval' to evaluate the interpolation.  There is
     an equivalence, such that 'ppval (interp1 (X, Y, METHOD, "pp"), XI)
     == interp1 (X, Y, XI, METHOD, "extrap")'.

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

     An example of the use of 'interp1' is

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

     See also: *note interpft: XREFinterpft.

   There are some important differences between the various
interpolation methods.  The "spline" method enforces that both the first
and second derivatives of the interpolated values have a continuous
derivative, whereas the other methods do not.  This means that the
results of the "spline" method are generally smoother.  If the function
to be interpolated is in fact smooth, then "spline" will give excellent
results.  However, if the function to be evaluated is in some manner
discontinuous, then "pchip" interpolation might give better results.

   This can be demonstrated by the code

     t = -2:2;
     dt = 1;
     ti =-2:0.025:2;
     dti = 0.025;
     y = sign (t);
     ys = interp1 (t,y,ti,"spline");
     yp = interp1 (t,y,ti,"pchip");
     ddys = diff (diff (ys)./dti) ./ dti;
     ddyp = diff (diff (yp)./dti) ./ dti;
     figure (1);
     plot (ti,ys,"r-", ti,yp,"g-");
     legend ("spline", "pchip", 4);
     figure (2);
     plot (ti,ddys,"r+", ti,ddyp,"g*");
     legend ("spline", "pchip");

   Fourier interpolation, is a resampling technique where a signal is
converted to the frequency domain, padded with zeros and then
reconverted to the time domain.

 -- Function File: interpft (X, N)
 -- Function File: interpft (X, N, DIM)

     Fourier interpolation.  If X is a vector, then X is resampled with
     N points.  The data in X is assumed to be equispaced.  If X is a
     matrix or an N-dimensional array, the interpolation is performed on
     each column of X.  If DIM is specified, then interpolate along the
     dimension DIM.

     'interpft' assumes that the interpolated function is periodic, and
     so assumptions are made about the endpoints of the interpolation.

     See also: *note interp1: XREFinterp1.

   There are two significant limitations on Fourier interpolation.
Firstly, the function signal is assumed to be periodic, and so
non-periodic signals will be poorly represented at the edges.  Secondly,
both the signal and its interpolation are required to be sampled at
equispaced points.  An example of the use of 'interpft' is

     t = 0 : 0.3 : pi; dt = t(2)-t(1);
     n = length (t); k = 100;
     ti = t(1) + [0 : k-1]*dt*n/k;
     y = sin (4*t + 0.3) .* cos (3*t - 0.1);
     yp = sin (4*ti + 0.3) .* cos (3*ti - 0.1);
     plot (ti, yp, "g", ti, interp1 (t, y, ti, "spline"), "b", ...
           ti, interpft (y, k), "c", t, y, "r+");
     legend ("sin(4t+0.3)cos(3t-0.1)", "spline", "interpft", "data");

which demonstrates the poor behavior of Fourier interpolation for
non-periodic functions.

   In addition, the support functions 'spline' and 'lookup' that
underlie the 'interp1' function can be called directly.

 -- Function File: PP = spline (X, Y)
 -- Function File: YI = spline (X, Y, XI)
     Return the cubic spline interpolant of points X and Y.

     When called with two arguments, return the piecewise polynomial PP
     that may be used with 'ppval' to evaluate the polynomial at
     specific points.  When called with a third input argument, 'spline'
     evaluates the spline at the points XI.  The third calling form
     'spline (X, Y, XI)' is equivalent to 'ppval (spline (X, Y), XI)'.

     The variable X must be a vector of length N.  Y can be either a
     vector or array.  If Y is a vector it must have a length of either
     N or 'N + 2'.  If the length of Y is N, then the "not-a-knot" end
     condition is used.  If the length of Y is 'N + 2', then the first
     and last values of the vector Y are the values of the first
     derivative of the cubic spline at the endpoints.

     If Y is an array, then the size of Y must have the form '[S1, S2,
     ..., SK, N]' or '[S1, S2, ..., SK, N + 2]'.  The array is reshaped
     internally to a matrix where the leading dimension is given by 'S1
     * S2 * ... * SK' and each row of this matrix is then treated
     separately.  Note that this is exactly opposite to 'interp1' but is
     done for MATLAB compatibility.

     See also: *note pchip: XREFpchip, *note ppval: XREFppval, *note
     mkpp: XREFmkpp, *note unmkpp: XREFunmkpp.


File: octave.info,  Node: Multi-dimensional Interpolation,  Prev: One-dimensional Interpolation,  Up: Interpolation

29.2 Multi-dimensional Interpolation
====================================

There are three multi-dimensional interpolation functions in Octave,
with similar capabilities.  Methods using Delaunay tessellation are
described in *note Interpolation on Scattered Data::.

 -- Function File: ZI = interp2 (X, Y, Z, XI, YI)
 -- Function File: ZI = interp2 (Z, XI, YI)
 -- Function File: ZI = interp2 (Z, N)
 -- Function File: ZI = interp2 (..., METHOD)
 -- Function File: ZI = interp2 (..., METHOD, EXTRAPVAL)

     Two-dimensional interpolation.  X, Y and Z describe a surface
     function.  If X and Y are vectors their length must correspondent
     to the size of Z.  X and Y must be monotonic.  If they are matrices
     they must have the 'meshgrid' format.

     'interp2 (X, Y, Z, XI, YI, ...)'
          Returns a matrix corresponding to the points described by the
          matrices XI, 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.

     'interp2 (Z, XI, YI)'
          Assumes 'X = 1:rows (Z)' and 'Y = 1:columns (Z)'

     'interp2 (Z, N)'
          Interleaves the matrix Z n-times.  If N is omitted a value of
          'N = 1' is assumed.

     The variable METHOD defines the method to use for the
     interpolation.  It can take one of the following values

     "nearest"
          Return the nearest neighbor.

     "linear"
          Linear interpolation from nearest neighbors.

     "pchip"
          Piecewise cubic Hermite interpolating polynomial.

     "cubic"
          Cubic interpolation from four nearest neighbors.

     "spline"
          Cubic spline interpolation--smooth first and second
          derivatives throughout the curve.

     If a scalar value EXTRAPVAL is defined as the final value, then
     values outside the mesh as set to this value.  Note that in this
     case METHOD must be defined as well.  If EXTRAPVAL is not defined
     then NA is assumed.

     See also: *note interp1: XREFinterp1.

 -- Function File: VI = interp3 (X, Y, Z, V, XI, YI, ZI)
 -- Function File: VI = interp3 (V, XI, YI, ZI)
 -- Function File: VI = interp3 (V, M)
 -- Function File: VI = interp3 (V)
 -- Function File: VI = interp3 (..., METHOD)
 -- Function File: VI = interp3 (..., METHOD, EXTRAPVAL)

     Perform 3-dimensional interpolation.  Each element of the
     3-dimensional array V represents a value at a location given by the
     parameters X, Y, and Z.  The parameters X, X, and Z are either
     3-dimensional arrays of the same size as the array V in the
     "meshgrid" format or vectors.  The parameters XI, etc.  respect a
     similar format to X, etc., and they represent the points at which
     the array VI is interpolated.

     If X, Y, Z are omitted, they are assumed to be 'x = 1 : size (V,
     2)', 'y = 1 : size (V, 1)' and 'z = 1 : size (V, 3)'.  If M is
     specified, then the interpolation adds a point half way between
     each of the interpolation points.  This process is performed M
     times.  If only V is specified, then M is assumed to be '1'.

     Method is one of:

     "nearest"
          Return the nearest neighbor.

     "linear"
          Linear interpolation from nearest neighbors.

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

     "spline"
          Cubic spline interpolation--smooth first and second
          derivatives throughout the curve.

     The default method is "linear".

     If EXTRAP is the string "extrap", then extrapolate values beyond
     the endpoints.  If EXTRAP is a number, replace values beyond the
     endpoints with that number.  If EXTRAP is missing, assume NA.

     See also: *note interp1: XREFinterp1, *note interp2: XREFinterp2,
     *note spline: XREFspline, *note meshgrid: XREFmeshgrid.

 -- Function File: VI = interpn (X1, X2, ..., V, Y1, Y2, ...)
 -- Function File: VI = interpn (V, Y1, Y2, ...)
 -- Function File: VI = interpn (V, M)
 -- Function File: VI = interpn (V)
 -- Function File: VI = interpn (..., METHOD)
 -- Function File: VI = interpn (..., METHOD, EXTRAPVAL)

     Perform N-dimensional interpolation, where N is at least two.  Each
     element of the N-dimensional array V represents a value at a
     location given by the parameters X1, X2, ..., XN.  The parameters
     X1, X2, ..., XN are either N-dimensional arrays of the same size as
     the array V in the "ndgrid" format or vectors.  The parameters Y1,
     etc.  respect a similar format to X1, etc., and they represent the
     points at which the array VI is interpolated.

     If X1, ..., XN are omitted, they are assumed to be 'x1 = 1 : size
     (V, 1)', etc.  If M is specified, then the interpolation adds a
     point half way between each of the interpolation points.  This
     process is performed M times.  If only V is specified, then M is
     assumed to be '1'.

     Method is one of:

     "nearest"
          Return the nearest neighbor.

     "linear"
          Linear interpolation from nearest neighbors.

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

     "spline"
          Cubic spline interpolation--smooth first and second
          derivatives throughout the curve.

     The default method is "linear".

     If EXTRAPVAL is the scalar value, use it to replace the values
     beyond the endpoints with that number.  If EXTRAPVAL is missing,
     assume NA.

     See also: *note interp1: XREFinterp1, *note interp2: XREFinterp2,
     *note spline: XREFspline, *note ndgrid: XREFndgrid.

   A significant difference between 'interpn' and the other two
multi-dimensional interpolation functions is the fashion in which the
dimensions are treated.  For 'interp2' and 'interp3', the y-axis is
considered to be the columns of the matrix, whereas the x-axis
corresponds to the rows of the array.  As Octave indexes arrays in
column major order, the first dimension of any array is the columns, and
so 'interpn' effectively reverses the 'x' and 'y' dimensions.  Consider
the example,

     x = y = z = -1:1;
     f = @(x,y,z) x.^2 - y - z.^2;
     [xx, yy, zz] = meshgrid (x, y, z);
     v = f (xx,yy,zz);
     xi = yi = zi = -1:0.1:1;
     [xxi, yyi, zzi] = meshgrid (xi, yi, zi);
     vi = interp3 (x, y, z, v, xxi, yyi, zzi, "spline");
     [xxi, yyi, zzi] = ndgrid (xi, yi, zi);
     vi2 = interpn (x, y, z, v, xxi, yyi, zzi, "spline");
     mesh (zi, yi, squeeze (vi2(1,:,:)));

where 'vi' and 'vi2' are identical.  The reversal of the dimensions is
treated in the 'meshgrid' and 'ndgrid' functions respectively.

   In additional the support function 'bicubic' that underlies the cubic
interpolation of 'interp2' function can be called directly.

 -- Function File: ZI = bicubic (X, Y, Z, XI, YI, EXTRAPVAL)

     Return a matrix ZI corresponding to the bicubic interpolations at
     XI and YI of the data supplied as X, Y and Z.  Points outside the
     grid are set to EXTRAPVAL.

     See <http://wiki.woodpecker.org.cn/moin/Octave/Bicubic> for further
     information.

     See also: *note interp2: XREFinterp2.


File: octave.info,  Node: Geometry,  Next: Signal Processing,  Prev: Interpolation,  Up: Top

30 Geometry
***********

Much of the geometry code in Octave is based on the Qhull library(1).
Some of the documentation for Qhull, particularly for the options that
can be passed to 'delaunay', 'voronoi' and 'convhull', etc., is relevant
to Octave users.

* Menu:

* Delaunay Triangulation::
* Voronoi Diagrams::
* Convex Hull::
* Interpolation on Scattered Data::

   ---------- Footnotes ----------

   (1) Barber, C.B., Dobkin, D.P., and Huhdanpaa, H.T., 'The Quickhull
Algorithm for Convex Hulls', ACM Trans.  on Mathematical Software,
22(4):469-483, Dec 1996, <http://www.qhull.org>


File: octave.info,  Node: Delaunay Triangulation,  Next: Voronoi Diagrams,  Up: Geometry

30.1 Delaunay Triangulation
===========================

The Delaunay triangulation is constructed from a set of circum-circles.
These circum-circles are chosen so that there are at least three of the
points in the set to triangulation on the circumference of the
circum-circle.  None of the points in the set of points falls within any
of the circum-circles.

   In general there are only three points on the circumference of any
circum-circle.  However, in some cases, and in particular for the case
of a regular grid, 4 or more points can be on a single circum-circle.
In this case the Delaunay triangulation is not unique.

 -- Function File: delaunay (X, Y)
 -- Function File: delaunay (X)
 -- Function File: delaunay (..., OPTIONS)
 -- Function File: TRI = delaunay (...)
     Compute the Delaunay triangulation for a 2-D set of points.  The
     return value TRI is a set of triangles which satisfies the Delaunay
     circum-circle criterion, i.e., only a single data point from [X, Y]
     is within the circum-circle of the defining triangle.  The input X
     may also be a matrix with two columns where the first column
     contains x-data and the second y-data.

     The set of triangles TRI is a matrix of size [n, 3].  Each row
     defines a triangle and the three columns are the three vertices of
     the triangle.  The value of 'TRI(i,j)' is an index into X and Y for
     the location of the j-th vertex of the i-th triangle.

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

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

     If no output argument is specified the resulting Delaunay
     triangulation is plotted along with the original set of points.

          x = rand (1, 10);
          y = rand (1, 10);
          T = delaunay (x, y);
          VX = [ x(T(:,1)); x(T(:,2)); x(T(:,3)); x(T(:,1)) ];
          VY = [ y(T(:,1)); y(T(:,2)); y(T(:,3)); y(T(:,1)) ];
          axis ([0,1,0,1]);
          plot (VX, VY, "b", x, y, "r*");

     See also: *note delaunay3: XREFdelaunay3, *note delaunayn:
     XREFdelaunayn, *note convhull: XREFconvhull, *note voronoi:
     XREFvoronoi, *note triplot: XREFtriplot, *note trimesh:
     XREFtrimesh, *note trisurf: XREFtrisurf.

   The 3- and N-dimensional extension of the Delaunay triangulation are
given by 'delaunay3' and 'delaunayn' respectively.  'delaunay3' returns
a set of tetrahedra that satisfy the Delaunay circum-circle criteria.
Similarly, 'delaunayn' returns the N-dimensional simplex satisfying the
Delaunay circum-circle criteria.  The N-dimensional extension of a
triangulation is called a tessellation.

 -- Function File: TETR = delaunay3 (X, Y, Z)
 -- Function File: TETR = delaunay3 (X, Y, Z, OPTIONS)
     Compute the Delaunay triangulation for a 3-D set of points.  The
     return value TETR is a set of tetrahedrons which satisfies the
     Delaunay circum-circle criterion, i.e., only a single data point
     from [X, Y, Z] is within the circum-circle of the defining
     tetrahedron.

     The set of tetrahedrons TETR is a matrix of size [n, 4].  Each row
     defines a tetrahedron and the four columns are the four vertices of
     the tetrahedron.  The value of 'TETR(i,j)' is an index into X, Y, Z
     for the location of the j-th vertex of the i-th tetrahedron.

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

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

     See also: *note delaunay: XREFdelaunay, *note delaunayn:
     XREFdelaunayn, *note convhull: XREFconvhull, *note voronoi:
     XREFvoronoi, *note tetramesh: XREFtetramesh.

 -- Function File: T = delaunayn (PTS)
 -- Function File: T = delaunayn (PTS, OPTIONS)
     Compute the Delaunay triangulation for an N-dimensional set of
     points.  The Delaunay triangulation is a tessellation of the convex
     hull of a set of points such that no N-sphere defined by the
     N-triangles contains any other points from the set.

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

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

        * 2-D and 3-D: OPTIONS = '{"Qt", "Qbb", "Qc", "Qz"}'

        * 4-D and higher: OPTIONS = '{"Qt", "Qbb", "Qc", "Qx"}'

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

     See also: *note delaunay: XREFdelaunay, *note delaunay3:
     XREFdelaunay3, *note convhulln: XREFconvhulln, *note voronoin:
     XREFvoronoin, *note trimesh: XREFtrimesh, *note tetramesh:
     XREFtetramesh.

   An example of a Delaunay triangulation of a set of points is

     rand ("state", 2);
     x = rand (10, 1);
     y = rand (10, 1);
     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*");

* Menu:

* Plotting the Triangulation::
* Identifying Points in Triangulation::


File: octave.info,  Node: Plotting the Triangulation,  Next: Identifying Points in Triangulation,  Up: Delaunay Triangulation

30.1.1 Plotting the Triangulation
---------------------------------

Octave has the functions 'triplot', 'trimesh', and 'trisurf' to plot the
Delaunay triangulation of a 2-dimensional set of points.  'tetramesh'
will plot the triangulation of a 3-dimensional set of points.

 -- Function File: triplot (TRI, X, Y)
 -- Function File: triplot (TRI, X, Y, LINESPEC)
 -- Function File: H = triplot (...)
     Plot a 2-D triangular mesh.

     TRI is typically the output of a Delaunay triangulation over the
     grid of X, Y.  Every row of TRI represents one triangle and
     contains three indices into [X, Y] which are the vertices of the
     triangles in the x-y plane.

     The linestyle to use for the plot can be defined with the argument
     LINESPEC of the same format as the 'plot' command.

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

     See also: *note plot: XREFplot, *note trimesh: XREFtrimesh, *note
     trisurf: XREFtrisurf, *note delaunay: XREFdelaunay.

 -- Function File: trimesh (TRI, X, Y, Z, C)
 -- Function File: trimesh (TRI, X, Y, Z)
 -- Function File: trimesh (TRI, X, Y)
 -- Function File: trimesh (..., PROP, VAL, ...)
 -- Function File: H = trimesh (...)
     Plot a 3-D triangular wireframe mesh.

     In contrast to 'mesh', which plots a mesh using rectangles,
     'trimesh' plots the mesh using triangles.

     TRI is typically the output of a Delaunay triangulation over the
     grid of X, Y.  Every row of TRI represents one triangle and
     contains three indices into [X, Y] which are the vertices of the
     triangles in the x-y plane.  Z determines the height above the
     plane of each vertex.  If no Z input is given then the triangles
     are plotted as a 2-D figure.

     The color of the trimesh is computed by linearly scaling the Z
     values to fit the range of the current colormap.  Use 'caxis'
     and/or change the colormap to control the appearance.

     Optionally, the color of the mesh can be specified independently of
     Z by supplying a color matrix, C.  If Z has N elements, then C
     should be an Nx1 vector for colormap data or an Nx3 matrix for RGB
     data.

     Any property/value pairs are passed directly to the underlying
     patch object.

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

     See also: *note mesh: XREFmesh, *note tetramesh: XREFtetramesh,
     *note triplot: XREFtriplot, *note trisurf: XREFtrisurf, *note
     delaunay: XREFdelaunay, *note patch: XREFpatch, *note hidden:
     XREFhidden.

 -- Function File: trisurf (TRI, X, Y, Z, C)
 -- Function File: trisurf (TRI, X, Y, Z)
 -- Function File: trisurf (..., PROP, VAL, ...)
 -- Function File: H = trisurf (...)
     Plot a 3-D triangular surface.

     In contrast to 'surf', which plots a surface mesh using rectangles,
     'trisurf' plots the mesh using triangles.

     TRI is typically the output of a Delaunay triangulation over the
     grid of X, Y.  Every row of TRI represents one triangle and
     contains three indices into [X, Y] which are the vertices of the
     triangles in the x-y plane.  Z determines the height above the
     plane of each vertex.

     The color of the trimesh is computed by linearly scaling the Z
     values to fit the range of the current colormap.  Use 'caxis'
     and/or change the colormap to control the appearance.

     Optionally, the color of the mesh can be specified independently of
     Z by supplying a color matrix, C.  If Z has N elements, then C
     should be an Nx1 vector for colormap data or an Nx3 matrix for RGB
     data.

     Any property/value pairs are passed directly to the underlying
     patch object.

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

     See also: *note surf: XREFsurf, *note triplot: XREFtriplot, *note
     trimesh: XREFtrimesh, *note delaunay: XREFdelaunay, *note patch:
     XREFpatch, *note shading: XREFshading.

 -- Function File: tetramesh (T, X)
 -- Function File: tetramesh (T, X, C)
 -- Function File: tetramesh (..., PROPERTY, VAL, ...)
 -- Function File: H = tetramesh (...)
     Display the tetrahedrons defined in the m-by-4 matrix T as 3-D
     patches.

     T is typically the output of a Delaunay triangulation of a 3-D set
     of points.  Every row of T contains four indices into the n-by-3
     matrix X of the vertices of a tetrahedron.  Every row in X
     represents one point in 3-D space.

     The vector C specifies the color of each tetrahedron as an index
     into the current colormap.  The default value is 1:m where m is the
     number of tetrahedrons; the indices are scaled to map to the full
     range of the colormap.  If there are more tetrahedrons than colors
     in the colormap then the values in C are cyclically repeated.

     Calling 'tetramesh (..., "property", "value", ...)' passes all
     property/value pairs directly to the patch function as additional
     arguments.

     The optional return value H is a vector of patch handles where each
     handle represents one tetrahedron in the order given by T.  A
     typical use case for H is to turn the respective patch "visible"
     property "on" or "off".

     Type 'demo tetramesh' to see examples on using 'tetramesh'.

     See also: *note trimesh: XREFtrimesh, *note delaunay3:
     XREFdelaunay3, *note delaunayn: XREFdelaunayn, *note patch:
     XREFpatch.

   The difference between 'triplot', and 'trimesh' or 'triplot', is that
the former only plots the 2-dimensional triangulation itself, whereas
the second two plot the value of a function 'f (X, Y)'.  An example of
the use of the 'triplot' function is

     rand ("state", 2)
     x = rand (20, 1);
     y = rand (20, 1);
     tri = delaunay (x, y);
     triplot (tri, x, y);

which plots the Delaunay triangulation of a set of random points in
2-dimensions.


File: octave.info,  Node: Identifying Points in Triangulation,  Prev: Plotting the Triangulation,  Up: Delaunay Triangulation

30.1.2 Identifying Points in Triangulation
------------------------------------------

It is often necessary to identify whether a particular point in the
N-dimensional space is within the Delaunay tessellation of a set of
points in this N-dimensional space, and if so which N-simplex contains
the point and which point in the tessellation is closest to the desired
point.  The functions 'tsearch' and 'dsearch' perform this function in a
triangulation, and 'tsearchn' and 'dsearchn' in an N-dimensional
tessellation.

   To identify whether a particular point represented by a vector P
falls within one of the simplices of an N-simplex, we can write the
Cartesian coordinates of the point in a parametric form with respect to
the N-simplex.  This parametric form is called the Barycentric
Coordinates of the point.  If the points defining the N-simplex are
given by 'N + 1' vectors T(I,:), then the Barycentric coordinates
defining the point P are given by

     P = sum (BETA(1:N+1) * T(1:N+1),:)

where there are 'N + 1' values 'BETA(I)' that together as a vector
represent the Barycentric coordinates of the point P.  To ensure a
unique solution for the values of 'BETA(I)' an additional criteria of

     sum (BETA(1:N+1)) == 1

is imposed, and we can therefore write the above as

     P - T(end, :) = BETA(1:end-1) * (T(1:end-1, :)
           - ones (N, 1) * T(end, :)

Solving for BETA we can then write

     BETA(1:end-1) = (P - T(end, :)) / (T(1:end-1, :)
           - ones (N, 1) * T(end, :))
     BETA(end) = sum (BETA(1:end-1))

which gives the formula for the conversion of the Cartesian coordinates
of the point P to the Barycentric coordinates BETA.  An important
property of the Barycentric coordinates is that for all points in the
N-simplex

     0 <= BETA(I) <= 1

Therefore, the test in 'tsearch' and 'tsearchn' essentially only needs
to express each point in terms of the Barycentric coordinates of each of
the simplices of the N-simplex and test the values of BETA.  This is
exactly the implementation used in 'tsearchn'.  'tsearch' is optimized
for 2-dimensions and the Barycentric coordinates are not explicitly
formed.

 -- Loadable Function: IDX = tsearch (X, Y, T, XI, YI)
     Search for the enclosing Delaunay convex hull.  For 'T = delaunay
     (X, Y)', finds the index in T containing the points '(XI, YI)'.
     For points outside the convex hull, IDX is NaN.

     See also: *note delaunay: XREFdelaunay, *note delaunayn:
     XREFdelaunayn.

 -- Function File: [IDX, P] = tsearchn (X, T, XI)
     Search for the enclosing Delaunay convex hull.  For 'T = delaunayn
     (X)', finds the index in T containing the points XI.  For points
     outside the convex hull, IDX is NaN. If requested 'tsearchn' also
     returns the Barycentric coordinates P of the enclosing triangles.

     See also: *note delaunay: XREFdelaunay, *note delaunayn:
     XREFdelaunayn.

   An example of the use of 'tsearch' can be seen with the simple
triangulation

     X = [-1; -1; 1; 1];
     Y = [-1; 1; -1; 1];
     TRI = [1, 2, 3; 2, 3, 1];

consisting of two triangles defined by TRI.  We can then identify which
triangle a point falls in like

     tsearch (X, Y, TRI, -0.5, -0.5)
     => 1
     tsearch (X, Y, TRI, 0.5, 0.5)
     => 2

and we can confirm that a point doesn't lie within one of the triangles
like

     tsearch (X, Y, TRI, 2, 2)
     => NaN

   The 'dsearch' and 'dsearchn' find the closest point in a tessellation
to the desired point.  The desired point does not necessarily have to be
in the tessellation, and even if it the returned point of the
tessellation does not have to be one of the vertexes of the N-simplex
within which the desired point is found.

 -- Function File: IDX = dsearch (X, Y, TRI, XI, YI)
 -- Function File: IDX = dsearch (X, Y, TRI, XI, YI, S)
     Return the index IDX or the closest point in 'X, Y' to the elements
     '[XI(:), YI(:)]'.  The variable S is accepted for compatibility but
     is ignored.

     See also: *note dsearchn: XREFdsearchn, *note tsearch: XREFtsearch.

 -- Function File: IDX = dsearchn (X, TRI, XI)
 -- Function File: IDX = dsearchn (X, TRI, XI, OUTVAL)
 -- Function File: IDX = dsearchn (X, XI)
 -- Function File: [IDX, D] = dsearchn (...)
     Return the index IDX or the closest point in X to the elements XI.
     If OUTVAL is supplied, then the values of XI that are not contained
     within one of the simplices TRI are set to OUTVAL.  Generally, TRI
     is returned from 'delaunayn (X)'.

     See also: *note dsearch: XREFdsearch, *note tsearch: XREFtsearch.

   An example of the use of 'dsearch', using the above values of X, Y
and TRI is

     dsearch (X, Y, TRI, -2, -2)
     => 1

   If you wish the points that are outside the tessellation to be
flagged, then 'dsearchn' can be used as

     dsearchn ([X, Y], TRI, [-2, -2], NaN)
     => NaN
     dsearchn ([X, Y], TRI, [-0.5, -0.5], NaN)
     => 1

where the point outside the tessellation are then flagged with 'NaN'.


File: octave.info,  Node: Voronoi Diagrams,  Next: Convex Hull,  Prev: Delaunay Triangulation,  Up: Geometry

30.2 Voronoi Diagrams
=====================

A Voronoi diagram or Voronoi tessellation of a set of points S in an
N-dimensional space, is the tessellation of the N-dimensional space such
that all points in 'V(P)', a partitions of the tessellation where P is a
member of S, are closer to P than any other point in S.  The Voronoi
diagram is related to the Delaunay triangulation of a set of points, in
that the vertexes of the Voronoi tessellation are the centers of the
circum-circles of the simplices of the Delaunay tessellation.

 -- Function File: voronoi (X, Y)
 -- Function File: voronoi (X, Y, OPTIONS)
 -- Function File: voronoi (..., "linespec")
 -- Function File: voronoi (HAX, ...)
 -- Function File: H = voronoi (...)
 -- Function File: [VX, VY] = voronoi (...)
     Plot the Voronoi diagram of points '(X, Y)'.  The Voronoi facets
     with points at infinity are not drawn.

     If "linespec" is given it is used to set the color and line style
     of the plot.  If an axis graphics handle HAX is supplied then the
     Voronoi diagram is drawn on the specified axis rather than in a new
     figure.

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

     If a single output argument is requested then the Voronoi diagram
     will be plotted and a graphics handle H to the plot is returned.
     [VX, VY] = voronoi (...) returns the Voronoi vertices instead of
     plotting the diagram.

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

     See also: *note voronoin: XREFvoronoin, *note delaunay:
     XREFdelaunay, *note convhull: XREFconvhull.

 -- Function File: [C, F] = voronoin (PTS)
 -- Function File: [C, F] = voronoin (PTS, OPTIONS)
     Compute N-dimensional Voronoi facets.  The input matrix PTS of size
     [n, dim] contains n points in a space of dimension dim.  C contains
     the points of the Voronoi facets.  The list F contains, for each
     facet, the indices of the Voronoi points.

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

     The default options depend on the dimension of the input:

        * 2-D and 3-D: OPTIONS = '{"Qbb"}'

        * 4-D and higher: OPTIONS = '{"Qbb", "Qx"}'

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

     See also: *note voronoi: XREFvoronoi, *note convhulln:
     XREFconvhulln, *note delaunayn: XREFdelaunayn.

   An example of the use of 'voronoi' is

     rand ("state",9);
     x = rand (10,1);
     y = rand (10,1);
     tri = delaunay (x, y);
     [vx, vy] = voronoi (x, y, tri);
     triplot (tri, x, y, "b");
     hold on;
     plot (vx, vy, "r");

   Additional information about the size of the facets of a Voronoi
diagram, and which points of a set of points is in a polygon can be had
with the 'polyarea' and 'inpolygon' functions respectively.

 -- Function File: polyarea (X, Y)
 -- Function File: polyarea (X, Y, DIM)

     Determine area of a polygon by triangle method.  The variables X
     and 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 X and Y are treated separately and an area
     returned for each.

     If the optional DIM argument is given, then 'polyarea' works along
     this dimension of the arrays X and Y.

   An example of the use of 'polyarea' might be

     rand ("state", 2);
     x = rand (10, 1);
     y = rand (10, 1);
     [c, f] = voronoin ([x, y]);
     af = zeros (size (f));
     for i = 1 : length (f)
       af(i) = polyarea (c (f {i, :}, 1), c (f {i, :}, 2));
     endfor

   Facets of the Voronoi diagram with a vertex at infinity have infinity
area.  A simplified version of 'polyarea' for rectangles is available
with 'rectint'

 -- Function File: AREA = rectint (A, B)

     Compute the area of intersection of rectangles in A and rectangles
     in B.  Rectangles are defined as [x y width height] where x and y
     are the minimum values of the two orthogonal dimensions.

     If A or B are matrices, then the output, 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.

     See also: *note polyarea: XREFpolyarea.

 -- Function File: [IN, ON] = inpolygon (X, Y, XV, YV)

     For a polygon defined by vertex points '(XV, YV)', determine if the
     points '(X, Y)' are inside or outside the polygon.  The variables
     X, Y, must have the same dimension.  The optional output ON gives
     the points that are on the polygon.

   An example of the use of 'inpolygon' might be

     randn ("state", 2);
     x = randn (100, 1);
     y = randn (100, 1);
     vx = cos (pi * [-1 : 0.1: 1]);
     vy = sin (pi * [-1 : 0.1 : 1]);
     in = inpolygon (x, y, vx, vy);
     plot (vx, vy, x(in), y(in), "r+", x(!in), y(!in), "bo");
     axis ([-2, 2, -2, 2]);


File: octave.info,  Node: Convex Hull,  Next: Interpolation on Scattered Data,  Prev: Voronoi Diagrams,  Up: Geometry

30.3 Convex Hull
================

The convex hull of a set of points is the minimum convex envelope
containing all of the points.  Octave has the functions 'convhull' and
'convhulln' to calculate the convex hull of 2-dimensional and
N-dimensional sets of points.

 -- Function File: H = convhull (X, Y)
 -- Function File: H = convhull (X, Y, OPTIONS)
     Compute the convex hull of the set of points defined by the arrays
     X and Y.  The hull H is an index vector into the set of points and
     specifies which points form the enclosing hull.

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

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

     See also: *note convhulln: XREFconvhulln, *note delaunay:
     XREFdelaunay, *note voronoi: XREFvoronoi.

 -- Loadable Function: H = convhulln (PTS)
 -- Loadable Function: H = convhulln (PTS, OPTIONS)
 -- Loadable Function: [H, V] = convhulln (...)
     Compute the convex hull of the set of points PTS which is a matrix
     of size [n, dim] containing n points in a space of dimension dim.
     The hull H is an index vector into the set of points and specifies
     which points form the enclosing hull.

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

        * 2D, 3D, 4D: OPTIONS = '{"Qt"}'

        * 5D and higher: OPTIONS = '{"Qt", "Qx"}'

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

     If the second output V is requested the volume of the enclosing
     convex hull is calculated.

     See also: *note convhull: XREFconvhull, *note delaunayn:
     XREFdelaunayn, *note voronoin: XREFvoronoin.

   An example of the use of 'convhull' is

     x = -3:0.05:3;
     y = abs (sin (x));
     k = convhull (x, y);
     plot (x(k), y(k), "r-", x, y, "b+");
     axis ([-3.05, 3.05, -0.05, 1.05]);


File: octave.info,  Node: Interpolation on Scattered Data,  Prev: Convex Hull,  Up: Geometry

30.4 Interpolation on Scattered Data
====================================

An important use of the Delaunay tessellation is that it can be used to
interpolate from scattered data to an arbitrary set of points.  To do
this the N-simplex of the known set of points is calculated with
'delaunay', 'delaunay3' or 'delaunayn'.  Then the simplices in to which
the desired points are found are identified.  Finally the vertices of
the simplices are used to interpolate to the desired points.  The
functions that perform this interpolation are 'griddata', 'griddata3'
and 'griddatan'.

 -- Function File: ZI = griddata (X, Y, Z, XI, YI)
 -- Function File: ZI = griddata (X, Y, Z, XI, YI, METHOD)
 -- Function File: [XI, YI, ZI] = griddata (...)

     Generate a regular mesh from irregular data using interpolation.
     The function is defined by 'Z = f (X, Y)'.  Inputs 'X, Y, Z' are
     vectors of the same length or 'X, Y' are vectors and 'Z' is matrix.

     The interpolation points are all '(XI, YI)'.  If XI, YI are vectors
     then they are made into a 2-D mesh.

     The interpolation method can be "nearest", "cubic" or "linear".  If
     method is omitted it defaults to "linear".

     See also: *note griddata3: XREFgriddata3, *note griddatan:
     XREFgriddatan, *note delaunay: XREFdelaunay.

 -- Function File: VI = griddata3 (X, Y, Z, V, XI, YI, ZI)
 -- Function File: VI = griddata3 (X, Y, Z, V, XI, YI, ZI, METHOD)
 -- Function File: VI = griddata3 (X, Y, Z, V, XI, YI, ZI, METHOD,
          OPTIONS)

     Generate a regular mesh from irregular data using interpolation.
     The function is defined by 'V = f (X, Y, Z)'.  The interpolation
     points are specified by XI, YI, ZI.

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

     The optional argument OPTIONS is passed directly to Qhull when
     computing the Delaunay triangulation used for interpolation.  See
     'delaunayn' for information on the defaults and how to pass
     different values.

     See also: *note griddata: XREFgriddata, *note griddatan:
     XREFgriddatan, *note delaunayn: XREFdelaunayn.

 -- Function File: YI = griddatan (X, Y, XI)
 -- Function File: YI = griddatan (X, Y, XI, METHOD)
 -- Function File: YI = griddatan (X, Y, XI, METHOD, OPTIONS)

     Generate a regular mesh from irregular data using interpolation.
     The function is defined by 'Y = f (X)'.  The interpolation points
     are all XI.

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

     The optional argument OPTIONS is passed directly to Qhull when
     computing the Delaunay triangulation used for interpolation.  See
     'delaunayn' for information on the defaults and how to pass
     different values.

     See also: *note griddata: XREFgriddata, *note griddata3:
     XREFgriddata3, *note delaunayn: XREFdelaunayn.

   An example of the use of the 'griddata' function is

     rand ("state", 1);
     x = 2*rand (1000,1) - 1;
     y = 2*rand (size (x)) - 1;
     z = sin (2*(x.^2+y.^2));
     [xx,yy] = meshgrid (linspace (-1,1,32));
     griddata (x,y,z,xx,yy);

that interpolates from a random scattering of points, to a uniform grid.


File: octave.info,  Node: Signal Processing,  Next: Image Processing,  Prev: Geometry,  Up: Top

31 Signal Processing
********************

This chapter describes the signal processing and fast Fourier transform
functions available in Octave.  Fast Fourier transforms are computed
with the FFTW or FFTPACK libraries depending on how Octave is built.

 -- Built-in Function: fft (X)
 -- Built-in Function: fft (X, N)
 -- Built-in Function: fft (X, N, DIM)
     Compute the discrete Fourier transform of A using a Fast Fourier
     Transform (FFT) algorithm.

     The FFT is calculated along the first non-singleton dimension of
     the array.  Thus if X is a matrix, 'fft (X)' computes the FFT for
     each column of X.

     If called with two arguments, N is expected to be an integer
     specifying the number of elements of X to use, or an empty matrix
     to specify that its value should be ignored.  If N is larger than
     the dimension along which the FFT is calculated, then X is resized
     and padded with zeros.  Otherwise, if N is smaller than the
     dimension along which the FFT is calculated, then X is truncated.

     If called with three arguments, DIM is an integer specifying the
     dimension of the matrix along which the FFT is performed

     See also: *note ifft: XREFifft, *note fft2: XREFfft2, *note fftn:
     XREFfftn, *note fftw: XREFfftw.

 -- Built-in Function: ifft (X)
 -- Built-in Function: ifft (X, N)
 -- Built-in Function: ifft (X, N, DIM)
     Compute the inverse discrete Fourier transform of A using a Fast
     Fourier Transform (FFT) algorithm.

     The inverse FFT is calculated along the first non-singleton
     dimension of the array.  Thus if X is a matrix, 'fft (X)' computes
     the inverse FFT for each column of X.

     If called with two arguments, N is expected to be an integer
     specifying the number of elements of X to use, or an empty matrix
     to specify that its value should be ignored.  If N is larger than
     the dimension along which the inverse FFT is calculated, then X is
     resized and padded with zeros.  Otherwise, if N is smaller than the
     dimension along which the inverse FFT is calculated, then X is
     truncated.

     If called with three arguments, DIM is an integer specifying the
     dimension of the matrix along which the inverse FFT is performed

     See also: *note fft: XREFfft, *note ifft2: XREFifft2, *note ifftn:
     XREFifftn, *note fftw: XREFfftw.

 -- Built-in Function: fft2 (A)
 -- Built-in Function: fft2 (A, M, N)
     Compute the two-dimensional discrete Fourier transform of A using a
     Fast Fourier Transform (FFT) algorithm.

     The optional arguments M and N may be used specify the number of
     rows and columns of A to use.  If either of these is larger than
     the size of A, A is resized and padded with zeros.

     If A is a multi-dimensional matrix, each two-dimensional sub-matrix
     of A is treated separately.

     See also: ifft2, fft, fftn, fftw.

 -- Built-in Function: ifft2 (A)
 -- Built-in Function: ifft2 (A, M, N)
     Compute the inverse two-dimensional discrete Fourier transform of A
     using a Fast Fourier Transform (FFT) algorithm.

     The optional arguments M and N may be used specify the number of
     rows and columns of A to use.  If either of these is larger than
     the size of A, A is resized and padded with zeros.

     If A is a multi-dimensional matrix, each two-dimensional sub-matrix
     of A is treated separately

     See also: fft2, ifft, ifftn, fftw.

 -- Built-in Function: fftn (A)
 -- Built-in Function: fftn (A, SIZE)
     Compute the N-dimensional discrete Fourier transform of A using a
     Fast Fourier Transform (FFT) algorithm.

     The optional vector argument SIZE may be used specify the
     dimensions of the array to be used.  If an element of SIZE is
     smaller than the corresponding dimension of A, then the dimension
     of A is truncated prior to performing the FFT.  Otherwise, if an
     element of SIZE is larger than the corresponding dimension then A
     is resized and padded with zeros.

     See also: *note ifftn: XREFifftn, *note fft: XREFfft, *note fft2:
     XREFfft2, *note fftw: XREFfftw.

 -- Built-in Function: ifftn (A)
 -- Built-in Function: ifftn (A, SIZE)
     Compute the inverse N-dimensional discrete Fourier transform of A
     using a Fast Fourier Transform (FFT) algorithm.

     The optional vector argument SIZE may be used specify the
     dimensions of the array to be used.  If an element of SIZE is
     smaller than the corresponding dimension of A, then the dimension
     of A is truncated prior to performing the inverse FFT.  Otherwise,
     if an element of SIZE is larger than the corresponding dimension
     then A is resized and padded with zeros.

     See also: *note fftn: XREFfftn, *note ifft: XREFifft, *note ifft2:
     XREFifft2, *note fftw: XREFfftw.

   Octave uses the FFTW libraries to perform FFT computations.  When
Octave starts up and initializes the FFTW libraries, they read a system
wide file (on a Unix system, it is typically '/etc/fftw/wisdom') that
contains information useful to speed up FFT computations.  This
information is called the _wisdom_.  The system-wide file allows wisdom
to be shared between all applications using the FFTW libraries.

   Use the 'fftw' function to generate and save wisdom.  Using the
utilities provided together with the FFTW libraries ('fftw-wisdom' on
Unix systems), you can even add wisdom generated by Octave to the
system-wide wisdom file.

 -- Loadable Function: METHOD = fftw ("planner")
 -- Loadable Function: fftw ("planner", METHOD)
 -- Loadable Function: WISDOM = fftw ("dwisdom")
 -- Loadable Function: fftw ("dwisdom", WISDOM)
 -- Loadable Function: fftw ("threads", NTHREADS)
 -- Loadable Function: NTHREADS = fftw ("threads")

     Manage FFTW wisdom data.  Wisdom data can be used to significantly
     accelerate the calculation of the FFTs, but implies an initial cost
     in its calculation.  When the FFTW libraries are initialized, they
     read a system wide wisdom file (typically in '/etc/fftw/wisdom'),
     allowing wisdom to be shared between applications other than
     Octave.  Alternatively, the 'fftw' function can be used to import
     wisdom.  For example,

          WISDOM = fftw ("dwisdom")

     will save the existing wisdom used by Octave to the string WISDOM.
     This string can then be saved to a file and restored using the
     'save' and 'load' commands respectively.  This existing wisdom can
     be re-imported as follows

          fftw ("dwisdom", WISDOM)

     If WISDOM is an empty string, then the wisdom used is cleared.

     During the calculation of Fourier transforms further wisdom is
     generated.  The fashion in which this wisdom is generated is also
     controlled by the 'fftw' function.  There are five different
     manners in which the wisdom can be treated:

     "estimate"
          Specifies that no run-time measurement of the optimal means of
          calculating a particular is performed, and a simple heuristic
          is used to pick a (probably sub-optimal) plan.  The advantage
          of this method is that there is little or no overhead in the
          generation of the plan, which is appropriate for a Fourier
          transform that will be calculated once.

     "measure"
          In this case a range of algorithms to perform the transform is
          considered and the best is selected based on their execution
          time.

     "patient"
          Similar to "measure", but a wider range of algorithms is
          considered.

     "exhaustive"
          Like "measure", but all possible algorithms that may be used
          to treat the transform are considered.

     "hybrid"
          As run-time measurement of the algorithm can be expensive,
          this is a compromise where "measure" is used for transforms up
          to the size of 8192 and beyond that the "estimate" method is
          used.

     The default method is "estimate".  The current method can be
     queried with

          METHOD = fftw ("planner")

     or set by using

          fftw ("planner", METHOD)

     Note that calculated wisdom will be lost when restarting Octave.
     However, the wisdom data can be reloaded if it is saved to a file
     as described above.  Saved wisdom files should not be used on
     different platforms since they will not be efficient and the point
     of calculating the wisdom is lost.

     The number of threads used for computing the plans and executing
     the transforms can be set with

          fftw ("threads", NTHREADS)

     Note that octave must be compiled with multi-threaded FFTW support
     for this feature.  The number of processors available to the
     current process is used per default.

     See also: *note fft: XREFfft, *note ifft: XREFifft, *note fft2:
     XREFfft2, *note ifft2: XREFifft2, *note fftn: XREFfftn, *note
     ifftn: XREFifftn.

 -- Function File: fftconv (X, Y)
 -- Function File: fftconv (X, Y, N)
     Convolve two vectors using the FFT for computation.

     'c = fftconv (X, Y)' returns a vector of length equal to 'length
     (X) + length (Y) - 1'.  If X and 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 'fftfilt'.  If
     the optional argument N is specified, an N-point FFT is used.

     See also: *note deconv: XREFdeconv, *note conv: XREFconv, *note
     conv2: XREFconv2.

 -- Function File: fftfilt (B, X)
 -- Function File: fftfilt (B, X, N)

     With two arguments, 'fftfilt' filters X with the FIR filter B using
     the FFT.

     Given the optional third argument, N, 'fftfilt' uses the
     overlap-add method to filter X with B using an N-point FFT.  The
     FFT size must be an even power of 2 and must be greater than or
     equal to the length of B.  If the specified N does not meet these
     criteria, it is automatically adjusted to the nearest value that
     does.

     If X is a matrix, filter each column of the matrix.

     See also: *note filter: XREFfilter, *note filter2: XREFfilter2.

 -- Built-in Function: y = filter (B, A, X)
 -- Built-in Function: [Y, SF] = filter (B, A, X, SI)
 -- Built-in Function: [Y, SF] = filter (B, A, X, [], DIM)
 -- Built-in Function: [Y, SF] = filter (B, A, X, SI, DIM)
     Return the solution to the following linear, time-invariant
     difference equation:

           N                   M
          SUM a(k+1) y(n-k) = SUM b(k+1) x(n-k)    for 1<=n<=length(x)
          k=0                 k=0

     where N=length(a)-1 and M=length(b)-1.  The result is calculated
     over the first non-singleton dimension of X or over DIM if
     supplied.

     An equivalent form of the equation is:

                    N                   M
          y(n) = - SUM c(k+1) y(n-k) + SUM d(k+1) x(n-k)  for 1<=n<=length(x)
                   k=1                 k=0

     where c = a/a(1) and d = b/a(1).

     If the fourth argument SI is provided, it is taken as the initial
     state of the system and the final state is returned as SF.  The
     state vector is a column vector whose length is equal to the length
     of the longest coefficient vector minus one.  If SI is not
     supplied, the initial state vector is set to all zeros.

     In terms of the Z Transform, y is the result of passing the
     discrete- time signal x through a system characterized by the
     following rational system function:

                    M
                   SUM d(k+1) z^(-k)
                   k=0
          H(z) = ---------------------
                      N
                 1 + SUM c(k+1) z^(-k)
                     k=1

     See also: *note filter2: XREFfilter2, *note fftfilt: XREFfftfilt,
     *note freqz: XREFfreqz.

 -- Function File: Y = filter2 (B, X)
 -- Function File: Y = filter2 (B, X, SHAPE)
     Apply the 2-D FIR filter B to X.  If the argument SHAPE is
     specified, return an array of the desired shape.  Possible values
     are:

     "full"
          pad X with zeros on all sides before filtering.

     "same"
          unpadded X (default)

     "valid"
          trim X after filtering so edge effects are no included.

     Note this is just a variation on convolution, with the parameters
     reversed and B rotated 180 degrees.

     See also: *note conv2: XREFconv2.

 -- Function File: [H, W] = freqz (B, A, N, "whole")
 -- Function File: H = freqz (B, A, W)
 -- Function File: [...] = freqz (..., FS)
 -- Function File: freqz (...)

     Return the complex frequency response H of the rational IIR filter
     whose numerator and denominator coefficients are B and A,
     respectively.  The response is evaluated at N angular frequencies
     between 0 and 2*pi.

     The output value W is a vector of the frequencies.

     If A is omitted, the denominator is assumed to be 1 (this
     corresponds to a simple FIR filter).

     If N is omitted, a value of 512 is assumed.

     For fastest computation, N should factor into a small number of
     small primes.

     If the fourth argument, "whole", is omitted the response is
     evaluated at frequencies between 0 and pi.

     'freqz (B, A, W)'

     Evaluate the response at the specific frequencies in the vector W.
     The values for W are measured in radians.

     '[...] = freqz (..., FS)'

     Return frequencies in Hz instead of radians assuming a sampling
     rate FS.  If you are evaluating the response at specific
     frequencies W, those frequencies should be requested in Hz rather
     than radians.

     'freqz (...)'

     Plot the pass band, stop band and phase response of H rather than
     returning them.

 -- Function File: freqz_plot (W, H)
     Plot the pass band, stop band and phase response of H.

 -- Function File: sinc (X)
     Return sin (pi*x) / (pi*x).

 -- Function File: B = unwrap (X)
 -- Function File: B = unwrap (X, TOL)
 -- Function File: B = unwrap (X, TOL, DIM)

     Unwrap radian phases by adding multiples of 2*pi as appropriate to
     remove jumps greater than TOL.  TOL defaults to pi.

     Unwrap will work along the dimension DIM.  If DIM is unspecified it
     defaults to the first non-singleton dimension.

 -- Function File: [A, B] = arch_fit (Y, X, P, ITER, GAMMA, A0, B0)
     Fit an ARCH regression model to the time series Y using the scoring
     algorithm in Engle's original ARCH paper.  The model is

          y(t) = b(1) * x(t,1) + ... + b(k) * x(t,k) + e(t),
          h(t) = a(1) + a(2) * e(t-1)^2 + ... + a(p+1) * e(t-p)^2

     in which e(t) is N(0, h(t)), given a time-series vector Y up to
     time t-1 and a matrix of (ordinary) regressors X up to t.  The
     order of the regression of the residual variance is specified by P.

     If invoked as 'arch_fit (Y, K, P)' with a positive integer K, fit
     an ARCH(K, P) process, i.e., do the above with the t-th row of X
     given by

          [1, y(t-1), ..., y(t-k)]

     Optionally, one can specify the number of iterations ITER, the
     updating factor GAMMA, and initial values a0 and b0 for the scoring
     algorithm.

 -- Function File: arch_rnd (A, B, T)
     Simulate an ARCH sequence of length T with AR coefficients B and CH
     coefficients A.  I.e., the result y(t) follows the model

          y(t) = b(1) + b(2) * y(t-1) + ... + b(lb) * y(t-lb+1) + e(t),

     where e(t), given Y up to time t-1, is N(0, h(t)), with

          h(t) = a(1) + a(2) * e(t-1)^2 + ... + a(la) * e(t-la+1)^2

 -- Function File: [PVAL, LM] = arch_test (Y, X, P)
     For a linear regression model

          y = x * b + e

     perform a Lagrange Multiplier (LM) test of the null hypothesis of
     no conditional heteroscedascity against the alternative of CH(P).

     I.e., the model is

          y(t) = b(1) * x(t,1) + ... + b(k) * x(t,k) + e(t),

     given Y up to t-1 and X up to t, e(t) is N(0, h(t)) with

          h(t) = v + a(1) * e(t-1)^2 + ... + a(p) * e(t-p)^2,

     and the null is a(1) == ... == a(p) == 0.

     If the second argument is a scalar integer, k, perform the same
     test in a linear autoregression model of order k, i.e., with

          [1, y(t-1), ..., y(t-K)]

     as the t-th row of X.

     Under the null, LM approximately has a chisquare distribution with
     P degrees of freedom and PVAL is the p-value (1 minus the CDF of
     this distribution at LM) of the test.

     If no output argument is given, the p-value is displayed.

 -- Function File: arma_rnd (A, B, V, T, N)
     Return a simulation of the ARMA model

          x(n) = a(1) * x(n-1) + ... + a(k) * x(n-k)
               + e(n) + b(1) * e(n-1) + ... + b(l) * e(n-l)

     in which K is the length of vector A, L is the length of vector B
     and E is Gaussian white noise with variance V.  The function
     returns a vector of length T.

     The optional parameter N gives the number of dummy X(I) used for
     initialization, i.e., a sequence of length T+N is generated and
     X(N+1:T+N) is returned.  If N is omitted, N = 100 is used.

 -- Function File: autoreg_matrix (Y, K)
     Given a time series (vector) Y, return a matrix with ones in the
     first column and the first K lagged values of Y in the other
     columns.  I.e., for T > K, '[1, Y(T-1), ..., Y(T-K)]' is the t-th
     row of the result.  The resulting matrix may be used as a regressor
     matrix in autoregressions.

 -- Function File: bartlett (M)
     Return the filter coefficients of a Bartlett (triangular) window of
     length M.

     For a definition of the Bartlett window, see e.g., A. V. Oppenheim
     & R. W. Schafer, 'Discrete-Time Signal Processing'.

 -- Function File: blackman (M)
     Return the filter coefficients of a Blackman window of length M.

     For a definition of the Blackman window, see e.g., A. V. Oppenheim
     & R. W. Schafer, 'Discrete-Time Signal Processing'.

 -- Function File: detrend (X, P)
     If X is a vector, 'detrend (X, P)' removes the best fit of a
     polynomial of order P from the data X.

     If X is a matrix, 'detrend (X, P)' does the same for each column in
     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 P must be either "constant" (corresponds to 'P=0') or "linear"
     (corresponds to 'P=1').

     See also: *note polyfit: XREFpolyfit.

 -- Function File: [D, DD] = diffpara (X, A, B)
     Return the estimator D for the differencing parameter of an
     integrated time series.

     The frequencies from [2*pi*a/t, 2*pi*b/T] are used for the
     estimation.  If B is omitted, the interval [2*pi/T, 2*pi*a/T] is
     used.  If both B and A are omitted then a = 0.5 * sqrt (T) and b =
     1.5 * sqrt (T) is used, where T is the sample size.  If 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 DD.  The value of D is simply the mean of DD.

     Reference: P.J. Brockwell & R.A. Davis.  'Time Series: Theory and
     Methods'.  Springer 1987.

 -- Function File: durbinlevinson (C, OLDPHI, OLDV)
     Perform one step of the Durbin-Levinson algorithm.

     The vector C specifies the autocovariances '[gamma_0, ...,
     gamma_t]' from lag 0 to T, OLDPHI specifies the coefficients based
     on C(T-1) and OLDV specifies the corresponding error.

     If OLDPHI and OLDV are omitted, all steps from 1 to T of the
     algorithm are performed.

 -- Function File: fftshift (X)
 -- Function File: fftshift (X, DIM)
     Perform a shift of the vector X, for use with the 'fft' and 'ifft'
     functions, in order the move the frequency 0 to the center of the
     vector or matrix.

     If X is a vector of N elements corresponding to N time samples
     spaced by dt, then 'fftshift (fft (X))' corresponds to frequencies

          f = [ -(ceil((N-1)/2):-1:1)*df 0 (1:floor((N-1)/2))*df ]

     where df = 1 / dt.

     If X is a matrix, the same holds for rows and columns.  If X is an
     array, then the same holds along each dimension.

     The optional DIM argument can be used to limit the dimension along
     which the permutation occurs.

 -- Function File: ifftshift (X)
 -- Function File: ifftshift (X, DIM)
     Undo the action of the 'fftshift' function.  For even length X,
     'fftshift' is its own inverse, but odd lengths differ slightly.

 -- Function File: fractdiff (X, D)
     Compute the fractional differences (1-L)^d x where L denotes the
     lag-operator and d is greater than -1.

 -- Function File: hamming (M)
     Return the filter coefficients of a Hamming window of length M.

     For a definition of the Hamming window, see e.g., A. V. Oppenheim &
     R. W. Schafer, 'Discrete-Time Signal Processing'.

 -- Function File: hanning (M)
     Return the filter coefficients of a Hanning window of length M.

     For a definition of this window type, see e.g., A. V. Oppenheim &
     R. W. Schafer, 'Discrete-Time Signal Processing'.

 -- Function File: hurst (X)
     Estimate the Hurst parameter of sample X via the rescaled range
     statistic.  If X is a matrix, the parameter is estimated for every
     single column.

 -- Function File: PP = pchip (X, Y)
 -- Function File: YI = pchip (X, Y, XI)
     Return the Piecewise Cubic Hermite Interpolating Polynomial (pchip)
     of points X and Y.

     If called with two arguments, return the piecewise polynomial PP
     that may be used with 'ppval' to evaluate the polynomial at
     specific points.  When called with a third input argument, 'pchip'
     evaluates the pchip polynomial at the points XI.  The third calling
     form is equivalent to 'ppval (pchip (X, Y), XI)'.

     The variable X must be a strictly monotonic vector (either
     increasing or decreasing) of length N.  Y can be either a vector or
     array.  If Y is a vector then it must be the same length N as X.
     If Y is an array then the size of Y must have the form '[S1, S2,
     ..., SK, N]' The array is reshaped internally to a matrix where the
     leading dimension is given by 'S1 * S2 * ... * SK' and each row of
     this matrix is then treated separately.  Note that this is exactly
     opposite to 'interp1' but is done for MATLAB compatibility.

     See also: *note spline: XREFspline, *note ppval: XREFppval, *note
     mkpp: XREFmkpp, *note unmkpp: XREFunmkpp.

 -- Function File: [Pxx, W] = periodogram (X)
     For a data matrix X from a sample of size N, return the
     periodogram.  The angular frequency is returned in W.

     [Pxx,w] = periodogram (X).

     [Pxx,w] = periodogram (X,win).

     [Pxx,w] = periodogram (X,win,nfft).

     [Pxx,f] = periodogram (X,win,nfft,Fs).

     [Pxx,f] = periodogram (X,win,nfft,Fs,"range").

        * x: data; if real-valued a one-sided spectrum is estimated, if
          complex-valued or range indicates "twosided", the full
          spectrum is estimated.

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

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

        * Fs: sampling rate, default 1.

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

        * Pxx: one-, or two-sided power spectrum.

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

        * f: frequency [0..Fs) (two-sided) or [0..Fs/2] one-sided.

 -- Function File: sinetone (FREQ, RATE, SEC, AMPL)
     Return a sinetone of frequency FREQ with length of SEC seconds at
     sampling rate RATE and with amplitude AMPL.  The arguments FREQ and
     AMPL may be vectors of common size.

     Defaults are RATE = 8000, SEC = 1 and AMPL = 64.

 -- Function File: sinewave (M, N, D)
     Return an M-element vector with I-th element given by 'sin (2 * pi
     * (I+D-1) / N)'.

     The default value for D is 0 and the default value for N is M.

 -- Function File: spectral_adf (C)
 -- Function File: spectral_adf (C, WIN)
 -- Function File: spectral_adf (C, WIN, B)
     Return the spectral density estimator given a vector of
     autocovariances C, window name WIN, and bandwidth, B.

     The window name, e.g., "triangle" or "rectangle" is used to search
     for a function called 'WIN_lw'.

     If WIN is omitted, the triangle window is used.  If B is omitted,
     '1 / sqrt (length (X))' is used.

     See also: *note spectral_xdf: XREFspectral_xdf.

 -- Function File: spectral_xdf (X)
 -- Function File: spectral_xdf (X, WIN)
 -- Function File: spectral_xdf (X, WIN, B)
     Return the spectral density estimator given a data vector X, window
     name WIN, and bandwidth, B.

     The window name, e.g., "triangle" or "rectangle" is used to search
     for a function called 'WIN_sw'.

     If WIN is omitted, the triangle window is used.  If B is omitted,
     '1 / sqrt (length (X))' is used.

     See also: *note spectral_adf: XREFspectral_adf.

 -- Function File: spencer (X)
     Return Spencer's 15 point moving average of each column of X.

 -- Function File: Y = stft (X)
 -- Function File: Y = stft (X, WIN_SIZE)
 -- Function File: Y = stft (X, WIN_SIZE, INC)
 -- Function File: Y = stft (X, WIN_SIZE, INC, NUM_COEF)
 -- Function File: Y = stft (X, WIN_SIZE, INC, NUM_COEF, WIN_TYPE)
 -- Function File: [Y, C] = stft (...)
     Compute the short-time Fourier transform of the vector X with
     NUM_COEF coefficients by applying a window of WIN_SIZE data points
     and an increment of INC points.

     Before computing the Fourier transform, one of the following
     windows is applied:

     "hanning"
          win_type = 1

     "hamming"
          win_type = 2

     "rectangle"
          win_type = 3

     The window names can be passed as strings or by the WIN_TYPE
     number.

     The following defaults are used for unspecified arguments: WIN_SIZE
     = 80, INC = 24, NUM_COEF = 64, and WIN_TYPE = 1.

     'Y = stft (X, ...)' returns the absolute values of the Fourier
     coefficients according to the NUM_COEF positive frequencies.

     '[Y, C] = stft (x, ...)' returns the entire STFT-matrix Y and a
     3-element vector C containing the window size, increment, and
     window type, which is needed by the 'synthesis' function.

     See also: *note synthesis: XREFsynthesis.

 -- Function File: X = synthesis (Y, C)
     Compute a signal from its short-time Fourier transform Y and a
     3-element vector C specifying window size, increment, and window
     type.

     The values Y and C can be derived by

          [Y, C] = stft (X , ...)

     See also: *note stft: XREFstft.

 -- Function File: [A, V] = yulewalker (C)
     Fit an AR (p)-model with Yule-Walker estimates given a vector C of
     autocovariances '[gamma_0, ..., gamma_p]'.

     Returns the AR coefficients, A, and the variance of white noise, V.


File: octave.info,  Node: Image Processing,  Next: Audio Processing,  Prev: Signal Processing,  Up: Top

32 Image Processing
*******************

Since an image is basically a matrix, Octave is a very powerful
environment for processing and analyzing images.  To illustrate how easy
it is to do image processing in Octave, the following example will load
an image, smooth it by a 5-by-5 averaging filter, and compute the
gradient of the smoothed image.

     I = imread ("myimage.jpg");
     S = conv2 (I, ones (5, 5) / 25, "same");
     [Dx, Dy] = gradient (S);

In this example 'S' contains the smoothed image, and 'Dx' and 'Dy'
contains the partial spatial derivatives of the image.

* Menu:

* Loading and Saving Images::
* Displaying Images::
* Representing Images::
* Plotting on top of Images::
* Color Conversion::


File: octave.info,  Node: Loading and Saving Images,  Next: Displaying Images,  Up: Image Processing

32.1 Loading and Saving Images
==============================

The first step in most image processing tasks is to load an image into
Octave which is done with the 'imread' function.  The 'imwrite' function
is the corresponding function for writing images to the disk.

   In summary, most image processing code will follow the structure of
this code

     I = imread ("my_input_image.img");
     J = process_my_image (I);
     imwrite (J, "my_output_image.img");

 -- Function File: [IMG, MAP, ALPHA] = imread (FILENAME)
 -- Function File: [...] = imread (FILENAME, EXT)
 -- Function File: [...] = imread (URL)
 -- Function File: [...] = imread (..., IDX)
 -- Function File: [...] = imread (..., PARAM1, VAL1, ...)
     Read images from various file formats.

     Reads an image as a matrix from the file FILENAME.  If there is no
     file FILENAME, and EXT was specified, it will look for a file named
     FILENAME and extension EXT, i.e., a file named FILENAME.EXT.

     The size and class of the output depends on the format of the
     image.  A color image is returned as an MxNx3 matrix.  Gray-level
     and black-and-white images are of size MxN. Multipage images will
     have an additional 4th dimension.

     The bit depth of the image determines the class of the output:
     "uint8", "uint16" or "single" for gray and color, and "logical" for
     black and white.  Note that indexed images always return the
     indexes for a colormap, independent if MAP is a requested output.
     To obtain the actual RGB image, use 'ind2rgb'.  When more than one
     indexed image is being read, MAP is obtained from the first.  In
     some rare cases this may be incorrect and 'imfinfo' can be used to
     obtain the colormap of each image.

     See the Octave manual for more information in representing images.

     Some file formats, such as TIFF and GIF, are able to store multiple
     images in a single file.  IDX can be a scalar or vector specifying
     the index of the images to read.  By default, Octave will only read
     the first page.

     Depending on the file format, it is possible to configure the
     reading of images with PARAM, VAL pairs.  The following options are
     supported:

     '"Frames" or "Index"'
          This is an alternative method to specify IDX.  When specifying
          it in this way, its value can also be the string "all".

     '"Info"'
          This option exists for MATLAB compatibility and has no effect.
          For maximum performance while reading multiple images from a
          single file, use the Index option.

     '"PixelRegion"'
          Controls the image region that is read.  Takes as value a cell
          array with two arrays of 3 elements '{ROWS COLS}'.  The
          elements in the array are the start, increment and end pixel
          to be read.  If the increment value is omitted, defaults to 1.

     See also: *note imwrite: XREFimwrite, *note imfinfo: XREFimfinfo,
     *note imformats: XREFimformats.

 -- Function File: imwrite (IMG, FILENAME)
 -- Function File: imwrite (IMG, FILENAME, EXT)
 -- Function File: imwrite (IMG, MAP, FILENAME)
 -- Function File: imwrite (..., PARAM1, VAL1, ...)
     Write images in various file formats.

     The image IMG can be a binary, grayscale, RGB, or multi-dimensional
     image.  The size and class of IMG should be the same as what should
     be expected when reading it with 'imread': the 3rd and 4th
     dimensions reserved for color space, and multiple pages
     respectively.  If it's an indexed image, the colormap MAP must also
     be specified.

     If EXT is not supplied, the file extension of FILENAME is used to
     determine the format.  The actual supported formats are dependent
     on options made during the build of Octave.  Use 'imformats' to
     check the support of the different image formats.

     Depending on the file format, it is possible to configure the
     writing of images with PARAM, VAL pairs.  The following options are
     supported:

     'Alpha'
          Alpha (transparency) channel for the image.  This must be a
          matrix with same class, and number of rows and columns of IMG.
          In case of a multipage image, the size of the 4th dimension
          must also match and the third dimension must be a singleton.
          By default, image will be completely opaque.

     'DelayTime'
          For formats that accept animations (such as GIF), controls for
          how long a frame is displayed until it moves to the next one.
          The value must be scalar (which will applied to all frames in
          IMG), or a vector of length equal to the number of frames in
          IM.  The value is in seconds, must be between 0 and 655.35,
          and defaults to 0.5.

     'DisposalMethod'
          For formats that accept animations (such as GIF), controls
          what happens to a frame before drawing the next one.  Its
          value can be one of the following strings: "doNotSpecify"
          (default); "leaveInPlace"; "restoreBG"; and "restorePrevious",
          or a cell array of those string with length equal to the
          number of frames in IMG.

     'LoopCount'
          For formats that accept animations (such as GIF), controls how
          many times the sequence is repeated.  A value of Inf means an
          infinite loop (default), a value of 0 or 1 that the sequence
          is played only once (loops zero times), while a value of 2 or
          above loops that number of times (looping twice means it plays
          the complete sequence 3 times).  This option is ignored when
          there is only a single image at the end of writing the file.

     'Quality'
          Set the quality of the compression.  The value should be an
          integer between 0 and 100, with larger values indicating
          higher visual quality and lower compression.  Defaults to 75.

     'WriteMode'
          Some file formats, such as TIFF and GIF, are able to store
          multiple images in a single file.  This option specifies if
          IMG should be appended to the file (if it exists) or if a new
          file should be created for it (possibly overwriting an
          existing file).  The value should be the string "Overwrite"
          (default), or "Append".

          Despite this option, the most efficient method of writing a
          multipage image is to pass a 4 dimensional IMG to 'imwrite',
          the same matrix that could be expected when using 'imread'
          with the option "Index" set to "all".

     See also: *note imread: XREFimread, *note imfinfo: XREFimfinfo,
     *note imformats: XREFimformats.

 -- Built-in Function: VAL = IMAGE_PATH ()
 -- Built-in Function: OLD_VAL = IMAGE_PATH (NEW_VAL)
 -- Built-in Function: IMAGE_PATH (NEW_VAL, "local")
     Query or set the internal variable that specifies a colon separated
     list of directories in which to search for image files.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note EXEC_PATH: XREFEXEC_PATH, *note OCTAVE_HOME:
     XREFOCTAVE_HOME.

   It is possible to get information about an image file on disk,
without actually reading it into Octave.  This is done using the
'imfinfo' function which provides read access to many of the parameters
stored in the header of the image file.

 -- Function File: INFO = imfinfo (FILENAME)
 -- Function File: INFO = imfinfo (FILENAME, EXT)
 -- Function File: INFO = imfinfo (URL)
     Read image information from a file.

     'imfinfo' returns a structure containing information about the
     image stored in the file FILENAME.  If there is no file FILENAME,
     and EXT was specified, it will look for a file named FILENAME and
     extension EXT, i.e., a file named FILENAME.EXT.

     The output structure INFO contains the following fields:

     'Filename'
          The full name of the image file.

     'FileModDate'
          Date of last modification to the file.

     'FileSize'
          Number of bytes of the image on disk

     'Format'
          Image format (e.g., "jpeg").

     'Height'
          Image height in pixels.

     'Width'
          Image Width in pixels.

     'BitDepth'
          Number of bits per channel per pixel.

     'ColorType'
          Image type.  Value is "grayscale", "indexed", "truecolor",
          "CMYK", or "undefined".

     'XResolution'
          X resolution of the image.

     'YResolution'
          Y resolution of the image.

     'ResolutionUnit'
          Units of image resolution.  Value is "Inch", "Centimeter", or
          "undefined".

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

     'LoopCount'
          Number of iterations to loop an animation.

     'ByteOrder'
          Endian option for formats that support it.  Value is
          "little-endian", "big-endian", or "undefined".

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

     'Quality'
          JPEG/MIFF/PNG compression level.  Value is an integer in the
          range [0 100].

     'DisposalMethod'
          Only valid for GIF images, control how successive frames are
          rendered (how the preceding frame is disposed of) when
          creating a GIF animation.  Values can be "doNotSpecify",
          "leaveInPlace", "restoreBG", or "restorePrevious".  For
          non-GIF files, value is an empty string.

     'Chromaticities'
          Value is a 1x8 Matrix with the x,y chromaticity values for
          white, red, green, and blue points, in that order.

     'Comment'
          Image comment.

     'Compression'
          Compression type.  Value can be "none", "bzip", "fax3",
          "fax4", "jpeg", "lzw", "rle", "deflate", "lzma", "jpeg2000",
          "jbig2", "jbig2", or "undefined".

     'Colormap'
          Colormap for each image.

     'Orientation'
          The orientation of the image with respect to the rows and
          columns.  Value is an integer between 1 and 8 as defined in
          the TIFF 6 specifications, and for MATLAB compatibility.

     'Software'
          Name and version of the software or firmware of the camera or
          image input device used to generate the image.

     'Make'
          The manufacturer of the recording equipment.  This is the
          manufacture of the DSC, scanner, video digitizer or other
          equipment that generated the image.

     'Model'
          The model name or model number of the recording equipment as
          mentioned on the field "Make".

     'DateTime'
          The date and time of image creation as defined by the Exif
          standard, i.e., it is the date and time the file was changed.

     'ImageDescription'
          The title of the image as defined by the Exif standard.

     'Artist'
          Name of the camera owner, photographer or image creator.

     'Copyright'
          Copyright notice of the person or organization claiming rights
          to the image.

     'DigitalCamera'
          A struct with information retrieved from the Exif tag.

     'GPSInfo'
          A struct with geotagging information retrieved from the Exif
          tag.

     See also: *note imread: XREFimread, *note imwrite: XREFimwrite,
     *note imshow: XREFimshow, *note imformats: XREFimformats.

   By default, Octave's image IO functions ('imread', 'imwrite', and
'imfinfo') use the 'GraphicsMagick' library for their operations.  This
means a vast number of image formats is supported but considering the
large amount of image formats in science and its commonly closed nature,
it is impossible to have a library capable of reading them all.  Because
of this, the function 'imformats' keeps a configurable list of available
formats, their extensions, and what functions should the image IO
functions use.  This allows to expand Octave's image IO capabilities by
creating functions aimed at acting on specific file formats.

   While it would be possible to call the extra functions directly,
properly configuring Octave with 'imformats' allows to keep a consistent
code that is abstracted from file formats.

   It is important to note that a file format is not actually defined by
its file extension and that 'GraphicsMagick' is capable to read and
write more file formats than the ones listed by 'imformats'.  What this
means is that even with an incorrect or missing extension the image may
still be read correctly, and that even unlisted formats are not
necessarily unsupported.

 -- Function File: imformats ()
 -- Function File: FORMATS = imformats (EXT)
 -- Function File: FORMATS = imformats (FORMAT)
 -- Function File: FORMATS = imformats ("add", FORMAT)
 -- Function File: FORMATS = imformats ("remove", EXT)
 -- Function File: FORMATS = imformats ("update", EXT, FORMAT)
 -- Function File: FORMATS = imformats ("factory")
     Manage supported image formats.

     FORMATS is a structure with information about each supported file
     format, or from a specific format EXT, the value displayed on the
     field 'ext'.  It contains the following fields:

     ext
          The name of the file format.  This may match the file
          extension but Octave will automatically detect the file
          format.

     description
          A long description of the file format.

     isa
          A function handle to confirm if a file is of the specified
          format.

     write
          A function handle to write if a file is of the specified
          format.

     read
          A function handle to open files the specified format.

     info
          A function handle to obtain image information of the specified
          format.

     alpha
          Logical value if format supports alpha channel (transparency
          or matte).

     multipage
          Logical value if format supports multipage (multiple images
          per file).

     It is possible to change the way Octave manages file formats with
     the options "add", "remove", and "update", and supplying a
     structure FORMAT with the required fields.  The option "factory"
     resets the configuration to the default.

     This can be used by Octave packages to extend the image reading
     capabilities Octave, through use of the PKG_ADD and PKG_DEL
     commands.

     See also: *note imfinfo: XREFimfinfo, *note imread: XREFimread,
     *note imwrite: XREFimwrite.

