Mercurial > octave-antonio
changeset 20165:f1d0f506ee78 stable
doc: Update more docstrings to have one sentence summary as first line.
Reviewed optimization, polynomial, signal script directories.
* scripts/optimization/fminbnd.m, scripts/optimization/fminsearch.m,
scripts/optimization/fminunc.m, scripts/optimization/fsolve.m,
scripts/optimization/fzero.m, scripts/optimization/glpk.m,
scripts/optimization/lsqnonneg.m, scripts/optimization/pqpnonneg.m,
scripts/optimization/qp.m, scripts/optimization/sqp.m,
scripts/polynomial/compan.m, scripts/polynomial/mkpp.m,
scripts/polynomial/mpoles.m, scripts/polynomial/pchip.m,
scripts/polynomial/poly.m, scripts/polynomial/polyaffine.m,
scripts/polynomial/polyder.m, scripts/polynomial/polyeig.m,
scripts/polynomial/polyfit.m, scripts/polynomial/polygcd.m,
scripts/polynomial/polyint.m, scripts/polynomial/polyout.m,
scripts/polynomial/polyval.m, scripts/polynomial/ppder.m,
scripts/polynomial/ppint.m, scripts/polynomial/ppjumps.m,
scripts/polynomial/ppval.m, scripts/polynomial/residue.m,
scripts/polynomial/roots.m, scripts/polynomial/spline.m,
scripts/polynomial/splinefit.m, scripts/polynomial/unmkpp.m,
scripts/signal/arch_fit.m, scripts/signal/arch_rnd.m,
scripts/signal/arma_rnd.m, scripts/signal/autoreg_matrix.m,
scripts/signal/bartlett.m, scripts/signal/blackman.m, scripts/signal/detrend.m,
scripts/signal/diffpara.m, scripts/signal/durbinlevinson.m,
scripts/signal/fftconv.m, scripts/signal/fftfilt.m, scripts/signal/fftshift.m,
scripts/signal/filter2.m, scripts/signal/freqz.m, scripts/signal/hamming.m,
scripts/signal/hanning.m, scripts/signal/hurst.m, scripts/signal/ifftshift.m,
scripts/signal/periodogram.m, scripts/signal/sinc.m, scripts/signal/sinetone.m,
scripts/signal/sinewave.m, scripts/signal/spectral_adf.m,
scripts/signal/spectral_xdf.m, scripts/signal/spencer.m, scripts/signal/stft.m,
scripts/signal/synthesis.m, scripts/signal/unwrap.m,
scripts/signal/yulewalker.m:
Update more docstrings to have one sentence summary as first line.
line wrap: on
line diff
--- a/scripts/optimization/fminbnd.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/optimization/fminbnd.m Mon May 04 21:50:57 2015 -0700 @@ -29,8 +29,9 @@ ## @qcode{"MaxIter"}, @qcode{"MaxFunEvals"}. For a description of these ## options, see @ref{XREFoptimset,,optimset}. ## -## On exit, the function returns @var{x}, the approximate minimum point -## and @var{fval}, the function value thereof. +## On exit, the function returns @var{x}, the approximate minimum point and +## @var{fval}, the function value thereof. +## ## @var{info} is an exit flag that can have these values: ## ## @itemize @@ -44,11 +45,11 @@ ## The algorithm has been terminated from user output function. ## @end itemize ## -## Notes: The search for a minimum is restricted to be in the interval -## bound by @var{a} and @var{b}. If you only have an initial point -## to begin searching from you will need to use an unconstrained -## minimization algorithm such as @code{fminunc} or @code{fminsearch}. -## @code{fminbnd} internally uses a Golden Section search strategy. +## Notes: The search for a minimum is restricted to be in the interval bound by +## @var{a} and @var{b}. If you only have an initial point to begin searching +## from you will need to use an unconstrained minimization algorithm such as +## @code{fminunc} or @code{fminsearch}. @code{fminbnd} internally uses a +## Golden Section search strategy. ## @seealso{fzero, fminunc, fminsearch, optimset} ## @end deftypefn
--- a/scripts/optimization/fminsearch.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/optimization/fminsearch.m Mon May 04 21:50:57 2015 -0700 @@ -23,19 +23,19 @@ ## @deftypefnx {Function File} {[@var{x}, @var{fval}] =} fminsearch (@dots{}) ## ## Find a value of @var{x} which minimizes the function @var{fun}. +## ## The search begins at the point @var{x0} and iterates using the ## @nospell{Nelder & Mead} Simplex algorithm (a derivative-free method). This ## algorithm is better-suited to functions which have discontinuities or for ## which a gradient-based search such as @code{fminunc} fails. ## -## Options for the search are provided in the parameter @var{options} using -## the function @code{optimset}. Currently, @code{fminsearch} accepts the -## options: @qcode{"TolX"}, @qcode{"MaxFunEvals"}, @qcode{"MaxIter"}, -## @qcode{"Display"}. For a description of these options, see -## @code{optimset}. +## Options for the search are provided in the parameter @var{options} using the +## function @code{optimset}. Currently, @code{fminsearch} accepts the options: +## @qcode{"TolX"}, @qcode{"MaxFunEvals"}, @qcode{"MaxIter"}, @qcode{"Display"}. +## For a description of these options, see @code{optimset}. ## -## On exit, the function returns @var{x}, the minimum point, -## and @var{fval}, the function value thereof. +## On exit, the function returns @var{x}, the minimum point, and @var{fval}, +## the function value thereof. ## ## Example usages: ##
--- a/scripts/optimization/fminunc.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/optimization/fminunc.m Mon May 04 21:50:57 2015 -0700 @@ -25,31 +25,34 @@ ## Solve an unconstrained optimization problem defined by the function ## @var{fcn}. ## -## @var{fcn} should accept a vector (array) defining the unknown variables, -## and return the objective function value, optionally with gradient. +## @var{fcn} should accept a vector (array) defining the unknown variables, and +## return the objective function value, optionally with gradient. ## @code{fminunc} attempts to determine a vector @var{x} such that -## @code{@var{fcn} (@var{x})} is a local minimum. @var{x0} determines a -## starting guess. The shape of @var{x0} is preserved in all calls to -## @var{fcn}, but otherwise is treated as a column vector. -## @var{options} is a structure specifying additional options. -## Currently, @code{fminunc} recognizes these options: +## @code{@var{fcn} (@var{x})} is a local minimum. +## +## @var{x0} determines a starting guess. The shape of @var{x0} is preserved in +## all calls to @var{fcn}, but otherwise is treated as a column vector. +## +## @var{options} is a structure specifying additional options. Currently, +## @code{fminunc} recognizes these options: ## @qcode{"FunValCheck"}, @qcode{"OutputFcn"}, @qcode{"TolX"}, ## @qcode{"TolFun"}, @qcode{"MaxIter"}, @qcode{"MaxFunEvals"}, -## @qcode{"GradObj"}, @qcode{"FinDiffType"}, -## @qcode{"TypicalX"}, @qcode{"AutoScaling"}. +## @qcode{"GradObj"}, @qcode{"FinDiffType"}, @qcode{"TypicalX"}, +## @qcode{"AutoScaling"}. ## -## If @qcode{"GradObj"} is @qcode{"on"}, it specifies that @var{fcn}, -## when called with 2 output arguments, also returns the Jacobian matrix -## of partial first derivatives at the requested point. -## @code{TolX} specifies the termination tolerance for the unknown variables -## @var{x}, while @code{TolFun} is a tolerance for the objective function -## value @var{fval}. The default is @code{1e-7} for both options. +## If @qcode{"GradObj"} is @qcode{"on"}, it specifies that @var{fcn}, when +## called with 2 output arguments, also returns the Jacobian matrix of partial +## first derivatives at the requested point. @code{TolX} specifies the +## termination tolerance for the unknown variables @var{x}, while @code{TolFun} +## is a tolerance for the objective function value @var{fval}. The default is +## @code{1e-7} for both options. ## ## For a description of the other options, see @code{optimset}. ## ## On return, @var{x} is the location of the minimum and @var{fval} contains -## the value of the objective function at @var{x}. @var{info} may be one of the -## following values: +## the value of the objective function at @var{x}. +## +## @var{info} may be one of the following values: ## ## @table @asis ## @item 1 @@ -77,11 +80,13 @@ ## (@var{output}), the output gradient (@var{grad}) at the solution @var{x}, ## and approximate Hessian (@var{hess}) at the solution @var{x}. ## -## Notes: If have only a single nonlinear equation of one variable then using -## @code{fminbnd} is usually a much better idea. The algorithm used is a -## gradient search which depends on the objective function being differentiable. -## If the function has discontinuities it may be better to use a derivative-free -## algorithm such as @code{fminsearch}. +## Application Notes: If have only a single nonlinear equation of one variable +## then using @code{fminbnd} is usually a better choice. +## +## The algorithm used by @code{fminsearch} is a gradient search which depends +## on the objective function being differentiable. If the function has +## discontinuities it may be better to use a derivative-free algorithm such as +## @code{fminsearch}. ## @seealso{fminbnd, fminsearch, optimset} ## @end deftypefn
--- a/scripts/optimization/fsolve.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/optimization/fsolve.m Mon May 04 21:50:57 2015 -0700 @@ -22,48 +22,53 @@ ## @deftypefn {Function File} {} fsolve (@var{fcn}, @var{x0}, @var{options}) ## @deftypefnx {Function File} {[@var{x}, @var{fvec}, @var{info}, @var{output}, @var{fjac}] =} fsolve (@var{fcn}, @dots{}) ## Solve a system of nonlinear equations defined by the function @var{fcn}. +## ## @var{fcn} should accept a vector (array) defining the unknown variables, ## and return a vector of left-hand sides of the equations. Right-hand sides -## are defined to be zeros. -## In other words, this function attempts to determine a vector @var{x} such -## that @code{@var{fcn} (@var{x})} gives (approximately) all zeros. +## are defined to be zeros. In other words, this function attempts to +## determine a vector @var{x} such that @code{@var{fcn} (@var{x})} gives +## (approximately) all zeros. +## ## @var{x0} determines a starting guess. The shape of @var{x0} is preserved ## in all calls to @var{fcn}, but otherwise it is treated as a column vector. -## @var{options} is a structure specifying additional options. -## Currently, @code{fsolve} recognizes these options: +## +## @var{options} is a structure specifying additional options. Currently, +## @code{fsolve} recognizes these options: ## @qcode{"FunValCheck"}, @qcode{"OutputFcn"}, @qcode{"TolX"}, ## @qcode{"TolFun"}, @qcode{"MaxIter"}, @qcode{"MaxFunEvals"}, ## @qcode{"Jacobian"}, @qcode{"Updating"}, @qcode{"ComplexEqn"} ## @qcode{"TypicalX"}, @qcode{"AutoScaling"} and @qcode{"FinDiffType"}. ## -## If @qcode{"Jacobian"} is @qcode{"on"}, it specifies that @var{fcn}, -## called with 2 output arguments, also returns the Jacobian matrix -## of right-hand sides at the requested point. @qcode{"TolX"} specifies -## the termination tolerance in the unknown variables, while -## @qcode{"TolFun"} is a tolerance for equations. Default is @code{1e-7} -## for both @qcode{"TolX"} and @qcode{"TolFun"}. +## If @qcode{"Jacobian"} is @qcode{"on"}, it specifies that @var{fcn}, called +## with 2 output arguments also returns the Jacobian matrix of right-hand sides +## at the requested point. @qcode{"TolX"} specifies the termination tolerance +## in the unknown variables, while @qcode{"TolFun"} is a tolerance for +## equations. Default is @code{1e-7} for both @qcode{"TolX"} and +## @qcode{"TolFun"}. ## ## If @qcode{"AutoScaling"} is on, the variables will be automatically scaled ## according to the column norms of the (estimated) Jacobian. As a result, -## TolF becomes scaling-independent. By default, this option is off, because +## TolF becomes scaling-independent. By default, this option is off because ## it may sometimes deliver unexpected (though mathematically correct) results. ## ## If @qcode{"Updating"} is @qcode{"on"}, the function will attempt to use ## @nospell{Broyden} updates to update the Jacobian, in order to reduce the ## amount of Jacobian calculations. If your user function always calculates the -## Jacobian (regardless of number of output arguments), this option provides +## Jacobian (regardless of number of output arguments) then this option provides ## no advantage and should be set to false. ## ## @qcode{"ComplexEqn"} is @qcode{"on"}, @code{fsolve} will attempt to solve -## complex equations in complex variables, assuming that the equations possess a -## complex derivative (i.e., are holomorphic). If this is not what you want, -## should unpack the real and imaginary parts of the system to get a real +## complex equations in complex variables, assuming that the equations possess +## a complex derivative (i.e., are holomorphic). If this is not what you want, +## you should unpack the real and imaginary parts of the system to get a real ## system. ## ## For description of the other options, see @code{optimset}. ## ## On return, @var{fval} contains the value of the function @var{fcn} -## evaluated at @var{x}, and @var{info} may be one of the following values: +## evaluated at @var{x}. +## +## @var{info} may be one of the following values: ## ## @table @asis ## @item 1 @@ -87,8 +92,8 @@ ## @code{fzero} is usually a much better idea. ## ## Note about user-supplied Jacobians: -## As an inherent property of the algorithm, Jacobian is always requested for a -## solution vector whose residual vector is already known, and it is the last +## As an inherent property of the algorithm, a Jacobian is always requested for +## a solution vector whose residual vector is already known, and it is the last ## accepted successful step. Often this will be one of the last two calls, but ## not always. If the savings by reusing intermediate results from residual ## calculation in Jacobian calculation are significant, the best strategy is to
--- a/scripts/optimization/fzero.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/optimization/fzero.m Mon May 04 21:50:57 2015 -0700 @@ -24,8 +24,9 @@ ## @deftypefnx {Function File} {[@var{x}, @var{fval}, @var{info}, @var{output}] =} fzero (@dots{}) ## Find a zero of a univariate function. ## -## @var{fun} is a function handle, inline function, or string -## containing the name of the function to evaluate. +## @var{fun} is a function handle, inline function, or string containing the +## name of the function to evaluate. +## ## @var{x0} should be a two-element vector specifying two points which ## bracket a zero. In other words, there must be a change in sign of the ## function between @var{x0}(1) and @var{x0}(2). More mathematically, the @@ -35,17 +36,19 @@ ## sign (@var{fun}(@var{x0}(1))) * sign (@var{fun}(@var{x0}(2))) <= 0 ## @end example ## -## If @var{x0} is a single scalar then several nearby and distant -## values are probed in an attempt to obtain a valid bracketing. If this -## is not successful, the function fails. -## @var{options} is a structure specifying additional options. -## Currently, @code{fzero} -## recognizes these options: @qcode{"FunValCheck"}, @qcode{"OutputFcn"}, -## @qcode{"TolX"}, @qcode{"MaxIter"}, @qcode{"MaxFunEvals"}. +## If @var{x0} is a single scalar then several nearby and distant values are +## probed in an attempt to obtain a valid bracketing. If this is not +## successful, the function fails. +## +## @var{options} is a structure specifying additional options. Currently, +## @code{fzero} recognizes these options: +## @qcode{"FunValCheck"}, @qcode{"OutputFcn"}, @qcode{"TolX"}, +## @qcode{"MaxIter"}, @qcode{"MaxFunEvals"}. ## For a description of these options, see @ref{XREFoptimset,,optimset}. ## -## On exit, the function returns @var{x}, the approximate zero point -## and @var{fval}, the function value thereof. +## On exit, the function returns @var{x}, the approximate zero point and +## @var{fval}, the function value thereof. +## ## @var{info} is an exit flag that can have these values: ## ## @itemize
--- a/scripts/optimization/glpk.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/optimization/glpk.m Mon May 04 21:50:57 2015 -0700 @@ -19,8 +19,9 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {[@var{xopt}, @var{fmin}, @var{errnum}, @var{extra}] =} glpk (@var{c}, @var{A}, @var{b}, @var{lb}, @var{ub}, @var{ctype}, @var{vartype}, @var{sense}, @var{param}) -## Solve a linear program using the GNU @sc{glpk} library. Given three -## arguments, @code{glpk} solves the following standard LP: +## Solve a linear program using the GNU @sc{glpk} library. +## +## Given three arguments, @code{glpk} solves the following standard LP: ## @tex ## $$ ## \min_x C^T x @@ -90,23 +91,21 @@ ## A matrix containing the constraints coefficients. ## ## @item b -## A column array containing the right-hand side value for each constraint -## in the constraint matrix. +## A column array containing the right-hand side value for each constraint in +## the constraint matrix. ## ## @item lb -## An array containing the lower bound on each of the variables. If -## @var{lb} is not supplied, the default lower bound for the variables is -## zero. +## An array containing the lower bound on each of the variables. If @var{lb} +## is not supplied, the default lower bound for the variables is zero. ## ## @item ub -## An array containing the upper bound on each of the variables. If -## @var{ub} is not supplied, the default upper bound is assumed to be -## infinite. +## An array containing the upper bound on each of the variables. If @var{ub} +## is not supplied, the default upper bound is assumed to be infinite. ## ## @item ctype ## An array of characters containing the sense of each constraint in the -## constraint matrix. Each element of the array may be one of the -## following values +## constraint matrix. Each element of the array may be one of the following +## values ## ## @table @asis ## @item @qcode{"F"} @@ -138,14 +137,14 @@ ## @end table ## ## @item sense -## If @var{sense} is 1, the problem is a minimization. If @var{sense} is -## -1, the problem is a maximization. The default value is 1. +## If @var{sense} is 1, the problem is a minimization. If @var{sense} is -1, +## the problem is a maximization. The default value is 1. ## ## @item param ## A structure containing the following parameters used to define the ## behavior of solver. Missing elements in the structure take on default -## values, so you only need to set the elements that you wish to change -## from the default. +## values, so you only need to set the elements that you wish to change from +## the default. ## ## Integer parameters: ## @@ -220,9 +219,8 @@ ## stop the search. ## ## @item outfrq (default: 200) -## Output frequency, in iterations. This parameter specifies how -## frequently the solver sends information about the solution to the -## standard output. +## Output frequency, in iterations. This parameter specifies how frequently +## the solver sends information about the solution to the standard output. ## ## @item branch (default: 4) ## Branching technique option (for MIP only): @@ -293,13 +291,12 @@ ## ## @item outdly (default: 0) ## Output delay, in seconds. This parameter specifies how long the solver -## should delay sending information about the solution to the standard -## output. +## should delay sending information about the solution to the standard output. ## ## @item save (default: 0) -## If this parameter is nonzero, save a copy of the problem in -## CPLEX LP format to the file @file{"outpb.lp"}. There is currently no -## way to change the name of the output file. +## If this parameter is nonzero, save a copy of the problem in CPLEX LP +## format to the file @file{"outpb.lp"}. There is currently no way to change +## the name of the output file. ## @end table ## ## Real parameters: @@ -316,30 +313,30 @@ ## have a detailed understanding of its purpose. ## ## @item tolpiv (default: 1e-10) -## Relative tolerance used to choose eligible pivotal elements of the -## simplex table. It is not recommended that you change this parameter unless -## you have a detailed understanding of its purpose. +## Relative tolerance used to choose eligible pivotal elements of the simplex +## table. It is not recommended that you change this parameter unless you have +## a detailed understanding of its purpose. ## ## @item objll (default: -DBL_MAX) -## Lower limit of the objective function. If the objective -## function reaches this limit and continues decreasing, the solver stops -## the search. This parameter is used in the dual simplex method only. +## Lower limit of the objective function. If the objective function reaches +## this limit and continues decreasing, the solver stops the search. This +## parameter is used in the dual simplex method only. ## ## @item objul (default: +DBL_MAX) -## Upper limit of the objective function. If the objective -## function reaches this limit and continues increasing, the solver stops -## the search. This parameter is used in the dual simplex only. +## Upper limit of the objective function. If the objective function reaches +## this limit and continues increasing, the solver stops the search. This +## parameter is used in the dual simplex only. ## ## @item tolint (default: 1e-5) ## Relative tolerance used to check if the current basic solution is integer -## feasible. It is not recommended that you change this parameter unless -## you have a detailed understanding of its purpose. +## feasible. It is not recommended that you change this parameter unless you +## have a detailed understanding of its purpose. ## ## @item tolobj (default: 1e-7) -## Relative tolerance used to check if the value of the objective function -## is not better than in the best known integer feasible solution. It is -## not recommended that you change this parameter unless you have a -## detailed understanding of its purpose. +## Relative tolerance used to check if the value of the objective function is +## not better than in the best known integer feasible solution. It is not +## recommended that you change this parameter unless you have a detailed +## understanding of its purpose. ## @end table ## @end table ##
--- a/scripts/optimization/lsqnonneg.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/optimization/lsqnonneg.m Mon May 04 21:50:57 2015 -0700 @@ -28,11 +28,15 @@ ## @deftypefnx {Function File} {[@var{x}, @var{resnorm}, @var{residual}, @var{exitflag}, @var{output}] =} lsqnonneg (@dots{}) ## @deftypefnx {Function File} {[@var{x}, @var{resnorm}, @var{residual}, @var{exitflag}, @var{output}, @var{lambda}] =} lsqnonneg (@dots{}) ## Minimize @code{norm (@var{c}*@var{x} - d)} subject to -## @code{@var{x} >= 0}. @var{c} and @var{d} must be real. @var{x0} is an -## optional initial guess for @var{x}. -## Currently, @code{lsqnonneg} -## recognizes these options: @qcode{"MaxIter"}, @qcode{"TolX"}. -## For a description of these options, see @ref{XREFoptimset,,optimset}. +## @code{@var{x} >= 0}. +## +## @var{c} and @var{d} must be real. +## +## @var{x0} is an optional initial guess for @var{x}. +## +## Currently, @code{lsqnonneg} recognizes these options: @qcode{"MaxIter"}, +## @qcode{"TolX"}. For a description of these options, see +## @ref{XREFoptimset,,optimset}. ## ## Outputs: ## @@ -47,10 +51,10 @@ ## ## @item exitflag ## -## An indicator of convergence. 0 indicates that the iteration count -## was exceeded, and therefore convergence was not reached; >0 indicates -## that the algorithm converged. (The algorithm is stable and will -## converge given enough iterations.) +## An indicator of convergence. 0 indicates that the iteration count was +## exceeded, and therefore convergence was not reached; >0 indicates that the +## algorithm converged. (The algorithm is stable and will converge given +## enough iterations.) ## ## @item output ##
--- a/scripts/optimization/pqpnonneg.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/optimization/pqpnonneg.m Mon May 04 21:50:57 2015 -0700 @@ -25,9 +25,12 @@ ## @deftypefnx {Function File} {[@var{x}, @var{minval}, @var{exitflag}] =} pqpnonneg (@dots{}) ## @deftypefnx {Function File} {[@var{x}, @var{minval}, @var{exitflag}, @var{output}] =} pqpnonneg (@dots{}) ## @deftypefnx {Function File} {[@var{x}, @var{minval}, @var{exitflag}, @var{output}, @var{lambda}] =} pqpnonneg (@dots{}) -## Minimize @code{1/2*x'*c*x + d'*x} subject to @code{@var{x} >= 0}. @var{c} -## and @var{d} must be real, and @var{c} must be symmetric and positive -## definite. @var{x0} is an optional initial guess for @var{x}. +## Minimize @code{1/2*x'*c*x + d'*x} subject to @code{@var{x} >= 0}. +## +## @var{c} ## and @var{d} must be real, and @var{c} must be symmetric and +## positive definite. +## +## @var{x0} is an optional initial guess for @var{x}. ## ## Outputs: ## @@ -38,10 +41,10 @@ ## ## @item exitflag ## -## An indicator of convergence. 0 indicates that the iteration count -## was exceeded, and therefore convergence was not reached; >0 indicates -## that the algorithm converged. (The algorithm is stable and will -## converge given enough iterations.) +## An indicator of convergence. 0 indicates that the iteration count was +## exceeded, and therefore convergence was not reached; >0 indicates that the +## algorithm converged. (The algorithm is stable and will converge given +## enough iterations.) ## ## @item output ##
--- a/scripts/optimization/qp.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/optimization/qp.m Mon May 04 21:50:57 2015 -0700 @@ -24,7 +24,9 @@ ## @deftypefnx {Function File} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H}, @var{q}, @var{A}, @var{b}, @var{lb}, @var{ub}) ## @deftypefnx {Function File} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H}, @var{q}, @var{A}, @var{b}, @var{lb}, @var{ub}, @var{A_lb}, @var{A_in}, @var{A_ub}) ## @deftypefnx {Function File} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@dots{}, @var{options}) -## Solve the quadratic program +## Solve a quadratic program (QP). +## +## Solve the quadratic program defined by ## @tex ## $$ ## \min_x {1 \over 2} x^T H x + x^T q @@ -60,16 +62,16 @@ ## @noindent ## using a null-space active-set method. ## -## Any bound (@var{A}, @var{b}, @var{lb}, @var{ub}, @var{A_lb}, -## @var{A_ub}) may be set to the empty matrix (@code{[]}) if not -## present. If the initial guess is feasible the algorithm is faster. +## Any bound (@var{A}, @var{b}, @var{lb}, @var{ub}, @var{A_lb}, @var{A_ub}) +## may be set to the empty matrix (@code{[]}) if not present. If the initial +## guess is feasible the algorithm is faster. ## ## @table @var ## @item options -## An optional structure containing the following -## parameter(s) used to define the behavior of the solver. Missing elements -## in the structure take on default values, so you only need to set the -## elements that you wish to change from the default. +## An optional structure containing the following parameter(s) used to define +## the behavior of the solver. Missing elements in the structure take on +## default values, so you only need to set the elements that you wish to +## change from the default. ## ## @table @code ## @item MaxIter (default: 200)
--- a/scripts/optimization/sqp.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/optimization/sqp.m Mon May 04 21:50:57 2015 -0700 @@ -24,6 +24,8 @@ ## @deftypefnx {Function File} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g}, @var{h}, @var{lb}, @var{ub}) ## @deftypefnx {Function File} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g}, @var{h}, @var{lb}, @var{ub}, @var{maxiter}) ## @deftypefnx {Function File} {[@dots{}] =} sqp (@var{x0}, @var{phi}, @var{g}, @var{h}, @var{lb}, @var{ub}, @var{maxiter}, @var{tol}) +## Minimize an objective function using sequential quadratic programming (SQP). +## ## Solve the nonlinear program ## @tex ## $$ @@ -62,31 +64,29 @@ ## ## The first argument is the initial guess for the vector @var{x0}. ## -## The second argument is a function handle pointing to the objective -## function @var{phi}. The objective function must accept one vector -## argument and return a scalar. -## -## The second argument may also be a 2- or 3-element cell array of -## function handles. The first element should point to the objective -## function, the second should point to a function that computes the -## gradient of the objective function, and the third should point to a -## function that computes the Hessian of the objective function. If the -## gradient function is not supplied, the gradient is computed by finite -## differences. If the Hessian function is not supplied, a BFGS update -## formula is used to approximate the Hessian. +## The second argument is a function handle pointing to the objective function +## @var{phi}. The objective function must accept one vector argument and +## return a scalar. ## -## When supplied, the gradient function @code{@var{phi}@{2@}} must accept -## one vector argument and return a vector. When supplied, the Hessian -## function @code{@var{phi}@{3@}} must accept one vector argument and -## return a matrix. +## The 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. ## -## The third and fourth arguments @var{g} and @var{h} are function -## handles pointing to functions that compute the equality constraints -## and the inequality constraints, respectively. If the problem does -## not have equality (or inequality) constraints, then use an empty -## matrix ([]) for @var{g} (or @var{h}). When supplied, these equality -## and inequality constraint functions must accept one vector argument -## and return a vector. +## When supplied, the gradient function @code{@var{phi}@{2@}} must accept one +## vector argument and return a vector. When supplied, the Hessian function +## @code{@var{phi}@{3@}} must accept one vector argument and return a matrix. +## +## The third and fourth arguments @var{g} and @var{h} are function handles +## pointing to functions that compute the equality constraints and the +## inequality constraints, respectively. If the problem does not have +## equality (or inequality) constraints, then use an empty matrix ([]) for +## @var{g} (or @var{h}). When supplied, these equality and inequality +## constraint functions must accept one vector argument and return a vector. ## ## The third and fourth arguments may also be 2-element cell arrays of ## function handles. The first element should point to the constraint @@ -110,20 +110,19 @@ ## @end example ## ## @end ifnottex -## The fifth and sixth arguments, @var{lb} and @var{ub}, contain lower -## and upper bounds on @var{x}. These must be consistent with the -## equality and inequality constraints @var{g} and @var{h}. If the -## arguments are vectors then @var{x}(i) is bound by @var{lb}(i) and -## @var{ub}(i). A bound can also be a scalar in which case all elements -## of @var{x} will share the same bound. If only one bound (lb, ub) is -## specified then the other will default to (-@var{realmax}, -## +@var{realmax}). +## The fifth and sixth arguments, @var{lb} and @var{ub}, contain lower and +## upper bounds on @var{x}. These must be consistent with the equality and +## inequality constraints @var{g} and @var{h}. If the arguments are vectors +## then @var{x}(i) is bound by @var{lb}(i) and @var{ub}(i). A bound can also +## be a scalar in which case all elements of @var{x} will share the same +## bound. If only one bound (lb, ub) is specified then the other will +## default to (-@var{realmax}, +@var{realmax}). ## ## The seventh argument @var{maxiter} specifies the maximum number of ## iterations. The default value is 100. ## -## The eighth argument @var{tol} specifies the tolerance for the -## stopping criteria. The default value is @code{sqrt (eps)}. +## The eighth argument @var{tol} specifies the tolerance for the stopping +## criteria. The default value is @code{sqrt (eps)}. ## ## The value returned in @var{info} may be one of the following: ##
--- a/scripts/polynomial/compan.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/compan.m Mon May 04 21:50:57 2015 -0700 @@ -18,8 +18,8 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} compan (@var{c}) -## Compute the companion matrix corresponding to polynomial coefficient -## vector @var{c}. +## Compute the companion matrix corresponding to polynomial coefficient vector +## @var{c}. ## ## The companion matrix is ## @tex
--- a/scripts/polynomial/mkpp.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/mkpp.m Mon May 04 21:50:57 2015 -0700 @@ -21,24 +21,24 @@ ## @deftypefnx {Function File} {@var{pp} =} mkpp (@var{breaks}, @var{coefs}, @var{d}) ## ## Construct a piecewise polynomial (pp) structure from sample points -## @var{breaks} and coefficients @var{coefs}. @var{breaks} must be a vector of -## strictly increasing values. The number of intervals is given by -## @code{@var{ni} = length (@var{breaks}) - 1}. -## When @var{m} is the polynomial order @var{coefs} must be of -## size: @var{ni} x @var{m} + 1. +## @var{breaks} and coefficients @var{coefs}. ## -## The i-th row of @var{coefs}, -## @code{@var{coefs} (@var{i},:)}, contains the coefficients for the polynomial -## over the @var{i}-th interval, ordered from highest (@var{m}) to -## lowest (@var{0}). +## @var{breaks} must be a vector of strictly increasing values. The number of +## intervals is given by @code{@var{ni} = length (@var{breaks}) - 1}. +## +## When @var{m} is the polynomial order @var{coefs} must be of size: +## @var{ni} x @var{m} + 1. +## +## The i-th row of @var{coefs}, @code{@var{coefs} (@var{i},:)}, contains the +## coefficients for the polynomial over the @var{i}-th interval, ordered from +## highest (@var{m}) to lowest (@var{0}). ## ## @var{coefs} may also be a multi-dimensional array, specifying a vector-valued ## or array-valued polynomial. In that case the polynomial order is defined -## by the length of the last dimension of @var{coefs}. -## The size of first dimension(s) are given by the scalar or -## vector @var{d}. If @var{d} is not given it is set to @code{1}. -## In any case @var{coefs} is reshaped to a 2-D matrix of -## size @code{[@var{ni}*prod(@var{d} @var{m})] } +## by the length of the last dimension of @var{coefs}. The size of first +## dimension(s) are given by the scalar or vector @var{d}. If @var{d} is not +## given it is set to @code{1}. In any case @var{coefs} is reshaped to a 2-D +## matrix of size @code{[@var{ni}*prod(@var{d} @var{m})] } ## ## @seealso{unmkpp, ppval, spline, pchip, ppder, ppint, ppjumps} ## @end deftypefn
--- a/scripts/polynomial/mpoles.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/mpoles.m Mon May 04 21:50:57 2015 -0700 @@ -20,17 +20,17 @@ ## @deftypefn {Function File} {[@var{multp}, @var{idxp}] =} mpoles (@var{p}) ## @deftypefnx {Function File} {[@var{multp}, @var{idxp}] =} mpoles (@var{p}, @var{tol}) ## @deftypefnx {Function File} {[@var{multp}, @var{idxp}] =} mpoles (@var{p}, @var{tol}, @var{reorder}) -## Identify unique poles in @var{p} and their associated multiplicity. The -## output is ordered from largest pole to smallest pole. +## Identify unique poles in @var{p} and their associated multiplicity. ## -## If the relative difference of two poles is less than @var{tol} then -## they are considered to be multiples. The default value for @var{tol} -## is 0.001. +## The output is ordered from largest pole to smallest pole. +## +## If the relative difference of two poles is less than @var{tol} then they are +## considered to be multiples. The default value for @var{tol} is 0.001. ## ## If the optional parameter @var{reorder} is zero, poles are not sorted. ## -## The output @var{multp} is a vector specifying the multiplicity of the -## poles. @code{@var{multp}(n)} refers to the multiplicity of the Nth pole +## The output @var{multp} is a vector specifying the multiplicity of the poles. +## @code{@var{multp}(n)} refers to the multiplicity of the Nth pole ## @code{@var{p}(@var{idxp}(n))}. ## ## For example:
--- a/scripts/polynomial/pchip.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/pchip.m Mon May 04 21:50:57 2015 -0700 @@ -24,32 +24,34 @@ ## ## If called with two arguments, return the piecewise polynomial @var{pp} ## that may be used with @code{ppval} to evaluate the polynomial at specific -## points. When called with a third input argument, @code{pchip} evaluates -## the pchip polynomial at the points @var{xi}. The third calling form is -## equivalent to @code{ppval (pchip (@var{x}, @var{y}), @var{xi})}. +## points. +## +## When called with a third input argument, @code{pchip} evaluates the pchip +## polynomial at the points @var{xi}. The third calling form is equivalent to +## @code{ppval (pchip (@var{x}, @var{y}), @var{xi})}. ## -## The variable @var{x} must be a strictly monotonic vector (either -## increasing or decreasing) of length @var{n}. @var{y} can be either a -## vector or array. If @var{y} is a vector then it must be the same length -## @var{n} as @var{x}. If @var{y} is an array then the size of @var{y} must -## have the form +## The variable @var{x} must be a strictly monotonic vector (either increasing +## or decreasing) of length @var{n}. +## +## @var{y} can be either a vector or array. If @var{y} is a vector then it +## must be the same length @var{n} as @var{x}. If @var{y} is an array then +## the size of @var{y} must have the form ## @tex ## $$[s_1, s_2, \cdots, s_k, n]$$ ## @end tex ## @ifnottex ## @code{[@var{s1}, @var{s2}, @dots{}, @var{sk}, @var{n}]} ## @end ifnottex -## The array is reshaped internally to a matrix where the leading -## dimension is given by +## The array is reshaped internally to a matrix where the leading dimension is +## given by ## @tex ## $$s_1 s_2 \cdots s_k$$ ## @end tex ## @ifnottex ## @code{@var{s1} * @var{s2} * @dots{} * @var{sk}} ## @end ifnottex -## and each row of this matrix is then treated separately. Note that this -## is exactly opposite to @code{interp1} but is done for @sc{matlab} -## compatibility. +## and each row of this matrix is then treated separately. Note that this is +## exactly opposite to @code{interp1} but is done for @sc{matlab} compatibility. ## ## @seealso{spline, ppval, mkpp, unmkpp} ## @end deftypefn
--- a/scripts/polynomial/poly.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/poly.m Mon May 04 21:50:57 2015 -0700 @@ -21,9 +21,10 @@ ## @deftypefnx {Function File} {} poly (@var{x}) ## If @var{A} is a square @math{N}-by-@math{N} matrix, @code{poly (@var{A})} ## is the row vector of the coefficients of @code{det (z * eye (N) - A)}, -## the characteristic polynomial of @var{A}. For example, -## the following code finds the eigenvalues of @var{A} which are the roots of -## @code{poly (@var{A})}. +## the characteristic polynomial of @var{A}. +## +## For example, the following code finds the eigenvalues of @var{A} which are +## the roots of @code{poly (@var{A})}. ## ## @example ## @group @@ -40,9 +41,10 @@ ## ## If @var{x} is a vector, @code{poly (@var{x})} is a vector of the ## coefficients of the polynomial whose roots are the elements of @var{x}. -## That is, if @var{c} is a polynomial, then the elements of @code{@var{d} = -## roots (poly (@var{c}))} are contained in @var{c}. The vectors @var{c} and -## @var{d} are not identical, however, due to sorting and numerical errors. +## That is, if @var{c} is a polynomial, then the elements of +## @code{@var{d} = roots (poly (@var{c}))} are contained in @var{c}. The +## vectors @var{c} and @var{d} are not identical, however, due to sorting and +## numerical errors. ## @seealso{roots, eig} ## @end deftypefn
--- a/scripts/polynomial/polyaffine.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/polyaffine.m Mon May 04 21:50:57 2015 -0700 @@ -19,9 +19,10 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} polyaffine (@var{f}, @var{mu}) ## Return the coefficients of the polynomial vector @var{f} after an affine -## transformation. If @var{f} is the vector representing the polynomial f(x), -## then @code{@var{g} = polyaffine (@var{f}, @var{mu})} is the vector -## representing: +## transformation. +## +## If @var{f} is the vector representing the polynomial f(x), then +## @code{@var{g} = polyaffine (@var{f}, @var{mu})} is the vector representing: ## ## @example ## g(x) = f( (x - @var{mu}(1)) / @var{mu}(2) )
--- a/scripts/polynomial/polyder.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/polyder.m Mon May 04 21:50:57 2015 -0700 @@ -21,8 +21,11 @@ ## @deftypefnx {Function File} {[@var{k}] =} polyder (@var{a}, @var{b}) ## @deftypefnx {Function File} {[@var{q}, @var{d}] =} polyder (@var{b}, @var{a}) ## Return the coefficients of the derivative of the polynomial whose -## coefficients are given by the vector @var{p}. If a pair of polynomials -## is given, return the derivative of the product @math{@var{a}*@var{b}}. +## coefficients are given by the vector @var{p}. +## +## If a pair of polynomials is given, return the derivative of the product +## @math{@var{a}*@var{b}}. +## ## If two inputs and two outputs are given, return the derivative of the ## polynomial quotient @math{@var{b}/@var{a}}. The quotient numerator is ## in @var{q} and the denominator in @var{d}.
--- a/scripts/polynomial/polyeig.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/polyeig.m Mon May 04 21:50:57 2015 -0700 @@ -23,8 +23,11 @@ ## Solve the polynomial eigenvalue problem of degree @var{l}. ## ## Given an @var{n*n} matrix polynomial +## ## @code{@var{C}(s) = @var{C0} + @var{C1} s + @dots{} + @var{Cl} s^l} -## polyeig solves the eigenvalue problem +## +## @code{polyeig} solves the eigenvalue problem +## ## @code{(@var{C0} + @var{C1} + @dots{} + @var{Cl})v = 0}. ## ## Note that the eigenvalues @var{z} are the zeros of the matrix polynomial.
--- a/scripts/polynomial/polyfit.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/polyfit.m Mon May 04 21:50:57 2015 -0700 @@ -22,9 +22,10 @@ ## @deftypefnx {Function File} {[@var{p}, @var{s}, @var{mu}] =} polyfit (@var{x}, @var{y}, @var{n}) ## Return the coefficients of a polynomial @var{p}(@var{x}) of degree ## @var{n} that minimizes the least-squares-error of the fit to the points -## @code{[@var{x}, @var{y}]}. If @var{n} is a logical vector, it is used -## as a mask to selectively force the corresponding polynomial -## coefficients to be used or ignored. +## @code{[@var{x}, @var{y}]}. +## +## If @var{n} is a logical vector, it is used as a mask to selectively force +## the corresponding polynomial coefficients to be used or ignored. ## ## The polynomial coefficients are returned in a row vector. ## @@ -54,15 +55,18 @@ ## ## The second output may be used by @code{polyval} to calculate the ## statistical error limits of the predicted values. In particular, the -## standard deviation of @var{p} coefficients is given by @* +## standard deviation of @var{p} coefficients is given by +## ## @code{sqrt (diag (s.C)/s.df)*s.normr}. ## -## When the third output, @var{mu}, is present the -## coefficients, @var{p}, are associated with a polynomial in -## @var{xhat} = (@var{x}-@var{mu}(1))/@var{mu}(2). -## Where @var{mu}(1) = mean (@var{x}), and @var{mu}(2) = std (@var{x}). -## This linear transformation of @var{x} improves the numerical -## stability of the fit. +## When the third output, @var{mu}, is present the coefficients, @var{p}, are +## associated with a polynomial in +## +## @code{@var{xhat} = (@var{x} - @var{mu}(1)) / @var{mu}(2)} @* +## where @var{mu}(1) = mean (@var{x}), and @var{mu}(2) = std (@var{x}). +## +## This linear transformation of @var{x} improves the numerical stability of +## the fit. ## @seealso{polyval, polyaffine, roots, vander, zscore} ## @end deftypefn
--- a/scripts/polynomial/polygcd.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/polygcd.m Mon May 04 21:50:57 2015 -0700 @@ -20,9 +20,12 @@ ## @deftypefn {Function File} {@var{q} =} polygcd (@var{b}, @var{a}) ## @deftypefnx {Function File} {@var{q} =} polygcd (@var{b}, @var{a}, @var{tol}) ## -## Find the greatest common divisor of two polynomials. This is equivalent -## to the polynomial found by multiplying together all the common roots. -## Together with deconv, you can reduce a ratio of two polynomials. +## Find the greatest common divisor of two polynomials. +## +## This is equivalent to the polynomial found by multiplying together all the +## common roots. Together with deconv, you can reduce a ratio of two +## polynomials. +## ## The tolerance @var{tol} defaults to @code{sqrt (eps)}. ## ## @strong{Caution:} This is a numerically unstable algorithm and should not
--- a/scripts/polynomial/polyint.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/polyint.m Mon May 04 21:50:57 2015 -0700 @@ -20,8 +20,10 @@ ## @deftypefn {Function File} {} polyint (@var{p}) ## @deftypefnx {Function File} {} polyint (@var{p}, @var{k}) ## Return the coefficients of the integral of the polynomial whose -## coefficients are represented by the vector @var{p}. The variable -## @var{k} is the constant of integration, which by default is set to zero. +## coefficients are represented by the vector @var{p}. +## +## The variable @var{k} is the constant of integration, which by default is +## set to zero. ## @seealso{polyder, polyval} ## @end deftypefn
--- a/scripts/polynomial/polyout.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/polyout.m Mon May 04 21:50:57 2015 -0700 @@ -20,7 +20,9 @@ ## @deftypefn {Function File} {} polyout (@var{c}) ## @deftypefnx {Function File} {} polyout (@var{c}, @var{x}) ## @deftypefnx {Function File} {@var{str} =} polyout (@dots{}) -## Write formatted polynomial +## Display a formatted version of the polynomial @var{c}. +## +## The formatted polynomial ## @tex ## $$ c(x) = c_1 x^n + \ldots + c_n x + c_{n+1} $$ ## @end tex @@ -31,8 +33,10 @@ ## @end example ## ## @end ifnottex -## and return it as a string or write it to the screen (if @var{nargout} is -## zero). @var{x} defaults to the string @qcode{"s"}. +## is returned as a string or written to the screen if @code{nargout} is zero. +## +## The second argument @var{x} specifies the variable name to use for each term +## and defaults to the string @qcode{"s"}. ## @seealso{polyreduce} ## @end deftypefn
--- a/scripts/polynomial/polyval.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/polyval.m Mon May 04 21:50:57 2015 -0700 @@ -22,17 +22,19 @@ ## @deftypefnx {Function File} {[@var{y}, @var{dy}] =} polyval (@var{p}, @var{x}, @var{s}) ## @deftypefnx {Function File} {[@var{y}, @var{dy}] =} polyval (@var{p}, @var{x}, @var{s}, @var{mu}) ## -## Evaluate the polynomial @var{p} at the specified values of @var{x}. When -## @var{mu} is present, evaluate the polynomial for -## (@var{x}-@var{mu}(1))/@var{mu}(2). +## Evaluate the polynomial @var{p} at the specified values of @var{x}. +## ## If @var{x} is a vector or matrix, the polynomial is evaluated for each of ## the elements of @var{x}. ## -## In addition to evaluating the polynomial, the second output -## represents the prediction interval, @var{y} +/- @var{dy}, which -## contains at least 50% of the future predictions. To calculate the -## prediction interval, the structured variable @var{s}, originating -## from @code{polyfit}, must be supplied. +## When @var{mu} is present, evaluate the polynomial for +## (@var{x}-@var{mu}(1))/@var{mu}(2). +## +## In addition to evaluating the polynomial, the second output represents the +## prediction interval, @var{y} +/- @var{dy}, which contains at least 50% of +## the future predictions. To calculate the prediction interval, the +## structured variable @var{s}, originating from @code{polyfit}, must be +## supplied. ## ## @seealso{polyvalm, polyaffine, polyfit, roots, poly} ## @end deftypefn
--- a/scripts/polynomial/ppder.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/ppder.m Mon May 04 21:50:57 2015 -0700 @@ -20,7 +20,9 @@ ## @deftypefn {Function File} {ppd =} ppder (pp) ## @deftypefnx {Function File} {ppd =} ppder (pp, m) ## Compute the piecewise @var{m}-th derivative of a piecewise polynomial -## struct @var{pp}. If @var{m} is omitted the first derivative is calculated. +## struct @var{pp}. +## +## If @var{m} is omitted the first derivative is calculated. ## @seealso{mkpp, ppval, ppint} ## @end deftypefn
--- a/scripts/polynomial/ppint.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/ppint.m Mon May 04 21:50:57 2015 -0700 @@ -20,6 +20,7 @@ ## @deftypefn {Function File} {@var{ppi} =} ppint (@var{pp}) ## @deftypefnx {Function File} {@var{ppi} =} ppint (@var{pp}, @var{c}) ## Compute the integral of the piecewise polynomial struct @var{pp}. +## ## @var{c}, if given, is the constant of integration. ## @seealso{mkpp, ppval, ppder} ## @end deftypefn
--- a/scripts/polynomial/ppjumps.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/ppjumps.m Mon May 04 21:50:57 2015 -0700 @@ -19,6 +19,7 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {@var{jumps} =} ppjumps (@var{pp}) ## Evaluate the boundary jumps of a piecewise polynomial. +## ## If there are @math{n} intervals, and the dimensionality of @var{pp} is ## @math{d}, the resulting array has dimensions @code{[d, n-1]}. ## @seealso{mkpp}
--- a/scripts/polynomial/ppval.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/ppval.m Mon May 04 21:50:57 2015 -0700 @@ -19,11 +19,11 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {@var{yi} =} ppval (@var{pp}, @var{xi}) ## Evaluate the piecewise polynomial structure @var{pp} at the points @var{xi}. -## If @var{pp} describes a scalar polynomial function, the result is an -## array of the same shape as @var{xi}. -## Otherwise, the size of the result is @code{[pp.dim, length(@var{xi})]} if -## @var{xi} is a vector, or @code{[pp.dim, size(@var{xi})]} if it is a -## multi-dimensional array. +## +## If @var{pp} describes a scalar polynomial function, the result is an array +## of the same shape as @var{xi}. Otherwise, the size of the result is +## @code{[pp.dim, length(@var{xi})]} if @var{xi} is a vector, or +## @code{[pp.dim, size(@var{xi})]} if it is a multi-dimensional array. ## @seealso{mkpp, unmkpp, spline, pchip} ## @end deftypefn
--- a/scripts/polynomial/residue.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/residue.m Mon May 04 21:50:57 2015 -0700 @@ -23,6 +23,8 @@ ## @deftypefnx {Function File} {[@var{b}, @var{a}] =} residue (@var{r}, @var{p}, @var{k}, @var{e}) ## The first calling form computes the partial fraction expansion for the ## quotient of the polynomials, @var{b} and @var{a}. +## +## The quotient is defined as ## @tex ## $$ ## {B(s)\over A(s)} = \sum_{m=1}^M {r_m\over (s-p_m)^e_m} @@ -33,18 +35,18 @@ ## ## @example ## @group -## B(s) M r(m) N -## ---- = SUM ------------- + SUM k(i)*s^(N-i) -## A(s) m=1 (s-p(m))^e(m) i=1 +## B(s) M r(m) N +## ---- = SUM ------------- + SUM k(i)*s^(N-i) +## A(s) m=1 (s-p(m))^e(m) i=1 ## @end group ## @end example ## ## @end ifnottex ## @noindent -## where @math{M} is the number of poles (the length of the @var{r}, -## @var{p}, and @var{e}), the @var{k} vector is a polynomial of order @math{N-1} -## representing the direct contribution, and the @var{e} vector specifies -## the multiplicity of the m-th residue's pole. +## where @math{M} is the number of poles (the length of the @var{r}, @var{p}, +## and @var{e}), the @var{k} vector is a polynomial of order @math{N-1} +## representing the direct contribution, and the @var{e} vector specifies the +## multiplicity of the m-th residue's pole. ## ## For example, ## @@ -79,11 +81,11 @@ ## ## @end ifnottex ## -## The second calling form performs the inverse operation and computes -## the reconstituted quotient of polynomials, @var{b}(s)/@var{a}(s), -## from the partial fraction expansion; represented by the residues, -## poles, and a direct polynomial specified by @var{r}, @var{p} and -## @var{k}, and the pole multiplicity @var{e}. +## The second calling form performs the inverse operation and computes the +## reconstituted quotient of polynomials, @var{b}(s)/@var{a}(s), from the +## partial fraction expansion; represented by the residues, poles, and a direct +## polynomial specified by @var{r}, @var{p} and @var{k}, and the pole +## multiplicity @var{e}. ## ## If the multiplicity, @var{e}, is not explicitly specified the multiplicity is ## determined by the function @code{mpoles}.
--- a/scripts/polynomial/roots.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/roots.m Mon May 04 21:50:57 2015 -0700 @@ -17,19 +17,21 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} roots (@var{v}) +## @deftypefn {Function File} {} roots (@var{c}) ## -## For a vector @var{v} with @math{N} components, return -## the roots of the polynomial +## Compute the roots of the polynomial @var{c}. +## +## For a vector @var{c} with @math{N} components, return the roots of the +## polynomial ## @tex ## $$ -## v_1 z^{N-1} + \cdots + v_{N-1} z + v_N. +## c_1 x^{N-1} + \cdots + c_{N-1} x + c_N. ## $$ ## @end tex ## @ifnottex ## ## @example -## v(1) * z^(N-1) + @dots{} + v(N-1) * z + v(N) +## c(1) * x^(N-1) + @dots{} + c(N-1) * x + c(N) ## @end example ## ## @end ifnottex
--- a/scripts/polynomial/spline.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/spline.m Mon May 04 21:50:57 2015 -0700 @@ -24,18 +24,21 @@ ## ## When called with two arguments, return the piecewise polynomial @var{pp} ## that may be used with @code{ppval} to evaluate the polynomial at specific -## points. When called with a third input argument, @code{spline} evaluates -## the spline at the points @var{xi}. The third calling form @code{spline -## (@var{x}, @var{y}, @var{xi})} is equivalent to @code{ppval (spline -## (@var{x}, @var{y}), @var{xi})}. +## points. +## +## When called with a third input argument, @code{spline} evaluates the spline +## at the points @var{xi}. The third calling form +## @code{spline (@var{x}, @var{y}, @var{xi})} is equivalent to +## @code{ppval (spline (@var{x}, @var{y}), @var{xi})}. ## -## The variable @var{x} must be a vector of length @var{n}. @var{y} can be -## either a vector or array. If @var{y} is a vector it must have a length of -## either @var{n} or @code{@var{n} + 2}. If the length of @var{y} is -## @var{n}, then the "not-a-knot" end condition is used. If the length of -## @var{y} is @code{@var{n} + 2}, then the first and last values of the -## vector @var{y} are the values of the first derivative of the cubic spline -## at the endpoints. +## The variable @var{x} must be a vector of length @var{n}. +## +## @var{y} can be either a vector or array. If @var{y} is a vector it must +## have a length of either @var{n} or @code{@var{n} + 2}. If the length of +## @var{y} is @var{n}, then the "not-a-knot" end condition is used. If the +## length of @var{y} is @code{@var{n} + 2}, then the first and last values of +## the vector @var{y} are the values of the first derivative of the cubic +## spline at the endpoints. ## ## If @var{y} is an array, then the size of @var{y} must have the form ## @tex @@ -59,8 +62,8 @@ ## @ifnottex ## @code{@var{s1} * @var{s2} * @dots{} * @var{sk}} ## @end ifnottex -## and each row of this matrix is then treated separately. Note that this -## is exactly opposite to @code{interp1} but is done for @sc{matlab} +## and each row of this matrix is then treated separately. Note that this is +## exactly the opposite of @code{interp1} but is done for @sc{matlab} ## compatibility. ## ## @seealso{pchip, ppval, mkpp, unmkpp}
--- a/scripts/polynomial/splinefit.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/splinefit.m Mon May 04 21:50:57 2015 -0700 @@ -26,12 +26,10 @@ ## @deftypefnx {Function File} {@var{pp} =} splinefit (@dots{}, "constraints", @var{constraints}) ## ## Fit a piecewise cubic spline with breaks (knots) @var{breaks} to the -## noisy data, @var{x} and @var{y}. @var{x} is a vector, and @var{y} -## is a vector or N-D array. If @var{y} is an N-D array, then @var{x}(j) -## is matched to @var{y}(:,@dots{},:,j). +## noisy data, @var{x} and @var{y}. ## -## The fitted spline is returned as a piecewise polynomial, @var{pp}, and -## may be evaluated using @code{ppval}. +## @var{x} is a vector, and @var{y} is a vector or N-D array. If @var{y} is an +## N-D array, then @var{x}(j) is matched to @var{y}(:,@dots{},:,j). ## ## @var{p} is a positive integer defining the number of intervals along @var{x}, ## and @var{p}+1 is the number of breaks. The number of points in each interval @@ -47,19 +45,22 @@ ## data points. Three iterations of weighted least squares are performed. ## Weights are computed from previous residuals. The sensitivity of outlier ## identification is controlled by the property @var{beta}. The value of -## @var{beta} is stricted to the range, 0 < @var{beta} < 1. The default +## @var{beta} is restricted to the range, 0 < @var{beta} < 1. The default ## value is @var{beta} = 1/2. Values close to 0 give all data equal ## weighting. Increasing values of @var{beta} reduce the influence of ## outlying data. Values close to unity may cause instability or rank ## deficiency. ## +## The fitted spline is returned as a piecewise polynomial, @var{pp}, and +## may be evaluated using @code{ppval}. +## ## The splines are constructed of polynomials with degree @var{order}. ## The default is a cubic, @var{order}=3. A spline with P pieces has ## P+@var{order} degrees of freedom. With periodic boundary conditions ## the degrees of freedom are reduced to P. ## -## The optional property, @var{constaints}, is a structure specifying -## linear constraints on the fit. The structure has three fields, @qcode{"xc"}, +## The optional property, @var{constaints}, is a structure specifying linear +## constraints on the fit. The structure has three fields, @qcode{"xc"}, ## @qcode{"yc"}, and @qcode{"cc"}. ## ## @table @asis
--- a/scripts/polynomial/unmkpp.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/polynomial/unmkpp.m Mon May 04 21:50:57 2015 -0700 @@ -20,6 +20,7 @@ ## @deftypefn {Function File} {[@var{x}, @var{p}, @var{n}, @var{k}, @var{d}] =} unmkpp (@var{pp}) ## ## Extract the components of a piecewise polynomial structure @var{pp}. +## ## The components are: ## ## @table @asis @@ -27,11 +28,11 @@ ## Sample points. ## ## @item @var{p} -## Polynomial coefficients for points in sample interval. @code{@var{p} -## (@var{i}, :)} contains the coefficients for the polynomial over -## interval @var{i} ordered from highest to lowest. If @code{@var{d} > -## 1}, @code{@var{p} (@var{r}, @var{i}, :)} contains the coefficients for -## the r-th polynomial defined on interval @var{i}. +## Polynomial coefficients for points in sample interval. +## @code{@var{p} (@var{i}, :)} contains the coefficients for the polynomial +## over interval @var{i} ordered from highest to lowest. If +## @code{@var{d} > 1}, @code{@var{p} (@var{r}, @var{i}, :)} contains the +## coefficients for the r-th polynomial defined on interval @var{i}. ## ## @item @var{n} ## Number of polynomial pieces.
--- a/scripts/signal/arch_fit.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/arch_fit.m Mon May 04 21:50:57 2015 -0700 @@ -18,8 +18,10 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {[@var{a}, @var{b}] =} arch_fit (@var{y}, @var{x}, @var{p}, @var{iter}, @var{gamma}, @var{a0}, @var{b0}) -## Fit an ARCH regression model to the time series @var{y} using the -## scoring algorithm in @nospell{Engle's} original ARCH paper. The model is +## Fit an ARCH regression model to the time series @var{y} using the scoring +## algorithm in @nospell{Engle's} original ARCH paper. +## +## The model is ## ## @example ## @group @@ -30,21 +32,21 @@ ## ## @noindent ## in which @math{e(t)} is @math{N(0, h(t))}, given a time-series vector -## @var{y} up to time @math{t-1} and a matrix of (ordinary) regressors -## @var{x} up to @math{t}. The order of the regression of the residual -## variance is specified by @var{p}. +## @var{y} up to time @math{t-1} and a matrix of (ordinary) regressors @var{x} +## up to @math{t}. The order of the regression of the residual variance is +## specified by @var{p}. ## -## If invoked as @code{arch_fit (@var{y}, @var{k}, @var{p})} with a -## positive integer @var{k}, fit an ARCH(@var{k}, @var{p}) process, -## i.e., do the above with the @math{t}-th row of @var{x} given by +## If invoked as @code{arch_fit (@var{y}, @var{k}, @var{p})} with a positive +## integer @var{k}, fit an ARCH(@var{k}, @var{p}) process, i.e., do the above +## with the @math{t}-th row of @var{x} given by ## ## @example ## [1, y(t-1), @dots{}, y(t-k)] ## @end example ## ## Optionally, one can specify the number of iterations @var{iter}, the -## updating factor @var{gamma}, and initial values @math{a0} and -## @math{b0} for the scoring algorithm. +## updating factor @var{gamma}, and initial values @math{a0} and @math{b0} +## for the scoring algorithm. ## @end deftypefn ## Author: KH <Kurt.Hornik@wu-wien.ac.at>
--- a/scripts/signal/arch_rnd.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/arch_rnd.m Mon May 04 21:50:57 2015 -0700 @@ -18,9 +18,10 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} arch_rnd (@var{a}, @var{b}, @var{t}) -## Simulate an ARCH sequence of length @var{t} with AR -## coefficients @var{b} and CH coefficients @var{a}. I.e., the result -## @math{y(t)} follows the model +## Simulate an ARCH sequence of length @var{t} with AR coefficients @var{b} and +## CH coefficients @var{a}. +## +## The result @math{y(t)} follows the model ## @c Set example in small font to prevent overfull line ## ## @smallexample
--- a/scripts/signal/arma_rnd.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/arma_rnd.m Mon May 04 21:50:57 2015 -0700 @@ -18,7 +18,9 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} arma_rnd (@var{a}, @var{b}, @var{v}, @var{t}, @var{n}) -## Return a simulation of the ARMA model +## Return a simulation of the ARMA model. +## +## The ARMA model is defined by ## ## @example ## @group @@ -28,14 +30,14 @@ ## @end example ## ## @noindent -## in which @var{k} is the length of vector @var{a}, @var{l} is the -## length of vector @var{b} and @var{e} is Gaussian white noise with -## variance @var{v}. The function returns a vector of length @var{t}. +## in which @var{k} is the length of vector @var{a}, @var{l} is the length of +## vector @var{b} and @var{e} is Gaussian white noise with variance @var{v}. +## The function returns a vector of length @var{t}. ## -## The optional parameter @var{n} gives the number of dummy -## @var{x}(@var{i}) used for initialization, i.e., a sequence of length -## @var{t}+@var{n} is generated and @var{x}(@var{n}+1:@var{t}+@var{n}) -## is returned. If @var{n} is omitted, @var{n} = 100 is used. +## The optional parameter @var{n} gives the number of dummy @var{x}(@var{i}) +## used for initialization, i.e., a sequence of length @var{t}+@var{n} is +## generated and @var{x}(@var{n}+1:@var{t}+@var{n}) is returned. If @var{n} +## is omitted, @var{n} = 100 is used. ## @end deftypefn ## Author: FL <Friedrich.Leisch@ci.tuwien.ac.at>
--- a/scripts/signal/autoreg_matrix.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/autoreg_matrix.m Mon May 04 21:50:57 2015 -0700 @@ -18,12 +18,14 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} autoreg_matrix (@var{y}, @var{k}) -## Given a time series (vector) @var{y}, return a matrix with ones in the -## first column and the first @var{k} lagged values of @var{y} in the -## other columns. I.e., for @var{t} > @var{k}, @code{[1, -## @var{y}(@var{t}-1), @dots{}, @var{y}(@var{t}-@var{k})]} is the t-th row -## of the result. The resulting matrix may be used as a regressor matrix -## in autoregressions. +## Given a time series (vector) @var{y}, return a matrix with ones in the first +## column and the first @var{k} lagged values of @var{y} in the other columns. +## +## In other words, for @var{t} > @var{k}, +## @code{[1, @var{y}(@var{t}-1), @dots{}, @var{y}(@var{t}-@var{k})]} is the +## t-th row of the result. +## +## The resulting matrix may be used as a regressor matrix in autoregressions. ## @end deftypefn ## Author: KH <Kurt.Hornik@wu-wien.ac.at>
--- a/scripts/signal/bartlett.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/bartlett.m Mon May 04 21:50:57 2015 -0700 @@ -18,10 +18,10 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} bartlett (@var{m}) -## Return the filter coefficients of a Bartlett (triangular) window of -## length @var{m}. +## Return the filter coefficients of a Bartlett (triangular) window of length +## @var{m}. ## -## For a definition of the Bartlett window, see e.g., +## For a definition of the Bartlett window see, e.g., ## @nospell{A.V. Oppenheim & R. W. Schafer}, ## @cite{Discrete-Time Signal Processing}. ## @end deftypefn
--- a/scripts/signal/blackman.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/blackman.m Mon May 04 21:50:57 2015 -0700 @@ -27,7 +27,7 @@ ## @var{m}+1 with the last coefficient removed. The optional argument ## @qcode{"symmetric"} is equivalent to not specifying a second argument. ## -## For a definition of the Blackman window, see e.g., +## For a definition of the Blackman window, see, e.g., ## @nospell{A.V. Oppenheim & R. W. Schafer}, ## @cite{Discrete-Time Signal Processing}. ## @end deftypefn
--- a/scripts/signal/detrend.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/detrend.m Mon May 04 21:50:57 2015 -0700 @@ -24,13 +24,12 @@ ## If @var{x} is a matrix, @code{detrend (@var{x}, @var{p})} does the same ## for each column in @var{x}. ## -## The second argument is optional. If it is not specified, a value of 1 -## is assumed. This corresponds to removing a linear trend. +## The second argument @var{p} is optional. If it is not specified, a value of +## 1 is assumed. This corresponds to removing a linear trend. ## ## The order of the polynomial can also be given as a string, in which case -## @var{p} must be either @qcode{"constant"} (corresponds to -## @code{@var{p}=0}) or -## @qcode{"linear"} (corresponds to @code{@var{p}=1}). +## @var{p} must be either @qcode{"constant"} (corresponds to @code{@var{p}=0}) +## or @qcode{"linear"} (corresponds to @code{@var{p}=1}). ## @seealso{polyfit} ## @end deftypefn
--- a/scripts/signal/diffpara.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/diffpara.m Mon May 04 21:50:57 2015 -0700 @@ -23,14 +23,15 @@ ## ## The frequencies from @math{[2*pi*a/t, 2*pi*b/T]} are used for the ## estimation. If @var{b} is omitted, the interval -## @math{[2*pi/T, 2*pi*a/T]} is used. If both @var{b} and @var{a} are -## omitted then @math{a = 0.5 * sqrt (T)} and @math{b = 1.5 * sqrt (T)} -## is used, where @math{T} is the sample size. If @var{x} is a matrix, -## the differencing parameter of each column is estimated. +## @math{[2*pi/T, 2*pi*a/T]} is used. If both @var{b} and @var{a} are omitted +## then @math{a = 0.5 * sqrt (T)} and @math{b = 1.5 * sqrt (T)} is used, where +## @math{T} is the sample size. If @var{x} is a matrix, the differencing +## parameter of each column is estimated. ## -## The estimators for all frequencies in the intervals -## described above is returned in @var{dd}. The value of @var{d} is -## simply the mean of @var{dd}. +## The estimators for all frequencies in the intervals described above is +## returned in @var{dd}. +## +## The value of @var{d} is simply the mean of @var{dd}. ## ## Reference: @nospell{P.J. Brockwell & R.A. Davis}. @cite{Time Series: ## Theory and Methods}. Springer 1987.
--- a/scripts/signal/durbinlevinson.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/durbinlevinson.m Mon May 04 21:50:57 2015 -0700 @@ -20,13 +20,13 @@ ## @deftypefn {Function File} {} durbinlevinson (@var{c}, @var{oldphi}, @var{oldv}) ## Perform one step of the @nospell{Durbin-Levinson} algorithm. ## -## The vector @var{c} specifies the autocovariances @code{[gamma_0, @dots{}, -## gamma_t]} from lag 0 to @var{t}, @var{oldphi} specifies the -## coefficients based on @var{c}(@var{t}-1) and @var{oldv} specifies the -## corresponding error. +## The vector @var{c} specifies the autocovariances +## @code{[gamma_0, @dots{}, gamma_t]} from lag 0 to @var{t}, @var{oldphi} +## specifies the coefficients based on @var{c}(@var{t}-1) and @var{oldv} +## specifies the corresponding error. ## -## If @var{oldphi} and @var{oldv} are omitted, all steps from 1 to -## @var{t} of the algorithm are performed. +## If @var{oldphi} and @var{oldv} are omitted, all steps from 1 to @var{t} of +## the algorithm are performed. ## @end deftypefn ## Author: FL <Friedrich.Leisch@ci.tuwien.ac.at>
--- a/scripts/signal/fftconv.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/fftconv.m Mon May 04 21:50:57 2015 -0700 @@ -22,9 +22,9 @@ ## Convolve two vectors using the FFT for computation. ## ## @code{c = fftconv (@var{x}, @var{y})} returns a vector of length equal to -## @code{length (@var{x}) + length (@var{y}) - 1}. -## If @var{x} and @var{y} are the coefficient vectors of two polynomials, the -## returned value is the coefficient vector of the product polynomial. +## @code{length (@var{x}) + length (@var{y}) - 1}. If @var{x} and @var{y} +## are the coefficient vectors of two polynomials, the returned value is the +## coefficient vector of the product polynomial. ## ## The computation uses the FFT by calling the function @code{fftfilt}. If ## the optional argument @var{n} is specified, an N-point FFT is used.
--- a/scripts/signal/fftfilt.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/fftfilt.m Mon May 04 21:50:57 2015 -0700 @@ -19,18 +19,16 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} fftfilt (@var{b}, @var{x}) ## @deftypefnx {Function File} {} fftfilt (@var{b}, @var{x}, @var{n}) +## Filter @var{x} with the FIR filter @var{b} using the FFT. ## -## With two arguments, @code{fftfilt} filters @var{x} with the FIR filter -## @var{b} using the FFT. +## If @var{x} is a matrix, filter each column of the matrix. ## ## Given the optional third argument, @var{n}, @code{fftfilt} uses the -## overlap-add method to filter @var{x} with @var{b} using an N-point -## FFT@. The FFT size must be an even power of 2 and must be greater than -## or equal to the length of @var{b}. If the specified @var{n} does not -## meet these criteria, it is automatically adjusted to the nearest value -## that does. +## overlap-add method to filter @var{x} with @var{b} using an N-point FFT@. +## The FFT size must be an even power of 2 and must be greater than or equal to +## the length of @var{b}. If the specified @var{n} does not meet these +## criteria, it is automatically adjusted to the nearest value that does. ## -## If @var{x} is a matrix, filter each column of the matrix. ## @seealso{filter, filter2} ## @end deftypefn
--- a/scripts/signal/fftshift.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/fftshift.m Mon May 04 21:50:57 2015 -0700 @@ -19,12 +19,12 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} fftshift (@var{x}) ## @deftypefnx {Function File} {} fftshift (@var{x}, @var{dim}) -## Perform a shift of the vector @var{x}, for use with the @code{fft} -## and @code{ifft} functions, in order the move the frequency 0 to the -## center of the vector or matrix. +## Perform a shift of the vector @var{x}, for use with the @code{fft} and +## @code{ifft} functions, in order the move the frequency 0 to the center of +## the vector or matrix. ## -## If @var{x} is a vector of @math{N} elements corresponding to @math{N} -## time samples spaced by @nospell{@math{dt}}, then +## If @var{x} is a vector of @math{N} elements corresponding to @math{N} time +## samples spaced by @nospell{@math{dt}}, then ## @code{fftshift (fft (@var{x}))} corresponds to frequencies ## ## @example @@ -34,11 +34,12 @@ ## @noindent ## where @nospell{@math{df} = 1 / @math{dt}}. ## -## If @var{x} is a matrix, the same holds for rows and columns. If -## @var{x} is an array, then the same holds along each dimension. +## If @var{x} is a matrix, the same holds for rows and columns. If @var{x} +## is an array, then the same holds along each dimension. ## -## The optional @var{dim} argument can be used to limit the dimension -## along which the permutation occurs. +## The optional @var{dim} argument can be used to limit the dimension along +## which the permutation occurs. +## @seealso{ifftshift} ## @end deftypefn ## Author: Vincent Cautaerts <vincent@comf5.comm.eng.osaka-u.ac.jp>
--- a/scripts/signal/filter2.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/filter2.m Mon May 04 21:50:57 2015 -0700 @@ -19,9 +19,10 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {@var{y} =} filter2 (@var{b}, @var{x}) ## @deftypefnx {Function File} {@var{y} =} filter2 (@var{b}, @var{x}, @var{shape}) -## Apply the 2-D FIR filter @var{b} to @var{x}. If the argument -## @var{shape} is specified, return an array of the desired shape. -## Possible values are: +## Apply the 2-D FIR filter @var{b} to @var{x}. +## +## If the argument @var{shape} is specified, return an array of the desired +## shape. Possible values are: ## ## @table @asis ## @item @qcode{"full"} @@ -34,8 +35,8 @@ ## trim @var{x} after filtering so edge effects are no included. ## @end table ## -## Note this is just a variation on convolution, with the parameters -## reversed and @var{b} rotated 180 degrees. +## Note this is just a variation on convolution, with the parameters reversed +## and @var{b} rotated 180 degrees. ## @seealso{conv2} ## @end deftypefn
--- a/scripts/signal/freqz.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/freqz.m Mon May 04 21:50:57 2015 -0700 @@ -27,8 +27,9 @@ ## ## Return the complex frequency response @var{h} of the rational IIR filter ## whose numerator and denominator coefficients are @var{b} and @var{a}, -## respectively. The response is evaluated at @var{n} angular frequencies -## between 0 and +## respectively. +## +## The response is evaluated at @var{n} angular frequencies between 0 and ## @ifnottex ## 2*pi. ## @end ifnottex @@ -42,9 +43,8 @@ ## If @var{a} is omitted, the denominator is assumed to be 1 (this ## corresponds to a simple FIR filter). ## -## If @var{n} is omitted, a value of 512 is assumed. -## For fastest computation, @var{n} should factor into a small number of -## small primes. +## If @var{n} is omitted, a value of 512 is assumed. For fastest computation, +## @var{n} should factor into a small number of small primes. ## ## If the fourth argument, @qcode{"whole"}, is omitted the response is ## evaluated at frequencies between 0 and
--- a/scripts/signal/hamming.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/hamming.m Mon May 04 21:50:57 2015 -0700 @@ -27,7 +27,7 @@ ## @var{m}+1 with the last coefficient removed. The optional argument ## @qcode{"symmetric"} is equivalent to not specifying a second argument. ## -## For a definition of the Hamming window, see e.g., +## For a definition of the Hamming window see, e.g., ## @nospell{A.V. Oppenheim & R. W. Schafer}, ## @cite{Discrete-Time Signal Processing}. ## @end deftypefn
--- a/scripts/signal/hanning.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/hanning.m Mon May 04 21:50:57 2015 -0700 @@ -27,7 +27,7 @@ ## @var{m}+1 with the last coefficient removed. The optional argument ## @qcode{"symmetric"} is equivalent to not specifying a second argument. ## -## For a definition of the Hanning window, see e.g., +## For a definition of the Hanning window see, e.g., ## @nospell{A.V. Oppenheim & R. W. Schafer}, ## @cite{Discrete-Time Signal Processing}. ## @end deftypefn
--- a/scripts/signal/hurst.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/hurst.m Mon May 04 21:50:57 2015 -0700 @@ -19,8 +19,9 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} hurst (@var{x}) ## Estimate the Hurst parameter of sample @var{x} via the rescaled range -## statistic. If @var{x} is a matrix, the parameter is estimated for -## every single column. +## statistic. +## +## If @var{x} is a matrix, the parameter is estimated for every column. ## @end deftypefn ## Author: FL <Friedrich.Leisch@ci.tuwien.ac.at>
--- a/scripts/signal/ifftshift.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/ifftshift.m Mon May 04 21:50:57 2015 -0700 @@ -19,9 +19,11 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} ifftshift (@var{x}) ## @deftypefnx {Function File} {} ifftshift (@var{x}, @var{dim}) -## Undo the action of the @code{fftshift} function. For even length -## @var{x}, @code{fftshift} is its own inverse, but odd lengths differ -## slightly. +## Undo the action of the @code{fftshift} function. +## +## For even length @var{x}, @code{fftshift} is its own inverse, but odd lengths +## differ slightly. +## @seealso{fftshift} ## @end deftypefn ## Author: Vincent Cautaerts <vincent@comf5.comm.eng.osaka-u.ac.jp>
--- a/scripts/signal/periodogram.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/periodogram.m Mon May 04 21:50:57 2015 -0700 @@ -25,7 +25,6 @@ ## @deftypefnx {Function File} {[@var{Pxx}, @var{f}] =} periodogram (@var{x}, @var{win}, @var{nfft}, @var{Fs}) ## @deftypefnx {Function File} {[@var{Pxx}, @var{f}] =} periodogram (@dots{}, "@var{range}") ## @deftypefnx {Function File} {} periodogram (@dots{}) -## ## Return the periodogram (Power Spectral Density) of @var{x}. ## ## The possible inputs are:
--- a/scripts/signal/sinc.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/sinc.m Mon May 04 21:50:57 2015 -0700 @@ -18,6 +18,8 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} sinc (@var{x}) +## Compute the sinc function. +## ## Return ## @tex ## $ \sin (\pi x)/(\pi x)$.
--- a/scripts/signal/sinetone.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/sinetone.m Mon May 04 21:50:57 2015 -0700 @@ -18,11 +18,13 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} sinetone (@var{freq}, @var{rate}, @var{sec}, @var{ampl}) -## Return a sinetone of frequency @var{freq} with length of @var{sec} +## Return a sinetone of frequency @var{freq} with a length of @var{sec} ## seconds at sampling rate @var{rate} and with amplitude @var{ampl}. +## ## The arguments @var{freq} and @var{ampl} may be vectors of common size. ## -## Defaults are @var{rate} = 8000, @var{sec} = 1 and @var{ampl} = 64. +## The defaults are @var{rate} = 8000, @var{sec} = 1, and @var{ampl} = 64. +## @seealso{sinewave} ## @end deftypefn ## Author: FL <Friedrich.Leisch@ci.tuwien.ac.at>
--- a/scripts/signal/sinewave.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/sinewave.m Mon May 04 21:50:57 2015 -0700 @@ -21,8 +21,9 @@ ## Return an @var{m}-element vector with @var{i}-th element given by ## @code{sin (2 * pi * (@var{i}+@var{d}-1) / @var{n})}. ## -## The default value for @var{d} is 0 and the default value for @var{n} -## is @var{m}. +## The default value for @var{d} is 0 and the default value for @var{n} is +## @var{m}. +## @seealso{sinetone} ## @end deftypefn ## Author: AW <Andreas.Weingessel@ci.tuwien.ac.at>
--- a/scripts/signal/spectral_adf.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/spectral_adf.m Mon May 04 21:50:57 2015 -0700 @@ -20,15 +20,15 @@ ## @deftypefn {Function File} {} spectral_adf (@var{c}) ## @deftypefnx {Function File} {} spectral_adf (@var{c}, @var{win}) ## @deftypefnx {Function File} {} spectral_adf (@var{c}, @var{win}, @var{b}) -## Return the spectral density estimator given a vector of -## autocovariances @var{c}, window name @var{win}, and bandwidth, -## @var{b}. +## Return the spectral density estimator given a vector of autocovariances +## @var{c}, window name @var{win}, and bandwidth, @var{b}. ## ## The window name, e.g., @qcode{"triangle"} or @qcode{"rectangle"} is ## used to search for a function called @code{@var{win}_lw}. ## -## If @var{win} is omitted, the triangle window is used. If @var{b} is -## omitted, @code{1 / sqrt (length (@var{x}))} is used. +## If @var{win} is omitted, the triangle window is used. +## +## If @var{b} is omitted, @code{1 / sqrt (length (@var{x}))} is used. ## @seealso{spectral_xdf} ## @end deftypefn
--- a/scripts/signal/spectral_xdf.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/spectral_xdf.m Mon May 04 21:50:57 2015 -0700 @@ -20,14 +20,15 @@ ## @deftypefn {Function File} {} spectral_xdf (@var{x}) ## @deftypefnx {Function File} {} spectral_xdf (@var{x}, @var{win}) ## @deftypefnx {Function File} {} spectral_xdf (@var{x}, @var{win}, @var{b}) -## Return the spectral density estimator given a data vector @var{x}, -## window name @var{win}, and bandwidth, @var{b}. +## Return the spectral density estimator given a data vector @var{x}, window +## name @var{win}, and bandwidth, @var{b}. ## -## The window name, e.g., @qcode{"triangle"} or @qcode{"rectangle"} is -## used to search for a function called @code{@var{win}_sw}. +## The window name, e.g., @qcode{"triangle"} or @qcode{"rectangle"} is used to +## search for a function called @code{@var{win}_sw}. ## -## If @var{win} is omitted, the triangle window is used. If @var{b} is -## omitted, @code{1 / sqrt (length (@var{x}))} is used. +## If @var{win} is omitted, the triangle window is used. +## +## If @var{b} is omitted, @code{1 / sqrt (length (@var{x}))} is used. ## @seealso{spectral_adf} ## @end deftypefn
--- a/scripts/signal/spencer.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/spencer.m Mon May 04 21:50:57 2015 -0700 @@ -18,8 +18,7 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} spencer (@var{x}) -## Return Spencer's 15 point moving average of each column of -## @var{x}. +## Return Spencer's 15 point moving average of each column of @var{x}. ## @end deftypefn ## Author: FL <Friedrich.Leisch@ci.tuwien.ac.at>
--- a/scripts/signal/stft.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/stft.m Mon May 04 21:50:57 2015 -0700 @@ -47,14 +47,13 @@ ## @var{win_size} = 80, @var{inc} = 24, @var{num_coef} = 64, and ## @var{win_type} = 1. ## -## @code{@var{y} = stft (@var{x}, @dots{})} returns the absolute values -## of the Fourier coefficients according to the @var{num_coef} positive -## frequencies. +## @code{@var{y} = stft (@var{x}, @dots{})} returns the absolute values of the +## Fourier coefficients according to the @var{num_coef} positive frequencies. ## -## @code{[@var{y}, @var{c}] = stft (@code{x}, @dots{})} returns the -## entire STFT-matrix @var{y} and a 3-element vector @var{c} containing -## the window size, increment, and window type, which is needed by the -## @code{synthesis} function. +## @code{[@var{y}, @var{c}] = stft (@code{x}, @dots{})} returns the entire +## STFT-matrix @var{y} and a 3-element vector @var{c} containing the window +## size, increment, and window type, which is needed by the @code{synthesis} +## function. ## @seealso{synthesis} ## @end deftypefn
--- a/scripts/signal/synthesis.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/synthesis.m Mon May 04 21:50:57 2015 -0700 @@ -19,8 +19,7 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {@var{x} =} synthesis (@var{y}, @var{c}) ## Compute a signal from its short-time Fourier transform @var{y} and a -## 3-element vector @var{c} specifying window size, increment, and -## window type. +## 3-element vector @var{c} specifying window size, increment, and window type. ## ## The values @var{y} and @var{c} can be derived by ##
--- a/scripts/signal/unwrap.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/unwrap.m Mon May 04 21:50:57 2015 -0700 @@ -21,8 +21,10 @@ ## @deftypefnx {Function File} {@var{b} =} unwrap (@var{x}, @var{tol}) ## @deftypefnx {Function File} {@var{b} =} unwrap (@var{x}, @var{tol}, @var{dim}) ## -## Unwrap radian phases by adding multiples of 2*pi as appropriate to -## remove jumps greater than @var{tol}. @var{tol} defaults to pi. +## Unwrap radian phases by adding multiples of 2*pi as appropriate to remove +## jumps greater than @var{tol}. +## +## @var{tol} defaults to pi. ## ## Unwrap will work along the dimension @var{dim}. If @var{dim} ## is unspecified it defaults to the first non-singleton dimension.
--- a/scripts/signal/yulewalker.m Mon May 04 14:22:02 2015 -0700 +++ b/scripts/signal/yulewalker.m Mon May 04 21:50:57 2015 -0700 @@ -18,11 +18,11 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {[@var{a}, @var{v}] =} yulewalker (@var{c}) -## Fit an AR (p)-model with Yule-Walker estimates given a vector @var{c} -## of autocovariances @code{[gamma_0, @dots{}, gamma_p]}. +## Fit an AR (p)-model with Yule-Walker estimates given a vector @var{c} of +## autocovariances @code{[gamma_0, @dots{}, gamma_p]}. ## -## Returns the AR coefficients, @var{a}, and the variance of white -## noise, @var{v}. +## Returns the AR coefficients, @var{a}, and the variance of white noise, +## @var{v}. ## @end deftypefn ## Author: FL <Friedrich.Leisch@ci.tuwien.ac.at>