This is Info file octave.info, produced by Makeinfo version 1.67 from the input file /ade-src/fsf/octave/doc/interpreter/octave.texi. START-INFO-DIR-ENTRY * Octave: (octave). Interactive language for numerical computations. END-INFO-DIR-ENTRY Copyright (C) 1996 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: Control Theory, Next: Signal Processing, Prev: Quadrature, Up: Top Control Theory ************** - Function File: abcddim (A, B, C, D) Check for compatibility of the dimensions of the matrices defining the linear system [A, B, C, D] corresponding to dx/dt = a x + b u y = c x + d u or a similar discrete-time system. If the matrices are compatibly dimensioned, then `abcddim' returns N = number of system states, M = number of system inputs, and P = number of system outputs. Otherwise `abcddim' returns N = M = P = -1. - Function File: are (A, B, C, OPT) Returns the solution, X, of the algebraic Riccati equation a' x + x a - x b x + c = 0 for identically dimensioned square matrices A, B, C. If B (C) is not square, then the function attempts to use `B*B'' (`C'*C') instead. Solution method: apply Laub's Schur method (IEEE Transactions on Automatic Control, 1979) to the appropriate Hamiltonian matrix. OPT is an option passed to the eigenvalue balancing routine. Default is `"B"'. - Function File: c2d (A, B, T) Converts the continuous time system described by: dx/dt = a x + b u into a discrete time equivalent model x[k+1] = Ad x[k] + Bd u[k] via the matrix exponential assuming a zero-order hold on the input and sample time T. - Function File: dare (A, B, C, R, OPT) Returns the solution, X of the discrete-time algebraic Riccati equation a' x a - x + a' x b (r + b' x b)^(-1) b' x a + c = 0 for matrices with dimensions: A: N by N B: N by M C: N by N, symmetric positive semidefinite R: M by M, symmetric positive definite (invertible) If C is not square, then the function attempts to use `C'*C' instead. Solution method: Laub's Schur method (IEEE Transactions on Automatic Control, 1979) is applied to the appropriate symplectic matrix. See also: Ran and Rodman, `Stable Hermitian Solutions of Discrete Algebraic Riccati Equations', Mathematics of Control, Signals and Systems, Volume 5, Number 2 (1992). OPT is an option passed to the eigenvalue balancing routine. The default is `"B"'. - Function File: dgram (A, B) Returns the discrete controllability and observability gramian for the discrete time system described by x[k+1] = A x[k] + B u[k] y[k] = C x[k] + D u[k] `dgram (A, B)' returns the discrete controllability gramian and `dgram (A', C')' returns the observability gramian. - Function File: dlqe (A, G, C, SIGW, SIGV [, Z]) Linear quadratic estimator (Kalman filter) design for the discrete time system x[k+1] = A x[k] + B u[k] + G w[k] y[k] = C x[k] + D u[k] + w[k] where W, V are zero-mean gaussian noise processes with respective intensities `SIGW = cov (W, W)' and `SIGV = cov (V, V)'. If specified, Z is `cov (W, V)'. Otherwise `cov (W, V) = 0'. The observer structure is z[k+1] = A z[k] + B u[k] + k(y[k] - C z[k] - D u[k]) Returns: L is the observer gain, `(A - A L C)' is stable. M is the Ricatti equation solution. P is the estimate error covariance after the measurement update. E are the closed loop poles of `(A - A L C)'. - Function File: dlqr (A, B, Q, R [, Z]) Linear quadratic regulator design for the discrete time system x[k+1] = A x[k] + B u[k] to minimize the cost functional J = Sum [ x' Q x + u' R u ], Z omitted or J = Sum [ x' Q x + u' R u +2 x' Z u ], Z included Returns: K is the state feedback gain, `(A - B K)' is stable. P is the solution of algebraic Riccati equation. E are the closed loop poles of (A - B K). - Function File: dlyap (A, B) Solve the discrete-time Lyapunov equation a x a' - x + b = 0 for square matrices A, B. If B is not square, then the function attempts to solve either a x a' - x + b b' = 0 or a' x a - x + b' b = 0 whichever is appropriate. Uses Schur decomposition method as in Kitagawa, International Journal of Control (1977); column-by-column solution method as suggested in Hammarling, IMA Journal of Numerical Analysis, (1982). - Function File: is_controllable (A, B, TOL) If the pair (a, b) is controllable, then return value 1. Otherwise, returns a value of 0. TOL is a roundoff parameter, set to `2*eps' if omitted. Currently just constructs the controllability matrix and checks rank. A better method is as follows (Boley and Golub, Systems and Control Letters, 1984): Controllability is determined by applying Arnoldi iteration with complete re-orthogonalization to obtain an orthogonal basis of the Krylov subspace n-1 span ([b, a*b, ..., a^ *b]). - Function File: is_observable (A, C, TOL) Returns 1 if the pair `(a, c)' is observable. Otherwise, returns a value of 0. - Function File: lqe (A, G, C, SIGW, SIGV, Z) [k, p, e] = lqe (a, g, c, sigw, sigv, z) Linear quadratic estimator (Kalman filter) design for the continuous time system dx -- = a x + b u dt y = c x + d u where W, V are zero-mean gaussian noise processes with respective intensities sigw = cov (w, w) sigv = cov (v, v) Z (if specified) is the cross-covariance `cov (W, V)'; the default value is `cov (W, V) = 0'. Observer structure is `dz/dt = A z + B u + k (y - C z - D u)' returns: K is observer gain: `(A - K C)' is stable. P is solution of algebraic Riccati equation. E is the vector of closed loop poles of `(A - K C)'. - Function File: lqr (A, B, Q, R, Z) - Function File: [K, P, E] = lqr (A, B, Q, R, Z) Linear quadratic regulator design for the continuous time system dx -- = A x + B u dt to minimize the cost functional infinity / J = | x' Q x + u' R u / t=0 Z omitted or infinity / J = | x' Q x + u' R u + 2 x' Z u / t=0 Z included Returns: K is state feedback gain: `(A - B K)' is stable. P is the stabilizing solution of appropriate algebraic Riccati equation. E is the vector of the closed loop poles of `(A - B K)'. - Function File: lyap (A, B, C) Solve the Lyapunov (or Sylvester) equation via the Bartels-Stewart algorithm (Communications of the ACM, 1972). If `(a, b, c)' are specified, then `lyap' returns the solution of the Sylvester equation a x + x b + c = 0 If only `(a, b)' are specified, then `lyap' returns the solution of the Lyapunov equation a' x + x a + b = 0 If B is not square, then `lyap' returns the solution of either a' x + x a + b' b = 0 or a x + x a' + b b' = 0 whichever is appropriate. Solves by using the Bartels-Stewart algorithm (1972). - Function File: tzero (A, B, C, D, BAL) Compute the transmission zeros of [A, B, C, D]. BAL = balancing option (see balance); default is `"B"'. Needs to incorporate `mvzero' algorithm to isolate finite zeros; see Hodel, `Computation of System Zeros with Balancing', Linear Algebra and its Applications, July 1993.  File: octave.info, Node: Signal Processing, Next: Sets, Prev: Control Theory, Up: Top Signal Processing ***************** I hope that someday Octave will include more signal processing functions. If you would like to help improve Octave in this area, please contact `bug-octave@bevo.che.wisc.edu'. - 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. - Function: fft (A [, N]) Compute the FFT of A using subroutines from FFTPACK. If A is a matrix, `fft' computes the FFT for each column of A. If called with two arguments, N is expected to be an integer specifying the number of elements of A to use. If A is a matrix, N specifies the number of rows of A to use. If N is larger than the size of A, A is resized and padded with zeros. - Loadable Function: ifft (A [, N]) Compute the inverse FFT of A using subroutines from FFTPACK. If A is a matrix, `fft' computes the inverse FFT for each column of A. If called with two arguments, N is expected to be an integer specifying the number of elements of A to use. If A is a matrix, N specifies the number of rows of A to use. If N is larger than the size of A, A is resized and padded with zeros. - Loadable Function: fft2 (A [, N [, M]]) Compute the two dimensional FFT of A. The optional arguments N and M 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. - Loadable Function: ifft2 (A [, N [, M]]) Compute the two dimensional inverse FFT of A. The optional arguments N and M 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. - Built-in Function: fftconv (A, B, N) This function returns the convolution of the vectors A and B, a vector with length equal to the `length (a) + length (b) - 1'. If A and B 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. - 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. - Loadable Function: y = filter (B, A, X) This function returns 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. An equivalent form of this 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). 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 - Loadable Function: [Y, SF] = filter (B, A, X, SI) This is the same as the `filter' function described above, except that SI 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 set, the initial state vector is set to all zeros. - Function File: freqz Compute the frequency response of a filter. `[H, W] = freqz (B)' returns the complex frequency response H of the FIR filter with coefficients B. The response is evaluated at 512 angular frequencies between 0 and pi. The output value W is a vector containing the 512 frequencies. `[H, W] = freqz (B, A)' returns the complex frequency response of the rational IIR filter whose numerator has coefficients B and denominator coefficients A. `[H, W] = freqz (B, A, N)' returns the response evaluated at N angular frequencies. For fastest computation n should factor into a small number of small primes. `[H, W] = freqz (B, A, N, "whole")' evaluates the response at n frequencies between 0 and 2*pi. - Function File: sinc (X) Returns sin(pi*x)/(pi*x).  File: octave.info, Node: Sets, Next: Statistics, Prev: Signal Processing, Up: Top Sets **** Octave has a limited set of functions for managing sets of data, where a set is defined as a collection unique elements. - Function File: create_set (X) Given a matrix or vector of values, the function `create_set' returns a row vector containing unique values, sorted in ascending order. For example, create_set ([ 1, 2; 3, 4; 4, 2 ]) returns the vector [ 1, 2, 3, 4 ] - Function File: union (X, Y) Return the set of elements that are in either of the sets X and Y. For example, union ([ 1, 2, 3 ], [ 2, 3, 5 ]) returns the vector [ 1, 2, 5 ] - Function File: intersection (X, Y) Return the set of elements that are in both sets X and Y. - Function File: complement (X, Y) Returns the elements of set Y that are not in set X. For example, complement ([ 1, 2, 3 ], [ 2, 3, 5 ]) returns the value `5'.  File: octave.info, Node: Statistics, Next: Plotting, Prev: Sets, Up: Top Statistics ********** I hope that someday Octave will include more statistics functions. If you would like to help improve Octave in this area, please contact `bug-octave@bevo.che.wisc.edu'. - Function File: mean (X) If X is a vector, compute the mean of the elements of 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. - Function File: median (X) If X is a vector, compute the median value of the elements of X. 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. - Function File: std (X) If X is a vector, compute the standard deviation of the elements of X. std (x) = sqrt (sumsq (x - mean (x)) / (n - 1)) If X is a matrix, compute the standard deviation for each column and return them in a row vector. - Function File: cov (X [, Y]) If each row of X and Y is an observation and each column is a variable, 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. If called with one argument, compute `cov (X, X)'. - Function File: corrcoef (X [, Y]) If each row of X and Y is an observation and each column is a variable, the (I,J)-th entry of `corrcoef (X, Y)' is the correlation between the I-th variable in X and the J-th variable in Y. If called with one argument, compute `corrcoef (X, X)'. - Function File: kurtosis (X) If X is a vector of length N, return the kurtosis kurtosis (x) = N^(-1) std(x)^(-4) sum ((x - mean(x)).^4) - 3 of X. If X is a matrix, return the row vector containing the kurtosis of each column. - Function File: mahalanobis (X, Y) Returns 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: skewness (X) If X is a vector of length N, return the skewness skewness (x) = N^(-1) std(x)^(-3) sum ((x - mean(x)).^3) of X. If X is a matrix, return the row vector containing the skewness of each column.  File: octave.info, Node: Plotting, Next: Image Processing, Prev: Statistics, Up: Top Plotting ******** All of Octave's plotting functions use `gnuplot' to handle the actual graphics. There are two low-level functions, `gplot' and `gsplot', that behave almost exactly like the corresponding `gnuplot' functions `plot' and `splot'. A number of other higher level plotting functions, patterned after the graphics functions found in MATLAB version 3.5, are also available. These higher level functions are all implemented in terms of the two low-level plotting functions. * Menu: * Two-Dimensional Plotting:: * Three-Dimensional Plotting:: * Multiple Plots on One Page:: * Miscellaneous Plotting Functions::  File: octave.info, Node: Two-Dimensional Plotting, Next: Three-Dimensional Plotting, Prev: Plotting, Up: Plotting Two-Dimensional Plotting ======================== - Command: gplot RANGES EXPRESSION USING TITLE STYLE Generate a 2-dimensional plot. The RANGES, USING, TITLE, and STYLE arguments are optional, and the USING, TITLE and STYLE qualifiers may appear in any order after the expression. You may plot multiple expressions with a single command by separating them with commas. Each expression may have its own set of qualifiers. The optional item RANGES has the syntax [ x_lo : x_up ] [ y_lo : y_up ] and may be used to specify the ranges for the axes of the plot, independent of the actual range of the data. The range for the y axes and any of the individual limits may be omitted. A range `[:]' indicates that the default limits should be used. This normally means that a range just large enough to include all the data points will be used. The expression to be plotted must not contain any literal matrices (e.g. `[ 1, 2; 3, 4 ]') since it is nearly impossible to distinguish a plot range from a matrix of data. See the help for `gnuplot' for a description of the syntax for the optional items. By default, the `gplot' command plots the second column of a matrix versus the first. If the matrix only has one column, it is taken as a vector of y-coordinates and the x-coordinate is taken as the element index, starting with zero. For example, gplot rand (100,1) with linespoints will plot 100 random values and connect them with lines. When `gplot' is used to plot a column vector, the indices of the elements are taken as x values. If there are more than two columns, you can choose which columns to plot with the USING qualifier. For example, given the data x = (-10:0.1:10)'; data = [x, sin(x), cos(x)]; the command gplot [-11:11] [-1.1:1.1] \ data with lines, data using 1:3 with impulses will plot two lines. The first line is generated by the command `data with lines', and is a graph of the sine function over the range -10 to 10. The data is taken from the first two columns of the matrix because columns to plot were not specified with the USING qualifier. The clause `using 1:3' in the second part of this plot command specifies that the first and third columns of the matrix `data' should be taken as the values to plot. In this example, the ranges have been explicitly specified to be a bit larger than the actual range of the data so that the curves do not touch the border of the plot. - Command: set OPTIONS - Command: show OPTIONS - Command: replot OPTIONS In addition to the basic plotting commands, the whole range of `set' and `show' commands from `gnuplot' are available, as is `replot'. The `set' and `show' commands allow you to set and show `gnuplot' parameters. For more information about the set and show commands, see the `gnuplot' user's guide (also available on line if you run `gnuplot' directly, instead of running it from Octave). The `replot' command allows you to force the plot to be redisplayed. This is useful if you have changed something about the plot, such as the title or axis labels. The `replot' command also accepts the same arguments as `gplot' or `gsplot' (except for data ranges) so you can add additional lines to existing plots. For example, set term tek40 set output "/dev/plotter" set title "sine with lines and cosine with impulses" replot "sin (x) w l" will change the terminal type for plotting, add a title to the current plot, add a graph of sin (x) to the plot, and force the new plot to be sent to the plot device. This last step is normally required in order to update the plot. This default is reasonable for slow terminals or hardcopy output devices because even when you are adding additional lines with a replot command, gnuplot always redraws the entire plot, and you probably don't want to have a completely new plot generated every time something as minor as an axis label changes. - Built-in Variable: automatic_replot You can tell Octave to redisplay the plot each time anything about it changes by setting the value of the builtin variable `automatic_replot' to a nonzero value. Since this is fairly inefficient, the default value is 0. Note that NaN values in the plot data are automatically omitted, and Inf values are converted to a very large value before calling gnuplot. The MATLAB-style two-dimensional plotting commands are: - Function File: plot (ARGS) This function produces two-dimensional plots. Many different combinations of arguments are possible. The simplest form is plot (y) where the argument is taken as the set of Y coordinates and the X coordinates are taken to be the indices of the elements, starting with 1. If more than one argument is given, they are interpreted as plot (x [, y] [, fmt] ...) where Y and FMT are optional, and any number of argument sets may appear. The X and Y values are interpreted as follows: * If a single data argument is supplied, it is taken as the set of Y coordinates and the X coordinates are taken to be the indices of the elements, starting with 1. * If the first argument is a vector and the second is a matrix, the the vector is plotted versus the columns (or rows) of the matrix. (using whichever combination matches, with columns tried first.) * If the first argument is a matrix and the second is a vector, the the columns (or rows) of the matrix are plotted versus the vector. (using whichever combination matches, with columns tried first.) * If both arguments are vectors, the elements of Y are plotted versus the elements of X. * If both arguments are matrices, the columns of Y are plotted versus the columns of X. In this case, both matrices must have the same number of rows and columns and no attempt is made to transpose the arguments to make the number of rows match. If both arguments are scalars, a single point is plotted. The FMT argument, if present is interpreted as follows. If FMT is missing, the default gnuplot line style is assumed. `-' Set lines plot style (default). `.' Set dots plot style. `@' Set points plot style. `-@' Set linespoints plot style. `^' Set impulses plot style. `L' Set steps plot style. `#' Set boxes plot style. `~' Set errorbars plot style. `#~' Set boxerrorbars plot style. `n' Interpreted as the plot color if N is an integer in the range 1 to 6. `nm' If NM is a two digit integer and M is an integer in the range 1 to 6, M is interpreted as the point style. This is only valid in combination with the `@' or `-@' specifiers. `c' If C is one of "R", "G", "B", "M", "C", or "W", it is interpreted as the plot color (red, green, blue, magenta, cyan, or white). `+' `*' `o' `x' Used in combination with the points or linespoints styles, set the point style. The color line styles have the following meanings on terminals that support color. Number Gnuplot colors (lines)points style 1 red * 2 green + 3 blue o 4 magenta x 5 cyan house 6 brown there exists Here are some plot examples: plot (x, y, "@12", x, y2, x, y3, "4", x, y4, "+") This command will plot Y with points of type 2 (displayed as `+') and color 1 (red), Y2 with lines, Y3 with lines of color 4 (magenta) and Y4 with points displayed as `+'. plot (b, "*") This command will plot the data in B will be plotted with points displayed as `*'. - Function File: hold ARGS Tell Octave to `hold' the current data on the plot when executing subsequent plotting commands. This allows you to execute a series of plot commands and have all the lines end up on the same figure. The default is for each new plot command to clear the plot device first. For example, the command hold on turns the hold state on. An argument of `off' turns the hold state off, and `hold' with no arguments toggles the current hold state. - Function File: ishold Returns 1 if the next line will be added to the current plot, or 0 if the plot device will be cleared before drawing the next line. - Function File: loglog (ARGS) Make a two-dimensional plot using log scales for both axes. See the description of `plot' above for a description of the arguments that `loglog' will accept. - Function File: semilogx (ARGS) Make a two-dimensional plot using a log scale for the X axis. See the description of `plot' above for a description of the arguments that `semilogx' will accept. - Function File: semilogy (ARGS) Make a two-dimensional plot using a log scale for the Y axis. See the description of `plot' above for a description of the arguments that `semilogy' will accept. - Function File: contour (Z, N, X, Y) Make a contour plot of the three-dimensional surface described by Z. Someone needs to improve `gnuplot''s contour routines before this will be very useful. - Function File: polar (THETA, RHO) Make a two-dimensional plot given polar the coordinates THETA and RHO.  File: octave.info, Node: Three-Dimensional Plotting, Next: Multiple Plots on One Page, Prev: Two-Dimensional Plotting, Up: Plotting Three-Dimensional Plotting ========================== - Command: gsplot RANGES EXPRESSION USING TITLE STYLE Generate a 3-dimensional plot. The RANGES, USING, TITLE, and STYLE arguments are optional, and the USING, TITLE and STYLE qualifiers may appear in any order after the expression. You may plot multiple expressions with a single command by separating them with commas. Each expression may have its own set of qualifiers. The optional item RANGES has the syntax [ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ] and may be used to specify the ranges for the axes of the plot, independent of the actual range of the data. The range for the y and z axes and any of the individual limits may be omitted. A range `[:]' indicates that the default limits should be used. This normally means that a range just large enough to include all the data points will be used. The expression to be plotted must not contain any literal matrices (e.g. `[ 1, 2; 3, 4 ]') since it is nearly impossible to distinguish a plot range from a matrix of data. See the help for `gnuplot' for a description of the syntax for the optional items. By default, the `gsplot' command plots each column of the expression as the z value, using the row index as the x value, and the column index as the y value. The indices are counted from zero, not one. For example, gsplot rand (5, 2) will plot a random surface, with the x and y values taken from the row and column indices of the matrix. If parametric plotting mode is set (using the command `set parametric', then `gsplot' takes the columns of the matrix three at a time as the x, y and z values that define a line in three space. Any extra columns are ignored, and the x and y values are expected to be sorted. For example, with `parametric' set, it makes sense to plot a matrix like 1 1 3 2 1 6 3 1 9 1 2 2 2 2 5 3 2 8 1 3 1 2 3 4 3 3 7 but not `rand (5, 30)'. The MATLAB-style three-dimensional plotting commands are: - Function File: mesh (X, Y, Z) Plot a mesh given matrices `x', and Y from `meshdom' and a matrix Z corresponding to the X and Y coordinates of the mesh. - Function File: meshdom (X, Y) Given vectors of X and Y coordinates, return two matrices corresponding to the X and Y coordinates of the mesh. See the file `sombrero.m' for an example of using `mesh' and `meshdom'. - Function File: [XX, YY] = meshgrid (X, Y) Given vectors of X and Y coordinates, return two matrices corresponding to the X and Y coordinates of a mesh. The rows of XX are copies of X, and the columns of YY are copies of Y. `[XX, YY] = meshgrid (X)' is an abbreviation for `[XX, YY] = meshgrid (X, X)'. - Built-in Variable: gnuplot_binary The name of the program invoked by the plot command. The default value is `"gnuplot"'. *Note Installation::. - Built-in Variable: gnuplot_has_frames If the value of this variable is nonzero, Octave assumes that your copy of gnuplot has support for multiple frames that is included in recent 3.6beta releases. It's initial value is determined by configure, but it can be changed in your startup script or at the command line in case configure got it wrong, or if you upgrade your gnuplot installation. - Built-in Variable: gnuplot_has_multiplot If the value of this variable is nonzero, Octave assumes that your copy of gnuplot has the multiplot support that is included in recent 3.6beta releases. It's initial value is determined by configure, but it can be changed in your startup script or at the command line in case configure got it wrong, or if you upgrade your gnuplot installation.  File: octave.info, Node: Multiple Plots on One Page, Next: Miscellaneous Plotting Functions, Prev: Three-Dimensional Plotting, Up: Plotting Multiple Plots on One Page ========================== The following functions all require a version of `gnuplot' that supports the multiplot feature. - Function File: mplot (X, Y) - Function File: mplot (X, Y, FMT) - Function File: mplot (X1, Y1, X2, Y2) This is a modified version of `plot()' to work with the multiplot version of `gnuplot' to plot multiple plots per page. This plot version automatically advances to the next subplot position after each set of arguments are processed. See command PLOT() for the various options to this command as this is just mulitplot version of the same command. - Function File: multiplot (XN, YN) Sets and resets multiplot mode. If the arguments are non-zero, `multiplot' will set up multiplot mode with XN, YN subplots along the X and Y axes. If both arguments are zero, `multiplot' closes multiplot mode. - Function File: oneplot () If in multiplot mode, switches to single plot mode. - Function File: subplot (ROWS, COLS, INDEX) - Function File: subplot (RCN) Sets `gnuplot' in multiplot mode and plots in location given by index (there are COLS by ROWS subwindows). Input: ROWS Number of rows in subplot grid. COLUMNS Number of columns in subplot grid. INDEX Index of subplot where to make the next plot. If only one argument is supplied, then it must be a three digit value specifying the location in digits 1 (rows) and 2 (columns) and the plot index in digit 3. The plot index runs row-wise. First all the columns in a row are filled and then the next row is filled. For example, a plot with 4 by 2 grid will have plot indices running as follows: +-------+-------+-------+-------+ | | | | | | 1 | 2 | 3 | 4 | | | | | | +-------+-------+-------+-------+ | | | | | | 5 | 6 | 7 | 8 | | | | | | +-------+-------+-------+-------+ - Function File: subwindow (XN, YN) Sets the subwindow position in multiplot mode for the next plot. The multiplot mode has to be previously initialized using the `multiplot()' command, otherwise this command just becomes an alias to MULTIPLOT() - Function File: top_title (STRING) - Function File: bottom_title (STRING) Makes a title with text STRING at the top (bottom) of the plot. - Function File: plot_border (...) Multiple arguments allowed to specify the sides on which the border is shown. Allowed arguments include: "blank", "BLANK", "b", "B", => No borders displayed "all", "ALL", "a", "A", => All borders displayed "north", "NORTH", "n", "N", => North Border "south", "SOUTH", "s", "S", => South Border "east", "EAST", "e", "E", => East Border "west", "WEST", "w", "W", => West Border Without any arguments, turns borders off.  File: octave.info, Node: Miscellaneous Plotting Functions, Prev: Multiple Plots on One Page, Up: Plotting Miscellaneous Plotting Functions ================================ - Function File: bar (X, Y) Given two vectors of x-y data, `bar' produces a bar graph. If only one argument is given, it is taken as a vector of y-values and the x coordinates are taken to be the indices of the elements. If two output arguments are specified, the data are generated but not plotted. For example, bar (x, y); and [xb, yb] = bar (x, y); plot (xb, yb); are equivalent. - Function File: grid For two-dimensional plotting, force the display of a grid on the plot. - Function File: stairs (X, Y) Given two vectors of x-y data, bar produces a `stairstep' plot. If only one argument is given, it is taken as a vector of y-values and the x coordinates are taken to be the indices of the elements. If two output arguments are specified, the data are generated but not plotted. For example, stairs (x, y); and [xs, ys] = stairs (x, y); plot (xs, ys); are equivalent. - Function File: title (STRING) Specify a title for the plot. If you already have a plot displayed, use the command `replot' to redisplay it with the new title. - Function File: xlabel (STRING) - Function File: ylabel (STRING) - Function File: zlabel (STRING) Specify x, y, and z axis labels for the plot. If you already have a plot displayed, use the command `replot' to redisplay it with the new labels. - Function File: sombrero (N) Display a classic three-dimensional mesh plot. The parameter N allows you to increase the resolution. - Function File: clearplot - Function File: clg Clear the plot window and any titles or axis labels. The name `clg' is aliased to `clearplot' for compatibility with MATLAB. The commands `gplot clear', `gsplot clear', and `replot clear' are equivalent to `clearplot'. (Previously, commands like `gplot clear' would evaluate `clear' as an ordinary expression and clear all the visible variables.) - Function File: closeplot Close stream to the `gnuplot' subprocess. If you are using X11, this will close the plot window. - Function File: purge_tmp_files Delete the temporary files created by the plotting commands. Octave creates temporary data files for `gnuplot' and then sends commands to `gnuplot' through a pipe. Octave will delete the temporary files on exit, but if you are doing a lot of plotting you may want to clean up in the middle of a session. A future version of Octave will eliminate the need to use temporary files to hold the plot data. - Function File: axis (LIMITS) Sets the axis limits for plots. The argument LIMITS should be a 2, 4, or 6 element vector. The first and second elements specify the lower and upper limits for the x axis. The third and fourth specify the limits for the y axis, and the fifth and sixth specify the limits for the z axis. With no arguments, `axis' turns autoscaling on. If your plot is already drawn, then you need to use `replot' before the new axis limits will take effect. You can get this to happen automatically by setting the built-in variable `automatic_replot' to a nonzero value. - Function File: hist (Y, X) Produce histogram counts or plots. With one vector input argument, plot a histogram of the values with 10 bins. The range of the histogram bins is determined by the range of the data. Given a second scalar argument, use that as the number of bins. Given a second vector argument, use that as the centers of the bins, with the width of the bins determined from the adjacent values in the vector. Extreme values are lumped in the first and last bins. With two output arguments, produce the values NN and XX such that `bar (XX, NN)' will plot the histogram.  File: octave.info, Node: Image Processing, Next: Audio Processing, Prev: Plotting, Up: Top Image Processing **************** To display images using these functions, you must be using Octave with the X Window System, and you must have either `xloadimage' or `xv' installed. You do not need to be running X in order to manipulate images, however, so some of these functions may be useful even if you are not able to view the results. - Function File: colormap Set the current colormap. `colormap (MAP)' sets the current colormap to MAP. The color map should be an N row by 3 column matrix. The columns contain red, green, and blue intensities respectively. All entries should be between 0 and 1 inclusive. The new colormap is returned. `colormap ("default")' restores the default colormap (a gray scale colormap with 64 entries). The default colormap is returned. With no arguments, `colormap' returns the current color map. - Function File: gray (N) Create a gray colormap with values from 0 to N. The argument N should be a scalar. If it is omitted, 64 is assumed. - Function File: gray2ind Convert a gray scale intensity image to an Octave indexed image. - Function File: image Display an Octave image matrix. `image (X)' displays a matrix as a color image. The elements of X are indices into the current colormap and should have values between 1 and the length of the colormap. `image (X, ZOOM)' changes the zoom factor. The default value is 4. - Function File: imagesc Scale and display a matrix as an image. `imagesc (X)' displays a scaled version of the matrix X. The matrix is scaled so that its entries are indices into the current colormap. The scaled matrix is returned. `imagesc (X, ZOOM)' sets the magnification, the default value is 4. - Function File: imshow Display images. `imshow (X)' displays an indexed image using the current colormap. `imshow (X, MAP)' displays an indexed image using the specified colormap. `imshow (I, N)' displays a gray scale intensity image. `imshow (R, G, B)' displays an RGB image. - Function File: ind2gray Convert an Octave indexed image to a gray scale intensity image. `Y = ind2gray (X)' converts an indexed image to a gray scale intensity image. The current colormap is used to determine the intensities. The intensity values lie between 0 and 1 inclusive. `Y = ind2gray (X, MAP)' uses the specified colormap instead of the current one in the conversion process. - Function File: ind2rgb Convert an indexed image to red, green, and blue color components. `[R, G, B] = ind2rgb (X)' uses the current colormap for the conversion. `[R, G, B] = ind2rgb (X, MAP)' uses the specified colormap. - Function File: loadimage Load an image file. `[X, MAP] = loadimage (FILE)' loads an image and it's associated color map from the specified FILE. The image must be stored in Octave's image format. - Function File: ocean (N) Create color colormap. The argument N should be a scalar. If it is omitted, 64 is assumed. - Function File: rgb2ind Convert and RGB image to an Octave indexed image. `[X, MAP] = rgb2ind (R, G, B)' - Function File: saveimage Save a matrix to disk in image format. `saveimage (FILE, X)' saves matrix X to FILE in Octave's image format. The current colormap is also saved in the file. `saveimage (FILE, X, "img")' saves the image in the default format and is the same as `saveimage (FILE, X)'. `saveimage (FILE, X, "ppm")' saves the image in ppm format instead of the default Octave image format. `saveimage (FILE, X, "ps")' saves the image in PostScript format instead of the default Octave image format. (Note: images saved in PostScript format can not be read back into Octave with loadimage.) `saveimage (FILE, X, FMT, MAP)' saves the image along with the specified colormap in the specified format. Note: if the colormap contains only two entries and these entries are black and white, the bitmap ppm and PostScript formats are used. If the image is a gray scale image (the entries within each row of the colormap are equal) the gray scale ppm and PostScript image formats are used, otherwise the full color formats are used. - Built-in Variable: IMAGEPATH A colon separated list of directories in which to search for image files.  File: octave.info, Node: Audio Processing, Next: Input and Output, Prev: Image Processing, Up: Top Audio Processing **************** Octave provides a few functions for dealing with audio data. An audio `sample' is a single output value from an A/D converter, i.e., a small integer number (usually 8 or 16 bits), and audio data is just a series of such samples. It can be characterized by three parameters: the sampling rate (measured in samples per second or Hz, e.g. 8000 or 44100), the number of bits per sample (e.g. 8 or 16), and the number of channels (1 for mono, 2 for stereo, etc.). There are many different formats for representing such data. Currently, only the two most popular, *linear encoding* and *mu-law encoding*, are supported by Octave. There is an excellent FAQ on audio formats by Guido van Rossum which can be found at any FAQ ftp site, in particular in the directory `/pub/usenet/news.answers/audio-fmts' of the archive site `rtfm.mit.edu'. Octave simply treats audio data as vectors of samples (non-mono data are not supported yet). It is assumed that audio files using linear encoding have one of the extensions `lin' or `raw', and that files holding data in mu-law encoding end in `au', `mu', or `snd'. - Function File: lin2mu (X) If the vector X represents mono audio data in 8- or 16-bit linear encoding, `lin2mu (X)' is the correspoding mu-law encoding. - Function File: mu2lin (X, BPS) If the vector X represents mono audio data in mu-law encoding, `mu2lin (X [, BPS])' converts it to linear encoding. The optional argument BPS specifies whether the input data uses 8 bit per sample (default) or 16 bit. - Function File: loadaudio (NAME, EXT, BPS) Loads audio data from the file `NAME.EXT' into the vector X. The extension EXT determines how the data in the audio file is interpreted; the extensions `lin' (default) and `raw' correspond to linear, the extensions `au', `mu', or `snd' to mu-law encoding. The argument BPS can be either 8 (default) or 16, and specifies the number of bits per sample used in the audio file. - Function File: saveaudio (NAME, X, EXT, BPS) Saves a vector X of audio data to the file `NAME.EXT'. The optional parameters EXT and BPS determine the encoding and the number of bits per sample used in the audio file (see `loadaudio'); defaults are `lin' and 8, respectively. The following functions for audio I/O require special A/D hardware and operating system support. It is assumed that audio data in linear encoding can be played and recorded by reading from and writing to `/dev/dsp', and that similarly `/dev/audio' is used for mu-law encoding. This definitely works on Linux systems, and should also work on Suns. If your hardware is accessed differently, please contact Andreas Weingessel . - Function File: playaudio (NAME, EXT) - Function File: playaudio (X) Plays the audio file `NAME.EXT' or in the vector X. - Function File: record (SEC, SAMPLING_RATE) Records SEC seconds of audio input into the vector X. The default value for SAMPLING_RATE is 8000 samples per second, or 8kHz. The program waits until the key is hit, and then immediately starts to record. - Function File: setaudio (TYPE) - Function File: setaudio (TYPE, VALUE) Set or display various properties of your mixer hardware. For example, if `vol' corresponds to the volume property, you can set it to 50 (percent) by `setaudio ("vol", 50)'. This is an simple experimental program to control the audio hardware settings. It assumes that there is a `mixer' program which can be used as `mixer TYPE VALUE', and simply executes `system ("mixer TYPE VALUE")'. Future releases might get rid of this assumption by using the `fcntl' interface.  File: octave.info, Node: Input and Output, Next: Special Matrices, Prev: Audio Processing, Up: Top Input and Output **************** There are two distinct classes of input and output functions. The first set are modeled after the functions available in MATLAB. The second set are modeled after the standard I/O library used by the C programming language. The C-style I/O functions offer more flexibility and control over the output, but are not quite as easy to use as the simpler MATLAB-style I/O functions. When running interactively, Octave normally sends any output intended for your terminal that is more than one screen long to a paging program, such as `less' or `more'. This avoids the problem of having a large volume of output stream by before you can read it. With `less' (and some versions of `more') it also allows you to scan forward and backward, and search for specific items. No output is displayed by the pager until just before Octave is ready to print the top level prompt, or read from the standard input (for example, by using the `fscanf' or `scanf' functions). This means that there may be some delay before any output appears on your screen if you have asked Octave to perform a significant amount of work with a single command statement. The function `fflush' may be used to force output to be sent to the pager immediately. *Note C-Style I/O Functions::. You can select the program to run as the pager by setting the variable `PAGER', and you can turn paging off by setting the value of the variable `page_screen_output' to 0. - Command: more Turn output pagination on or off. - Built-in Variable: PAGER The default value is `"less"', or, if `less' is not available on your system, `"more"'. *Note Installation::. - Built-in Variable: page_screen_output If the value of `page_screen_output' is nonzero, all output intended for the screen that is longer than one page is sent through a pager. This allows you to view one screenful at a time. Some pagers (such as `less'--see *Note Installation::.) are also capable of moving backward on the output. The default value is 1. - Built-in Variable: page_output_immediately If the value of `page_output_immediately' is nonzero, Octave sends output to the pager as soon as it is available. Otherwise, Octave buffers its output and waits until just before the prompt is printed to flush it to the pager. The default value is 0. * Menu: * Basic Input and Output:: * C-Style I/O Functions::