**preview**has

**blurred**sections. Sign up to view the full version! View Full Document

**Unformatted text preview: **MATLAB
The Language of Technical Computing
Computation Visualization Programming
MATLAB Function Reference Volume 3: P - Z
Version 6
How to Contact The MathWorks:
www.mathworks.com comp.soft-sys.matlab support@mathworks.com suggest@mathworks.com bugs@mathworks.com doc@mathworks.com service@mathworks.com info@mathworks.com
Web Newsgroup Technical support Product enhancement suggestions Bug reports Documentation error reports Order status, license renewals, passcodes Sales, pricing, and general information Phone Fax Mail
508-647-7000 508-647-7001 The MathWorks, Inc. 3 Apple Hill Drive Natick, MA 01760-2098
For contact information about worldwide offices, see the MathWorks Web site. MATLAB Function Reference Volume 3: P - Z COPYRIGHT 1984 - 2002 by The MathWorks, Inc.
The software described in this document is furnished under a license agreement. The software may be used or copied only under the terms of the license agreement. No part of this manual may be photocopied or reproduced in any form without prior written consent from The MathWorks, Inc. FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by or for the federal government of the United States. By accepting delivery of the Program, the government hereby agrees that this software qualifies as "commercial" computer software within the meaning of FAR Part 12.212, DFARS Part 227.7202-1, DFARS Part 227.7202-3, DFARS Part 252.227-7013, and DFARS Part 252.227-7014. The terms and conditions of The MathWorks, Inc. Software License Agreement shall pertain to the government's use and disclosure of the Program and Documentation, and shall supersede any conflicting contractual terms or conditions. If this license fails to meet the government's minimum needs or is inconsistent in any respect with federal procurement law, the government agrees to return the Program and Documentation, unused, to MathWorks. MATLAB, Simulink, Stateflow, Handle Graphics, and Real-Time Workshop are registered trademarks, and TargetBox is a trademark of The MathWorks, Inc. Other product or brand names are trademarks or registered trademarks of their respective holders.
Printing History: December 1996 June 1997 October 1997 January 1999 June 1999 June 2001 July 2002
First printing Online only Online only Online only Second printing Online only Online only
For MATLAB 5 Revised for 5.1 Revised for 5.2 Revised for Release 11 For Release 11 Revised for 6.1 Revised for 6.5 (Release 13)
Contents
Functions By Category
1
Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting and Quitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workspace, File, and Search Path . . . . . . . . . . . . . . . . . . . . . . . Programming Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance Improvement Tools and Techniques . . . . . . . . . .
1-2 1-2 1-2 1-3 1-3 1-4 1-5 1-5
Mathematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6 Arrays and Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 Linear Algebra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 Elementary Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11 Data Analysis and Fourier Transforms . . . . . . . . . . . . . . . . . . 1-13 Polynomials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14 Interpolation and Computational Geometry . . . . . . . . . . . . . . 1-15 Coordinate System Conversion . . . . . . . . . . . . . . . . . . . . . . . . . 1-16 Nonlinear Numerical Methods . . . . . . . . . . . . . . . . . . . . . . . . . 1-16 Specialized Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18 Sparse Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18 Math Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20 Programming and Data Types . . . . . . . . . . . . . . . . . . . . . . . . Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operators and Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Programming in MATLAB . . . . . . . . . . . . . . . . . . . . . . . . . . . . File I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filename Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Opening, Loading, Saving Files . . . . . . . . . . . . . . . . . . . . . . . . Low-Level File I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Text Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-21 1-21 1-25 1-27 1-29 1-34 1-34 1-34 1-35 1-35 1-35
i
Spreadsheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scientific Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Audio and Audio/Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Plots and Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Annotating Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specialized Plotting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bit-Mapped Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handle Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-D Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Surface and Mesh Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . View Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transparency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Volume Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Graphical User Interfaces . . . . . . . . . . . . . . . . . . . . Predefined Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Developing User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Interface Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Objects from Callbacks . . . . . . . . . . . . . . . . . . . . . . . . GUI Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Program Execution . . . . . . . . . . . . . . . . . . . . . . . . .
1-35 1-36 1-36 1-37 1-38 1-38 1-38 1-39 1-41 1-41 1-42 1-44 1-44 1-45 1-46 1-47 1-47 1-48 1-48 1-49 1-49 1-49 1-49 1-49 1-50
Functions Alphabetical List
2
Index
ii
Contents
1
Functions By Category
The MATLAB Function Reference contains descriptions of all MATLAB commands and functions. Select a category from the following table to see a list of related functions. Development Environment Mathematics Programming and Data Types File I/O Graphics 3-D Visualization Creating Graphical User Interface External Interfaces Startup, Command Window, help, editing and debugging, other general functions Arrays and matrices, linear algebra, data analysis, other areas of mathematics Function/expression evaluation, program control, function handles, object oriented programming, error handling, operators, data types, dates and times, timers General and low-level file I/O, plus specific file formats, like audio, spreadsheet, HDF, images Line plots, annotating graphs, specialized plots, images, printing, Handle Graphics Surface and mesh plots, view control, lighting and transparency, volume visualization. GUIDE, programming graphical user interfaces. Java, COM, Serial Port functions.
See Simulink, Stateflow, Real-Time Workshop, and the individual toolboxes for lists of their functions
1
Functions By Category
Development Environment
General functions for working in MATLAB, including functions for startup, Command Window, help, and editing and debugging. "Starting and Quitting" "Command Window" "Getting Help" "Workspace, File, and Search Path" "Programming Tools" "System" "Performance Improvement Tools and Techniques" Startup and shutdown options Controlling Command Window Finding information File, search path, variable management Editing and debugging, source control, Notebook Identifying current computer, license, product version, and more Improving and assessing performance, e.g., profiling and memory use
Starting and Quitting
exit finish matlab matlabrc quit startup
Terminate MATLAB (same as quit) MATLAB termination M-file Start MATLAB (UNIX systems only) MATLAB startup M-file for single user systems or administrators Terminate MATLAB MATLAB startup M-file for user-defined options
Command Window
clc diary dos format home more notebook system unix
Clear Command Window Save session to file Execute DOS command and return result Control display format for output Move cursor to upper left corner of Command Window Control paged output for Command Window Open M-book in Microsoft Word (Windows only) Execute operating system command and return result Execute UNIX command and return result
1-2
Development Environment
Getting Help
doc demo docopt help helpbrowser helpwin info lookfor support web whatsnew
Display online documentation in MATLAB Help browser Access product demos via Help browser Location of help file directory for UNIX platforms Display help for MATLAB functions in Command Window Display Help browser for access to extensive online help Display M-file help, with access to M-file help for all functions Display information about The MathWorks or products Search for specified keyword in all help entries Open MathWorks Technical Support Web page Point Help browser or Web browser to file or Web site Display information about MATLAB and toolbox releases
Workspace, File, and Search Path
"Workspace" "File" "Search Path"
Workspace
assignin clear evalin exist openvar pack which who, whos workspace
Assign value to workspace variable Remove items from workspace, freeing up system memory Execute string containing MATLAB expression in a workspace Check if variable or file exists Open workspace variable in Array Editor for graphical editing Consolidate workspace memory Locate functions and files List variables in the workspace Display Workspace browser, a tool for managing the workspace
File
cd copyfile delete dir exist fileattrib filebrowser lookfor ls
Change working directory Copy file or directory Delete files or graphics objects Display directory listing Check if a variable or file exists Set or get attributes of file or directory Display Current Directory browser, a tool for viewing files Search for specified keyword in all help entries List directory on UNIX
1-3
1
Functions By Category
matlabroot mkdir movefile pwd rehash rmdir type what which
Return root directory of MATLAB installation Make new directory Move file or directory Display current directory Refresh function and file system caches Remove directory List file List MATLAB specific files in current directory Locate functions and files
See also "File I/O" functions.
Search Path
addpath genpath partialpath path path2rc pathtool rmpath
Add directories to MATLAB search path Generate path string Partial pathname View or change the MATLAB directory search path Save current MATLAB search path to pathdef.m file Open Set Path dialog box to view and change MATLAB path Remove directories from MATLAB search path
Programming Tools
"Editing and Debugging" "Source Control" "Notebook"
Editing and Debugging
dbclear dbcont dbdown dbquit dbstack dbstatus dbstep dbstop dbtype dbup edit keyboard
Clear breakpoints Resume execution Change local workspace context Quit debug mode Display function call stack List all breakpoints Execute one or more lines from current breakpoint Set breakpoints in M-file function List M-file with line numbers Change local workspace context Edit or create M-file Invoke the keyboard in an M-file
1-4
Development Environment
Source Control
checkin Check file into source control system checkout Check file out of source control system cmopts Get name of source control system customverctrl Allow custom source control system undocheckout Undo previous checkout from source control system verctrl Version control operations on PC platforms
Notebook
notebook
Open M-book in Microsoft Word (Windows only)
System
computer javachk license prefdir usejava ver version
Identify information about computer on which MATLAB is running Generate error message based on Java feature support Show license number for MATLAB Return directory containing preferences, history, and .ini files Determine if a Java feature is supported in MATLAB Display version information for MathWorks products Get MATLAB version number
Performance Improvement Tools and Techniques
memory pack profile profreport rehash sparse zeros
Help for memory limitations Consolidate workspace memory Optimize performance of M-file code Generate profile report Refresh function and file system caches Create sparse matrix Create array of all zeros
1-5
1
Functions By Category
Mathematics
Functions for working with arrays and matrices, linear algebra, data analysis, and other areas of mathematics. "Arrays and Matrices" "Linear Algebra" Basic array operators and operations, creation of elementary and specialized arrays and matrices Matrix analysis, linear equations, eigenvalues, singular values, logarithms, exponentials, factorization Trigonometry, exponentials and logarithms, complex values, rounding, remainders, discrete math Descriptive statistics, finite differences, correlation, filtering and convolution, fourier transforms Multiplication, division, evaluation, roots, derivatives, integration, eigenvalue problem, curve fitting, partial fraction expansion Interpolation, Delaunay triangulation and tessellation, convex hulls, Voronoi diagrams, domain generation Conversions between Cartesian and polar or spherical coordinates Differential equations, optimization, integration Airy, Bessel, Jacobi, Legendre, beta, elliptic, error, exponential integral, gamma functions Elementary sparse matrices, operations, reordering algorithms, linear algebra, iterative methods, tree operations Pi, imaginary unit, infinity, Not-a-Number, largest and smallest positive floating point numbers, floating point relative accuracy
"Elementary Math"
"Data Analysis and Fourier Transforms" "Polynomials"
"Interpolation and Computational Geometry" "Coordinate System Conversion" "Nonlinear Numerical Methods" "Specialized Math" "Sparse Matrices"
"Math Constants"
1-6
Mathematics
Arrays and Matrices
"Basic Information" "Operators" "Operations and Manipulation" "Elementary Matrices and Arrays" "Specialized Matrices"
Basic Information
disp display isempty isequal islogical isnumeric issparse length ndims numel size
Display array Display array True for empty matrix True if arrays are identical True for logical array True for numeric arrays True for sparse matrix Length of vector Number of dimensions Number of elements Size of matrix
Operators
+ + * ^ \ / ' .' .* .^ .\ ./
Addition Unary plus Subtraction Unary minus Matrix multiplication Matrix power Backslash or left matrix divide Slash or right matrix divide Transpose Nonconjugated transpose Array multiplication (element-wise) Array power (element-wise) Left array divide (element-wise) Right array divide (element-wise)
Operations and Manipulation
: (colon) blkdiag
Index into array, rearrange array Block diagonal concatenation
1-7
1
Functions By Category
cat cross cumprod cumsum diag dot end find fliplr flipud flipdim horzcat ind2sub ipermute kron max min permute prod repmat reshape rot90 sort sortrows sum sqrtm sub2ind tril triu vertcat
Concatenate arrays Vector cross product Cumulative product Cumulative sum Diagonal matrices and diagonals of matrix Vector dot product Last index Find indices of nonzero elements Flip matrices left-right Flip matrices up-down Flip matrix along specified dimension Horizontal concatenation Multiple subscripts from linear index Inverse permute dimensions of multidimensional array Kronecker tensor product Maximum elements of array Minimum elements of array Rearrange dimensions of multidimensional array Product of array elements Replicate and tile array Reshape array Rotate matrix 90 degrees Sort elements in ascending order Sort rows in ascending order Sum of array elements Matrix square root Linear index from multiple subscripts Lower triangular part of matrix Upper triangular part of matrix Vertical concatenation
See also "Linear Algebra" for other matrix operations. See also "Elementary Math" for other array operations.
Elementary Matrices and Arrays
: (colon) blkdiag diag eye freqspace linspace logspace
Regularly spaced vector Construct block diagonal matrix from input arguments Diagonal matrices and diagonals of matrix Identity matrix Frequency spacing for frequency response Generate linearly spaced vectors Generate logarithmically spaced vectors
1-8
Mathematics
meshgrid ndgrid ones rand randn repmat zeros
Generate X and Y matrices for three-dimensional plots Arrays for multidimensional functions and interpolation Create array of all ones Uniformly distributed random numbers and arrays Normally distributed random numbers and arrays Replicate and tile array Create array of all zeros
Specialized Matrices
compan gallery hadamard hankel hilb invhilb magic pascal rosser toeplitz vander wilkinson
Companion matrix Test matrices Hadamard matrix Hankel matrix Hilbert matrix Inverse of Hilbert matrix Magic square Pascal matrix Classic symmetric eigenvalue test problem Toeplitz matrix Vandermonde matrix Wilkinson's eigenvalue test matrix
Linear Algebra
"Matrix Analysis" "Linear Equations" "Eigenvalues and Singular Values" "Matrix Logarithms and Exponentials" "Factorization"
Matrix Analysis
cond condeig det norm normest null orth rank rcond
Condition number with respect to inversion Condition number with respect to eigenvalues Determinant Matrix or vector norm Estimate matrix 2-norm Null space Orthogonalization Matrix rank Matrix reciprocal condition number estimate
1-9
1
Functions By Category
rref subspace trace
Reduced row echelon form Angle between two subspaces Sum of diagonal elements
Linear Equations
\ and / chol cholinc cond condest funm inv lscov lsqnonneg lu luinc pinv qr rcond
Linear equation solution Cholesky factorization Incomplete Cholesky factorization Condition number with respect to inversion 1-norm condition number estimate Evaluate general matrix function Matrix inverse Least squares solution in presence of known covariance Nonnegative least squares LU matrix factorization Incomplete LU factorization Moore-Penrose pseudoinverse of matrix Orthogonal-triangular decomposition Matrix reciprocal condition number estimate
Eigenvalues and Singular Values
balance cdf2rdf condeig eig eigs gsvd hess poly polyeig qz rsf2csf schur svd svds
Improve accuracy of computed eigenvalues Convert complex diagonal form to real block diagonal form Condition number with respect to eigenvalues Eigenvalues and eigenvectors Eigenvalues and eigenvectors of sparse matrix Generalized singular value decomposition Hessenberg form of matrix Polynomial with specified roots Polynomial eigenvalue problem QZ factorization for generalized eigenvalues Convert real Schur form to complex Schur form Schur decomposition Singular value decomposition Singular values and vectors of sparse matrix
Matrix Logarithms and Exponentials
expm logm sqrtm
Matrix exponential Matrix logarithm Matrix square root
1-10
Mathematics
Factorization
balance cdf2rdf chol cholinc cholupdate lu luinc planerot qr qrdelete qrinsert qrupdate qz rsf2csf
Diagonal scaling to improve eigenvalue accuracy Complex diagonal form to real block diagonal form Cholesky factorization Incomplete Cholesky factorization Rank 1 update to Cholesky factorization LU matrix factorization Incomplete LU factorization Givens plane rotation Orthogonal-triangular decomposition Delete column or row from QR factorization Insert column or row into QR factorization Rank 1 update to QR factorization QZ factorization for generalized eigenvalues Real block diagonal form to complex diagonal form
Elementary Math
"Trigonometric" "Exponential" "Complex" "Rounding and Remainder" "Discrete Math (e.g., Prime Factors)"
Trigonometric
acos acosh acot acoth acsc acsch asec asech asin asinh atan atanh atan2 cos cosh cot coth
Inverse cosine Inverse hyperbolic cosine Inverse cotangent Inverse hyperbolic cotangent Inverse cosecant Inverse hyperbolic cosecant Inverse secant Inverse hyperbolic secant Inverse sine Inverse hyperbolic sine Inverse tangent Inverse hyperbolic tangent Four-quadrant inverse tangent Cosine Hyperbolic cosine Cotangent Hyperbolic cotangent
1-11
1
Functions By Category
csc csch sec sech sin sinh tan tanh
Cosecant Hyperbolic cosecant Secant Hyperbolic secant Sine Hyperbolic sine Tangent Hyperbolic tangent
Exponential
exp log log2 log10 nextpow2 pow2 reallog realpow realsqrt sqrt
Exponential Natural logarithm Base 2 logarithm and dissect floating-point numbers into exponent and mantissa Common (base 10) logarithm Next higher power of 2 Base 2 power and scale floating-point number Natural logarithm for nonnegative real arrays Array power for real-only output Square root for nonnegative real arrays Square root
Complex
abs angle complex conj cplxpair
i
imag isreal
j
real unwrap
Absolute value Phase angle Construct complex data from real and imaginary parts Complex conjugate Sort numbers into complex conjugate pairs Imaginary unit Complex imaginary part True for real array Imaginary unit Complex real part Unwrap phase angle
Rounding and Remainder
fix floor ceil round mod rem sign
Round towards zero Round towards minus infinity Round towards plus infinity Round towards nearest integer Modulus after division Remainder after division Signum
1-12
Mathematics
Discrete Math (e.g., Prime Factors)
factor factorial gcd isprime lcm nchoosek perms primes rat, rats
Prime factors Factorial function Greatest common divisor True for prime numbers Least common multiple All combinations of N elements taken K at a time All possible permutations Generate list of prime numbers Rational fraction approximation
Data Analysis and Fourier Transforms
"Basic Operations" "Finite Differences" "Correlation" "Filtering and Convolution" "Fourier Transforms"
Basic Operations
cumprod cumsum cumtrapz max mean median min prod sort sortrows std sum trapz var
Cumulative product Cumulative sum Cumulative trapezoidal numerical integration Maximum elements of array Average or mean value of arrays Median value of arrays Minimum elements of array Product of array elements Sort elements in ascending order Sort rows in ascending order Standard deviation Sum of array elements Trapezoidal numerical integration Variance
Finite Differences
del2 diff gradient
Discrete Laplacian Differences and approximate derivatives Numerical gradient
1-13
1
Functions By Category
Correlation
corrcoef cov subspace
Correlation coefficients Covariance matrix Angle between two subspaces
Filtering and Convolution
conv conv2 convn deconv detrend filter filter2
Convolution and polynomial multiplication Two-dimensional convolution N-dimensional convolution Deconvolution and polynomial division Linear trend removal Filter data with infinite impulse response (IIR) or finite impulse response (FIR) filter Two-dimensional digital filtering
Fourier Transforms
abs angle fft fft2 fftn fftshift ifft ifft2 ifftn ifftshift nextpow2 unwrap
Absolute value and complex magnitude Phase angle One-dimensional discrete Fourier transform Two-dimensional discrete Fourier transform N-dimensional discrete Fourier Transform Shift DC component of discrete Fourier transform to center of spectrum Inverse one-dimensional discrete Fourier transform Inverse two-dimensional discrete Fourier transform Inverse multidimensional discrete Fourier transform Inverse fast Fourier transform shift Next power of two Correct phase angles
Polynomials
conv deconv poly polyder polyeig polyfit polyint polyval polyvalm residue
Convolution and polynomial multiplication Deconvolution and polynomial division Polynomial with specified roots Polynomial derivative Polynomial eigenvalue problem Polynomial curve fitting Analytic polynomial integration Polynomial evaluation Matrix polynomial evaluation Convert between partial fraction expansion and polynomial
1-14
Mathematics
roots
coefficients Polynomial roots
Interpolation and Computational Geometry
"Interpolation" "Delaunay Triangulation and Tessellation" "Convex Hull" "Voronoi Diagrams" "Domain Generation"
Interpolation
dsearch dsearchn griddata griddata3 griddatan interp1 interp2 interp3 interpft interpn meshgrid mkpp ndgrid pchip ppval spline tsearchn unmkpp
Search for nearest point Multidimensional closest point search Data gridding Data gridding and hypersurface fitting for three-dimensional data Data gridding and hypersurface fitting (dimension >= 2) One-dimensional data interpolation (table lookup) Two-dimensional data interpolation (table lookup) Three-dimensional data interpolation (table lookup) One-dimensional interpolation using fast Fourier transform method Multidimensional data interpolation (table lookup) Generate X and Y matrices for three-dimensional plots Make piecewise polynomial Generate arrays for multidimensional functions and interpolation Piecewise Cubic Hermite Interpolating Polynomial (PCHIP) Piecewise polynomial evaluation Cubic spline data interpolation Multidimensional closest simplex search Piecewise polynomial details
Delaunay Triangulation and Tessellation
delaunay delaunay3 delaunayn dsearch dsearchn
Delaunay triangulation Three-dimensional Delaunay tessellation Multidimensional Delaunay tessellation Search for nearest point Multidimensional closest point search
1-15
1
Functions By Category
tetramesh trimesh triplot trisurf tsearch tsearchn
Tetrahedron mesh plot Triangular mesh plot Two-dimensional triangular plot Triangular surface plot Search for enclosing Delaunay triangle Multidimensional closest simplex search
Convex Hull
convhull convhulln patch plot trisurf
Convex hull Multidimensional convex hull Create patch graphics object Linear two-dimensional plot Triangular surface plot
Voronoi Diagrams
dsearch patch plot voronoi voronoin
Search for nearest point Create patch graphics object Linear two-dimensional plot Voronoi diagram Multidimensional Voronoi diagrams
Domain Generation
meshgrid ndgrid
Generate X and Y matrices for three-dimensional plots Generate arrays for multidimensional functions and interpolation
Coordinate System Conversion
Cartesian
cart2sph cart2pol pol2cart sph2cart
Transform Cartesian to spherical coordinates Transform Cartesian to polar coordinates Transform polar to Cartesian coordinates Transform spherical to Cartesian coordinates
Nonlinear Numerical Methods
"Ordinary Differential Equations (IVP)" "Delay Differential Equations" "Boundary Value Problems"
1-16
Mathematics
"Partial Differential Equations" "Optimization" "Numerical Integration (Quadrature)"
Ordinary Differential Equations (IVP)
deval ode113 ode15s ode23 ode23s ode23t ode23tb ode45 odeget odeset
Evaluate solution of differential equation problem Solve non-stiff differential equations, variable order method Solve stiff ODEs and DAEs Index 1, variable order method Solve non-stiff differential equations, low order method Solve stiff differential equations, low order method Solve moderately stiff ODEs and DAEs Index 1, trapezoidal rule Solve stiff differential equations, low order method Solve non-stiff differential equations, medium order method Get ODE options parameters Create/alter ODE options structure
Delay Differential Equations
dde23 ddeget ddeset
Solve delay differential equations with constant delays Get DDE options parameters Create/alter DDE options structure
Boundary Value Problems
bvp4c bvpget bvpset deval
Solve two-point boundary value problems for ODEs by collocation Get BVP options parameters Create/alter BVP options structure Evaluate solution of differential equation problem
Partial Differential Equations
pdepe pdeval
Solve initial-boundary value problems for parabolic-elliptic PDEs Evaluates by interpolation solution computed by pdepe
Optimization
fminbnd fminsearch fzero lsqnonneg
Scalar bounded nonlinear function minimization Multidimensional unconstrained nonlinear minimization, by Nelder-Mead direct search method Scalar nonlinear zero finding Linear least squares with nonnegativity constraints
1-17
1
Functions By Category
optimset optimget
Create or alter optimization options structure Get optimization parameters from options structure
Numerical Integration (Quadrature)
quad quadl dblquad triplequad
Numerically evaluate integral, adaptive Simpson quadrature (low order) Numerically evaluate integral, adaptive Lobatto quadrature (high order) Numerically evaluate double integral Numerically evaluate triple integral
Specialized Math
airy besselh besseli besselj besselk bessely beta betainc betaln ellipj ellipke erf erfc erfcinv erfcx erfinv expint gamma gammainc gammaln legendre psi
Airy functions Bessel functions of third kind (Hankel functions) Modified Bessel function of first kind Bessel function of first kind Modified Bessel function of second kind Bessel function of second kind Beta function Incomplete beta function Logarithm of beta function Jacobi elliptic functions Complete elliptic integrals of first and second kind Error function Complementary error function Inverse complementary error function Scaled complementary error function Inverse error function Exponential integral Gamma function Incomplete gamma function Logarithm of gamma function Associated Legendre functions Psi (polygamma) function
Sparse Matrices
"Elementary Sparse Matrices" "Full to Sparse Conversion" "Working with Sparse Matrices"
1-18
Mathematics
"Reordering Algorithms" "Linear Algebra" "Linear Equations (Iterative Methods)" "Tree Operations"
Elementary Sparse Matrices
spdiags speye sprand sprandn sprandsym
Sparse matrix formed from diagonals Sparse identity matrix Sparse uniformly distributed random matrix Sparse normally distributed random matrix Sparse random symmetric matrix
Full to Sparse Conversion
find full sparse spconvert
Find indices of nonzero elements Convert sparse matrix to full matrix Create sparse matrix Import from sparse matrix external format
Working with Sparse Matrices
issparse nnz nonzeros nzmax spalloc spfun spones spparms spy
True for sparse matrix Number of nonzero matrix elements Nonzero matrix elements Amount of storage allocated for nonzero matrix elements Allocate space for sparse matrix Apply function to nonzero matrix elements Replace nonzero sparse matrix elements with ones Set parameters for sparse matrix routines Visualize sparsity pattern
Reordering Algorithms
colamd colmmd colperm dmperm randperm symamd symmmd symrcm
Column approximate minimum degree permutation Column minimum degree permutation Column permutation Dulmage-Mendelsohn permutation Random permutation Symmetric approximate minimum degree permutation Symmetric minimum degree permutation Symmetric reverse Cuthill-McKee permutation
1-19
1
Functions By Category
Linear Algebra
cholinc condest eigs luinc normest sprank svds
Incomplete Cholesky factorization 1-norm condition number estimate Eigenvalues and eigenvectors of sparse matrix Incomplete LU factorization Estimate matrix 2-norm Structural rank Singular values and vectors of sparse matrix
Linear Equations (Iterative Methods)
bicg bicgstab cgs gmres lsqr minres pcg qmr spaugment symmlq
BiConjugate Gradients method BiConjugate Gradients Stabilized method Conjugate Gradients Squared method Generalized Minimum Residual method LSQR implementation of Conjugate Gradients on Normal Equations Minimum Residual method Preconditioned Conjugate Gradients method Quasi-Minimal Residual method Form least squares augmented system Symmetric LQ method
Tree Operations
etree etreeplot gplot symbfact treelayout treeplot
Elimination tree Plot elimination tree Plot graph, as in "graph theory" Symbolic factorization analysis Lay out tree or forest Plot picture of tree
Math Constants
eps i Inf j NaN pi realmax realmin
Floating-point relative accuracy Imaginary unit Infinity, Imaginary unit Not-a-Number Ratio of a circle's circumference to its diameter, Largest positive floating-point number Smallest positive floating-point number
1-20
Programming and Data Types
Programming and Data Types
Functions to store and operate on data at either the MATLAB command line or in programs and scripts. Functions to write, manage, and execute MATLAB programs. "Data Types" "Arrays" "Operators and Operations" Numeric, character, structures, cell arrays, and data type conversion Basic array operations and manipulation Special characters and arithmetic, bit-wise, relational, logical, set, date and time operations M-files, function/expression evaluation, program control, function handles, object oriented programming, error handling
"Programming in MATLAB"
Data Types
"Numeric" "Characters and Strings" "Structures" "Cell Arrays" "Data Type Conversion" "Determine Data Type"
Numeric
[ ] Array constructor cat Concatenate arrays class Return object's class name (e.g., numeric) find Find indices and values of nonzero array elements ipermute Inverse permute dimensions of multidimensional array isa Detect object of given class (e.g., numeric) isequal Determine if arrays are numerically equal isequalwithequalnansTest for equality, treating NaNs as equal isnumeric Determine if item is numeric array isreal Determine if all array elements are real numbers permute Rearrange dimensions of multidimensional array
1-21
1
Functions By Category
reshape squeeze zeros
Reshape array Remove singleton dimensions from array Create array of all zeros
Characters and Strings
Description of Strings in MATLAB strings
Describes MATLAB string handling
Creating and Manipulating Strings blanks char cellstr datestr deblank lower sprintf sscanf strcat strjust strread strrep strvcat upper
Create string of blanks Create character array (string) Create cell array of strings from character array Convert to date string format Strip trailing blanks from the end of string Convert string to lower case Write formatted data to string Read string under format control String concatenation Justify character array Read formatted data from string String search and replace Vertical concatenation of strings Convert string to upper case
Comparing and Searching Strings class findstr isa iscellstr ischar isletter isspace regexp regexpi regexprep strcmp strcmpi strfind strmatch strncmp
Return object's class name (e.g., char) Find string within another, longer string Detect object of given class (e.g., char) Determine if item is cell array of strings Determine if item is character array Detect array elements that are letters of the alphabet Detect elements that are ASCII white spaces Match regular expression Match regular expression, ignoring case Replace string using regular expression Compare strings Compare strings, ignoring case Find one string within another Find possible matches for string Compare first n characters of strings
1-22
Programming and Data Types
strncmpi strtok
Compare first n characters of strings, ignoring case First token in string
Evaluating String Expressions eval evalc evalin
Execute string containing MATLAB expression Evaluate MATLAB expression with capture Execute string containing MATLAB expression in workspace
Structures
cell2struct class deal fieldnames isa isequal isfield isstruct orderfields rmfield struct struct2cell
Cell array to structure array conversion Return object's class name (e.g., struct) Deal inputs to outputs Field names of structure Detect object of given class (e.g., struct) Determine if arrays are numerically equal Determine if item is structure array field Determine if item is structure array Order fields of a structure array Remove structure fields Create structure array Structure to cell array conversion
Cell Arrays
{ } cell cellfun cellstr cell2mat cell2struct celldisp cellplot class deal isa iscell iscellstr isequal mat2cell num2cell struct2cell
Construct cell array Construct cell array Apply function to each element in cell array Create cell array of strings from character array Convert cell array of matrices into single matrix Cell array to structure array conversion Display cell array contents Graphically display structure of cell arrays Return object's class name (e.g., cell) Deal inputs to outputs Detect object of given class (e.g., cell) Determine if item is cell array Determine if item is cell array of strings Determine if arrays are numerically equal Divide matrix up into cell array of matrices Convert numeric array into cell array Structure to cell array conversion
1-23
1
Functions By Category
Data Type Conversion
Numeric double int8 int16 int32 int64 single uint8 uint16 uint32 uint64 String to Numeric base2dec bin2dec hex2dec hex2num str2double str2num Numeric to String char dec2base dec2bin dec2hex int2str mat2str num2str Other Conversions cell2mat cell2struct datestr func2str logical mat2cell num2cell str2func struct2cell
Convert to double-precision Convert to signed 8-bit integer Convert to signed 16-bit integer Convert to signed 32-bit integer Convert to signed 64-bit integer Convert to single-precision Convert to unsigned 8-bit integer Convert to unsigned 16-bit integer Convert to unsigned 32-bit integer Convert to unsigned 64-bit integer
Convert base N number string to decimal number Convert binary number string to decimal number Convert hexadecimal number string to decimal number Convert hexadecimal number string to double number Convert string to double-precision number Convert string to number
Convert to character array (string) Convert decimal to base N number in string Convert decimal to binary number in string Convert decimal to hexadecimal number in string Convert integer to string Convert a matrix to string Convert number to string
Convert cell array of matrices into single matrix Convert cell array to structure array Convert serial date number to string Convert function handle to function name string Convert numeric to logical array Divide matrix up into cell array of matrices Convert a numeric array to cell array Convert function name string to function handle Convert structure to cell array
1-24
Programming and Data Types
Determine Data Type
is* isa iscell iscellstr ischar isfield isjava islogical isnumeric isobject isstruct
Detect state Detect object of given MATLAB class or Java class Determine if item is cell array Determine if item is cell array of strings Determine if item is character array Determine if item is character array Determine if item is Java object Determine if item is logical array Determine if item is numeric array Determine if item is MATLAB OOPs object Determine if item is MATLAB structure array
Arrays
"Array Operations" "Basic Array Information" "Array Manipulation" "Elementary Arrays"
Array Operations
[ ] , ; : end + .* ./ .\ .^ .'
Array constructor Array row element separator Array column element separator Specify range of array elements Indicate last index of array Addition or unary plus Subtraction or unary minus Array multiplication Array right division Array left division Array power Array (nonconjugated) transpose
Basic Array Information
disp Display text or array display Overloaded method to display text or array isempty Determine if array is empty isequal Determine if arrays are numerically equal isequalwithequalnansTest for equality, treating NaNs as equal
1-25
1
Functions By Category
isnumeric islogical length ndims numel size
Determine if item is numeric array Determine if item is logical array Length of vector Number of array dimensions Number of elements in matrix or cell array Array dimensions
Array Manipulation
: blkdiag cat circshift find fliplr flipud flipdim horzcat ind2sub ipermute permute repmat reshape rot90 shiftdim sort sortrows squeeze sub2ind vertcat
Specify range of array elements Construct block diagonal matrix from input arguments Concatenate arrays Shift array circularly Find indices and values of nonzero elements Flip matrices left-right Flip matrices up-down Flip array along specified dimension Horizontal concatenation Subscripts from linear index Inverse permute dimensions of multidimensional array Rearrange dimensions of multidimensional array Replicate and tile array Reshape array Rotate matrix 90 degrees Shift dimensions Sort elements in ascending order Sort rows in ascending order Remove singleton dimensions Single index from subscripts Horizontal concatenation
Elementary Arrays
: blkdiag eye linspace logspace meshgrid ndgrid ones rand randn zeros
Regularly spaced vector Construct block diagonal matrix from input arguments Identity matrix Generate linearly spaced vectors Generate logarithmically spaced vectors Generate X and Y matrices for three-dimensional plots Generate arrays for multidimensional functions and interpolation Create array of all ones Uniformly distributed random numbers and arrays Normally distributed random numbers and arrays Create array of all zeros
1-26
Programming and Data Types
Operators and Operations
"Special Characters" "Arithmetic Operations" "Bit-wise Operations" "Relational Operations" "Logical Operations" "Set Operations" "Date and Time Operations"
Special Characters
: ( ) [ ] { } . ... , ; % ! =
Specify range of array elements Pass function arguments, or prioritize operations Construct array Construct cell array Decimal point, or structure field separator Continue statement to next line Array row element separator Array column element separator Insert comment line into code Command to operating system Assignment
Arithmetic Operations
+ . = * / \ ^ ' .* ./ .\ .^ .'
Plus Minus Decimal point Assignment Matrix multiplication Matrix right division Matrix left division Matrix power Matrix transpose Array multiplication (element-wise) Array right division (element-wise) Array left division (element-wise) Array power (element-wise) Array transpose
1-27
1
Functions By Category
Bit-wise Operations
bitand bitcmp bitor bitmax bitset bitshift bitget bitxor
Bit-wise AND Bit-wise complement Bit-wise OR Maximum floating-point integer Set bit at specified position Bit-wise shift Get bit at specified position Bit-wise XOR
Relational Operations
< <= > >= == ~= Less than Less than or equal to Greater than Greater than or equal to Equal to Not equal to
Logical Operations
&& || & | ~ all any false find is* isa iskeyword isvarname logical true xor
Logical AND Logical OR Logical AND for arrays Logical OR for arrays Logical NOT Test to determine if all elements are nonzero Test for any nonzero elements False array Find indices and values of nonzero elements Detect state Detect object of given class Determine if string is MATLAB keyword Determine if string is valid variable name Convert numeric values to logical True array Logical EXCLUSIVE OR
Set Operations
intersect ismember setdiff issorted
Set intersection of two vectors Detect members of set Return set difference of two vectors Determine if set elements are in sorted order
1-28
Programming and Data Types
setxor union unique
Set exclusive or of two vectors Set union of two vectors Unique elements of vector
Date and Time Operations
calendar clock cputime date datenum datestr datevec eomday etime now tic, toc weekday
Calendar for specified month Current time as date vector Elapsed CPU time Current date string Serial date number Convert serial date number to string Date components End of month Elapsed time Current date and time Stopwatch timer Day of the week
Programming in MATLAB
"M-File Functions and Scripts" "Evaluation of Expressions and Functions" "Timer Functions" "Variables and Functions in Memory" "Control Flow" "Function Handles" "Object-Oriented Programming" "Error Handling" "MEX Programming"
M-File Functions and Scripts
( ) % ... depfun depdir function input
Pass function arguments Insert comment line into code Continue statement to next line List dependent functions of M-file or P-file List dependent directories of M-file or P-file Function M-files Request user input
1-29
1
Functions By Category
inputname Input argument name mfilename Name of currently running M-file namelengthmax Return maximum identifier length nargin Number of function input arguments nargout Number of function output arguments nargchk Check number of input arguments nargoutchk Validate number of output arguments pcode Create preparsed pseudocode file (P-file) script Describes script M-file varargin Accept variable number of arguments varargout Return variable number of arguments
Evaluation of Expressions and Functions
builtin cellfun eval evalc evalin feval iskeyword isvarname pause run script symvar tic, toc
Execute builtin function from overloaded method Apply function to each element in cell array Interpret strings containing MATLAB expressions Evaluate MATLAB expression with capture Evaluate expression in workspace Evaluate function Determine if item is MATLAB keyword Determine if item is valid variable name Halt execution temporarily Run script that is not on current path Describes script M-file Determine symbolic variables in expression Stopwatch timer
Timer Functions
delete disp get isvalid set start startat stop timer timerfind wait
Delete timer object from memory Display information about timer object Retrieve information about timer object properties Determine if timer object is valid Display or set timer object properties Start a timer Start a timer at a specific timer Stop a timer Create a timer object Return an array of all timer object in memory Block command line until timer completes
Variables and Functions in Memory
assignin
Assign value to workspace variable
1-30
Programming and Data Types
global Define global variables inmem Return names of functions in memory isglobal Determine if item is global variable mislocked True if M-file cannot be cleared mlock Prevent clearing M-file from memory munlock Allow clearing M-file from memory namelengthmax Return maximum identifier length pack Consolidate workspace memory persistent Define persistent variable rehash Refresh function and file system caches
Control Flow
break case catch continue else elseif end error for if otherwise return switch try while
Terminate execution of for loop or while loop Case switch Begin catch block Pass control to next iteration of for or while loop Conditionally execute statements Conditionally execute statements Terminate conditional statements, or indicate last index Display error messages Repeat statements specific number of times Conditionally execute statements Default part of switch statement Return to invoking function Switch among several cases based on expression Begin try block Repeat statements indefinite number of times
Function Handles
class Return object's class name (e.g. function_handle) feval Evaluate function function_handle functions func2str isa isequal str2func
Describes function handle data type Return information about function handle Constructs function name string from function handle Detect object of given class (e.g. function_handle) Determine if function handles are equal Constructs function handle from function name string
1-31
1
Functions By Category
Object-Oriented Programming
MATLAB Classes and Objects class fieldnames inferiorto isa isobject loadobj methods methodsview saveobj subsasgn subsindex subsref substruct superiorto
Create object or return class of object List public fields belonging to object, Establish inferior class relationship Detect object of given class Determine if item is MATLAB OOPs object User-defined extension of load function for user objects Display method names Displays information on all methods implemented by class User-defined extension of save function for user objects Overloaded method for A(I)=B, A{I}=B, and A.field=B Overloaded method for X(A) Overloaded method for A(I), A{I} and A.field Create structure argument for subsasgn or subsref Establish superior class relationship
Java Classes and Objects cell class clear depfun exist fieldnames im2java import inmem isa isjava javaArray javaMethod javaObject methods methodsview which
Convert Java array object to cell array Return class name of Java object Clear Java packages import list List Java classes used by M-file Detect if item is Java class List public fields belonging to object Convert image to instance of Java image object Add package or class to current Java import list List names of Java classes loaded into memory Detect object of given class Determine whether object is Java object Constructs Java array Invokes Java method Constructs Java object Display methods belonging to class Display information on all methods implemented by class Display package and class name for method
Error Handling
catch error ferror
Begin catch block of try/catch statement Display error message Query MATLAB about errors in file input or output
1-32
Programming and Data Types
lasterr lasterror lastwarn rethrow try warning
Return last error message generated by MATLAB Last error message and related information Return last warning message issued by MATLAB Reissue error Begin try block of try/catch statement Display warning message
MEX Programming
dbmex inmem mex mexext
Enable MEX-file debugging Return names of currently loaded MEX-files Compile MEX-function from C or Fortran source code Return MEX-filename extension
1-33
1
Functions By Category
File I/O
Functions to read and write data to files of different format types. "Filename Construction" "Opening, Loading, Saving Files" "Low-Level File I/O" "Text Files" "XML Documents" "Spreadsheets" "Scientific Data" "Audio and Audio/Video" "Images" Get path, directory, filename information; construct filenames Open files; transfer data between files and MATLAB workspace Low-level operations that use a file identifier (e.g., fopen, fseek, fread) Delimited or formatted I/O to text files Documents written in Extensible Markup Language Excel and Lotus 123 files CDF, FITS, HDF formats General audio functions; SparcStation, Wave, AVI files Graphics files
To see a listing of file formats that are readable from MATLAB, go to file
formats.
Filename Construction
fileparts filesep fullfile tempdir tempname
Return parts of filename Return directory separator for this platform Build full filename from parts Return name of system's temporary directory Return unique string for use as temporary filename
Opening, Loading, Saving Files
importdata load open save winopen
Load data from various types of files Load all or specific data from MAT or ASCII file Open files of various types using appropriate editor or program Save all or specific data to MAT or ASCII file Open file in appropriate application (Windows only)
1-34
File I/O
Low-Level File I/O
fclose feof ferror fgetl fgets fopen fprintf fread frewind fscanf fseek ftell fwrite
Close one or more open files Test for end-of-file Query MATLAB about errors in file input or output Return next line of file as string without line terminator(s) Return next line of file as string with line terminator(s) Open file or obtain information about open files Write formatted data to file Read binary data from file Rewind open file Read formatted data from file Set file position indicator Get file position indicator Write binary data to file
Text Files
csvread csvwrite dlmread dlmwrite textread
Read numeric data from text file, using comma delimiter Write numeric data to text file, using comma delimiter Read numeric data from text file, specifying your own delimiter Write numeric data to text file, specifying your own delimiter Read data from text file, specifying format for each value
XML Documents
xmlread xmlwrite xslt
Parse XML document Serialize XML Document Object Model node Transform XML document using XSLT engine
Spreadsheets
Microsoft Excel Functions
xlsfinfo xlsread
Determine if file contains Microsoft Excel (.xls) spreadsheet Read Microsoft Excel spreadsheet file (.xls)
Lotus123 Functions
wk1read wk1write
Read Lotus123 WK1 spreadsheet file into matrix Write matrix to Lotus123 WK1 spreadsheet file
1-35
1
Functions By Category
Scientific Data
Common Data Format (CDF)
cdfinfo cdfread
Return information about CDF file Read CDF file
Flexible Image Transport System
fitsinfo fitsread
Return information about FITS file Read FITS file
Hierarchical Data Format (HDF)
hdf hdfinfo hdfread
Interface to HDF files Return information about HDF or HDF-EOS file Read HDF file
Audio and Audio/Video
General
audioplayer Create audio player object audiorecorder Perform real-time audio capture beep Produce beep sound lin2mu Convert linear audio signal to mu-law mu2lin Convert mu-law audio signal to linear sound Convert vector into sound soundsc Scale data and play as sound
SPARCstation-Specific Sound Functions
auread auwrite
Read NeXT/SUN (.au) sound file Write NeXT/SUN (.au) sound file
Microsoft WAVE Sound Functions
wavplay wavread wavrecord wavwrite
Play sound on PC-based audio output device Read Microsoft WAVE (.wav) sound file Record sound using PC-based audio input device Write Microsoft WAVE (.wav) sound file
1-36
File I/O
Audio Video Interleaved (AVI) Functions
addframe avifile aviinfo aviread close movie2avi
Add frame to AVI file Create new AVI file Return information about AVI file Read AVI file Close AVI file Create AVI movie from MATLAB movie
Images
im2java imfinfo imread imwrite
Convert image to instance of Java image object Return information about graphics file Read image from graphics file Write image to graphics file
1-37
1
Functions By Category
Graphics
2-D graphs, specialized plots (e.g., pie charts, histograms, and contour plots), function plotters, and Handle Graphics functions. Basic Plots and Graphs Annotating Plots Specialized Plotting Bit-Mapped Images Printing Handle Graphics Linear line plots, log and semilog plots Titles, axes labels, legends, mathematical symbols Bar graphs, histograms, pie charts, contour plots, function plotters Display image object, read and write graphics file, convert to movie frames Printing and exporting figures to standard formats Creating graphics objects, setting properties, finding handles
Basic Plots and Graphs
box errorbar hold LineSpec loglog polar plot plot3 plotyy semilogx semilogy subplot
Axis box for 2-D and 3-D plots Plot graph with error bars Hold current graph Line specification syntax Plot using log-log scales Polar coordinate plot Plot vectors or matrices. Plot lines and points in 3-D space Plot graphs with Y tick labels on the left and right Semi-log scale plot Semi-log scale plot Create axes in tiled positions
Annotating Plots
clabel datetick gtext legend texlabel
Add contour labels to contour plot Date formatted tick labels Place text on 2-D graph using mouse Graph legend for lines and patches Produce the TeX format from character string
1-38
Graphics
title xlabel ylabel zlabel
Titles for 2-D and 3-D plots X-axis labels for 2-D and 3-D plots Y-axis labels for 2-D and 3-D plots Z-axis labels for 3-D plots
Specialized Plotting
"Area, Bar, and Pie Plots" "Contour Plots" "Direction and Velocity Plots" "Discrete Data Plots" "Function Plots" "Histograms" "Polygons and Surfaces" "Scatter Plots" "Animation"
Area, Bar, and Pie Plots
area bar barh bar3 bar3h pareto pie pie3
Area plot Vertical bar chart Horizontal bar chart Vertical 3-D bar chart Horizontal 3-D bar chart Pareto char Pie plot 3-D pie plot
Contour Plots
contour contour3 contourc contourf ezcontour ezcontourf
Contour (level curves) plot 3-D contour plot Contour computation Filled contour plot Easy to use contour plotter Easy to use filled contour plotter
Direction and Velocity Plots
comet comet3
Comet plot 3-D comet plot
1-39
1
Functions By Category
compass feather quiver quiver3
Compass plot Feather plot Quiver (or velocity) plot 3-D quiver (or velocity) plot
Discrete Data Plots
stem stem3 stairs
Plot discrete sequence data Plot discrete surface data Stairstep graph
Function Plots
ezcontour ezcontourf ezmesh ezmeshc ezplot ezplot3 ezpolar ezsurf ezsurfc fplot
Easy to use contour plotter Easy to use filled contour plotter Easy to use 3-D mesh plotter Easy to use combination mesh/contour plotter Easy to use function plotter Easy to use 3-D parametric curve plotter Easy to use polar coordinate plotter Easy to use 3-D colored surface plotter Easy to use combination surface/contour plotter Plot a function
Histograms
hist histc rose
Plot histograms Histogram count Plot rose or angle histogram
Polygons and Surfaces
convhull cylinder delaunay dsearch ellipsoid fill fill3 inpolygon pcolor polyarea ribbon slice sphere
Convex hull Generate cylinder Delaunay triangulation Search Delaunay triangulation for nearest point Generate ellipsoid Draw filled 2-D polygons Draw filled 3-D polygons in 3-space True for points inside a polygonal region Pseudocolor (checkerboard) plot Area of polygon Ribbon plot Volumetric slice plot Generate sphere
1-40
Graphics
tsearch voronoi waterfall
Search for enclosing Delaunay triangle Voronoi diagram Waterfall plot
Scatter Plots
plotmatrix scatter scatter3
Scatter plot matrix
Scatter plot
3-D scatter plot
Animation
frame2im getframe im2frame movie noanimate
Convert movie frame to indexed image Capture movie frame Convert image to movie frame Play recorded movie frames Change EraseMode of all objects to normal
Bit-Mapped Images
frame2im image imagesc imfinfo imformats im2frame im2java imread imwrite ind2rgb
Convert movie frame to indexed image Display image object Scale data and display image object Information about graphics file Manage file format registry Convert image to movie frame Convert image to instance of Java image object Read image from graphics file Write image to graphics file Convert indexed image to RGB image
Printing
frameedit orient pagesetupdlg print printdlg printopt printpreview saveas
Edit print frame for Simulink and Stateflow diagram Hardcopy paper orientation Page position dialog box Print graph or save graph to file Print dialog box Configure local printer defaults Preview figure to be printed Save figure to graphic file
1-41
1
Functions By Category
Handle Graphics
Finding and Identifying Graphics Objects Object Creation Functions Figure Windows Axes Operations
Finding and Identifying Graphics Objects
allchild copyobj delete findall figflag findfigs findobj gca gcbo gcbf gco get ishandle set
Find all children of specified objects Make copy of graphics object and its children Delete files or graphics objects Find all graphics objects (including hidden handles) Test if figure is on screen Display off-screen visible figure windows Find objects with specified property values Get current Axes handle Return object whose callback is currently executing Return handle of figure containing callback object Return handle of current object Get object properties True if value is valid object handle Set object properties
Object Creation Functions
axes Create axes object figure Create figure (graph) windows image Create image (2-D matrix) light Create light object (illuminates Patch and Surface) line Create line object (3-D polylines) patch Create patch object (polygons) rectangle Create rectangle object (2-D rectangle) rootobject List of root properties surface Create surface (quadrilaterals) text Create text object (character strings) uicontextmenu Create context menu (popup associated with object)
Figure Windows
capture clc clf
Screen capture of the current figure Clear figure window Clear figure
1-42
Graphics
close closereq drawnow figflag gcf hgload hgsave newplot opengl refresh saveas
Close specified window Default close request function Complete any pending drawing Test if figure is on screen Get current figure handle Load graphics object hierarchy from a FIG-file Save graphics object hierarchy to a FIG-file Graphics M-file preamble for NextPlot property Change automatic selection mode of OpenGL rendering Refresh figure Save figure or model to desired output format
Axes Operations
axis box cla gca grid ishold
Plot axis scaling and appearance Display axes border Clear Axes Get current Axes handle Grid lines for 2-D and 3-D plots Get the current hold state
1-43
1
Functions By Category
3-D Visualization
Create and manipulate graphics that display 2-D matrix and 3-D volume data, controlling the view, lighting and transparency. Surface and Mesh Plots View Control Lighting Transparency Volume Visualization Plot matrices, visualize functions of two variables, specify colormap Control the camera viewpoint, zooming, rotation, aspect ratio, set axis limits Add and control scene lighting Specify and control object transparency Visualize gridded volume data
Surface and Mesh Plots
Creating Surfaces and Meshes Domain Generation Color Operations Colormaps
Creating Surfaces and Meshes
hidden meshc mesh peaks surf surface surfc surfl tetramesh trimesh triplot trisurf
Mesh hidden line removal mode Combination mesh/contourplot 3-D mesh with reference plane A sample function of two variables 3-D shaded surface graph Create surface low-level objects Combination surf/contourplot 3-D shaded surface with lighting Tetrahedron mesh plot Triangular mesh plot 2-D triangular plot Triangular surface plot
Domain Generation
griddata meshgrid
Data gridding and surface fitting Generation of X and Y arrays for 3-D plots
1-44
3-D Visualization
Color Operations
brighten Brighten or darken color map caxis Pseudocolor axis scaling colormapeditorStart colormap editor colorbar Display color bar (color scale) colordef Set up color defaults colormap Set the color look-up table (list of colormaps) ColorSpec Ways to specify color graymon Graphics figure defaults set for grayscale monitor hsv2rgb Hue-saturation-value to red-green-blue conversion rgb2hsv RGB to HSVconversion rgbplot Plot color map shading Color shading mode spinmap Spin the colormap surfnorm 3-D surface normals whitebg Change axes background color for plots
Colormaps
autumn bone contrast cool copper flag gray hot hsv jet lines prism spring summer winter
Shades of red and yellow color map Gray-scale with a tinge of blue color map Gray color map to enhance image contrast Shades of cyan and magenta color map Linear copper-tone color map Alternating red, white, blue, and black color map Linear gray-scale color map Black-red-yellow-white color map Hue-saturation-value (HSV) color map Variant of HSV Line color colormap Colormap of prism colors Shades of magenta and yellow color map Shades of green and yellow colormap Shades of blue and green color map
View Control
Controlling the Camera Viewpoint Setting the Aspect Ratio and Axis Limits Object Manipulation Selecting Region of Interest
1-45
1
Functions By Category
Controlling the Camera Viewpoint
camdolly camlookat camorbit campan campos camproj camroll camtarget camup camva camzoom view viewmtx
Move camera position and target View specific objects Orbit about camera target Rotate camera target about camera position Set or get camera position Set or get projection type Rotate camera about viewing axis Set or get camera target Set or get camera up-vector Set or get camera view angle Zoom camera in or out 3-D graph viewpoint specification. Generate view transformation matrices
Setting the Aspect Ratio and Axis Limits
daspect pbaspect xlim ylim zlim
Set or get data aspect ratio Set or get plot box aspect ratio Set or get the current x-axis limits Set or get the current y-axis limits Set or get the current z-axis limits
Object Manipulation
reset Reset axis or figure rotate Rotate objects about specified origin and direction rotate3d Interactively rotate the view of a 3-D plot selectmoveresizeInteractively select, move, or resize objects zoom Zoom in and out on a 2-D plot
Selecting Region of Interest
dragrect rbbox
Drag XOR rectangles with mouse Rubberband box
Lighting
camlight light lightangle lighting material
Cerate or position Light Light object creation function Position light in sphereical coordinates Lighting mode Material reflectance mode
1-46
3-D Visualization
Transparency
alpha alphamap alim
Set or query transparency properties for objects in current axes Specify the figure alphamap Set or query the axes alpha limits
Volume Visualization
coneplot Plot velocity vectors as cones in 3-D vector field contourslice Draw contours in volume slice plane curl Compute curl and angular velocity of vector field divergence Compute divergence of vector field flow Generate scalar volume data interpstreamspeedInterpolate streamline vertices from vector-field
magnitudes
isocaps Compute isosurface end-cap geometry isocolors Compute colors of isosurface vertices isonormals Compute normals of isosurface vertices isosurface Extract isosurface data from volume data reducepatch Reduce number of patch faces reducevolume Reduce number of elements in volume data set shrinkfaces Reduce size of patch faces slice Draw slice planes in volume smooth3 Smooth 3-D data stream2 Compute 2-D stream line data stream3 Compute 3-D stream line data streamline Draw stream lines from 2- or 3-D vector data streamparticlesDraws stream particles from vector volume data streamribbon Draws stream ribbons from vector volume data streamslice Draws well-spaced stream lines from vector volume data streamtube Draws stream tubes from vector volume data surf2patch Convert surface data to patch data subvolume Extract subset of volume data set volumebounds Return coordinate and color limits for volume (scalar and
vector)
1-47
1
Functions By Category
Creating Graphical User Interfaces
Predefined dialog boxes and functions to control GUI programs. Predefined Dialog Boxes Deploying User Interfaces Developing User Interfaces User Interface Objects Finding Objects from Callbacks GUI Utility Functions Controlling Program Execution Dialog boxes for error, user input, waiting, etc. Launching GUIs, creating the handles structure Starting GUIDE, managing application data, getting user input Creating GUI components Finding object handles from within callbacks functions Moving objects, text wrapping Wait and resume based on user input
Predefined Dialog Boxes
dialog errordlg helpdlg inputdlg listdlg msgbox pagedlg printdlg questdlg uigetdir uigetfile uiputfile uisetcolor uisetfont waitbar warndlg
Create dialog box Create error dialog box Display help dialog box Create input dialog box Create list selection dialog box Create message dialog box Display page layout dialog box Display print dialog box Create question dialog box Display dialog box to retrieve name of directory Display dialog box to retrieve name of file for reading Display dialog box to retrieve name of file for writing Set ColorSpec using dialog box Set font using dialog box Display wait bar Create warning dialog box
1-48
Creating Graphical User Interfaces
Deploying User Interfaces
guidata guihandles movegui openfig
Store or retrieve application data Create a structure of handles Move GUI figure onscreen Open or raise GUI figure
Developing User Interfaces
guide inspect
Open GUI Layout Editor Display Property Inspector
Working with Application Data
getappdata isappdata rmappdata setappdata
Get value of application data True if application data exists Remove application data Specify application data
Interactive User Input
ginput Graphical input from a mouse or cursor waitfor Wait for conditions before resuming execution waitforbuttonpressWait for key/buttonpress over figure
User Interface Objects
menu Generate menu of choices for user input uicontextmenu Create context menu uicontrol Create user interface control uimenu Create user interface menu
Finding Objects from Callbacks
findall findfigs findobj gcbf gcbo
Find all graphics objects Display off-screen visible figure windows Find specific graphics object Return handle of figure containing callback object Return handle of object whose callback is executing
GUI Utility Functions
selectmoveresizeSelect, move, resize, or copy axes and uicontrol graphics textwrap
objects Return wrapped string matrix for given uicontrol
1-49
1
Functions By Category
Controlling Program Execution
uiresume uiwait
Resumes program execution halted with uiwait Halts program execution, restart with uiresume
1-50
2
Functions Alphabetical List
2
Functions Alphabetical List
pack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 pagedlg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14 pagesetupdlg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 pareto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16 partialpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17 pascal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18 patch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19 Patch Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31 path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-49 path2rc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-51 pathtool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52 pause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-53 pbaspect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-54 pcg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-59 pchip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-63 pcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-65 pcolor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-66 pdepe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-69 pdeval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-80 peaks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-81 perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-82 perms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-83 permute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-84 persistent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-85 pi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-86 pie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-87 pie3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-89 pinv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-91 planerot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-94 plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-95 plot3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-100 plotedit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-102 plotmatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-104 plotyy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-106 pol2cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-108 polar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-109 poly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-111
2-2
polyarea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polyder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polyeig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polyfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polyint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polyval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . polyvalm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pow2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ppval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . prefdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . primes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . print, printopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . printdlg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . printpreview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . prod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . profreport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . propedit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . propedit (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . psi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . qmr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . qr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . qrdelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . qrinsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . qrupdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . quad, quad8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . quadl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . questdlg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . quiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . quiver3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . qz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . randn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . randperm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-113 2-114 2-115 2-117 2-120 2-121 2-123 2-125 2-126 2-127 2-128 2-129 2-143 2-144 2-145 2-146 2-150 2-152 2-154 2-155 2-157 2-158 2-162 2-166 2-168 2-170 2-173 2-175 2-177 2-179 2-181 2-184 2-186 2-188 2-190 2-192 2-193
2-3
2
Functions Alphabetical List
rat, rats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rbbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rcond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . readasync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . real . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reallog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . realmax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . realmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . realpow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . realsqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectangle properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rectint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reducepatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reducevolume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . regexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . regexpi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . regexprep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . registerevent (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rehash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . release (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . repmat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . reshape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . residue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rethrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rgb2hsv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rgbplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ribbon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rmappdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rmdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rmfield . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rmpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-194 2-197 2-199 2-200 2-202 2-203 2-204 2-205 2-206 2-207 2-208 2-210 2-217 2-224 2-225 2-229 2-231 2-232 2-235 2-237 2-239 2-241 2-243 2-245 2-246 2-247 2-248 2-250 2-253 2-254 2-255 2-256 2-257 2-259 2-260 2-263 2-264
2-4
root object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Root Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . roots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rosser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rot90 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rotate3d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . round . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . rsf2csf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . save (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . save (serial) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . saveas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . saveobj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . scatter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . scatter3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . schur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sech . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . selectmoveresize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . semilogx, semilogy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . send (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sendmail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . serialbreak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set (serial) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . set (timer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setappdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setdiff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setfield . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-265 2-268 2-274 2-276 2-278 2-279 2-280 2-282 2-283 2-284 2-286 2-288 2-289 2-290 2-293 2-294 2-296 2-299 2-300 2-302 2-304 2-306 2-307 2-309 2-311 2-312 2-314 2-315 2-316 2-318 2-319 2-322 2-323 2-325 2-328 2-329 2-330
2-5
2
Functions Alphabetical List
setstr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setxor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . shading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . shiftdim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . shrinkfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . single . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sinh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . size (serial) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . slice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . smooth3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sortrows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . soundsc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spalloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sparse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spaugment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spconvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spdiags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . speye . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spfun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sph2cart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spinmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spparms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sprand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sprandn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sprandsym . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sprank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . spy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-332 2-333 2-334 2-337 2-338 2-342 2-343 2-345 2-346 2-348 2-351 2-352 2-357 2-359 2-361 2-362 2-363 2-364 2-365 2-367 2-368 2-370 2-373 2-374 2-376 2-377 2-379 2-380 2-384 2-385 2-388 2-389 2-390 2-391 2-392 2-398 2-400
2-6
sqrtm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . squeeze . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sscanf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . stairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . startat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . std . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . stem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . stem3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . stopasync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . str2double . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . str2func . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . str2mat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . str2num . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strcmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strcmpi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . stream2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . stream3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . streamline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . streamparticles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . streamribbon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . streamslice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . streamtube . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strfind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strjust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strmatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strncmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strncmpi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strrep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strtok . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . struct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . struct2cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . strvcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-401 2-404 2-405 2-408 2-410 2-411 2-413 2-415 2-417 2-419 2-420 2-421 2-422 2-423 2-424 2-425 2-427 2-429 2-430 2-432 2-434 2-436 2-440 2-446 2-451 2-455 2-456 2-458 2-459 2-460 2-461 2-462 2-466 2-467 2-468 2-470 2-471
2-7
2
Functions Alphabetical List
sub2ind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . subplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . subsasgn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . subsindex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . subspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . subsref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . substruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . subvolume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . superiorto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . surf, surfc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . surf2patch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . surface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Surface Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . surfl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . surfnorm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . svds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . symamd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . symbfact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . symmlq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . symmmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . symrcm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . symvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tanh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tempdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tempname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tetramesh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . texlabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-472 2-474 2-476 2-477 2-479 2-480 2-481 2-482 2-484 2-485 2-486 2-487 2-491 2-493 2-501 2-515 2-518 2-520 2-523 2-525 2-527 2-529 2-530 2-534 2-536 2-538 2-539 2-540 2-541 2-543 2-545 2-546 2-547 2-549 2-552 2-554 2-562
2-8
textread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . textwrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tic, toc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . timerfind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . toeplitz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . trapz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . treelayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . treeplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tril . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . trimesh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . triplequad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . triplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . trisurf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . triu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . true . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . try . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tsearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . tsearchn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uicontextmenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uicontextmenu Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . uicontrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Uicontrol Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uigetdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uigetfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uiimport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uimenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Uimenu Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uint8, uint16, uint32, uint64 . . . . . . . . . . . . . . . . . . . . . . . . . uiputfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uiresume, uiwait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uisetcolor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uisetfont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . uistack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-579 2-584 2-585 2-586 2-591 2-593 2-595 2-596 2-597 2-599 2-600 2-601 2-602 2-603 2-605 2-607 2-608 2-609 2-610 2-611 2-612 2-613 2-614 2-617 2-622 2-630 2-644 2-648 2-654 2-655 2-659 2-666 2-668 2-673 2-674 2-675 2-677
2-9
2
Functions Alphabetical List
................................................. undocheckout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . union . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unmkpp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unregisterallevents (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . unregisterevent (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unwrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . unzip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . upper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . urlread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . urlwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . usejava . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vander . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . var . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . varargin, varargout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vectorize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . verctrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vertcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viewmtx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . volumebounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . voronoi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . voronoin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . waitbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . waitfor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . waitforbuttonpress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . warndlg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . warning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . waterfall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . wavplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . wavread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . wavrecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-677 2-678 2-679 2-680 2-682 2-683 2-684 2-686 2-688 2-692 2-693 2-694 2-695 2-696 2-697 2-698 2-699 2-701 2-702 2-704 2-708 2-709 2-711 2-714 2-718 2-720 2-724 2-727 2-728 2-730 2-731 2-732 2-733 2-737 2-739 2-741 2-742
2-10
wavwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . weekday . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . what . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . whatsnew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . which . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . while . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . whitebg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . who, whos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . wilkinson . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . winopen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . wk1read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . wk1write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlabel, ylabel, zlabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlim, ylim, zlim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlsfinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlsread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xmlread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xmlwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xslt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . zeros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . zip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . zoom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-743 2-744 2-746 2-747 2-749 2-750 2-753 2-756 2-757 2-759 2-760 2-761 2-762 2-763 2-764 2-766 2-768 2-769 2-773 2-774 2-775 2-776 2-777 2-778 2-780
2-11
pack
Purpose Syntax
2pack
Consolidate workspace memory
pack pack filename pack('filename') pack frees up needed space by reorganizing information so it only uses the minimum memory required. You must run pack from a directory for which you have write permission. Running pack clears all variables not in the base
Description
workspace, so persistent variables, for example, will be cleared.
pack filename accepts an optional filename for the temporary file used to hold the variables. Otherwise, it uses the file named pack.tmp. You must run pack from a directory for which you have write permission. pack('filename') is the function form of pack.
Remarks
The pack function does not affect the amount of memory allocated to the MATLAB process. You must quit MATLAB to free up this memory. Since MATLAB uses a heap method of memory management, extended MATLAB sessions may cause memory to become fragmented. When memory is fragmented, there may be plenty of free space, but not enough contiguous memory to store a new large variable. If you get the Out of memory message from MATLAB, the pack function may find you some free memory without forcing you to delete variables. The pack function frees space by: Saving all variables in the base workspace to disk in a temporary file called
pack.tmp
Clearing all variables and functions from memory Reloading the base workspace variables back from pack.tmp Deleting the temporary file pack.tmp
2-12
pack
If you use pack and there is still not enough free memory to proceed, you must clear some variables. If you run out of memory often, you can allocate larger matrices earlier in the MATLAB session and use these system-specific tips: UNIX: Ask your system manager to increase your swap space. Windows: Increase virtual memory using the Windows Control Panel. To maintain persistent variables when you run pack, use mlock in the function.
Examples
Change the current directory to one that is writable, run pack, and return to the previous directory.
cwd = pwd; cd(tempdir); pack cd(cwd)
See Also
clear
2-13
pagedlg
Purpose Syntax Description
2pagedlg
This function is obsolete. Use pagesetupdlg to display the page setup dialog.
pagedlg pagedlg(fig) pagedlg displays a page position dialog box for the current figure. The dialog
box enables you to set page layout properties.
pagedlg(fig) displays a page position dialog box for the figure identified by the handle fig.
Remarks
This dialog box enables you to set figure properties that determine how MATLAB lays out the figure on the printed paper. See the dialog box help for more information. The figure properties PaperPosition, PaperOrientation, PaperUnits
See Also
2-14
pagesetupdlg
Purpose Syntax Description
2pagesetupdlg
Page position dialog box
dlg = pagesetupdlg(fig) dlg = pagesetupdlg(fig) creates a dialog box from which a set of pagelayout properties for the figure window, fig, can be set. pagesetupdlg implements the "Page Setup..." option in the Figure File Menu.
Unlike pagedlg, pagesetupdlg currently only supports setting the layout for a single figure. fig must be a single figure handle, not a vector of figures or a simulink diagram.
See Also
pagedlg, printpreview, printopt
2-15
pareto
Purpose Syntax
2pareto
Pareto chart
pareto(Y) pareto(Y,names) pareto(Y,X) H = pareto(...)
Description
Pareto charts display the values in the vector Y as bars drawn in descending order.
pareto(Y) labels each bar with its element index in Y. pareto(Y,names) labels each bar with the associated name in the string matrix or cell array names. pareto(Y,X) labels each bar with the associated value from X. H = pareto(...) returns a combination of patch and line object handles.
See Also
hist, bar
2-16
partialpath
Purpose Description
2partialpath
pathname
A partial pathname is a pathname relative to the MATLAB path, matlabpath. It is used to locate private and method files, which are usually hidden, or to restrict the search for files when more than one file with the given name exists. A partial pathname contains the last component, or last several components, of the full pathname separated by /. For example, matfun/trace, private/children, inline/formula, and demos/clown.mat are valid partial pathnames. Specifying the @ in method directory names is optional, so funfun/inline/formula is also a valid partial pathname. Partial pathnames make it easy to find toolbox or MATLAB relative files on your path, independent of the location where MATLAB is installed. Many commands accept partial pathnames instead of a full pathname. Some of these commands are
help, type, load, exist, what, which, edit, dbtype, dbstop, dbclear, and fopen
Examples
The following examples use partial pathnames:
what funfun/inline M-files in argnames cat char directory matlabroot\toolbox\matlab\funfun\@inline disp feval inline subsref vertcat display formula nargin symvar exist horzcat nargout vectorize
which funfun/inline/formula matlabroot\toolbox\matlab\funfun\@inline\formula.m % inline method
See Also
matlabroot, path
2-17
pascal
Purpose Syntax
2pascal
Pascal matrix
A = pascal(n) A = pascal(n,1) A = pascal(n,2) A = pascal(n) returns the Pascal matrix of order n: a symmetric positive
Description
definite matrix with integer entries taken from Pascal's triangle. The inverse of A has integer entries.
A = pascal(n,1) returns the lower triangular Cholesky factor (up to the signs
of the columns) of the Pascal matrix. It is involutary, that is, it is its own inverse.
A = pascal(n,2) returns a transposed and permuted version of pascal(n,1). A is a cube root of the identity matrix.
Examples
pascal(4) returns 1 1 1 1 1 2 3 4 1 3 6 10 1 4 10 20
A = pascal(3,2) produces A = 1 -2 1 1 -1 0 1 0 0
See Also
chol
2-18
patch
Purpose Syntax
2patch
Create patch graphics object
patch(X,Y,C) patch(X,Y,Z,C) patch(FV) patch(...'PropertyName',PropertyValue...) patch('PropertyName',PropertyValue...) PN/PV pairs only handle = patch(...)
patch is the low-level graphics function for creating patch graphics objects. A
Description
patch object is one or more polygons defined by the coordinates of its vertices. You can specify the coloring and lighting of the patch. See the Creating 3-D Models with Patches for more information on using patch objects.
patch(X,Y,C) adds the filled two-dimensional patch to the current axes. The
elements of X and Y specify the vertices of a polygon. If X and Y are matrices, MATLAB draws one polygon per column. C determines the color of the patch. It can be a single ColorSpec, one color per face, or one color per vertex (see "Remarks"). If C is a 1-by-3 vector, it is assumed to be an RGB triplet, specifying a color directly.
patch(X,Y,Z,C) creates a patch in three-dimensional coordinates. patch(FV) creates a patch using structure FV, which contains the fields vertices, faces, and optionally facevertecdata. These fields correspond to the Vertices, Faces, and FaceVertexCData patch properties. patch(...'PropertyName',PropertyValue...) follows the X, Y, (Z), and C
arguments with property name/property value pairs to specify additional patch properties.
patch('PropertyName',PropertyValue,...) specifies all properties using property name/property value pairs. This form enables you to omit the color specification because MATLAB uses the default face color and edge color, unless you explicitly assign a value to the FaceColor and EdgeColor properties. This form also allows you to specify the patch using the Faces and Vertices properties instead of x-, y-, and z-coordinates. See the "Examples" section for more information.
2-19
patch
handle = patch(...) returns the handle of the patch object it creates.
Remarks
Unlike high-level area creation functions, such as fill or area, patch does not check the settings of the figure and axes NextPlot properties. It simply adds the patch object to the current axes. If the coordinate data does not define closed polygons, patch closes the polygons. The data can define concave or intersecting polygons. However, if the edges of an individual patch face intersect themselves, the resulting face may or may not be completely filled. In that case, it is better to break up the face into smaller polygons.
Specifying Patch Properties
You can specify properties as property name/property value pairs, structure arrays, and cell arrays (see the set and get reference pages for examples of how to specify these data types). There are two patch properties that specify color: CData use when specifying x-, y-, and z-coordinates (XData, YData, ZData). FaceVertexCData use when specifying vertices and connection matrix (Vertices and Faces). The CData and FaceVertexCData properties accept color data as indexed or true color (RGB) values. See the CData and FaceVertexCData property descriptions for information on how to specify color. Indexed color data can represent either direct indices into the colormap or scaled values that map the data linearly to the entire colormap (see the caxis
2-20
patch
function for more information on this scaling). The CDataMapping property determines how MATLAB interprets indexed color data. Color Specification
CData
Color Interpretation by MATLAB
FaceVertexCData
True Color Indexed
(CDataMapping) direct scaled
Color Mapping
Color Data Interpretation
You can specify patch colors as: A single color for all faces One color for each face enabling flat coloring One color for each vertex enabling interpolated coloring The following tables summarize how MATLAB interprets color data defined by the CData and FaceVertexCData properties.
Interpretation of the CData Property [X,Y,Z]Data Dimensions CData Required for Indexed True Color Results Obtained
m-by-n
scalar
1-by-1-by-3
Use the single color specified for all patch faces. Edges can be only a single color.
2-21
patch
[X,Y,Z]Data Dimensions
CData Required for Indexed True Color
Results Obtained
m-by-n m-by-n
1-by-n (n >= 4) m-by-n
1-by-n-by-3 m-by-n-3
Use one color for each patch face. Edges can be only a single color. Assign a color to each vertex. patch faces can be flat (a single color) or interpolated. Edges can be flat or interpolated.
Interpretation of the FaceVertexCData Property Vertices Dimensions Faces Dimensions FaceVertexCData Required for Indexed True Color Results Obtained
m-by-n
k-by-3
scalar
1-by-3
Use the single color specified for all patch faces. Edges can be only a single color. Use one color for each patch face. Edges can be only a single color. Assign a color to each vertex. patch faces can be flat (a single color) or interpolated. Edges can be flat or interpolated.
m-by-n m-by-n
k-by-3 k-by-3
k-by-1 m-by-1
k-by-3 m-by-3
Examples
This example creates a patch object using two different methods: Specifying x-, y-, and z-coordinates and color data (XData, YData, ZData, and CData properties). Specifying vertices, the connection matrix, and color data (Vertices, Faces, FaceVertexCData, and FaceColor properties).
2-22
patch
Specifying X, Y, and Z Coordinates
The first approach specifies the coordinates of each vertex. In this example, the coordinate data defines two triangular faces, each having three vertices. Using true color, the top face is set to white and the bottom face to gray.
x = [0 0;0 1;1 1]; y = [1 1;2 2;2 1]; z = [1 1;1 1;1 1]; tcolor(1,1,1:3) = [1 1 1]; tcolor(1,2,1:3) = [.7 .7 .7]; patch(x,y,z,tcolor)
2 1.9 1.8 1.7 1.6 1.5 1.4 1.3 1.2 1.1 1 0
V2
V3 V5
V1 V4
0.2 0.4 0.6 0.8
V6
1
Notice that each face shares two vertices with the other face (V1-V4 and V3-V5).
Specifying Vertices and Faces
The Vertices property contains the coordinates of each unique vertex defining the patch. The Faces property specifies how to connect these vertices to form each face of the patch. For this example, two vertices share the same location so you need to specify only four of the six vertices. Each row contains the x, y, and z-coordinates of each vertex.
vert = [0 1 1;0 2 1;1 2 1;1 1 1];
2-23
patch
There are only two faces, defined by connecting the vertices in the order indicated.
fac = [1 2 3;1 3 4];
To specify the face colors, define a 2-by-3 matrix containing two RGB color definitions.
tcolor = [1 1 1;.7 .7 .7];
With two faces and two colors, MATLAB can color each face with flat shading. This means you must set the FaceColor property to flat, since the faces/vertices technique is available only as a low-level function call (i.e., only by specifying property name/property value pairs). Create the patch by specifying the Faces, Vertices, and FaceVertexCData properties as well as the FaceColor property.
patch('Faces',fac,'Vertices',vert,'FaceVertexCData',tcolor,... 'FaceColor','flat')
V22
1.9 1.8 1.7 1.6 1.5 1.4 1.3 1.2 1.1
V3
Face 1
Face 2
V1 0
1
0.2
0.4
0.6
0.8
1
V4
Specifying only unique vertices and their connection matrix can reduce the size of the data for patches having many faces. See the descriptions of the Faces, Vertices, and FaceVertexCData properties for information on how to define them.
2-24
patch
MATLAB does not require each face to have the same number of vertices. In cases where they do not, pad the Faces matrix with NaNs. To define a patch with faces that do not close, add one or more NaN to the row in the Vertices matrix that defines the vertex you do not want connected.
Object Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Uicontextmenu
Image
Light
Line
Patch
Rectangle
Surface
Text
Setting Default Properties
You can set default patch properties on the axes, figure, and root levels.
set(0,'DefaultPatchPropertyName',PropertyValue...) set(gcf,'DefaultPatchPropertyName',PropertyValue...) set(gca,'DefaultPatchPropertyName',PropertyValue...) PropertyName is the name of the patch property and PropertyValue is the value you are specifying. Use set and get to access patch properties.
Property List
The following table lists all patch properties and provides a brief description of each. The property name links take you to an expanded description of the properties.
Property Description Property Value
Property Name Data Defining the Object Faces
Connection matrix for Vertices
Values: m-by-n matrix Default: [1,2,3]
2-25
patch
Property Name Vertices
Property Description
Property Value
Matrix of x-, y-, and z-coordinates of the vertices (used with Faces) The x-coordinates of the vertices of the patch The y-coordinates of the vertices of the patch The z-coordinates of the vertices of the patch
Values: matrix Default: [0,1;1,1;0,0] Values: vector or matrix Default: [0;1;0] Values: vector or matrix Default: [1;1;0] Values: vector or matrix Default: [] empty matrix
XData
YData
ZData
Specifying Color
CData
Color data for use with the
XData/YData/ZData method
Values: scalar, vector, or matrix Default: [] empty matrix Values: scaled, direct Default: scaled Values: ColorSpec, none, flat, interp Default: ColorSpec Values: ColorSpec, none, flat, interp Default: ColorSpec Values: matrix Default: [] empty matrix Values: ColorSpec, none,
auto
CDataMapping EdgeColor
Controls mapping of CData to colormap Color of face edges
FaceColor
Color of face
FaceVertexCData
MarkerEdgeColor
Color data for use with
Faces/Vertices method
Color of marker or the edge color for filled markers Fill color for markers that are closed shapes
Default: auto
MarkerFaceColor
Values: ColorSpec, none,
auto
Default: none
Controlling the Effects of Lights
2-26
patch
Property Name AmbientStrength
Property Description
Property Value
Intensity of the ambient light Controls lighting of faces pointing away from camera Intensity of diffuse light Method used to light edges
Values: scalar >=0 and <=1 Default: 0.3 Values: unlit, lit,
reverselit Default: reverselit
BackFaceLighting
DiffuseStrength
Values: scalar >=0 and <=1 Default: 0.6 Values: none, flat, gouraud, phong Default: none Values: none, flat, gouraud, phong Default: none Values: auto, manual Default: auto Values: scalar 0 to 1 Default: 1 Values: scalar >= 1 Default: 10 Values: scalar >=0 and <=1 Default: 0.9 Values: matrix
EdgeLighting
FaceLighting
Method used to light edges
NormalMode
SpecularColorReflectan ce SpecularExponent
MATLAB-generated or user-specified normal vectors Composite color of specularly reflected light Harshness of specular reflection Intensity of specular light Vertex normal vectors
SpecularStrength
VertexNormals
Defining Edges and Markers LineStyle
Select from five line styles. The width of the edge in points
Values: -, --, :, -., none Default: - Values: scalar Default: 0.5 points
LineWidth
2-27
patch
Property Name Marker
Property Description
Property Value
Marker symbol to plot at data points Size of marker in points
Values: see Marker property Default: none Values: size in points Default: 6
MarkerSize
Specifying Transparency AlphaDataMapping
Transparency mapping method Transparency of the edges of patch faces Transparency of the patch face Face and vertex transparency data
none, direct, scaled Default: scaled scalar, flat, interp Default: 1 (opaque) scalar, flat, interp Default: 1 (opaque)
EdgeAlpha
FaceAlpha
FaceVertexAlphaData Controlling the Appearance
m-by-1 matrix
Clipping EraseMode
Clipping to axes rectangle Method of drawing and erasing the patch (useful for animation) Highlight patch when selected (Selected property set to on) Make the patch visible or invisible
Values: on, off Default: on Values: normal, none, xor,
background Default: normal
SelectionHighlight
Values: on, off Default: on Values: on, off Default: on
Visible
Controlling Access to Objects HandleVisibility
Determines if and when the the patch's handle is visible to other functions
Values: on, callback, off Default: on
2-28
patch
Property Name HitTest
Property Description
Property Value
Determines if the patch can become the current object (see the figure CurrentObject property)
Values: on, off Default: on
Controlling Callback Routine Execution BusyAction
Specify how to handle callback routine interruption Define a callback routine that executes when a mouse button is pressed on over the patch Define a callback routine that executes when an patch is created Define a callback routine that executes when the patch is deleted (via close or delete) Determine if callback routine can be interrupted Associate a context menu with the patch
Values: cancel, queue Default: queue Values: string or function handle Default: '' (empty string) Values: string or function handle Default: '' (empty string) Values: string or function handle Default: '' (empty string) Values: on, off Default: on (can be interrupted) Values: handle of a Uicontrextmenu
ButtonDownFcn
CreateFcn
DeleteFcn
Interruptible
UIContextMenu
General Information About the Patch Children Parent
Patch objects have no children The parent of a patch object is always an axes object Indicate whether the patch is in a "selected" state. User-specified label
Values: [] (empty matrix) Value: axes handle Values: on, off Default: on Value: any string Default: '' (empty string)
Selected
Tag
2-29
patch
Property Name Type
Property Description
Property Value
The type of graphics object (read only) User-specified data
Value: the string 'patch' Values: any matrix Default: [] (empty matrix)
UserData
See Also
area, caxis, fill, fill3, isosurface, surface
2-30
Patch Properties
Modifying Properties
2Patch Properties
You can set and query graphics object properties in two ways: The Property Editor is an interactive tool that enables you to see and change object property values. The set and get commands enable you to set and query the values of properties To change the default value of properties see Setting Default Property Values.
Patch Property Descriptions
This section lists property names along with the type of values each accepts. Curly braces { } enclose default values.
AlphaDataMapping none | direct | {scaled}
Transparency mapping method. This property determines how MATLAB interprets indexed alpha data. This property can be any of the following: none - The transparency values of FaceVertexAlphaData are between 0 and 1 or are clamped to this range (the default). scaled - Transform the FaceVertexAlphaData to span the portion of the alphamap indicated by the axes ALim property, linearly mapping data values to alpha values. direct - use the FaceVertexAlphaData as indices directly into the alphamap. When not scaled, the data are usually integer values ranging from 1 to length(alphamap). MATLAB maps values less than 1 to the first alpha value in the alphamap, and values greater than length(alphamap) to the last alpha value in the alphamap. Values with a decimal portion are fixed to the nearest, lower integer. If FaceVertexAlphaData is an array unit8 integers, then the indexing begins at 0 (i.e., MATLAB maps a value of 0 to the first alpha value in the alphamap).
AmbientStrength
scalar >= 0 and <= 1
Strength of ambient light. This property sets the strength of the ambient light, which is a nondirectional light source that illuminates the entire scene. You must have at least one visible light object in the axes for the ambient light to be visible. The axes AmbientColor property sets the color of the ambient light, which is therefore the same on all objects in the axes. You can also set the strength of the diffuse and specular contribution of light objects. See the DiffuseStrength and SpecularStrength properties.
2-31
Patch Properties
BackFaceLighting
unlit | lit | {reverselit}
Face lighting control. This property determines how faces are lit when their vertex normals point away from the camera: unlit face is not lit lit face lit in normal way reverselit face is lit as if the vertex pointed towards the camera This property is useful for discriminating between the internal and external surfaces of an object. See the Using MATLAB Graphics manual for an example.
BusyAction cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control how MATLAB handles events that potentially interrupt executing callback routines. If there is a callback routine executing, subsequently invoked callback routes always attempt to interrupt it. If the Interruptible property of the object whose callback is executing is set to on (the default), then interruption occurs at the next point where the event queue is processed. If the Interruptible property is off, the BusyAction property (of the object owning the executing callback) determines how MATLAB handles the event. The choices are: cancel discard the event that attempted to execute a second callback routine. queue queue the event that attempted to execute a second callback routine until the current callback finishes.
ButtonDownFcn
string or function handle
Button press callback routine. A callback routine that executes whenever you press a mouse button while the pointer is over the patch object. Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace. See Function Handle Callbacks for information on how to use function handles to define the callback function.
CData
scalar, vector, or matrix
Patch colors. This property specifies the color of the patch. You can specify color for each vertex, each face, or a single color for the entire patch. The way
2-32
Patch Properties
MATLAB interprets CData depends on the type of data supplied. The data can be numeric values that are scaled to map linearly into the current colormap, integer values that are used directly as indices into the current colormap, or arrays of RGB values. RGB values are not mapped into the current colormap, but interpreted as the colors defined. On true color systems, MATLAB uses the actual colors defined by the RGB triples. On pseudocolor systems, MATLAB uses dithering to approximate the RGB triples using the colors in the figure's Colormap and Dithermap. The following two diagrams illustrate the dimensions of CData with respect to the coordinate data arrays, XData, YData, and ZData. The first diagram illustrates the use of indexed color.
Single Color
One Color Per Face
One Color Per Vertex
CData
CData CData [X,Y,Z]Data [X,Y,Z]Data
F a c e 1
F a c e 2
F a c e 3
F a c e 4
F a c e 5
[X,Y,Z]Data
2-33
Patch Properties
The second diagram illustrates the use of true color. True color requires m-by-n-by-3 arrays to define red, green, and blue components for each color. Single Color
CData
One Color Per Face
One Color Per Vertex Blue Green Red
B G R
[X,Y,Z]Data
B G R
CData [X,Y,Z]Data
CData
F a c e 1
F a c e 2
F a c e 3
F a c e 4
F a c e 5
[X,Y,Z]Data
Note that if CData contains NaNs, MATLAB does not color the faces. See also the Faces, Vertices, and FaceVertexCData properties for an alternative method of patch definition.
CDataMapping {scaled} | direct
Direct or scaled color mapping. This property determines how MATLAB interprets indexed color data used to color the patch. (If you use true color specification for CData or FaceVertexCData, this property has no effect.) scaled transform the color data to span the portion of the colormap indicated by the axes CLim property, linearly mapping data values to colors. See the caxis command for more information on this mapping. direct use the color data as indices directly into the colormap. When not scaled, the data are usually integer values ranging from 1 to
2-34
Patch Properties
length(colormap). MATLAB maps values less than 1 to the first color in the colormap, and values greater than length(colormap) to the last color in
the colormap. Values with a decimal portion are fixed to the nearest, lower integer.
Children
matrix of handles
Always the empty matrix; patch objects have no children.
Clipping {on} | off
Clipping to axes rectangle. When Clipping is on, MATLAB does not display any portion of the patch outside the axes rectangle.
CreateFcn
string or function handle
Callback routine executed during object creation. This property defines a callback routine that executes when MATLAB creates a patch object. You must define this property as a default value for patches. For example, the statement,
set(0,'DefaultPatchCreateFcn','set(gcf,''DitherMap'',my_dither_ map)')
defines a default value on the root level that sets the figure DitherMap property whenever you create a patch object. MATLAB executes this routine after setting all properties for the patch created. Setting this property on an existing patch object has no effect. The handle of the object whose CreateFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo. See Function Handle Callbacks for information on how to use function handles to define the callback function.
DeleteFcn
string or function handle
Delete patch callback routine. A callback routine that executes when you delete the patch object (e.g., when you issue a delete command or clear the axes (cla) or figure (clf) containing the patch). MATLAB executes the routine before deleting the object's properties so these values are available to the callback routine. The handle of the object whose DeleteFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo.
2-35
Patch Properties
See Function Handle Callbacks for information on how to use function handles to define the callback function.
DiffuseStrength
scalar >= 0 and <= 1
Intensity of diffuse light. This property sets the intensity of the diffuse component of the light falling on the patch. Diffuse light comes from light objects in the axes. You can also set the intensity of the ambient and specular components of the light on the patch object. See the AmbientStrength and SpecularStrength properties.
EdgeAlpha {scalar = 1} | flat | interp
Transparency of the edges of patch faces. This property can be any of the following: scalar - A single non-Nan scalar value between 0 and 1 that controls the transparency of all the edges of the object. 1 (the default) is fully opaque and 0 means completely transparent. flat - The alpha data (FaceVertexAlphaData) of each vertex controls the transparency of the edge that follows it. interp - Linear interpolation of the alpha data (FaceVertexAlphaData) at each vertex determines the transparency of the edge. Note that you cannot specify flat or interp EdgeAlpha without first setting FaceVertexAlphaData to a matrix containing one alpha value per face (flat) or one alpha value per vertex (interp).
EdgeColor {ColorSpec} | none | flat | interp
Color of the patch edge. This property determines how MATLAB colors the edges of the individual faces that make up the patch. ColorSpec A three-element RGB vector or one of the MATLAB predefined names, specifying a single color for edges. The default edge color is black. See ColorSpec for more information on specifying color. none Edges are not drawn.
2-36
Patch Properties
flat The color of each vertex controls the color of the edge that follows it. This means flat edge coloring is dependent on the order you specify the vertices:
Vertex controlling the color of the following edge
interp Linear interpolation of the CData or FaceVertexCData values at the vertices determines the edge color.
EdgeLighting {none} | flat | gouraud | phong
Algorithm used for lighting calculations. This property selects the algorithm used to calculate the effect of light objects on patch edges. Choices are: none Lights do not affect the edges of this object. flat The effect of light objects is uniform across each edge of the patch. gouraud The effect of light objects is calculated at the vertices and then linearly interpolated across the edge lines. phong The effect of light objects is determined by interpolating the vertex normals across each edge line and calculating the reflectance at each pixel. Phong lighting generally produces better results than Gouraud lighting, but takes longer to render.
EraseMode {normal} | none | xor | background
Erase mode. This property controls the technique MATLAB uses to draw and erase patch objects. Alternative erase modes are useful in creating animated sequences, where control of the way individual objects redraw is necessary to improve performance and obtain the desired effect. normal Redraw the affected region of the display, performing the three-dimensional analysis necessary to ensure that all objects are rendered correctly. This mode produces the most accurate picture, but is the slowest.
2-37
Patch Properties
The other modes are faster, but do not perform a complete redraw and are therefore less accurate. none Do not erase the patch when it is moved or destroyed. While the object is still visible on the screen after erasing with EraseMode none, you cannot print it because MATLAB stores no information about its former location. xor Draw and erase the patch by performing an exclusive OR (XOR) with each pixel index of the screen behind it. Erasing the patch does not damage the color of the objects behind it. However, patch color depends on the color of the screen behind it and is correctly colored only when over the axes background Color, or the figure background Color if the axes Color is set to none. background Erase the patch by drawing it in the axes' background Color, or the figure background Color if the axes Color is set to none. This damages objects that are behind the erased patch, but the patch is always properly colored.
Printing with Non-normal Erase Modes. MATLAB always prints figures as if the EraseMode of all objects is normal. This means graphics objects created with EraseMode set to none, xor, or background can look different on screen than on
paper. On screen, MATLAB may mathematically combine layers of colors (e.g., XORing a pixel color with that of the pixel behind it) and ignore three-dimensional sorting to obtain greater rendering speed. However, these techniques are not applied to the printed output. You can use the MATLAB getframe command or other screen capture application to create an image of a figure containing non-normal mode objects.
FaceAlpha {scalar = 1} | flat | interp
Transparency of the patch face. This property can be any of the following: A scalar - A single non-NaN scalar value between 0 and 1 that controls the transparency of all the faces of the object. 1 (the default) is fully opaque and 0 is completely transparent (invisible). flat - The values of the alpha data (FaceVertexAlphaData) determine the transparency for each face. The alpha data at the first vertex determines the transparency of the entire face. interp - Bilinear interpolation of the alpha data (FaceVertexAlphaData) at each vertex determine the transparency of each face.
2-38
Patch Properties
Note that you cannot specify flat or interp FaceAlpha without first setting FaceVertexAlphaData to a matrix containing one alpha value per face (flat) or one alpha value per vertex (interp).
FaceColor {ColorSpec} | none | flat | interp
Color of the patch face. This property can be any of the following: ColorSpec A three-element RGB vector or one of the MATLAB predefined names, specifying a single color for faces. See ColorSpec for more information on specifying color. none Do not draw faces. Note that edges are drawn independently of faces. flat The values of CData or FaceVertexCData determine the color for each face in the patch. The color data at the first vertex determines the color of the entire face. interp Bilinear interpolation of the color at each vertex determines the coloring of each face.
FaceLighting {none} | flat | gouraud | phong
Algorithm used for lighting calculations. This property selects the algorithm used to calculate the effect of light objects on patch faces. Choices are: none Lights do not affect the faces of this object. flat The effect of light objects is uniform across the faces of the patch. Select this choice to view faceted objects. gouraud The effect of light objects is calculated at the vertices and then linearly interpolated across the faces. Select this choice to view curved surfaces. phong The effect of light objects is determined by interpolating the vertex normals across each face and calculating the reflectance at each pixel. Select this choice to view curved surfaces. Phong lighting generally produces better results than Gouraud lighting, but takes longer to render.
Faces
m-by-n matrix
Vertex connection defining each face. This property is the connection matrix specifying which vertices in the Vertices property are connected. The Faces matrix defines m faces with up to n vertices each. Each row designates the connections for a single face, and the number of elements in that row that are not NaN defines the number of vertices for that face.
2-39
Patch Properties
The Faces and Vertices properties provide an alternative way to specify a patch that can be more efficient than using x, y, and z coordinates in most cases. For example, consider the following patch. It is composed of eight triangular faces defined by nine vertices.
Faces property Vertices property
V7
2 1.8 1.6 1.4 1.2
V8
V9 F1 V1 V4 V5 5 V1 V5 V2 5 V2 V5 V6 5 V2 V6 V3 V4 V7 V8 V4 V8 V5 7 V1 X1 Y1 Z1 V2 X2 Y2 Z2 V3 X3 Y3 Z3 V4 X4 Y4 Z4 V5 X5 Y5 Z5 V6 X6 Y6 Z6 V7 X7 Y7 Z7 V8 X8 Y8 Z8 V9 X9 Y9 Z9 F2 F8 F3 V6 F3 F4 F5 F6 F4
F5 F6 V5 F1 F2
0.2 0.4 0.6 0.8 1
F7
V4 1
0.8 0.6 0.4 0.2 0 0
F7 V5 V8 V9 F8 5 5 V9 V6 V
1.8 2
V1
V2
1.2
1.4
1.6
V3
The corresponding Faces and Vertices properties are shown to the right of the patch. Note how some faces share vertices with other faces. For example, the fifth vertex (V5) is used six times, once each by faces one, two, and three and six, seven, and eight. Without sharing vertices, this same patch requires 24 vertex definitions.
FaceVertexAlphaDatam-by-1 matrix
Face and vertex transparency data. The FaceVertexAlphaData property specifies the tranparency of patches defined by the Faces and Vertices properties. The interpretation of the values specified for FaceVertexAlphaData depends on the dimensions of the data.
FaceVertexAlphaData can be one of the following:
A single value, which applies the same transparency to the entire patch. An m-by-1 matrix (where m is the number of rows in the Faces property), which specifies one transparency value per face.
2-40
Patch Properties
An m-by-1 matrix (where m is the number of rows in the Vertices property), which specifies one transparency value per vertex.
FaceVertexCData
matrix
Face and vertex colors. The FaceVertexCData property specifies the color of patches defined by the Faces and Vertices properties, and the values are used when FaceColor, EdgeColor, MarkerFaceColor, or MarkerEdgeColor are set appropriately. The interpretation of the values specified for FaceVertexCData depends on the dimensions of the data. For indexed colors, FaceVertexCData can be: A single value, which applies a single color to the entire patch An n-by-1 matrix, where n is the number of rows in the Faces property, which specifies one color per face An n-by-1 matrix, where n is the number of rows in the Vertices property, which specifies one color per vertex For true colors, FaceVertexCData can be: A 1-by-3 matrix , which applies a single color to the entire patch An n-by-3 matrix, where n is the number of rows in the Faces property, which specifies one color per face An n-by-3 matrix, where n is the number of rows in the Vertices property, which specifies one color per vertex The following diagram illustrates the various forms of the FaceVertexCData property for a patch having eight faces and nine vertices. The CDataMapping
2-41
Patch Properties
property determines how MATLAB interprets the FaceVertexCData property when you specify indexed colors.
FaceVertexCData
Indexed
True color
One color Single color per face C C1 C2 C3 C4 C5 C6 C7 C8
One color per vertex C1 C2 C3 C4 C5 C6 C7 C8 C9
Single color R G B
One color per face R1 G1 B1 R2 G2 B2 R3 G3 B3 R4 G4 B4 R5 G5 B5 R6 G6 B6 R7 G7 B7 R8 G8 B8
One color per vertex R1 G1 B1 R2 G2 B2 R3 G3 B3 R4 G4 B4 R5 G5 B5 R6 G6 B6 R7 G7 B7 R8 G8 B8 R9 B9 B9
HandleVisibility
{on} | callback | off
Control access to object's handle by command-line users and GUIs. This property determines when an object's handle is visible in its parent's list of children. HandleVisibility is useful for preventing command-line users from accidentally drawing into or deleting a figure that contains only user interface devices (such as a dialog box). Handles are always visible when HandleVisibility is on. Setting HandleVisibility to callback causes handles to be visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provides a means to
2-42
Patch Properties
protect GUIs from command-line users, while allowing callback routines to have complete access to object handles. Setting HandleVisibility to off makes handles invisible at all times. This may be necessary when a callback routine invokes a function that might potentially damage the GUI (such as evaluating a user-typed string), and so temporarily hides its own handles during the execution of that function. When a handle is not visible in its parent's list of children, it cannot be returned by functions that obtain handles by searching the object hierarchy or querying handle properties. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close. When a handle's visibility is restricted using callback or off, the object's handle does not appear in its parent's Children property, figures do not appear in the root's CurrentFigure property, objects do not appear in the root's CallbackObject property or in the figure's CurrentObject property, and axes do not appear in their parent's Currentaxes property. You can set the root ShowHiddenHandles property to on to make all handles visible, regardless of their HandleVisibility settings (this does not affect the values of the HandleVisibility properties). Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.
HitTest {on} | off
Selectable by mouse click. HitTest determines if the patch can become the current object (as returned by the gco command and the figure CurrentObject property) as a result of a mouse click on the patch. If HitTest is off, clicking on the patch selects the object below it (which maybe the axes containing it).
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls whether a patch callback routine can be interrupted by subsequently invoked callback routines. Only callback routines defined for the ButtonDownFcn are affected by the Interruptible property. MATLAB checks for events that can interrupt a callback routine only when it encounters a drawnow, figure, getframe, or pause command in the routine. See the BusyAction property for related information.
2-43
Patch Properties
{-} | -- | : | -. | none
LineStyle
Edge linestyle. This property specifies the line style of the patch edges. The following table lists the available line styles.
Symbol Line Style
- --
:
solid line (default) dashed line dotted line dash-dot line no line
-.
none
You can use LineStyle none when you want to place a marker at each point but do not want the points connected with a line (see the Marker property).
LineWidth
scalar
Edge line width. The width, in points, of the patch edges (1 point = 1/72 inch). The default LineWidth is 0.5 points.
Marker
character (see table)
Marker symbol. The Marker property specifies marks that locate vertices. You can set values for the Marker property independently from the LineStyle property. The following tables lists the available markers.
Marker Specifier + o * . x s Description
plus sign circle asterisk point cross square
2-44
Patch Properties
Marker Specifier d ^ v > < p h none MarkerEdgeColor
Description
diamond upward pointing triangle downward pointing triangle right pointing triangle left pointing triangle five-pointed star (pentagram) six-pointed star (hexagram) no marker (default)
ColorSpec | none | {auto} | flat
Marker edge color. The color of the marker or the edge color for filled markers (circle, square, diamond, pentagram, hexagram, and the four triangles). ColorSpec defines the color to use. none specifies no color, which makes nonfilled markers invisible. auto sets MarkerEdgeColor to the same color as the EdgeColor property.
MarkerFaceColor ColorSpec | {none} | auto | flat
Marker face color. The fill color for markers that are closed shapes (circle, square, diamond, pentagram, hexagram, and the four triangles). ColorSpec defines the color to use. none makes the interior of the marker transparent, allowing the background to show through. auto sets the fill color to the axes color, or the figure color, if the axes Color property is set to none.
MarkerSize
size in points
Marker size. A scalar specifying the size of the marker, in points. The default value for MarkerSize is six points (1 point = 1/72 inch). Note that MATLAB draws the point marker at 1/3 of the specified size.
2-45
Patch Properties
NormalMode
{auto} | manual
MATLAB-generated or user-specified normal vectors. When this property is auto, MATLAB calculates vertex normals based on the coordinate data. If you specify your own vertex normals, MATLAB sets this property to manual and does not generate its own data. See also the VertexNormals property.
Parent
axes handle
Patch's parent. The handle of the patch's parent object. The parent of a patch object is the axes in which it is displayed. You can move a patch object to another axes by setting this property to the handle of the new parent.
Selected on | {off}
Is object selected? When this property is on, MATLAB displays selection handles or a dashed box (depending on the number of faces) if the SelectionHighlight property is also on. You can, for example, define the ButtonDownFcn to set this property, allowing users to select the object with the mouse.
SelectionHighlight {on} | off
Objects highlight when selected. When the Selected property is on, MATLAB indicates the selected state by: Drawing handles at each vertex for a single-faced patch. Drawing a dashed bounding box for a multi-faced patch. When SelectionHighlight is off, MATLAB does not draw the handles.
SpecularColorReflectancescalar in the range 0 to 1
Color of specularly reflected light. When this property is 0, the color of the specularly reflected light depends on both the color of the object from which it reflects and the color of the light source. When set to 1, the color of the specularly reflected light depends only on the color or the light source (i.e., the light object Color property). The proportions vary linearly for values in between.
SpecularExponent
scalar >= 1
Harshness of specular reflection. This property controls the size of the specular spot. Most materials have exponents in the range of 5 to 20.
2-46
Patch Properties
SpecularStrength
scalar >= 0 and <= 1
Intensity of specular light. This property sets the intensity of the specular component of the light falling on the patch. Specular light comes from light objects in the axes. You can also set the intensity of the ambient and diffuse components of the light on the patch object. See the AmbientStrength and DiffuseStrength properties.
Tag
string
User-specified object label. The Tag property provides a means to identify graphics objects with a user-specified label. This is particularly useful when constructing interactive graphics programs that would otherwise need to define object handles as global variables or pass them as arguments between callback routines. For example, suppose you use patch objects to create borders for a group of uicontrol objects and want to change the color of the borders in a uicontrol's callback routine. You can specify a Tag with the patch definition:
patch(X,Y,'k','Tag','PatchBorder')
Then use findobj in the uicontrol's callback routine to obtain the handle of the patch and set its FaceColor property.
set(findobj('Tag','PatchBorder'),'FaceColor','w') Type
string (read only)
Class of the graphics object. For patch objects, Type is always the string 'patch'.
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the patch. Assign this property the handle of a uicontextmenu object created in the same figure as the patch. Use the uicontextmenu function to create the context menu. MATLAB displays the context menu whenever you right-click over the patch.
UserData
matrix
User-specified data. Any matrix you want to associate with the patch object. MATLAB does not use this data, but you can access it using set and get.
2-47
Patch Properties
VertexNormals
matrix
Surface normal vectors. This property contains the vertex normals for the patch. MATLAB generates this data to perform lighting calculations. You can supply your own vertex normal data, even if it does not match the coordinate data. This can be useful to produce interesting lighting effects.
Vertices
matrix
Vertex coordinates. A matrix containing the x-, y-, z-coordinates for each vertex. See the Faces property for more information.
Visible {on} | off
Patch object visibility. By default, all patches are visible. When set to off, the patch is not visible, but still exists and you can query and set its properties.
XData
vector or matrix
X-coordinates. The x-coordinates of the patch vertices. If XData is a matrix, each column represents the x-coordinates of a single face of the patch. In this case, XData, YData, and ZData must have the same dimensions.
YData
vector or matrix
Y-coordinates. The y-coordinates of the patch vertices. If YData is a matrix, each column represents the y-coordinates of a single face of the patch. In this case, XData, YData, and ZData must have the same dimensions.
ZData
vector or matrix
Z-coordinates. The z-coordinates of the patch vertices. If ZData is a matrix, each column represents the z-coordinates of a single face of the patch. In this case, XData, YData, and ZData must have the same dimensions.
See Also
patch
2-48
path
Purpose Graphical Interface Syntax
2path
View or change the MATLAB directory search path As an alternative to the path function, use the Set Path dialog box. To open it, select Set Path from the File menu in the MATLAB desktop.
path path('newpath') path(path,'newpath') path('newpath',path) p = path(...) path displays the current MATLAB search path. The initial search path list is defined by toolbox/local/pathdef.m. path('newpath') changes the search path to newpath, where newpath is a
Description
string array of directories.
path(path,'newpath') appends a new directory to the current search path. path('newpath',path) prepends a new directory to the current search path. p = path(...) returns the specified path in string variable p.
Remarks
For more information on how MATLAB uses the directory search path, see "Search Path", "How Functions Work", and "How MATLAB Determines Which Method to Call".
Note Save any M-files you create and any MathWorks-supplied M-files that you edit in a directory that is not in the $matlabroot/toolbox directory tree. If you keep your files in $matlabroot/toolbox directories, they may be overwritten when you install a new version of MATLAB. Also note that locations of files in $matlabroot/toolbox directories are loaded and cached in memory at the beginning of each MATLAB session to improve performance. If you edit and save files in $matlabroot/toolbox directories using the Editor, run clear functions to ensure that the updated files are used. If you save files to $matlabroot/toolbox directories using an external editor or add or remove in from these directories using file system operations, run rehash toolbox before you use the files in the current session. If you make
2-49
path
changes to existing files in $matlabroot/toolbox directories using an external editor, run clear functionname before you use the files in the current session. For more information, see rehash or "Toolbox Path Caching" in MATLAB Development Environment documentation.
Examples
To add a new directory to the search path on Windows,
path(path,'c:/tools/goodstuff')
To add a new directory to the search path on UNIX,
path(path,'/home/tools/goodstuff')
See Also
addpath, cd, dir, genpath, matlabroot, partialpath, pathtool, rehash, rmpath, what
2-50
path2rc
Purpose Graphical Interface Syntax Description
2path2rc
Save current MATLAB search path to pathdef.m file As an alternative to the pathdef function, use the Set Path dialog box. To open it, select Set Path from the File menu in the MATLAB desktop.
path2rc path2rc newfile path2rc saves the current MATLAB search path to pathdef.m. It returns 0 1
If the file was saved successfully If the save failed
path2rc newfile saves the current MATLAB search path to newfile, where newfile is in the current directory or is a relative or absolute path.
Examples
path2rc myfiles/newpath
saves the current search path to the file newpath.m, which is located in the myfiles directory in the MATLAB current directory.
See Also
path, pathtool
2-51
pathtool
Purpose Graphical Interface Syntax Description
2pathtool
Open Set Path dialog box to view and change MATLAB path As an alternative to the pathtool function, select Set Path from the File menu in the MATLAB desktop.
pathtool pathtool opens the Set Path dialog box, a graphical user interface you use to
view and modify the MATLAB search path, as well as see files on the path.
When you press one of these buttons, the change is made to the current search path, but the search path is not automatically saved for future sessions.
Directories on the current MATLAB search path.
Make changes to the search path.
Save changes for use in the next MATLAB session.
See Also
addpath, edit, path, rmpath, workspace
"Setting the Search Path"
2-52
pause
Purpose Syntax
2pause
Halt execution temporarily
pause pause(n) pause on pause off pause, by itself, causes M-files to stop and wait for you to press any key before
Description
continuing.
pause(n) pauses execution for n seconds before continuing, where n can be any
real number. The resolution of the clock is platform specific. A fractional pause of 0.01 seconds should be supported on most platforms.
pause on allows subsequent pause commands to pause execution. pause off ensures that any subsequent pause or pause(n) statements do not pause execution. This allows normally interactive scripts to run unattended.
See Also
drawnow
2-53
pbaspect
Purpose Syntax
2pbaspect
Set or query the plot box aspect ratio
pbaspect pbaspect([aspect_ratio]) pbaspect('mode') pbaspect('auto') pbaspect('manual') pbaspect(axes_handle,...)
Description
The plot box aspect ratio determines the relative size of the x-, y-, and z-axes.
pbaspect with no arguments returns the plot box aspect ratio of the current
axes.
pbaspect([aspect_ratio]) sets the plot box aspect ratio in the current axes to the specified value. Specify the aspect ratio as three relative values representing the ratio of the x-, y-, and z-axes size. For example, a value of [1 1 1] (the default) means the plot box is a cube (although with stretch-to-fill enabled, it may not appear as a cube). See Remarks. pbaspect('mode') returns the current value of the plot box aspect ratio mode, which can be either auto (the default) or manual. See Remarks. pbaspect('auto') sets the plot box aspect ratio mode to auto. pbaspect('manual') sets the plot box aspect ratio mode to manual. pbaspect(axes_handle,...) performs the set or query on the axes identified by the first argument, axes_handle. If you do not specify an axes handle, pbaspect operates on the current axes.
Remarks
pbaspect sets or queries values of the axes object PlotBoxAspectRatio and PlotBoxAspectRatioMode properties.
When the plot box aspect ratio mode is auto, MATLAB sets the ratio to [1 1 1], but may change it to accommodate manual settings of the data aspect ratio, camera view angle, or axis limits. See the axes DataAspectRatio property for a table listing the interactions between various properties.
2-54
pbaspect
Setting a value for the plot box aspect ratio or setting the plot box aspect ratio mode to manual disables the MATLAB stretch-to-fill feature (stretching of the axes to fit the window). This means setting the plot box aspect ratio to its current value,
pbaspect(pbaspect)
can cause a change it the way the graphs look. See the Remarks section of the axes reference description and the "Aspect Ratio" section in the Using MATLAB Graphics manual for a discussion of stretch-to-fill.
Examples
The following surface plot of the function z = xe ( x y ) is useful to illustrate the plot box aspect ratio. First plot the function over the range 2 x 2, 2 y 2,
2 2
[x,y] = meshgrid([-2:.2:2]); z = x.*exp(-x.^2 - y.^2); surf(x,y,z)
0.5
0
-0.5 2 1 0 -1 -2 -2 0 -1 1 2
Querying the plot box aspect ratio shows that the plot box is square.
pbaspect ans = 1 1
1
2-55
pbaspect
It is also interesting to look at the data aspect ratio selected by MATLAB.
daspect ans = 4 4
1
To illustrate the interaction between the plot box and data aspect ratios, set the data aspect ratio to [1 1 1] and again query the plot box aspect ratio.
daspect([1 1 1])
0.5
0
-0.5 2 1.5 1 0.5 0 -0.5 -1 -1.5 -2 -2 -1 0 1 2
pbaspect ans = 4 4
1
The plot box aspect ratio has changed to accommodate the specified data aspect ratio. Now suppose you want the plot box aspect ratio to be [1 1 1] as well.
2-56
pbaspect
pbaspect([1 1 1])
2 1.5 1 0.5 0 -0.5 -1 -1.5 -2 2 1 0 0 -1 -2 -2 -1 1 2
Notice how MATLAB changed the axes limits because of the constraints introduced by specifying both the plot box and data aspect ratios. You can also use pbaspect to disable stretch-to-fill. For example, displaying two subplots in one figure can give surface plots a squashed appearance. Disabling stretch-to-fill.
upper_plot = subplot(211); surf(x,y,z) lower_plot = subplot(212); surf(x,y,z) pbaspect(upper_plot,'manual')
2-57
pbaspect
0.5
0
-0.5 2 0 -2 -2 2 0
0.5
0
-0.5 2 1 0 -1 -2 -2 -1 0 1 2
See Also
axis, daspect, xlim, ylim, zlim
The axes properties DataAspectRatio, PlotBoxAspectRatio, XLim, YLim, ZLim The "Aspect Ratio" section in the Using MATLAB Graphics manual.
2-58
pcg
Purpose Syntax
2pcg
Preconditioned Conjugate Gradients method
x = pcg(A,b) pcg(A,b,tol) pcg(A,b,tol,maxit) pcg(A,b,tol,maxit,M) pcg(A,b,tol,maxit,M1,M2) pcg(A,b,tol,maxit,M1,M2,x0) pcg(A,b,tol,maxit,M1,M2,x0,p1,p2,...) [x,flag] = pcg(A,b,tol,maxit,M1,M2,x0,p1,p2,...) [x,flag,relres] = pcg(A,b,tol,maxit,M1,M2,x0,p1,p2,...) [x,flag,relres,iter] = pcg(A,b,tol,maxit,M1,M2,x0,p1,p2,...) [x,flag,relres,iter,resvec] = pcg(A,b,tol,maxit,M1,M2,x0,p1,p2,...) x = pcg(A,b) attempts to solve the system of linear equations A*x=b for x. The n-by-n coefficient matrix A must be symmetric and positive definite, and should also be large and sparse. The column vector b must have length n. A can be a function afun such that afun(x) returns A*x.
Description
If pcg converges, a message to that effect is displayed. If pcg fails to converge after the maximum number of iterations or halts for any reason, a warning message is printed displaying the relative residual norm(b-A*x)/norm(b) and the iteration number at which the method stopped or failed.
pcg(A,b,tol) specifies the tolerance of the method. If tol is [], then pcg uses the default, 1e-6. pcg(A,b,tol,maxit) specifies the maximum number of iterations. If maxit is [], then pcg uses the default, min(n,20). pcg(A,b,tol,maxit,M) and pcg(A,b,tol,maxit,M1,M2) use symmetric positive definite preconditioner M or M = M1*M2 and effectively solve the system inv(M)*A*x = inv(M)*b for x. If M is [] then pcg applies no preconditioner. M can be a function that returns M\x. pcg(A,b,tol,maxit,M1,M2,x0) specifies the initial guess. If x0 is [], then pcg
uses the default, an all-zero vector.
2-59
pcg
pcg(afun,b,tol,maxit,m1fun,m2fun,x0,p1,p2,...) passes parameters p1,p2,... to functions afun(x,p1,p2,...), m1fun(x,p1,p2,...), and m2fun(x,p1,p2,...). [x,flag] = pcg(A,b,tol,maxit,M1,M2,x0) also returns a convergence flag. Flag 0 Convergence pcg converged to the desired tolerance tol within maxit
iterations.
1 2 3 4 pcg iterated maxit times but did not converge.
Preconditioner M was ill-conditioned.
pcg stagnated. (Two consecutive iterates were the same.)
One of the scalar quantities calculated during pcg became too small or too large to continue computing.
Whenever flag is not 0, the solution x returned is that with minimal norm residual computed over all the iterations. No messages are displayed if the flag output is specified.
[x,flag,relres] = pcg(A,b,tol,maxit,M1,M2,x0) also returns the relative residual norm(b-A*x)/norm(b). If flag is 0, relres <= tol. [x,flag,relres,iter] = pcg(A,b,tol,maxit,M1,M2,x0) also returns the iteration number at which x was computed, where 0 <= iter <= maxit. [x,flag,relres,iter,resvec] = pcg(A,b,tol,maxit,M1,M2,x0) also
returns a vector of the residual norms at each iteration including norm(b-A*x0).
Examples
Example 1.
A = gallery('wilk',21); b = sum(A,2); tol = 1e-12; maxit = 15; M = diag([10:-1:1 1 1:10]);
2-60
pcg
[x,flag,rr,iter,rv] = pcg(A,b,tol,maxit,M);
Alternatively, use this one-line matrix-vector product function
function y = afun(x,n) y = [0; x(1:n-1)] + [((n-1)/2:-1:0)'; (1:(n-1)/2)'].*x + [x(2:n); 0];
and this one-line preconditioner backsolve function
function y = mfun(r,n) y = r ./ [((n-1)/2:-1:1)'; 1; (1:(n-1)/2)'];
as inputs to pcg
[x1,flag1,rr1,iter1,rv1] = pcg(@afun,b,tol,maxit,@mfun,... [],[],21);
Example 2.
A = delsq(numgrid('C',25)); b = ones(length(A),1); [x,flag] = pcg(A,b) flag is 1 because pcg does not converge to the default tolerance of 1e-6 within
the default 20 iterations.
R = cholinc(A,1e-3); [x2,flag2,relres2,iter2,resvec2] = pcg(A,b,1e-8,10,R',R) flag2 is 0 because pcg converges to the tolerance of 1.2e-9 (the value of relres2) at the sixth iteration (the value of iter2) when preconditioned by the incomplete Cholesky factorization with a drop tolerance of 1e-3. resvec2(1) = norm(b) and resvec2(7) = norm(b-A*x2). You can follow the progress of pcg by plotting the relative residuals at each iteration starting from
the initial estimate (iterate number 0).
semilogy(0:iter2,resvec2/norm(b),'-o') xlabel('iteration number') ylabel('relative residual')
2-61
pcg
10
0
10
-1
10
-2
10 relative residual
-3
10
-4
10
-5
10
-6
10
-7
10
-8
10
-9
0
1
2
3 iteration number
4
5
6
See Also
bicg, bicgstab, cgs, cholinc, gmres, lsqr, minres, qmr, symmlq @ (function handle), \ (backslash)
References
[1] Barrett, R., M. Berry, T. F. Chan, et al., Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia, 1994.
2-62
pchip
Purpose Syntax Description
2pchip
Piecewise Cubic Hermite Interpolating Polynomial (PCHIP)
yi = pchip(x,y,xi) pp = pchip(x,y) yi = pchip(x,y,xi) returns vector yi containing elements corresponding to the elements of xi and determined by piecewise cubic interpolation within vectors x and y. The vector x specifies the points at which the data y is given. If y is a matrix, then the interpolation is performed for each column of y and yi is length(xi)-by-size(y,2). pp = pchip(x,y) returns a piecewise polynomial structure for use by ppval. x can be a row or column vector. y is a row or column vector of the same length as x, or a matrix with length(x) columns. pchip finds values of an underlying interpolating function P ( x ) at
intermediate points, such that: On each subinterval x k x x k + 1 , P ( x ) is the cubic Hermite interpolant to the given values and certain slopes at the two endpoints. P ( x ) interpolates y , i.e., P ( x j ) = y j, and the first derivative P ( x ) is continuous. P ( x ) is probably not continuous; there may be jumps at the x j . The slopes at the x j are chosen in such a way that P ( x ) preserves the shape of the data and respects monotonicity. This means that, on intervals where the data are monotonic, so is P ( x ) ; at points where the data has a local extremum, so does P ( x ) . Note If y is a matrix, P ( x ) satisfies the above for each column of y .
Remarks
spline constructs S ( x ) in almost the same way pchip constructs P ( x ) . However, spline chooses the slopes at the x j differently, namely to make even
S ( x ) continuous. This has the following effects:
spline produces a smoother result, i.e. S ( x ) is continuous. spline produces a more accurate result if the data consists of values of a smooth function.
2-63
pchip
pchip has no overshoots and less oscillation if the data are not smooth. pchip is less expensive to set up. The two are equally expensive to evaluate.
Examples
x = -3:3; y = [-1 -1 -1 0 1 1 1]; t = -3:.01:3; p = pchip(x,y,t); s = spline(x,y,t); plot(x,y,'o',t,p,'-',t,s,'-.') legend('data','pchip','spline',4)
1.5
1
0.5
0
-0.5
-1
data pchip spline
-1.5 -3
-2
-1
0
1
2
3
See Also References
interp1, spline, ppval
[1] Fritsch, F. N. and R. E. Carlson, "Monotone Piecewise Cubic Interpolation," SIAM J. Numerical Analysis, Vol. 17, 1980, pp.238-246. [2] Kahaner, David, Cleve Moler, Stephen Nash, Numerical Methods and Software, Prentice Hall, 1988.
2-64
pcode
Purpose Syntax
2pcode
Create preparsed pseudocode file (P-file)
pcode fun pcode *.m pcode fun1 fun2 ... pcode... -inplace pcode fun parses the M-file fun.m into the P-file fun.p and puts it into the current directory. The original M-file can be anywhere on the search path. pcode *.m creates P-files for all the M-files in the current directory. pcode fun1 fun2 ... creates P-files for the listed functions. pcode... -inplace creates P-files in the same directory as the M-files. An
Description
error occurs if the files can't be created.
2-65
pcolor
Purpose Syntax
2pcolor
Pseudocolor plot
pcolor(C) pcolor(X,Y,C) h = pcolor(...)
Description
A pseudocolor plot is a rectangular array of cells with colors determined by C. MATLAB creates a pseudocolor plot by using each set of four adjacent points in C to define a surface patch (i.e., cell).
pcolor(C) draws a pseudocolor plot. The elements of C are linearly mapped to an index into the current colormap. The mapping from C to the current colormap is defined by colormap and caxis. pcolor(X,Y,C) draws a pseudocolor plot of the elements of C at the locations specified by X and Y. The plot is a logically rectangular, two-dimensional grid with vertices at the points [X(i,j), Y(i,j)]. X and Y are vectors or matrices that specify the spacing of the grid lines. If X and Y are vectors, X corresponds to the columns of C and Y corresponds to the rows. If X and Y are matrices, they must be the same size as C. h = pcolor(...) returns a handle to a surface graphics object.
Remarks
A pseudocolor plot is a flat surface plot viewed from above. pcolor(X,Y,C) is the same as viewing surf(X,Y,0*Z,C) using view([0 90]). When you use shading faceted or shading flat, the constant color of each cell is the color associated with the corner having the smallest x-y coordinates. Therefore, C(i,j) determines the color of the cell in the ith row and jth column. The last row and column of C are not used. When you use shading interp, each cell's color results from a bilinear interpolation of the colors at its four vertices and all elements of C are used.
Examples
A Hadamard matrix has elements that are +1 and 1. A colormap with only two entries is appropriate when displaying a pseudocolor plot of this matrix.
pcolor(hadamard(20)) colormap(gray(2)) axis ij
2-66
pcolor
axis square
2 4 6 8 10 12 14 16 18 20
2
4
6
8
10
12
14
16
18
20
A simple color wheel illustrates a polar coordinate system.
n = 6; r = (0:n)'/n; theta = pi*(n:n)/n; X = r*cos(theta); Y = r*sin(theta); C = r*cos(2theta); pcolor(X,Y,C)
2-67
pcolor
axis equal tight
1 0.8 0.6 0.4 0.2 0 -0.2 -0.4 -0.6 -0.8 -1 -1
-0.5
0
0.5
1
Algorithm
The number of vertex colors for pcolor(C) is the same as the number of cells for image(C). pcolor differs from image in that pcolor(C) specifies the colors of vertices, which are scaled to fit the colormap; changing the axes clim property changes this color mapping. image(C) specifies the colors of cells and directly indexes into the colormap without scaling. Additionally, pcolor(X,Y,C) can produce parametric grids, which is not possible with image.
caxis, image, mesh, shading, surf, view
See Also
2-68
pdepe
Purpose Syntax
2pdepe
Solve initial-boundary value problems for systems of parabolic and elliptic partial differential equations (PDEs) in one space variable and time
sol = pdepe(m,pdefun,icfun,bcfun,xmesh,tspan) sol = pdepe(m,pdefun,icfun,bcfun,xmesh,tspan,options) sol = pdepe(m,pdefun,icfun,bcfun,xmesh,tspan,options,p1,p2...) m pdefun icfun bcfun xmesh
Arguments
A parameter corresponding to the symmetry of the problem. m can be slab = 0, cylindrical = 1, or spherical = 2. A function that defines the components of the PDE. A function that defines the initial conditions. A function that defines the boundary conditions. A vector [x0, x1, ..., xn] specifying the points at which a numerical solution is requested for every value in tspan. The elements of xmesh must satisfy x0 < x1 < ... < xn. The length of xmesh must be >= 3. A vector [t0, t1, ..., tf] specifying the points at which a solution is requested for every value in xmesh. The elements of tspan must satisfy t0 < t1 < ... < tf. The length of tspan must be >= 3. Some options of the underlying ODE solver are available in pdepe: RelTol, AbsTol, NormControl, InitialStep, and MaxStep. In most cases, default values for these options provide satisfactory solutions. See odeset for details.
tspan
options
p1,p2,... Optional parameters to be passed to pdefun, icfun, and bcfun.
Description
sol = pdepe(m,pdefun,icfun,bcfun,xmesh,tspan) solves initial-boundary value problems for systems of parabolic and elliptic PDEs in the one space variable x and time t . The ordinary differential equations (ODEs) resulting from discretization in space are integrated to obtain approximate solutions at times specified in tspan. The pdepe function returns values of the solution on a mesh provided in xmesh.
2-69
pdepe
pdepe solves PDEs of the form:
u u u u m m ------ x f x, t, u, ------ + s x, t, u, ------ c x, t, u, ------ ------ = x t x x x x
(2-1)
The PDEs hold for t 0 t t f and a x b . The interval [ a, b ] must be finite. m can be 0, 1, or 2, corresponding to slab, cylindrical, or spherical symmetry, respectively. If m > 0 , then a must be >= 0. In Equation 2-1, f ( x, t, u, u / x) is a flux term and s( x, t, u, u / x) is a source term. The coupling of the partial derivatives with respect to time is restricted to multiplication by a diagonal matrix c( x, t, u, u / x) . The diagonal elements of this matrix are either identically zero or positive. An element that is identically zero corresponds to an elliptic equation and otherwise to a parabolic equation. There must be at least one parabolic equation. An element of c that corresponds to a parabolic equation can vanish at isolated values of x if those values of x are mesh points. Discontinuities in c and/or s due to material interfaces are permitted provided that a mesh point is placed at each interface. For t = t 0 and all x , the solution components satisfy initial conditions of the form u ( x, t 0 ) = u 0 ( x ) For all t and either x = a or x = b , the solution components satisfy a boundary condition of the form
(2-2)
u p ( x, t, u ) + q ( x, t ) f x, t, u, ------ = 0 x
(2-3)
Elements of q are either identically zero or never zero. Note that the boundary conditions are expressed in terms of the flux f rather than u / x . Also, of the two coefficients, only p can depend on u . In the call sol = pdepe(m,pdefun,icfun,bcfun,xmesh,tspan): m corresponds to m . xmesh(1) and xmesh(end) correspond to a and b . tspan(1) and tspan(end) correspond to t 0 and t f .
2-70
pdepe
pdefun computes the terms c , f , and s (Equation 2-1). It has the form
[c,f,s] = pdefun(x,t,u,dudx)
The input arguments are scalars x and t and vectors u and dudx that approximate the solution u and its partial derivative with respect to x , respectively. c, f, and s are column vectors. c stores the diagonal elements of the matrix c (Equation 2-1). icfun evaluates the initial conditions. It has the form
u = icfun(x)
When called with an argument x, icfun evaluates and returns the initial values of the solution components at x in the column vector u. bcfun evaluates the terms p and q of the boundary conditions (Equation 2-3). It has the form
[pl,ql,pr,qr] = bcfun(xl,ul,xr,ur,t) ul is the approximate solution at the left boundary xl = a and ur is the approximate solution at the right boundary xr = b . pl and ql are column vectors corresponding to p and q evaluated at xl, similarly pr and qr correspond to xr. When m > 0 and a = 0 , boundedness of the solution near x = 0 requires that the flux f vanish at a = 0 . pdepe imposes this boundary condition automatically and it ignores values returned in pl and ql. pdepe returns the solution as a multidimensional array sol. u i = ui = sol(:,:,i) is an approximation to the ith component of the solution vector u . The element ui(j,k) = sol(j,k,i) approximates u i at ( t, x ) = (tspan(j),xmesh(k)). ui = sol(j,:,i) approximates component i of the solution at time tspan(j) and mesh points xmesh(:). Use pdeval to compute the approximation and its partial derivative u i / x at points not included in xmesh. See pdeval for
details.
sol = pdepe(m,pdefun,icfun,bcfun,xmesh,tspan,options) solves as above with default integration parameters replaced by values in options, an argument created with the odeset function. Only some of the options of the underlying ODE solver are available in pdepe: RelTol, AbsTol, NormControl,
2-71
pdepe
InitialStep, and MaxStep. The defaults obtained by leaving off the input argument options will generally be satisfactory. See odeset for details. sol = pdepe(m,pdefun,icfun,bcfun,xmesh,tspan,options,p1,p2...) passes the additional parameters p1, p2, ... to the functions pdefun, icfun, and bcfun. Use options = [] as a placeholder if no options are set.
Remarks
The arrays xmesh and tspan play different roles in pdepe.
tspan The pdepe function performs the time integration with an ODE
solver that selects both the time step and formula dynamically. The elements of tspan merely specify where you want answers and the cost depends weakly on the length of tspan.
xmesh Second order approximations to the solution are made on the mesh specified in xmesh. Generally, it is best to use closely spaced mesh points where the solution changes rapidly. pdepe does not select the mesh in x automatically. You must provide an appropriate fixed mesh in xmesh. The cost depends strongly on the length of xmesh. When m > 0 , it is not necessary
to use a fine mesh near x = 0 to account for the coordinate singularity. The time integration is done with ode15s. pdepe exploits the capabilities of ode15s for solving the differential-algebraic equations that arise when Equation 2-1 contains elliptic equations, and for handling Jacobians with a specified sparsity pattern. After discretization, elliptic equations give rise to algebraic equations. If the elements of the initial conditions vector that correspond to elliptic equations are not "consistent" with the discretization, pdepe tries to adjust them before beginning the time integration. For this reason, the solution returned for the initial time may have a discretization error comparable to that at any other time. If the mesh is sufficiently fine, pdepe can find consistent initial conditions close to the given ones. If pdepe displays a message that it has difficulty finding consistent initial conditions, try refining the mesh. No adjustment is necessary for elements of the initial conditions vector that correspond to parabolic equations.
2-72
pdepe
Examples
Example 1. This example illustrates the straightforward formulation,
computation, and plotting of the solution of a single PDE. u 2 u ------ = ----- ------ t x x This equation holds on an interval 0 x 1 for times t 0 . The PDE satisfies the initial condition u ( x, 0 ) = sin x and boundary conditions u ( 0, t ) 0 t u e + ------ ( 1, t ) = 0 x It is convenient to use subfunctions to place all the functions required by pdepe in a single M-file.
function pdex1 m = 0; x = linspace(0,1,20); t = linspace(0,2,5); sol = pdepe(m,@pdex1pde,@pdex1ic,@pdex1bc,x,t); % Extract the first solution component as u. u = sol(:,:,1); % A surface plot is often a good way to study a solution. surf(x,t,u) title('Numerical solution computed with 20 mesh points.') xlabel('Distance x') ylabel('Time t') % A solution profile can also be illuminating. figure plot(x,u(end,:)) title('Solution at t = 2') xlabel('Distance x')
2-73
pdepe
ylabel('u(x,2)') % -------------------------------------------------------------function [c,f,s] = pdex1pde(x,t,u,DuDx) c = pi^2; f = DuDx; s = 0; % -------------------------------------------------------------function u0 = pdex1ic(x) u0 = sin(pi*x); % -------------------------------------------------------------function [pl,ql,pr,qr] = pdex1bc(xl,ul,xr,ur,t) pl = ul; ql = 0; pr = pi * exp(-t); qr = 1;
In this example, the PDE, initial condition, and boundary conditions are coded in subfunctions pdex1pde, pdex1ic, and pdex1bc. The surface plot shows the behavior of the solution.
Numerical solution computed with 20 mesh points.
1
0.8
0.6
0.4
0.2
0 2 1.5 1 0.5 0.2 Time t 0 0 Distance x 0.4 0.8 0.6 1
2-74
pdepe
The following plot shows the solution profile at the final value of t (i.e., t = 2).
Solution at t = 2 0.14
0.12
0.1
0.08
u(x,2)
0.06
0.04
0.02
0
-0.02
0
0.1
0.2
0.3
0.4
0.5 Distance x
0.6
0.7
0.8
0.9
1
Example 2. This example illustrates the solution of a system of PDEs. The
problem has boundary layers at both ends of the interval. The solution changes rapidly for small t . The PDEs are u1 u 1 --------- = 0.024 ----------- F (u 1 u 2) 2 t x u2 u 2 --------- = 0.170 ----------- + F (u 1 u 2) 2 t x where F ( y ) = exp(5.73 y) exp( 11.46 y) . This equation holds on an interval 0 x 1 for times t 0 .
2 2
2-75
pdepe
The PDE satisfies the initial conditions u 1 ( x, 0 ) 1 u 2 ( x, 0 ) 0 and boundary conditions u 1 --------- ( 0, t ) 0 x u 2(0, t) 0 u 1(1, t) 1 u 2 --------- ( 1, t ) 0 x In the form expected by pdepe, the equations are F ( u1 u2 ) u 0.024 ( u 1 / x ) + . ---- 1 = ----t u x 0.170 ( u / x ) F ( u1 u2 ) 1 2 2 1 The boundary conditions on the partial derivatives of u have to be written in terms of the flux. In the form expected by pdepe, the left boundary condition is 0.024 ( u 1 / x ) 0 1 0 + = . u2 0.170 ( u 2 / x ) 0 0 and the right boundary condition is u1 1 0 0 1 0.024 ( u 1 / x ) 0.170 ( u 2 / x ) 0 0
+
.
=
The solution changes rapidly for small t . The program selects the step size in time to resolve this sharp change, but to see this behavior in the plots, the example must select the output times accordingly. There are boundary layers in the solution at both ends of [0,1], so the example places mesh points near 0 and 1 to resolve these sharp changes. Often some experimentation is needed to select a mesh that reveals the behavior of the solution.
2-76
pdepe
function pdex4 m = 0; x = [0 0.005 0.01 0.05 0.1 0.2 0.5 0.7 0.9 0.95 0.99 0.995 1]; t = [0 0.005 0.01 0.05 0.1 0.5 1 1.5 2]; sol = pdepe(m,@pdex4pde,@pdex4ic,@pdex4bc,x,t); u1 = sol(:,:,1); u2 = sol(:,:,2); figure surf(x,t,u1) title('u1(x,t)') xlabel('Distance x') ylabel('Time t') figure surf(x,t,u2) title('u2(x,t)') xlabel('Distance x') ylabel('Time t') % -------------------------------------------------------------function [c,f,s] = pdex4pde(x,t,u,DuDx) c = [1; 1]; f = [0.024; 0.17] .* DuDx; y = u(1) - u(2); F = exp(5.73*y)-exp(-11.47*y); s = [-F; F]; % -------------------------------------------------------------function u0 = pdex4ic(x); u0 = [1; 0]; % -------------------------------------------------------------function [pl,ql,pr,qr] = pdex4bc(xl,ul,xr,ur,t) pl = [0; ul(2)]; ql = [1; 0]; pr = [ur(1)-1; 0]; qr = [0; 1];
In this example, the PDEs, intial conditions, and boundary conditions are coded in subfunctions pdex4pde, pdex4ic, and pdex4bc.
2-77
pdepe
The surface plots show the behavior of the solution components.
u1(x,t)
1
0.8
0.6
0.4
0.2
0 2 1.5 1 0.5 0.2 Time t 0 0 Distance x 0.4 0.8 0.6 1
u2(x,t)
0.8 0.7 0.6 0.5 0.4 0.3 0.2 0.1 0 2 1.5 1 0.5 0.2 Time t 0 0 Distance x 0.4 0.8 0.6 1
2-78
pdepe
See Also References
function_handle, pdeval, ode15s, odeset, odeget
[1] Skeel, R. D. and M. Berzins, "A Method for the Spatial Discretization of Parabolic Equations in One Space Variable," SIAM Journal on Scientific and Statistical Computing, Vol. 11, 1990, pp.1-32.
2-79
pdeval
Purpose Syntax Arguments
2pdeval
Evaluate the numerical solution of a PDE using the output of pdepe
[uout,duoutdx] = pdeval(m,xmesh,ui,xout) m xmesh
Symmetry of the problem: slab = 0, cylindrical = 1, spherical = 2. This is the first input argument used in the call to pdepe. A vector [x0, x1, ..., xn] specifying the points at which the elements of ui were computed. This is the same vector with which pdepe was called. A vector sol(j,:,i) that approximates component i of the solution at time t f and mesh points xmesh, where sol is the solution returned by pdepe. A vector of points from the interval [x0,xn] at which the interpolated solution is requested.
ui
xout
Description
[uout,duoutdx] = pdeval(m,x,ui,xout) approximates the solution u and i its partial derivative u i / x at points from the interval [x0,xn]. The pdeval function returns the computed values in uout and duoutdx, respectively.
Note pdeval evaluates the partial derivative u i / x rather than the flux f . Although the flux is continuous, the partial derivative may have a jump at a material interface.
See Also
pdepe
2-80
peaks
Purpose Syntax
2peaks
A sample function of two variables.
Z Z Z Z = = = = peaks; peaks(n); peaks(V); peaks(X,Y);
peaks; peaks(N); peaks(V); peaks(X,Y); [X,Y,Z] = peaks; [X,Y,Z] = peaks(n); [X,Y,Z] = peaks(V);
Description
peaks is a function of two variables, obtained by translating and scaling Gaussian distributions, which is useful for demonstrating mesh, surf, pcolor, contour, and so on. Z = peaks; returns a 49-by-49 matrix. Z = peaks(n); returns an n-by-n matrix. Z = peaks(V); returns an n-by-n matrix, where n = length(V). Z = peaks(X,Y); evaluates peaks at the given X and Y (which must be the same size) and returns a matrix the same size. peaks(...) (with no output argument) plots the peaks function with surf. [X,Y,Z] = peaks(...); returns two additional matrices, X and Y, for parametric plots, for example, surf(X,Y,Z,del2(Z)). If not given as input, the underlying matrices X and Y are: [X,Y] = meshgrid(V,V)
where V is a given vector, or V is a vector of length n with elements equally spaced from -3 to 3. If no input argument is given, the default n is 49.
See Also
meshgrid, surf
2-81
perl
Purpose Syntax
2perl
Call Perl script using appropriate operating system executable
perl('perlfile') perl('perlfile',arg1,arg2,...) result = perl(...) perl('perlfile') calls the Perl script perlfile, using the appropriate
Description
operating system Perl executable.
perl('perlfile',arg1,arg2,...) calls the Perl script perlfile, using the appropriate operating system Perl executable and passes the arguments arg1, arg2, and so on, to perlfile. result = perl(...) returns the results of attempted Perl call to result.
See Also
! (exclamation point), dos, system, unix
2-82
perms
Purpose Syntax Description
2perms
All possible permutations
P = perms(v) P = perms(v), where v is a row vector of length n, creates a matrix whose rows consist of all possible permutations of the n elements of v. Matrix P contains n! rows and n columns.
Examples
The command perms(2:2:6) returns all the permutations of the numbers 2, 4, and 6:
2 2 4 4 6 6 4 6 2 6 4 2 6 4 6 2 2 4
Limitations See Also
This function is only practical for situations where n is less than about 15.
nchoosek, permute, randperm
2-83
permute
Purpose Syntax Description
2permute
Rearrange the dimensions of a multidimensional array
B = permute(A,order) B = permute(A,order) rearranges the dimensions of A so that they are in the order specified by the vector order. B has the same values of A but the order of
the subscripts needed to access any particular element is rearranged as specified by order. All the elements of order must be unique.
Remarks Examples
permute and ipermute are a generalization of transpose (.') for
multidimensional arrays. Given any matrix A, the statement
permute(A,[2 1])
is the same as A'. For example:
A = [1 2; 3 4]; permute(A,[2 1]) ans = 1 3 2 4
The following code permutes a three-dimensional array:
X = rand(12,13,14); Y = permute(X,[2 3 1]); size(Y) ans = 13 14 12
See Also
ipermute
2-84
persistent
Purpose Syntax Description
2persistent
Define persistent variable
persistent X Y Z persistent X Y Z defines X, Y, and Z as variables that are local to the function in which they are declared yet their values are retained in memory between calls to the function. Persistent variables are similar to global variables because MATLAB creates permanent storage for both. They differ from global variables in that persistent variables are known only to the function in which they are declared. This prevents persistent variables from being changed by other functions or from the MATLAB command line.
Persistent variables are cleared when the M-file is cleared from memory or when the M-file is changed. To keep an M-file in memory until MATLAB quits, use mlock. If the persistent variable does not exist the first time you issue the persistent statement, it is initialized to the empty matrix. It is an error to declare a variable persistent if a variable with the same name exists in the current workspace.
Remarks See Also
There is no function form of the persistent command (i.e., you cannot use parentheses and quote the variable names).
clear, global, mislocked, mlock, munlock
2-85
pi
Purpose Syntax Description Examples
Ratio of a circle's circumference to its diameter,
2pi
pi pi returns the floating-point number nearest the value of . The expressions 4*atan(1) and imag(log(-1)) provide the same value.
The expression sin(pi) is not exactly zero because pi is not exactly .
sin(pi) ans = 1.2246e-16
See Also
ans, eps, i, Inf, j, NaN
2-86
pie
Purpose Syntax
2pie
Pie chart
pie(X) pie(X,explode) h = pie(...) pie(X) draws a pie chart using the data in X. Each element in X is represented
Description
as a slice in the pie chart.
pie(X,explode) offsets a slice from the pie. explode is a vector or matrix of zeros and nonzeros that correspond to X. A non-zero value offsets the corresponding slice from the center of the pie chart, so that X(i,j) is offset from the center if explode(i,j) is nonzero. explode must be the same size as X. h = pie(...) returns a vector of handles to patch and text graphics objects.
Remarks
The values in X are normalized via X/sum(X) to determine the area of each slice of the pie. If sum(X)1, the values in X directly specify the are of the pie slices. MATLAB draws only a partial pie if sum(X)<1. Emphasize the second slice in the chart by setting its corresponding explode element to 1.
x = [1 3 0.5 2.5 2]; explode = [0 1 0 0 0]; pie(x,explode)
Examples
2-87
pie
colormap jet
11% 22%
33%
28%
6%
See Also
pie3
2-88
pie3
Purpose Syntax
2pie3
Three-dimensional pie chart
pie3(X) pie3(X,explode) h = pie3(...) pie3(X) draws a three-dimensional pie chart using the data in X. Each element in X is represented as a slice in the pie chart. pie3(X,explode) specifies whether to offset a slice from the center of the pie chart. X(i,j) is offset from the center of the pie chart if explode(i,j) is nonzero. explode must be the same size as X. h = pie(...) returns a vector of handles to patch, surface, and text graphics
Description
objects.
Remarks
The values in X are normalized via X/sum(X) to determine the area of each slice of the pie. If sum(X)1, the values in X directly specify the area of the pie slices. MATLAB draws only a partial pie if sum(X)<1. Offset a slice in the pie chart by setting the corresponding explode element to 1:
x = [1 3 0.5 2.5 2] explode = [0 1 0 0 0] pie3(x,explode) colormap hsv
22% 11%
Examples
28%
33%
6%
2-89
pie3
See Also
pie
2-90
pinv
Purpose Syntax Definition
2pinv
Moore-Penrose pseudoinverse of a matrix
B = pinv(A) B = pinv(A,tol)
The Moore-Penrose pseudoinverse is a matrix B of the same dimensions as A' satisfying four conditions:
A*B*A B*A*B A*B is B*A is = A = B
Hermitian Hermitian
The computation is based on svd(A) and any singular values less than tol are treated as zero.
Description
B = pinv(A) returns the Moore-Penrose pseudoinverse of A. B = pinv(A,tol) returns the Moore-Penrose pseudoinverse and overrides the default tolerance, max(size(A))*norm(A)*eps.
Examples
If A is square and not singular, then pinv(A) is an expensive way to compute inv(A). If A is not square, or is square and singular, then inv(A) does not exist. In these cases, pinv(A) has some of, but not all, the properties of inv(A). If A has more rows than columns and is not of full rank, then the overdetermined least squares problem minimize norm(A*x-b) does not have a unique solution. Two of the infinitely many solutions are
x = pinv(A)*b
and
y = A\b
These two are distinguished by the facts that norm(x) is smaller than the norm of any other solution and that y has the fewest possible nonzero components. For example, the matrix generated by
2-91
pinv
A = magic(8); A = A(:,1:6)
is an 8-by-6 matrix that happens to have rank(A) = 3.
A = 64 9 17 40 32 41 49 8 2 55 47 26 34 23 15 58 3 54 46 27 35 22 14 59 61 12 20 37 29 44 52 5 60 13 21 36 28 45 53 4 6 51 43 30 38 19 11 62
The right-hand side is b = 260*ones(8,1),
b = 260 260 260 260 260 260 260 260
The scale factor 260 is the 8-by-8 magic sum. With all eight columns, one solution to A*x = b would be a vector of all 1's. With only six columns, the equations are still consistent, so a solution exists, but it is not all 1's. Since the matrix is rank deficient, there are infinitely many solutions. Two of them are
x = pinv(A)*b
which is
x = 1.1538 1.4615 1.3846 1.3846 1.4615 1.1538
2-92
pinv
and
y = A\b
which produces this result.
Warning: Rank deficient, rank = 3 y = 4.0000 5.0000 0 0 0 -1.0000 tol = 1.8829e-013.
Both of these are exact solutions in the sense that norm(Ax-b) and norm(Ay-b) are on the order of roundoff error. The solution x is special because
norm(x) = 3.2817
is smaller than the norm of any other solution, including
norm(y) = 6.4807
On the other hand, the solution y is special because it has only three nonzero components.
See Also
inv, qr, rank, svd
2-93
planerot
Purpose Syntax Description Examples
2planerot
Givens plane rotation
[G,y] = planerot(x) [G,y] = planerot(x) where x is a 2-component column vector, returns a 2-by-2 orthogonal matrix G so that y = G*x has y(2) = 0. x = [3 4]; [G,y] = planerot(x') G = 0.6000 -0.8000 y = 5 0 0.8000 0.6000
See Also
qrdelete, qrinsert
2-94
plot
Purpose Syntax
2plot
Linear 2D plot
plot(Y) plot(X1,Y1,...) plot(X1,Y1,LineSpec,...) plot(...,'PropertyName',PropertyValue,...) h = plot(...) plot(Y) plots the columns of Y versus their index if Y is a real number. If Y is complex, plot(Y) is equivalent to plot(real(Y),imag(Y)). In all other uses of plot, the imaginary component is ignored. plot(X1,Y1,...) plots all lines defined by Xn versus Yn pairs. If only Xn or Yn
Description
is a matrix, the vector is plotted versus the rows or columns of the matrix, depending on whether the vector's row or column dimension matches the matrix.
plot(X1,Y1,LineSpec,...) plots all lines defined by the Xn,Yn,LineSpec triples, where LineSpec is a line specification that determines line type, marker symbol, and color of the plotted lines. You can mix Xn,Yn,LineSpec triples with Xn,Yn pairs: plot(X1,Y1,X2,Y2,LineSpec,X3,Y3). plot(...,'PropertyName',PropertyValue,...) sets properties to the specified property values for all line graphics objects created by plot. (See the
"Examples" section for examples.)
h = plot(...) returns a column vector of handles to line graphics objects, one
handle per line.
Remarks
If you do not specify a color when plotting more than one line, plot automatically cycles through the colors in the order specified by the current axes ColorOrder property. After cycling through all the colors defined by ColorOrder, plot then cycles through the line styles defined in the axes LineStyleOrder property. Note that, by default, MATLAB resets the ColorOrder and LineStyleOrder properties each time you call plot. If you want changes you make to these properties to persist, then you must define these changes as default values. For example,
2-95
plot
set(0,'DefaultAxesColorOrder',[0 0 0],... 'DefaultAxesLineStyleOrder','-|-.|--|:')
sets the default ColorOrder to use only the color black and sets the LineStyleOrder to use solid, dash-dot, dash-dash, and dotted line styles.
Additional Information
See the "Creating 2-D Graphs" and "Labeling Graphs" in Using MATLAB Graphics for more information on plotting. See LineSpec for more information on specifying line styles and colors.
Examples
Specifying the Color and Size of Markers
You can also specify other line characteristics using graphics properties (see line for a description of these properties): LineWidth specifies the width (in points) of the line. MarkerEdgeColor specifies the color of the marker or the edge color for filled markers (circle, square, diamond, pentagram, hexagram, and the four triangles). MarkerFaceColor specifies the color of the face of filled markers. MarkerSize specifies the size of the marker in units of points. For example, these statements,
x = -pi:pi/10:pi; y = tan(sin(x)) - sin(tan(x)); plot(x,y,'--rs','LineWidth',2,... 'MarkerEdgeColor','k',... 'MarkerFaceColor','g',... 'MarkerSize',10)
2-96
plot
produce this graph.
3
2
1
0
-1
-2
-3 -4
-3
-2
-1
0
1
2
3
4
Specifying Tick Mark Location and Labeling
You can adjust the axis tick-mark locations and the labels appearing at each tick. For example, this plot of the sine function relabels the x-axis with more meaningful values,
x = -pi:.1:pi; y = sin(x); plot(x,y) set(gca,'XTick',-pi:pi/2:pi) set(gca,'XTickLabel',{'-pi','-pi/2','0','pi/2','pi'})
2-97
plot
Now add axis labels and annotate the point -pi/4, sin(-pi/4).
1 0.8 0.6 0.4 0.2 0 -0.2 -0.4 -0.6 -0.8 -1
-pi
-pi/2
0
pi/2
pi
Adding Titles, Axis Labels, and Annotations MATLAB enables you to add axis labels and titles. For example, using the graph from the previous example, add an x- and y-axis label,
xlabel('-\pi \leq \Theta \leq \pi') ylabel('sin(\Theta)') title('Plot of sin(\Theta)') text(-pi/4,sin(-pi/4),'\leftarrow sin(-\pi\div4)',... 'HorizontalAlignment','left')
Now change the line color to red by first finding the handle of the line object created by plot and then setting its Color property. In the same statement, set the LineWidth property to 2 points.
set(findobj(gca,'Type','line','Color',[0 0 1]),... 'Color','red',... 'LineWidth',2)
2-98
plot
Plot of sin() 1 0.8 0.6 0.4 0.2 sin() 0 -0.2 -0.4 -0.6 sin(-4) -0.8 -1
-pi
-pi/2
0 -
pi/2
pi
See Also
axis, bar, grid, hold, legend, line, LineSpec, loglog, plotyy, semilogx, semilogy, subplot, title, xlabel, xlim, ylabel, ylim, zlabel, zlim, stem
See the text String property for a list of symbols and how to display them. See the Plot Editor for information on plot annotation tools in the figure window toolbar. See Basic Plots and Graphs for related functions.
2-99
plot3
Purpose Syntax
2plot3
Linear 3-D plot
plot3(X1,Y1,Z1,...) plot3(X1,Y1,Z1,LineSpec,...) plot3(...,'PropertyName',PropertyValue,...) h = plot3(...)
Description
The plot3 function displays a three-dimensional plot of a set of data points.
plot3(X1,Y1,Z1,...), where X1, Y1, Z1 are vectors or matrices, plots one or
more lines in three-dimensional space through the points whose coordinates are the elements of X1, Y1, and Z1.
plot3(X1,Y1,Z1,LineSpec,...) creates and displays all lines defined by the Xn,Yn,Zn,LineSpec quads, where LineSpec is a line specification that
determines line style, marker symbol, and color of the plotted lines.
plot3(...,'PropertyName',PropertyValue,...) sets properties to the specified property values for all Line graphics objects created by plot3. h = plot3(...) returns a column vector of handles to line graphics objects,
with one handle per line.
Remarks
If one or more of X1, Y1, Z1 is a vector, the vectors are plotted versus the rows or columns of the matrix, depending whether the vectors' lengths equal the number of rows or the number of columns. You can mix Xn,Yn,Zn triples with Xn,Yn,Zn,LineSpec quads, for example,
plot3(X1,Y1,Z1,X2,Y2,Z2,LineSpec,X3,Y3,Z3)
See LineSpec and plot for information on line types and markers.
Examples
Plot a three-dimensional helix.
t = 0:pi/50:10pi; plot3(sin(t),cos(t),t) grid on
2-100
plot3
axis square
35 30 25 20 15 10 5 0 1 0.5 0 0 -0.5 -1 -1 -0.5 0.5 1
See Also
axis, bar3, grid, line, LineSpec, loglog, plot, semilogx, semilogy, subplot
2-101
plotedit
Purpose Syntax
2plotedit
Start plot edit mode to allow editing and annotation of plots
plotedit on plotedit off plotedit plotedit('state') plotedit(h) plotedit(h,'state') plotedit on starts plot edit mode for the current figure, allowing you to use a
Description
graphical interface to annotate and edit plots easily. In plot edit mode, you can label axes, chang line styles, and adding text, line, and arrow annotations.
plotedit off ends plot mode for the current figure. plotedit toggles the plot edit mode for the current figure. plotedit(h) toggles the plot edit mode for the figure specified by figure handle h. plotedit('state') specifies the plotedit state for the current figure. Values for state can be as shown. Value for state on off showtoolsmenu hidetoolsmenu Description
Starts plot edit mode Ends plot edit mode Displays the Tools menu in the menu bar Removes the Tools menu from the menu bar
Note hidetoolsmenu is intended for GUI developers who do not want the Tools menu to appear in applications that use the figure window.
plotedit(h,'state') specifies the plotedit state for figure handle h.
2-102
plotedit
Remarks
Plot Editing Mode Graphical Interface Components
Use these toolbar buttons to add text, arrows, and lines.
To start plot edit mode, click this button. Add objects or edit existing objects in the plot through the Edit, Insert, and Tools menus.
Position labels, legends, and other object by clicking and dragging.
Access object-specific plot edit functions through context-sensitive pop-up menus.
Examples
Start plot edit mode for figure 2:
plotedit(2)
End plot edit mode for figure 2:
plotedit(2, 'off')
Hide the Tools menu for the current figure:
plotedit('hidetoolsmenu')
See Also
axes, line, open, plot, print, saveas, text, propedit
2-103
plotmatrix
Purpose Syntax
2plotmatrix
Draw scatter plots
plotmatrix(X,Y) plotmatrix(...,'LineSpec') [H,AX,BigAx,P] = plotmatrix(...) plotmatrix(X,Y) scatter plots the columns of X against the columns of Y. If X is p-by-m and Y is p-by-n, plotmatrix produces an n-by-m matrix of axes. plotmatrix(Y) is the same as plotmatrix(Y,Y) except that the diagonal is replaced by hist(Y(:,i)). plotmatrix(...,'LineSpec') uses a LineSpec to create the scatter plot.The
Description
default is '.' .
[H,AX,BigAx,P] = plotmatrix(...) returns a matrix of handles to the objects created in H, a matrix of handles to the individual subaxes in AX, a handle to a big (invisible) axes that frames the subaxes in BigAx, and a matrix of handles for the histogram plots in P. BigAx is left as the current axes so that a subsequent title, xlabel, or ylabel commands are centered with respect to
the matrix of axes.
Examples
Generate plots of random data.
x = randn(50,3); y = x*[-1 2 1;2 0 1;1 -2 3;]'; plotmatrix(y,'*r')
2-104
plotmatrix
5
0
-5 10 5 0 -5 10 5 0 -5 -10 -5 0 5 -5 0 5 10 -10 -5 0 5 10
See Also
scatter, scatter3
2-105
plotyy
Purpose Syntax
2plotyy
Create graphs with y axes on both left and right side
plotyy(X1,Y1,X2,Y2) plotyy(X1,Y1,X2,Y2,'function') plotyy(X1,Y1,X2,Y2,'function1','function2') [AX,H1,H2] = plotyy(...) plotyy(X1,Y1,X2,Y2) plots X1 versus Y1 with y-axis labeling on the left and plots X2 versus Y2 with y-axis labeling on the right. plotyy(X1,Y1,X2,Y2,'function') uses the plotting function specified by the string 'function' instead of plot to produce each graph. 'function' can be plot, semilogx, semilogy, loglog, stem or any MATLAB function that accepts the syntax: h = function(x,y) plotyy(X1,Y1,X2,Y2,'function1','function2') uses function1(X1,Y1) to plot the data for the left axis and function2(X2,Y2) to plot the data for the
Description
right axis.
[AX,H1,H2] = plotyy(...) returns the handles of the two axes created in AX and the handles of the graphics objects from each plot in H1 and H2. AX(1) is the left axes and AX(2) is the right axes.
Examples
This example graphs two mathematical functions using plot as the plotting function. The two y-axes enable you to display both sets of data on one graph even though relative values of the data are quite different.
x = 0:0.01:20; y1 = 200*exp(-0.05*x).*sin(x); y2 = 0.8*exp(-0.5*x).*sin(10*x); [AX,H1,H2] = plotyy(x,y1,x,y2,'plot');
You can use the handles returned by plotyy to label the axes and set the line styles used for plotting. With the axes handles you can specify the YLabel properties of the left- and right-side y-axis:
set(get(AX(1),'Ylabel'),'String','Left Y-axis') set(get(AX(2),'Ylabel'),'String','Right Y-axis')
Use the xlabel and title commands to label the x-axis and add a title:
2-106
plotyy
xlabel('Zero to 20 \musec.') title('Labeling plotyy')
Use the line handles to set the LineStyle properties of the left- and right-side plots:
set(H1,'LineStyle','--') set(H2,'LineStyle',':')
Labeling plotyy 200 0.8
150
0.6
100
0.4
50 Left Y-axis
0.2 Right Y-axis
0
0
-50
-0.2
-100
-0.4
-150
-0.6
-200
0
5
10 Zero to 20 sec.
15
-0.8 20
See Also
plot, loglog, semilogx, semilogy, axes properties: XAxisLocation, YAxisLocation
The axes chapter in the Using MATLAB Graphics manual for information on multi-axis axes.
2-107
pol2cart
Purpose Syntax Description
2pol2cart
Transform polar or cylindrical coordinates to Cartesian
[X,Y] = pol2cart(THETA,RHO) [X,Y,Z] = pol2cart(THETA,RHO,Z) [X,Y] = pol2cart(THETA,RHO) transforms the polar coordinate data stored in corresponding elements of THETA and RHO to two-dimensional Cartesian, or xy, coordinates. The arrays THETA and RHO must be the same size (or either can be scalar). The values in THETA must be in radians. [X,Y,Z] = pol2cart(THETA,RHO,Z) transforms the cylindrical coordinate data stored in corresponding elements of THETA, RHO, and Z to three-dimensional Cartesian, or xyz, coordinates. The arrays THETA , RHO, and Z must be the same size (or any can be scalar). The values in THETA must be in
radians.
Algorithm
The mapping from polar and cylindrical coordinates to Cartesian coordinates is:
Y
Z P P Y z
rh
o
theta X
rho theta
X Polar to Cartesian Mapping
theta = atan2(y,x) rho = sqrt(x.^2 + y.^2)
Cylindrical to Cartesian Mapping
theta = atan2(y,x) rho = sqrt(x.^2 + y.^2) z = z
See Also
cart2pol, cart2sph, sph2cart
2-108
polar
Purpose Syntax Description
2polar
Plot polar coordinates
polar(theta,rho) polar(theta,rho,LineSpec)
The polar function accepts polar coordinates, plots them in a Cartesian plane, and draws the polar grid on the plane.
polar(theta,rho) creates a polar coordinate plot of the angle theta versus the radius rho. theta is the angle from the x-axis to the radius vector specified in radians; rho is the length of the radius vector specified in dataspace units. polar(theta,rho,LineSpec) LineSpec specifies the line type, plot symbol, and color for the lines drawn in the polar plot.
Examples
Create a simple polar plot using a dashed, red line: t = 0:.01:2pi;
2-109
polar
polar(t,sin(2t).cos(2t),'--r')
90 0.5 120 0.375 60
150
0.25
30
0.125
180
0
210
330
240 270
300
See Also
cart2pol, compass, LineSpec, plot, pol2cart, rose
2-110
poly
Purpose Syntax Description
2poly
Polynomial with specified roots
p = poly(A) p = poly(r) p = poly(A) where A is an n-by-n matrix returns an n+1 element row vector whose elements are the coefficients of the characteristic polynomial, det ( sl A ) . The coefficients are ordered in descending powers: if a vector c has n+1 components, the polynomial it represents is c 1 s n + ... + c n s + c n + 1 p = poly(r) where r is a vector returns a row vector whose elements are the coefficients of the polynomial whose roots are the elements of r.
Remarks
Note the relationship of this command to
r = roots(p)
which returns a column vector whose elements are the roots of the polynomial specified by the coefficients row vector p. For vectors, roots and poly are inverse functions of each other, up to ordering, scaling, and roundoff error.
Examples
MATLAB displays polynomials as row vectors containing the coefficients ordered by descending powers. The characteristic equation of the matrix
A = 1 4 7 2 5 8 3 6 0
is returned in a row vector by poly:
p = poly(A) p = 1 -6 -72 -27
The roots of this polynomial (eigenvalues of matrix A) are returned in a column vector by roots:
r = roots(p)
2-111
poly
r = 12.1229 -5.7345 -0.3884
Algorithm
The algorithms employed for poly and roots illustrate an interesting aspect of the modern approach to eigenvalue computation. poly(A) generates the characteristic polynomial of A, and roots(poly(A)) finds the roots of that polynomial, which are the eigenvalues of A. But both poly and roots use eig, which is based on similarity transformations. The classical approach, which characterizes eigenvalues as roots of the characteristic polynomial, is actually reversed. If A is an n-by-n matrix, poly(A) produces the coefficients c(1) through c(n+1), with c(1) = 1, in det ( I A ) = c 1 n + ... + c n + c n + 1 The algorithm is
z = eig(A); c = zeros(n+1,1); c(1) = 1; for j = 1:n c(2:j+1) = c(2:j+1)-z(j)*c(1:j); end
This recursion is easily derived by expanding the product. ( 1 ) ( 2 )... ( n ) It is possible to prove that poly(A) produces the coefficients in the characteristic polynomial of a matrix within roundoff error of A. This is true even if the eigenvalues of A are badly conditioned. The traditional algorithms for obtaining the characteristic polynomial, which do not use the eigenvalues, do not have such satisfactory numerical properties.
See Also
conv, polyval, residue, roots
2-112
polyarea
Purpose Syntax Description
2polyarea
Area of polygon
A = polyarea(X,Y) A = polyarea(X,Y,dim) A = polyarea(X,Y) returns the area of the polygon specified by the vertices in the vectors X and Y.
If X and Y are matrices of the same size, then polyarea returns the area of polygons defined by the columns X and Y. If X and Y are multidimensional arrays, polyarea returns the area of the polygons in the first nonsingleton dimension of X and Y.
A = polyarea(X,Y,dim) operates along the dimension specified by scalar dim.
Examples
L = linspace(0,2.*pi,6); xv = cos(L)';yv = sin(L)'; xv = [xv ; xv(1)]; yv = [yv ; yv(1)]; A = polyarea(xv,yv); plot(xv,yv); title(['Area = ' num2str(A)]); axis image
Area = 2.3776 0.8 0.6 0.4 0.2 0 -0.2 -0.4 -0.6 -0.8 -0.5 0 0.5 1
See Also
convhull, inpolygon, rectint
2-113
polyder
Purpose Syntax
2polyder
Polynomial derivative
k = polyder(p) k = polyder(a,b) [q,d] = polyder(b,a)
Description
The polyder function calculates the derivative of polynomials, polynomial products, and polynomial quotients. The operands a, b, and p are vectors whose elements are the coefficients of a polynomial in descending powers.
k = polyder(p) returns the derivative of the polynomial p. k = polyder(a,b) returns the derivative of the product of the polynomials a and b. [q,d] = polyder(b,a) returns the numerator q and denominator d of the derivative of the polynomial quotient b/a.
Examples
The derivative of the product ( 3x 2 + 6x + 9 ) ( x 2 + 2x ) is obtained with
a b k k = [3 6 9]; = [1 2 0]; = polyder(a,b) = 12 36 42
18
This result represents the polynomial 12x 3 + 36x 2 + 42x + 18
See Also
conv, deconv
2-114
polyeig
Purpose Syntax Description
2polyeig
Polynomial eigenvalue problem
[X,e] = polyeig(A0,A1,...Ap) e = polyeig(A0,A1,..,Ap) [X,e] = polyeig(A0,A1,...Ap) solves the polynomial eigenvalue problem of degree p
( A 0 + A 1 + ... + P A p )x = 0 where polynomial degree p is a non-negative integer, and A0,A1,...Ap are input matrices of order n. Output matrix X, of size n-by-n*p, contains eigenvectors in its columns. Output vector e, of length n*p, contains eigenvalues. If lambda is the jth eigenvalue in e, and x is the jth column of eigenvectors in X, then (A0 + lambda*A1 + ... + lambda^p*Ap)*x is approximately 0.
e = polyeig(A0,A1,..,Ap) is a vector of length n*p whose elements are the
eigenvalues of the polynomial eigenvalue problem.
Remarks
Based on the values of p and n, polyeig handles several special cases: p = 0, or polyeig(A) is the standard eigenvalue problem: eig(A). p = 1, or polyeig(A,B) is the generalized eigenvalue problem: eig(A,-B). n = 1, or polyeig(a0,a1,...ap) for scalars a0, a1 ..., ap is the standard polynomial problem: roots([ap ... a1 a0]).
Algorithm
If both A0 and Ap are singular, the problem is potentially ill posed; solutions might not exist or they might not be unique. In this case, the computed solutions may be inaccurate. polyeig attempts to detect this situation and display an appropriate warning message. If either one, but not both, of A0 and Ap is singular, the problem is well posed but some of the eigenvalues may be zero or infinite (Inf). The polyeig function uses the QZ factorization to find intermediate results in the computation of generalized eigenvalues. It uses these intermediate results to determine if the eigenvalues are well-determined. See the descriptions of eig and qz for more on this.
2-115
polyeig
See Also
eig, qz
2-116
polyfit
Purpose Syntax
2polyfit
Polynomial curve fitting
p = polyfit(x,y,n) [p,S] = polyfit(x,y,n) [p,S,mu] = polyfit(x,y,n) p = polyfit(x,y,n) finds the coefficients of a polynomial p(x) of degree n that fits the data, p(x(i)) to y(i), in a least squares sense. The result p is a row vector of length n+1 containing the polynomial coefficients in descending
Description
powers p ( x ) = p1 x n + p2 x n 1 + ... + pn x + pn + 1
[p,S] = polyfit(x,y,n) returns the polynomial coefficients p and a structure S for use with polyval to obtain error estimates or predictions. If the errors in the data y are independent normal with constant variance, polyval produces error bounds that contain at least 50% of the predictions. [p,S,mu] = polyfit(x,y,n) finds the coefficients of a polynomial in
x 1 ^ x = -------------2
where 1 = mean (x) and 2 = std (x) . mu is the two-element vector [ 1, 2 ] . This centering and scaling transformation improves the numerical properties of both the polynomial and the fitting algorithm.
Examples
This example involves fitting the error function, erf(x), by a polynomial in x. This is a risky project because erf(x) is a bounded function, while polynomials are unbounded, so the fit might not be very good. First generate a vector of x points, equally spaced in the interval [ 0, 2.5 ] ; then evaluate erf(x) at those points.
x = (0: 0.1: 2.5)'; y = erf(x);
The coefficients in the approximating polynomial of degree 6 are
p = polyfit(x,y,6)
2-117
polyfit
p = 0.0084 -0.0983 0.4217 -0.7435 0.1471 1.1064 0.0004
There are seven coefficients and the polynomial is 0.0084x 0.0983x + 0.4217x 0.7435x + 0.1471x + 1.1064x + 0.0004 To see how good the fit is, evaluate the polynomial at the data points with
f = polyval(p,x);
6 5 4 3 2
A table showing the data, fit, and error is
table = [x y f y-f] table = 0 0.1000 0.2000 0.3000 0.4000 ... 2.1000 2.2000 2.3000 2.4000 2.5000 0 0.1125 0.2227 0.3286 0.4284 0.9970 0.9981 0.9989 0.9993 0.9996 0.0004 0.1119 0.2223 0.3287 0.4288 0.9969 0.9982 0.9991 0.9995 0.9994 -0.0004 0.0006 0.0004 -0.0001 -0.0004 0.0001 -0.0001 -0.0003 -0.0002 0.0002
So, on this interval, the fit is good to between three and four digits. Beyond this interval the graph shows that the polynomial behavior takes over and the approximation quickly deteriorates.
x = (0: 0.1: 5)'; y = erf(x); f = polyval(p,x); plot(x,y,'o',x,f,'-') axis([0 5 0 2])
2-118
polyfit
2 1.8 1.6 1.4 1.2 1 0.8
o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o
0.6 0.4 0.2
o o
0o 0
0.5
1
1.5
2
2.5
3
3.5
4
4.5
5
Algorithm
The polyfit M-file forms the Vandermonde matrix, V , whose elements are powers of x . v i,
j n = xi j
It then uses the backslash operator, \, to solve the least squares problem Vp y You can modify the M-file to use other functions of x as the basis functions.
See Also
poly, polyval, roots
2-119
polyint
Purpose Syntax Description
2polyint
Integrate polynomial analytically
polyint(p,k) polyint(p) polyint(p,k) returns a polynomial representing the integral of polynomial p, using a scalar constant of integration k. polyint(p) assumes a constant of integration k=0.
See Also
polyder, polyval, polyvalm, polyfit
2-120
polyval
Purpose Syntax
2polyval
Polynomial evaluation
y = polyval(p,x) y = polyval(p,x,[],mu) [y,delta] = polyval(p,x,S) [y,delta] = polyval(p,x,S,mu) y = polyval(p,x) returns the value of a polynomial of degree n evaluated at x. The input argument p is a vector of length n+1 whose elements are the
Description
coefficients in descending powers of the polynomial to be evaluated. y = p1 x n + p2 x n 1 + ... + pn x + pn + 1
x can be a matrix or a vector. In either case, polyval evaluates p at each element of x.
^ y = polyval(p,x,[],mu) uses x = ( x 1 ) / 2 in place of x . In this equation, 1 = mean ( x) and 2 = std ( x) . The centering and scaling parameters mu = [ 1, 2 ] are optional output computed by polyfit.
[y,delta] = polyval(p,x,S) and [y,delta] = polyval(p,x,S,mu) use the optional output structure S generated by polyfit to generate error estimates, ydelta. If the errors in the data input to polyfit are independent normal with constant variance, ydelta contains at least 50% of the predictions.
Remarks Examples
The polyvalm(p,x) function, with x a matrix, evaluates the polynomial in a matrix sense. See polyvalm for more information. The polynomial p ( x ) = 3x + 2x + 1 is evaluated at x = 5, 7, and 9 with
p = [3 2 1]; polyval(p,[5 7 9])
2
which results in
ans = 86 162 262
For another example, see polyfit.
2-121
polyval
See Also
polyfit, polyvalm
2-122
polyvalm
Purpose Syntax Description
2polyvalm
Matrix polynomial evaluation
Y = polyvalm(p,X) Y = polyvalm(p,X) evaluates a polynomial in a matrix sense. This is the same as substituting matrix X in the polynomial p.
Polynomial p is a vector whose elements are the coefficients of a polynomial in descending powers, and X must be a square matrix.
Examples
The Pascal matrices are formed from Pascal's triangle of binomial coefficients. Here is the Pascal matrix of order 4.
X = pascal(4) X = 1 1 1 1 2 3 1 3 6 1 4 10
1 4 10 20
Its characteristic polynomial can be generated with the poly function.
p = poly(X) p = 1 -29
72
-29
1
This represents the polynomial x 4 29x 3 + 72x 2 29x + 1 . Pascal matrices have the curious property that the vector of coefficients of the characteristic polynomial is palindromic; it is the same forward and backward. Evaluating this polynomial at each element is not very interesting.
polyval(p,X) ans = 16 16 16 15 16 -140 16 -563
16 -140 -2549 -12089
16 -563 -12089 -43779
But evaluating it in a matrix sense is interesting.
polyvalm(p,X)
2-123
polyvalm
ans = 0 0 0 0
0 0 0 0
0 0 0 0
0 0 0 0
The result is the zero matrix. This is an instance of the Cayley-Hamilton theorem: a matrix satisfies its own characteristic equation.
See Also
polyfit, polyval
2-124
pow2
Purpose Syntax Description
2pow2
Base 2 power and scale floating-point numbers
X = pow2(Y) X = pow2(F,E) X = pow2(Y) returns an array X whose elements are 2 raised to the power Y. X = pow2(F,E) computes x = f * 2 for corresponding elements of F and E. The result is computed quickly by simply adding E to the floating-point exponent of F. Arguments F and E are real and integer arrays, respectively.
e
Remarks Examples
This function corresponds to the ANSI C function ldexp() and the IEEE floating-point standard function scalbn(). For IEEE arithmetic, the statement X = pow2(F,E) yields the values:
F 1/2 pi/4 -3/4 1/2 1-eps/2 1/2 E 1 2 2 -51 1024 -1021 X 1 pi -3 eps realmax realmin
See Also
log2, exp, hex2num, realmax, realmin
The arithmetic operators ^ and .^
2-125
ppval
Purpose Syntax Description
2ppval
Evaluate piecewise polynomial.
v = ppval(pp,xx) v = ppval(xx,pp) v = ppval(pp,xx) returns the value at the points xx of the piecewise polynomial contained in pp, as constructed by spline or the spline utility mkpp. v = ppval(xx,pp) returns the same result but can be used with functions like fminbnd, fzero and quad that take a function as an argument.
Examples
Compare the results of integrating the function cos
a = 0; b = 10; int1 = quad(@cos,a,b,[],[]) int1 = -0.5440
with the results of integrating the piecewise polynomial pp that approximates the cosine function by interpolating the computed values x and y.
x = a:b; y = cos(x); pp = spline(x,y); int2 = quad(@ppval,a,b,[],[],pp) int2 = -0.5485 int1 provides the integral of the cosine function over the interval [a,b], while int2 provides the integral over the same interval of the piecewise polynomial pp.
See Also
mkpp, spline, unmkpp
2-126
prefdir
Purpose Syntax
2prefdir
Return directory containing preferences, history, and .ini files
prefdir d = prefdir d = prefdir(1) prefdir returns the directory that contains preferences for MATLAB and related products (matlab.prf), the command history (history.m), and the MATLAB initialization file (MATLAB.ini). d = prefdir returns the name of the directory containing preferences and
Description
related files, but does not ensure its existence.
d = prefdir(1) creates a directory for preferences and related files if one does
not exist.
Examples
Run
prefdir
MATLAB returns
ans = C:\WINNT\Profiles\Application Data\MathWorks\MATLAB\R13
Running dir for the directory shows
dir . .. MATLAB.ini cstprefs.mat cwdhistory.m history.m launchpad_cache.txt matlab.prf matlab_help.hst
See Also
"Setting Preferences" in the MATLAB Development Environment documentation
2-127
primes
Purpose Syntax Description Examples
2primes
Generate list of prime numbers
p = primes(n) p = primes(n) returns a row vector of the prime numbers less than or equal to n. A prime number is one that has no factors other than 1 and itself. p = primes(37) p = 2 3 5 7 11 13 17 19 23 29 31 37
See Also
factor
2-128
print, printopt
Purpose Syntax
2print, printopt
Create hardcopy output
print print filename print -ddriver print -dformat print -dformat filename print ... -options [pcmd,dev] = printopt print and printopt produce hardcopy output. All arguments to the print
Description
command are optional. You can use them in any combination or order.
print sends the contents of the current figure, including bitmap
representations of any user interface controls, to the printer using the device and system printing command defined by printopt.
print filename directs the output to the file designated by filename. If filename does not include an extension, print appends an appropriate
extension.
print -ddriver prints the figure using the specified printer driver, (such as color PostScript). If you omit -ddriver, print uses the default value stored in printopt.m. The Printer Driver table lists all supported device types. print -dformat copies the figure to the system clipboard (Windows only). A valid format for this operation is either -dmeta (Windows Enhanced Metafile) or -dbitmap (Windows Bitmap). print -dformat filename exports the figure to the specified file using the specified graphics format, (such as TIFF). The Graphics Format table lists all
supported graphics-file formats.
print -options specifies print options that modify the action of the print command. (For example, the noui option suppresses printing of user interface
controls.) The Options section lists available options.
2-129
print, printopt
print(...) is the function form of print. It enables you to pass variables for
any input arguments. This form is useful passing filenames and handles. See Batch Processing for an example.
[pcmd,dev] = printopt returns strings containing the current system-dependent printing command and output device. printopt is an M-file used by print to produce the hardcopy output. You can edit the M-file printopt.m to set your default printer type and destination. pcmd and dev are platform-dependent strings. pcmd contains the command that print uses to send a file to the printer. dev contains the printer driver or graphics format option for the print command. Their defaults are platform
dependent.
Platform System Printing Command lpr r s COPY /B %s LPT1: Driver or Format dps2 dwin
UNIX Windows
Drivers
The table below shows the complete list of printer drivers supported by MATLAB. If you do not specify a driver, MATLAB uses the default setting shown in the previous table. Some of the drivers are available from a product called Ghostscript, which is shipped with MATLAB. The last column indicates when Ghostscript is used. Some drivers are not available on all platforms. This is noted in the first column of the table.
Printer Driver
PRINT Command Option String -dbj10e -dbj200 -dbjc600 -dbjc800
GhostScript
Canon BubbleJet BJ10e Canon BubbleJet BJ200 color Canon Color BubbleJet BJC-70/BJC-600/BJC-4000 Canon Color BubbleJet BJC-800
Yes Yes Yes Yes
2-130
print, printopt
Printer Driver
PRINT Command Option String -dln03 -depson -deps9high
GhostScript
DEC LN03 Epson and compatible 9- or 24-pin dot matrix print drivers Epson and compatible 9-pin with interleaved lines (triple
Yes Yes Yes Yes Yes Yes Yes Yes Yes
resolution)
Epson LQ-2550 and compatible; color (not supported on
-depsonc
HP-700)
Fujitsu 3400/2400/1200 HP DesignJet 650C color (not supported on Windows or
-depsonc -ddnj650c
DEC Alpha)
HP DeskJet 500 HP DeskJet 500C (creates black-and-white output) HP DeskJet 500C (with 24 bit/pixel color and high-quality Floyd-Steinberg color dithering) (not supported on Windows or DEC Alpha) HP DeskJet 500C/540C color (not supported on Windows or
-ddjet500 -dcdjmono -dcdjcolor
-dcdj500
Yes Yes Yes Yes Yes Yes Yes Yes Yes
DEC Alpha)
HP Deskjet 550C color (not supported on Windows or DEC
-dcdj550
Alpha)
HP DeskJet and DeskJet Plus HP LaserJet HP LaserJet+ HP LaserJet IIP HP LaserJet III HP LaserJet 4.5L and 5P HP LaserJet 5 and 6
-ddeskjet -dlaserjet -dljetplus -dljet2p -dljet3 -dljet4 -dpxlmono
2-131
print, printopt
Printer Driver
PRINT Command Option String -dpaintjet -dpjxl -dpjetxl -dpjxl300
GhostScript
HP PaintJet color HP PaintJet XL color HP PaintJet XL color HP PaintJet XL300 color (not supported on Windows or
Yes Yes Yes Yes No Yes No No No No No No
DEC Alpha)
HPGL for HP 7475A and other compatible plotters.
-dhpgl
(Renderer cannot be set to Z-buffer.)
IBM 9-pin Proprinter PostScript black and white PostScript color PostScript Level 2 black and white PostScript Level 2 color Windows color (Windows only) Windows monochrome (Windows only)
-dibmpro -dps -dpsc -dps2 -dpsc2 -dwinc -dwin
Note Generally, Level 2 PostScript files are smaller and render more quickly when printing than Level 1 PostScript files. However, not all PostScript printers support Level 2, so determine the capabilities of your printer before using those drivers. Level 2 PostScript is the default for UNIX. You can change this default by editing the printopt.m file.
Graphics Format Files
To save your figure as a graphics-format file, specify a format switch and filename. To set the resolution of the output file for a built-in MATLAB format, use the -r switch. (For example, -r300 sets the output resolution to 300 dots per inch.) The -r switch is also supported for Windows Enhanced Metafiles but is not supported for Ghostscript formats.
2-132
print, printopt
The table below shows the supported output formats for exporting from MATLAB and the switch settings to use. In some cases, a format is available both as a MATLAB output filter and as a Ghostscript output filter. The first column indicates this by showing "MATLAB" or "Ghostscript" in parentheses. All formats are supported on both the PC and UNIX platforms.
Graphics Format
Bitmap or Vector
PRINT Command Option String -dbmpmono -dbmp16m -dbmp256
MATLAB or Ghostscript
BMP Monochrome BMP BMP 24-bit BMP BMP 8-bit (256-color) BMP *this format uses a
Bitmap Bitmap Bitmap Bitmap Vector Vector Vector Vector Vector Bitmap Vector Bitmap Bitmap Bitmap Bitmap Bitmap
Ghostscript Ghostscript Ghostscript MATLAB MATLAB MATLAB MATLAB MATLAB MATLAB MATLAB MATLAB MATLAB Ghostscript Ghostscript Ghostscript Ghostscript
fixed colormap
BMP 24-bit EMF EPS black and white EPS color EPS Level 2 black and white EPS Level 2 color HDF 24-bit ILL (Adobe Illustrator) JPEG 24-bit PBM (plain format) 1-bit PBM (raw format) 1-bit PCX 1-bit PCX 24-bit color PCX file format, three 8-bit
-dbmp -dmeta -deps -depsc -deps2 -depsc2 -dhdf -dill -djpeg -dpbm -dpbmraw -dpcxmono -dpcx24b
planes
2-133
print, printopt
Graphics Format
Bitmap or Vector
PRINT Command Option String -dpcx256
MATLAB or Ghostscript
PCX 8-bit Newer color PCX file format
Bitmap Bitmap Bitmap
Ghostscript Ghostscript MATLAB Ghostscript Ghostscript Ghostscript MATLAB Ghostscript Ghostscript MATLAB
(256-color)
PCX Older color PCX file format (EGA/VGA,
-dpcx16
16-color)
PCX 8-bit PDF Color PDF file Format PGM Portable Graymap (plain format) PGM Portable Graymap (raw format) PNG 24-bit PPM Portable Pixmap, plain format PPM Portable Pixmap raw format TIFF 24-bit TIFF preview for EPS Files
-dpcx -dpdf
Bitmap Bitmap Bitmap Bitmap Bitmap Bitmap Bitmap
-dpgm -dpgmraw -dpng -dppm -dppmraw
-dtiff or -dtiffn
-tiff
The TIFF image format is supported on all platforms by almost all word processors for importing images. JPEG is a lossy, highly compressed format that is supported on all platforms for image processing and for inclusion into HTML documents on the World Wide Web. To create these formats, MATLAB renders the figure using the Z-buffer rendering method and the resulting bitmap is then saved to the specified file.
Options
This table summarizes options that you can specify for print. The second column also shows which tutorial sections contain more detailed information.
2-134
print, printopt
The sections listed are located under Printing and Exporting Figures with MATLAB.
Option -adobecset Description
PostScript only. Use PostScript default character set encoding. See "Early PostScript 1 Printers." PostScript only. Append figure to existing PostScript file. See "Settings That Are Driver Specific." PostScript only. Print with CMYK colors instead of RGB. See "Setting CMYK Color." Printing only. Printer driver to use. See Drivers table. Exporting only. Graphics format to use. See Graphics Format Files table. Display the Print Setup dialog. Handle of figure to print. Note that you cannot specify both this option and the -swindowtitle option. See "Which Figure Is Printed." PostScript and Ghostscript only. Use loose bounding box for PostScript. See "Producing Uncropped Figures." Suppress printing of user interface controls. See "Excluding User Interface Controls." Render using the OpenGL algorithm. Note that you cannot specify this method in conjunction with -zbuffer or -painters. See "Selecting a Renderer." Render using the Painter's algorithm. Note that you cannot specify this method in conjunction with -zbuffer or -OpenGL. See "Selecting a Renderer." Specify name of printer to use. See "Selecting Printer." PostScript and Ghostscript only. Specify resolution in dots per inch. See "Setting the Resolution."
-append
-cmyk
-ddriver -dformat -dsetup -fhandle
-loose
-noui
-OpenGL
-painters
-Pprinter -rnumber
2-135
print, printopt
Option -swindowtitle
Description
Specify name of Simulink system window to print. Note that you cannot specify both this option and the -fhandle option. See "Which Figure Is Printed." Windows only. Display the Windows Print dialog box. The v stands for "verbose mode." Render using the Z-buffer algorithm. Note that you cannot specify this method in conjunction with -OpenGL or -painters. See "Selecting a Renderer." MATLAB supports a number of standard paper sizes. You can select from the following list by setting the PaperType property of the figure or selecting a supported paper size from the Print dialog box.
Property Value usletter uslegal tabloid A0 A1 A2 A3 A4 A5 B0 B1 B2 Size (Width-by-Height)
-v
-zbuffer
Paper Sizes
8.5-by-11 inches 11-by-14 inches 11-by-17 inches 841-by-1189mm 594-by-841mm 420-by-594mm 297-by-420mm 210-by-297mm 148-by-210mm 1029-by-1456mm 728-by-1028mm 514-by-728mm
2-136
print, printopt
Property Value B3 B4 B5 arch-A arch-B arch-C arch-D arch-E A B C D E
Size (Width-by-Height)
364-by-514mm 257-by-364mm 182-by-257mm 9-by-12 inches 12-by-18 inches 18-by-24 inches 24-by-36 inches 36-by-48 inches 8.5-by-11 inches 11-by-17 inches 17-by-22 inches 22-by-34 inches 34-by-43 inches
Printing Tips
This section includes information about specific printing issues.
Figures with Resize Functions
The print command produces a warning when you print a figure having a callback routine defined for the figure ResizeFcn. To avoid the warning, set the figure PaperPositionMode property to auto or select Match Figure Screen Size in the File->Page Setup... dialog box.
Troubleshooting MS-Windows Printing
If you encounter problems such as segmentation violations, general protection faults, application errors, or the output does not appear as you expect when using MS-Windows printer drivers, try the following:
2-137
print, printopt
If your printer is PostScript compatible, print with one of the MATLAB built-in PostScript drivers. There are various PostScript device options that you can use with the print command: they all start with -dps. The behavior you are experiencing may occur only with certain versions of the print driver. Contact the print driver vendor for information on how to obtain and install a different driver. Try printing with one of the MATLAB built-in Ghostscript devices. These devices use Ghostscript to convert PostScript files into other formats, such as HP LaserJet, PCX, Canon BubbleJet, and so on. Copy the figure as a Windows Enhanced Metafile using the Edit-->Copy Figure menu item on the figure window menu or the print -dmeta option at the command line. You can then import the file into another application for printing. You can set copy options in the figure's File-->Preferences...-->Copying Options dialog box. The Windows Enhanced Metafile clipboard format produces a better quality image than Windows Bitmap.
Printing MATLAB GUIs
You can generally obtain better results when printing a figure window that contains MATLAB uicontrols by setting these key properties: Set the figure PaperPositionMode property to auto. This ensures the printed version is the same size as the onscreen version. With PaperPositionMode set to auto MATLAB does not resize the figure to fit the current value of the PaperPosition. This is particularly important if you have specified a figure ResizeFcn because if MATLAB resizes the figure during the print operation, the ResizeFcn is automatically called. To set PaperPositionMode on the current figure, use the command:
set(gcf,'PaperPositionMode','auto')
Set the figure InvertHardcopy property to off. By default, MATLAB changes the figure background color of printed output to white, but does not change the color of uicontrols. If you have set the background color to, for example, match the gray of the GUI devices, you must set InvertHardcopy to off to preserve the color scheme. To set InvertHardcopy on the current figure, use the command:
set(gcf,'InvertHardcopy','off')
2-138
print, printopt
Use a color device if you want lines and text that are in color on the screen to be written to the output file as colored objects. Black and white devices convert colored lines and text to black or white to provide the best contrast with the background and to avoid dithering. Use the print command's -loose option to prevent MATLAB from using a bounding box that is tightly wrapped around objects contained in the figure. This is important if you have intentionally used space between uicontrols or axes and the edge of the figure and you want to maintain this appearance in the printed output.
Notes on Printing Interpolated Shading with PostScript Drivers
MATLAB can print surface objects (such as graphs created with surf or mesh) using interpolated colors. However, only patch objects that are composed of triangular faces can be printed using interpolated shading. Printed output is always interpolated in RGB space, not in the colormap colors. This means, if you are using indexed color and interpolated face coloring, the printed output can look different from what is displayed on screen. PostScript files generated for interpolated shading contain the color information of the graphics object's vertices and require the printer to perform the interpolation calculations. This can take an excessive amount of time and in some cases, printers may actually "time-out" before finishing the print job. One solution to this problem is to interpolate the data and generate a greater number of faces, which can then be flat shaded. To ensure that the printed output matches what you see on the screen, print using the -zbuffer option. To obtain higher resolution (for example, to make text look better), use the -r option to increase the resolution. There is, however, a trade-off between the resolution and the size of the created PostScript file, which can be quite large at higher resolutions. The default resolution of 150 dpi generally produces good results. You can reduce the size of the output file by making the figure smaller before printing it and setting the figure PaperPositionMode to auto, or by just setting the PaperPosition property to a smaller size.
2-139
print, printopt
Note that in some UNIX environments, the default lpr command cannot print files larger than 1 Mbyte unless you use the -s option, which MATLAB does by default. See the lpr man page for more information.
Examples
Specifying the Figure to Print
You can print a noncurrent figure by specifying the figure's handle. If a figure has the title "Figure No. 2", its handle is 2. The syntax is,
print -fhandle
This example prints the figure whose handle is 2, regardless of which figure is the current figure.
print -f2
Note Note that you must use the -f option if the figure's handle is hidden (i.e., its HandleVisibility property is set to off).
This example saves the figure with the handle -f2 to a PostScript file named Figure2, which can be printed later.
print -f2 -dps 'Figure2.ps'
If the figure uses noninteger handles, use the figure command to get its value, and then pass it in as the first argument.
h = figure('IntegerHandle','off') print h -depson
You can also pass a figure handle as a variable to the function form of print. For example,
h = figure; plot(1:4,5:8) print(h)
This example uses the function form of print to enable a filename to be passed in as a variable.
filename = 'mydata';
2-140
print, printopt
print('-f3', '-dpsc', filename);
(Because a filename is specified, the figure will be printed to a file.)
Specifying the Model to Print
To print a noncurrent Simulink model, use the -s option with the title of the window. For example, this command prints the Simulink window titled f14.
print -sf14
If the window title includes any spaces, you must call the function form rather than the command form of print. For example, this command saves a Simulink window title Thruster Control.
print('-sThruster Control')
To print the current system use:
print -s
For information about issues specific to printing Simulink windows, see the Simulink documentation. This example prints a surface plot with interpolated shading. Setting the current figure's (gcf) PaperPositionMode to auto enables you to resize the figure window and print it at the size you see on the screen. See Options and the previous section for information on the -zbuffer and -r200 options.
surf(peaks) shading interp set(gcf,'PaperPositionMode','auto') print -dpsc2 -zbuffer -r200
Batch Processing
You can use the function form of print to pass variables containing file names. For example, this for loop creates a series of graphs and prints each one with a different file name.
for k=1:length(fnames) surf(Z(:,:,k)) print('-dtiff','-r200',fnames(k)) end
2-141
print, printopt
Tiff Preview
The command:
print -depsc -tiff -r300 picture1
saves the current figure at 300 dpi, in a color Encapsulated PostScript file named picture1.eps. The -tiff option creates a 72 dpi TIFF preview, which many word processor applications can display on screen after you import the EPS file. This enables you to view the picture on screen within your word processor and print the document to a PostScript printer using a resolution of 300 dpi.
See Also
orient, figure
2-142
printdlg
Purpose Syntax
2printdlg
Display print dialog box
printdlg printdlg(fig) printdlg('-crossplatform',fig) printdlg('-setup',fig) printdlg prints the current figure. printdlg(fig) creates a dialog box from which you can print the figure window identified by the handle fig. Note that uimenus do not print. printdlg('-crossplatform',fig) displays the standard cross-platform
Description
MATLAB printing dialog rather than the built-in printing dialog box for Microsoft Windows computers. Insert this option before the fig argument.
printdlg('-setup',fig) forces the printing dialog to appear in a setup mode.
Here one can set the default printing options without actually printing.
2-143
printpreview
Purpose Syntax Description
2printpreview
Preview figure to be printed
printpreview printpreview(f) printpreview displays a dialog box showing the figure in the currently active figure window as it will be printed. The figure is displayed with a 1/4 size
thumbnail or full size image.
printpreview(f) displays a dialog box showing the figure having the handle f
as it will be printed. You can select any of the following options from the Print Preview dialog box.
Option Button Print... Page Setup... Zoom In Zoom Out Close Description
Close Print Preview and open the Print dialog Open the Page Setup dialog Display a full size image of the page Display a 1/4 scaled image of the page Close the Print Preview dialog
See Also
printdlg, pagesetupdlg
2-144
prod
Purpose Syntax Description
2prod
Product of array elements
B = prod(A) B = prod(A,dim) B = prod(A) returns the products along different dimensions of an array.
If A is a vector, prod(A) returns the product of the elements. If A is a matrix, prod(A) treats the columns of A as vectors, returning a row vector of the products of each column. If A is a multidimensional array, prod(A) treats the values along the first non-singleton dimension as vectors, returning an array of row vectors.
B = prod(A,dim) takes the products along the dimension of A specified by
scalar dim.
Examples
The magic square of order 3 is
M = magic(3) M = 8 3 4 1 5 9 6 7 2
The product of the elements in each column is
prod(M) = 96 45 84
The product of the elements in each row can be obtained by:
prod(M,2) = 48 105 72
See Also
cumprod, diff, sum
2-145
profile
Purpose Graphical Interface Syntax
2profile
Tool for optimizing and debugging M-file code As an alternative to the profile function, select View -> Profiler from the desktop.
profile viewer profile on profile on -detail level profile on -history profile off profile resume profile clear profile report profile report basename profile plot s = profile('status') stats = profile('info')
Description
The profile function helps you debug and optimize M-files by tracking their execution time. For each function in the M-file, profile records information about execution time, number of calls, parent functions, child functions, code line hit count, and code line execution time. Some people use profile simply to see the child functions; see also depfun for that purpose. The Profiler user interface, opened with profile viewer, provides information gathered using the profile function, but presents the information in a different format from profile report.
profile viewer opens the Profiler graphical interface, a tool for assessing
M-file performance to help you identify potential performance improvements. It is based on the results returned by the profile function, but presents the information a different format than the profile report. The report function provides some options not available with the Profiler, including saving the reports to a file.
profile on starts profile, clearing previously recorded profile statistics.
2-146
profile
profile on -detail level starts profile for the set of functions specified by level, clearing previously recorded profile statistics. Value for level mmex Functions profile Gathers Information About
M-functions, M-subfunctions, and MEX-functions; mmex is the default value Same functions as for mmex plus built-in functions such as eig Same functions as for builtin plus built-in operators such as +
builtin
operator
profile on -history starts profile, clearing previously recorded profile statistics, and recording the exact sequence of function calls. The profile
function records up to 10,000 function entry and exit events. For more than 10,000 events, profile continues to record other profile statistics, but not the sequence of calls.
profile off suspends profile. profile resume restarts profile without clearing previously recorded
statistics.
profile clear clears the statistics recorded by profile. profile report suspends profile, generates a profile report in HTML
format, and displays the report in your system's default Web browser. This report contains some different information than what is available in the Profiler reports.
profile report basename suspends profile, generates a profile report in HTML format, saves the report in the file basename in the current directory,
and displays the report in your system's default Web browser. Because the report consists of several files, do not provide an extension for basename.
profile plot suspends profile and displays in a figure window a bar graph of the functions using the most execution time.
2-147
profile
s = profile('status') displays a structure containing the current profile
status. The structure's fields are
Field ProfilerStatus DetailLevel HistoryTracking Values 'on' or 'off' 'mmex', 'builtin', or 'operator' 'on' or 'off'
stats = profile('info') suspends profile and displays a structure containing profile results. Use this function to access the data generated by profile. The structure's fields are Field FunctionTable FunctionHistory ClockPrecision Description
Array containing list of all functions called Array containing function call history Precision of profile's time measurement
Remarks
To see an example of a profile report and profile plot, as well as to learn more about the results and how to use profiling, see "Measuring Performance" and "The profile Function" in MATLAB Programming documentation. Follow these steps to run profile and create a profile report.
1 Run profile for code that computes the Lotka-Volterra predator-prey
Examples
population model.
profile on -detail builtin -history [t,y] = ode23('lotka',[0 2],[20;20]); profile report
The profile report appears in your system's default Web browser, providing information for all M-functions, M-subfunctions, MEX-functions, and built-in functions. The report includes the function call history.
2-148
profile
2 Generate the profile plot.
profile plot
The profile plot appears in a figure window.
3 Because the report and plot features suspend profile, resume its operation
without clearing the statistics already gathered.
profile resume
The profile function continues gathering statistics when you execute the next M-file.
See Also
depdir, depfun, profreport, tic
See "Measuring Performance", "The Profiler", and "The profile Function" in the MATLAB Programming documentation.
2-149
profreport
Purpose Syntax
2profreport
Generate profile report
profreport profreport(basename) profreport(stats) profreport(basename,stats) profreport suspends the profile function, generates a profile report in HTML format using the current profile results, and displays the report in a
Description
Web browser. This presents the information in a different format from the Profiler reports.
profreport(basename) suspends profile, generates a profile report in HTML format using the current profile results, saves the report using the basename
you supply, and displays the report in a Web browser. Because the report consists of several files, do not provide an extension for basename.
profreport(stats) suspends profile, generates a profile report in HTML format using the info results from profile, and displays the report in a Web browser. Here, stats is the profile information structure returned by stats = profile('info'). profreport(basename,stats) suspends profile, generates a profile report in HTML format using the stats result from profile, saves the report using the basename you supply, and displays the report in a Web browser. Here, stats is the profile information structure returned by stats = profile('info').
Because the report consists of several files, do not provide an extension for basename.
Examples
Run profile and view the structure containing profile results.
1 Run profile for code that computes the Lotka-Volterra predator-prey
population model.
profile on -detail builtin -history [t,y] = ode23('lotka',[0 2],[20;20]);
2-150
profreport
2 View the structure containing the profile results.
stats = profile('info')
MATLAB returns
stats = FunctionTable: [42x1 FunctionHistory: ClockPrecision: Name: struct] [2x830 double] 0.0100 'MATLAB'
3 View the contents of the second element in the FunctionTable structure.
stats.FunctionTable(2)
MATLAB returns
ans = FunctionName: FileName: Type: NumCalls: TotalTime: TotalRecursiveTime: Children: Parents: ExecutedLines: 'horzcat' '' 'Builtin-function' 43 0 0 [0x1 struct] [2x1 struct] [0x3 double]
4 Display the profile report from the structure.
profreport(stats)
MATLAB displays the profile report in a Web browser.
See Also
profile
"Measuring Performance" and "The profile Function" in MATLAB Programming documentation
2-151
propedit
Purpose Syntax Description
2propedit
Starts the Property Editor
propedit propedit(HandleList) propedit starts the Property Editor, a graphical user interface to the
properties of Handle Graphics objects. If you call it without any input arguments, the Property Editor displays the properties of the current figure, if there are more than one figure displayed, or the root object, if there is no currently active figure.
propedit(HandleList) edits the properties for the object (or objects) in HandleList.
Note Starting the Property Editor enables plot editing mode for the figure.
2-152
propedit
Remarks
Property Editor Graphical User Interface Components
Use these buttons to move back and forth among the graphics objects you have edited. Use the navigation bar to select the object you want to edit. Click on a tab to view a group of properties.
Click here to view a list of values for this field.
Click Apply to apply your changes without dismissing the Property Editor. Click Cancel to dismiss the Property Editor without applying your changes. Click OK to apply your changes and dismiss the Property Editor. Check this box to see the effect of your changes as you make them. Click Help to get information about particular properties.
See Also
plotedit
2-153
propedit (COM)
Purpose Syntax Arguments Description
2propedit (COM)
Request the control to display its built-in property page
propedit(h) h
Handle for a MATLAB COM control object. Request the control to display its built-in property page. Note that some controls do not have a built-in property page. For those objects, this command will fail. Create a Microsoft Calendar control and display its property page:
cal = actxcontrol('mscal.calendar', [0 0 500 500]); propedit(cal)
Examples
See Also
inspect, get
2-154
psi
Purpose Syntax
2psi
Psi (polygamma) function
Y = psi(X) Y = psi(k,X) Y = psi(k0:k1,X) Y = psi(X) evaluates the function for each element of array X. X must be real and nonnegative. The function, also known as the digamma function, is the logarithmic derivative of the gamma function
Description
( x ) = digamma ( x ) d ( log ( ( x ) ) ) = --------------------------------dx d(( x)) / dx = ---------------------------( x)
Y = psi(k,X) evaluates the kth derivative of at the elements of X. psi(0,X) is the digamma function, psi(1,X) is the trigamma function, psi(2,X) is the
tetragamma function, etc.
Y = psi(k0:k1,X) evaluates derivatives of order k0 through k1 at X. Y(k,j) is the (k-1+k0)th derivative of , evaluated at X(j).
Examples
Example 1. Use the psi function to calculate Euler's constant, .
format long -psi(1) ans = 0.57721566490153 -psi(0,1) ans = 0.57721566490153
Example 2. The trigamma function of 2, psi(1,2), is the same as ( / 6 ) 1 .
format long psi(1,2) ans = 0.64493406684823
2
2-155
psi
pi^2/6 - 1 ans = 0.64493406684823
Example 3. This code produces the first page of Table 6.1 in Abramowitz and
Stegun [].
x = (1:.005:1.250)'; [x gamma(x) gammaln(x) psi(0:1,x)' x-1]
Example 4. This code produces a portion of Table 6.2 in [].
psi(2:3,1:.01:2)'
See Also References
gamma, gammainc, gammaln
Abramowitz, M. and I. A. Stegun, Handbook of Mathematical Functions, Dover Publlications, 1965, Sections 6.3 and 6.4.
2-156
pwd
Purpose Graphical Interface Syntax Description
2pwd
Display current directory As an alternative to the pwd function, use the Current Directory field in the MATLAB desktop toolbar.
pwd s = pwd pwd displays the current working directory. s = pwd returns the current directory to the variable s.
See Also
cd, dir, path, what
2-157
qmr
Purpose Syntax
2qmr
Quasi-Minimal Residual method
x = qmr(A,b) qmr(A,b,tol) qmr(A,b,tol,maxit) qmr(A,b,tol,maxit,M) qmr(A,b,tol,maxit,M1,M2) qmr(A,b,tol,maxit,M1,M2,x0) qmr(afun,b,tol,maxit,m1fun,m2fun,x0,p1,p2,...) [x,flag] = qmr(A,b,...) [x,flag,relres] = qmr(A,b,...) [x,flag,relres,iter] = qmr(A,b,...) [x,flag,relres,iter,resvec] = qmr(A,b,...) x = qmr(A,b) attempts to solve the system of linear equations A*x=b for x. The n-by-n coefficient matrix A must be square and should be large and sparse. The column vector b must have length n. A can be a function afun such that afun(x) returns A*x and afun(x,'transp') returns A'*x.
Description
If qmr converges, a message to that effect is displayed. If qmr fails to converge after the maximum number of iterations or halts for any reason, a warning message is printed displaying the relative residual norm(b-A*x)/norm(b) and the iteration number at which the method stopped or failed.
qmr(A,b,tol) specifies the tolerance of the method. If tol is [], then qmr uses the default, 1e-6. qmr(A,b,tol,maxit) specifies the maximum number of iterations. If maxit is [], then qmr uses the default, min(n,20). qmr(A,b,tol,maxit,M) and qmr(A,b,tol,maxit,M1,M2) use preconditioners M or M = M1*M2 and effectively solve the system inv(M)*A*x = inv(M)*b for x. If M is [] then qmr applies no preconditioner. M can be a function mfun such that mfun(x) returns M\x and mfun(x,'transp') returns M'\x. qmr(A,b,tol,maxit,M1,M2,x0) specifies the initial guess. If x0 is [], then qmr
uses the default, an all zero vector.
2-158
qmr
qmr(afun,b,tol,maxit,m1fun,m2fun,x0,p1,p2,...) passes parameters p1,p2,... to functions afun(x,p1,p2,...) and afun(x,p1,p2,...,'transp') and similarly to the preconditioner functions m1fun and m2fun. [x,flag] = qmr(A,b,...) also returns a convergence flag.
Flag 0
Convergence qmr converged to the desired tolerance tol within maxit
iterations.
1 2 3 qmr iterated maxit times but did not converge.
Preconditioner M was ill-conditioned. The method stagnated. (Two consecutive iterates were the same.) One of the scalar quantities calculated during qmr became too small or too large to continue computing.
4
Whenever flag is not 0, the solution x returned is that with minimal norm residual computed over all the iterations. No messages are displayed if the flag output is specified.
[x,flag,relres] = qmr(A,b,...) also returns the relative residual norm(b-A*x)/norm(b). If flag is 0, relres <= tol. [x,flag,relres,iter] = qmr(A,b,...) also returns the iteration number at which x was computed, where 0 <= iter <= maxit. [x,flag,relres,iter,resvec] = qmr(A,b,...) also returns a vector of the residual norms at each iteration, including norm(b-A*x0).
Examples
Example 1.
n = 100; on = ones(n,1); A = spdiags([-2*on 4*on -on],-1:1,n,n); b = sum(A,2);
2-159
qmr
tol = 1e-8; maxit = 15; M1 = spdiags([on/(-2) on],-1:0,n,n); M2 = spdiags([4*on -on],0:1,n,n); x = qmr(A,b,tol,maxit,M1,M2,[]);
Alternatively, use this matrix-vector product function
function y = afun(x,n,transp_flag) if (nargin > 2) & strcmp(transp_flag,'transp') y = 4 * x; y(1:n-1) = y(1:n-1) - 2 * x(2:n); y(2:n) = y(2:n) - x(1:n-1); else y = 4 * x; y(2:n) = y(2:n) - 2 * x(1:n-1); y(1:n-1) = y(1:n-1) - x(2:n); end
as input to qmr
x1 = qmr(@afun,b,tol,maxit,M1,M2,[],n);
Example 2.
load west0479; A = west0479; b = sum(A,2); [x,flag] = qmr(A,b) flag is 1 because qmr does not converge to the default tolerance 1e-6 within the
default 20 iterations.
[L1,U1] = luinc(A,1e-5); [x1,flag1] = qmr(A,b,1e-6,20,L1,U1) flag1 is 2 because the upper triangular U1 has a zero on its diagonal, and qmr fails in the first iteration when it tries to solve a system such as U1*y = r for y using backslash. [L2,U2] = luinc(A,1e-6); [x2,flag2,relres2,iter2,resvec2] = qmr(A,b,1e-15,10,L2,U2) flag2 is 0 because qmr converges to the tolerance of 1.6571e-016 (the value of relres2) at the eighth iteration (the value of iter2) when preconditioned by
2-160
qmr
the incomplete LU factorization with a drop tolerance of 1e-6. resvec2(1) = norm(b) and resvec2(9) = norm(b-A*x2). You can follow the progress of qmr by plotting the relative residuals at each iteration starting from the initial estimate (iterate number 0).
semilogy(0:iter2,resvec2/norm(b),'-o') xlabel('iteration number') ylabel('relative residual')
10
2
10
0
10
-2
10 relative residual
-4
10
-6
10
-8
10
-10
10
-12
10
-14
10
-16
0
1
2
3
4 iteration number
5
6
7
8
See Also
bicg, bicgstab, cgs, gmres, lsqr, luinc, minres, pcg, symmlq @ (function handle), \ (backslash)
References
[1] Barrett, R., M. Berry, T. F. Chan, et al., Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia, 1994. [2] Freund, Roland W. and Nel M. Nachtigal, "QMR: A quasi-minimal residual method for non-Hermitian linear systems", SIAM Journal: Numer. Math. 60, 1991, pp. 315-339.
2-161
qr
Purpose Syntax
2qr
Orthogonal-triangular decomposition
[Q,R] = qr(A) [Q,R] = qr(A,0) [Q,R,E] = qr(A) [Q,R,E] = qr(A,0) X = qr(A) R = qr(A) [C,R] = qr(A,B) R = qr(A,0) [C,R] = qr(A,B,0)
(full and sparse matrices) (full and sparse matrices) (full matrices) (full matrices) (full matrices) (sparse matrices) (sparse matrices) (sparse matrices) (sparse matrices)
Description
The qr function performs the orthogonal-triangular decomposition of a matrix. This factorization is useful for both square and rectangular matrices. It expresses the matrix as the product of a real orthonormal or complex unitary matrix and an upper triangular matrix.
[Q,R] = qr(A) produces an upper triangular matrix R of the same dimension as A and a unitary matrix Q so that A = Q*R. For sparse matrices, Q is often nearly full. If [m n] = size(A), then Q is m-by-m and R is m-by-n. [Q,R] = qr(A,0) produces an "economy-size" decomposition. If [m n] = size(A), and m > n, then qr computes only the first n columns of of Q and R is n-by-n. If m <= n, it is the same as [Q,R] = qr(A). [Q,R,E] = qr(A) for full matrix A, produces a permutation matrix E, an upper triangular matrix R with decreasing diagonal elements, and a unitary matrix Q so that A*E = Q*R. The column permutation E is chosen so that abs(diag(R))
is decreasing.
[Q,R,E] = qr(A,0) for full matrix A, produces an "economy-size" decomposition in which E is a permutation vector, so that A(:,E) = Q*R. The column permutation E is chosen so that abs(diag(R)) is decreasing. X = qr(A) for full matrix A, returns the output of the LAPACK subroutine DGEQRF or ZGEQRF. triu(qr(A)) is R.
2-162
qr
R = qr(A) for sparse matrix A, produces only an upper triangular matrix, R. The matrix R provides a Cholesky factorization for the matrix associated with
the normal equations,
R'*R = A'*A
This approach avoids the loss of numerical information inherent in the computation of A'*A. It may be preferred to [Q,R] = qr(A) since Q is always nearly full.
[C,R] = qr(A,B) for sparse matrix A, applies the orthogonal transformations to B, producing C = Q'*B without computing Q. B and A must have the same number of rows. R = qr(A,0) and [C,R] = qr(A,B,0) for sparse matrix A, produce "economy-size" results.
For sparse matrices, the Q-less QR factorization allows the solution of sparse least squares problems minimize Ax b with two steps
[C,R] = qr(A,b) x = R\c
If A is sparse but not square, MATLAB uses the two steps above for the linear equation solving backslash operator, i.e., x = A\b.
Examples
Example 1. Start with
A = [ 1 4 7 10 2 5 8 11 3 6 9 12 ]
This is a rank-deficient matrix; the middle column is the average of the other two columns. The rank deficiency is revealed by the factorization:
[Q,R] = qr(A) Q =
2-163
qr
-0.0776 -0.3105 -0.5433 -0.7762 R = -12.8841 0 0 0
-0.8331 -0.4512 -0.0694 0.3124
0.5444 -0.7709 -0.0913 0.3178
0.0605 0.3251 -0.8317 0.4461
-14.5916 -1.0413 0 0
-16.2992 -2.0826 0.0000 0
The triangular structure of R gives it zeros below the diagonal; the zero on the diagonal in R(3,3) implies that R, and consequently A, does not have full rank.
Example 2. This examples uses matrix A from the first example. The QR
factorization is used to solve linear systems with more equations than unknowns. For example, let
b = [1;3;5;7]
The linear system Ax = b represents four equations in only three unknowns. The best solution in a least squares sense is computed by
x = A\b
which produces
Warning: Rank deficient, rank = 2, tol = 1.4594E-014 x = 0.5000 0 0.1667
The quantity tol is a tolerance used to decide if a diagonal element of R is negligible. If [Q,R,E] = qr(A), then
tol = max(size(A))*eps*abs(R(1,1))
The solution x was computed using the factorization and the two steps
y = Q'*b; x = R\y
2-164
qr
The computed solution can be checked by forming Ax . This equals b to within roundoff error, which indicates that even though the simultaneous equations Ax = b are overdetermined and rank deficient, they happen to be consistent. There are infinitely many solution vectors x; the QR factorization has found just one of them.
Algorithm
The qr function uses LAPACK routines to compute the QR decomposition:
Syntax R = qr(A) R = qr(A,0) [Q,R] = qr(A) [Q,R] = qr(A,0) [Q,R,e] = qr(A) [Q,R,e] = qr(A,0)
Real DGEQRF DGEQRF, DORGQR DGEQP3, DORGQR
Complex ZGEQRF ZGEQRF, ZUNGQR ZGEQPF, ZUNGQR
See Also
lu, null, orth, qrdelete, qrinsert, qrupdate
The arithmetic operators \ and /
References
[1] Anderson, E., Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra, J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen, LAPACK User's Guide (http://www.netlib.org/lapack/lug/lapack_lug.html), Third Edition, SIAM, Philadelphia, 1999.
2-165
qrdelete
Purpose Syntax
2qrdelete
Delete column or row from QR factorization
[Q1,R1] = qrdelete(Q,R,j) [Q1,R1] = qrdelete(Q,R,j,'col') [Q1,R1] = qrdelete(Q,R,j,'row') [Q1,R1] = qrdelete(Q,R,j) returns the QR factorization of the matrix A1, where A1 is A with the column A(:,j) removed and [Q,R] = qr(A) is the QR factorization of A. [Q1,R1] = qrdelete(Q,R,j,'col') is the same as qrdelete(Q,R,j). [Q1,R1] = qrdelete(Q,R,j,'row') returns the QR factorization of the matrix A1, where A1 is A with the row A(j,:) removed and [Q,R] = qr(A) is the QR factorization of A.
Description
Examples
A = magic(5); [Q,R] = qr(A); j = 3; [Q1,R1] = qrdelete(Q,R,j,'row'); Q1 = 0.5274 0.7135 0.3102 0.3413 R1 = 32.2335 0 0 0 -0.5197 0.6911 -0.1982 -0.4616 -0.6697 0.0158 0.4675 0.5768 -0.0578 0.1142 -0.8037 0.5811
26.0908 -19.7045 0 0
19.9482 -10.9891 22.7444 0
21.4063 0.4318 5.8357 -14.5784
23.3297 -1.4873 -3.1977 3.7796
returns a valid QR factorization, although possibly different from
A2 = A; A2(j,:) = []; [Q2,R2] = qr(A2)
2-166
qrdelete
Q2 = -0.5274 -0.7135 -0.3102 -0.3413 R2 = -32.2335 0 0 0
0.5197 -0.6911 0.1982 0.4616
0.6697 -0.0158 -0.4675 -0.5768
-0.0578 0.1142 -0.8037 0.5811
-26.0908 19.7045 0 0
-19.9482 10.9891 -22.7444 0
-21.4063 -0.4318 -5.8357 -14.5784
-23.3297 1.4873 3.1977 3.7796
Algorithm See Also
The qrdelete function uses a series of Givens rotations to zero out the appropriate elements of the factorization.
planerot, qr, qrinsert
2-167
qrinsert
Purpose Syntax
2qrinsert
Insert column or row into QR factorization
[Q1,R1] = qrinsert(Q,R,j,x) [Q1,R1] = qrinsert(Q,R,j,x,'col') [Q1,R1] = qrinsert(Q,R,j,x,'row') [Q1,R1] = qrinsert(Q,R,j,x) returns the QR factorization of the matrix A1, where A1 is A = Q*R with the column x inserted before A(:,j). If A has n columns and j = n+1, then x is inserted after the last column of A. [Q1,R1] = qrinsert(Q,R,j,x,'col') is the same as qrinsert(Q,R,j,x). [Q1,R1] = qrinsert(Q,R,j,x,'row') returns the QR factorization of the matrix A1, where A1 is A = Q*R with an extra row, x, inserted before A(j,:).
Description
Examples
A = magic(5); [Q,R] = qr(A); j = 3; x = 1:5; [Q1,R1] = qrinsert(Q,R,j,x,'row') Q1 = 0.5231 0.7078 0.0308 0.1231 0.3077 0.3385 R1 = 32.4962 0 0 0 0 0 0.5039 -0.6966 0.0592 0.1363 0.1902 0.4500 -0.6750 0.0190 0.0656 0.3542 0.4100 0.4961 0.1205 -0.0788 0.1169 0.6222 0.4161 -0.6366 0.0411 0.0833 0.1527 0.6398 -0.7264 0.1761 0.0225 -0.0150 -0.9769 0.2104 -0.0150 0.0225
26.6801 19.9292 0 0 0 0
21.4795 12.4403 24.4514 0 0 0
23.8182 2.1340 11.8132 20.2382 0 0
26.0031 4.3271 3.9931 10.3392 16.1948 0
returns a valid QR factorization, although possibly different from
2-168
qrinsert
A2 = [A(1:j-1,:); x; A(j:end,:)]; [Q2,R2] = qr(A2) Q2 = -0.5231 -0.7078 -0.0308 -0.1231 -0.3077 -0.3385 R2 = -32.4962 0 0 0 0 0
0.5039 -0.6966 0.0592 0.1363 0.1902 0.4500
0.6750 -0.0190 -0.0656 -0.3542 -0.4100 -0.4961
-0.1205 0.0788 -0.1169 -0.6222 -0.4161 0.6366
0.0411 0.0833 0.1527 0.6398 -0.7264 0.1761
0.0225 -0.0150 -0.9769 0.2104 -0.0150 0.0225
-26.6801 19.9292 0 0 0 0
-21.4795 12.4403 -24.4514 0 0 0
-23.8182 2.1340 -11.8132 -20.2382 0 0
-26.0031 4.3271 -3.9931 -10.3392 16.1948 0
Algorithm
The qrinsert function inserts the values of x into the jth column (row) of R. It then uses a series of Givens rotations to zero out the nonzero elements of R on and below the diagonal in the jth column (row).
planerot, qr, qrdelete
See Also
2-169
qrupdate
Description Syntax Description
2qrupdate
Rank 1 update to QR factorization
[Q1,R1] = qrupdate(Q,R,u,v) [Q1,R1] = qrupdate(Q,R,u,v) when [Q,R] = qr(A) is the original QR factorization of A, returns the QR factorization of A + u*v', where u and v are
column vectors of appropriate lengths.
Remarks Examples
qrupdate works only for full matrices.
The matrix
mu = sqrt(eps) mu = 1.4901e-08 A = [ones(1,4); mu*eye(4)];
is a well-known example in least squares that indicates the dangers of forming A'*A. Instead, we work with the QR factorization orthonormal Q and upper triangular R.
[Q,R] = qr(A);
As we expect, R is upper triangular.
R = -1.0000 0 0 0 0 -1.0000 0.0000 0 0 0 -1.0000 0.0000 0.0000 0 0 -1.0000 0.0000 0.0000 0.0000 0
In this case, the upper triangular entries of R, excluding the first row, are on the order of sqrt(eps). Consider the update vectors
u = [-1 0 0 0 0]'; v = ones(4,1);
2-170
qrupdate
Instead of computing the rather trivial QR factorization of this rank one update to A from scratch with
[QT,RT] = qr(A + u*v') QT = 0 -1 0 0 0 RT = 1.0e-007 * -0.1490 0 0 0 0 0 -0.1490 0 0 0 0 0 -0.1490 0 0 0 0 0 -0.1490 0 0 0 -1 0 0 0 0 0 -1 0 0 0 0 0 -1 1 0 0 0 0
we may use qrupdate.
[Q1,R1] = qrupdate(Q,R,u,v) Q1 = -0.0000 1.0000 0.0000 0.0000 -0.0000 R1 = 1.0e-007 * 0.1490 0.0000 0 0.1490 0 0 -0.0000 -0.0000 1.0000 0.0000 -0.0000 -0.0000 -0.0000 -0.0000 1.0000 -0.0000 -0.0000 -0.0000 -0.0000 -0.0000 1.0000 1.0000 0.0000 0.0000 0.0000 0.0000
0.0000 0.0000 0.1490
0.0000 0.0000 0.0000
2-171
qrupdate
0 0
0 0
0 0
0.1490 0
Note that both factorizations are correct, even though they are different.
Algorithm
qrupdate uses the algorithm in section 12.5.1 of the third edition of Matrix Computations by Golub and van Loan. qrupdate is useful since, if we take N = max(m,n), then computing the new QR factorization from scratch is roughly an O ( N 3 ) algorithm, while simply updating the existing factors in this way is an O ( N 2 ) algorithm.
References See Also
[1] Golub, Gene H. and Charles Van Loan, Matrix Computations, Third Edition, Johns Hopkins University Press, Baltimore, 1996
cholupdate, qr
2-172
quad, quad8
Purpose
2quad, quad8
Numerically evaluate integral, adaptive Simpson quadrature
Note The quad8 function, which implemented a higher order method, is obsolete. The quadl function is its recommended replacement.
Syntax
q = quad(fun,a,b) q = quad(fun,a,b,tol) q = quad(fun,a,b,tol,trace) q = quad(fun,a,b,tol,trace,p1,p2,...) [q,fcnt] = quadl(fun,a,b,...)
Description
Quadrature is a numerical method used to find the area under the graph of a function, that is, to compute a definite integral. q =
a f ( x ) dx
b
q = quad(fun,a,b) approximates the integral of function fun from a to b to within an error of 10-6 using recursive adaptive Simpson quadrature. fun accepts a vector x and returns a vector y, the function fun evaluated at each element of x. q = quad(fun,a,b,tol) uses an absolute error tolerance tol instead of the default which is 1.0e-6. Larger values of tol result in fewer function
evaluations and faster computation, but less accurate results. In MATLAB version 5.3 and earlier, the quad function used a less reliable algorithm and a default relative tolerance of 1.0e-3.
q = quad(fun,a,b,tol,trace) with non-zero trace shows the values of [fcnt a b-a Q] during the recursion. q = quad(fun,a,b,tol,trace,p1,p2,...) provides for additional arguments p1,p2,... to be passed directly to function fun, fun(x,p1,p2,...). Pass empty matrices for tol or trace to use the default values. [q,fcnt] = quad(...) returns the number of function evaluations.
2-173
quad, quad8
The function quadl may be more efficient with high accuracies and smooth integrands.
Examples
The function fun can be An inline object
F = inline('1./(x.^3-2*x-5)'); Q = quad(F,0,2);
A function handle
Q = quad(@myfun,0,2);
where myfun.m is an M-file.
function y = myfun(x) y = 1./(x.^3-2*x-5);
Algorithm Diagnostics
quad implements a low order method using an adaptive recursive Simpson's
rule.
quad may issue one of the following warnings: 'Minimum step size reached' indicates that the recursive interval
subdivision has produced a subinterval whose length is on the order of roundoff error in the length of the original interval. A nonintegrable singularity is possible.
'Maximum function count exceeded' indicates that the integrand has been evaluated more than 10,000 times. A nonintegrable singularity is likely. 'Infinite or Not-a-Number function value encountered' indicates a
floating point overflow or division by zero during the evaluation of the integrand in the interior of the interval.
See Also References
dblquad, inline, quadl, triplequad, @ (function handle)
[1] Gander, W. and W. Gautschi, "Adaptive Quadrature Revisited", BIT, Vol. 40, 2000, pp. 84-101. This document is also available at http://www.inf.ethz.ch/personal/gander.
2-174
quadl
Purpose Syntax
2quadl
Numerically evaluate integral, adaptive Lobatto quadrature
q = quadl(fun,a,b) q = quadl(fun,a,b,tol) q = quadl(fun,a,b,tol,trace) q = quadl(fun,a,b,tol,trace,p1,p2,...) [q,fcnt] = quadl(fun,a,b,...) q = quadl(fun,a,b) approximates the integral of function fun from a to b, to within an error of 10-6 using recursive adaptive Lobatto quadrature. fun accepts a vector x and returns a vector y, the function fun evaluated at each element of x. q = quadl(fun,a,b,tol) uses an absolute error tolerance of tol instead of the default, which is 1.0e-6. Larger values of tol result in fewer function evaluations and faster computation, but less accurate results. quadl(fun,a,b,tol,trace) with non-zero trace shows the values of [fcnt a b-a q] during the recursion. quadl(fun,a,b,tol,trace,p1,p2,...) provides for additional arguments p1,p2,... to be passed directly to function fun, fun(x,p1,p2,...). Pass empty matrices for tol or trace to use the default values. [q,fcnt] = quadl(...) returns the number of function evaluations.
Description
Use array operators .*, ./ and .^ in the definition of fun so that it can be evaluated with a vector argument. The function quad may be more efficient with low accuracies or nonsmooth integrands.
Examples
The function fun can be: An inline object
F = inline('1./(x.^3-2*x-5)'); Q = quadl(F,0,2);
2-175
quadl
A function handle
Q = quadl(@myfun,0,2);
where myfun.m is an M-file.
function y = myfun(x) y = 1./(x.^3-2*x-5);
Algorithm Diagnostics
quadl implements a high order method using an adaptive Gauss/Lobatto
qudrature rule.
quadl may issue one of the following warnings: 'Minimum step size reached' indicates that the recursive interval
subdivision has produced a subinterval whose length is on the order of roundoff error in the length of the original interval. A nonintegrable singularity is possible.
'Maximum function count exceeded' indicates that the integrand has been evaluated more than 10,000 times. A nonintegrable singularity is likely. 'Infinite or Not-a-Number function value encountered' indicates a
floating point overflow or division by zero during the evaluation of the integrand in the interior of the interval.
See Also References
dblquad, inline, quad, triplequad, @ (function handle)
[1] Gander, W. and W. Gautschi, "Adaptive Quadrature Revisited", BIT, Vol. 40, 2000, pp. 84-101. This document is also available at http://www.inf.ethz.ch/personal/gander.
2-176
questdlg
Purpose Syntax
2questdlg
Create and display question dialog box
button = questdlg('qstring') button = questdlg('qstring','title') button = questdlg('qstring','title','default') button = questdlg('qstring','title','str1','str2','default') button = questdlg('qstring','title','str1','str2','str3','default') button = questdlg('qstring') displays a modal dialog presenting the question 'qstring'. The dialog has three default buttons, Yes, No, and Cancel. If the user presses one of these three buttons, button is set to the name of the button pressed. If the user presses the close button on the dialog, button
Description
is set to the empty string. If the user presses the Return key, button is set to 'Yes'. 'qstring' is a cell array or a string that automatically wraps to fit within the dialog box.
button = questdlg('qstring','title') displays a question dialog with 'title' displayed in the dialog's title bar. button = questdlg('qstring','title','default') specifies which push button is the default in the event that the Return key is pressed. 'default' must be 'Yes', 'No', or 'Cancel'. button = questdlg('qstring','title','str1','str2','default') creates a question dialog box with two push buttons labeled 'str1' and 'str2'. 'default' specifies the default button selection and must be 'str1' or 'str2'. button = questdlg('qstring','title','str1','str2','str3','default') creates a question dialog box with three push buttons labeled 'str1', 'str2', and 'str3'. 'default' specifies the default button selection and must be 'str1', 'str2', or 'str3'.
In all cases where 'default' is specified, if'default' is not set to one of the button names, pressing the Return key displays a warning and the dialog remains open.
2-177
questdlg
Example
Create a question dialog asking the user whether to continue a hypothetical operation:
button = questdlg('Do you want to continue?',... 'Continue Operation','Yes','No','Help','No'); if strcmp(button,'Yes') disp('Creating file') elseif strcmp(button,'No') disp('Canceled file operation') elseif strcmp(button,'Help') disp('Sorry, no help available') end
See Also
dialog, errordlg, helpdlg, inputdlg, msgbox, warndlg
"Predefined Dialog Boxes" for related functions
2-178
quit
Purpose Graphical Interface Syntax
2quit
Terminate MATLAB As an alternative to the quit function, use the close box or select Exit
MATLAB from the File menu in the MATLAB desktop.
quit quit cancel quit force quit terminates MATLAB after running finish.m, if finish.m exists. The workspace is not automatically saved by quit. To save the workspace or perform other actions when quitting, create a finish.m file to perform those actions. If an error occurs while finish.m is running, quit is canceled so that you can correct your finish.m file without losing your workspace. quit cancel is for use in finish.m and cancels quitting. It has no effect
Description
anywhere else.
quit force bypasses finish.m and terminates MATLAB. Use this to override finish.m, for example, if an errant finish.m will not let you quit.
Remarks
When using Handle Graphics in finish.m, use uiwait, waitfor, or drawnow so that figures are visible. See the reference pages for these functions for more information.
2-179
quit
Examples
Two sample finish.m files are included with MATLAB. Use them to help you create your own finish.m, or rename one of the files to finish.m to use it. finishsav.m--Saves the workspace to a MAT-file when MATLAB quits. finishdlg.m--Displays a dialog allowing you to cancel quitting; it uses quit cancel and contains the following code:
button = questdlg('Ready to quit?', ... 'Exit Dialog','Yes','No','No'); switch button case 'Yes', disp('Exiting MATLAB'); %Save variables to matlab.mat save case 'No', quit cancel; end
See Also
finish, save, startup
2-180
quiver
Purpose Syntax
2quiver
Quiver or velocity plot
quiver(U,V,U,V) quiver(X,Y) quiver(...,scale) quiver(...,LineSpec) quiver(...,LineSpec,'filled') h = quiver(...)
Description
A quiver plot displays velocity vectors as arrows with components (U,V) at the points (X,Y). For example, the first vector is defined by componets U(1),V(1) and is displayed at the point X(1),Y(1).
quiver(X,Y,U,V) plots vectors as arrows at the coordinates specifide in each corresponding pair of elements in X and Y. The matirces X, Y, U, and V must all
be the same size and contain corresponding position and velocity components.
Expanding X and Y Coordinates
MATLAB expandes X and Y, if they are not matrices. This expansion is equivalent to calling meshgrid to generate matrices from vectors:
[X,Y] = meshgrid(X,Y) quiver(X,Y,U,V)
In this case, the following must be true:
length(X) = n and length(Y) = m, where [m,n] = size(U) = size(V)
The vector X corresponds to the columns of U and V, and vector Y corresponds to the rows of U and V.
quiver(U,V) draws vectors specified by U and V at equally spaced points in the
x-y plane.
quiver(...,scale) automatically scales the arrows to fit within the grid and then stretches them by the factor scale. scale = 2 doubles their relative length and scale = 0.5 halves the length. Use scale = 0 to plot the velocity
vectors without the automatic scaling.
2-181
quiver
quiver(...,LineSpec) specifies line style, marker symbol, and color using any valid LineSpec. quiver draws the markers at the origin of the vectors. quiver(...,LineSpec,'filled') fills markers specified by LineSpec. h = quiver(...) returns a vector of line handles.
Examples
Plot the gradient field of the function z = xe ( x
[X,Y] = meshgrid(2:.2:2); Z = X.exp(X.^2 Y.^2); [DX,DY] = gradient(Z,.2,.2); contour(X,Y,Z) hold on quiver(X,Y,DX,DY) colormap hsv grid off hold off
2
2
y2 )
.
1.5
1
0.5
0
-0.5
-1
-1.5
-2 -2
-1.5
-1
-0.5
0
0.5
1
1.5
2
See Also
contour, LineSpec, plot, quiver3
"Direction and Velocity Plots" for related functions
2-182
quiver
Two-Dimensional Quiver Plots for more examples
2-183
quiver3
Purpose Syntax
2quiver3
Three-dimensional velocity plot
quiver3(X,Y,Z,U,V,W) quiver3(Z,U,V,W) quiver3(...,scale) quiver3(...,LineSpec) quiver3(...,LineSpec,'filled') h = quiver3(...)
Description
A three-dimensional quiver plot displays vectors with components (u,v,w) at the points (x,y,z).
quiver3(X,Y,Z,U,V,W) plots vectors with components (u,v,w) at the points (x,y,z). The matrices X, Y, Z, U, V, W must all be the same size and contain the
corresponding position and vector components.
quiver3(Z,U,V,W) plots the vectors at the equally spaced surface points specified by matrix Z. quiver3 automatically scales the vectors based on the
distance between them to prevent them from overlapping.
quiver3(...,scale) automatically scales the vectors to prevent them from overlapping, then multiplies them by scale. scale = 2 doubles their relative length and scale = 0.5 halves them. Use scale = 0 to plot the vectors without
the automatic scaling.
quiver3(...,LineSpec) specify line type and color using any valid LineSpec. quiver3(...,LineSpec,'filled') fills markers specified by LineSpec. h = quiver3(...) returns a vector of line handles.
Examples
Plot the surface normals of the function
z = xe ( x
2
y2 ) .
[X,Y] = meshgrid(2:0.25:2,1:0.2:1); Z = X.* exp(X.^2 Y.^2); [U,V,W] = surfnorm(X,Y,Z); quiver3(X,Y,Z,U,V,W,0.5); hold on surf(X,Y,Z); colormap hsv
2-184
quiver3
view(-35,45) axis ([-2 2 -1 1 -.6 .6]) hold off
0.6 0.4 0.2 0 -0.2 -0.4 1 0.5 0 -0.5 -1 -1 -2 0 1 2
See Also
axis, contour, LineSpec, plot, plot3, quiver, surfnorm, view
"Direction and Velocity Plots" for related functions Three-Dimensional Quiver Plots for more examples
2-185
qz
Purpose Syntax
2qz
QZ factorization for generalized eigenvalues
[AA,BB,Q,Z,] = qz(A,B) [AA,BB,Q,Z,V,W] = qz(A,B) qz(A,B,flag)
Description
The qz function gives access to intermediate results in the computation of generalized eigenvalues.
[AA,BB,Q,Z] = qz(A,B) for square matrices A and B, produces upper quasitriangular matrices AA and BB, and unitary matrices Q and Z such that Q*A*Z = AA, and Q*B*Z = BB. For complex matrices, AA and BB are triangular. [AA,BB,Q,Z,V,W] = qz(A,B) also produces matrices V and W whose columns
are generalized eigenvectors.
qz(A,B,flag) for real matrices A and B, produces one of two decompositions depending on the value of flag: 'complex'
Produces a possibly complex decomposition with a triangular AA. For compatibility with earlier versions, 'complex' is the default. Produces a real decomposition with a quasitriangular AA, containing 1-by-1 and 2-by-2 blocks on its diagonal.
'real'
If AA is triangular, the diagonal elements of AA and BB, = diag (AA ) and = diag (BB ) , are the generalized eigenvalues that satisfy
A*V* = B*V*
*W ' *A = *W ' *B The eigenvalues produced by = eig (A, B ) are the ratios of the s and s. = ./ If AA is triangular, the diagonal elements of AA and BB,
2-186
qz
alpha = diag(AA) beta = diag(BB)
are the generalized eigenvalues that satisfy
A*V*diag(beta) = B*V*diag(alpha) diag(beta)*W'*A = diag(alpha)*W'*B
The eigenvalues produced by
lambda = eig(A,B)
are the element-wise ratios of alpha and beta.
lambda = alpha ./ beta
If AA is not triangular, it is necessary to further reduce the 2-by-2 blocks to obtain the eigenvalues of the full system.
Algorithm
For real QZ on real A and real B, eig uses the LAPACK DGGES routine. If you request the fifth output V, eig also uses DTGEVC. For complex QZ on real or complex A and B, eig uses the LAPACK ZGGES routine. If you request the fifth output V, eig also uses ZTGEVC.
See Also References
eig
[1] Anderson, E., Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra, J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen, LAPACK User's Guide (http://www.netlib.org/lapack/lug/lapack_lug.html), Third Edition, SIAM, Philadelphia, 1999.
2-187
rand
Purpose Syntax
2rand
Uniformly distributed random numbers and arrays
Y = rand(n) Y = rand(m,n) Y = rand([m n]) Y = rand(m,n,p,...) Y = rand([m n p...]) Y = rand(size(A)) rand s = rand('state')
Description
The rand function generates arrays of random numbers whose elements are uniformly distributed in the interval (0,1).
Y = rand(n) returns an n-by-n matrix of random entries. An error message appears if n is not a scalar. Y = rand(m,n) or Y = rand([m n]) returns an m-by-n matrix of random
entries.
Y = rand(m,n,p,...) or Y = rand([m n p...]) generates random arrays. Y = rand(size(A)) returns an array of random entries that is the same size as A. rand, by itself, returns a scalar whose value changes each time it's referenced. s = rand('state') returns a 35-element vector containing the current state
of the uniform generator. To change the state of the generator:
rand('state',s) rand('state',0) rand('state',j)
Resets the state to s. Resets the generator to its initial state. For integer j, resets the generator to its j-th state.
rand('state',sum(100*clock)) Resets it to a different state each time.
2-188
rand
Examples
Example 1. R = rand(3,4) may produce
R = 0.2190 0.0470 0.6789 0.6793 0.9347 0.3835 0.5194 0.8310 0.0346 0.0535 0.5297 0.6711
This code makes a random choice between two equally probable alternatives.
if rand < .5 'heads' else 'tails' end
Example 2. Generate a uniform distribution of random numbers on a specified
interval [a,b]. To do this, multiply the output of rand by (b-a) then add a. For example, to generate a 5-by-5 array of uniformly distributed random numbers on the interval [10,50]
a = 10; b = 50; x = a + (b-a) * rand(5) x = 18.1106 17.9489 34.1517 20.8875 17.9526 10.6110 39.8714 27.8039 47.2726 28.6398 26.7460 43.8489 31.0061 18.1059 36.8855 43.5247 10.7856 37.2511 25.1792 43.2718 30.1125 38.3789 27.1557 22.1847 17.5861
See Also
randn, randperm, sprand, sprandn
2-189
randn
Purpose Syntax
2randn
Normally distributed random numbers and arrays
Y = randn(n) Y = randn(m,n) Y = randn([m n]) Y = randn(m,n,p,...) Y = randn([m n p...]) Y = randn(size(A)) randn s = randn('state')
Description
The randn function generates arrays of random numbers whose elements are 2 normally distributed with mean 0, variance = 1 , and standard deviation = 1.
Y = randn(n) returns an n-by-n matrix of random entries. An error message appears if n is not a scalar. Y = randn(m,n) or Y = randn([m n]) returns an m-by-n matrix of random
entries.
Y = randn(m,n,p,...) or Y = randn([m n p...]) generates random arrays. Y = randn(size(A)) returns an array of random entries that is the same size as A. randn, by itself, returns a scalar whose value changes each time it's referenced. s = randn('state') returns a 2-element vector containing the current state
of the normal generator. To change the state of the generator:
randn('state',s) randn('state',0) randn('state',j) randn('state',sum(100*clock))
Resets the state to s. Resets the generator to its initial state. For integer j, resets the generator to its jth state. Resets it to a different state each time.
2-190
randn
Examples
Example 1. R = randn(3,4) may produce
R = 1.1650 0.6268 0.0751 0.3516 -0.6965 1.6961 0.0591 1.7971 0.2641 0.8717 -1.4462 -0.7012
For a histogram of the randn distribution, see hist.
Example 2. Generate a random distribution with a specific mean and variance
. To do this, multiply the output of randn by the standard deviation , and then add the desired mean. For example, to generate a 5-by-5 array of random numbers with a mean of .6 that are distributed with a variance of 0.1
x = .6 + sqrt(0.1) * randn(5) x = 0.8713 0.9966 0.0960 0.1443 0.7806 0.4735 0.8182 0.8579 0.8251 1.0080 0.8114 0.9766 0.2197 0.5937 0.5504 0.0927 0.6814 0.2659 1.0475 0.3454 0.7672 0.6694 0.3085 -0.0864 0.5813
2
See Also
rand, randperm, sprand, sprandn
2-191
randperm
Purpose Syntax Description Remarks Examples
2randperm
Random permutation
p = randperm(n) p = randperm(n) returns a random permutation of the integers 1:n.
The randperm function calls rand and therefore changes rand's state.
randperm(6) might be the vector [3 2 6 4 1 5]
or it might be some other permutation of 1:6.
See Also
permute
2-192
rank
Purpose Syntax Description
2rank
Rank of a matrix
k = rank(A) k = rank(A,tol)
The rank function provides an estimate of the number of linearly independent rows or columns of a full matrix.
k = rank(A) returns the number of singular values of A that are larger than the default tolerance, max(size(A))*norm(A)*eps. k = rank(A,tol) returns the number of singular values of A that are larger than tol.
Remark Algorithm
Use sprank to determine the structural rank of a sparse matrix. There are a number of ways to compute the rank of a matrix. MATLAB uses the method based on the singular value decomposition, or SVD. The SVD algorithm is the most time consuming, but also the most reliable. The rank algorithm is
s = svd(A); tol = max(size(A))*s(1)*eps; r = sum(s > tol);
See Also References
sprank
[1] Anderson, E., Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra, J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen, LAPACK User's Guide (http://www.netlib.org/lapack/lug/lapack_lug.html), Third Edition, SIAM, Philadelphia, 1999.
2-193
rat, rats
Purpose Syntax
2rat, rats
Rational fraction approximation
[N,D] = rat(X) [N,D] = rat(X,tol) rat(...) S = rats(X,strlen) S = rats(X)
Description
Even though all floating-point numbers are rational numbers, it is sometimes desirable to approximate them by simple rational numbers, which are fractions whose numerator and denominator are small integers. The rat function attempts to do this. Rational approximations are generated by truncating continued fraction expansions. The rats function calls rat, and returns strings.
[N,D] = rat(X) returns arrays N and D so that N./D approximates X to within the default tolerance, 1.e-6*norm(X(:),1). [N,D] = rat(X,tol) returns N./D approximating X to within tol. rat(X), with no output arguments, simply displays the continued fraction. S = rats(X,strlen) returns a string containing simple rational approximations to the elements of X. Asterisks are used for elements that
cannot be printed in the allotted space, but are not negligible compared to the other elements in X. strlen is the length of each string element returned by the rats function. The default is strlen = 13, which allows 6 elements in 78 spaces.
S = rats(X) returns the same results as those printed by MATLAB with format rat.
Examples
Ordinarily, the statement
s = 1 - 1/2 + 1/3 - 1/4 + 1/5 - 1/6 + 1/7
produces
s = 0.7595
2-194
rat, rats
However, with
format rat
or with
rats(s)
the printed result is
s = 319/420
This is a simple rational number. Its denominator is 420, the least common multiple of the denominators of the terms involved in the original expression. Even though the quantity s is stored internally as a binary floating-point number, the desired rational form can be reconstructed. To see how the rational approximation is generated, the statement rat(s) produces
1 + 1/(-4 + 1/(-6 + 1/(-3 + 1/(-5))))
And the statement
[n,d] = rat(s)
produces
n = 319, d = 420
The mathematical quantity is certainly not a rational number, but the MATLAB quantity pi that approximates it is a rational number. pi is the ratio of a large integer and 252:
14148475504056880/4503599627370496
However, this is not a simple rational number. The value printed for pi with format rat, or with rats(pi), is
355/113
This approximation was known in Euclid's time. Its decimal representation is
3.14159292035398
2-195
rat, rats
and so it agrees with pi to seven significant figures. The statement
rat(pi)
produces
3 + 1/(7 + 1/(16))
This shows how the 355/113 was obtained. The less accurate, but more familiar approximation 22/7 is obtained from the first two terms of this continued fraction.
Algorithm
The rat(X) function approximates each element of X by a continued fraction of the form n 1 -- = d 1 + -------------------------------------------------d 1 d 2 + -----------------------------------1 d + ... + ----- 3 d
k
The d s are obtained by repeatedly picking off the integer part and then taking the reciprocal of the fractional part. The accuracy of the approximation increases exponentially with the number of terms and is worst when X = sqrt(2). For x = sqrt(2), the error with k terms is about 2.68*(.173)^k, so each additional term increases the accuracy by less than one decimal digit. It takes 21 terms to get full floating-point accuracy.
See Also
format
2-196
rbbox
Purpose Syntax
2rbbox
Create rubberband box for area selection
rbbox rbbox(initialRect) rbbox(initialRect,fixedPoint) rbbox(initialRect,fixedPoint,stepSize) finalRect = rbbox(...) rbbox initializes and tracks a rubberband box in the current figure. It sets the
Description
initial rectangular size of the box to 0, anchors the box at the figure's CurrentPoint, and begins tracking from this point.
rbbox(initialRect) specifies the initial location and size of the rubberband box as [x y width height], where x and y define the lower-left corner, and width and height define the size. initialRect is in the units specified by the current figure's Units property, and measured from the lower-left corner of the
figure window. The corner of the box closest to the pointer position follows the pointer until rbbox receives a button-up event.
rbbox(initialRect,fixedPoint) specifies the corner of the box that remains fixed. All arguments are in the units specified by the current figure's Units
property, and measured from the lower-left corner of the figure window. fixedPoint is a two-element vector, [x y]. The tracking point is the corner diametrically opposite the anchored corner defined by fixedPoint.
rbbox(initialRect,fixedPoint,stepSize) specifies how frequently the rubberband box is updated. When the tracking point exceeds stepSize figure units, rbbox redraws the rubberband box. The default stepsize is 1. finalRect = rbbox(...) returns a four-element vector, [x y width height], where x and y are the x and y components of the lower-left corner of the box, and width and height are the dimensions of the box.
Remarks
rbbox is useful for defining and resizing a rectangular region:
For box definition, initialRect is [x y 0 0], where (x,y) is the figure's CurrentPoint.
2-197
rbbox
For box resizing, initialRect defines the rectangular region that you resize (e.g., a legend). fixedPoint is the corner diametrically opposite the tracking point.
rbbox returns immediately if a button is not currently pressed. Therefore, you use rbbox with waitforbuttonpress so that the mouse button is down when rbbox is called. rbbox returns when you release the mouse button.
Examples
Assuming the current view is view(2), use the current axes' CurrentPoint property to determine the extent of the rectangle in dataspace units:
k = waitforbuttonpress; point1 = get(gca,'CurrentPoint'); finalRect = rbbox; point2 = get(gca,'CurrentPoint'); point1 = point1(1,1:2); point2 = point2(1,1:2); p1 = min(point1,point2); offset = abs(point1-point2); % button down detected % return figure units % button up detected % extract x and y
% calculate locations % and dimensions
x = [p1(1) p1(1)+offset(1) p1(1)+offset(1) p1(1) p1(1)]; y = [p1(2) p1(2) p1(2)+offset(2) p1(2)+offset(2) p1(2)]; hold on axis manual plot(x,y)
% redraw in dataspace units
See Also
axis, dragrect, waitforbuttonpress
"View Control" for related functions
2-198
rcond
Purpose Syntax Description
2rcond
Matrix reciprocal condition number estimate
c = rcond(A) c = rcond(A) returns an estimate for the reciprocal of the condition of A in 1-norm using the LAPACK condition estimator. If A is well conditioned, rcond(A) is near 1.0. If A is badly conditioned, rcond(A) is near 0.0. Compared to cond, rcond is a more efficient, but less reliable, method of estimating the
condition of a matrix.
Algorithm
rcond uses LAPACK routines to compute the estimate of the reciprocal
condition number:
Matrix
Routine DLANGE, DGETRF, DGECON ZLANGE, ZGETRF, ZGECON
Real Complex
See Also References
cond, condest, norm, normest, rank, svd
[1] Anderson, E., Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra, J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen, LAPACK User's Guide (http://www.netlib.org/lapack/lug/lapack_lug.html), Third Edition, SIAM, Philadelphia, 1999.
2-199
readasync
Purpose Syntax Arguments
2readasync
Read data asynchronously from the device
readasync(obj) readasync(obj,size) obj size
A serial port object. The number of bytes to read from the device.
Description
readasync(obj) initiates an asynchronous read operation. readasync(obj,size) asynchronously reads, at most, the number of bytes given by size. If size is greater than the difference between the InputBufferSize property value and the BytesAvailable property value, an
error is returned.
Remarks
Before you can read data, you must connect obj to the device with the fopen function. A connected serial port object has a Status property value of open. An error is returned if you attempt to perform a read operation while obj is not connected to the device. You should use readasync only when you configure the ReadAsyncMode property to manual. readasync is ignored if used when ReadAsyncMode is continuous. The TransferStatus property indicates if an asynchronous read or write operation is in progress. You can write data while an asynchronous read is in progress because serial ports have separate read and write pins. You can stop asynchronous read and write operations with the stopasync function. You can monitor the amount of data stored in the input buffer with the BytesAvailable property. Additionally, you can use the BytesAvailableFcn property to execute an M-file callback function when the terminator or the specified amount of data is read.
Rules for Completing an Asynchronous Read Operation
An asynchronous read operation with readasync completes when one of these conditions is met: The terminator specified by the Terminator property is read.
2-200
readasync
The time specified by the Timeout property passes. The specified number of bytes is read. The input buffer is filled (if size is not specified). Because readasync checks for the terminator, this function can be slow. To increase speed, you might want to configure ReadAsyncMode to continuous and continuously return data to the input buffer as soon as it is available from the device.
Example
This example creates the serial port object s, connects s to a Tektronix TDS 210 oscilloscope, configures s to read data asynchronously only if readasync is issued, and configures the instrument to return the peak-to-peak value of the signal on channel 1.
s = serial('COM1'); fopen(s) s.ReadAsyncMode = 'manual'; fprintf(s,'Measurement:Meas1:Source CH1') fprintf(s,'Measurement:Meas1:Type Pk2Pk') fprintf(s,'Measurement:Meas1:Value?')
Begin reading data asynchronously from the instrument using readasync. When the read operation is complete, return the data to the MATLAB workspace using fscanf.
readasync(s) s.BytesAvailable ans = 15 out = fscanf(s) out = 2.0399999619E0 fclose(s)
See Also
Functions
fopen, stopasync
Properties
BytesAvailable, BytesAvailableFcn, ReadAsyncMode, Status, TransferStatus
2-201
real
Purpose Syntax Description Examples See Also
2real
Real part of complex number
X = real(Z) X = real(Z) returns the real part of the elements of the complex array Z. real(2+3*i) is 2. abs, angle, conj, i, j, imag
2-202
reallog
Purpose Syntax Description
2reallog
Natural logarithm for nonnegative real arrays
Y = reallog(X) Y = reallog(X) returns the natural logarithm of each element in array X. Array X must contain only nonnegative real numbers. The size of Y is the same as the size of X. M = magic(4) M = 16 5 9 4 reallog(M) ans = 2.7726 1.6094 2.1972 1.3863 2 11 7 14 3 10 6 15 13 8 12 1
Examples
0.6931 2.3979 1.9459 2.6391
1.0986 2.3026 1.7918 2.7081
2.5649 2.0794 2.4849 0
See Also
log, realpow, realsqrt
2-203
realmax
Purpose Syntax Description Examples Algorithm
2realmax
Largest positive floating-point number
n = realmax n = realmax returns the largest floating-point number representable on a
particular computer. Anything larger overflows.
realmax is one bit less than 21024 or about 1.7977e+308.
The realmax function is equivalent to pow2(2-eps,maxexp), where maxexp is the largest possible floating-point exponent. Execute type realmax to see maxexp for various computers.
See Also
eps, realmin
2-204
realmin
Purpose Syntax Description
2realmin
Smallest positive floating-point number
n = realmin n = realmin returns the smallest positive normalized floating-point number
on a particular computer. Anything smaller underflows or is an IEEE "denormal."
Examples Algorithm
realmin is 2^(-1022) or about 2.2251e-308.
The realmin function is equivalent to pow2(1,minexp) where minexp is the smallest possible floating-point exponent. Execute type realmin to see minexp for various computers.
See Also
eps, realmax
2-205
realpow
Purpose Syntax Description
2realpow
Array power for real-only output
Z = realpow(X,Y) Z = realpow(X,Y) raises each element of array X to the power of its corresponding element in array Y. Arrays X and Y must be the same size. The range of realpow is the set of all real numbers, i.e., all elements of the output array Z must be real. X = -2*ones(3,3) X = -2 -2 -2 -2 -2 -2 -2 -2 -2
Examples
Y = pascal(3) ans = 1 1 1 1 2 3 1 3 6
realpow(X,Y) ans = -2 -2 -2
-2 4 -8
-2 -8 64
See Also
reallog, realsqrt, .^ (array power operator)
2-206
realsqrt
Purpose Syntax Description
2realsqrt
Square root for nonnegative real arrays
Y = realsqrt(X) Y = realsqrt(X) returns the square root of each element of array X. Array X must contain only nonnegative real numbers. The size of Y is the same as the size of X. M = magic(4) M = 16 5 9 4 2 11 7 14 3 10 6 15 13 8 12 1
Examples
realsqrt(M) ans = 4.0000 2.2361 3.0000 2.0000
1.4142 3.3166 2.6458 3.7417
1.7321 3.1623 2.4495 3.8730
3.6056 2.8284 3.4641 1.0000
See Also
reallog, realpow, sqrt, sqrtm
2-207
record
Purpose Syntax Arguments
2record
Record data and event information to a file
record(obj) record(obj,'switch') obj 'switch'
A serial port object. Switch recording capabilities on or off.
Description
record(obj) toggles the recording state for obj. record(obj,'switch') initiates or terminates recording for obj. switch can be on or off. If switch is on, recording is initiated. If switch is off, recording
is terminated.
Remarks
Before you can record information to disk, obj must be connected to the device with the fopen function. A connected serial port object has a Status property value of open. An error is returned if you attempt to record information while obj is not connected to the device. Each serial port object must record information to a separate file. Recording is automatically terminated when obj is disconnected from the device with fclose. The RecordName and RecordMode properties are read-only while obj is recording, and must be configured before using record. For a detailed description of the record file format and the properties associated with recording data and event information to a file, refer to "Debugging: Recording Information to Disk."
Example
This example creates the serial port object s, connects s to the device, configures s to record information to a file, writes and reads text data, and then disconnects s from the device.
s = serial('COM1'); fopen(s) s.RecordDetail = 'verbose'; s.RecordName = 'MySerialFile.txt'; record(s,'on') fprintf(s,'*IDN?') out = fscanf(s);
2-208
record
record(s,'off') fclose(s)
See Also
Functions
fclose, fopen
Properties
RecordDetail, RecordMode, RecordName, RecordStatus, Status
2-209
rectangle
Purpose Syntax
2rectangle
Create a 2-D rectangle object
rectangle rectangle('Position',[x,y,w,h]) rectangle(...,'Curvature',[x,y]) h = rectangle(...) rectangle draws a rectangle with Position [0,0,1,1] and Curvature [0,0]
Description
(i.e., no curvature).
rectangle('Position',[x,y,w,h]) draws the rectangle from the point x,y and having a width of w and a height of h. Specify values in axes data units.
Note that, to display a rectangle in the specified proportions, you need to set the axes data aspect ratio so that one unit is of equal length along both the x and y axes. You can do this with the command axis equal or daspect([1,1,1]).
rectangle(...,'Curvature',[x,y]) specifies the curvature of the rectangle sides, enabling it to vary from a rectangle to an ellipse. The horizontal curvature x is the fraction of width of the rectangle that is curved along the top and bottom edges. The vertical curvature y is the fraction of the height of the rectangle that is curved along the left and right edges.
The values of x and y can range from 0 (no curvature) to 1 (maximum curvature). A value of [0,0] creates a rectangle with square sides. A value of [1,1] creates an ellipse. If you specify only one value for Curvature, then the same length (in axes data units) is curved along both horizontal and vertical sides. The amount of curvature is determined by the shorter dimension.
h = rectangle(...) returns the handle of the rectangle object created.
Remarks
Rectangle objects are 2-D and can be drawn in an axes only if the view is [0 90] (i.e., view(2)). Rectangles are children of axes and are defined in coordinates of the axes data. This example sets the data aspect ratio to [1,1,1] so that the rectangle displays in the specified proportions (daspect). Note that the horizontal and vertical curvature can be different. Also, note the effects of using a single value for Curvature.
Examples
2-210
rectangle
rectangle('Position',[0.59,0.35,3.75,1.37],... 'Curvature',[0.8,0.4],... 'LineWidth',2,'LineStyle','--') daspect([1,1,1])
2 1.8 1.6 1.4 1.2 1 0.8 0.6 0.4 0.2 0 0.5 1 1.5 2 2.5 3 3.5 4 4.5
Specifying a single value of [0.4] for Curvature produces:
2 1.8 1.6 1.4 1.2 1 0.8 0.6 0.4 0.2 0 0.5 1 1.5 2 2.5 3 3.5 4 4.5
A Curvature of [1] produces a rectangle with the shortest side completely round:
2-211
rectangle
2 1.8 1.6 1.4 1.2 1 0.8 0.6 0.4 0.2 0 0.5 1 1.5 2 2.5 3 3.5 4 4.5
This example creates an ellipse and colors the face red.
rectangle('Position',[1,2,5,10],'Curvature',[1,1],... 'FaceColor','r') daspect([1,1,1]) xlim([0,7]) ylim([1,13])
2-212
rectangle
12
10
8
6
4
2
0
1
2
3
4
5
6
7
See Also Object Hierarchy
line, patch, rectangle properties
"Object Creation Functions" for related functions
Root
Figure
Axes
Uicontrol
Uimenu
Uicontextmenu
Image
Light
Line
Patch
Rectangle
Surface
Text
2-213
rectangle
Setting Default Properties
You can set default rectangle properties on the axes, figure, and root levels.
set(0,'DefaultRectangleProperty',PropertyValue...) set(gcf,'DefaultRectangleProperty',PropertyValue...) set(gca,'DefaultRectangleProperty',PropertyValue...)
Where Property is the name of the rectangle property whose default value you want to set and PropertyValue is the value you are specifying. Use set and get to access the surface properties.
Property List
The following table lists all rectangle properties and provides a brief description of each. The property name links take you to an expanded description of the properties.
Property Description Property Value
Property Name Defining the Rectangle Object Curvature
Degree of horizontal and vertical curvature Method of drawing and erasing the rectangle (useful for animation) Color of rectangle edges Color of rectangle interior Line style of edges Width of edge lines in points Location and width and height of rectangle
Value: two-element vector with values between 0 and 1 Default: [0,0] Values: normal, none, xor,
background Default: normal
EraseMode
EdgeColor
Value: ColorSpec or none Default: ColorSpec [0,0,0] Value: ColorSpec or none Default: none Values: -, --, :, -., none Default: - Value: scalar Default: 0.5 points Value: [x,y,width,height] Default: [0,0,1,1]
FaceColor
LineStyle
LineWidth
Position
2-214
rectangle
Property Name
Property Description
Property Value
General Information About Rectangle Objects Children Parent Selected
Rectangle objects have no children Axes object Indicate if the rectangle is in a "selected" state. User-specified label The type of graphics object (read only) User-specified data Value: handle of axes Value: on, off Default: off Value: any string Default: '' (empty string) Value: the string
'rectangle'
Tag
Type
UserData
Value: any matrix Default: [] (empty matrix)
Properties Related to Callback Routine Execution BusyAction
Specify how to handle callback routine interruption Define a callback routine that executes when a mouse button is pressed on over the rectangle Define a callback routine that executes when a rectangle is created Define a callback routine that executes when the rectangle is deleted (via close or delete) Determine if callback routine can be interrupted Associate a context menu with the rectangle
Value: cancel, queue Default: queue Value: string or function handle Default: '' (empty string) Value: string or function handle Default: '' (empty string) Values: string or function handle Default: '' (empty string) Values: on, off Default: on (can be interrupted) Values: handle of a Uicontextmenu
ButtonDownFcn
CreateFcn
DeleteFcn
Interruptible
UIContextMenu
2-215
rectangle
Property Name Controlling Access to Objects HandleVisibility
Property Description
Property Value
Determines if and when the rectangle's handle is visible to other functions Determines if the rectangle can become the current object (see the Figure CurrentObject property)
Values: on, callback, off Default: on Values: on, off Default: on
HitTest
Controlling the Appearance Clipping
Clipping to axes rectangle Highlight rectangle when selected (Selected property set to on) Make the rectangle visible or invisible
Values: on, off Default: on Values: on, off Default: on Values: on, off Default: on
SelectionHighlight
Visible
2-216
rectangle properties
Modifying Properties
2rectangle properties
You can set and query graphics object properties in two ways: The Property Editor is an interactive tool that enables you to see and change object property values. The set and get commands enable you to set and query the values of properties To change the default value of properties see Setting Default Property Values.
Rectangle Property Descriptions
This section lists property names along with the type of values each accepts. Curly braces { } enclose default values.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control how MATLAB handles events that potentially interrupt executing callback routines. If there is a callback routine executing, subsequently invoked callback routes always attempt to interrupt it. If the Interruptible property of the object whose callback is executing is set to on (the default), then interruption occurs at the next point where the event queue is processed. If the Interruptible property is off, the BusyAction property (of the object owning the executing callback) determines how MATLAB handles the event. The choices are: cancel discard the event that attempted to execute a second callback routine. queue queue the event that attempted to execute a second callback routine until the current callback finishes.
ButtonDownFcn
string or function handle
Button press callback routine. A callback routine that executes whenever you press a mouse button while the pointer is over the rectangle object. Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace. See Function Handle Callbacks for information on how to use function handles to define the callback function.
Children
vector of handles
The empty matrix; rectangle objects have no children.
2-217
rectangle properties
Clipping
{on} | off
Clipping mode. MATLAB clips rectangles to the axes plot box by default. If you set Clipping to off, rectangles display outside the axes plot box. This can occur if you create a rectangle, set hold to on, freeze axis scaling (axis manual), and then create a larger rectangle.
CreateFcn
string or function handle
Callback routine executed during object creation. This property defines a callback routine that executes when MATLAB creates a rectangle object. You must define this property as a default value for rectangles. For example, the statement,
set(0,'DefaultRectangleCreateFcn',...
'set(gca,''DataAspectRatio'',[1,1,1])')
defines a default value on the root level that sets the axes DataAspectRatio whenever you create a rectangle object. MATLAB executes this routine after setting all rectangle properties. Setting this property on an existing rectangle object has no effect. The handle of the object whose CreateFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo. See Function Handle Callbacks for information on how to use function handles to define the callback function.
Curvature
one- or two-element vector [x,y]
Amount of horizontal and vertical curvature. This property specifies the curvature of the rectangle sides, which enables the shape of the rectangle to vary from rectangular to ellipsoidal. The horizontal curvature x is the fraction of width of the rectangle that is curved along the top and bottom edges. The vertical curvature y is the fraction of the height of the rectangle that is curved along the left and right edges. The values of x and y can range from 0 (no curvature) to 1 (maximum curvature). A value of [0,0] creates a rectangle with square sides. A value of [1,1] creates an ellipse. If you specify only one value for Curvature, then the same length (in axes data units) is curved along both horizontal and vertical sides. The amount of curvature is determined by the shorter dimension.
2-218
rectangle properties
DeleteFcn
string or function handle
Delete rectangle callback routine. A callback routine that executes when you delete the rectangle object (e.g., when you issue a delete command or clear the axes or figure). MATLAB executes the routine before deleting the object's properties so these values are available to the callback routine. The handle of the object whose DeleteFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo. See Function Handle Callbacks for information on how to use function handles to define the callback function.
EdgeColor {ColorSpec} | none
Color of the rectangle edges. This property specifies the color of the rectangle edges as a color or specifies that no edges be drawn.
EraseMode {normal} | none | xor | background
Erase mode. This property controls the technique MATLAB uses to draw and erase rectangle objects. Alternative erase modes are useful for creating animated sequences, where control of the way individual objects redraw is necessary to improve performance and obtain the desired effect. normal (the default) Redraw the affected region of the display, performing the three-dimensional analysis necessary to ensure that all objects are rendered correctly. This mode produces the most accurate picture, but is the slowest. The other modes are faster, but do not perform a complete redraw and are therefore less accurate. none Do not erase the rectangle when it is moved or destroyed. While the object is still visible on the screen after erasing with EraseMode none, you cannot print it because MATLAB stores no information about its former location. xor Draw and erase the rectangle by performing an exclusive OR (XOR) with the color of the screen beneath it. This mode does not damage the color of the objects beneath the rectangle. However, the rectangle's color depends on the color of whatever is beneath it on the display. background Erase the rectangle by drawing it in the Axes' background Color, or the Figure background Color if the Axes Color is set to none. This damages objects that are behind the erased rectangle, but rectangles are always properly colored.
2-219
rectangle properties
Printing with Non-normal Erase Modes.
MATLAB always prints Figures as if the EraseMode of all objects is normal. This means graphics objects created with EraseMode set to none, xor, or background can look different on screen than on paper. On screen, MATLAB may mathematically combine layers of colors (e.g., XORing a pixel color with that of the pixel behind it) and ignore three-dimensional sorting to obtain greater rendering speed. However, these techniques are not applied to the printed output. You can use the MATLAB getframe command or other screen capture application to create an image of a Figure containing non-normal mode objects.
FaceColor ColorSpec | {none}
Color of rectangle face. This property specifies the color of the rectangle face, which is not colored by default.
HandleVisibility {on} | callback | off
Control access to object's handle by command-line users and GUIs. This property determines when an object's handle is visible in its parent's list of children. HandleVisibility is useful for preventing command-line users from accidentally drawing into or deleting a figure that contains only user interface devices (such as a dialog box). Handles are always visible when HandleVisibility is on. Setting HandleVisibility to callback causes handles to be visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provides a means to protect GUIs from command-line users, while allowing callback routines to have complete access to object handles. Setting HandleVisibility to off makes handles invisible at all times. This may be necessary when a callback routine invokes a function that might potentially damage the GUI (such as evaling a user-typed string), and so temporarily hides its own handles during the execution of that function. When a handle is not visible in its parent's list of children, it cannot be returned by functions that obtain handles by searching the object hierarchy or querying handle properties. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close.
2-220
rectangle properties
When a handle's visibility is restricted using callback or off, the object's handle does not appear in its parent's Children property, figures do not appear in the root's CurrentFigure property, objects do not appear in the root's CallbackObject property or in the figure's CurrentObject property, and Axes do not appear in their parent's CurrentAxes property. You can set the Root ShowHiddenHandles property to on to make all handles visible, regardless of their HandleVisibility settings (this does not affect the values of the HandleVisibility properties). Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.
HitTest {on} | off
Selectable by mouse click. HitTest determines if the rectangle can become the current object (as returned by the gco command and the figure CurrentObject property) as a result of a mouse click on the rectangle. If HitTest is off, clicking on the rectangle selects the object below it (which may be the axes containing it).
Interruptible {on} | off
Callback routine interruption mode. The Interruptible property controls whether a rectangle callback routine can be interrupted by subsequently invoked callback routines. Only callback routines defined for the ButtonDownFcn are affected by the Interruptible property. MATLAB checks for events that can interrupt a callback routine only when it encounters a drawnow, figure, getframe, or pause command in the routine.
LineStyle {-} | -- | : | -. | none
Line style of rectangle edge. This property specifies the line style of the edges. The available line styles are:
Symbol Line Style
- --
:
solid line (default) dashed line dotted line dash-dot line
-.
2-221
rectangle properties
Symbol none LineWidth
Line Style
no line scalar
The width of the rectangle edge line. Specify this value in points (1 point = 1/72 inch). The default LineWidth is 0.5 points.
Parent
handle
rectangle's parent. The handle of the rectangle object's parent axes. You can move a rectangle object to another axes by changing this property to the new axes handle.
Position
four-element vector [x,y,width,height]
Location and size of rectangle. This property specifies the location and size of the rectangle in the data units of the axes. The point defined by x, y specifies one corner of the rectangle, and width and height define the size in units along the x and y axes respecitvely.
Selected on | off
Is object selected? When this property is on MATLAB displays selection handles if the SelectionHighlight property is also on. You can, for example, define the ButtonDownFcn to set this property, allowing users to select the object with the mouse.
SelectionHighlight {on} | off
Objects highlight when selected. When the Selected property is on, MATLAB indicates the selected state by drawing handles at each vertex. When SelectionHighlight is off, MATLAB does not draw the handles.
Tag
string
User-specified object label. The Tag property provides a means to identify graphics objects with a user-specified label. This is particularly useful when constructing interactive graphics programs that would otherwise need to define object handles as global variables or pass them as arguments between callback routines. You can define Tag as any string.
2-222
rectangle properties
Type
string (read only)
Class of graphics object. For rectangle objects, Type is always the string 'rectangle'.
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the rectangle. Assign this property the handle of a uicontextmenu object created in the same figure as the rectangle. Use the uicontextmenu function to create the context menu. MATLAB displays the context menu whenever you right-click over the rectangle.
UserData
matrix
User-specified data. Any data you want to associate with the rectangle object. MATLAB does not use this data, but you can access it using the set and get commands.
Visible {on} | off
rectangle visibility. By default, all rectangles are visible. When set to off, the rectangle is not visible, but still exists and you can get and set its properties.
2-223
rectint
Purpose Syntax Description
2rectint
Rectangle intersection area.
area = rectint(A,B) area = rectint(A,B) returns the area of intersection of the rectangles specified by position vectors A and B.
If A and B each specify one rectangle, the output area is a scalar.
A and B can also be matrices, where each row is a position vector. area is then a matrix giving the intersection of all rectangles specified by A with all the rectangles specified by B. That is, if A is n-by-4 and B is m-by-4, then area is an n-by-m matrix where area(i,j) is the intersection area of the rectangles specified by the ith row of A and the jth row of B.
Note A position vector is a four-element vector [x,y,width,height], where the point defined by x and y specifies one corner of the rectangle, and width and height define the size in units along the x and y axes respectively.
See Also
polyarea
2-224
reducepatch
Purpose Syntax
2reducepatch
Reduce the number of patch faces
reducepatch(p,r) nfv = reducepatch(p,r) nfv = reducepatch(fv,r) reducepatch(...,'fast') reducepatch(...,'verbose') nfv = reducepatch(f,v,r) [nf,nv] = reducepatch(...) reducepatch(p,r) reduces the number of faces of the patch identified by handle p, while attempting to preserve the overall shape of the original object. MATLAB interprets the reduction factor r in one of two ways depending on its
Description
value: If r is less than 1, r is interpreted as a fraction of the original number of faces. For example, if you specify r as 0.2, then the number of faces is reduced to 20% of the number in the original patch. If r is greater than or equal to 1, then r is the target number of faces. For example, if you specify r as 400, then the number of faces is reduced until there are 400 faces remaining.
nfv = reducepatch(p,r) returns the reduced set of faces and vertices but does not set the Faces and Vertices properties of patch p. The struct nfv contains the faces and vertices after reduction. nfv = reducepatch(fv,r) performs the reduction on the faces and vertices in the struct fv. nfv = reducepatch(p) or nfv = reducepatch(fv) uses a reduction value of 0.5. reducepatch(...,'fast') assumes the vertices are unique and does not
compute shared vertices.
reducepatch(...,'verbose') prints progress messages to the command
window as the computation progresses.
nfv = reducepatch(f,v,r) performs the reduction on the faces in f and the vertices in v.
2-225
reducepatch
[nf,nv] = reducepatch(...) returns the faces and vertices in the arrays nf and nv.
Remarks
If the patch contains nonshared vertices, MATLAB computes shared vertices before reducing the number of faces. If the faces of the patch are not triangles, MATLAB triangulates the faces before reduction. The faces returned are always defined as triangles. The number of output triangles may not be exactly the number specified with the reduction factor argument (r), particularly if the faces of the original patch are not triangles.
Examples
This example illustrates the effect of reducing the number of faces to only 15% of the original value.
[x,y,z,v] = flow; p = patch(isosurface(x,y,z,v,-3)); set(p,'facecolor','w','EdgeColor','b'); daspect([1,1,1]) view(3) figure; h = axes; p2 = copyobj(p,h); reducepatch(p2,0.15) daspect([1,1,1]) view(3)
2-226
reducepatch
Before Reduction
3 2 1 0 -1 -2 -3 4 2 0 -2 -4 0 4 2 6 8
10
2-227
reducepatch
After Reduction to 15% of Original Number of Faces
3 2 1 0 -1 -2 -3 4 2 0 4 -2 -4 0 2 6 8
10
See Also
isosurface, isocaps, isonormals, smooth3, subvolume, reducevolume
"Volume Visualization" for related functions Vector Field Displayed with Cone Plots for another example
2-228
reducevolume
Purpose Syntax
2reducevolume
Reduce the number of elements in a volume data set
[nx,ny,nz,nv] = reducevolume(X,Y,Z,V,[Rx,Ry,Rz]) [nx,ny,nz,nv] = reducevolume(V,[Rx,Ry,Rz]) nv = reducevolume(...) [nx,ny,nz,nv] = reducevolume(X,Y,Z,V,[Rx,Ry,Rz]) reduces the number of elements in the volume by retaining every Rxth element in the x direction, every Ryth element in the y direction, and every Rzth element in the z direction. If a scalar R is used to indicate the amount or reduction instead of a 3-element vector, MATLAB assumes the reduction to be [R R R].
Description
The arrays X, Y, and Z define the coordinates for the volume V. The reduced volume is returned in nv and the coordinates of the reduced volume are returned in nx, ny, and nz.
[nx,ny,nz,nv] = reducevolume(V,[Rx,Ry,Rz]) assumes the arrays X, Y, and Z are defined as [X,Y,Z] = meshgrid(1:n,1:m,1:p) where [m,n,p] = size(V). nv = reducevolume(...) returns only the reduced volume.
Examples
This example uses a data set that is a collection of MRI slices of a human skull. This data is processed in a variety of ways: The 4-D array is squeezed (squeeze) into three dimensions and then reduced (reducevolume) so that what remains is every 4th element in the x and y directions and every element in the z direction. The reduced data is smoothed (smooth3). The outline of the skull is an isosurface generated as a patch (p1) whose vertex normals are recalculated to improve the appearance when lighting is applied (patch, isosurface, isonormals). A second patch (p2) with an interpolated face color draws the end caps (FaceColor, isocaps). The view of the object is set (view, axis, daspect). A 100-element grayscale colormap provides coloring for the end caps (colormap).
2-229
reducevolume
Adding a light to the right of the camera illuminates the object (camlight, lighting).
load mri D = squeeze(D); [x,y,z,D] = reducevolume(D,[4,4,1]); D = smooth3(D); p1 = patch(isosurface(x,y,z,D, 5,'verbose'),... 'FaceColor','red','EdgeColor','none'); isonormals(x,y,z,D,p1); p2 = patch(isocaps(x,y,z,D, 5),... 'FaceColor','interp','EdgeColor','none'); view(3); axis tight; daspect([1,1,.4]) colormap(gray(100)) camlight; lighting gouraud
See Also
isosurface, isocaps, isonormals, smooth3, subvolume, reducepatch
"Volume Visualization" for related functions
2-230
refresh
Purpose Syntax Description
2refresh
Redraw current figure
refresh refresh(h) refresh erases and redraws the current figure. refresh(h) redraws the figure identified by h.
See Also
"Figure Windows" for related functions
2-231
regexp
Purpose Syntax
2regexp
Match regular expression
start = regexp(str,expr) [start,finish] = regexp(str,expr) [start,finish,tokens] = regexp(str,expr) [...] = regexp(str,expr,'once') start = regexp(str,expr) returns a row vector, start, containing the indices of the substrings in str that match the regular expression string, expr.
Description
When either str or expr is a cell array of strings, regexp returns an m-by-n cell array of row vectors of indices, where m is the the number of strings in str and n is the number of regular expression patterns in expr.
[start,finish] = regexp(str,expr) returns an additional row vector finish, that contains the indices of the last character of the corresponding substrings in start. [start,finish,tokens] = regexp(str,expr) returns a 1-by-n cell array, tokens, of beginining and ending indices of tokens within the corresponding substrings in start and finish. Tokens are denoted by parentheses in the expression, expr. [...] = regexp(str,expr,'once') finds just the first match. (By default, regexp returns all matches.) If no matches are found, then all return values are
empty.
Remarks
See "Regular Expressions", in the MATLAB documentation, for a listing of all regular expression metacharacters supported by MATLAB.
regexp does not support international character sets.
Examples
Example 1
Return a row vector of indices that match words that start with c, end with t, and contain one or more vowels between them:
str = 'bat cat can car coat court cut ct caoueouat'; regexp(str, 'c[aeiou]+t') ans = 5 17 28 35
2-232
regexp
Example 2
Return a cell array of row vectors of indices that match capital letters and whitespaces in the cell array of strings, str:
str = {'Madrid, Spain' 'Romeo and Juliet' 'MATLAB is great'}; s = regexp(str, {'[A-Z]' '\s'});
Capital letters, '[A-Z]', were found at these str indices:
s{:,1} ans = 1 ans = 1 ans = 1
9 11 2 3 4 5 6
Space characters, '\s', were found at these str indices:
s{:,2} ans = 8 ans = 6 ans = 7
10 10
Example 3
Return the starting and ending indices of words containing the letter x:
str = 'regexp helps you relax'; [s,f] = regexp(str, '\w*x\w*') s = 1 18 f = 6 22
2-233
regexp
Example 4
Return the starting and ending indices of substrings contained by the letter s. Also return the starting and ending indices of the token defined within the parentheses:
str = 'six sides of a hexagon'; [s,f,t] = regexp(str, 's(\w*)s') s = 5 f = 9 t = [1x2 double] t{:} ans = 6 8
See Also
regexpi, regexprep, strfind, findstr, strmatch, strcmp, strcmpi, strncmp, strncmpi
2-234
regexpi
Purpose Syntax
2regexpi
Match regular expression, ignoring case
start = regexpi(str,expr) [start,finish] = regexpi(str,expr) [start,finish,tokens] = regexpi(str,expr) [...] = regexpi(str,expr,'once') start = regexpi(str,expr) returns a row vector, start, containing the indices of the substrings in str that match the regular expression string, expr,
Description
regardless of case. When either str or expr is a cell array of strings, regexpi returns an m-by-n cell array of row vectors of indices, where m is the the number of strings in str and n is the number of regular expression patterns in expr.
[start,finish] = regexpi(str,expr) returns an additional row vector finish, that contains the indices of the last character of the corresponding substrings in start. [start,finish,tokens] = regexpi(str,expr) returns a 1-by-n cell array, tokens, of beginining and ending indices of tokens within the corresponding substrings in start and finish. Tokens are denoted by parentheses in the expression, expr. [...] = regexpi(str,expr,'once') finds just the first match. (By default, regexp returns all matches.) If no matches are found, then all return values are
empty.
Remarks
See "Regular Expressions", in the MATLAB documentation, for a listing of all regular expression metacharacters supported by MATLAB.
regexpi does not support international character sets.
Examples
Return a row vector of indices that match words that start with m and end with y, regardless of case:
str = 'My flowers may bloom in May'; pat = 'm\w*y';
2-235
regexpi
regexpi(str, pat) ans = 1 12 25
See Also
regexp, regexprep, strfind, findstr, strmatch, strcmp, strcmpi, strncmp, strncmpi
2-236
regexprep
Purpose Syntax Description
2regexprep
Replace string using regular expression
s = regexprep(str,expr,replace) s = regexprep(str,expr,replace,options) s = regexprep(str,expr,replace) replaces all occurrences of the regular expression, expr, in string, str, with the string, replace. The new string is returned. If no matches are found regexprep returns str unchanged.
When any of str, expr, or replace are cell arrays of strings, regexprep returns an m-by-n-by-p cell array of strings, where m is the number of strings in str, n is the number of regular expressions in expr, and p is the number of strings in replace.
s = regexprep(str,expr,replace,options) By default, regexprep replaces
all matches, is case sensitive, and does not use tokens. You can use one or more of the following options with regexprep.
Option ignorecase preservecase Description
Ignore the case of characters when matching expr to str. Ignore case when matching (as with 'ignorecase'), but override the case of replace characters with the case of corresponding characters in str when replacing. Modify replace to use the tokens delimited by parenthesis in expr such that $1 is the first token, $2 is the second token, ..., and $N is the Nth token. Replace only the first occurrence of expr in str. Replace only the Nth occurrence of expr in str.
tokenize
once N
Remarks
See "Regular Expressions", in the MATLAB documentation, for a listing of all regular expression metacharacters supported by MATLAB.
regexprep does not support international character sets.
2-237
regexprep
Examples Example 1
Perform a case-sensitive replacement on words starting with m and ending with y:
str = 'My flowers may bloom in May'; pat = 'm(\w*)y'; regexprep(str, pat, 'April') ans = My flowers April bloom in May
Replace all words starting with m and ending with y, regardless of case, but maintain the original case in the replacement strings:
regexprep(str, pat, 'April', 'preservecase') ans = April flowers april bloom in April
Example 2
Replace all variations of the words 'walk up' using the letters following walk as a token.
str = 'I walk up, they walked up, we are walking up, she walks.'; pat = 'walk(\w*) up'; regexprep(str, pat, 'ascend$1', 'tokenize') ans = I ascend, they ascended, we are ascending, she walks.
See Also
regexp, regexpi, strfind, findstr, strmatch, strcmp, strcmpi, strncmp, strncmpi
2-238
registerevent (COM)
Purpose Syntax Arguments
2registerevent (COM)
Register an event handler with a control's event
registerevent(h, callback | {event1 eventhandler1; event2 eventhandler2; ...}) h
Handle for a MATLAB COM control object.
callback
Name of an M-function that accepts a variable number of arguments. This function will be called whenever the control triggers an event. Each argument is converted to a MATLAB string. See the section, "Writing Event Handlers" in the External Interfaces/API documentation for more information on handling control events.
event
Any event associated with h that can be triggered. Specify event using the event name.
eventhandler
Name of an M-function that accepts a variable number of arguments. This function will be called whenever the control triggers the event associated with it. See "Writing Event Handlers" in the External Interfaces/API documentation for more information on handling control events.
Description
Register one or more events with a single callback function or with a separate handler function for each event. You can either register events at the time you create the control (using actxcontrol), or register them dynamically at any time after the control has been created (using registerevent). The strings specified in the callback, event, and eventhandler arguments are not case sensitive.
Note There are two ways to handle events. You can create a single handler (callback) for all events, or you can specify a cell array that contains pairs of events and event handlers. In the cell array format, specify events by name in a quoted string. There is no limit to the number of pairs that can be specified in the cell array. Although using the single callback method may be easier in
2-239
registerevent (COM)
some cases, using the cell array technique creates more efficient code that results in better performance.
Examples
Create an mwsamp control and list all events associated with the control:
f = figure ('pos', [100 200 200 200]); h = actxcontrol ('mwsamp.mwsampctrl.2', [0 0 200 200], f); events(h) ans = Click = void Click() DblClick = void DblClick() MouseDown = void MouseDown(int16 Button, int16 Shift, Variant x, Variant y)
Register all events with the same callback routine, sampev. Use the eventlisteners function to see the event handler used by each event:
registerevent(h, 'sampev'); eventlisteners(h) ans = 'click' 'sampev' 'dblclick' 'sampev' 'mousedown' 'sampev' unregisterallevents(h);
Register the Click and DblClick events with event handlers myclick and my2click, respectively:
registerevent(h, {'click' 'myclick'; 'dblclick' 'my2click'}); eventlisteners(h) ans = 'click' 'myclick' 'dblclick' 'my2click'
See Also
events, eventlisteners, unregisterevent, unregisterallevents, isevent
2-240
rehash
Purpose Syntax
2rehash
Refresh function and file system path caches
rehash rehash rehash rehash rehash rehash
path toolbox pathreset toolboxreset toolboxcache
Description
rehash with no arguments updates the MATLAB list of known files and classes for directories on the search path that are not in $matlabroot/toolbox. It
compares the timestamps for loaded functions (functions that have been called but not cleared in the current session) against their timestamps on disk. It clears loaded functions if the files on disk are newer. All of this normally happens each time MATLAB displays the Command Window prompt. Therefore, use rehash with no arguments only when you run an M-file that updates another M-file, and the calling file needs to reuse the updated version before it has finished running.
rehash path performs the same updates as rehash, but uses a different
technique for detecting the files and directories that require updates. If you receive a warning during MATLAB startup notifying you that MATLAB could not tell if a directory has changed and you encounter problems with MATLAB using the most current versions of your M-files, run rehash path.
rehash toolbox updates all directories in $matlabroot/toolbox. Run this when you add or remove files in $matlabroot/toolbox during a session by
some means other than MATLAB tools, like the Editor.
rehash pathreset performs the same updates as rehash path, and also
ensures the known files and classes list follows precedence rules for shadowed functions.
rehash toolboxreset performs the same updates as rehash toolbox, and
also ensures the known files and classes list follows precedence rules for shadowed functions.
2-241
rehash
rehash toolboxcache performs the same updates as rehash toolbox, and
also updates the cache file. This is the equivalent of clicking the Update Toolbox Path Cache button in General Preferences.
See Also
addpath, clear, path, rmpath
"Toolbox Path Caching" in MATLAB Development Environment.
2-242
release (COM)
Purpose Syntax Arguments Description
2release (COM)
Release an interface
release(h) h
Handle for a COM object that represents the interface to be released. Release the interface and all resources used by the interface. Each interface handle must be released when you are finished manipulating its properties and invoking its methods. Once an interface has been released, it is no longer valid and subsequent operations on the MATLAB object that represents that interface will result in errors.
Note Releasing the interface will not delete the control itself (see delete), since other interfaces on that object may still be active. See "Releasing Interfaces" in the External Interfaces/API documentation for more information.
Examples
Create a Microsoft Calender application. Then create a TitleFont interface and use it to change the appearance of the font of the calendar's title:
f = figure('pos',[300 300 500 500]); cal = actxcontrol('mscal.calendar', [0 0 500 500], f); TFont = get(cal, 'TitleFont') TFont = Interface.mscal.calendar.TitleFont set(TFont, 'Name', 'Viva BoldExtraExtended'); set(TFont, 'Bold', 0);
When you're finished working with the title font, release the TitleFont interface:
release(TFont);
Now create a GridFont interface and use it to modify the size of the calendar's date numerals:
2-243
release (COM)
GFont = get(cal, 'GridFont') GFont = Interface.mscal.calendar.GridFont set(GFont, 'Size', 16);
When you're done, delete the cal object and the figure window:
delete(cal); delete(f); clear f;
See Also
delete, save, load, actxcontrol, actxserver
2-244
rem
Purpose Syntax Description
2rem
Remainder after division
R = rem(X,Y) R = rem(X,Y) if Y ~= 0, returns X - n.*Y where n = fix(X./Y). If Y is not an integer and the quotient X./Y is within roundoff error of an integer, then n is that integer. By convention, rem(X,0) is NaN. The inputs X and Y must be real
arrays of the same size, or real scalars.
Remarks
So long as operands X and Y are of the same sign, the statement rem(X,Y) returns the same result as does mod(X,Y). However, for positive X and Y,
rem(-X,Y) = mod(-X,Y)-Y
The rem function returns a result that is between 0 and sign(X)*abs(Y). If Y is zero, rem returns NaN.
See Also
mod
2-245
repmat
Purpose Syntax
2repmat
Replicate and tile an array
B = repmat(A,m,n) B = repmat(A,[m n]) B = repmat(A,[m n p...]) repmat(A,m,n) B = repmat(A,m,n) creates a large matrix B consisting of an m-by-n tiling of copies of A. The statement repmat(A,n) creates an n-by-n tiling. B = repmat(A,[m n]) accomplishes the same result as repmat(A,m,n). B = repmat(A,[m n p...]) produces a multidimensional (m-by-n-by-p-by-...) array composed of copies of A. A may be multidimensional. repmat(A,m,n) when A is a scalar, produces an m-by-n matrix filled with A's value. This can be much faster than a*ones(m,n) when m or n is large.
Description
Examples
In this example, repmat replicates 12 copies of the second-order identity matrix, resulting in a "checkerboard" pattern.
B = repmat(eye(2),3,4) B = 1 0 1 0 1 0 0 1 0 1 0 1 1 0 1 0 1 0 0 1 0 1 0 1 1 0 1 0 1 0 0 1 0 1 0 1 1 0 1 0 1 0 0 1 0 1 0 1
The statement N = repmat(NaN,[2 3]) creates a 2-by-3 matrix of NaNs.
2-246
reset
Purpose Syntax Description
2reset
Reset graphics object properties to their defaults
reset(h) reset(h) resets all properties having factory defaults on the object identified by h. To see the list of factory defaults, use the statement, get(0,'factory')
If h is a figure, MATLAB does not reset Position, Units, PaperPosition, and PaperUnits. If h is an axes, MATLAB does not reset Position and Units.
Examples
reset(gca) resets the properties of the current axes. reset(gcf) resets the properties of the current figure.
See Also
cla, clf, gca, gcf, hold
"Object Manipulation" for related functions
2-247
reshape
Purpose Syntax
2reshape
Reshape array
B B B B B = = = = = reshape(A,m,n) reshape(A,m,n,p,...) reshape(A,[m n p ...]) reshape(A,...,[],...) reshape(A,siz)
Description
B = reshape(A,m,n) returns the m-by-n matrix B whose elements are taken column-wise from A. An error results if A does not have m*n elements. B = reshape(A,m,n,p,...) or B = reshape(A,[m n p ...]) returns an N-D array with the same elements as A but reshaped to have the size m-by-n-by-p-by-... . The product of the specified dimensions, m*n*p*..., must be the same as prod(size(A)). B = reshape(A,...,[],...) calculates the length of the dimension represented by the placeholder [], such that the product of the dimensions equals prod(size(A)). The value of prod(size(A)) must be evenly divisible by the product of the specified dimensions. You can use only one occurence of []. B = reshape(A,siz) returns an N-D array with the same elements as A, but reshaped to siz, a vector representing the dimensions of the reshaped array. The quantity prod(siz) must be the same as prod(size(A)).
Examples
Reshape a 3-by-4 matrix into a 2-by-6 matrix.
A = 1 2 3 4 5 6 7 8 9 10 11 12
B = reshape(A,2,6) B = 1 3 5 7 2 4 6 8 B = reshape(A,2,[]) 9 10 11 12
2-248
reshape
B = 1 2 3 4 5 6 7 8 9 10 11 12
See Also
shiftdim, squeeze
The colon operator :
2-249
residue
Purpose Syntax Description
2residue
Convert between partial fraction expansion and polynomial coefficients
[r,p,k] = residue(b,a) [b,a] = residue(r,p,k)
The residue function converts a quotient of polynomials to pole-residue representation, and back again.
[r,p,k] = residue(b,a) finds the residues, poles, and direct term of a partial
fraction expansion of the ratio of two polynomials, b ( s ) and a ( s ) , of the form b1 s + b2 s + b3 s + ... + bm + 1 b(s) ---------- = -----------------------------------------------------------------------------------------------------n n1 n2 a(s) + a3 s + ... + an + 1 a1 s + a2 s where b j and a j are the jth elements of the input vectors b and a.
[b,a] = residue(r,p,k) converts the partial fraction expansion back to the polynomials with coefficients in b and a.
m m1 m2
Definition
If there are no multiple roots, then r1 r2 rn b(s) ---------- = -------------- + -------------- + ... + --------------- + k ( s ) a(s) s p1 s p2 s pn The number of poles n is
n = length(a)-1 = length(r) = length(p)
The direct term coefficient vector is empty if length(b) < length(a); otherwise
length(k) = length(b)-length(a)+1
If p(j) = ... = p(j+m-1) is a pole of multiplicity m, then the expansion includes terms of the form rj rj+m1 rj+1 -------------- + ---------------------- + ... + ----------------------s p j ( s p )2 ( s p )m
j j
2-250
residue
Arguments
b,a r p k
Vectors that specify the coefficients of the polynomials in descending powers of s Column vector of residues Column vector of poles Row vector of direct terms
Algorithm
It first obtains the poles with roots. Next, if the fraction is nonproper, the direct term k is found using deconv, which performs polynomial long division. Finally, the residues are determined by evaluating the polynomial with individual roots removed. For repeated roots, resi2 computes the residues at the repeated root locations. Numerically, the partial fraction expansion of a ratio of polynomials represents an ill-posed problem. If the denominator polynomial, a ( s ) , is near a polynomial with multiple roots, then small changes in the data, including roundoff errors, can make arbitrarily large changes in the resulting poles and residues. Problem formulations making use of state-space or zero-pole representations are preferable. If the ratio of two polynomials is expressed as b(s) 5s + 3s 2s + 7 ---------- = ---------------------------------------------3 a(s) 4s + 8s + 3 then
b = [ 5 3 -2 7] a = [-4 0 8 3]
3 2
Limitations
Examples
and you can calculate the partial fraction expansion as
[r, p, k] = residue(b,a) r = -1.4167 -0.6653 1.3320
2-251
residue
p = 1.5737 -1.1644 -0.4093 k = -1.2500
Now, convert the partial fraction expansion back to polynomial coefficients.
[b,a] = residue(r,p,k) b = -1.2500 a = 1.0000 -0.0000 -2.0000 -0.7500 -0.7500 0.5000 -1.7500
The result can be expressed as b(s) 1.25s 0.75s + 0.50s 1.75 ---------- = ----------------------------------------------------------------------------------3 a(s) s 2.00s 0.75 Note that the result is normalized for the leading coefficient in the denominator.
3 2
See Also References
deconv, poly, roots
[1] Oppenheim, A.V. and R.W. Schafer, Digital Signal Processing, Prentice-Hall, 1975, p. 56.
2-252
rethrow
Purpose Syntax Description
2rethrow
Reissue error
rethrow(err) rethrow(err) reissues the error specified by err. The currently running M-file terminates and control returns to the keyboard (or to any enclosing catch block). The err argument must be a MATLAB structure containing the following character array fields.
Fieldname message identifier
Description
Text of the error message Message identifier of the error message
See "Message Identifiers" in the MATLAB documentation for more information on the syntax and usage of message identifiers. A convenient way to get a valid err structure for the last error issued is by using the lasterror function.
Examples
rethrow is usually used in conjunction with try-catch statements to reissue an error from a catch block after performing catch-related operations. For
example:
try do_something catch do_cleanup rethrow(lasterror) end
See Also
error, lasterror, lasterr, try, catch, dbstop
2-253
return
Purpose Syntax Description Examples
2return
Return to the invoking function
return return causes a normal return to the invoking function or to the keyboard. It
also terminates keyboard mode. If the determinant function were an M-file, it might use a return statement in handling the special case of an empty matrix as follows:
function d = det(A) %DET det(A) is the determinant of A. if isempty(A) d = 1; return else ... end
See Also
break, continue, disp, end, error, for, if, keyboard, switch, while
2-254
rgb2hsv
Purpose Syntax Description
2rgb2hsv
Convert RGB colormap to HSV colormap
cmap = rgb2hsv(M) cmap = rgb2hsv(M) converts an RGB colormap, M, to an HSV colormap, cmap.
Both colormaps are m-by-3 matrices. The elements of both colormaps are in the range 0 to 1. The columns of the input matrix, M, represent intensities of red, green, and blue, respectively. The columns of the output matrix, cmap, represent hue, saturation, and value, respectively.
hsv_image = rgb2hsv(rgb_image) converts the RGB image to the equivalent
HSV image. RGB is an m-by-n-by-3 image array whose three planes contain the red, green, and blue components for the image. HSV is returned as an m-by-n-by-3 image array whose three planes contain the hue, saturation, and value components for the image.
See Also
brighten, colormap, hsv2rgb,rgbplot
"Color Operations" for related functions
2-255
rgbplot
Purpose Syntax Description
2rgbplot
Plot colormap
rgbplot(cmap) rgbplot(cmap) plots the three columns of cmap, where cmap is an m-by-3 colormap matrix. rgbplot draws the first column in red, the second in green,
and the third in blue.
Examples
Plot the RGB values of the copper colormap.
rgbplot(copper)
1
0.9
0.8
0.7
0.6
0.5
0.4
0.3
0.2
0.1
0
0
10
20
30
40
50
60
70
See Also
colormap
"Color Operations" for related functions
2-256
ribbon
Purpose Syntax
2ribbon
Ribbon plot
ribbon(Y) ribbon(X,Y) ribbon(X,Y,width) h = ribbon(...) ribbon(Y) plots the columns of Y as separate three-dimensional ribbons using X = 1:size(Y,1). ribbon(X,Y) plots X versus the columns of Y as three-dimensional strips. X and Y are vectors of the same size or matrices of the same size. Additionally, X can be a row or a column vector, and Y a matrix with length(X) rows. ribbon(X,Y,width) specifies the width of the ribbons. The default is 0.75. h = ribbon(...) returns a vector of handles to surface graphics objects. ribbon returns one handle per strip.
Description
Examples
Create a ribbon plot of the peaks function.
[x,y] = meshgrid(-3:.5:3,-3:.1:3); z = peaks(x,y); ribbon(y,z) colormap hsv
2-257
ribbon
10
5
0
-5
-10 4 2 0 -2 -4 0 5 10 15
See Also
plot, plot3, surface, waterfall
"Polygons and Surfaces" for related functions
2-258
rmappdata
Purpose Syntax Description See Also
2rmappdata
Remove application-defined data
rmappdata(h,name,value) rmappdata(h,name,value) removes the application-defined data name from the object specified by handle h. getappdata, isappdata, setappdata
2-259
rmdir
Purpose Graphical Interface Syntax
2rmdir
Remove directory As an alternative to the rmdir function, use the delete feature in the Current Directory browser.
rmdir('dirname') rmdir('dirname','s') [status,message,messageid] = rmdir('dirname','s') rmdir('dirname') removes the directory dirname from the current directory. If the directory is not empty, you must use the s argument. If dirname is not in
Description
the current directory, specify the relative path to the current directory or the full path for dirname.
rmdir('dirname','s') removes the directory dirname and its contents from the current directory. This removes all subdirectories and files in the current directory regardless of their write permissions. [status, message, messageid] = rmdir('dirname','s') removes the directory dirname and its contents from the current directory, returning the status, a message, and the MATLAB error message ID (see error and lasterr). Here, status is 1 for success and is 0 for no error, and message, messageid, and the s input argument are optional.
Examples
Remove Empty Directory
To remove myfiles from the current directory, where myfiles is empty, type
rmdir('myfiles')
If the current directory is matlabr13/work, and myfiles is in d:/matlabr13/work/project/, use the relative path to myfiles
rmdir('project/myfiles')
or the full path to myfiles
rmdir('d:/matlabr13/work/project/myfiles')
2-260
rmdir
Remove Directory and All Contents
To remove myfiles, its subdirectories, and all files in the directories, assuming myfiles is in the current directory, type
rmdir('myfiles','s')
Remove Directory and Return Results
To remove myfiles from the current directory, type
[stat, mess, id]=rmdir('myfiles')
MATLAB returns
stat = 0 mess = The directory is not empty. id = MATLAB:RMDIR:OSError
indicating the directory myfiles is not empty. To remove myfiles and its contents, run
[stat, mess]=rmdir('myfiles','s')
and MATLAB returns
stat = 1 mess = ''
indicating myfiles and its contents were removed.
2-261
rmdir
See Also
cd, copyfile, delete, dir, error, fileattrib, filebrowser, lasterr, mkdir, movefile
2-262
rmfield
Purpose Syntax Description
2rmfield
Remove structure fields
s = rmfield(s,'field') s = rmfield(s,FIELDS) s = rmfield(s,'field') removes the specified field from the structure array s. s = rmfield(s,FIELDS) removes more than one field at a time when FIELDS
is a character array of field names or cell array of strings.
See Also
fieldnames, isfield, orderfields
2-263
rmpath
Purpose Graphical Interface Syntax Description
2rmpath
Remove directories from MATLAB search path As an alternative to the rmpath function, use the Set Path dialog box. To open it, select Set Path from the File menu in the MATLAB desktop.
rmpath('directory') rmpath directory rmpath('directory') removes the specified directory from the current MATLAB search path. Use the full pathname for directory. rmpath directory is the unquoted form of the syntax.
Examples
Remove /usr/local/matlab/mytools from the search path.
rmpath /usr/local/matlab/mytools
See Also
addpath, path, pathtool, rehash
2-264
root object
Purpose Description
2root object
Root object properties The root is a graphics object that corresponds to the computer screen. There is only one root object and it has no parent. The children of the root object are figures. The root object exists when you start MATLAB; you never have to create it and you cannot destroy it. Use set and get to access the root properties.
See Also
Object Hierarchy
diary, echo, figure, format, gcf, get, set
Root
Figure
Axes
Uicontrol
Uimenu
Uicontextmenu
Image
Light
Line
Patch
Rectangle
Surface
Text
Property List
The following table lists all root properties and provides a brief description of each. The property name links take you to an expanded description of the properties. This table does not include properties that are defined for, but not used by, the root object.
Property Description Property Value
Property Name Information about MATLAB state CallbackObject
Handle of object whose callback is executing Handle of current figure
Values: object handle Values: object handle
CurrentFigure
2-265
root object
Property Name ErrorMessage PointerLocation PointerWindow
Property Description
Property Value
Text of last error message Current location of pointer Handle of window containing the pointer Show or hide handles marked as hidden
Value: character string Values: x-, and y-coordinates Values: figure handle Values: on, off Default: off
ShowHiddenHandles
Controlling MATLAB behavior Diary
Enable the diary file Name of the diary file Display each line of script M-file as executed Format used to display numbers
Values: on, off Default: off Values: filename (string) Default: diary Values: on, off Default: off Values: short, shortE, long, longE, bank, hex, +, rat Default: shortE Values: compact, loose Default: loose Values: string Default: english Values: integer Defalut: 2.1478e+009 Values: pixels, normalized, inches, centimeters, points, characters Default: pixels
DiaryFile
Echo
Format
FormatSpacing
Display or omit extra line feed System environment setting Maximum number of nested M-file calls Units for PointerLocation and ScreenSize properties
Language
RecursionLimit
Units
Information about the display
2-266
root object
Property Name FixedWidthFontName
Property Description
Property Value
Value for axes, text, and uicontrol FontName property Depth of the display bitmap Size of the screen
Values: font name Default: Courier Values: bits per pixel Values: [left, bottom, width, height]
ScreenDepth ScreenSize
General Information About Root Objects Children
Handles of all nonhidden Figue objects The root object has no parent This property is not used by the root object. User-specified label The type of graphics object (read only) User-specified data
Values: vector of handles Value: [] (empty matrix)
Parent Selected
Tag
Value: any string Default: '' (empty string) Value: the string 'root' Values: any matrix Default: [] (empty matrix)
Type
UserData
2-267
Root Properties
Modifying Properties
2Root Properties
You can set and query graphics object properties in two ways: The Property Editor is an interactive tool that enables you to see and change object property values. The set and get commands enable you to set and query the values of properties To change the default value of properties see Setting Default Property Values.
Root Properties This section lists property names along with the type of values each accepts.
Curly braces { } enclose default values.
BusyAction cancel | {queue}
Not used by the root object.
ButtonDownFcn
string
Not used by the root object.
CallbackObject
handle (read only)
Handle of current callback's object. This property contains the handle of the object whose callback routine is currently executing. If no callback routines are executing, this property contains the empty matrix [ ]. See also the gco command.
CaptureMatrix
(obsolete)
This property has been superseded by the getframe command.
CaptureRect
(obsolete)
This property has been superseded by the getframe command.
Children
vector of handles
Handles of child objects. A vector containing the handles of all nonhidden figure objects. You can change the order of the handles and thereby change the stacking order of the figures on the display.
Clipping {on} | off
Clipping has no effect on the root object.
CreateFcn
The root does not use this property.
2-268
Root Properties
CurrentFigure
figure handle
Handle of the current figure window, which is the one most recently created, clicked in, or made current with the statement:
figure(h)
which restacks the figure to the top of the screen, or
set(0,'CurrentFigure',h)
which does not restack the figures. In these statements, h is the handle of an existing figure. If there are no figure objects,
get(0,'CurrentFigure')
returns the empty matrix. Note, however, that gcf always returns a figure handle, and creates one if there are no figure objects.
DeleteFcn
string
This property is not used since you cannot delete the root object
Diary on | {off}
Diary file mode. When this property is on, MATLAB maintains a file (whose name is specified by the DiaryFile property) that saves a copy of all keyboard input and most of the resulting output. See also the diary command.
DiaryFile
string
Diary filename. The name of the diary file. The default name is diary.
Echo on | {off}
Script echoing mode. When Echo is on, MATLAB displays each line of a script file as it executes. See also the echo command.
ErrorMessage
string
Text of last error message. This property contains the last error message issued by MATLAB.
FixedWidthFontName font name
Fixed-width font to use for axes, text, and uicontrols whose FontName is set to FixedWidth. MATLAB uses the font name specified for this property as the value for axes, text, and uicontrol FontName properties when their FontName property is set to FixedWidth. Specifying the font name with this property
2-269
Root Properties
eliminates the need to hardcode font names in MATLAB applications and thereby enables these applications to run without modification in locales where non-ASCII character sets are required. In these cases, MATLAB attempts to set the value of FixedWidthFontName to the correct value for a given locale. MATLAB application developers should not change this property, but should create axes, text, and uicontrols with FontName properties set to FixedWidth when they want to use a fixed width font for these objects. MATLAB end users can set this property if they do not want to use the preselected value. In locales where Latin-based characters are used, Courier is the default.
Format short | {shortE} | long | longE | bank | hex | + | rat
Output format mode. This property sets the format used to display numbers. See also the format command. short Fixed-point format with 5 digits. shortE Floating-point format with 5 digits. shortG Fixed- or floating-point format displaying as many significant figures as possible with 5 digits. long Scaled fixed-point format with 15 digits. longE Floating-point format with 15 digits. longG Fixed- or floating-point format displaying as many significant figures as possible with 15 digits. bank Fixed-format of dollars and cents. hex Hexadecimal format. + Displays + and symbols. rat Approximation by ratio of small integers.
FormatSpacing compact | {loose}
Output format spacing (see also format command). compact -- Suppress extra line feeds for more compact display. loose -- Display extra line feeds for a more readable display.
2-270
Root Properties
HandleVisibility
{on} | callback | off
This property is not useful on the root object.
HitTest {on} | off
This property is not useful on the root object.
Interruptible {on} | off
This property is not useful on the root object.
Language
string
System environment setting.
Parent
handle
Handle of parent object. This property always contains the empty matrix, as the root object has no parent.
PointerLocation [x,y]
Current location of pointer. A vector containing the x- and y-coordinates of the pointer position, measured from the lower-left corner of the screen. You can move the pointer by changing the values of this property. The Units property determines the units of this measurement. This property always contains the instantaneous pointer location, even if the pointer is not in a MATLAB window. A callback routine querying the PointerLocation can get a different value than the location of the pointer when the callback was triggered. This difference results from delays in callback execution caused by competition for system resources.
PointerWindow
handle (read only)
Handle of window containing the pointer. MATLAB sets this property to the handle of the figure window containing the pointer. If the pointer is not in a MATLAB window, the value of this property is 0. A callback routine querying the PointerWindow can get the wrong window handle if you move the pointer to another window before the callback executes. This error results from delays in callback execution caused by competition for system resources.
RecursionLimit
integer
Number of nested M-file calls. This property sets a limit to the number of nested calls to M-files MATLAB will make before stopping (or potentially running out of memory). By default the value is set to a large value. Setting this
2-271
Root Properties
property to a smaller value (something like 150, for example) should prevent MATLAB from running out of memory and will instead cause MATLAB to issue an error when the limit is reached.
ScreenDepth
bits per pixel
Screen depth. The depth of the display bitmap (i.e., the number of bits per pixel). The maximum number of simultaneously displayed colors on the current graphics device is 2 raised to this power.
ScreenDepth supersedes the BlackAndWhite property. To override automatic
hardware checking, set this property to 1. This value causes MATLAB to assume the display is monochrome. This is useful if MATLAB is running on color hardware but is displaying on a monochrome terminal. Such a situation can cause MATLAB to determine erroneously that the display is color.
ScreenSize
4-element rectangle vector (read only)
Screen size. A four-element vector,
[left,bottom,width,height]
that defines the display size. left and bottom are 0 for all Units except pixels, in which case left and bottom are 1. width and height are the screen dimensions in units specified by the Units property.
Selected on | off
This property has no effect on the root level.
SelectionHighlight {on} | off
This property has no effect on the root level.
ShowHiddenHandles on | {off}
Show or hide handles marked as hidden. When set to on, this property disables handle hiding and exposes all object handles, regardless of the setting of an object's HandleVisibility property. When set to off, all objects so marked remain hidden within the graphics hierarchy.
Tag
string
User-specified object label. The Tag property provides a means to identify graphics objects with a user-specified label. While it is not necessary to identify the root object with a tag (since its handle is always 0), you can use this property to store any string value that you can later retrieve using set.
2-272
Root Properties
Type
string (read only)
Class of graphics object. For the root object, Type is always 'root'.
UIContextMenu
handle
This property has no effect on the root level.
Units {pixels} | normalized | inches | centimeters | points | characters
Unit of measurement. This property specifies the units MATLAB uses to interpret size and location data. All units are measured from the lower-left corner of the screen. Normalized units map the lower-left corner of the screen to (0,0) and the upper right corner to (1.0,1.0). inches, centimeters, and points are absolute units (one point equals 1/72 of an inch). Characters are units defined by characters from the default system font; the width of one unit is the width of the letter x, the height of one character is the distance between the baselines of two lines of text. This property affects the PointerLocation and ScreenSize properties. If you change the value of Units, it is good practice to return it to its default value after completing your operation so as not to affect other functions that assume Units is set to the default value.
UserData
matrix
User specified data. This property can be any data you want to associate with the root object. MATLAB does not use this property, but you can access it using the set and get functions.
Visible {on} | off
Object visibility. This property has no effect on the root object.
2-273
roots
Purpose Syntax Description
2roots
Polynomial roots
r = roots(c) r = roots(c) returns a column vector whose elements are the roots of the polynomial c.
Row vector c contains the coefficients of a polynomial, ordered in descending powers. If c has n+1 components, the polynomial it represents is c1 s n + ... + cn s + cn + 1 .
Remarks
Note the relationship of this function to p = poly(r), which returns a row vector whose elements are the coefficients of the polynomial. For vectors, roots and poly are inverse functions of each other, up to ordering, scaling, and roundoff error. The polynomial s 3 6s 2 72s 27 is represented in MATLAB as
p = [1 -6 -72 -27]
Examples
The roots of this polynomial are returned in a column vector by
r = roots(p) r = 12.1229 -5.7345 -0.3884
Algorithm
The algorithm simply involves computing the eigenvalues of the companion matrix:
A = diag(ones(n-2,1),-1); A(1,:) = -c(2:n-1)./c(1); eig(A)
It is possible to prove that the results produced are the exact eigenvalues of a matrix within roundoff error of the companion matrix A, but this does not mean that they are the exact roots of a polynomial with coefficients within roundoff error of those in c.
2-274
roots
See Also
fzero, poly, residue
2-275
rose
Purpose Syntax
2rose
Angle histogram
rose(theta) rose(theta,x) rose(theta,nbins) [tout,rout] = rose(...) rose creates an angle histogram, which is a polar plot showing the distribution
Description
of values grouped according to their numeric range. Each group is shown as one bin.
rose(theta) plots an angle histogram showing the distribution of theta in 20 angle bins or less. The vector theta, expressed in radians, determines the angle
from the origin of each bin. The length of each bin reflects the number of elements in theta that fall within a group, which ranges from 0 to the greatest number of elements deposited in any one bin.
rose(theta,x) uses the vector x to specify the number and the locations of bins. length(x) is the number of bins and the values of x specify the center angle of each bin. For example, if x is a five-element vector, rose distributes the elements of theta in five bins centered at the specified x values. rose(theta,nbins) plots nbins equally spaced bins in the range [0, 2*pi]. The default is 20. [tout,rout] = rose(...) returns the vectors tout and rout so polar(tout,rout) generates the histogram for the data. This syntax does not
generate a plot.
Example
Create a rose plot showing the distribution of 50 random numbers.
theta = 2*pi*rand(1,50); rose(theta)
2-276
rose
90 5 120 4 60
3 150 2 30
1
180
0
210
330
240 270
300
See Also
compass, feather, hist, polar
"Histograms" for related functions Histograms in Polar Coordinates for another example
2-277
rosser
Purpose Syntax Description
2rosser
Classic symmetric eigenvalue test problem
A = rosser A = rosser returns the Rosser matrix. This matrix was a challenge for many matrix eigenvalue algorithms. But LAPACK's DSYEV routine used in MATLAB
has no trouble with it. The matrix is 8-by-8 with integer elements. It has: A double eigenvalue Three nearly equal eigenvalues Dominant eigenvalues of opposite sign A zero eigenvalue A small, nonzero eigenvalue
Examples
rosser ans = 611 196 -192 407 -8 -52 -49 29 196 899 113 -192 -71 -43 -8 -44 -192 113 899 196 61 49 8 52 407 -192 196 611 8 44 59 -23 -8 -71 61 8 411 -599 208 208 -52 -43 49 44 -599 411 208 208 -49 -8 8 59 208 208 99 -911 29 -44 52 -23 208 208 -911 99
2-278
rot90
Purpose Syntax Description
2rot90
Rotate matrix 90
B = rot90(A) B = rot90(A,k) B = rot90(A) rotates matrix A counterclockwise by 90 degrees. B = rot90(A,k) rotates matrix A counterclockwise by k*90 degrees, where k is
an integer.
Examples
The matrix
X = 1 4 7 2 5 8 3 6 9
rotated by 90 degrees is
Y = rot90(X) Y = 3 6 2 5 1 4
9 8 7
See Also
flipdim, fliplr, flipud
2-279
rotate
Purpose Syntax Description
2rotate
Rotate object about a specified direction
rotate(h,direction,alpha) rotate(...,origin)
The rotate function rotates a graphics object in three-dimensional space, according to the right-hand rule.
rotate(h,direction,alpha) rotates the graphics object h by alpha degrees. direction is a two- or three-element vector that describes the axis of rotation
in conjunction with the origin.
rotate(...,origin) specifies the origin of the axis of rotation as a
three-element vector. The default origin is the center of the plot box.
Remarks
The graphics object you want rotated must be a child of the same axes. The object's data is modified by the rotation transformation. This is in contrast to view and rotate3d, which only modify the viewpoint. The axis of rotation is defined by an origin and a point P relative to the origin. P is expressed as the spherical coordinates [theta phi], or as Cartesian coordinates.
Z P
Y
ax fr is o ota tion
origin
X The two-element form for direction specifies the axis direction using the spherical coordinates [theta phi]. theta is the angle in the xy plane
2-280
rotate
counterclockwise from the positive x-axis. phi is the elevation of the direction vector from the xy plane.
Z
P
r
phi
th et a
Y
X
The three-element form for direction specifies the axis direction using Cartesian coordinates. The direction vector is the vector from the origin to (X,Y,Z).
Examples
Rotate a graphics object 180 about the x-axis.
h = surf(peaks(20)); rotate(h,[1 0 0],180)
Rotate a surface graphics object 45 about its center in the z direction.
h = surf(peaks(20)); zdir = [0 0 1]; center = [10 10 0]; rotate(h,zdir,45,center)
Remarks See Also
rotate changes the Xdata, Ydata, and Zdata properties of the appropriate
graphics object.
rotate3d, sph2cart, view
The axes CameraPosition, CameraTarget, CameraUpVector, CameraViewAngle "Object Manipulation" for related functions
2-281
rotate3d
Purpose Syntax
2rotate3d
Rotate 3-D view using mouse
rotate3d on rotate3d off rotate3d rotate3d(figure_handle,...) rotate3d(axes_handle,...) rotate3d on enables mouse-base rotation on all axes within the current figure. rotate3d off disables interactive axes rotation in the current figure. rotate3d toggles interactive axes rotation in the current figure. rotate3d(figure_handle,...) enables rotation within the specified figure
Description
instead of the current figure.
rotate3d(axes_handle,...) enables rotation only in the specified axes.
Using rotate3d
When enabled, clicking on an axes draws an animated box, which rotates as the mouse is dragged, showing the view that will result when the mouse button is released. A numeric readout appears in the lower-left corner of the figure during rotation, showing the current azimuth and elevation of the animated box. Releasing the mouse button removes the animated box and the readout, and changes the view of the axes to correspond to the last orientation of the animated box.
See Also
camorbit, rotate, view
Object Manipulation for related functions.
2-282
round
Purpose Syntax Description Examples
2round
Round to nearest integer
Y = round(X) Y = round(X) rounds the elements of X to the nearest integers. For complex X,
the imaginary and real parts are rounded independently.
a = [-1.9, -0.2, 3.4, 5.6, 7.0, 2.4+3.6i] a = Columns 1 through 4 -1.9000 -0.2000 3.4000 Columns 5 through 6 7.0000 2.4000 + 3.6000i round(a) ans = Columns 1 through 4 -2.0000 0 3.0000 Columns 5 through 6 7.0000 2.0000 + 4.0000i
5.6000
6.0000
See Also
ceil, fix, floor
2-283
rref
Purpose Syntax
2rref
Reduced row echelon form
R = rref(A) [R,jb] = rref(A) [R,jb] = rref(A,tol) R = rref(A) produces the reduced row echelon form of A using Gauss Jordan
Description
elimination with partial pivoting. A default tolerance of (max(size(A))*eps *norm(A,inf)) tests for negligible column elements.
[R,jb] = rref(A) also returns a vector jb such that:
r = length(jb) is this algorithm's idea of the rank of A. x(jb) are the pivot variables in a linear system Ax = b. A(:,jb) is a basis for the range of A. R(1:r,jb) is the r-by-r identity matrix.
[R,jb] = rref(A,tol) uses the given tolerance in the rank tests.
Roundoff errors may cause this algorithm to compute a different value for the rank than rank, orth and null.
Note The demo rrefmovie(A) enables you to sequence through the iterations of the algorithm.
Examples
Use rref on a rank-deficient magic square:
A = magic(4), R = rref(A) A = 16 5 9 4 2 11 7 14 3 10 6 15 13 8 12 1
2-284
rref
R = 1 0 0 0 0 1 0 0 0 0 1 0 1 3 -3 0
See Also
inv, lu, rank
2-285
rsf2csf
Purpose Syntax Description
2rsf2csf
Convert real Schur form to complex Schur form
[U,T] = rsf2csf(U,T)
The complex Schur form of a matrix is upper triangular with the eigenvalues of the matrix on the diagonal. The real Schur form has the real eigenvalues on the diagonal and the complex eigenvalues in 2-by-2 blocks on the diagonal.
[U,T] = rsf2csf(U,T) converts the real Schur form to the complex form.
Arguments U and T represent the unitary and Schur forms of a matrix A, respectively, that satisfy the relationships: A = U*T*U' and U'*U = eye(size(A)). See schur for details.
Examples
Given matrix A,
1 1 1 -2 1 2 1 1 1 1 3 1 3 1 1 4
with the eigenvalues
4.8121 1.9202 + 1.4742i 1.9202 + 1.4742i 1.3474
Generating the Schur form of A and converting to the complex Schur form
[u,t] = schur(A); [U,T] = rsf2csf(u,t)
yields a triangular matrix T whose diagonal (underlined here for readability) consists of the eigenvalues of A.
U = -0.4916 -0.4980 -0.6751 -0.2337 -0.2756 -0.1012 0.1842 0.2635 + + 0.4411i 0.2163i 0.3860i 0.6481i 0.2133 -0.1046 -0.1867 0.3134 + + 0.5699i 0.2093i 0.3808i 0.5448i -0.3428 0.8001 -0.4260 0.2466
2-286
rsf2csf
T = 4.8121 0 0 0 -0.9697 + 1.0778i 1.9202 + 1.4742i 0 0 -0.5212 + 2.0051i 2.3355 1.9202 - 1.4742i 0 -1.0067 0.1117 + 1.6547i 0.8002 + 0.2310i 1.3474
See Also
schur
2-287
run
Purpose Syntax Description
2run
Run a script
run scriptname run scriptname runs the MATLAB script specified by scriptname. If scriptname contains the full pathname to the script file, then run changes the
current directory to be the one in which the script file resides, executes the script, and sets the current directory back to what it was. The script is run within the caller's workspace.
run is a convenience function that runs scripts that are not currently on the
path. Typically, you just type the name of a script at the MATLAB prompt to execute it. This works when the script is on your path. Use the cd or addpath function to make a script executable by entering the script name alone.
See Also
cd, addpath
2-288
runtime
Purpose Syntax
2runtime
Emulate the runtime environment in MATLAB and set the global error mode
runtime runtime runtime runtime on off status errormode mode
Description
The runtime command lets you emulate the Runtime Server environment in commercial MATLAB and set the global error mode for a runtime application. Because the Runtime Server disables the command window, it is generally much more convenient to test and debug with MATLAB emulating the Runtime Server than with the Runtime Server variant itself.
runtime on tells commercial MATLAB to begin emulating the Runtime Server.
This means that MATLAB executes neither M-files nor standard P-files. The command line remains accessible.
runtime off returns MATLAB to its ordinary state. runtime status indicates whether MATLAB is emulating the Runtime Server
or not.
runtime errormode mode sets the global error mode to mode. The value of mode can be either continue, quit, or dialog. However, dialog is both the default
error mode and the recommended one. The error mode setting is only effective when the application runs with the Runtime Server; when the application runs with commercial MATLAB emulating the Runtime Server, untrapped errors are always displayed in the command window.
See Also
isruntime
2-289
save
Purpose Graphical Interface Syntax
2save
Save workspace variables on disk As an alternative to the save function, select Save Workspace As from the File menu in the MATLAB desktop, or use the Workspace browser.
save save filename save filename var1 var2 ... save ... option save('filename', ...) save by itself, stores all workspace variables in a binary format in the current directory in a file named matlab.mat. Retrieve the data with load. MAT-files
Description
are double-precision, binary, MATLAB format files. They can be created on one machine and later read by MATLAB on another machine with a different floating-point format, retaining as much accuracy and range as the different formats allow. They can also be manipulated by other programs external to MATLAB.
save filename stores all workspace variables in the current directory in filename.mat. To save to another directory, use the full pathname for the filename. If filename is the special string stdio, the save command sends the
data as standard output.
save filename var1 var2 ... saves only the specified workspace variables in filename.mat. Use the * wildcard to save only those variables that match the specified pattern. For example, save('A*') saves all variables that start with A. save ... option saves the workspace variables in the format specified by option option Argument -append Result: How Data is Stored
The specified existed MAT-file, appended to the end 8-digit ASCII format
-ascii
2-290
save
option Argument -ascii -ascii -ascii -mat -v4 -double -tabs -double -tabs
Result: How Data is Stored
16-digit ASCII format delimits with tabs 16-digit ASCII format, tab delimited Binary MAT-file form (default) A format that MATLAB version 4 can open
Remarks
When saving in ASCII format, consider the following: Each variable to be saved must be either a two dimensional double array or a two dimensional character array. Saving a complex double array causes the imaginary part of the data to be lost, as MATLAB cannot load nonnumeric data ('i'). In order to be able to read the file with the MATLAB load function, all of the variables must have the same number of columns. If you are using a program other than MATLAB to read the saved data this restriction can be relaxed. Each MATLAB character in a character array is converted to a floating point number equal to its internal ASCII code and written out as a floating point number string. There is no information in the save file that indicates whether the value was originally a number or a character. The values of all variables saved merge into a single variable that takes the name of the ASCII file (minus any extension). Therefore, it is advisable to save only one variable at a time. With the v4 flag, you can only save data constructs that are compatible with versions of MATLAB 4. Therefore, you cannot save structures, cell arrays, multidimensional arrays, or objects. In addition, you must use filenames that are supported by MATLAB version 4.
save('filename', ...) is the function form of the syntax.
For more control over the format of the file, MATLAB provides other functions, as listed in "See Also", below.
2-291
save
Algorithm
The binary formats used by save depend on the size and type of each array. Arrays with any noninteger entries and arrays with 10,000 or fewer elements are saved in floating-point formats requiring 8 bytes per real element. Arrays with all integer entries and more than 10,000 elements are saved in the formats shown, requiring fewer bytes per element.
Element Range Bytes per Element
0 to 255 0 to 65535 -32767 to 32767 -231+1 to 231-1 other
1 2 2 4 8
External Interfaces to MATLAB provides details on reading and writing MAT-files from external C or Fortran programs. It is important to use recommended access methods, rather than rely upon the specific MAT-file format, which is likely to change in the future.
Examples
To save all variables from the workspace in binary MAT-file, test.mat, type
save test.mat
To save variables p and q in binary MAT-file, test.mat, type
savefile = 'test.mat'; p = rand(1,10); q = ones(10); save(savefile,'p','q')
To save the variables vol and temp in ASCII format to a file named june10, type
save('d:\mymfiles\june10','vol','temp','-ASCII')
See Also
diary, fprintf, fwrite, load, workspace
2-292
save (COM)
Purpose Syntax Arguments
2save (COM)
Serialize a COM control object to a file
save(h, 'filename') h
Handle for a MATLAB COM control object.
filename
The full path and filename of the serialized data.
Description
Save the COM control object associated with the interface represented by the MATLAB COM object h into a file. The COM save function is only supported for controls at this time.
Examples
Create an mwsamp control and save its original state to the file mwsample:
f = figure('pos', [100 200 200 200]); h = actxcontrol('mwsamp.mwsampctrl.2', [0 0 200 200], f); save(h, 'mwsample')
Now, alter the figure by changing its label and the radius of the circle:
set(h, 'Label', 'Circle'); set(h, 'Radius', 50); Redraw(h);
Using the load function, you can restore the control to its original state:
load(h, 'mwsample'); get(h) ans = Label: 'Label' Radius: 20
See Also
load, actxcontrol, actxserver, release, delete
2-293
save (serial)
Purpose Syntax Arguments
2save (serial)
Save serial port objects and variables to a MAT-file
save filename save filename obj1 obj2... filename obj1 obj2...
The MAT-file name. Serial port objects or arrays of serial port objects.
Description
save filename saves all MATLAB variables to the MAT-file filename. If an extension is not specified for filename, then the .mat extension is used. save filename obj1 obj2... saves the serial port objects obj1 obj2 ... to the
MAT-file filename.
Remarks
You can use save in the functional form as well as the command form shown above. When using the functional form, you must specify the filename and serial port objects as strings. For example. to save the serial port object s to the file MySerial.mat
s = serial('COM1'); save('MySerial','s')
Any data that is associated with the serial port object is not automatically stored in the MAT-file. For example, suppose there is data in the input buffer for obj. To save that data to a MAT-file, you must bring it into the MATLAB workspace using one of the synchronous read functions, and then save to the MAT-file using a separate variable name. You can also save data to a text file with the record function. You return objects and variables to the MATLAB workspace with the load command. Values for read-only properties are restored to their default values upon loading. For example, the Status property is restored to closed. To determine if a property is read-only, examine its reference pages. If you use the help command to display help for save, then you need to supply the pathname shown below.
help serial/private/save
Example
This example illustrates how to use the command and functional form of save.
2-294
save (serial)
s = serial('COM1'); set(s,'BaudRate',2400,'StopBits',1) save MySerial1 s set(s,'BytesAvailableFcn',@mycallback) save('MySerial2','s')
See Also
Functions
load, record
Properties
Status
2-295
saveas
Purpose Syntax Description
2saveas
Save figure or model using specified format
saveas(h,'filename.ext') saveas(h,'filename','format') saveas(h,'filename.ext') saves the figure or model with the handle h to the file filename.ext. The format of the file is determined by the extension, ext. Allowable values for ext are listed in this table. ext Values ai bmp emf eps fig jpg m pbm pcx pgm png ppm tif Format
Adobe Illustrator `88 Windows bitmap Enhanced metafile EPS Level 1 MATLAB figure (invalid for MATLAB models) JPEG image (invalid for MATLAB models) MATLAB M-file (invalid for MATLAB models) Portable bitmap Paintbrush 24-bit Portable Graymap Portable Network Graphics Portable Pixmap TIFF image, compressed
saveas(h,'filename','format') saves the figure or model with the handle h to the file called filename using the specified format. The filename can have
an extension but the extension is not used to define the file format. If no extension is specified, the standard extension corresponding to the specified format is automatically appended to the filename.
2-296
saveas
Allowable values for format are the extensions in the table above and the device types supported by print. The print device types include the formats listed in the table of extensions above as well as additional file formats. Use an extension from the table above or from the list of device types supported by print. When using the print device type to specify format for saveas, do not use the prepended -d.
Remarks
You can use open to open files saved using saveas with an m or fig extension. Other formats are not supported by open. The Save As dialog box you access from the figure window's File menu uses saveas, limiting the file extensions to m and fig. The Export dialog box you access from the figure window's File menu uses saveas with the format argument.
Examples
Example 1 Specify File Extension
Save the current figure that you annotated using the Plot Editor to a file named pred_prey using the MATLAB fig format. This allows you to open the file pred_prey.fig at a later time and continue editing it with the Plot Editor.
saveas(gcf,'pred_prey.fig')
Example 2 Specify File Format but No Extension
Save the current figure, using Adobe Illustrator format, to the file logo. Use the ai extension from the above table to specify the format. The file created is logo.ai.
saveas(gcf,'logo', 'ai')
This is the same as using the Adobe Illustrator format from the print devices table, which is -dill; use doc print or help print to see the table for print device types. The file created is logo.ai. MATLAB automatically appends the ai extension, for an Illustrator format file, because no extension was specified.
saveas(gcf,'logo', 'ill')
Example 3 Specify File Format and Extension
Save the current figure to the file star.eps using the Level 2 Color PostScript format. If you use doc print or help print, you can see from the table for print device types that the device type for this format is -dpsc2. The file created is star.eps.
2-297
saveas
saveas(gcf,'star.eps', 'psc2')
In another example, save the current model to the file trans.tiff using the TIFF format with no compression. From the table for print device types, you can see the device type for this format is -dtiffn. The file created is trans.tiff.
saveas(gcf,'trans.tiff', 'tiffn')
See Also
open, print
"Printing" for related functions
2-298
saveobj
Purpose Syntax Description
2saveobj
Save an object to a MAT-file
B = saveobj(A) B = saveobj(A) is called by the MATLAB save function when object, A, is saved to a .MAT file. This call executes the saveobj method for the object's class, if such a method exists. The return value B is subsequently used by save
to populate the .MAT file. When you issue a save command on an object, MATLAB looks for a method called saveobj in the class directory. You can overload this method to modify the object before the save operation. For example, you could define a saveobj method that saves related data along with the object.
Remarks
saveobj can be overloaded only for user objects. save will not call saveobj for a built-in datatype, such as double, even if @double/saveobj exists. saveobj will be separately invoked for each object to be saved.
A child object does not inherit the saveobj method of its parent class. To implement saveobj for any class, including a class that inherits from a parent, you must define a saveobj method within that class directory.
Examples
The following example shows a saveobj method written for the portfolio class. The method determines if a portfolio object has already been assigned an account number from a previous save operation. If not, saveobj calls getAccountNumber to obtain the number and assigns it to the account_number field. The contents of b is saved to the MAT-file.
function b = saveobj(a) if isempty(a.account_number) a.account_number = getAccountNumber(a); end b = a;
See Also
save, load, loadobj
2-299
scatter
Purpose Syntax
2scatter
2-D Scatter plot
scatter(X,Y,S,C) scatter(X,Y) scatter(X,Y,S) scatter(...,markertype) scatter(...,'filled') h = scatter(...,) scatter(X,Y,S,C) displays colored circles at the locations specified by the vectors X and Y (which must be the same size). S determines the area of each marker (specified in points^2). S can be a vector the same length as X and Y or a scalar. If S is a scalar, MATLAB draws all the
Description
markers the same size.
C determines the colors of each marker. When C is a vector the same length as X and Y, the values in C are linearly mapped to the colors in the current colormap. When C is a length(X)-by-3 matrix, it specifies the colors of the markers as RGB values. C can also be a color string (see ColorSpec for a list of
color string specifiers)
scatter(X,Y) draws the markers in the default size and color. scatter(X,Y,S) draws the markers at the specified sizes (S) with a single
color.
scatter(...,markertype) uses the marker type specified instead of 'o' (see LineSpec for a list of marker specifiers). scatter(...,'filled') fills the markers. h = scatter(...) returns the handles to the line objects created by scatter (see line for a list of properties you can specify using the object handles and set).
Remarks Examples
Use plot for single color, single marker size scatter plots.
load seamount scatter(x,y,5,z)
2-300
scatter
-47.95
-48
-48.05
-48.1
-48.15
-48.2
-48.25
-48.3
-48.35
-48.4
-48.45 210.8
210.9
211
211.1
211.2
211.3
211.4
211.5
211.6
211.7
211.8
See Also
scatter3, plot, plotmatrix
"Specialized Plotting" for related functions
2-301
scatter3
Purpose Syntax
2scatter3
3-D scatter plot
scatter3(X,Y,Z,S,C) scatter3(X,Y,Z) scatter3(X,Y,Z,S) scatter3(...,markertype) scatter3(...,'filled') h = scatter3(...,) scatter3(X,Y,Z,S,C) displays colored circles at the locations specified by the vectors X, Y, and Z (which must all be the same size). S determines the size of each marker (specified in points). S can be a vector the same length as X, Y, and Z or a scalar. If S is a scalar, MATLAB draws all the
Description
markers the same size.
C determines the colors of each marker. When C is a vector the same length as X, Y, and Z, the values in C are linearly mapped to the colors in the current colormap. When C is a length(X)-by-3 matrix, it specifies the colors of the markers as RGB values. C can also be a color string (see ColorSpec for a list of
color string specifiers)
scatter3(X,Y,Z) draws the markers in the default size and color. scatter3(X,Y,Z,S) draws the markers at the specified sizes (S) with a single
color.
scatter3(...,markertype) uses the marker type specified instead of 'o' (see LineSpec for a list of marker specifiers). scatter3(...,'filled') fills the markers. h = scatter3(...) returns the handles to the line objects created by scatter3 (see line for a list of properties you can specify using the object handles and set).
Remarks Examples
Use plot3 for single color, single marker size 3-D scatter plots.
[x,y,z] = sphere(16); X = [x(:)*.5 x(:)*.75 x(:)]; Y = [y(:)*.5 y(:)*.75 y(:)];
2-302
scatter3
Z = [z(:)*.5 z(:)*.75 z(:)]; S = repmat([1 .75 .5]*10,prod(size(x)),1); C = repmat([1 2 3],prod(size(x)),1); scatter3(X(:),Y(:),Z(:),S(:),C(:),'filled'), view(-60,60)
1 0.5 0 -0.5 0.5 -1 1 0.5 0 -0.5 -1 -1 -0.5 0 1
See Also
scatter, plot3
"Scatter Plots" for related functions
2-303
schur
Purpose Syntax
2schur
Schur decomposition
T = schur(A) T = schur(A,flag) [U,T] = schur(A,...)
Description
The schur command computes the Schur form of a matrix.
T = schur(A) returns the Schur matrix T. T = schur(A,flag) for real matrix A, returns a Schur matrix T in one of two forms depending on the value of flag: 'complex' 'real' T is triangular and is complex if A has complex eigenvalues. T has the real eigenvalues on the diagonal and the complex eigenvalues in 2-by-2 blocks on the diagonal. 'real' is the
default. If A is complex, schur returns the complex Schur form in matrix T. The complex Schur form is upper triangular with the eigenvalues of A on the diagonal. The function rsf2csf converts the real Schur form to the complex Schur form.
[U,T] = schur(A,...) also returns a unitary matrix U so that A = U*T*U' and U'*U = eye(size(A)).
Examples
H is a 3-by-3 eigenvalue test matrix: H = [ -149 537 -27 -50 180 -9 -154 546 -25 ]
Its Schur form is
schur(H) ans = 1.0000 0 0
-7.1119 -815.8706 2.0000 -55.0236 0 3.0000
2-304
schur
The eigenvalues, which in this case are 1, 2, and 3, are on the diagonal. The fact that the off-diagonal elements are so large indicates that this matrix has poorly conditioned eigenvalues; small changes in the matrix elements produce relatively large changes in its eigenvalues.
Algorithm
schur uses LAPACK routines to compute the Schur form of a matrix:
Matrix A
Routine DSYTRD, DSTEQR DSYTRD, DORGTR, DSTEQR (with output U) DGEHRD, DHSEQR DGEHRD, DORGHR, DHSEQR (with output U) ZHETRD, ZSTEQR ZHETRD, ZUNGTR, ZSTEQR (with output U) ZGEHRD, ZHSEQR ZGEHRD, ZUNGHR, ZHSEQR (with output U)
Real symmetric Real nonsymmetric Complex Hermitian Non-Hermitian
See Also References
eig, hess, qz, rsf2csf
[1] Anderson, E., Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra, J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen, LAPACK User's Guide (http://www.netlib.org/lapack/lug/lapack_lug.html), Third Edition, SIAM, Philadelphia, 1999.
2-305
script
Purpose Description
2script
Script M-files A script file is an external file that contains a sequence of MATLAB statements. By typing the filename, subsequent MATLAB input is obtained from the file. Script files have a filename extension of .m and are often called M-files. Scripts are the simplest kind of M-file. They are useful for automating blocks of MATLAB commands, such as computations you have to perform repeatedly from the command line. Scripts can operate on existing data in the workspace, or they can create new data on which to operate. Although scripts do not return output arguments, any variables that they create remain in the workspace so you can use them in further computations. In addition, scripts can produce graphical output using commands like plot. Scripts can contain any series of MATLAB statements. They require no declarations or begin/end delimiters. Like any M-file, scripts can contain comments. Any text following a percent sign (%) on a given line is comment text. Comments can appear on lines by themselves, or you can append them to the end of any executable line.
See Also
echo, function, type
2-306
sec
Purpose Syntax Description
2sec
Secant
Y = sec(X)
The sec function operates element-wise on arrays. The function's domains and ranges include complex values. All angles are in radians.
Y = sec(X) returns an array the same size as X containing the secant of the elements of X.
Examples
Graph the secant over the domains / 2 < x < / 2 and / 2 < x < 3 / 2 .
x1 = -pi/2+0.01:0.01:pi/2-0.01; x2 = pi/2+0.01:0.01:(3*pi/2)-0.01; plot(x1,sec(x1),x2,sec(x2)), grid on
150
100
50
0
-50
-100
-150 -2
-1
0
1
2
3
4
5
The expression sec(pi/2) does not evaluate as infinite but as the reciprocal of the floating-point accuracy eps, because pi is a floating-point approximation to the exact value of .
Definition
The secant can be defined as 1 sec ( z ) = --------------cos ( z )
2-307
sec
Algorithm
sec uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see http://www.netlib.org.
See Also
asec, asech, eps, pi, sech
2-308
sech
Purpose Syntax Description
2 sech
Hyperbolic secant
Y = sech(X)
The sech function operates element-wise on arrays. The function's domains and ranges include complex values. All angles are in radians.
Y = sech(X) returns an array the same size as X containing the hyperbolic secant of the elements of X.
Examples
Graph the hyperbolic secant over the domain 2 x 2.
x = -2*pi:0.01:2*pi; plot(x,sech(x)), grid on
1 0.9 0.8 0.7 0.6 0.5 0.4 0.3 0.2 0.1 0 -8 -6 -4 -2 0 2 4 6 8
Algorithm
sech uses this algorithm.
1 sech ( z ) = -------------------cosh ( z )
Definition
The secant can be defined as 1 sech ( z ) = -------------------cosh ( z )
2-309
sech
Algorithm
sec uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see http://www.netlib.org.
See Also
asec, asech, sec
2-310
selectmoveresize
Purpose Syntax Description
2selectmoveresize
Select, move, resize, or copy axes and uicontrol graphics objects
A = selectmoveresize; set(h,'ButtonDownFcn','selectmoveresize') selectmoveresize is useful as the callback routine for axes and uicontrol
button down functions. When executed, it selects the object and allows you to move, resize, and copy it. For example, this statement sets the ButtonDownFcn of the current axes to selectmoveresize:
set(gca,'ButtonDownFcn','selectmoveresize') A = selectmoveresize returns a structure array containing:
A.Type: a string containing the action type, which can be Select, Move, Resize, or Copy. A.Handles: a list of the selected handles or for a Copy an m-by-2 matrix containing the original handles in the first column and the new handles in the second column.
See Also
The ButtonDownFcn of axes and uicontrol graphics objects "Object Manipulation" for related functions
2-311
semilogx, semilogy
Purpose Syntax
2semilogx, semilogy
Semi-logarithmic plots
semilogx(Y) semilogx(X1,Y1,...) semilogx(X1,Y1,LineSpec,...) semilogx(...,'PropertyName',PropertyValue,...) h = semilogx(...) semilogy(...) h = semilogy(...)
Description
semilogx and semilogy plot data as logarithmic scales for the x- and y-axis, respectively. logarithmic semilogx(Y) creates a plot using a base 10 logarithmic scale for the x-axis and a linear scale for the y-axis. It plots the columns of Y versus their index if Y contains real numbers. semilogx(Y) is equivalent to semilogx(real(Y), imag(Y)) if Y contains complex numbers. semilogx ignores the imaginary
component in all other uses of this function.
semilogx(X1,Y1,...) plots all Xn versus Yn pairs. If only Xn or Yn is a matrix, semilogx plots the vector argument versus the rows or columns of the matrix,
depending on whether the vector's row or column dimension matches the matrix.
semilogx(X1,Y1,LineSpec,...) plots all lines defined by the Xn,Yn,LineSpec triples. LineSpec determines line style, marker symbol, and color of the plotted
lines.
semilogx(...,'PropertyName',PropertyValue,...) sets property values for
all line graphics objects created by semilogx.
semilogy(...) creates a plot using a base 10 logarithmic scale for the y-axis
and a linear scale for the x-axis.
h = semilogx(...) and h = semilogy(...) return a vector of handles to line
graphics objects, one handle per line.
2-312
semilogx, semilogy
Remarks
If you do not specify a color when plotting more than one line, semilogx and semilogy automatically cycle through the colors and line styles in the order specified by the current axes ColorOrder and LineStyleOrder properties. You can mix Xn,Yn pairs with Xn,Yn,LineSpec triples; for example,
semilogx(X1,Y1,X2,Y2,LineSpec,X3,Y3)
Examples
Create a simple semilogy plot.
x = 0:.1:10; semilogy(x,10.^x)
10
10
10
9
10
8
10
7
10
6
10
5
10
4
10
3
10
2
10
1
10
0
0
1
2
3
4
5
6
7
8
9
10
See Also
line, LineSpec, loglog, plot
"Basic Plots and Graphs" for related functions
2-313
send (COM)
Purpose
2send (COM)
Return a list of events that the control can trigger
Note Support for send will be removed in a future release of MATLAB. Use the events function instead of send.
2-314
sendmail
Purpose Syntax Description
2sendmail
Send e-mail message (attachments optional) to list of addresses
sendmail('recipients','subject','message','attachments') sendmail('recipients','subject','message','attachments') sends message to recipients with the specified subject. For recipients, use a
string for a single address, or a cell array of strings for multiple addresses. Optionally specify attachments as a cell array of files to send along with message. If MATLAB cannot read the SMTP mail server from your system registry, you get an error. You need to identify the outgoing SMTP mail server for your electronic mail application, which is usually listed in preferences. Or, consult your e-mail system administrator. Then provide the information to MATLAB using
setpref('Internet','SMTP_Server','myserver.myhost.com');
Examples
Sample message:
sendmail('user@otherdomain.com','Test subject','Test message', {'directory/attach1.html','attach2.doc'});
2-315
serial
Purpose Syntax Arguments
2serial
Create a serial port object
obj = serial('port') obj = serial('port','PropertyName',PropertyValue,...) 'port' 'PropertyName' PropertyValue obj
The serial port name. A serial port property name. A property value supported by PropertyName. The serial port object.
Description
obj = serial('port') creates a serial port object associated with the serial port specified by port. If port does not exist, or if it is in use, you will not be
able to connect the serial port object to the device.
obj = serial('port','PropertyName',PropertyValue,...) creates a serial
port object with the specified property names and property values. If an invalid property name or property value is specified, an error is returned and the serial port object is not created.
Remarks
When you create a serial port object, these property values are automatically configured: The Type property is given by serial. The Name property is given by concatenating Serial with the port specified in the serial function. The Port property is given by the port specified in the serial function. You can specify the property names and property values using any format supported by the set function. For example, you can use property name/property value cell array pairs. Additionally, you can specify property names without regard to case, and you can make use of property name completion. For example, the following commands are all valid.
s = serial('COM1','BaudRate',4800); s = serial('COM1','baudrate',4800); s = serial('COM1','BAUD',4800);
2-316
serial
Refer to "Configuring Property Values" for a list of serial port object properties that you can use with serial. Before you can communicate with the device, it must be connected to obj with the fopen function. A connected serial port object has a Status property value of open. An error is returned if you attempt a read or write operation while the object is not connected to the device. You can connect only one serial port object to a given serial port.
Example
This example creates the serial port object s1 associated with the serial port COM1.
s1 = serial('COM1');
The Type, Name, and Port properties are automatically configured.
get(s1,{'Type','Name','Port'}) ans = 'serial' 'Serial-COM1'
'COM1'
To specify properties during object creation
s2 = serial('COM2','BaudRate',1200,'DataBits',7);
See Also
Functions
fclose, fopen
Properties
Name, Port, Status, Type
2-317
serialbreak
Purpose Syntax Arguments
2serialbreak
Send a break to the device connected to the serial port
serialbreak(obj) serialbreak(obj,time) obj time
A serial port object. The duration of the break, in milliseconds.
Description
serialbreak(obj) sends a break of 10 milliseconds to the device connected to obj. serialbreak(obj,time) sends a break to the device with a duration, in milliseconds, specified by time. Note that the duration of the break might be
inaccurate under some operating systems.
Remarks
For some devices, the break signal provides a way to clear the hardware buffer. Before you can send a break to the device, it must be connected to obj with the fopen function. A connected serial port object has a Status property value of open. An error is returned if you attempt to send a break while obj is not connected to the device.
serialbreak is a synchronous function, and blocks the command line until
execution is complete. If you issue serialbreak while data is being asynchronously written, an error is returned. In this case, you must call the stopasync function or wait for the write operation to complete.
See Also
Functions
fopen, stopasync
Properties
Status
2-318
set
Purpose Syntax
2set
Set object properties
set(H,'PropertyName',PropertyValue,...) set(H,a) set(H,pn,pv...) set(H,pn,<m-by-n cell array>) a= set(h) a= set(0,'Factory') a= set(0,'FactoryObjectTypePropertyName') a= set(h,'Default') a= set(h,'DefaultObjectTypePropertyName') <cell array> = set(h,'PropertyName') set(H,'PropertyName',PropertyValue,...) sets the named properties to the specified values on the object(s) identified by H. H can be a vector of handles, in which case set sets the properties' values for all the objects. set(H,a) sets the named properties to the specified values on the object(s) identified by H. a is a structure array whose field names are the object property
Description
names and whose field values are the values of the corresponding properties.
set(H,pn,pv,...) sets the named properties specified in the cell array pn to the corresponding value in the cell array pv for all objects identified in H. set(H,pn,<m-by-n cell array>) sets n property values on each of m graphics objects, where m = length(H) and n is equal to the number of property names contained in the cell array pn. This allows you to set a given group of properties
to different values on each object.
a = set(h) returns the user-settable properties and possible values for the object identified by h. a is a structure array whose field names are the object's
property names and whose field values are the possible values of the corresponding properties. If you do not specify an output argument, MATLAB displays the information on the screen. h must be scalar.
a = set(0,'Factory') returns the properties whose defaults are user settable for all objects and lists possible values for each property. a is a
structure array whose field names are the object's property names and whose field values are the possible values of the corresponding properties. If you do
2-319
set
not specify an output argument, MATLAB displays the information on the screen.
a = set(0,'FactoryObjectTypePropertyName') returns the possible values
of the named property for the specified object type, if the values are strings. The argument FactoryObjectTypePropertyName is the word Factory concatenated with the object type (e.g., axes) and the property name (e.g., CameraPosition).
a = set(h,'Default') returns the names of properties having default values set on the object identified by h. set also returns the possible values if they are strings. h must be scalar. a = set(h,'DefaultObjectTypePropertyName') returns the possible values
of the named property for the specified object type, if the values are strings. The argument DefaultObjectTypePropertyName is the word Default concatenated with the object type (e.g., axes) and the property name (e.g., CameraPosition). For example, DefaultAxesCameraPosition. h must be scalar.
pv = set(h,'PropertyName') returns the possible values for the named property. If the possible values are strings, set returns each in a cell of the cell array, pv. For other properties, set returns an empty cell array. If you do not
specify an output argument, MATLAB displays the information on the screen. h must be scalar.
Remarks Examples
You can use any combination of property name/property value pairs, structure arrays, and cell arrays in one call to set. Set the Color property of the current axes to blue.
set(gca,'Color','b')
Change all the lines in a plot to black.
plot(peaks) set(findobj('Type','line'),'Color','k')
You can define a group of properties in a structure to better organize your code. For example, these statements define a structure called active, which contains a set of property definitions used for the uicontrol objects in a
2-320
set
particular figure. When this figure becomes the current figure, MATLAB changes colors and enables the controls.
active.BackgroundColor = [.7 .7 .7]; active.Enable = 'on'; active.ForegroundColor = [0 0 0]; if gcf == control_fig_handle set(findobj(control_fig_handle,'Type','uicontrol'),active) end
You can use cell arrays to set properties to different values on each object. For example, these statements define a cell array to set three properties,
PropName(1) = {'BackgroundColor'}; PropName(2) = {'Enable'}; PropName(3) = {'ForegroundColor'};
These statements define a cell array containing three values for each of three objects (i.e., a 3-by-3 cell array).
PropVal(1,1) = {[.5 .5 .5]}; PropVal(1,2) = {'off'}; PropVal(1,3) = {[.9 .9 .9]}; PropVal(2,1) = {[1 0 0]}; PropVal(2,2) = {'on'}; PropVal(2,3) = {[1 1 1]}; PropVal(3,1) = {[.7 .7 .7]}; PropVal(3,2) = {'on'}; PropVal(3,3) = {[0 0 0]};
Now pass the arguments to set,
set(H,PropName,PropVal)
where length(H) = 3 and each element is the handle to a uicontrol.
See Also
findobj, gca, gcf, gco, gcbo, get
"Finding and Identifying Graphics Objects" for related functions
2-321
set (COM)
Purpose Syntax Arguments
2set (COM)
Set an interface property to a specific value
set(h, 'propertyname', value[, 'propertyname2', value2, ...]) h
Handle for a COM object previously returned from actxcontrol, actxserver, get, or invoke.
propertyname
A string that is the name of the property to be set.
value
The value to which the interface property is set.
Description
Set one or more properties of a COM object to the specified value(s). Each propertyname argument must be followed by a value argument. See "Converting Data" in the External Interfaces documentation for information on how MATLAB converts workspace matrices to COM data types.
Examples
Create an mwsamp control and use set to change the Label and Radius properties:
f = figure ('pos', [100 200 200 200]); h = actxcontrol ('mwsamp.mwsampctrl.1', [0 0 200 200], f); set(h, 'Label', 'Click to fire event', 'Radius', 40); invoke(h, 'Redraw');
See Also
get, inspect, isprop, addproperty, deleteproperty
2-322
set (serial)
Purpose Syntax
2set (serial)
Configure or display serial port object properties
set(obj) props = set(obj) set(obj,'PropertyName') props = set(obj,'PropertyName') set(obj,'PropertyName',PropertyValue,...) set(obj,PN,PV) set(obj,S) obj 'PropertyName' PropertyValue PN PV S props
Arguments
A serial port object or an array of serial port objects. A property name for obj. A property value supported by PropertyName. A cell array of property names. A cell array of property values. A structure with property names and property values. A structure array whose field names are the property names for obj, or cell array of possible values.
Description
set(obj) displays all configurable properties values for obj. If a property has
a finite list of possible string values, then these values are also displayed.
props = set(obj) returns all configurable properties and their possible values for obj to props. props is a structure whose field names are the property names of obj, and whose values are cell arrays of possible property values. If
the property does not have a finite set of possible values, then the cell array is empty.
set(obj,'PropertyName') displays the valid values for PropertyName if it
possesses a finite list of string values.
props = set(obj,'PropertyName') returns the valid values for PropertyName to props. props is a cell array of possible string values or an empty cell array if PropertyName does not have a finite list of possible values.
2-323
set (serial)
set(obj,'PropertyName',PropertyValue,...) configures multiple property
values with a single command.
set(obj,PN,PV) configures the properties specified in the cell array of strings PN to the corresponding values in the cell array PV. PN must be a vector. PV can be m-by-n where m is equal to the number of serial port objects in obj and n is equal to the length of PN. set(obj,S) configures the named properties to the specified values for obj. S
is a structure whose field names are serial port object properties, and whose field values are the values of the corresponding properties.
Remarks
Refer to "Configuring Property Values" for a list of serial port object properties that you can configure with set. You can use any combination of property name/property value pairs, structures, and cell arrays in one call to set. Additionally, you can specify a property name without regard to case, and you can make use of property name completion. For example, if s is a serial port object, then the following commands are all valid.
set(s,'BaudRate') set(s,'baudrate') set(s,'BAUD')
If you use the help command to display help for set, then you need to supply the pathname shown below.
help serial/set
Examples
This example illustrates some of the ways you can use set to configure or return property values for the serial port object s.
s = serial('COM1'); set(s,'BaudRate',9600,'Parity','even') set(s,{'StopBits','RecordName'},{2,'sydney.txt'}) set(s,'Parity') [ {none} | odd | even | mark | space ]
See Also
Functions
get
2-324
set (timer)
Purpose Syntax
2set (timer)
Configure or display timer object properties
set(obj) prop_struct = set(obj) set(obj,'PropertyName') prop_cell = set(obj,'PropertyName') set(obj,'PropertyName',PropertyValue,...) set(obj,S) set(obj,PN,PV) set(obj) displays property names and their possible values for all configurable properties of timer object obj. obj must be a single timer object. prop_struct=set(obj) returns the property names and their possible values for all configurable properties of timer object obj. obj must be a single timer object. The return value, prop_struct, is a structure whose field names are the property names of obj, and whose values are cell arrays of possible property
Description
values or empty cell arrays if the property does not have a finite set of possible string values.
set(obj,'PropertyName') displays the possible values for the specified property, PropertyName, of timer object obj. obj must be a single timer object. prop_cell=set(obj,'PropertyName') returns the possible values for the specified property, PropertyName, of timer object obj. obj must be a single timer object. The returned array, prop_cell, is a cell array of possible value strings or an empty cell array if the property does not have a finite set of possible string values. set(obj,'PropertyName',PropertyValue,...) configures the property, PropertyName, to the specified value, PropertyValue, for timer object obj. You
can specify multiple property name/property value pairs in a single statement. obj can be a single timer object or a vector of timer objects, in which case set configures the property values for all the timer objects specified.
set(obj,S) configures the properties of obj, with the values specified in S, where S is a structure whose field names are object property names.
2-325
set (timer)
set(obj,PN,PV) configures the properties specified in the cell array of strings, PN, to the corresponding values in the cell array PV, for the timer object obj. PN must be a vector. If obj is an array of timer objects, PV can be an M-by-N cell
array, where M is equal to the length of timer object array and N is equal to the length of PN. In this case, each timer object is updated with a different set of values for the list of property names contained in PN.
Note Param-value string pairs, structures, and param-value cell array pairs can be use in the same call to set.
Example
Create a timer object.
t = timer;
Display all configurable properties and their possible values.
set(t) BusyMode: [ {drop} | queue | error ] ErrorFcn ExecutionMode: [{singleShot}|fixedSpacing|fixedDelay|fixedRate] LastError: [ {none} | busy | callback ] Name Period StartDelay StartFcn StopFcn Tag TasksToExecute TimerFcn UserData
Retrieve the possible values of the ExecutionMode property.
set(t, 'ExecutionMode') ans = 'singleShot' 'fixedSpacing' 'fixedDelay'
2-326
set (timer)
'fixedRate'
Set the value of a specific timer object property.
set(t, 'ExecutionMode', 'FixedRate')
Set the values of several properties of the timer object.
set(t, 'TimerFcn', 'callbk', 'Period', 10)
Use a cell array to specify the names of the properties you want to set and another cell array to specify the values of these properties.
set(t, {'StartDelay', 'Period'}, {30, 30})
See Also
timer, get
2-327
setappdata
Purpose Syntax Description
2setappdata
Set application-defined data
setappdata(h,name,value) setappdata(h,name,value) sets application-defined data for the object with handle h. The application-defined data, which is created if it does not already exist, is assigned a name and a value. value can be type of data. getappdata, isappdata, rmappdata
See Also
2-328
setdiff
Purpose Syntax
2setdiff
Return the set difference of two vectors
c = setdiff(A,B) c = setdiff(A,B,'rows') [c,i] = setdiff(...) c = setdiff(A,B) returns the values in A that are not in B. The resulting vector is sorted is ascending order. In set theoretic terms, c = A - B. A and B
Description
can be cell arrays of strings.
c = setdiff(A,B,'rows') when A and B are matrices with the same number of columns returns the rows from A that are not in B. [c,i] = setdiff(...) also returns an index vector index such that c = a(i) or c = a(i,:).
Examples
A = magic(5); B = magic(4); [c,i] = setdiff(A(:),B(:)); c' = 17 18 19 20 i' = 1 10 14 18
21 19
22 23
23 2
24 6
25 15
See Also
intersect, ismember, issorted, setxor, union, unique
2-329
setfield
Purpose
2setfield
Set field of structure array
Note setfield is obsolete and will be removed in a future release. Please use dynamic field names instead.
Syntax Description
s = setfield(s,'field',v) s = setfield(s,{i,j},'field',{k},v) s = setfield(s,'field',v), where s is a 1-by-1 structure, sets the contents of the specified field to the value v. This is equivalent to the syntax s.field = v. s = setfield(s,{i,j},'field',{k},v) sets the contents of the specified field to the value v. This is equivalent to the syntax s(i,j).field(k) = v. All
subscripts must be passed as cell arrays--that is, they must be enclosed in curly braces (similar to{i,j} and {k} above). Pass field references as strings.
Examples
Given the structure
mystr(1,1).name mystr(1,1).ID = mystr(2,1).name mystr(2,1).ID = = 'alice'; 0; = 'gertrude'; 1;
You can change the name field of mystr(2,1) using
mystr = setfield(mystr,{2,1},'name','ted'); mystr(2,1).name ans = ted
The following example sets fields of a structure using setfield with variable and quoted field names and additional subscripting arguments.
class = 5; student = 'John_Doe'; grades_Doe = [85,89,76,93,85,91,68,84,95,73]; grades = [];
2-330
setfield
grades = setfield(grades,{class}, student, 'Math',{10,21:30},... grades_Doe);
You can check the outcome using the standard structure syntax.
grades(class).John_Doe.Math(10,21:30) ans = 85 89 76 93 85 91 68 84 95 73
See Also
fieldnames, isfield, orderfields, rmfield
2-331
setstr
Purpose Description
2setstr
Set string flag This MATLAB 4 function has been renamed char in MATLAB 5.
2-332
setxor
Purpose Syntax
2setxor
Set exclusive-or of two vectors
c = setxor(A,B) c = setxor(A,B,'rows') [c,ia,ib] = setxor(...) c = setxor(A,B) returns the values that are not in the intersection of A and B. The resulting vector is sorted. A and B can be cell arrays of strings. c = setxor(A,B,'rows') when A and B are matrices with the same number of columns returns the rows that are not in the intersection of A and B. [c,ia,ib] = setxor(...) also returns index vectors ia and ib such that c is a sorted combination of the elements c = a(ia) and c = b(ib) or, for row combinations, c = a(ia,:) and c = b(ib,:).
Description
Examples
a = [-1 0 1 Inf -Inf NaN]; b = [-2 pi 0 Inf]; c = setxor(a,b) c = -Inf -2.0000 -1.0000 1.0000 3.1416 NaN
See Also
intersect, ismember, issorted, setdiff, union, unique
2-333
shading
Purpose Syntax
2shading
Set color shading properties
shading flat shading faceted shading interp
Description
The shading function controls the color shading of surface and patch graphics objects.
shading flat each mesh line segment and face has a constant color
determined by the color value at the end point of the segment or the corner of the face that has the smallest index or indices.
shading faceted flat shading with superimposed black mesh lines. This is the
default shading mode.
shading interp varies the color in each line segment and face by interpolating
the colormap index or true color value across the line or face.
Examples
Compare a flat, faceted, and interpolated-shaded sphere.
subplot(3,1,1) sphere(16) axis square shading flat title('Flat Shading') subplot(3,1,2) sphere(16) axis square shading faceted title('Faceted Shading') subplot(3,1,3) sphere(16) axis square shading interp title('Interpolated Shading')
2-334
shading
Algorithm
shading sets the EdgeColor and FaceColor properties of all surface and patch graphics objects in the current axes. shading sets the appropriate values,
depending on whether the surface or patch objects represent meshes or solid surfaces.
2-335
shading
See Also
fill, fill3, hidden, mesh, patch, pcolor, surf
The EdgeColor and FaceColor properties for surface and patch graphics objects. "Color Operations" for related functions
2-336
shiftdim
Purpose Syntax Description
2shiftdim
Shift dimensions
B = shiftdim(X,n) [B,nshifts] = shiftdim(X) B = shiftdim(X,n) shifts the dimensions of X by n. When n is positive, shiftdim shifts the dimensions to the left and wraps the n leading dimensions to the end. When n is negative, shiftdim shifts the dimensions to the right and
pads with singletons.
[B,nshifts] = shiftdim(X) returns the array B with the same number of elements as X but with any leading singleton dimensions removed. A singleton dimension is any dimension for which size(A,dim) = 1. nshifts is the number
of dimensions that are removed. If X is a scalar, shiftdim has no effect.
Examples
The shiftdim command is handy for creating functions that, like sum or diff, work along the first nonsingleton dimension.
a = rand(1,1,3,1,2); [b,n] = shiftdim(a); % b is 3-by-1-by-2 and n is 2. c = shiftdim(b,-n); % c == a. d = shiftdim(a,3); % d is 1-by-2-by-1-by-1-by-3.
See Also
circshift, reshape, squeeze
2-337
shrinkfaces
Purpose Syntax
2shrinkfaces
Reduce the size of patch faces
shrinkfaces(p,sf) nfv = shrinkfaces(p,sf) nfv = shrinkfaces(fv,sf) shrinkfaces(p), shrinkfaces(fv) nfv = shrinkfaces(f,v,sf) [nf,nv] = shrinkfaces(...) shrinkfaces(p,sf) shrinks the area of the faces in patch p to shrink factor sf. A shrink factor of 0.6 shrinks each face to 60% of its original area. If the patch contains shared vertices, MATLAB creates nonshared vertices before performing the face-area reduction. nfv = shrinkfaces(p,sf) returns the face and vertex data in the struct nfv, but does not set the Faces and Vertices properties of patch p. nfv = shrinkfaces(fv,sf) uses the face and vertex data from the struct fv. shrinkfaces(p) and shrinkfaces(fv) (without specifying a shrink factor)
Description
assume a shrink factor of 0.3.
nfv = shrinkfaces(f,v,sf) uses the face and vertex data from the arrays f and v. [nf,nv] = shrinkfaces(...) returns the face and vertex data in two separate
arrays instead of a struct.
Examples
This example uses the flow data set, which represents the speed profile of a submerged jet within a infinite tank (type help flow for more information). Two isosurfaces provide a before and after view of the effects of shrinking the face size. First reducevolume samples the flow data at every other point and then isosurface generates the faces and vertices data. The patch command accepts the face/vertex struct and draws the first (p1) isosurface. Use the daspect, view, and axis commands to set up the view and then add a title.
2-338
shrinkfaces
The shrinkfaces command modifies the face/vertex data and passes it directly to patch.
[x,y,z,v] = flow; [x,y,z,v] = reducevolume(x,y,z,v,2); fv = isosurface(x,y,z,v,-3); p1 = patch(fv); set(p1,'FaceColor','red','EdgeColor',[.5,.5,.5]); daspect([1 1 1]); view(3); axis tight title('Original') figure p2 = patch(shrinkfaces(fv,.3)); set(p2,'FaceColor','red','EdgeColor',[.5,.5,.5]); daspect([1 1 1]); view(3); axis tight
2-339
shrinkfaces
title('After Shrinking')
Original
3 2 1 0 -1 -2 -3 3 2 1 0 -1 -2 -3 2 4 6 8
2-340
shrinkfaces
After Shrinking
2 1 0 -1 -2
2 1 0 -1 -2 2 4 6
8
See Also
isosurface, patch, reducevolume, daspect, view, axis
"Volume Visualization" for related functions
2-341
sign
Purpose Syntax Description
2sign
Signum function
Y = sign(X) Y = sign(X) returns an array Y the same size as X, where each element of Y is:
1 if the corresponding element of X is greater than zero 0 if the corresponding element of X equals zero -1 if the corresponding element of X is less than zero For nonzero complex X, sign(X) = X./abs(X).
See Also
abs, conj, imag, real
2-342
sin
Purpose Syntax Description
2sin
Sine
Y = sin(X)
The sin function operates element-wise on arrays. The function's domains and ranges include complex values. All angles are in radians.
Y = sin(X) returns the circular sine of the elements of X.
Examples
Graph the sine function over the domain x .
x = -pi:0.01:pi; plot(x,sin(x)), grid on
1 0.8 0.6 0.4 0.2 0 -0.2 -0.4 -0.6 -0.8 -1 -4 -3 -2 -1 0 1 2 3 4
The expression sin(pi) is not exactly zero, but rather a value the size of the floating-point accuracy eps, because pi is only a floating-point approximation to the exact value of .
2-343
sin
Definition
The sine can be defined as sin ( x + iy ) = sin ( x )cosh ( y ) + i cos ( x )sinh ( y ) e iz e iz sin ( z ) = ---------------------2i
Algorithm
sin uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see http://www.netlib.org.
See Also
asin, asinh, sinh
2-344
single
Purpose Syntax Description
2single
Convert to single-precision
B = single(A) B = single(A) converts the matrix A to single-precision, returning that value in B. A can be any numeric object (such as a double). If A is already single-precision, single has no effect. Single-precision quantities require less
storage than double-precision quantities, but have less precision and a smaller range. The single class is primarily meant to be used to store single-precision values. Hence most operations that manipulate arrays without changing their elements are defined. Examples are reshape, size, the relational operators, subscripted assignment and subscripted reference. No math operations are defined for single objects. You can define your own methods for the single class by placing the appropriately named method in an @single directory within a directory on your path.
Examples
a = magic(4); b = single(a); whos Name a b
Size 4x4 4x4
Bytes 128 64
Class double array single array
See Also
double
2-345
sinh
Purpose Syntax Description
2 sinh
Hyperbolic sine
Y = sinh(X)
The sinh function operates element-wise on arrays. The function's domains and ranges include complex values. All angles are in radians.
Y = sinh(X) returns the hyperbolic sine of the elements of X.
Examples
Graph the hyperbolic sine function over the domain 5 x 5 .
x = -5:0.01:5; plot(x,sinh(x)), grid on
80 60 40 20 0 -20 -40 -60 -80 -5
0
5
Definition
The hyperbolic sine can be defined as e z ez sinh ( z ) = -----------------2
Algorithm
sinh uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see http://www.netlib.org.
2-346
sinh
See Also
asin, asinh, sin
2-347
size
Purpose Syntax
2size
Array dimensions
d = size(X) [m,n] = size(X) m = size(X,dim) [d1,d2,d3,...,dn] = size(X) d = size(X) returns the sizes of each dimension of array X in a vector d with ndims(X) elements. [m,n] = size(X) returns the size of matrix X in separate variables m and n. m = size(X,dim) returns the size of the dimension of X specified by scalar dim. [d1,d2,d3,...,dn] = size(X) returns the sizes of the first n dimensions of array X in separate variables.
Description
If the number of output arguments n does not equal ndims(X), then for:
n > ndims(X) n < ndims(X) size returns ones in the "extra" variables, i.e., outputs ndims(X)+1 through n. dn contains the product of the sizes of the remaining dimensions of X, i.e., dimensions n+1 through ndims(X).
Note For a Java array, size returns the length of the Java array as the number of rows. The number of columns is always 1. For a Java array of arrays, the result describes only the top level array.
Examples
Example 1. The size of the second dimension of rand(2,3,4) is 3.
m = size(rand(2,3,4),2) m = 3
Here the size is output as a single vector.
2-348
size
d = size(rand(2,3,4)) d = 2 3 4
Here the size of each dimension is assigned to a separate variable.
[m,n,p] = size(rand(2,3,4)) m = 2 n = 3 p = 4
Example 2. If X = ones(3,4,5), then
[d1,d2,d3] = size(X) d1 = 3 d2 = 4 d3 = 5
But when the number of output variables is less than ndims(X):
[d1,d2] = size(X) d1 = 3 d2 = 20
The "extra" dimensions are collapsed into a single product. If n > ndims(X), the "extra" variables all represent singleton dimensions:
[d1,d2,d3,d4,d5,d6] = size(X) d1 = 3 d4 = 1 d5 = 1 d2 = 4 d6 = 1 d3 = 5
2-349
size
See Also
exist, length, whos
2-350
size (serial)
Purpose Syntax
2size (serial)
Size of serial port object array
d = size(obj) [m,n] = size(obj) [m1,m2,...,mn] = size(obj) m = size(obj,dim) obj dim d m
Arguments
A serial port object or an array of serial port objects. The dimension of obj. The number of rows and columns in obj. The number of rows in obj, or the length of the dimension specified by dim. The number of columns in obj. The length of the first N dimensions of obj.
n m1,m2,...,m n
Description
d = size(obj) returns the two-element row vector d containing the number of rows and columns in obj. [m,n] = size(obj) returns the number of rows and columns in separate
output variables.
[m1,m2,m3,...,mn] = size(obj) returns the length of the first n dimensions of obj. m = size(obj,dim) returns the length of the dimension specified by the scalar dim. For example, size(obj,1) returns the number of rows.
See Also
Functions
length
2-351
slice
Purpose Syntax
2slice
Volumetric slice plot
slice(V,sx,sy,sz) slice(X,Y,Z,V,sx,sy,sz) slice(V,XI,YI,ZI) slice(X,Y,Z,V,XI,YI,ZI) slice(...,'method') h = slice(...) slice displays orthogonal slice planes through volumetric data. slice(V,sx,sy,sz) draws slices along the x, y, z directions in the volume V at the points in the vectors sx, sy, and sz. V is an m-by-n-by-p volume array containing data values at the default location X = 1:n, Y = 1:m, Z = 1:p. Each element in the vectors sx, sy, and sz defines a slice plane in the x-, y-, or z-axis
Description
direction.
slice(X,Y,Z,V,sx,sy,sz) draws slices of the volume V. X, Y, and Z are three-dimensional arrays specifying the coordinates for V. X, Y, and Z must be monotonic and orthogonally spaced (as if produced by the function meshgrid). The color at each point is determined by 3-D interpolation into the volume V. slice(V,XI,YI,ZI) draws data in the volume V for the slices defined by XI, YI, and ZI. XI, YI, and ZI are matrices that define a surface, and the volume is evaluated at the surface points. XI, YI, and ZI must all be the same size. slice(X,Y,Z,V,XI,YI,ZI) draws slices through the volume V along the surface defined by the arrays XI, YI, ZI. slice(...,'method') specifies the interpolation method. 'method' is 'linear', 'cubic', or 'nearest'.
linear specifies trilinear interpolation (the default). cubic specifies tricubic interpolation. nearest specifies nearest neighbor interpolation.
h = slice(...) returns a vector of handles to surface graphics objects.
2-352
slice
Remarks Examples
The color drawn at each point is determined by interpolation into the volume V. Visualize the function v = xe ( x
2
y2 z2 )
over the range 2 x 2, 2 y 2, 2 z 2:
[x,y,z] = meshgrid(-2:.2:2,-2:.25:2,-2:.16:2); v = x.*exp(-x.^2-y.^2-z.^2); xslice = [-1.2,.8,2]; yslice = 2; zslice = [-2,0]; slice(x,y,z,v,xslice,yslice,zslice) colormap hsv
2 1.5 1 0.5 0 -0.5 -1 -1.5 -2 2 1 0 1 -1 -2 -2 0 -1 2
z axis sliced at 0 and -2
y axis sliced at 2
x axis sliced at -1.2, .8, and 2
Slicing At Arbitrary Angles
You can also create slices that are oriented in arbitrary planes. To do this, Create a slice surface in the domain of the volume (surf, linspace). Orient this surface with respect the the axes (rotate).
2-353
slice
Get the XData, YData, and ZData of the surface (get). Use this data to draw the slice plane within the volume. For example, these statements slice the volume in the first example with a rotated plane. Placing these commands within a for loop "passes" the plane through the volume along the z-axis.
for i = -2:.5:2 hsp = surf(linspace(-2,2,20),linspace(-2,2,20),zeros(20)+i); rotate(hsp,[1,-1,1],30) xd = get(hsp,'XData'); yd = get(hsp,'YData'); zd = get(hsp,'ZData'); delete(hsp) slice(x,y,z,v,[-2,2],2,-2) % Draw some volume boundaries hold on slice(x,y,z,v,xd,yd,zd) hold off axis tight view(-5,10) drawnow end
The following picture illustrates three positions of the same slice surface as it passes through the volume.
2-354
slice
2 1.5 1 0.5 0 -0.5 -1 -1.5 -2
2 0 -2 -2.5 -2 -1.5 -1 -0.5 0 0.5 1 1.5 2 2.5
Slicing with a Nonplanar Surface
You can slice the volume with any surface. This example probes the volume created in the previous example by passing a spherical slice surface through the volume.
[xsp,ysp,zsp] = sphere; slice(x,y,z,v,[-2,2],2,-2) % Draw some volume boundaries
for i = -3:.2:3 hsp = surface(xsp+i,ysp,zsp); rotate(hsp,[1 0 0],90) xd = get(hsp,'XData'); yd = get(hsp,'YData'); zd = get(hsp,'ZData'); delete(hsp) hold on hslicer = slice(x,y,z,v,xd,yd,zd); axis tight
2-355
slice
xlim([-3,3]) view(-10,35) drawnow delete(hslicer) hold off end
The following picture illustrates three positions of the spherical slice surface as it passes through the volume.
2 1.5 1 0.5 0 -0.5 -1 -1.5 -2 2 1 0 -1 -2 -3 0 1 2 3
-2
-1
See Also
interp3, meshgrid
"Volume Visualization" for related functions Exploring Volumes with Slice Planes for more examples.
2-356
smooth3
Purpose Syntax
2smooth3
Smooth 3-D data
W W W W = = = = smooth3(V) smooth3(V,'filter') smooth3(V,'filter',size) smooth3(V,'filter',size,sd)
Description
W = smooth3(V) smooths the input data V and returns the smoothed data in W. W = smooth3(V,'filter') filter determines the convolution kernel and can
be the strings: 'gaussian' 'box' (default)
W = smooth3(V,'filter',size) sets the size of the convolution kernel (default is [3 3 3]). If size is scalar, then size is interpreted as [size, size, size]. W = smooth3(V,'filter',size,sd) sets an attribute of the convolution kernel. When filter is gaussian, sd is the standard deviation (default is .65).
Examples
This example smooths some random 3-D data and then creates an isosurface with end caps.
rand('seed',0) data = rand(10,10,10); data = smooth3(data,'box',5); p1 = patch(isosurface(data,.5), ... 'FaceColor','blue','EdgeColor','none'); p2 = patch(isocaps(data,.5), ... 'FaceColor','interp','EdgeColor','none'); isonormals(data,p1) view(3); axis vis3d tight camlight; lighting phong
2-357
smooth3
See Also
isocaps, isonormals, isosurface, patch
"Volume Visualization" for related functions See Displaying an Isosurface for another example
2-358
sort
Purpose Syntax
2sort
Sort elements in ascending order
B = sort(A) B = sort(A,dim) [B,INDEX] = sort(A,...) B = sort(A) sorts the elements along different dimensions of an array, and
Description
arranges those elements in ascending order.
If A is a ... sort(A) ...
Vector Matrix Multidimensional array Cell array of strings
Sorts the elements of A in ascending order. Sorts each column of A in ascending order. Sorts A along the first non-singleton dimension, and returns an array of sorted vectors. Sorts the strings in ASCII dictionary order.
Real, complex, and string elements are permitted. For elements of A with identical values, the order of these elements is preserved in the sorted list. When A is complex, the elements are sorted by magnitude, i.e., abs(A), and where magnitudes are equal, further sorted by phase angle, i.e., angle(A), on the interval [ , ] . If A includes any NaN elements, sort places these at the end.
B = sort(A,dim) sorts the elements along the dimension of A specified by a scalar dim. If dim is a vector, sort works iteratively on the specified dimensions. Thus, sort(A,[1 2]) is equivalent to sort(sort(A,2),1). [B,IX] = sort(A,...) also returns an array of indices IX, where size(IX) == size(A). If A is a vector, B = A(IX). If A is an m-by-n matrix, then each column of IX is a permutation vector of the corresponding column of A,
such that
for j = 1:n B(:,j) = A(IX(:,j),j); end
2-359
sort
If A has repeated elements of equal value, the returned indices preserve the original ordering.
Examples
This example sorts a matrix A in each dimension, and then sorts it a third time, requesting an array of indices for the sorted result.
A = [ 3 7 5 0 4 2 ]; sort(A,1) ans = 0 3 sort(A,2) ans = 3 0 5 2 7 4 4 7 2 5
[B,IX] = sort(A,2) B = 3 0 IX = 1 1 3 3 2 2 5 2 7 4
See Also
max, mean, median, min, sortrows
2-360
sortrows
Purpose Syntax
2sortrows
Sort rows in ascending order
B = sortrows(A) B = sortrows(A,column) [B,index] = sortrows(A) B = sortrows(A) sorts the rows of A as a group in ascending order. Argument A must be either a matrix or a column vector.
Description
For strings, this is the familiar dictionary sort. When A is complex, the elements are sorted by magnitude, and, where magnitudes are equal, further sorted by phase angle on the interval [ , ] .
B = sortrows(A,column) sorts the matrix based on the columns specified in the vector column. For example, sortrows(A,[2 3]) sorts the rows of A by the
second column, and where these are equal, further sorts by the third column.
[B,index] = sortrows(A) also returns an index vector index.
If A is a column vector, then B = A(index). If A is an m-by-n matrix, then B = A(index,:).
Examples
Given the 5-by-5 string matrix,
A = ['one ';'two ';'three';'four ';'five '];
The commands B = sortrows(A) and C = sortrows(A,1) yield
B = five four one three two C = four five one two three
See Also
sort
2-361
sound
Purpose Syntax
2sound
Convert vector into sound
sound(y,Fs) sound(y) sound(y,Fs,bits) sound(y,Fs), sends the signal in vector y (with sample frequency Fs) to the speaker on PC and most UNIX platforms. Values in y are assumed to be in the
Description
range 1.0 y 1.0 . Values outside that range are clipped. Stereo sound is played on platforms that support it when y is an n-by-2 matrix.
Note The playback duration that results from setting Fs depends on the sound card you have installed. Most sound cards support sample frequencies of approximately 5-10kHz to 44.1KHz. Sample frequencies outside this range may produce unexpected results.
sound(y) plays the sound at the default sample rate or 8192 Hz. sound(y,Fs,bits) plays the sound using bits number of bits/sample, if possible. Most platforms support bits = 8 or bits = 16.
Remarks See Also
MATLAB supports all Windows-compatible sound devices.
auread, auwrite, soundsc, wavread, wavwrite
2-362
soundsc
Purpose Syntax
2soundsc
Scale data and play as sound
soundsc(y,Fs) soundsc(y) soundsc(y,Fs,bits) soundsc(y,...,slim) soundsc(y,Fs) sends the signal in vector y (with sample frequency Fs) to the speaker on PC and most UNIX platforms. The signal y is scaled to the range
Description
1.0 y 1.0 before it is played, resulting in a sound that is played as loud as possible without clipping.
Note The playback duration that results from setting Fs depends on the sound card you have installed. Most sound cards support sample frequencies of approximately 5-10kHz to 44.1KHz. Sample frequencies outside this range may produce unexpected results.
soundsc(y) plays the sound at the default sample rate or 8192 Hz. soundsc(y,Fs,bits) plays the sound using bits number of bits/sample if possible. Most platforms support bits = 8 or bits = 16. soundsc(y,...,slim) where slim = [slow shigh] maps the values in y between slow and shigh to the full sound range. The default value is slim = [min(y) max(y)].
Remarks See Also
MATLAB supports all Windows-compatible sound devices.
auread, auwrite, sound, wavread, wavwrite
2-363
spalloc
Purpose Syntax Description
2spalloc
Allocate space for sparse matrix
S = spalloc(m,n,nzmax) S = spalloc(m,n,nzmax) creates an all zero sparse matrix S of size m-by-n with room to hold nzmax nonzeros. The matrix can then be generated column
by column without requiring repeated storage allocation as the number of nonzeros grows.
spalloc(m,n,nzmax) is shorthand for sparse([],[],[],m,n,nzmax)
Examples
To generate efficiently a sparse matrix that has an average of at most three nonzero elements per column
S = spalloc(n,n,3*n); for j = 1:n S(:,j) = [zeros(n-3,1)' round(rand(3,1))']'; end
2-364
sparse
Purpose Syntax
2sparse
Create sparse matrix
S S S S S = = = = = sparse(A) sparse(i,j,s,m,n,nzmax) sparse(i,j,s,m,n) sparse(i,j,s) sparse(m,n)
Description
The sparse function generates matrices in the MATLAB sparse storage organization.
S = sparse(A) converts a full matrix to sparse form by squeezing out any zero elements. If S is already sparse, sparse(S) returns S. S = sparse(i,j,s,m,n,nzmax) uses vectors i, j, and s to generate an m-by-n sparse matrix such that S(i(k),j(k)) = s(k), with space allocated for nzmax nonzeros. Vectors i, j, and s are all the same length. Any elements of s that are zero are ignored, along with the corresponding values of i and j. Any elements of s that have duplicate values of i and j are added together.
Note If any value in i or j is larger than the maximum integer size, 2^31-1, then the sparse matrix cannot be constructed.
To simplify this six-argument call, you can pass scalars for the argument s and one of the arguments i or j--in which case they are expanded so that i, j, and s all have the same length.
S = sparse(i,j,s,m,n) uses nzmax = length(s). S = sparse(i,j,s) uses m = max(i) and n = max(j). The maxima are computed before any zeros in s are removed, so one of the rows of [i j s] might be [m n 0]. S = sparse(m,n) abbreviates sparse([],[],[],m,n,0). This generates the ultimate sparse matrix, an m-by-n all zero matrix.
2-365
sparse
Remarks
All of the MATLAB built-in arithmetic, logical, and indexing operations can be applied to sparse matrices, or to mixtures of sparse and full matrices. Operations on sparse matrices return sparse matrices and operations on full matrices return full matrices. In most cases, operations on mixtures of sparse and full matrices return full matrices. The exceptions include situations where the result of a mixed operation is structurally sparse, for example, A.*S is at least as sparse as S.
Examples
S = sparse(1:n,1:n,1) generates a sparse representation of the n-by-n identity matrix. The same S results from S = sparse(eye(n,n)), but this would also temporarily generate a full n-by-n matrix with most of its elements
equal to zero.
B = sparse(10000,10000,pi) is probably not very useful, but is legal and works; it sets up a 10000-by-10000 matrix with only one nonzero element. Don't try full(B); it requires 800 megabytes of storage.
This dissects and then reassembles a sparse matrix:
[i,j,s] = find(S); [m,n] = size(S); S = sparse(i,j,s,m,n);
So does this, if the last row and column have nonzero entries:
[i,j,s] = find(S); S = sparse(i,j,s);
See Also
diag, find, full, nnz, nonzeros, nzmax, spones, sprandn, sprandsym, spy
The sparfun directory
2-366
spaugment
Purpose Syntax Description
2spaugment
Form least squares augmented system
S = spaugment(A,c) S = spaugment(A,c) creates the sparse, square, symmetric indefinite matrix S = [c*I A; A' 0]. The matrix S is related to the least squares problem min norm(b - A*x)
by
r = b - A*x S * [r/c; x] = [b; 0]
The optimum value of the residual scaling factor c, involves min(svd(A)) and norm(r), which are usually too expensive to compute.
S = spaugment(A) without a specified value of c, uses max(max(abs(A)))/1000.
Note In previous versions of MATLAB, the augmented matrix was used by sparse linear equation solvers, \ and /, for nonsquare problems. Now, MATLAB performs a least squares solve using the qr factorization of A instead.
See Also
spparms
2-367
spconvert
Purpose Syntax Description
2spconvert
Import matrix from sparse matrix external format
S = spconvert(D) spconvert is used to create sparse matrices from a simple sparse format easily produced by non-MATLAB sparse programs. spconvert is the second step in
the process:
1 Load an ASCII data file containing [i,j,v] or [i,j,re,im] as rows into a
MATLAB variable.
2 Convert that variable into a MATLAB sparse matrix.
S = spconvert(D) converts a matrix D with rows containing [i,j,s] or [i,j,r,s] to the corresponding sparse matrix. D must have an nnz or nnz+1
row and three or four columns. Three elements per row generate a real matrix and four elements per row generate a complex matrix. A row of the form [m n 0] or [m n 0 0] anywhere in D can be used to specify size(S). If D is already sparse, no conversion is done, so spconvert can be used after D is loaded from either a MAT-file or an ASCII file.
Examples
Suppose the ASCII file uphill.dat contains
1 1 2 1 2 3 1 2 3 4 4 1 2 2 3 3 3 4 4 4 4 4 1.000000000000000 0.500000000000000 0.333333333333333 0.333333333333333 0.250000000000000 0.200000000000000 0.250000000000000 0.200000000000000 0.166666666666667 0.142857142857143 0.000000000000000
Then the statements
load uphill.dat H = spconvert(uphill)
2-368
spconvert
H = (1,1) (1,2) (2,2) (1,3) (2,3) (3,3) (1,4) (2,4) (3,4) (4,4) 1.0000 0.5000 0.3333 0.3333 0.2500 0.2000 0.2500 0.2000 0.1667 0.1429
recreate sparse(triu(hilb(4))), possibly with roundoff errors. In this case, the last line of the input file is not necessary because the earlier lines already specify that the matrix is at least 4-by-4.
2-369
spdiags
Purpose Syntax
2spdiags
Extract and create sparse band and diagonal matrices
[B,d] = spdiags(A) B = spdiags(A,d) A = spdiags(B,d,A) A = spdiags(B,d,m,n)
Description
The spdiags function generalizes the function diag. Four different operations, distinguished by the number of input arguments, are possible:
[B,d] = spdiags(A) extracts all nonzero diagonals from the m-by-n matrix A. B is a min(m,n)-by-p matrix whose columns are the p nonzero diagonals of A. d is a vector of length p whose integer components specify the diagonals in A. B = spdiags(A,d) extracts the diagonals specified by d. A = spdiags(B,d,A) replaces the diagonals specified by d with the columns of B. The output is sparse. A = spdiags(B,d,m,n) creates an m-by-n sparse matrix by taking the columns of B and placing them along the diagonals specified by d.
Note If a column of B is longer than the diagonal it's replacing, spdiags takes elements of super-diagonals from the lower part of the column of B, and elements of sub-diagonals from the upper part of the column of B.
Arguments
The spdiags function deals with three matrices, in various combinations, as both input and output.
A B d
An m-by-n matrix, usually (but not necessarily) sparse, with its nonzero or specified elements located on p diagonals. A min(m,n)-by-p matrix, usually (but not necessarily) full, whose columns are the diagonals of A. A vector of length p whose integer components specify the diagonals in A.
2-370
spdiags
Roughly, A, B, and d are related by
for k = 1:p B(:,k) = diag(A,d(k)) end
Some elements of B, corresponding to positions outside of A, are not defined by these loops. They are not referenced when B is input and are set to zero when B is output.
Examples
Example 1. This example generates a sparse tridiagonal representation of the
classic second difference operator on n points.
e = ones(n,1); A = spdiags([e -2*e e], -1:1, n, n)
Turn it into Wilkinson's test matrix (see gallery):
A = spdiags(abs(-(n-1)/2:(n-1)/2)',0,A)
Finally, recover the three diagonals:
B = spdiags(A)
Example 2. The second example is not square.
A = [11 0 0 41 0 0 0 0 22 0 0 52 0 0 13 0 33 0 0 63 0 0 24 0 44 0 0 74]
Here m = 7, n = 4, and p = 3. The statement [B,d] = spdiags(A) produces d = [-3 0 2]' and
B = [41 52 63 74 11 22 33 44 0 0 13 24]
2-371
spdiags
Conversely, with the above B and d, the expression spdiags(B,d,7,4) reproduces the original A.
Example 3. This example shows how spdiags creates the diagonals when the
columns of B are longer than the diagonals they are replacing.
B = repmat((1:6)',[1 7]) B = 1 2 3 4 5 6 1 2 3 4 5 6 1 2 3 4 5 6 1 2 3 4 5 6 1 2 3 4 5 6 1 2 3 4 5 6 1 2 3 4 5 6
d = [-4 -2 -1 0 3 4 5]; A = spdiags(B,d,6,6); full(A) ans = 1 1 1 0 1 0 0 2 2 2 0 2 0 0 3 3 3 0 4 0 0 4 4 4 5 5 0 0 5 5 6 6 6 0 0 6
See Also
diag
2-372
speye
Purpose Syntax Description
2speye
Sparse identity matrix
S = speye(m,n) S = speye(n) S = speye(m,n) forms an m-by-n sparse matrix with 1s on the main diagonal. S = speye(n) abbreviates speye(n,n).
Examples
I = speye(1000) forms the sparse representation of the 1000-by-1000 identity
matrix, which requires only about 16 kilobytes of storage. This is the same final result as I = sparse(eye(1000,1000)), but the latter requires eight megabytes for temporary storage for the full representation.
See Also
spalloc, spones, spdiags, sprand, sprandn
2-373
spfun
Purpose Syntax Description
2spfun
Apply function to nonzero sparse matrix elements
f = spfun(fun,S)
The spfun function selectively applies a function to only the nonzero elements of a sparse matrix S, preserving the sparsity pattern of the original matrix (except for underflow or if fun returns zero for some nonzero elements of S).
f = spfun(fun,S) evaluates fun(S) on the nonzero elements of S. You can specify fun as a function handle or as an inline object.
Remarks Examples
Functions that operate element-by-element, like those in the elfun directory, are the most appropriate functions to use with spfun. Given the 4-by-4 sparse diagonal matrix
S = spdiags([1:4]',0,4,4) S = (1,1) (2,2) (3,3) (4,4) 1 2 3 4
Because fun returns nonzero values for all nonzero element of S, f = spfun(@exp,S) has the same sparsity pattern as S.
f = (1,1) (2,2) (3,3) (4,4) 2.7183 7.3891 20.0855 54.5982
whereas exp(S) has 1s where S has 0s.
full(exp(S)) ans = 2.7183 1.0000
1.0000 7.3891
1.0000 1.0000
1.0000 1.0000
2-374
spfun
1.0000 1.0000
1.0000 1.0000
20.0855 1.0000
1.0000 54.5982
See Also
function handle (@), inline
2-375
sph2cart
Purpose Syntax Description
2sph2cart
Transform spherical coordinates to Cartesian
[x,y,z] = sph2cart(THETA,PHI,R) [x,y,z] = sph2cart(THETA,PHI,R) transforms the corresponding elements of spherical coordinate arrays to Cartesian, or xyz, coordinates. THETA, PHI, and R must all be the same size. THETA and PHI are angular displacements in
radians from the positive x-axis and from the x-y plane, respectively.
Algorithm
The mapping from spherical coordinates to three-dimensional Cartesian coordinates is
Z
P
r
phi
th eta
Y
x = r .* cos(phi) .* cos(theta) y = r .* cos(phi) .* sin(theta) z = r .* sin(phi)
X
See Also
cart2pol, cart2sph, pol2cart
2-376
sphere
Purpose Syntax
2sphere
Generate sphere
sphere sphere(n) [X,Y,Z] = sphere(...)
Description
The sphere function generates the x-, y-, and z-coordinates of a unit sphere for use with surf and mesh.
sphere generates a sphere consisting of 20-by-20 faces. sphere(n) draws a surf plot of an n-by-n sphere in the current figure. [X,Y,Z] = sphere(n) returns the coordinates of a sphere in three matrices that are (n+1)by(n+1) in size. You draw the sphere with surf(X,Y,Z) or mesh(X,Y,Z).
Examples
Generate and plot a sphere.
sphere axis equal
1
0.5
0
-0.5
-1 1 0.5 0 0 -0.5 -1 -1 -0.5 0.5 1
2-377
sphere
See Also
cylinder, axis equal
"Polygons and Surfaces" for related functions
2-378
spinmap
Purpose Syntax
2spinmap
Spin colormap
spinmap spinmap(t) spinmap(t,inc) spinmap('inf')
Description
The spinmap function shifts the colormap RGB values by some incremental value. For example, if the increment equals 1, color 1 becomes color 2, color 2 becomes color 3, etc.
spinmap cyclically rotates the colormap for approximately five seconds using
an incremental value of 2.
spinmap(t) rotates the colormap for approximately 10*t seconds. The amount of time specified by t depends on your hardware configuration (e.g., if you are
running MATLAB over a network).
spinmap(t,inc) rotates the colormap for approximately 10*t seconds and specifies an increment inc by which the colormap shifts. When inc is 1, the
rotation appears smoother than the default (i.e., 2). Increments greater than 2 are less smooth than the default. A negative increment (e.g., 2) rotates the colormap in a negative direction.
spinmap('inf') rotates the colormap for an infinite amount of time. To break
the loop, press Ctrl-C.
See Also
colormap, colormapeditor
"Color Operations" for related functions
2-379
spline
Purpose Syntax Description
2spline
Cubic spline data interpolation
yy = spline(x,y,xx) pp = spline(x,y) yy = spline(x,y,xx) uses cubic spline interpolation to find yy, the values of the underlying function y at the points in the vector xx. The vector x specifies the points at which the data y is given. If y is a matrix, then the data is taken to be vector-valued and interpolation is performed for each row of y. For this case, length(x) must equal size(y,2), and yy is size(y,1)-by-length(xx).
Note This is the opposite of the interp1(x,y,xx,'spline') function which performs the interpolation for each column of matrix y. For this function, length(x) must equal size(y,1), and the resulting yy is length(xx)-by-size(y,2).
pp = spline(x,y) returns the piecewise polynomial form of the cubic spline interpolant for later use with ppval and the spline utility unmkpp.
Ordinarily, the not-a-knot end conditions are used. However, if y contains two more values than x has entries, then the first and last value in y are used as the endslopes for the cubic spline. Namely:
f(x) = y(:,2:end-1), df(min(x)) = y(:,1), df(max(x)) = y(:,end)
Examples
Example 1. This generates a sine curve, then samples the spline over a finer
mesh.
x = 0:10; y = sin(x); xx = 0:.25:10; yy = spline(x,y,xx); plot(x,y,'o',xx,yy)
2-380
spline
1
0.8
0.6
0.4
0.2
0
-0.2
-0.4
-0.6
-0.8
-1
0
1
2
3
4
5
6
7
8
9
10
Example 2. This illustrates the use of clamped or complete spline interpolation
where end slopes are prescribed. Zero slopes at the ends of an interpolant to the values of a certain distribution are enforced.
x = -4:4; y = [0 .15 1.12 2.36 2.36 1.46 .49 .06 0]; cs = spline(x,[0 y 0]); xx = linspace(-4,4,101); plot(x,y,'o',xx,ppval(cs,xx),'-');
2-381
spline
3
2.5
2
1.5
1
0.5
0
-0.5 -4
-3
-2
-1
0
1
2
3
4
Example 3. The two vectors
t = 1900:10:1990; p = [ 75.995 91.972 150.697 179.323 105.711 203.212 123.203 226.505 131.669 ... 249.633 ];
represent the census years from 1900 to 1990 and the corresponding United States population in millions of people. The expression
spline(t,p,2000)
uses the cubic spline to extrapolate and predict the population in the year 2000. The result is
ans = 270.6060
Example 4. The statements
x = pi*[0:.5:2]; y = [0 1 0 -1 0 1 0 1 0 -1 pp = spline(x,y); 1 0 0; 1];
2-382
spline
yy = ppval(pp, linspace(0,2*pi,101)); plot(yy(1,:),yy(2,:),'-b',y(1,2:5),y(2,2:5),'or'), axis equal
generate the plot of a circle, with the five data points y(:,2),...,y(:,6) marked with o's. Note that this y contains two more values (i.e., two more columns) than does x, hence y(:,1) and y(:,end) are used as endslopes.
1
0.8
0.6
0.4
0.2
0
-0.2
-0.4
-0.6
-0.8
-1
-1
-0.5
0
0.5
1
Algorithm
A tridiagonal linear system (with, possibly, several right sides) is being solved for the information needed to describe the coefficients of the various cubic polynomials which make up the interpolating spline. spline uses the functions ppval, mkpp, and unmkpp. These routines form a small suite of functions for working with piecewise polynomials. For access to more advanced features, see the M-file help for these functions and the Spline Toolbox.
interp1, ppval, mkpp, unmkpp
See Also References
[1] de Boor, C., A Practical Guide to Splines, Springer-Verlag, 1978.
2-383
spones
Purpose Syntax Description Examples
2spones
Replace nonzero sparse matrix elements with ones
R = spones(S) R = spones(S) generates a matrix R with the same sparsity structure as S, but with 1's in the nonzero positions. c = sum(spones(S)) is the number of nonzeros in each column. r = sum(spones(S'))' is the number of nonzeros in each row. sum(c) and sum(r) are equal, and are equal to nnz(S).
See Also
nnz, spalloc, spfun
2-384
spparms
Purpose Syntax
2spparms
Set parameters for sparse matrix routines
spparms('key',value) spparms values = spparms [keys,values] = spparms spparms(values) value = spparms('key') spparms('default') spparms('tight') spparms('key',value) sets one or more of the tunable parameters used in the sparse routines, particularly the minimum degree orderings, colmmd and symmmd. In ordinary use, you should never need to deal with this function.
Description
The meanings of the key parameters are
'spumoni'
Sparse Monitor flag:
0 1 2
Produces no diagnostic output, the default Produces information about choice of algorithm based on matrix structure, and about storage allocation Also produces very detailed information about the sparse matrix algorithms
'thr_rel', 'thr_abs' 'exact_d' 'supernd' 'rreduce' 'wh_frac' 'autommd'
Minimum degree threshold is
thr_rel*mindegree + thr_abs.
Nonzero to use exact degrees in minimum degree. Zero to use approximate degrees. If positive, minimum degree amalgamates the supernodes every supernd stages. If positive, minimum degree does row reduction every rreduce stages. Rows with density > wh_frac are ignored in colmmd. Nonzero to use minimum degree (MMD) orderings with Cholesky- and QR-based \ and /.
2-385
spparms
'autoamd' 'piv_tol' 'bandden'
Nonzero to use colamd ordering with the UMFPACK LU-based \ and /. Pivot tolerance used by the UMFPACK LU-based \ and /. Band density used by LAPACK-based \ and / for banded matrices. Band density is defined as (# nonzeros in the band)/(# nonzeros in a full band). If bandden = 1.0, never use band solver. If bandden = 0.0, always use band solver. Default is 0.5.
Note Cholesky-based \ and / on symmetric positive definite matrices use symmmd. LU-based \ and / (UMFPACK) on square matrices use a modified colamd. QR-based \ and / on rectangular matrices use colmmd.
spparms, by itself, prints a description of the current settings. values = spparms returns a vector whose components give the current
settings.
[keys,values] = spparms returns that vector, and also returns a character
matrix whose rows are the keywords for the parameters.
spparms(values), with no output argument, sets all the parameters to the
values specified by the argument vector.
value = spparms('key') returns the current setting of one parameter. spparms('default') sets all the parameters to their default settings. spparms('tight') sets the minimum degree ordering parameters to their
tight settings, which can lead to orderings with less fill-in, but which make the ordering functions themselves use more execution time. The key parameters for default and tight settings are
2-386
spparms
Keyword values(1) values(2) values(3) values(4) values(5) values(6) values(7) values(8) values(9) values(10) values(11) 'spumoni' 'thr_rel' 'thr_abs' 'exact_d' 'supernd' 'rreduce' 'wh_frac' 'autommd' 'autoamd' 'piv_tol' 'bandden'
Default
Tight
0.0 1.1 1.0 0.0 3.0 3.0 0.5 1.0 1.0 0.1 0.5 1.0 0.0 1.0 1.0 1.0 0.5
Notes
Sparse A\b on symmetric positive definite A uses symmmd and chol. Sparse A\b on general square A uses UMFPACK and its modified colamd reordering. colamd does not used the parameters above, other than 'autoamd' which turns the preordering on or off, and 'piv_tol' which controls the pivot tolerance. UMFPACK also responds to 'spumoni', as do the majority of the built-in sparse matrix functions.
See Also References
\, chol, colamd, colmmd, symmmd
[1] Gilbert, John R., Cleve Moler, and Robert Schreiber, "Sparse Matrices in MATLAB: Design and Implementation," SIAM Journal on Matrix Analysis and Applications, Vol. 13, 1992, pp. 333-356. [2] Davis, T. A., UMFPACK Version 4.0 User Guide (http://www.cise.ufl.edu/research/sparse/umfpack/v4.0/UserGuide.pdf), Dept. of Computer and Information Science and Engineering, Univ. of Florida, Gainesville, FL, 2002.
2-387
sprand
Purpose Syntax
2sprand
Sparse uniformly distributed random matrix
R = sprand(S) R = sprand(m,n,density) R = sprand(m,n,density,rc) R = sprand(S) has the same sparsity structure as S, but uniformly distributed random entries. R = sprand(m,n,density) is a random, m-by-n, sparse matrix with approximately density*m*n uniformly distributed nonzero entries (0 <= density <= 1). R = sprand(m,n,density,rc) also has reciprocal condition number approximately equal to rc. R is constructed from a sum of matrices of rank one.
Description
If rc is a vector of length lr, where lr <= min(m,n), then R has rc as its first lr singular values, all others are zero. In this case, R is generated by random plane rotations applied to a diagonal matrix with the given singular values. It has a great deal of topological and algebraic structure.
See Also
sprandn, sprandsym
2-388
sprandn
Purpose Syntax
2sprandn
Sparse normally distributed random matrix
R = sprandn(S) R = sprandn(m,n,density) R = sprandn(m,n,density,rc) R = sprandn(S) has the same sparsity structure as S, but normally distributed random entries with mean 0 and variance 1. R = sprandn(m,n,density) is a random, m-by-n, sparse matrix with approximately density*m*n normally distributed nonzero entries (0 <= density <= 1). R = sprandn(m,n,density,rc) also has reciprocal condition number approximately equal to rc. R is constructed from a sum of matrices of rank one.
Description
If rc is a vector of length lr, where lr <= min(m,n), then R has rc as its first lr singular values, all others are zero. In this case, R is generated by random plane rotations applied to a diagonal matrix with the given singular values. It has a great deal of topological and algebraic structure.
See Also
sprand, sprandsym
2-389
sprandsym
Purpose Syntax
2sprandsym
Sparse symmetric random matrix
R R R R = = = = sprandsym(S) sprandsym(n,density) sprandsym(n,density,rc) sprandsym(n,density,rc,kind)
Description
R = sprandsym(S) returns a symmetric random matrix whose lower triangle and diagonal have the same structure as S. Its elements are normally distributed, with mean 0 and variance 1. R = sprandsym(n,density) returns a symmetric random, n-by-n, sparse matrix with approximately density*n*n nonzeros; each entry is the sum of one or more normally distributed random samples, and (0 <= density <= 1). R = sprandsym(n,density,rc) returns a matrix with a reciprocal condition number equal to rc. The distribution of entries is nonuniform; it is roughly
symmetric about 0; all are in [ 1, 1 ] . If rc is a vector of length n, then R has eigenvalues rc. Thus, if rc is a positive (nonnegative) vector then R is a positive definite matrix. In either case, R is generated by random Jacobi rotations applied to a diagonal matrix with the given eigenvalues or condition number. It has a great deal of topological and algebraic structure.
R = sprandsym(n,density,rc,kind) returns a positive definite matrix. Argument kind can be:
1 to generate R by random Jacobi rotation of a positive definite diagonal matrix. R has the desired condition number exactly. 2 to generate an R that is a shifted sum of outer products. R has the desired condition number only approximately, but has less structure. 3 to generate an R that has the same structure as the matrix S and approximate condition number 1/rc. density is ignored.
See Also
sprand, sprandn
2-390
sprank
Purpose Syntax Description
2sprank
Structural rank
r = sprank(A) r = sprank(A) is the structural rank of the sparse matrix A. Also known as
maximum traversal, maximum assignment, and size of a maximum matching in the bipartite graph of A. Always sprank(A) >= rank(full(A)), and in exact arithmetic sprank(A) == rank(full(sprandn(A))) with probability one.
Examples
A = [1 2
0 0
2 4
0 0 ];
A = sparse(A); sprank(A) ans = 2 rank(full(A)) ans = 1
See Also
dmperm
2-391
sprintf
Purpose Syntax Description
2sprintf
Write formatted data to a string
[s,errmsg] = sprintf(format,A,...) [s,errmsg] = sprintf(format,A,...) formats the data in matrix A (and in any additional matrix arguments) under control of the specified format string, and returns it in the MATLAB string variable s. The sprintf function returns an error message string errmsg if an error occurred. errmsg is an empty matrix
if no error occurred.
sprintf is the same as fprintf except that it returns the data in a MATLAB
string variable rather than writing it to a file.
Format String
The format argument is a string containing C language conversion specifications. A conversion specification controls the notation, alignment, significant digits, field width, and other aspects of output format. The format string can contain escape characters to represent non-printing characters such as newline characters and tabs. Conversion specifications begin with the % character and contain these optional and required elements: Flags (optional) Width and precision fields (optional) A subtype specifier (optional) Conversion character (required) You specify these elements in the following order:
Start of conversion specification Flags Field width Precision
%12.5e
Conversion character
2-392
sprintf
Flags
You can control the alignment of the output using any of these optional flags.
Character Description Example %5.2d
A minus sign () A plus sign (+) Zero (0)
Left-justifies the converted argument in its field. Always prints a sign character (+ or ). Pad with zeros rather than spaces.
%+5.2d %05.2d
Field Width and Precision Specifications
You can control the width and precision of the output by including these options in the format string.
Character Description Example %6f
Field width Precision
A digit string specifying the minimum number of digits to be printed. A digit string including a period (.) specifying the number of digits to be printed to the right of the decimal point.
%6.2f
Conversion Characters
Conversion characters specify the notation of the output.
Specifier %c %d %e Description
Single character Decimal notation (signed) Exponential notation (using a lowercase e as in 3.1415e+00) Exponential notation (using an uppercase E as in 3.1415E+00)
%E
2-393
sprintf
Specifier %f %g
Description
Fixed-point notation The more compact of %e or %f, as defined in [2]. Insignificant zeros do not print. Same as %g, but using an uppercase E Octal notation (unsigned) String of characters Decimal notation (unsigned) Hexadecimal notation (using lowercase letters af) Hexadecimal notation (using uppercase letters AF)
%G %o %s %u %x %X
The following tables describe the nonalphanumeric characters found in format specification strings.
Escape Characters
This table lists the escape character sequences you use to specify non-printing characters in a format specification.
Character \b \f \n \r \t \\ Description
Backspace Form feed New line Carriage return Horizontal tab Backslash
2-394
sprintf
Character
Description
\'' or '' (two single quotes)
%%
Single quotation mark
Percent character
Remarks
The sprintf function behaves like its ANSI C language namesake with these exceptions and extensions. If you use sprintf to convert a MATLAB double into an integer, and the double contains a value that cannot be represented as an integer (for example, it contains a fraction), MATLAB ignores the specified conversion and outputs the value in exponential format. To successfully perform this conversion, use the fix, floor, ceil, or round functions to change the value in the double into a value that can be represented as an integer before passing it to sprintf. The following, non-standard subtype specifiers are supported for the conversion characters %o, %u, %x, and %X.
b
The underlying C data type is a double rather than an unsigned integer. For example, to print a double-precision value in hexadecimal, use a format like '%bx'. The underlying C data type is a float rather than an unsigned integer.
t
For example, to print a double value in hexadecimal use the format '%bx' The sprintf function is vectorized for nonscalar arguments. The function recycles the format string through the elements of A (columnwise) until all the elements are used up. The function then continues in a similar manner through any additional matrix arguments. If %s is used to print part of a nonscalar double argument, the following behavior occurs:
a. Successive values are printed as long as they are integers and in the range
of a valid character. The first invalid character terminates the printing for
2-395
sprintf
this %s specifier and is used for a later specifier. For example, pi terminates the string below and is printed using %f format.
Str = [65 66 67 pi]; sprintf('%s %f', Str) ans = ABC 3.141593 b. If the first value to print is not a valid character, then just that value is printed for this %s specifier using an e conversion as a warning to the user. For example, pi is formatted by %s below in exponential notation, and 65, though representing a valid character, is formatted as fixed-point (%f). Str = [pi 65 66 67]; sprintf('%s %f %s', Str) ans = 3.141593e+000 65.000000 BC c. One exception is zero which is a valid character. If zero is found first, %s
prints nothing and the value is skipped. If zero is found after at least one valid character, it terminates the printing for this %s specifier and is used for a later specifier. sprintf prints negative zero and exponents differently on some platforms, as shown in the following tables.
Negative Zero Printed with %e, %E, %f, %g, or %G Display of Negative Zero Platform %e or %E %f %g or %G
PC SGI HP700 Others
0.000000e+000 0.000000e+00 -0.000000e+00 -0.000000e+00
0.000000 0.000000 -0.000000 -0.000000
0 0 0 -0
2-396
sprintf
Exponents Printed with %e, %E, %g, or %G Platform Minimum Digits in Exponent Example 1.23e+004 1.23e+04
PC UNIX
3 2
You can resolve this difference in exponents by post-processing the results of sprintf. For example, to make the PC output look like that of UNIX, use
a = sprintf('%e', 12345.678); if ispc, a = strrep(a, 'e+0', 'e+'); end
Examples
Command sprintf('%0.5g',(1+sqrt(5))/2) sprintf('%0.5g',1/eps) sprintf('%15.5f',1/eps) sprintf('%d',round(pi)) sprintf('%s','hello') sprintf('The array is %dx%d.',2,3) sprintf('\n') Result 1.618 4.5036e+15 4503599627370496.00000 3 hello The array is 2x3
Line termination character on all platforms
See Also References
int2str, num2str, sscanf
[1] Kernighan, B.W. and D.M. Ritchie, The C Programming Language, Second Edition, Prentice-Hall, Inc., 1988. [2] ANSI specification X3.159-1989: "Programming Language C," ANSI, 1430 Broadway, New York, NY 10018.
2-397
spy
Purpose Syntax
2spy
Visualize sparsity pattern
spy(S) spy(S,markersize) spy(S,'LineSpec') spy(S,'LineSpec',markersize) spy(S) plots the sparsity pattern of any matrix S. spy(S,markersize), where markersize is an integer, plots the sparsity
Description
pattern using markers of the specified point size.
spy(S,'LineSpec'), where LineSpec is a string, uses the specified plot marker
type and color.
spy(S,'LineSpec',markersize) uses the specified type, color, and size for the
plot markers.
S is usually a sparse matrix, but full matrices are acceptable, in which case the
locations of the nonzero elements are plotted.
Note spy replaces format +, which takes much more space to display essentially the same information.
Examples
This example plots the 60-by-60 sparse adjacency matrix of the connectivity graph of the Buckminster Fuller geodesic dome. This matrix also represents the soccer ball and the carbon-60 molecule.
B = bucky; spy(B)
2-398
spy
0
10
20
30
40
50
60 0
10
20
30 nz = 180
40
50
60
See Also
find, gplot, LineSpec, symamd, symmmd, symrcm
2-399
sqrt
Purpose Syntax Description Remarks Examples
2sqrt
Square root
B = sqrt(X) B = sqrt(X) returns the square root of each element of the array X. For the elements of X that are negative or complex, sqrt(X) produces complex results.
See sqrtm for the matrix square root.
sqrt((-2:2)') ans = 0 + 1.4142i 0 + 1.0000i 0 1.0000 1.4142 sqrtm
See Also
2-400
sqrtm
Purpose Syntax
2sqrtm
Matrix square root
X = sqrtm(A) [X,resnorm] = sqrtm(A) [X,alpha,condest] = sqrtm(A) X = sqrtm(A) is the principal square root of the matrix A, i.e. X*X = A. X is the unique square root for which every eigenvalue has nonnegative real part. If A has any eigenvalues with negative real parts then a complex result is produced. If A is singular then A may not have a square root. A warning is
Description
printed if exact singularity is detected.
[X, resnorm] = sqrtm(A) does not print any warning, and returns the residual, norm(A-X^2,'fro')/norm(A,'fro'). [X, alpha, condest] = sqrtm(A) returns a stability factor alpha and an estimate condest of the matrix square root condition number of X. The residual norm(A-X^2,'fro')/norm(A,'fro') is bounded approximately by n*alpha*eps and the Frobenius norm relative error in X is bounded approximately by n*alpha*condest*eps, where n = max(size(A)).
Remarks
If X is real, symmetric and positive definite, or complex, Hermitian and positive definite, then so is the computed matrix square root. Some matrices, like X = [0 1; 0 0], do not have any square roots, real or complex, and sqrtm cannot be expected to produce one.
Examples
Example 1. A matrix representation of the fourth difference operator is
X = 5 -4 1 0 0 -4 6 -4 1 0 1 -4 6 -4 1 0 1 -4 6 -4 0 0 1 -4 5
This matrix is symmetric and positive definite. Its unique positive definite square root, Y = sqrtm(X), is a representation of the second difference operator.
2-401
sqrtm
Y = 2 -1 0 -0 -0 -1 2 -1 0 -0 -0 -1 2 -1 -0 -0 0 -1 2 -1 -0 -0 0 -1 2
Example 2. The matrix
X = 7 15 10 22
has four square roots. Two of them are
Y1 = 1.5667 2.6112 1.7408 4.1779
and
Y2 = 1 3 2 4
The other two are -Y1 and -Y2. All four can be obtained from the eigenvalues and vectors of X.
[V,D] = eig(X); D = 0.1386 0 0 28.8614
The four square roots of the diagonal matrix D result from the four choices of sign in
S = 0.3723 0 0 5.3723
All four Ys are of the form
Y = V*S/V
2-402
sqrtm
The sqrtm function chooses the two plus signs and produces Y1, even though Y2 is more natural because its entries are integers.
See Also
expm, funm, logm
2-403
squeeze
Purpose Syntax Description
2squeeze
Remove singleton dimensions
B = squeeze(A) B = squeeze(A) returns an array B with the same elements as A, but with all
singleton dimensions removed. A singleton dimension is any dimension for which size(A,dim) = 1.
Examples
Consider the 2-by-1-by-3 array Y = rand(2,1,3). This array has a singleton column dimension -- that is, there's only one column per page.
Y = Y(:,:,1) = 0.5194 0.8310 Y(:,:,3) = 0.5297 0.6711 Y(:,:,2) = 0.0346 0.0535
The command Z = squeeze(Y) yields a 2-by-3 matrix:
Z = 0.5194 0.8310 0.0346 0.0535 0.5297 0.6711
See Also
reshape, shiftdim
2-404
sscanf
Purpose Syntax
2sscanf
Read string under format control
A = sscanf(s,format) A = sscanf(s,format,size) [A,count,errmsg,nextindex] = sscanf(...) A = sscanf(s,format) reads data from the MATLAB string variable s, converts it according to the specified format string, and returns it in matrix A. format is a string specifying the format of the data to be read. See "Remarks" for details. sscanf is the same as fscanf except that it reads the data from a
Description
MATLAB string variable rather than reading it from a file.
A = sscanf(s,format,size) reads the amount of data specified by size and converts it according to the specified format string. size is an argument that determines how much data is read. Valid options are
n inf
Read n elements into a column vector. Read to the end of the file, resulting in a column vector containing the same number of elements as are in the file. Read enough elements to fill an m-by-n matrix, filling the matrix in column order. n can be Inf, but not m.
[m,n]
If the matrix A results from using character conversions only and size is not of the form [M,N], a row vector is returned.
sscanf differs from its C language namesakes scanf() and fscanf() in an
important respect -- it is vectorized in order to return a matrix argument. The format string is cycled through the file until an end-of-file is reached or the amount of data specified by size is read in.
[A,count,errmsg,nextindex] = sscanf(...) reads data from the MATLAB string variable s, converts it according to the specified format string, and returns it in matrix A. count is an optional output argument that returns the number of elements successfully read. errmsg is an optional output argument
that returns an error message string if an error occurred or an empty matrix if an error did not occur. nextindex is an optional output argument specifying one more than the number of characters scanned in s.
2-405
sscanf
Remarks
When MATLAB reads a specified file, it attempts to match the data in the file to the format string. If a match occurs, the data is written into the matrix in column order. If a partial match occurs, only the matching data is written to the matrix, and the read operation stops. The format string consists of ordinary characters and/or conversion specifications. Conversion specifications indicate the type of data to be matched and involve the character %, optional width fields, and conversion characters, organized as shown below: %12.5e }
Initial % characte r Conversion character
Flag
Field width and precision
Add one or more of these characters between the % and the conversion character. An asterisk (*) A digit string A letter Skip over the matched value if the value is matched but not stored in the output matrix. Maximum field width. The size of the receiving object; for example, h for short as in %hd for a short integer, or l for long as in %ld for a long integer or %lg for a double floating-point number.
Valid conversion characters are as shown.
%c %d %e, %f, %g %i %o %s
Sequence of characters; number specified by field width Decimal numbers Floating-point numbers Signed integer Signed octal integer A series of non-whitespace characters
2-406
sscanf
%u %x [...]
Signed decimal integer Signed hexadecimal integer Sequence of characters (scanlist)
If %s is used, an element read may use several MATLAB matrix elements, each holding one character. Use %c to read space characters, or %s to skip all white space. Mixing character and numeric conversion specifications cause the resulting matrix to be numeric and any characters read to appear as their ASCII values, one character per MATLAB matrix element. For more information about format strings, refer to the scanf() and fscanf() routines in a C language reference manual.
Examples
The statements
s = '2.7183 3.1416'; A = sscanf(s,'%f')
create a two-element vector containing poor approximations to e and pi.
See Also
eval, sprintf, textread
2-407
stairs
Purpose Syntax
2stairs
Stairstep plot
stairs(Y) stairs(X,Y) stairs(...,LineSpec) [xb,yb] = stairs(Y) [xb,yb] = stairs(X,Y)
Description
Stairstep plots are useful for drawing time-history plots of digitally sampled data systems.
stairs(Y) draws a stairstep plot of the elements of Y. When Y is a vector, the x-axis scale ranges from 1 to size(Y). When Y is a matrix, the x-axis scale ranges from 1 to the number of rows in Y. stairs(X,Y) plots X versus the columns of Y. X and Y are vectors of the same size or matrices of the same size. Additionally, X can be a row or a column vector, and Y a matrix with length(X) rows. stairs(...,LineSpec) specifies a line style, marker symbol, and color for the plot (see LineSpec for more information). [xb,yb] = stairs(Y) and [xb,yb] = stairs(x,Y) do not draw graphs, but return vectors xb and yb such that plot(xb,yb) plots the stairstep graph.
Examples
Create a stairstep plot of a sine wave.
x = 0:.25:10; stairs(x,sin(x))
2-408
stairs
1 0.8 0.6 0.4 0.2 0 -0.2 -0.4 -0.6 -0.8 -1 0 2 4 6 8 10
See Also
bar, hist
"Discrete Data Plots" for related functions
2-409
start
Purpose Syntax Description
2start
Start timer(s) running
start(obj) start(obj) starts the timer running, represented by the timer object, obj. If obj is an array of timer objects, start starts all the timers. Use the timer
function to create a timer object.
start sets the Running property of the timer object, obj, to 'on', initiates TimerFcn callbacks, and executes the StartFcn callback.
The timer stops running if one of the following conditions apply: The number of TimerFcn callbacks specified in TasksToExecute have been executed. The stop(obj) command is issued. An error occurred while executing a TimerFcn callback.
See Also
timer, stop
2-410
startat
Purpose Syntax
2startat
Start timer(s) running at the specified time
startat(obj,time) startat(obj,S) startat(obj,S,pivotyear) startat(obj,Y,M,D) startat(obj,[Y,M,D]) startat(obj,Y,M,D,H,MI,S) startat(obj,[Y,M,D,H,MI,S]) startat(obj,time) starts the timer running, represented by the timer object obj, at the time specified by the serial date number time. If obj is an array of timer objects, startat starts all the timers running at the specified time. Use the timer function to create the timer object. startat sets the Running property of the timer object, obj, to 'on', initiates TimerFcn callbacks, and executes the StartFcn callback.
Description
The serial date number, time, indicates the number of days that have elapsed since 1-Jan-0000 (starting at 1). See datenum for additional information about serial date numbers.
startat(obj,S) starts the timer running at the time specified by the date string S. The date string must use date format 0, 1, 2, 6, 13, 14, 15, 16, or 23, as defined by the datestr function. Date strings with two-character years are
interpreted to be within the 100 years centered around the current year.
startat(obj,S,pivotyear) uses the specified pivot year as the starting year of the 100-year range in which a two-character year resides. The default pivot year is the current year minus 50 years. startat(obj,Y,M,D) startat(obj,[Y,M,D]) start the timer at the year (Y), month (M), and day (D) specified. Y, M, and D must be arrays of the same size (or they can be a scalar). startat(obj,Y,M,D,H,MI,S) startat(obj,[Y,M,D,H,MI,S]) start the timer at the year (Y), month (M), day(D), hour(H), minute(MI), and second(S) specified. Y, M, D, H, MI, and S must
be arrays of the same size (or they can be a scalar). Values outside the normal range of each array are automatically carried to the next unit (for example
2-411
startat
month values greater than 12 are carried to years). Month values less than 1 are set to be 1; all other units can wrap and have valid negative values. The timer stops running if one of the following conditions apply: The number of TimerFcn callbacks specified in TasksToExecute have been executed. The stop(obj) command is issued. An error occurred while executing a TimerFcn callback.
Example
This example uses a timer object to execute a function at a specified time.
t1=timer('TimerFcn','disp(''it is 10 o''''clock'')'); startat(t1,'10:00:00');
This example uses a timer to display a message when an hour has elapsed.
t2=timer('TimerFcn','disp(''It has been an hour now.'')'); startat(t2,now+1/24);
See Also
datenum, datestr, now, timer, start, stop
2-412
std
Purpose Syntax
2std
Standard deviation
s = std(X) s = std(X,flag) s = std(X,flag,dim)
Definition
There are two common textbook definitions for the standard deviation s of a data vector X. 1 n (1) s = -----------( x i x ) 2 n 1i = 1
1 -2
1 (2) s = -n where 1 x = -n
( xi
i=1
n
2 x )2
1 --
xi
i=1
n
and n is the number of elements in the sample. The two forms of the equation differ only in n 1 versus n in the divisor.
Description
s = std(X), where X is a vector, returns the standard deviation using (1) 2 above. If X is a random sample of data from a normal distribution, s is the best
unbiased estimate of its variance. If X is a matrix, std(X) returns a row vector containing the standard deviation of the elements of each column of X. If X is a multidimensional array, std(X) is the standard deviation of th elements along the first nonsingleton dimension of X.
s = std(X,flag) for flag = 0, is the same as std(X). For flag = 1, std(X,1)
returns the standard deviation using (2) above, producing the second moment of the sample about its mean.
2-413
std
s = std(X,flag,dim) computes the standard deviations along the dimension of X specified by scalar dim.
Examples
For matrix X
X = 1 7 5 15 9 22
s = std(X,0,1) s = 4.2426 7.0711 s = std(X,0,2) s = 4.000 7.5056
9.1924
See Also
corrcoef, cov, mean, median
2-414
stem
Purpose Syntax
2stem
Plot discrete sequence data
stem(Y) stem(X,Y) stem(...,'fill') stem(...,LineSpec) h = stem(...)
Description
A two-dimensional stem plot displays data as lines extending from a baseline along the x-axis. A circle (the default) or other marker whose y-position represents the data value terminates each stem.
stem(Y) plots the data sequence Y as stems that extend from equally spaced and automatically generated values along the x-axis. When Y is a matrix, stem
plots all elements in a row against the same x value.
stem(X,Y) plots X versus the columns of Y. X and Y are vectors or matrices of the same size. Additionally, X can be a row or a column vector and Y a matrix with length(X) rows. stem(...,'fill') specifies whether to color the circle at the end of the stem. stem(...,LineSpec) specifies the line style, marker symbol, and color for the stem and top marker (the base line is not affected). See LineSpec for more
information.
h = stem(...) returns handles to three line graphics objects:
h(1) the marker symbol at the top of each stem h(2) the stem line h(3) the base line
Examples
Create a stem plot of a circular function.
y = linspace(0,2*pi,10); h = stem(cos(y),'fill','-.'); set(h(3),'Color','r','LineWidth',2) % Set base line properties axis ([0 11 -1 1])
2-415
stem
1
0.8
0.6
0.4
0.2
0
-0.2
-0.4
-0.6
-0.8
-1
0
1
2
3
4
5
6
7
8
9
10
11
See Also
bar, plot, stairs, stem3
"Discrete Data Plots" for related functions. See Two Dimensional Stem Plots for more examples using the stem function.
2-416
stem3
Purpose Syntax
2stem3
Plot three-dimensional discrete sequence data
stem3(Z) stem3(X,Y,Z) stem3(...,'fill') stem3(...,LineSpec) h = stem3(...)
Description
Three-dimensional stem plots display lines extending from the xy-plane. A circle (the default) or other marker symbol whose z-position represents the data value terminates each stem.
stem3(Z) plots the data sequence Z as stems that extend from the xy-plane. x and y are generated automatically. When Z is a row vector, stem3 plots all elements at equally spaced x values against the same y value. When Z is a column vector, stem3 plots all elements at equally spaced y values against the
same x value.
stem3(X,Y,Z) plots the data sequence Z at values specified by X and Y. X, Y, and Z must all be vectors or matrices of the same size. stem3(...,'fill') specifies whether to color the interior of the circle at the
end of the stem.
stem3(...,LineSpec) specifies the line style, marker symbol, and color for the stems. See LineSpec for more information. h = stem3(...) returns handles to line graphics objects.
Examples
Create a three-dimensional stem plot to visualize a function of two variables.
X = linspace(0,1,10); Y = X./2; Z = sin(X) + cos(Y); stem3(X,Y,Z,'fill') view(-25,30)
2-417
stem3
:
2 1.5 1 0.5 0 0.5 0.4 0.3 0.2 0.1 0 0 0.2 0.4 0.6 0.8 1
See Also
bar, plot, stairs, stem
"Discrete Data Plots" for related functions See Three-Dimensional Stem Plots for more examples
2-418
stop
Purpose Syntax Description
2stop
Stop timer(s)
stop(obj) stop(obj) stops the timer, represented by the timer object, obj. If obj is an array of timer objects, the stop function stops them all. Use the timer function
to create a timer object. The stop function sets the Running property of the timer object, obj, to 'off', halts further TimerFcn callbacks, and executes the StopFcn callback.
See Also
timer, start
2-419
stopasync
Purpose Syntax Arguments Description Remarks
2stopasync
Stop asynchronous read and write operations
stopasync(obj) obj
A serial port object or an array of serial port objects.
stopasync(obj) stops any asynchronous read or write operation that is in progress for obj.
You can write data asynchronously using the fprintf or fwrite functions. You can read data asynchronously using the readasync function, or by configuring the ReadAsyncMode property to continuous. In-progress asynchronous operations are indicated by the TransferStatus property. If obj is an array of serial port objects and one of the objects cannot be stopped, the remaining objects in the array are stopped and a warning is returned. After an object stops: Its TransferStatus property is configured to idle. Its ReadAsyncMode property is configured to manual. The data in its output buffer is flushed. Data in the input buffer is not flushed. You can return this data to the MATLAB workspace using any of the synchronous read functions. If you execute the readasync function, or configure the ReadAsyncMode property to continuous, then the new data is appended to the existing data in the input buffer.
See Also
Functions
fprintf, fwrite, readasync
Properties
ReadAsyncMode, TransferStatus
2-420
str2double
Purpose Syntax Description
2str2double
Convert string to double-precision value
x = str2double('str') X = str2double(C) X = str2double('str') converts the string str, which should be an ASCII
character representation of a real or complex scalar value, to the MATLAB double-precision representation. The string may contain digits, a comma (thousands separator), a decimal point, a leading + or - sign, an e preceeding a power of 10 scale factor, and an i for a complex unit. If str does not represent a valid scalar value, str2double returns NaN.
X = str2double(C) converts the strings in the cell array of strings C to double-precision. The matrix X returned will be the same size as C.
Examples
Here are some valid str2double conversions.
str2double('123.45e7') str2double('123 + 45i') str2double('3.14159') str2double('2.7i - 3.14') str2double({'2.71' '3.1415'}) str2double('1,200.34')
See Also
char, hex2num, num2str, str2num
2-421
str2func
Purpose Syntax Description
2str2func
Constructs a function handle from a function name string
fhandle = str2func('str') str2func('str') constructs a function handle, fhandle, for the function named in the string, 'str'.
You can create a function handle using either the @function syntax or the str2func command. You can also perform this operation on a cell array of strings. In this case, an array of function handles is returned.
Examples
To create a function handle from the function name, 'humps'
fhandle = str2func('humps') fhandle = @humps
To create an array of function handles from a cell array of function names
fh_array = str2func({'sin' 'cos' 'tan'}) fh_array = @sin @cos @tan
See Also
function_handle, func2str, functions
2-422
str2mat
Purpose Syntax Description
2str2mat
Form a blank padded character matrix from strings
S = str2mat(T1,T2,T3,..) S = str2mat(T1,T2,T3,..) forms the matrix S containing the text strings T1,T2,T3,... as rows. The function automatically pads each string with
blanks in order to form a valid matrix. Each text parameter, Ti, can itself be a string matrix. This allows the creation of arbitrarily large string matrices. Empty strings are significant.
Note This routine will become obsolete in a future version. Use char instead.
Remarks Examples
str2mat differs from strvcat in that empty strings produce blank rows in the output. In strvcat, empty strings are ignored. x = str2mat('36842','39751','38453','90307'); whos x Name x x(2,3) ans = 7
Size 4x5
Bytes 40
Class char array
See Also
char, strvcat
2-423
str2num
Purpose Syntax Description
2str2num
String to number conversion
x = str2num('str') x = str2num('str') converts the string str, which is an ASCII character representation of a numeric value, to numeric representation. The string can contain:
Digits A decimal point A leading + or - sign A letter e or d preceding a power of 10 scale factor A letter i or j indicating a complex or imaginary number. The str2num function can also convert string matrices.
Examples
str2num('3.14159e0') is approximately .
To convert a string matrix:
str2num(['1 2';'3 4']) ans = 1 3 2 4
See Also
num2str, hex2num, sscanf, sparse, special characters
2-424
strcat
Purpose Syntax Description
2strcat
String concatenation
t = strcat(s1,s2,s3,...) t = strcat(s1,s2,s3,...) horizontally concatenates corresponding rows of the character arrays s1, s2, s3, etc. All input arrays must have the same number of rows (or any can be a single string). When the inputs are all character arrays, the output is also a character array.
When any of the inputs is a cell array of strings, strcat returns a cell array of strings formed by concatenating corresponding elements of s1, s2, etc. The inputs must all have the same size (or any can be a scalar). Any of the inputs can also be character arrays. Trailing spaces in character array inputs are ignored and do not appear in the output. This is not true for inputs that are cell arrays of strings. Use the concatenation syntax [s1 s2 s3 ...] to preserve trailing spaces.
Remarks
strcat and matrix operation are different for strings that contain trailing
spaces:
a = 'hello ' b = 'goodbye' strcat(a,b) ans = hellogoodbye [a b] ans = hello goodbye
Examples
Given two 1-by-2 cell arrays a and b,
a = 'abcde' 'fghi' b = 'jkl' 'mn'
the command t = strcat(a,b) yields:
t = 'abcdejkl' 'fghimn'
Given the 1-by-1 cell array c = {`Q'}, the command t = strcat(a,b,c) yields:
2-425
strcat
t = 'abcdejklQ' 'fghimnQ'
See Also
strvcat, cat, cellstr
2-426
strcmp
Purpose Syntax Description
2strcmp
Compare strings
k = strcmp('str1','str2') TF = strcmp(S,T) k = strcmp('str1','str2') compares the strings str1 and str2 and returns logical true (1) if the two are identical, and logical false (0) otherwise. TF = strcmp(S,T) where either S or T is a cell array of strings, returns an array TF the same size as S and T containing 1 for those elements of S and T that match, and 0 otherwise. S and T must be the same size (or one can be a scalar cell). Either one can also be a character array with the right number of rows.
Remarks
Note that the value returned by strcmp is not the same as the C language convention. In addition, the strcmp function is case sensitive; any leading and trailing blanks in either of the strings are explicitly included in the comparison.
strcmp is intended for comparison of character data. When used to compare numeric data, strcmp returns 0.
Examples
strcmp('Yes','No') = 0 strcmp('Yes','Yes') = 1 A = 'MATLAB' 'Toolboxes' B = 'Handle Graphics' 'Toolboxes' C = 'Signal Processing' 'MATLAB' strcmp(A,B) ans = 0 0 'Image Processing' 'SIMULINK' 'Real Time Workshop' 'The MathWorks' 'SIMULINK' 'The MathWorks'
2-427
strcmp
1
1
strcmp(A,C) ans = 0 0 0 0
See Also
strcmpi, strncmp, strncmpi, strmatch, strfind, findstr, regexp, regexpi, regexprep
2-428
strcmpi
Purpose Syntax Description
2strcmpi
Compare strings ignoring case
strcmpi(str1,str2) strcmpi(S,T) strcmpi(str1,str2) returns 1 if strings str1 and str2 are the same except
for case and 0 otherwise.
strcmpi(S,T) when either S or T is a cell array of strings, returns an array the same size as S and T containing 1 for those elements of S and T that match except for case, and 0 otherwise. S and T must be the same size (or one can be a scalar cell). Either one can also be a character array with the right number of rows.
Remarks
strcmpi is intended for comparison of character data. When used to compare numeric data, strcmpi returns 0. strcmpi supports international character sets.
See Also
strcmp, strncmpi, strncmp, strmatch, strfind, findstr, regexp, regexpi, regexprep
2-429
stream2
Purpose Syntax
2stream2
Compute 2-D stream line data
XY = stream2(x,y,u,v,startx,starty) XY = stream2(u,v,startx,starty) XY = stream2(...,options) XY = stream2(x,y,u,v,startx,starty) computes stream lines from vector data u and v. The arrays x and y define the coordinates for u and v and must be monotonic and 2-D plaid (such as the data produced by meshgrid). startx and starty define the starting positions of the stream lines. The section "Starting
Description
Points for Stream Plots" in Visualization Techniques provides more information on defining starting points. The returned value XY contains a cell array of vertex arrays.
XY = stream2(u,v,startx,starty) assumes the arrays x and y are defined as [x,y] = meshgrid(1:n,1:m) where [m,n] = size(u). XY = stream2(...,options) specifies the options used when creating the stream lines. Define options as a one or two element vector containing the step
size or the step size and the maximum number of vertices in a stream line:
[stepsize]
or
[stepsize, max_number_vertices]
If you do not specify a value, MATLAB uses the default: stepsize = 0.1 (one tenth of a cell) maximum number of vertices = 10000 Use the streamline command to plot the data returned by stream2.
Examples
This example draws 2-D stream lines from data representing air currents over regions of North America.
load wind [sx,sy] = meshgrid(80,20:10:50); streamline(stream2(x(:,:,5),y(:,:,5),u(:,:,5),v(:,:,5),sx,sy));
2-430
stream2
See Also
coneplot, stream3, streamline
"Volume Visualization" for related functions Specifying Starting Points for Stream Plots for related information
2-431
stream3
Purpose Syntax Description
2stream3
Compute 3-D stream line data
XYZ = stream3(X,Y,Z,U,V,W,startx,starty,startz) XYZ = stream3(U,V,W,startx,starty,startz) XYZ = stream3(X,Y,Z,U,V,W,startx,starty,startz) computes stream lines from vector data U, V, W. The arrays X, Y, Z define the coordinates for U, V, W and must be monotonic and 3-D plaid (such as the data produced by meshgrid). startx, starty, and startz define the starting positions of the stream lines. The section "Starting Points for Stream Plots" in Visualization Techniques provides more information on defining starting points.
The returned value XYZ contains a cell array of vertex arrays.
XYZ = stream3(U,V,W,startx,starty,startz) assumes the arrays X, Y, and Z are defined as [X,Y,Z] = meshgrid(1:N,1:M,1:P) where [M,N,P] = size(U). XYZ = stream3(...,options) specifies the options used when creating the stream lines. Define options as a one or two element vector containing the step
size or the step size and the maximum number of vertices in a stream line:
[stepsize]
or
[stepsize, max_number_vertices]
If you do not specify values, MATLAB uses the default: stepsize = 0.1 (one tenth of a cell) maximum number of vertices = 10000 Use the streamline command to plot the data returned by stream3.
Examples
This example draws 3-D stream lines from data representing air currents over regions of North America.
load wind [sx sy sz] = meshgrid(80,20:10:50,0:5:15); streamline(stream3(x,y,z,u,v,w,sx,sy,sz)) view(3)
2-432
stream3
See Also
coneplot, stream2, streamline
"Volume Visualization" for related functions Specifying Starting Points for Stream Plots for related information
2-433
streamline
Purpose Syntax
2streamline
Draw stream lines from 2-D or 3-D vector data
h h h h h h h = = = = = = = streamline(X,Y,Z,U,V,W,startx,starty,startz) streamline(U,V,W,startx,starty,startz) streamline(XYZ) streamline(X,Y,U,V,startx,starty) streamline(U,V,startx,starty) streamline(XY) streamline(...,options)
Description
h = streamline(X,Y,Z,U,V,W,startx,starty,startz) draws stream lines from 3-D vector data U, V, W. The arrays X, Y, Z define the coordinates for U, V, W and must be monotonic and 3-D plaid (such as the data produced by meshgrid). startx, starty, startz define the starting positions of the stream lines. The
section "Starting Points for Stream Plots" in Visualization Techniques provides more information on defining starting points. The output argument h contains a vector of line handles, one handle for each stream line.
h = streamline(U,V,W,startx,starty,startz) assumes the arrays X, Y, and Z are defined as [X,Y,Z] = meshgrid(1:N,1:M,1:P) where [M,N,P] = size(U). h = streamline(XYZ) assumes XYZ is a precomputed cell array of vertex arrays (as produced by stream3). h = streamline(X,Y,U,V,startx,starty) draws stream lines from 2-D vector data U, V. The arrays X, Y define the coordinates for U, V and must be monotonic and 2-D plaid (such as the data produced by meshgrid). startx and starty define the starting positions of the stream lines. The output argument h
contains a vector of line handles, one handle for each stream line.
h = streamline(U,V,startx,starty) assumes the arrays X and Y are defined as [X,Y] = meshgrid(1:N,1:M) where [M,N] = size(U). h = streamline(XY) assumes XY is a precomputed cell array of vertex arrays (as produced by stream2).
2-434
streamline
streamline(...,options) specifies the options used when creating the stream lines. Define options as a one or two element vector containing the step
size or the step size and the maximum number of vertices in a stream line:
[stepsize]
or
[stepsize, max_number_vertices]
If you do not specify values, MATLAB uses the default: stepsize = 0.1 (one tenth of a cell) maximum number of vertices = 1000
Examples
This example draws stream lines from data representing air currents over a region of North America. Loading the wind data set creates the variables x, y, z, u, v, and w in the MATLAB workspace. The plane of stream lines indicates the flow of air from the west to the east (the x direction) beginning at x = 80 (which is close to the minimum value of the x coordinates). The y and z coordinate starting points are multivalued and approximately span the range of these coordinates. meshgrid generates the starting positions of the stream lines.
load wind [sx,sy,sz] = meshgrid(80,20:10:50,0:5:15); h = streamline(x,y,z,u,v,w,sx,sy,sz); set(h,'Color','red') view(3)
See Also
coneplot, stream2, stream3, streamparticles
"Volume Visualization" for related functions Specifying Starting Points for Stream Plots for related information Stream Line Plots of Vecotr Data for another example
2-435
streamparticles
Purpose Syntax
2streamparticles
Display stream particles
streamparticles(vertices) streamparticles(vertices,n) streamparticles(...,'PropertyName',PropertyValue,...) streamparticles(line_handle,...) h = streamparticles(...) streamparticles(vertices) draws stream particles of a vector field. Stream
Description
particles are usually represented by markers and can show the position and velocity of a streamline. vertices is a cell array of 2-D or 3-D vertices (as if produced by stream2 or stream3).
streamparticles(vertices,n) uses n to determine how many stream particles to draw. The ParticleAlignment property controls how n is
interpreted. If ParticleAlignment is set to off (the default) and n is greater than 1, then approximately n particles are drawn evenly spaced over the streamline vertices. If n is less than or equal to 1, n is interpreted as a fraction of the original stream vertices; for example, if n is 0.2, approximately 20% of the vertices are used.
n determines the upper bound for the number of particles drawn. Note that the actual number of particles may deviate from n by as much as a factor of 2.
If ParticleAlignment is on, n determines the number of particles on the streamline having the most vertices and sets the spacing on the other streamlines to this value. The default value is n = 1.
streamparticles(...,'PropertyName',PropertyValue,...) controls the
stream particles using named properties and specified values. Any unspecified properties have default values. MATLAB ignores the case of property names.
Stream Particle Properties
Animate Stream particle motion [non-negative integer]
The number of times to animate the stream particles. The default is 0, which does not animate. Inf animates until you enter ctrl-c.
2-436
streamparticles
FrameRate Animation frames per second [non-negative integer]
This property specifies the number of frames per second for the animation. Inf, the default draws the animation as fast as possible. Note that speed of the animation may be limited by the speed of the computer. In such cases, the value of FrameRate can not necessarily be achieved.
ParticleAlignment Align particles with stream lines [ on | {off} ]
Set this property to on to draw particles at the beginning of each the stream line. This property controls how streamparticles interprets the argument n (number of stream particles). Stream particles are line objects. In addition to stream particle properties, you can specify any line object property, such as Marker and EraseMode. streamparticles sets the following line properties when called.
Line Property EraseMode LineStyle Marker MarkerEdgeColor MarkerFaceColor Value Set by streamparticles xor none o none red
You can override any of these properties by specifying a property name and value as arguments to streamparticles. For example, this statement uses RGB values to set the MarkerFaceColor to medium gray:
streamparticles(vertices,'MarkerFaceColor',[.5 .5 .5]) streamparticles(line_handle,...) uses the line object identified by line_handle to draw the stream particles. h = streamparticles(...) returns a vector of handles to the line objects it
creates.
Examples
This example combines stream lines with stream particle animation. The interpstreamspeed function determines the vertices along the stream lines
2-437
streamparticles
where stream particles will be drawn during the animation, thereby controlling the speed of the animation. Setting the axes DrawMode property to fast provides faster rendering.
load wind [sx sy sz] = meshgrid(80,20:1:55,5); verts = stream3(x,y,z,u,v,w,sx,sy,sz); sl = streamline(verts); iverts = interpstreamspeed(x,y,z,u,v,w,verts,.025); axis tight; view(30,30); daspect([1 1 .125]) camproj perspective; camva(8) set(gca,'DrawMode','fast') box on streamparticles(iverts,35,'animate',10,'ParticleAlignment','on' )
The following picture is a static view of the animation.
This example uses the stream lines in the z = 5 plane to animate the flow along these lines with steamparticles.
load wind daspect([1 1 1]); view(2) [verts averts] = streamslice(x,y,z,u,v,w,[],[],[5]);
2-438
streamparticles
sl = streamline([verts averts]); axis tight off; set(sl,'Visible','off') iverts = interpstreamspeed(x,y,z,u,v,w,verts,.05); set(gca,'DrawMode','fast','Position',[0 0 1 1],'ZLim',[4.9 5.1]) set(gcf,'Color','black') streamparticles(iverts, 200, ... 'Animate',100,'FrameRate',40, ... 'MarkerSize',10,'MarkerFaceColor','yellow')
See Also
interpstreamspeed, stream3, streamline
"Volume Visualization" for related functions Creating Stream Particle Animations for more details Specifying Starting Points for Stream Plots for related information
2-439
streamribbon
Purpose Syntax
2streamribbon
Creates a 3-D stream ribbon plot
streamribbon(X,Y,Z,U,V,W,startx,starty,startz) streamribbon(U,V,W,startx,starty,startz) streamribbon(vertices,X,Y,Z,cav,speed) streamribbon(vertices,cav,speed) streamribbon(vertices,twistangle) streamribbon(...,width) h = streamribbon(...) streamribbon(X,Y,Z,U,V,W,startx,starty,startz) draws stream ribbons from vector volume data U, V, W. The arrays X, Y, Z define the coordinates for U, V, W and must be monotonic and 3-D plaid (as if produced by meshgrid). startx, starty, and startz define the starting positions of the stream ribbons at the center of the ribbons. The section "Starting Points for Stream Plots" in Visualization Techniques provides more information on defining starting points.
Description
The twist of the ribbons is proportional to the curl of the vector field. The width of the ribbons is calculated automatically. Generally, you should set the DataAspectRatio (daspect) before calling streamribbon.
streamribbon(U,V,W,startx,starty,startz) assumes X, Y, and Z are
determined by the expression:
[X,Y,Z] = meshgrid(1:n,1:m,1:p)
where [m,n,p] = size(U).
streamribbon(vertices,X,Y,Z,cav,speed) assumes precomputed streamline vertices, curl angular velocity, and flow speed. vertices is a cell array of stream line vertices (as produced by stream3). X, Y, Z, cav, and speed
are 3-D arrays.
streamribbon(vertices,cav,speed) assumes X, Y, and Z are determined by
the expression:
[X,Y,Z] = meshgrid(1:n,1:m,1:p)
2-440
streamribbon
where [m,n,p] = size(cav)
streamribbon(vertices,twistangle) uses the cell array of vectors twistangle for the twist of the ribbons (in radians). The size of each corresponding element of vertices and twistangle must be equal. streamribbon(...,width) sets the width of the ribbons to width. h = streamribbon(...) returns a vector of handles (one per start point) to surface objects.
Examples
This example uses stream ribbons to indicate the flow in the wind data set. Inputs include the coordinates, vector field components, and starting location for the stream ribbons.
load wind [sx sy sz] = meshgrid(80,20:10:50,0:5:15); daspect([1 1 1]) streamribbon(x,y,z,u,v,w,sx,sy,sz); %-----Define viewing and lighting axis tight shading interp; view(3); camlight; lighting gouraud
2-441
streamribbon
This example uses precalculated vertex data (stream3), curl average velocity (curl), and speed ( u + v + w ). Using precalculated data enables you to use values other than those calculated from the single data source. In this case, the speed is reduced by a factor of 10 compared to the previous example.
load wind [sx sy sz] = meshgrid(80,20:10:50,0:5:15); daspect([1 1 1]) verts = stream3(x,y,z,u,v,w,sx,sy,sz); cav = curl(x,y,z,u,v,w); spd = sqrt(u.^2 + v.^2 + w.^2).*.1; streamribbon(verts,x,y,z,cav,spd); %-----Define viewing and lighting axis tight shading interp view(3) camlight; lighting gouraud
2 2 2
2-442
streamribbon
This example specifies a twist angle for the stream ribbon.
t = 0:.15:15; verts = {[cos(t)' sin(t)' (t/3)']}; twistangle = {cos(t)'}; daspect([1 1 1]) streamribbon(verts,twistangle); %-----Define viewing and lighting axis tight shading interp; view(3); camlight; lighting gouraud
2-443
streamribbon
This example combines cone plots (coneplot) and stream ribbon plots in one graph.
%-----Define 3-D arrays x, y, z, u, v, w xmin = -7; xmax = 7; ymin = -7; ymax = 7; zmin = -7; zmax = 7; x = linspace(xmin,xmax,30); y = linspace(ymin,ymax,20); z = linspace(zmin,zmax,20); [x y z] = meshgrid(x,y,z); u = y; v = -x; w = 0*x+1; daspect([1 1 1]); [cx cy cz] = meshgrid(linspace(xmin,xmax,30),... linspace(ymin,ymax,30),[-3 4]); h = coneplot(x,y,z,u,v,w,cx,cy,cz,'quiver'); set(h,'color','k'); %-----Plot two sets of streamribbons [sx sy sz] = meshgrid([-1 0 1],[-1 0 1],-6); streamribbon(x,y,z,u,v,w,sx,sy,sz); [sx sy sz] = meshgrid([1:6],[0],-6); streamribbon(x,y,z,u,v,w,sx,sy,sz);
2-444
streamribbon
%-----Define viewing and lighting shading interp view(-30,10) ; axis off tight camproj perspective; camva(66); camlookat; camdolly(0,0,.5,'fixtarget') camlight
See also
curl, streamtube, streamline, stream3
"Volume Visualization" for related functions Displaying Curl with Stream Ribbons for another example Specifying Starting Points for Stream Plots for related information
2-445
streamslice
Purpose Syntax
2streamslice
Draws stream lines in slice planes
streamslice(X,Y,Z,U,V,W,startx,starty,startz) streamslice(U,V,W,startx,starty,startz) streamslice(X,Y,U,V) streamslice(U,V) streamslice(...,density) streamslice(...,'arrowmode') streamslice(...,'method') h = streamslice(...) [vertices arrowvertices] = streamslice(...) streamslice(X,Y,Z,U,V,W,startx,starty,startz) draws well spaced streamlines (with direction arrows) from vector data U, V, W in axis aligned x-, y-, z-planes at the points in the vectors startx, starty, startz. (The section
Description
"Starting Points for Stream Plots" in Visualization Techniques provides more information on defining starting points.) The arrays X, Y, Z define the coordinates for U, V, W and must be monotonic and 3-D plaid (as if produced by meshgrid). U, V, W must be m-by-n-by-p volume arrays. You should not assumed that the flow is parallel to the slice plane. For example, in a stream slice at a constant z, the z component of the vector field, W, is ignored when calculating the streamlines for that plane. Stream slices are useful for determining where to start stream lines, stream tubes, and stream ribbons.
streamslice(U,V,W,startx,starty,startz) assumes X, Y, and Z are
determined by the expression:
[X,Y,Z] = meshgrid(1:n,1:m,1:p)
where [m,n,p] = size(U).
streamslice(X,Y,U,V) draws well spaced stream lines (with direction arrows) from vector volume data U, V. The arrays X, Y define the coordinates for U, V and must be monotonic and 2-D plaid (as if produced by meshgrid). streamslice(U,V) assumes X, Y, and Z are determined by the expression: [X,Y,Z] = meshgrid(1:n,1:m,1:p)
2-446
streamslice
where [m,n,p] = size(U)
streamslice(...,density) modifies the automatic spacing of the stream lines. density must be greater than 0. The default value is 1; higher values produce more stream lines on each plane. For example, 2 produces
approximately twice as many stream lines, while 0.5 produces approximately half as many.
streamslice(...,'arrowsmode') determines if direction arrows are present or not. arrowmode can be:
arrows draw direction arrows on the streamlines (default) noarrows does not draw direction arrows
streamslice(...,'method') specifies the interpolation method to use. method
can be: linear linear interpolation (default) cubic cubic interpolation nearest nearest neighbor interpolation See interp3 for more information interpolation methods.
h = streamslice(...) returns a vector of handles to the line objects created. [vertices arrowvertices] = streamslice(...) returns two cell arrays of vertices for drawing the stream lines and the arrows. You can pass these values to any of the stream line drawing functions (streamline, streamribbon, streamtube)
Examples
This example creates a stream slice in the wind data set at z = 5.
load wind daspect([1 1 1]) streamslice(x,y,z,u,v,w,[],[],[5]) axis tight
2-447
streamslice
This example uses streamslice to calculate vertex data for the stream lines and the direction arrows. This data is then used by streamline to plot the lines and arrows. Slice planes illustrating with color the wind speed ( u + v + w ) are drawn by slice in the same planes.
load wind daspect([1 1 1]) [verts averts] = streamslice(u,v,w,10,10,10); streamline([verts averts]) spd = sqrt(u.^2 + v.^2 + w.^2); hold on; slice(spd,10,10,10); colormap(hot) shading interp view(30,50); axis(volumebounds(spd)); camlight; material([.5 1 0])
2 2 2
2-448
streamslice
This example superimposes contour lines on a surface and then uses streamslice to draw lines that indicate the gradient of the surface. interp2 is used to find the points for the lines that lie on the surface.
z = peaks; surf(z) shading interp hold on [c ch] = contour3(z,20); set(ch,'edgecolor','b') [u v] = gradient(z); h = streamslice(-u,-v); set(h,'color','k') for i=1:length(h); zi = interp2(z,get(h(i),'xdata'),get(h(i),'ydata')); set(h(i),'zdata',zi); end view(30,50); axis tight
2-449
streamslice
See also
contourslice, slice, streamline, volumebounds
"Volume Visualization" for related functions Specifying Starting Points for Stream Plots for related information
2-450
streamtube
Purpose Syntax
2streamtube
Creates a 3-D stream tube plot
streamtube(X,Y,Z,U,V,W,startx,starty,startz) streamtube(U,V,W,startx,starty,startz) streamtube(vertices,X,Y,Z,divergence) streamtube(vertices,divergence) streamtube(vertices,width) streamtube(vertices) streamtube(...,[scale n]) h = streamtube(...) streamtube(X,Y,Z,U,V,W,startx,starty,startz) draws stream tubes from vector volume data U, V, W. The arrays X, Y, Z define the coordinates for U, V, W and must be monotonic and 3-D plaid (as if produced by meshgrid). startx, starty, and startz define the starting positions of the stream lines at the center of the tubes. The section "Starting Points for Stream Plots" in Visualization Techniques provides more information on defining starting points.
Description
The width of the tubes is proportional to the normalized divergence of the vector field. Generally, you should set the DataAspectRatio (daspect) before calling streamtube.
streamtube(U,V,W,startx,starty,startz) assumes X, Y, and Z are
determined by the expression:
[X,Y,Z] = meshgrid(1:n,1:m,1:p)
where [m,n,p] = size(U).
streamtube(vertices,X,Y,Z,divergence) assumes precomputed stream line vertices and divergence. vertices is a cell array of stream line vertices (as produced by stream3). X, Y, Z, and divergence are 3-D arrays. streamtube(vertices,divergence) assumes X, Y, and Z are determined by
the expression:
[X,Y,Z] = meshgrid(1:n,1:m,1:p)
2-451
streamtube
where [m,n,p] = size(divergence)
streamtube(vertices,width) specifies the width of the tubes in the cell array of vectors, width. The size of each corresponding element of vertices and width must be equal. width can also be a scalar, specifying a single value for
the width of all stream tubes.
streamtube(vertices) selects the width automatically. streamtube(...,[scale n]) scales the width of the tubes by scale. The default is scale = 1. When the stream tubes are created using start points or divergence, specifying scale = 0 suppresses automatic scaling. n is the number of points along the circumference of the tube. The default is n = 20. h = streamtube(...z) returns a vector of handles (one per start point) to surface objects used to draw the stream tubes.
Examples
This example uses stream tubes to indicate the flow in the wind data set. Inputs include the coordinates, vector field components, and starting location for the stream tubes.
load wind [sx sy sz] = meshgrid(80,20:10:50,0:5:15); daspect([1 1 1]) streamtube(x,y,z,u,v,w,sx,sy,sz); %-----Define viewing and lighting view(3) axis tight shading interp; camlight; lighting gouraud
2-452
streamtube
This example uses precalculated vertex data (stream3) and divergence (divergence).
load wind [sx sy sz] = meshgrid(80,20:10:50,0:5:15); daspect([1 1 1]) verts = stream3(x,y,z,u,v,w,sx,sy,sz); div = divergence(x,y,z,u,v,w); streamtube(verts,x,y,z,-div); %-----Define viewing and lighting view(3) axis tight shading interp camlight; lighting gouraud
2-453
streamtube
See also
divergence, streamribbon, streamline, stream3
"Volume Visualization" for related functions Displaying Divergence with Stream Tubes for another example Specifying Starting Points for Stream Plots for related information
2-454
strfind
Purpose Syntax Description
2strfind
Find one string within another
k = strfind(str,pattern) k = strfind(str,pattern) searches the string, str, for occurrences of a shorter string, pattern, returning the starting index of each such occurrence in the double array, k. If pattern is not found in str, or if pattern is longer than str, then strfind returns the empty array, [].
The search performed by strfind is case sensitive. Any leading and trailing blanks in either str or pattern are explicitly included in the comparison. Use the function findstr, if you are not certain which of the two input strings is the longer one.
Examples
s = 'Find the starting indices of the pattern string'; strfind(s,'in') ans = 2 15 19 45 strfind(s,'In') ans = [] strfind(s,' ') ans = 5 9
18
26
29
33
41
See Also
findstr, strmatch, strtok, strcmp, strncmp, strcmpi, strncmpi, regexp, regexpi, regexprep
2-455
strings
Purpose Syntax
2strings
MATLAB string handling
S = 'Any Characters' S = char(X) X = double(S) S = 'Any Characters' creates a character array, or string. The string is
Description
actually a vector whose components are the numeric codes for the characters (the first 127 codes are ASCII). The actual characters displayed depend on the character set encoding for a given font. The length of S is the number of characters. A quote within the string is indicated by two quotes.
S = [S1 S2 ...] concatenates character arrays S1, S2, etc. into a new character array, S. S = strcat(S1, S2, ...) concatenates S1, S2, etc., which can be character arrays or cell arrays of strings. When the inputs are all character arrays, the output is also a character array. When any of the inputs is a cell array of strings, strcat returns a cell array of strings.
Trailing spaces in strcat character array inputs are ignored and do not appear in the output. This is not true for strcat inputs that are cell arrays of strings. Use the S = [S1 S2 ...] concatenation syntax, shown above, to preserve trailing spaces.
S = char(X) can be used to convert an array that contains positive integers
representing numeric codes into a MATLAB character array.
X = double(S) converts the string to its equivalent double precision numeric
codes. A collection of strings can be created in either of the following two ways: As the rows of a character array via strvcat As a cell array of strings via the curly braces You can convert between character array and cell array of strings using char and cellstr. Most string functions support both types.
ischar(S) tells if S is a string variable. iscellstr(S) tells if S is a cell array of
strings.
2-456
strings
Examples
Create a simple string that includes a single quote.
msg = 'You''re right!' msg = You're right!
Create the string, name, using two methods of concatenation.
name = ['Thomas' ' R. ' 'Lee'] name = strcat('Thomas',' R.',' Lee')
Create a vertical array of strings.
C = strvcat('Hello','Yes','No','Goodbye') C = Hello Yes No Goodbye
Create a cell array of strings.
S = {'Hello' 'Yes' 'No' 'Goodbye'} S = 'Hello' 'Yes' 'No' 'Goodbye'
See Also
char, cellstr, ischar, iscellstr, strvcat, sprintf, sscanf, input
2-457
strjust
Purpose Syntax
2strjust
Justify a character array
T T T T = = = = strjust(S) strjust(S,'right') strjust(S,'left') strjust(S,'center')
Description
T = strjust(S) or T = strjust(S,'right') returns a right-justified version
of the character array S.
T = strjust(S,'left') returns a left-justified version of S. T = strjust(S,'center') returns a center-justified version of S.
See Also
deblank
2-458
strmatch
Purpose Syntax Description
2strmatch
Find possible matches for a string
x = strmatch('str',STRS) x = strmatch('str',STRS,'exact') x = strmatch('str',STRS) looks through the rows of the character array or cell array of strings STRS to find strings that begin with string str, returning the matching row indices. strmatch is fastest when STRS is a character array. x = strmatch('str',STRS,'exact') returns only the indices of the strings in STRS matching str exactly.
Examples
The statement
x = strmatch('max',strvcat('max','minimax','maximum'))
returns x = [1; 3] since rows 1 and 3 begin with 'max'. The statement
x = strmatch('max',strvcat('max','minimax','maximum'),'exact')
returns x = 1, since only row 1 matches 'max' exactly.
See Also
strcmp, strcmpi, strncmp, strncmpi, strfind, findstr, strvcat, regexp, regexpi, regexprep
2-459
strncmp
Purpose Syntax Description
2strncmp
Compare the first n characters of two strings
k = strncmp('str1','str2',n) TF = strncmp(S,T,n) k = strncmp('str1','str2',n) returns logical true (1) if the first n characters of the strings str1 and str2 are the same, and returns logical false (0) otherwise. Arguments str1 and str2 may also be cell arrays of strings. TF = strncmp(S,T,N) where either S or T is a cell array of strings, returns an array TF the same size as S and T containing 1 for those elements of S and T that match (up to n characters), and 0 otherwise. S and T must be the same size (or one can be a scalar cell). Either one can also be a character array with the right number of rows.
Remarks
The command strncmp is case sensitive. Any leading and trailing blanks in either of the strings are explicitly included in the comparison.
strncmp is intended for comparison of character data. When used to compare numeric data, strncmp returns 0.
See Also
strncmpi, strcmp, strcmpi, strmatch, strfind, findstr, regexp, regexpi, regexprep
2-460
strncmpi
Purpose Syntax Description
2strncmpi
Compare first n characters of strings ignoring case
strncmpi('str1','str2',n) TF = strncmpi(S,T,n) strncmpi('str1','str2',n) returns 1 if the first n characters of the strings str1 and str2 are the same except for case, and 0 otherwise. TF = strncmpi(S,T,n) when either S or T is a cell array of strings, returns an array the same size as S and T containing 1 for those elements of S and T that match except for case (up to n characters), and 0 otherwise. S and T must be the same size (or one can be a scalar cell). Either one can also be a character array with the right number of rows.
Remarks
strncmpi is intended for comparison of character data. When used to compare numeric data, strncmpi returns 0. strncmpi supports international character sets.
See Also
strncmp, strcmpi, strcmp, strmatch, strfind, findstr, regexp, regexpi, regexprep
2-461
strread
Purpose Syntax
2strread
Read formatted data from a string
A = strread('str') A = strread('str','',N) A = strread('str','',param,value,...) A = strread('str','',N,param,value,...) [A,B,C,...] = strread('str','format') [A,B,C,...] = strread('str','format',N) [A,B,C,...] = strread('str','format',param,value,...) [A,B,C,...] = strread('str','format',N,param,value,...)
Description
The first four syntaxes are used on strings containing only numeric data. If the input string, str, contains any text data, an error is generated.
A = strread('str') reads numeric data from the string, str, into the single
variable A.
A = strread('str','',N) reads N lines of numeric data, where N is an integer greater than zero. If N is -1, strread reads the entire string. A = strread('str','',param,value,...) customizes strread using param/value pairs, as listed in the table below. A = strread('str','',N,param,value,...) reads N lines and customizes the strread using param/value pairs.
The next four syntaxes can be used on numeric or nonnumeric data. In this case, strread reads data from the string, str, into the variables A, B, C, and so on, using the specified format. The type of each return argument is given by the format string. The number of return arguments must match the number of conversion specifiers in the format string. If there are fewer fields in the string than matching conversion specifiers in the format string, an error is generated. The format string determines the number and types of return arguments. The number of return arguments is the number of items in the format string. The format string supports a subset of the conversion specifiers and conventions of
2-462
strread
the C language fscanf routine. Values for the format string are listed in the table below. Whitespace characters in the format string are ignored.
[A,B,C,...] = strread('str','format') reads data from the string, str, into the variables A, B, C, and so on, using the specified format, until the entire
string is read.
format Action Output
Literals (ordinary characters)
Ignore the matching characters. For example, in a file that has Dept followed by a number (for department number), to skip the Dept and read only the number, use 'Dept' in the format string. Read a signed integer value. Read an integer value. Read a floating point value. Read a whitespace-separated string. Read a string, which could be in double quotes.
None
%d %u %f %s
Double array Double array Double array Cell array of strings Cell array of strings. Does not include the double quotes. Character array Cell array of strings
%q
%c
Read characters, including white space. Read the longest string containing characters specified in the brackets. Read the longest non-empty string containing characters that are not specified in the brackets.
%[...]
%[^...]
Cell array of strings
2-463
strread
format %*...
Action
Output
instead of %
%w...
Ignore the matching characters specified by *. Read field width specified by w. The %f format supports %w.pf, where w is the field width and p is the precision.
No output
instead of %
[A,B,C,...] = strread('str','format',N) reads the data, reusing the format string N times, where N is an integer greater than zero. If N is -1, strread reads the entire string. [A,B,C,...] = strread('str','format',param,value,...) customizes strread using param/value pairs, as listed in the table below. [A,B,C,...] = strread('str','format',N,param,value,...) reads the data, reusing the format string N times and customizes the strread using param/value pairs. param whitespace value \* where * can be: b f n r t \\ \'' or '' %% delimiter Action
Treats vector of characters, *, as whitespace. Default is \b\r\n\t. Backspace Form feed New line Carriage return Horizontal tab Backslash Single quotation mark Percent sign Specifies delimiter character. Default is none. Default is eEdD.
Delimiter character Exponent characters
expchars
2-464
strread
param bufsize
value
Action
positive integer positive integer
matlab shell c c++
Specifies the maximum string length, in bytes. Default is 4095. Ignores the specified number of lines at the beginning of the file. Ignores characters after % Ignores characters after #. Ignores characters between /* and */. Ignores characters after //.
headerlines
commentstyle commentstyle commentstyle commentstyle
Remarks
If your data uses a character other than a space as a delimiter, you must use the strread parameter 'delimiter' to specify the delimiter. For example, if the string, str, used a semicolon as a delimiter, you would use this command.
[names,types,x,y,answer] = strread(str,'%s %s %f ... %d %s','delimiter',';')
Examples
s = sprintf('a,1,2\nb,3,4\n'); [a,b,c] = strread(s,'%s%d%d','delimiter',',') a = 'a' 'b' b = 1 3 c = 2 4
See Also
textread, sscanf
2-465
strrep
Purpose Syntax Description
2strrep
String search and replace
str = strrep(str1,str2,str3) str = strrep(str1,str2,str3) replaces all occurrences of the string str2 within string str1 with the string str3. strrep(str1,str2,str3), when any of str1, str2, or str3 is a cell array of strings, returns a cell array the same size as str1, str2 and str3 obtained by performing a strrep using corresponding elements of the inputs. The inputs must all be the same size (or any can be a scalar cell). Any one of the strings can also be a character array with the right number of rows.
Examples
s1 = 'This is a good example.'; str = strrep(s1,'good','great') str = This is a great example. A = 'MATLAB' 'Toolboxes' B = 'Handle Graphics' 'Toolboxes' C = 'Signal Processing' 'MATLAB' strrep(A,B,C) ans = 'MATLAB' 'MATLAB' 'Image Processing' 'SIMULINK' 'Real Time Workshop' 'The MathWorks' 'SIMULINK' 'The MathWorks'
'SIMULINK' 'SIMULINK'
See Also
findstr
2-466
strtok
Purpose Syntax
2strtok
First token in string
token = strtok('str',delimiter) token = strtok('str') [token,rem] = strtok(...) token = strtok('str',delimiter) returns the first token in the text string str, that is, the first set of characters before a delimiter is encountered. The vector delimiter contains valid delimiter characters. Any leading delimiters
Description
are ignored.
token = strtok('str') uses the default delimiters, the white space
characters. These include tabs (ASCII 9), carriage returns (ASCII 13), and spaces (ASCII 32). Any leading white space characters are ignored.
[token,rem] = strtok(...) returns the remainder rem of the original string.
The remainder consists of all characters from the first delimiter on.
Examples
s = ' This is a good example.'; [token,rem] = strtok(s) token = This rem = is a good example. findstr, strmatch
See Also
2-467
struct
Purpose Syntax Description
2struct
Create structure array
s = struct('field1',{},'field2',{},...) s = struct('field1',values1,'field2',values2,...) s = struct('field1',{},'field2',{},...) creates an empty structure
with fields field1, field2, ...
s = struct('field1',values1,'field2',values2,...) creates a structure array with the specified fields and values. The value arrays values1, values2, etc. must be cell arrays of the same size or scalar cells. Corresponding elements of the value arrays are placed into corresponding structure array elements. The size of the resulting structure is the same size as the value cell arrays or 1-by-1 if none of the values is a cell.
Examples
The command
s = struct('type',{'big','little'},'color',{'red'},'x',{3 4})
produces a structure array s:
s = 1x2 struct array with fields: type color x
The value arrays have been distributed among the fields of s:
s(1) ans = type: 'big' color: 'red' x: 3 s(2) ans = type: 'little' color: 'red' x: 4
2-468
struct
Similarly, the command
a.b = struct('z',{});
produces an empty structure a.b with field z.
a.b ans = 0x0 struct array with fields: z
See Also
isstruct, fieldnames, isfield, orderfields, rmfield, deal, cell2struct, struct2cell
2-469
struct2cell
Purpose Syntax Description
2struct2cell
Structure to cell array conversion
c = struct2cell(s) c = struct2cell(s) converts the m-by-n structure s (with p fields) into a p-by-m-by-n cell array c.
If structure s is multidimensional, cell array c has size [p size(s)].
Examples
The commands
clear s, s.category = 'tree'; s.height = 37.4; s.name = 'birch';
create the structure
s = category: 'tree' height: 37.4000 name: 'birch'
Converting the structure to a cell array,
c = struct2cell(s) c = 'tree' [37.4000] 'birch'
See Also
cell2struct, fieldnames
2-470
strvcat
Purpose Syntax Description
2strvcat
Vertical concatenation of strings
S = strvcat(t1,t2,t3,...) S = strvcat(t1,t2,t3,...) forms the character array S containing the text strings (or string matrices) t1,t2,t3,... as rows. Spaces are appended to each
string as necessary to form a valid matrix. Empty arguments are ignored.
Remarks Examples
If each text parameter, ti, is itself a character array, strvcat appends them vertically to create arbitrarily large string matrices. The command strvcat('Hello','Yes') is the same as ['Hello';'Yes except that strvcat performs the padding automatically.
t1 = 'first';t2 = 'string';t3 = 'matrix';t4 = 'second'; S1 = strvcat(t1,t2,t3) S1 = first string matrix S3 = strvcat(S1,S2) S3 = first string matrix second string matrix S2 = strvcat(t4,t2,t3) S2 = second string matrix '],
See Also
cat, int2str, mat2str, num2str, strings
2-471
sub2ind
Purpose Syntax Description
2sub2ind
Single index from subscripts
IND = sub2ind(siz,I,J) IND = sub2ind(siz,I1,I2,...,In)
The sub2ind command determines the equivalent single index corresponding to a set of subscript values.
IND = sub2ind(siz,I,J) returns the linear index equivalent to the row and column subscripts I and J for a matrix of size siz. siz is a 2-element vector, where siz(1) is the number of rows and siz(2) is the number of columns. IND = sub2ind(siz,I1,I2,...,In) returns the linear index equivalent to the n subscripts I1,I2,...,In for an array of size siz. siz is an n-element vector that
specifies the size of each array dimension.
Examples
Create a 3-by-4-by-2 array, A.
A = [17 24 1 8; 2 22 7 14; 4 6 13 20]; A(:,:,2) = A - 10 A(:,:,1) = 17 2 4 24 22 6 1 7 13 8 14 20
A(:,:,2) = 7 -8 -6 14 12 -4 -9 -3 3 -2 4 10
The value at row 2, column 1, page 2 of the array is -8.
A(2,1,2) ans = -8
2-472
sub2ind
To convert A(2,1,2) into its equivalent single subscript, use sub2ind.
sub2ind(size(A),2,1,2) ans = 14
You can now access the same location in A using the single subscripting method.
A(14) ans = -8
See Also
ind2sub, find, size
2-473
subplot
Purpose Syntax
2subplot
Create and control multiple axes
subplot(m,n,p) subplot(m,n,p,'replace') subplot(h) subplot('Position',[left bottom width height]) h = subplot(...) subplot divides the current figure into rectangular panes that are numbered
Description
row-wise. Each pane contains an axes. Subsequent plots are output to the current pane.
subplot(m,n,p) creates an axes in the p-th pane of a figure divided into an m-by-n matrix of rectangular panes. The new axes becomes the current axes.
If p is a vector, it specifies an axes having a position that covers all the subplot positions listed in p.
subplot(m,n,p,'replace') If the specified axes already exists, delete it and
creat a new axes.
subplot(h) makes the axes with handle h current for subsequent plotting
commands.
subplot('Position',[left bottom width height]) creates an axes at the position specified by a four-element vector. left, bottom, width, and height are in normalized coordinates in the range from 0.0 to 1.0. h = subplot(...) returns the handle to the new axes.
Remarks
If a subplot specification causes a new axes to overlap any existing axes, then subplot deletes the existing axes and uicontrol objects. However, if the subplot specification exactly matches the position of an existing axes, then the matching axes is not deleted and it becomes the current axes.
subplot(1,1,1) or clf deletes all axes objects and returns to the default subplot(1,1,1) configuration.
You can omit the parentheses and specify subplot as.
subplot mnp
2-474
subplot
where m refers to the row, n refers to the column, and p specifies the pane.
Special Case subplot(111)
The command subplot(111) is not identical in behavior to subplot(1,1,1) and exists only for compatibility with previous releases. This syntax does not immediately create an axes, but instead sets up the figure so that the next graphics command executes a clf reset (deleting all figure children) and creates a new axes in the default position. This syntax does not return a handle, so it is an error to specify a return argument. (This behavior is implemented by setting the figure's NextPlot property to replace.)
Examples
To plot income in the top half of a figure and outgo in the bottom half,
income = [3.2 4.1 5.0 5.6]; outgo = [2.5 4.0 3.35 4.9]; subplot(2,1,1); plot(income) subplot(2,1,2); plot(outgo)
2-475
subsasgn
Purpose Syntax Description
2subsasgn
Overloaded method for A(I)=B, A{I}=B, and A.field=B
A = subsasgn(A,S,B) A = subsasgn(A,S,B) is called for the syntax A(i)=B, A{i}=B, or A.i=B when A is an object. S is a structure array with the fields:
type: A string containing '()', '{}', or '.', where '()' specifies integer subscripts; '{}' specifies cell array subscripts, and '.' specifies subscripted structure fields. subs: A cell array or string containing the actual subscripts.
Remarks
subsasgn is designed to be used by the MATLAB interpreter to handle indexed assignments to objects. Calling subsasgn directly as a function is not recommended. If you do use subsasgn in this way, it conforms to the formal
MATLAB dispatching rules and may yield unexpected results.
Examples
The syntax A(1:2,:)=B calls A=subsasgn(A,S,B) where S is a 1-by-1 structure with S.type='()' and S.subs = {1:2,':'}. A colon used as a subscript is passed as the string ':'. The syntax A{1:2}=B calls A=subsasgn(A,S,B) where S.type='{}'. The syntax A.field=B calls subsasgn(A,S,B) where S.type='.' and S.subs='field'. These simple calls are combined in a straightforward way for more complicated subscripting expressions. In such cases length(S) is the number of subscripting levels. For instance, A(1,2).name(3:5)=B calls A=subsasgn(A,S,B) where S is 3-by-1 structure array with the following values:
S(1).type='()' S(1).subs={1,2} S(2).type='.' S(2).subs='name' S(3).type='()' S(3).subs={3:5}
See Also
subsref
See "Handling Subscripted Assignment" for more information about overloaded methods and subsasgn.
2-476
subsindex
Purpose Syntax Description
2subsindex
Overloaded method for X(A)
ind = subsindex(A) ind = subsindex(A) is called for the syntax 'X(A)' when A is an object. subsindex must return the value of the object as a zero-based integer index. (ind must contain integer values in the range 0 to prod(size(X))-1). subsindex is called by the default subsref and subsasgn functions, and you
can call it if you overload these functions.
See Also
subsasgn, subsref
2-477
subsindex
The following illustration shows four subplot regions and indicates the command used to create each.
See Also
axes, cla, clf, figure, gca
"Basic Plots and Graphs" for more information
2-478
subspace
Purpose Syntax Description
2subspace
Angle between two subspaces
theta = subspace(A,B) theta = subspace(A,B) finds the angle between two subspaces specified by the columns of A and B. If A and B are column vectors of unit length, this is the same as acos(A'*B).
Remarks
If the angle between the two subspaces is small, the two spaces are nearly linearly dependent. In a physical experiment described by some observations A, and a second realization of the experiment described by B, subspace(A,B) gives a measure of the amount of new information afforded by the second experiment not associated with statistical errors of fluctuations. Consider two subspaces of a Hadamard matrix, whose columns are orthogonal.
H = hadamard(8); A = H(:,2:4); B = H(:,5:8);
Examples
Note that matrices A and B are different sizes-- A has three columns and B four. It is not necessary that two subspaces be the same size in order to find the angle between them. Geometrically, this is the angle between two hyperplanes embedded in a higher dimensional space.
theta = subspace(A,B) theta = 1.5708
That A and B are orthogonal is shown by the fact that theta is equal to / 2 .
theta - pi/2 ans = 0
2-479
subsref
Purpose Syntax Description
2subsref
Overloaded method for A(I), A{I} and A.field
B = subsref(A,S) B = subsref(A,S) is called for the syntax A(i), A{i}, or A.i when A is an object. S is a structure array with the fields:
type: A string containing '()', '{}', or '.', where '()' specifies integer subscripts; '{}' specifies cell array subscripts, and '.' specifies subscripted structure fields. subs: A cell array or string containing the actual subscripts.
Remarks
subsref is designed to be used by the MATLAB interpreter to handle indexed references to objects. Calling subsref directly as a function is not recommended. If you do use subsref in this way, it conforms to the formal
MATLAB dispatching rules and may yield unexpected results.
Examples
The syntax A(1:2,:) calls subsref(A,S) where S is a 1-by-1 structure with S.type='()' and S.subs={1:2,':'}. A colon used as a subscript is passed as the string ':'. The syntax A{1:2} calls subsref(A,S) where S.type='{}' and S.subs={1:2}. The syntax A.field calls subsref(A,S) where S.type='.' and S.subs='field'. These simple calls are combined in a straightforward way for more complicated subscripting expressions. In such cases length(S) is the number of subscripting levels. For instance, A(1,2).name(3:5) calls subsref(A,S) where S is 3-by-1 structure array with the following values:
S(1).type='()' S(1).subs={1,2} S(2).type='.' S(2).subs='name' S(3).type='()' S(3).subs={3:5}
See Also
subsasgn
See "Handling Subscripted Reference" for more information about overloaded methods and subsref.
2-480
substruct
Purpose Syntax Description
2substruct
Create structure argument for subsasgn or subsref
S = substruct(type1,subs1,type2,subs2,...) S = substruct(type1,subs1,type2,subs2,...) creates a structure with the fields required by an overloaded subsref or subsasgn method. Each type string must be one of '.', '()', or '{}'. The corresponding subs argument must be either a field name (for the '.' type) or a cell array containing the index vectors (for the '()' or '{}' types).
The output S is a structure array containing the fields: type one of '.', '()', or '{}' subs subscript values (field name or cell array of index vectors)
Examples
To call subsref with parameters equivalent to the syntax
B = A(3,5).field
you can use
S = substruct('()',{3,5},'.','field'); B = subsref(A,S);
The structure created by substruct in this example contains the following.
S(1) ans = type: '()' subs: {[3] S(2) ans = type: '.' subs: 'field'
[5]}
See Also
subsasgn, subsref
2-481
subvolume
Purpose Syntax
2subvolume
Extract subset of volume data set
[Nx,Ny,Nz,Nv] = subvolume(X,Y,Z,V,limits) [Nx,Ny,Nz,Nv] = subvolume(V,limits) Nv = subvolume(...) [Nx,Ny,Nz,Nv] = subvolume(X,Y,Z,V,limits) extracts a subset of the volume data set V using the specified axis-aligned limits. limits = [xmin,xmax,ymin, ymax,zmin,zmax] (Any NaNs in the limits indicate that the
Description
volume should not be cropped along that axis). The arrays X, Y, and Z define the coordinates for the volume V. The subvolume is returned in NV and the coordinates of the subvolume are given in NX, NY, and NZ.
[Nx,Ny,Nz,Nv] = subvolume(V,limits) assumes the arrays X, Y, and Z are defined as [X,Y,Z] = meshgrid(1:N,1:M,1:P) where [M,N,P] = size(V). Nv = subvolume(...) returns only the subvolume.
Examples
This example uses a data set that is a collection of MRI slices of a human skull. The data is processed in a variety of ways: The 4-D array is squeezed (squeeze) into three dimensions and then a subset of the data is extracted (subvolume). The outline of the skull is an isosurface generated as a patch (p1) whose vertex normals are recalculated to improve the appearance when lighting is applied (patch, isosurface, isonormals). A second patch (p2) with interpolated face color draws the end caps (FaceColor, isocaps). The view of the object is set (view, axis, daspect). A 100-element grayscale colormap provides coloring for the end caps (colormap). Adding lights to the right and left of the camera illuminates the object (camlight, lighting).
load mri D = squeeze(D); [x,y,z,D] = subvolume(D,[60,80,nan,80,nan,nan]);
2-482
subvolume
p1 = patch(isosurface(x,y,z,D, 5),... 'FaceColor','red','EdgeColor','none'); isonormals(x,y,z,D,p1); p2 = patch(isocaps(x,y,z,D, 5),... 'FaceColor','interp','EdgeColor','none'); view(3); axis tight; daspect([1,1,.4]) colormap(gray(100)) camlight right; camlight left; lighting gouraud
See Also
isocaps, isonormals, isosurface, reducepatch, reducevolume, smooth3
"Volume Visualization" for related functions
2-483
sum
Purpose Syntax Description
2sum
Sum of array elements
B = sum(A) B = sum(A,dim) B = sum(A) returns sums along different dimensions of an array.
If A is a vector, sum(A) returns the sum of the elements. If A is a matrix, sum(A) treats the columns of A as vectors, returning a row vector of the sums of each column. If A is a multidimensional array, sum(A) treats the values along the first non-singleton dimension as vectors, returning an array of row vectors.
B = sum(A,dim) sums along the dimension of A specified by scalar dim.
Remarks Examples
sum(diag(X)) is the trace of X.
The magic square of order 3 is
M = magic(3) M = 8 1 3 5 4 9
6 7 2
This is called a magic square because the sums of the elements in each column are the same.
sum(M) = 15 15 15
as are the sums of the elements in each row, obtained by transposing:
sum(M') = 15 15 15
See Also
cumsum, diff, prod, trace
2-484
superiorto
Purpose Syntax Description
2superiorto
Superior class relationship
superiorto('class1','class2',...)
The superiorto function establishes a hierarchy that determines the order in which MATLAB calls object methods.
superiorto('class1','class2',...) invoked within a class constructor method (say myclass.m) indicates that myclass's method should be invoked if a function is called with an object of class myclass and one or more objects of class class1, class2, and so on.
Remarks
Suppose A is of class 'class_a', B is of class 'class_b' and C is of class 'class_c'. Also suppose the constructor class_c.m contains the statement: superiorto('class_a'). Then e = fun(a,c) or e = fun(c,a) invokes class_c/fun. If a function is called with two objects having an unspecified relationship, the two objects are considered to have equal precedence, and the leftmost object's method is called. So, fun(b,c) calls class_b/fun, while fun(c,b) calls class_c/fun.
See Also
inferiorto
2-485
support
Purpose Syntax Description
2support
Open MathWorks Technical Support Web page
support support opens your web browser to The MathWorks Technical Support Web page at http://www.mathworks.com/support.
This page contains the following items: A Solution Search Engine The "Virtual Technical Support Engineer" that, through a series of questions, determines possible solutions to the problems you are experiencing Technical Notes Tutorials Bug fixes and patches
See Also
web
2-486
surf, surfc
Purpose Syntax
2surf, surfc
3-D shaded surface plot
surf(Z) surf(X,Y,Z) surf(X,Y,Z,C) surf(...,'PropertyName',PropertyValue) surfc(...) h = surf(...) h = surfc(...)
Description
Use surf and surfc to view mathematical functions over a rectangular region. surf and surfc create colored parametric surfaces specified by X, Y, and Z, with color specified by Z or C.
surf(Z) creates a a three-dimensional shaded surface from the z components in matrix Z, using x = 1:n and y = 1:m, where [m,n] = size(Z). The height, Z, is a single-valued function defined over a geometrically rectangular grid. Z
specifies the color data as well as surface height, so color is proportional to surface height.
surf(X,Y,Z) creates a shaded surface using Z for the color data as well as surface height. X and Y are vectors or matrices defining the x and y components of a surface. If X and Y are vectors, length(X) = n and length(Y) = m, where [m,n] = size(Z). In this case, the vertices of the surface faces are
( X ( j ), Y ( i ), Z ( i, j ) ) triples.
surf(X,Y,Z,C) creates a shaded surface, with color defined by C. MATLAB
performs a linear transformation on this data to obtain colors from the current colormap.
surf(...,'PropertyName',PropertyValue) specifies surface properties along
with the data.
surfc(...) draws a contour plot beneath the surface. h = surf(...) and h = surfc(...) return a handle to a surface graphics
object.
2-487
surf, surfc
Algorithm
Abstractly, a parametric surface is parametrized by two independent variables, i and j, which vary continuously over a rectangle; for example, 1 i m and 1 j n. The three functions, x(i,j), y(i,j), and z(i,j), specify the surface. When i and j are integer values, they define a rectangular grid with integer grid points. The functions x(i,j), y(i,j), and z(i,j) become three m-by-n matrices, X, Y and Z. surface color is a fourth function, c(i,j), denoted by matrix C. Each point in the rectangular grid can be thought of as connected to its four nearest neighbors.
i1,j | i,j1 i,j i,j+1 | i+1,j
This underlying rectangular grid induces four-sided patches on the surface. To express this another way, [X(:) Y(:) Z(:)] returns a list of triples specifying points in 3-space. Each interior point is connected to the four neighbors inherited from the matrix indexing. Points on the edge of the surface have three neighbors; the four points at the corners of the grid have only two neighbors. This defines a mesh of quadrilaterals or a quad-mesh. Surface color can be specified in two different ways at the vertices or at the centers of each patch. In this general setting, the surface need not be a single-valued function of x and y. Moreover, the four-sided surface patches need not be planar. For example, you can have surfaces defined in polar, cylindrical, and spherical coordinate systems. The shading function sets the shading. If the shading is interp, C must be the same size as X, Y, and Z; it specifies the colors at the vertices. The color within a surface patch is a bilinear function of the local coordinates. If the shading is faceted (the default) or flat, C(i,j) specifies the constant color in the surface patch:
(i,j) (i,j+1) | C(i,j) | (i+1,j) (i+1,j+1)
2-488
surf, surfc
In this case, C can be the same size as X, Y, and Z and its last row and column are ignored, Alternatively, its row and column dimensions can be one less than those of X, Y, and Z. The surf and surfc functions specify the view point using view(3). The range of X, Y, and Z, or the current setting of the axes XLimMode, YLimMode, and ZLimMode properties (also set by the axis function) determine the axis labels. The range of C, or the current setting of the axes CLim and ClimMode properties (also set by the caxis function) determine the color scaling. The scaled color values are used as indices into the current colormap.
Examples
Display a surface and contour plot of the peaks surface.
[X,Y,Z] = peaks(30); surfc(X,Y,Z) colormap hsv axis([-3 3 -3 3 -10 5])
5
0
-5
-10 3 2 1 0 -1 -2 -3 -3 -2 0 -1 1 2 3
Color a sphere with the pattern of +1s and -1s in a Hadamard matrix.
2-489
surf, surfc
k = 5; n = 2^k1; [x,y,z] = sphere(n); c = hadamard(2^k); surf(x,y,z,c); colormap([1 1 0; 0 axis equal
1
1])
1
0.5
0
-0.5
-1 1 0.5 0 -0.5 -1 -1 0 -0.5 0.5 1
See Also
axis, caxis, colormap, contour, delaunay, mesh, pcolor, shading, trisurf, view
Properties for surface graphics objects "Creating Surfaces and Meshes" for related functions Representing a Matrix as a Surface for more examples Coloring Mesh and Surface Plots for information about how to control the coloring of surfaces
2-490
surf2patch
Purpose Syntax
2surf2patch
Convert surface data to patch data
fvc = surf2patch(h) fvc = surf2patch(Z) fvc = surf2patch(Z,C) fvc = surf2patch(X,Y,Z) fvc = surf2patch(X,Y,Z,C) fvc = surf2patch(...,'triangles') [f,v,c] = surf2patch(...) fvc = surf2patch(h) converts the geometry and color data from the surface object identified by the handle h into patch format and returns the face, vertex, and color data in the struct fvc. You can pass this struct directly to the patch
Description
command.
fvc = surf2patch(Z) calculates the patch data from the surface's ZData matrix Z. fvc = surf2patch(Z,C) calculates the patch data from the surface's ZData and CData matrices Z and C. fvc = surf2patch(X,Y,Z) calculates the patch data from the surface's XData, YData, and ZData matrices X, Y, and Z. fvc = surf2patch(X,Y,Z,C) calculates the patch data from the surface's XData, YData, ZData, and CData matrices X, Y, Z, and C. fvc = surf2patch(...,'triangles') creates triangular faces instead of the
quadrilaterals that compose surfaces.
[f,v,c] = surf2patch(...) returns the face, vertex, and color data in the three arrays f, v, and c instead of a struct.
Examples
The first example uses the sphere command to generate the XData, YData, and ZData of a surface, which is then converted to a patch. Note that the ZData (z) is passed to surf2patch as both the third and fourth arguments the third argument is the ZData and the fourth argument is taken as the CData. This is because the patch command does not automatically use the z-coordinate data for the color data, as does the surface command.
2-491
surf2patch
Also, because patch is a low-level command, you must set the view to 3-D and shading to faceted to produce the same results produced by the surf command.
[x y z] = sphere; patch(surf2patch(x,y,z,z)); shading faceted; view(3)
In the second example surf2patch calculates face, vertex, and color data from a surface whose handle has been passed as an argument.
s = surf(peaks); pause patch(surf2patch(s)); delete(s) shading faceted; view(3)
See Also
patch, reducepatch, shrinkfaces, surface, surf
"Volume Visualization" for related functions
2-492
surface
Purpose Syntax
2surface
Create surface object
surface(Z) surface(Z,C) surface(X,Y,Z) surface(X,Y,Z,C) surface(...'PropertyName',PropertyValue,...) h = surface(...)
surface is the low-level function for creating surface graphics objects. surfaces
Description
are plots of matrix data created using the row and column indices of each element as the x- and y-coordinates and the value of each element as the z-coordinate.
surface(Z) plots the surface specified by the matrix Z. Here, Z is a
single-valued function, defined over a geometrically rectangular grid.
surface(Z,C) plots the surface specified by Z and colors it according to the data in C (see "Examples"). surface(X,Y,Z) uses C = Z, so color is proportional to surface height above the
x-y plane.
surface(X,Y,Z,C) plots the parametric surface specified by X, Y and Z, with
color specified by C.
surface(x,y,Z), surface(x,y,Z,C) replaces the first two matrix arguments with vectors and must have length(x) = n and length(y) = m where [m,n] = size(Z). In this case, the vertices of the surface facets are the triples (x(j),y(i),Z(i,j)). Note that x corresponds to the columns of Z and y corresponds to the rows of Z. For a complete discussion of parametric surfaces, see the surf function. surface(...'PropertyName',PropertyValue,...) follows the X, Y, Z, and C
arguments with property name/property value pairs to specify additional surface properties. These properties are described in the "Surface Properties" section.
h = surface(...) returns a handle to the created surface object.
2-493
surface
Remarks
Unlike high-level area creation functions, such as surf or mesh, surface does not respect the settings of the figure and axes NextPlot properties. It simply adds the surface object to the current axes. If you do not specify separate color data (C), MATLAB uses the matrix (Z) to determine the coloring of the surface. In this case, color is proportional to values of Z. You can specify a separate matrix to color the surface independently of the data defining the area of the surface. You can specify properties as property name/property value pairs, structure arrays, and cell arrays (see set and get for examples of how to specify these data types).
surface provides convenience forms that allow you to omit the property name for the XData, YData, ZData, and CData properties. For example,
surface('XData',X,'YData',Y,'ZData',Z,'CData',C)
is equivalent to:
surface(X,Y,Z,C)
When you specify only a single matrix input argument,
surface(Z)
MATLAB assigns the data properties as if you specified,
surface('XData',[1:size(Z,2)],... 'YData',[1:size(Z,1)],... 'ZData',Z,... 'CData',Z)
The axis, caxis, colormap, hold, shading, and view commands set graphics properties that affect surfaces. You can also set and query surface property values after creating them using the set and get commands.
Example
This example creates a surface using the peaks M-file to generate the data, and colors it using the clown image. The ZData is a 49-by-49 element matrix, while the CData is a 200-by-320 matrix. You must set the surface's FaceColor to texturemap to use ZData and CData of different dimensions.
load clown surface(peaks,flipud(X),...
2-494
surface
'FaceColor','texturemap',... 'EdgeColor','none',... 'CDataMapping','direct') colormap(map) view(-35,45)
Note the use of the surface(Z,C) convenience form combined with property name/property value pairs. Since the clown data (X) is typically viewed with the image command, which MATLAB normally displays with 'ij' axis numbering and direct CDataMapping, this example reverses the data in the vertical direction using flipud and sets the CDataMapping property to direct.
See Also
ColorSpec, mesh, patch, pcolor, surf
Properties for surface graphics objects "Creating Surfaces and Meshes" and "Object Creation Functions" for related functions
2-495
surface
Object Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Uicontextmenu
Image
Light
Line
Patch
Rectangle
Surface
Text
Setting Default Properties
You can set default surface properties on the axes, figure, and root levels.
set(0,'DefaultSurfaceProperty',PropertyValue...) set(gcf,'DefaultSurfaceProperty',PropertyValue...) set(gca,'DefaultSurfaceProperty',PropertyValue...)
Where Property is the name of the surface property whose default value you want to set and PropertyValue is the value you are specifying. Use set and get to access the surface properties.
Property List
The following table lists all surface properties and provides a brief description of each. The property name links take you to an expanded description of the properties.
Property Description Property Value
Property Name Data Defining the Object XData
The x-coordinates of the vertices of the surface The y-coordinates of the vertices of the surface
Values: vector or matrix Values: vector or matrix
YData
2-496
surface
Property Name ZData
Property Description
Property Value
The z-coordinates of the vertices of the surface
Values: matrix
Specifying Color CData
Color data
Values: scalar, vector, or matrix Default: [] empty matrix Values: scaled, direct Default: scaled Values: ColorSpec, none, flat, interp Default: ColorSpec Values: ColorSpec, none, flat, interp Default: ColorSpec Values: ColorSpec, none,
auto
CDataMapping
Controls mapping of CData to colormap Color of face edges
EdgeColor
FaceColor
Color of face
MarkerEdgeColor
Color of marker or the edge color for filled markers Fill color for markers that are closed shapes
Default: auto
MarkerFaceColor
Values: ColorSpec, none,
auto
Default: none
Specifying Transparency AlphaData
The transparency data Transparency mapping method Transparency of the edges of patch faces
m-by-n matrix of double or
uint8 none, direct, scaled Default: scaled scalar, flat, interp Default: 1 (opaque)
AlphaDataMapping
EdgeAlpha
2-497
surface
Property Name FaceAlpha
Property Description
Property Value scalar, flat, interp, texture Default: 1 (opaque)
Transparency of the patch face
Controlling the Effects of Lights AmbientStrength
Intensity of the ambient light Controls lighting of faces pointing away from camera Intensity of diffuse light Method used to light edges
Values: scalar >=0 and <=1 Default: 0.3 Values: unlit, lit,
reverselit Default: reverselit
BackFaceLighting
DiffuseStrength
Values: scalar >=0 and <=1 Default: 0.6 Values: none, flat, gouraud,
phong
EdgeLighting
Default: none
FaceLighting
Method used to light edges
Values: none, flat, gouraud,
phong
Default: none
NormalMode
MATLAB-generated or user-specified Values: auto, manual normal vectors Default: auto Values: scalar 0 to 1 Default: 1 Values: scalar >= 1 Default: 10 Values: scalar >=0 and <=1 Default: 0.9 Values: matrix
SpecularColorReflectanc Composite color of specularly e reflected light SpecularExponent
Harshness of specular reflection Intensity of specular light Vertex normal vectors
SpecularStrength
VertexNormals
Defining Edges and Markers
2-498
surface
Property Name LineStyle
Property Description
Property Value
Linestyle of the edge. Select from five line styles. The width of the edge in points Marker symbol to plot at data points Size of marker in points
Values: -, --, :, -., none Default: - Values: scalar Default: 0.5 points Values: see Marker property Default: none Values: size in points Default: 6
LineWidth
Marker
MarkerSize
Controlling the Appearance Clipping
Clipping to axes rectangle Method of drawing and erasing the surface (useful for animation)
Values: on, off Default: on Values: normal, none, xor,
background Default: normal
EraseMode
MeshStyle
Specifies whether to draw all edge Values: both, row, column lines or just row or column edge lines Defaults: both Highlight surface when selected (Selected property set to on) Make the surface visible or invisible Values: on, off Default: on Values: on, off Default: on
SelectionHighlight
Visible
Controlling Access to Objects HandleVisibility
Determines if and when the surface's handle is visible to other functions Determines if the surface can become the current object (see the figure CurrentObject property)
Values: on, callback, off Default: on Values: on, off Default: on
HitTest
Properties Related to Callback Routine Execution
2-499
surface
Property Name BusyAction
Property Description
Property Value
Specifies how to handle callback routine interruption Defines a callback routine that executes when a mouse button is pressed on over the surface Defines a callback routine that executes when an surface is created Defines a callback routine that executes when the surface is deleted (via close or delete) Determines if callback routine can be interrupted Associates a context menu with the surface
Values: cancel, queue Default: queue Values: string or function handle Default: '' (empty string) Values: string or function handle Default: '' (empty string) Values: string or function handle Default: '' (empty string) Values: on, off Default: on (can be interrupted) Values: handle of a uicontextmenu
ButtonDownFcn
CreateFcn
DeleteFcn
Interruptible
UIContextMenu
General Information About the Surface Children Parent
Surface objects have no children The parent of a surface object is always an axes object Indicates whether the surface is in a "selected" state. User-specified label The type of graphics object (read only) User-specified data
Values: [] (empty matrix) Value: axes handle Values: on, off Default: on Value: any string Default: '' (empty string) Value: the string 'surface' Values: any matrix Default: [] (empty matrix)
Selected
Tag
Type
UserData
2-500
Surface Properties
Modifying Properties
2Surface Properties
You can set and query graphics object properties in two ways: The Property Editor is an interactive tool that enables you to see and change object property values. The set and get commands enable you to set and query the values of properties To change the default value of properties see Setting Default Property Values.
Surface Property Descriptions
This section lists property names along with the types of values each accepts. Curly braces { } enclose default values.
AlphaData
m-by-n matrix of double or uint8
The transparency data. A matrix of non-NaN values specifying the transparency of each face or vertex of the object. The AlphaData can be of class double or uint8. MATLAB determines the transparency in one of three ways: Using the elements of AlphaData as transparency values (AlphaDataMapping set to none). Using the elements of AlphaData as indices into the current alphamap (AlphaDataMapping set to direct). Scaling the elements of AlphaData to range between the minimum and maximum values of the axes ALim property (AlphaDataMapping set to scaled, the default).
AlphaDataMapping none | direct | {scaled}
Transparency mapping method. This property determines how MATLAB interprets indexed alpha data. This property can be any of the following: none - The transparency values of AlphaData are between 0 and 1 or are clamped to this range (the default). scaled - Transform the AlphaData to span the portion of the alphamap indicated by the axes ALim property, linearly mapping data values to alpha values. direct - use the AlphaData as indices directly into the alphamap. When not scaled, the data are usually integer values ranging from 1 to length(alphamap). MATLAB maps values less than 1 to the first alpha value in the alphamap, and values greater than length(alphamap) to the
2-501
Surface Properties
last alpha value in the alphamap. Values with a decimal portion are fixed to the nearest, lower integer. If AlphaData is an array unit8 integers, then the indexing begins at 0 (i.e., MATLAB maps a value of 0 to the first alpha value in the alphamap).
AmbientStrength
scalar >= 0 and <= 1
Strength of ambient light. This property sets the strength of the ambient light, which is a nondirectional light source that illuminates the entire scene. You must have at least one visible light object in the axes for the ambient light to be visible. The axes AmbientLightColor property sets the color of the ambient light, which is therefore the same on all objects in the axes. You can also set the strength of the diffuse and specular contribution of light objects. See the surface DiffuseStrength and SpecularStrength properties.
BackFaceLighting
unlit | lit | reverselit
Face lighting control. This property determines how faces are lit when their vertex normals point away from the camera. unlit face is not lit lit face lit in normal way reverselit face is lit as if the vertex pointed towards the camera This property is useful for discriminating between the internal and external surfaces of an object. See Back Face Lighting for an example.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control how MATLAB handles events that potentially interrupt executing callback routines. If there is a callback routine executing, subsequently invoked callback routines always attempt to interrupt it. If the Interruptible property of the object whose callback is executing is set to on (the default), then interruption occurs at the next point where the event queue is processed. If the Interruptible property is off, the BusyAction property (of the object owning the executing callback) determines how MATLAB handles the event. The choices are: cancel discard the event that attempted to execute a second callback routine.
2-502
Surface Properties
queue queue the event that attempted to execute a second callback routine until the current callback finishes.
ButtonDownFcn
string or function handle
Button press callback routine. A callback routine that executes whenever you press a mouse button while the pointer is over the surface object. Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace. See Function Handle Callbacks for information on how to use function handles to define the callback function.
CData
matrix
Vertex colors. A matrix containing values that specify the color at every point in ZData. If you set the FaceColor property to texturemap, CData does not need to be the same size as ZData. In this case, MATLAB maps CData to conform to the surface defined by ZData. You can specify color as indexed values or true color. Indexed color data specifies a single value for each vertex. These values are either scaled to map linearly into the current colormap (see caxis) or interpreted directly as indices into the colormap, depending on the setting of the CDataMapping property. True color defines an RGB value for each vertex. If the coordinate data (XData for example) are contained in m-by-n matrices, then CData must be an m-by-n-3 array. The first page contains the red components, the second the green components, and the third the blue components of the colors. On computer displays that cannot display true color (e.g., 8-bit displays), MATLAB uses dithering to approximate the RGB triples using the colors in the figure's Colormap and Dithermap. By default, Dithermap uses the colorcube(64) colormap. You can also specify your own dithermap.
CDataMapping {scaled} | direct
Direct or scaled color mapping. This property determines how MATLAB interprets indexed color data used to color the surface. (If you use true color specification for CData, this property has no effect.) scaled transform the color data to span the portion of the colormap indicated by the axes CLim property, linearly mapping data values to colors. See the caxis reference page for more information on this mapping.
2-503
Surface Properties
direct use the color data as indices directly into the colormap. The color data should then be integer values ranging from 1 to length(colormap). MATLAB maps values less than 1 to the first color in the colormap, and values greater than length(colormap) to the last color in the colormap. Values with a decimal portion are fixed to the nearest, lower integer.
Children
matrix of handles
Always the empty matrix; surface objects have no children.
Clipping {on} | off
Clipping to axes rectangle. When Clipping is on, MATLAB does not display any portion of the surface that is outside the axes rectangle.
CreateFcn
string or function handle
Callback routine executed during object creation. This property defines a callback routine that executes when MATLAB creates a surface object. You must define this property as a default value for surfaces. For example, the statement,
set(0,'DefaultSurfaceCreateFcn',... 'set(gcf,''DitherMap'',my_dithermap)')
defines a default value on the root level that sets the figure DitherMap property whenever you create a surface object. MATLAB executes this routine after setting all surface properties. Setting this property on an existing surface object has no effect. The handle of the object whose CreateFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo. See Function Handle Callbacks for information on how to use function handles to define the callback function.
DeleteFcn
string or function handle
Delete surface callback routine. A callback routine that executes when you delete the surface object (e.g., when you issue a delete command or clear the axes or figure). MATLAB executes the routine before destroying the object's properties so these values are available to the callback routine. The handle of the object whose DeleteFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo.
2-504
Surface Properties
See Function Handle Callbacks for information on how to use function handles to define the callback function.
DiffuseStrength
scalar >= 0 and <= 1
Intensity of diffuse light. This property sets the intensity of the diffuse component of the light falling on the surface. Diffuse light comes from light objects in the axes. You can also set the intensity of the ambient and specular components of the light on the surface object. See the AmbientStrength and SpecularStrength properties.
EdgeAlpha {scalar = 1} | flat | interp
Transparency of the surface edges. This property can be any of the following: scalar - A single non-Nan scalar value between 0 and 1 that controls the transparency of all the edges of the object. 1 (the default) is fully opaque and 0 means completely transparent. flat - The alpha data (AlphaData) value for the first vertex of the face determines the transparency of the edges. interp - Linear interpolation of the alpha data (AlphaData) values at each vertex determine the transparency of the edge. Note that you must specify AlphaData as a matrix equal in size to ZData to use flat or interp EdgeAlpha.
EdgeColor {ColorSpec} | none | flat | interp
Color of the surface edge. This property determines how MATLAB colors the edges of the individual faces that make up the surface: ColorSpec -- A three-element RGB vector or one of the MATLAB predefined names, specifying a single color for edges. The default EdgeColor is black. See ColorSpec for more information on specifying color. none -- Edges are not drawn.
2-505
Surface Properties
flat -- The CData value of the first vertex for a face determines the color of each edge.
Direction of increasing y data
Vertex controlling the color of adjacent edges
Direction of increasing x data
interp -- Linear interpolation of the CData values at the face vertices determines the edge color.
EdgeLighting {none} | flat | gouraud | phong
Algorithm used for lighting calculations. This property selects the algorithm used to calculate the effect of light objects on surface edges. Choices are: none Lights do not affect the edges of this object. flat The effect of light objects is uniform across each edge of the surface. gouraud The effect of light objects is calculated at the vertices and then linearly interpolated across the edge lines. phong The effect of light objects is determined by interpolating the vertex normals across each edge line and calculating the reflectance at each pixel. Phong lighting generally produces better results than Gouraud lighting, but takes longer to render.
EraseMode {normal} | none | xor | background
Erase mode. This property controls the technique MATLAB uses to draw and erase surface objects. Alternative erase modes are useful for creating animated sequences, where control of the way individual objects redraw is necessary to improve performance and obtain the desired effect. normal -- Redraw the affected region of the display, performing the three-dimensional analysis necessary to ensure that all objects are rendered correctly. This mode produces the most accurate picture, but is the slowest. The other modes are faster, but do not perform a complete redraw and are therefore less accurate.
2-506
Surface Properties
none -- Do not erase the surface when it is moved or destroyed. While the object is still visible on the screen after erasing with EraseMode none, you cannot print it because MATLAB stores no information about its former location. xor -- Draw and erase the surface by performing an exclusive OR (XOR) with each pixel index of the screen behind it. Erasing the surface does not damage the color of the objects behind it. However, surface color depends on the color of the screen behind it and is correctly colored only when over the axes background Color, or the figure background Color if the axes Color is set to none. background -- Erase the surface by drawing it in the axes' background Color, or the figure background Color if the axes Color is set to none. This damages objects that are behind the erased object, but surface objects are always properly colored.
Printing with Non-normal Erase Modes. MATLAB always prints figures as if the EraseMode of all objects is normal. This means graphics objects created with EraseMode set to none, xor, or background can look different on screen than on
paper. On screen, MATLAB may mathematically combine layers of colors (e.g., XORing a pixel color with that of the pixel behind it) and ignore three-dimensional sorting to obtain greater rendering speed. However, these techniques are not applied to the printed output. You can use the MATLAB getframe command or other screen capture application to create an image of a figure containing non-normal mode objects.
FaceAlpha {scalar = 1} | flat | interp | texturemap
Transparency of the surface faces. This property can be any of the following: scalar - A single non-NaN scalar value between 0 and 1 that controls the transparency of all the faces of the object. 1 (the default) is fully opaque and 0 is completely transparent (invisible). flat - The values of the alpha data (AlphaData) determine the transparency for each face. The alpha data at the first vertex determines the transparency of the entire face. interp - Bilinear interpolation of the alpha data (AlphaData) at each vertex determine the transparency of each face. texturemap Use transparency for the texturemap.
2-507
Surface Properties
Note that you must specify AlphaData as a matrix equal in size to ZData to use flat or interp FaceAlpha.
FaceColor ColorSpec | none | {flat} | interp
Color of the surface face. This property can be any of the following: ColorSpec -- A three-element RGB vector or one of the MATLAB predefined names, specifying a single color for faces. See ColorSpec for more information on specifying color. none -- Do not draw faces. Note that edges are drawn independently of faces. flat -- The values of CData determine the color for each face of the surface. The color data at the first vertex determines the color of the entire face. interp -- Bilinear interpolation of the values at each vertex (the CData) determines the coloring of each face. texturemap -- Texture map the CData to the surface. MATLAB transforms the color data so that it conforms to the surface. (See the texture mapping example.)
FaceLighting {none} | flat | gouraud | phong
Algorithm used for lighting calculations. This property selects the algorithm used to calculate the effect of light objects on the surface. Choices are: none Lights do not affect the faces of this object. flat The effect of light objects is uniform across the faces of the surface. Select this choice to view faceted objects. gouraud The effect of light objects is calculated at the vertices and then linearly interpolated across the faces. Select this choice to view curved surfaces. phong The effect of light objects is determined by interpolating the vertex normals across each face and calculating the reflectance at each pixel. Select this choice to view curved surfaces. Phong lighting generally produces better results than Gouraud lighting, but takes longer to render.
HandleVisibility
{on} | callback | off
Control access to object's handle by command-line users and GUIs. This property determines when an object's handle is visible in its parent's list of children. This property is useful for preventing command-line users from
2-508
Surface Properties
accidentally drawing into or deleting a figure that contains only user interface devices (such as a dialog box). Handles are always visible when HandleVisibility is on. Setting HandleVisibility to callback causes handles to be visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provides a means to protect GUIs from command-line users, while allowing callback routines to have complete access to object handles. Setting HandleVisibility to off makes handles invisible at all times. This may be necessary when a callback routine invokes a function that might potentially damage the GUI (such as evaluating a user-typed string), and so temporarily hides its own handles during the execution of that function. When a handle is not visible in its parent's list of children, it cannot be returned by functions that obtain handles by searching the object hierarchy or querying handle properties. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close. When a handle's visibility is restricted using callback or off, the object's handle does not appear in its parent's Children property, figures do not appear in the root's CurrentFigure property, objects do not appear in the root's CallbackObject property or in the figure's CurrentObject property, and axes do not appear in their parent's CurrentAxes property. You can set the root ShowHiddenHandles property to on to make all handles visible, regardless of their HandleVisibility settings (this does not affect the values of the HandleVisibility properties). Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.
HitTest {on} | off
Selectable by mouse click. HitTest determines if the surface can become the current object (as returned by the gco command and the figure CurrentObject property) as a result of a mouse click on the surface. If HitTest is off, clicking on the surface selects the object below it (which maybe the axes containing it).
2-509
Surface Properties
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls whether a surface callback routine can be interrupted by subsequently invoked callback routines. Only callback routines defined for the ButtonDownFcn are affected by the Interruptible property. MATLAB checks for events that can interrupt a callback routine only when it encounters a drawnow, figure, getframe, or pause command in the routine. See the BusyAction property for related information.
LineStyle {-} | -- | : | -. | none
Edge line type. This property determines the line style used to draw surface edges. The available line styles are shown in this table.
Symbol - Line Style
solid line (default) dashed line dotted line dash-dot line no line scalar
--
: -. none LineWidth
Edge line width. The width of the lines in points used to draw surface edges. The default width is 0.5 points (1 point = 1/72 inch).
Marker
marker symbol (see table)
Marker symbol. The Marker property specifies symbols that display at vertices. You can set values for the Marker property independently from the LineStyle property.
2-510
Surface Properties
You can specify these markers.
Marker Specifier + o * . x s d ^ v > < p h Description
plus sign circle asterisk point cross square diamond upward pointing triangle downward pointing triangle right pointing triangle left pointing triangle five-pointed star (pentagram) six-pointed star (hexagram) no marker (default)
none | {auto} | flat | ColorSpec
none
MarkerEdgeColor
Marker edge color. The color of the marker or the edge color for filled markers (circle, square, diamond, pentagram, hexagram, and the four triangles). none specifies no color, which makes nonfilled markers invisible. auto uses the same color as the EdgeColor property. flat uses the CData value of the vertex to determine the color of the maker edge. ColorSpec defines a single color to use for the edge (see ColorSpec for more information).
2-511
Surface Properties
MarkerFaceColor
{none} | auto | flat | ColorSpec
Marker face color. The fill color for markers that are closed shapes (circle, square, diamond, pentagram, hexagram, and the four triangles). none makes the interior of the marker transparent, allowing the background to show through. auto uses the axes Color for the marker face color. flat uses the CData value of the vertex to determine the color of the face. ColorSpec defines a single color to use for all marker on the surface (see ColorSpec for more information).
MarkerSize
size in points
Marker size. A scalar specifying the marker size, in points. The default value for MarkerSize is six points (1 point = 1/72 inch). Note that MATLAB draws the point marker at 1/3 the specified marker size.
MeshStyle {both} | row | column
Row and column lines. This property specifies whether to draw all edge lines or just row or column edge lines. both draws edges for both rows and columns. row draws row edges only. column draws column edges only.
NormalMode {auto} | manual
MATLAB -generated or user-specified normal vectors. When this property is auto, MATLAB calculates vertex normals based on the coordinate data. If you specify your own vertex normals, MATLAB sets this property to manual and does not generate its own data. See also the VertexNormals property.
Parent
handle
Surface's parent object. The parent of a surface object is the axes in which it is displayed. You can move a surface object to another axes by setting this property to the handle of the new parent.
Selected on | {off}
Is object selected? When this property is on, MATLAB displays a dashed bounding box around the surface if the SelectionHighlight property is also
2-512
Surface Properties
on. You can, for example, define the ButtonDownFcn to set this property,
allowing users to select the object with the mouse.
SelectionHighlight {on} | off
Objects highlight when selected. When the Selected property is on, MATLAB indicates the selected state by drawing a dashed bounding box around the surface. When SelectionHighlight is off, MATLAB does not draw the handles.
SpecularColorReflectancescalar in the range 0 to 1
Color of specularly reflected light. When this property is 0, the color of the specularly reflected light depends on both the color of the object from which it reflects and the color of the light source. When set to 1, the color of the specularly reflected light depends only on the color or the light source (i.e., the light object Color property). The proportions vary linearly for values in between.
SpecularExponent
scalar >= 1
Harshness of specular reflection. This property controls the size of the specular spot. Most materials have exponents in the range of 5 to 20.
SpecularStrength
scalar >= 0 and <= 1
Intensity of specular light. This property sets the intensity of the specular component of the light falling on the surface. Specular light comes from light objects in the axes. You can also set the intensity of the ambient and diffuse components of the light on the surface object. See the AmbientStrength and DiffuseStrength properties. Also see the material function.
Tag
string
User-specified object label. The Tag property provides a means to identify graphics objects with a user-specified label. This is particularly useful when constructing interactive graphics programs that would otherwise need to define object handles as global variables or pass them as arguments between callback routines. You can define Tag as any string.
Type
string (read only)
Class of the graphics object. The class of the graphics object. For surface objects, Type is always the string 'surface'.
2-513
Surface Properties
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the surface. Assign this property the handle of a uicontextmenu object created in the same figure as the surface. Use the uicontextmenu function to create the context menu. MATLAB displays the context menu whenever you right-click over the surface.
UserData
matrix
User-specified data. Any matrix you want to associate with the surface object. MATLAB does not use this data, but you can access it using the set and get commands.
VertexNormals
vector or matrix
Surface normal vectors. This property contains the vertex normals for the surface. MATLAB generates this data to perform lighting calculations. You can supply your own vertex normal data, even if it does not match the coordinate data. This can be useful to produce interesting lighting effects.
Visible {on} | off
Surface object visibility. By default, all surfaces are visible. When set to off, the surface is not visible, but still exists and you can query and set its properties.
XData
vector or matrix
X-coordinates. The x-position of the surface points. If you specify a row vector, surface replicates the row internally until it has the same number of columns as ZData.
YData
vector or matrix
Y-coordinates. The y-position of the surface points. If you specify a row vector, surface replicates the row internally until it has the same number of rows as ZData.
ZData
matrix
Z-coordinates. Z-position of the surface points. See the Description section for more information.
2-514
surfl
Purpose Syntax
2surfl
Surface plot with colormap-based lighting
surfl(Z) surfl(X,Y,Z) surfl(...,'light') surfl(...,s) surfl(X,Y,Z,s,k) h = surfl(...)
Description
The surfl function displays a shaded surface based on a combination of ambient, diffuse, and specular lighting models.
surfl(Z) and surfl(X,Y,Z) create three-dimensional shaded surfaces using
the default direction for the light source and the default lighting coefficients for the shading model. X, Y, and Z are vectors or matrices that define the x, y, and z components of a surface.
surfl(...,'light') produces a colored, lighted surface using a MATLAB
light object. This produces results different from the default lighting method, surfl(...,'cdata'), which changes the color data for the surface to be the reflectance of the surface.
surfl(...,s) specifies the direction of the light source. s is a two- or
three-element vector that specifies the direction from a surface to a light source. s = [sx sy sz] or s = [azimuth elevation]. The default s is 45 counterclockwise from the current view direction.
surfl(X,Y,Z,s,k) specifies the reflectance constant. k is a four-element vector defining the relative contributions of ambient light, diffuse reflection, specular reflection, and the specular shine coefficient. k = [ka kd ks shine] and defaults to [.55,.6,.4,10]. h = surfl(...) returns a handle to a surface graphics object.
Remarks
For smoother color transitions, use colormaps that have linear intensity variations (e.g., gray, copper, bone, pink). The ordering of points in the X, Y, and Z matrices define the inside and outside of parametric surfaces. If you want the opposite side of the surface to reflect the
2-515
surfl
light source, use surfl(X',Y',Z'). Because of the way surface normal vectors are computed, surfl requires matrices that are at least 3-by-3.
Examples
View peaks using colormap-based lighting.
[x,y] = meshgrid(3:1/8:3); z = peaks(x,y); surfl(x,y,z); shading interp colormap(gray); axis([3 3 3 3 8 8])
To plot a lighted surface from a view direction other than the default.
view([10 10]) grid on hold on surfl(peaks) shading interp colormap copper
2-516
surfl
hold off
See Also
colormap, shading, light
"Creating Surfaces and Meshes" for functions related to surfaces "Lighting" for functions related to lighting
2-517
surfnorm
Purpose Syntax
2surfnorm
Compute and display 3-D surface normals
surfnorm(Z) surfnorm(X,Y,Z) [Nx,Ny,Nz] = surfnorm(...)
Description
The surfnorm function computes surface normals for the surface defined by X, Y, and Z. The surface normals are unnormalized and valid at each vertex. Normals are not shown for surface elements that face away from the viewer.
surfnorm(Z) and surfnorm(X,Y,Z) plot a surface and its surface normals. Z is a matrix that defines the z component of the surface. X and Y are vectors or
matrices that define the x and y components of the surface.
[Nx,Ny,Nz] = surfnorm(...) returns the components of the
three-dimensional surface normals for the surface.
Remarks
The direction of the normals is reversed by calling surfnorm with transposed arguments:
surfnorm(X',Y',Z') surfl uses surfnorm to compute surface normals when calculating the
reflectance of a surface.
Algorithm Examples
The surface normals are based on a bicubic fit of the data in X, Y, and Z. For each vertex, diagonal vectors are computed and crossed to form the normal. Plot the normal vectors for a truncated cone.
[x,y,z] = cylinder(1:10); surfnorm(x,y,z) axis([-12 12 -12 12 -0.1 1])
2-518
surfnorm
1 0.8 0.6 0.4 0.2 0 10 5 0 -5 -10 -10 -5 0 5 10
See Also
surf, quiver3
"Colormaps" for related functions
2-519
svd
Purpose Syntax
2svd
Singular value decomposition
s = svd(X) [U,S,V] = svd(X) [U,S,V] = svd(X,0)
Description
The svd command computes the matrix singular value decomposition.
s = svd(X) returns a vector of singular values. [U,S,V] = svd(X) produces a diagonal matrix S of the same dimension as X,
with nonnegative diagonal elements in decreasing order, and unitary matrices U and V so that X = U*S*V'.
[U,S,V] = svd(X,0) produces the "economy size" decomposition. If X is m-by-n with m > n, then svd computes only the first n columns of U and S is n-by-n.
Examples
For the matrix
X = 1 3 5 7 2 4 6 8
the statement
[U,S,V] = svd(X)
produces
U = -0.1525 -0.3499 -0.5474 -0.7448 S = 14.2691 0 0 0.6268 -0.8226 -0.4214 -0.0201 0.3812 -0.3945 0.2428 0.6979 -0.5462 -0.3800 0.8007 -0.4614 0.0407
2-520
svd
0 0 V = -0.6414 -0.7672
0 0
0.7672 -0.6414
The economy size decomposition generated by
[U,S,V] = svd(X,0)
produces
U = -0.1525 -0.3499 -0.5474 -0.7448 S = 14.2691 0 V = -0.6414 -0.7672 0.7672 -0.6414 0 0.6268 -0.8226 -0.4214 -0.0201 0.3812
Algorithm
svd uses LAPACK routines to compute the singular value decomposition.
Matrix
Routine DGESVD ZGESVD
Real Complex
Diagnostics
If the limit of 75 QR step iterations is exhausted while seeking a singular value, this message appears:
Solution will not converge.
References
[1] Anderson, E., Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra, J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen, LAPACK User's Guide
2-521
svd
(http://www.netlib.org/lapack/lug/lapack_lug.html), Third Edition, SIAM, Philadelphia, 1999.
2-522
svds
Purpose Syntax
2svds
A few singular values
s = svds(A) s = svds(A,k) s = svds(A,k,0) [U,S,V] = svds(A,...) svds(A) computes the five largest singular values and associated singular vectors of the matrix A. svds(A,k) computes the k largest singular values and associated singular vectors of the matrix A. svds(A,k,0) computes the k smallest singular values and associated singular
Description
vectors. With one output argument, s is a vector of singular values. With three output arguments and if A is m-by-n: U is m-by-k with orthonormal columns S is k-by-k diagonal V is n-by-k with orthonormal columns U*S*V' is the closest rank k approximation to A
Algorithm
svds(A,k) uses eigs to find the k largest magnitude eigenvalues and corresponding eigenvectors of B = [0 A; A' 0]. svds(A,k,0) uses eigs to find the 2k smallest magnitude eigenvalues and corresponding eigenvectors of B = [0 A; A' 0], and then selects the k positive eigenvalues and their eigenvectors.
Example
west0479 is a real 479-by-479 sparse matrix. svd calculates all 479 singular values. svds picks out the largest and smallest singular values. load west0479 s = svd(full(west0479)) sl = svds(west0479,4) ss = svds(west0479,6,0)
2-523
svds
These plots show some of the singular values of west0479 as computed by svd and svds.
3.19 3.185 3.18 3.175 3.17 3.165
x 10
5
4 largest singular values of west0479 svds(A,4) svd(A)
1
2
3
4
6 5 4 3 2 1 0
x 10
-5
6 smallest singular values of west0479
svds(A,6,0) svd(A) 1 2 3 4 5 6
The largest singular value of west0479 can be computed a few different ways:
svds(west0479,1) = 3.189517598808622e+05 max(svd(full(west0479))) = 3.18951759880862e+05 norm(full(west0479)) = 3.189517598808623e+05
and estimated:
normest(west0479) = 3.189385666549991e+05
See Also
svd, eigs
2-524
switch
Purpose Syntax
2switch
Switch among several cases based on expression
switch switch_expr case case_expr statement,...,statement case {case_expr1,case_expr2,case_expr3,...} statement,...,statement ... otherwise statement,...,statement end
Discussion
The switch statement syntax is a means of conditionally executing code. In particular, switch executes one set of statements selected from an arbitrary number of alternatives. Each alternative is called a case, and consists of: The case statement One or more case expressions One or more statements In its basic syntax, switch executes the statements associated with the first case where switch_expr == case_expr. When the case expression is a cell array (as in the second case above), the case_expr matches if any of the elements of the cell array match the switch expression. If no case expression matches the switch expression, then control passes to the otherwise case (if it exists). After the case is executed, program execution resumes with the statement after the end. The switch_expr can be a scalar or a string. A scalar switch_expr matches a case_expr if switch_expr==case_expr. A string switch_expr matches a case_expr if strcmp(switch_expr,case_expr) returns 1 (true).
Note for C Programmers Unlike the C language switch construct, the MATLAB switch does not "fall through." That is, switch executes only the first matching case, subsequent matching cases do not execute. Therefore, break statements are not used.
2-525
switch
Examples
To execute a certain block of code based on what the string, method, is set to,
method = 'Bilinear'; switch lower(method) case {'linear','bilinear'} disp('Method is linear') case 'cubic' disp('Method is cubic') case 'nearest' disp('Method is nearest') otherwise disp('Unknown method.') end Method is linear
See Also
case, end, if, otherwise, while
2-526
symamd
Purpose Syntax
2symamd
Symmetric approximate minimum degree permutation
p = symamd(S) p = symamd(S,knobs) [p,stats] = symamd(S) [p,stats] = symamd(S,knobs) p = symamd(S) for a symmetric positive definite matrix S, returns the permutation vector p such that S(p,p) tends to have a sparser Cholesky factor than S. To find the ordering for S, symamd constructs a matrix M such that spones(M'*M) = spones (S), and then computes p = colamd(M). The symamd
Description
function may also work well for symmetric indefinite matrices.
S must be square; only the strictly lower triangular part is referenced. knobs is a scalar. If S is n-by-n, rows and columns with more than knobs*n
entries are removed prior to ordering, and ordered last in the output permutation p. If the knobs parameter is not present, then knobs = spparms('wh_frac').
stats is an optional vector that provides data about the ordering and the validity of the matrix S. stats(1) stats(2) stats(3)
Number of dense or empty rows ignored by symamd Number of dense or empty columns ignored by symamd Number of garbage collections performed on the internal data structure used by symamd (roughly of size 8.4*nnz(tril(S,-1)) + 9n integers)
0 if the matrix is valid, or 1 if invalid
stats(4) stats(5) stats(6) stats(7)
Rightmost column index that is unsorted or contains duplicate entries, or 0 if no such column exists Last seen duplicate or out-of-order row index in the column index given by stats(5), or 0 if no such row index exists Number of duplicate and out-of-order row indices
2-527
symamd
Although, MATLAB built-in functions generate valid sparse matrices, a user may construct an invalid sparse matrix using the MATLAB C or Fortran APIs and pass it to symamd. For this reason, symamd verifies that S is valid: If a row index appears two or more times in the same column, symamd ignores the duplicate entries, continues processing, and provides information about the duplicate entries in stats(4:7). If row indices in a column are out of order, symamd sorts each column of its internal copy of the matrix S (but does not repair the input matrix S), continues processing, and provides information about the out-of-order entries in stats(4:7). If S is invalid in any other way, symamd cannot continue. It prints an error message, and returns no output arguments (p or stats) . The ordering is followed by a symmetric elimination tree post-ordering.
Note symamd tends to be faster than symmmd and tends to return a better ordering.
See Also References
colamd, colmmd, colperm, spparms, symmmd, symrcm
The authors of the code for symamd are Stefan I. Larimore and Timothy A. Davis (davis@cise.ufl.edu), University of Florida. The algorithm was developed in collaboration with John Gilbert, Xerox PARC, and Esmond Ng, Oak Ridge National Laboratory. Sparse Matrix Algorithms Research at the University of Florida: http://www.cise.ufl.edu/research/sparse/
2-528
symbfact
Purpose Syntax
2symbfact
Symbolic factorization analysis
count = symbfact(A) count = symbfact(A,'col') count = symbfact(A,'sym') [count,h,parent,post,R] = symbfact(...) count = symbfact(A) returns the vector of row counts for the upper
Description
triangular Cholesky factor of a symmetric matrix whose upper triangle is that of A, assuming no cancellation during the factorization. symbfact should be much faster than chol(A).
count = symbfact(A,'col') analyzes A' *A (without forming it explicitly). count = symbfact(A,'sym') is the same as count = symbfact(A). [count,h,parent,post,R] = symbfact(...) has several optional return
values.
h parent post R
Height of the elimination tree The elimination tree itself Postordering permutation of the elimination tree 0-1 matrix whose structure is that of chol(A)
See Also
chol, etree, treelayout
2-529
symmlq
Purpose Syntax
2symmlq
Symmetric LQ method
x = symmlq(A,b) symmlq(A,b,tol) symmlq(A,b,tol,maxit) symmlq(A,b,tol,maxit,M) symmlq(A,b,tol,maxit,M1,M2) symmlq(A,b,tol,maxit,M1,M2,x0) symmlq(afun,b,tol,maxit,m1fun,m2fun,x0,p1,p2,...) [x,flag] = symmlq(A,b,...) [x,flag,relres] = symmlq(A,b,...) [x,flag,relres,iter] = symmlq(A,b,...) [x,flag,relres,iter,resvec] = symmlq(A,b,...) [x,flag,relres,iter,resvec,resveccg] = symmlq(A,b,...) x = symmlq(A,b) attempts to solve the system of linear equations A*x=b for x. The n-by-n coefficient matrix A must be symmetric but need not be positive definite. It should also be large and sparse. The column vector b must have length n. A can be a function afun such that afun(x) returns A*x.
Description
If symmlq converges, a message to that effect is displayed. If symmlq fails to converge after the maximum number of iterations or halts for any reason, a warning message is printed displaying the relative residual norm(b-A*x)/norm(b) and the iteration number at which the method stopped or failed.
symmlq(A,b,tol) specifies the tolerance of the method. If tol is [], then symmlq uses the default, 1e-6. symmlq(A,b,tol,maxit) specifies the maximum number of iterations. If maxit is [], then symmlq uses the default, min(n,20). symmlq(A,b,tol,maxit,M) and symmlq(A,b,tol,maxit,M1,M2) use the symmetric positive definite preconditioner M or M = M1*M2 and effectively solve the system inv(sqrt(M))*A*inv(sqrt(M))*y = inv(sqrt(M))*b for y and then return x = inv(sqrt(M))*y. If M is [] then symmlq applies no preconditioner. M can be a function that returns M\x.
2-530
symmlq
symmlq(A,b,tol,maxit,M1,M2,x0) specifies the initial guess. If x0 is [], then symmlq uses the default, an all-zero vector. symmlq(afun,b,tol,maxit,m1fun,m2fun,x0,p1,p2,...) passes parameters p1,p2,... to functions afun(x,p1,p2,...), m1fun(x,p1,p2,...), and m2fun(x,p1,p2,...). [x,flag] = symmlq(A,b,tol,maxit,M1,M2,x0,p1,p2,...) also returns a
convergence flag.
Flag 0
Convergence symmlq converged to the desired tolerance tol within maxit iterations. symmlq iterated maxit times but did not converge.
1 2 3
Preconditioner M was ill-conditioned.
symmlq stagnated. (Two consecutive iterates were the
same.)
4
One of the scalar quantities calculated during symmlq became too small or too large to continue computing. Preconditioner M was not symmetric positive definite.
5
Whenever flag is not 0, the solution x returned is that with minimal norm residual computed over all the iterations. No messages are displayed if the flag output is specified.
[x,flag,relres] = symmlq(A,b,tol,maxit,M1,M2,x0,p1,p2,...) also returns the relative residual norm(b-A*x)/norm(b). If flag is 0, relres <= tol. [x,flag,relres,iter] = symmlq(A,b,tol,maxit,M1,M2,x0,p1,p2,...) also returns the iteration number at which x was computed, where 0 <= iter <= maxit.
2-531
symmlq
[x,flag,relres,iter,resvec] = symmlq(A,b,tol,maxit,M1,M2,x0,p1,p2,...) also returns a vector of estimates of the symmlq residual norms at each iteration, including norm(b-A*x0). [x,flag,relres,iter,resvec,resveccg] = symmlq(A,b,tol,maxit,M1,M2,x0,p1,p2,...) also returns a vector of
estimates of the conjugate gradients residual norms at each iteration.
Examples
Example 1.
n = 100; on = ones(n,1); A = spdiags([-2*on 4*on -2*on],-1:1,n,n); b = sum(A,2); tol = 1e-10; maxit = 50; M1 = spdiags(4*on,0,n,n); x = symmlq(A,b,tol,maxit,M1,[],[]); symmlq converged at iteration 49 to a solution with relative residual 4.3e-015
Alternatively, use this matrix-vector product function
function y = afun(x,n) y = 4 * x; y(2:n) = y(2:n) - 2 * x(1:n-1); y(1:n-1) = y(1:n-1) - 2 * x(2:n);
as input to symmlq.
x1 = symmlq(@afun,b,tol,maxit,M1,[],[],n);
Example 2.
Use a symmetric indefinite matrix that fails with pcg.
A = diag([20:-1:1,-1:-1:-20]); b = sum(A,2); % The true solution is the vector of all ones. x = pcg(A,b); % Errors out at the first iteration. pcg stopped at iteration 1 without converging to the desired tolerance 1e-006 because a scalar quantity became too small or too large to continue computing.
2-532
symmlq
The iterate returned (number 0) has relative residual 1
However, symmlq can handle the indefinite matrix A.
x = symmlq(A,b,1e-6,40); symmlq converged at iteration 39 to a solution with relative residual 1.3e-007
See Also
bicg, bicgstab, cgs, lsqr, gmres, minres, pcg, qmr @ (function handle), / (slash)
References
[1] Barrett, R., M. Berry, T. F. Chan, et al., Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia, 1994. [2] Paige, C. C. and M. A. Saunders, "Solution of Sparse Indefinite Systems of Linear Equations." SIAM J. Numer. Anal., Vol.12, 1975, pp. 617-629.
2-533
symmmd
Purpose Syntax Description
2symmmd
Sparse symmetric minimum degree ordering
p = symmmd(S) p = symmmd(S) returns a symmetric minimum degree ordering of S. For a symmetric positive definite matrix S, this is a permutation p such that S(p,p) tends to have a sparser Cholesky factor than S. Sometimes symmmd works well for symmetric indefinite matrices too.
Remarks
The minimum degree ordering is automatically used by \ and / for the solution of symmetric, positive definite, sparse linear systems. Some options and parameters associated with heuristics in the algorithm can be changed with spparms.
Algorithm
The symmetric minimum degree algorithm is based on the column minimum degree algorithm. In fact, symmmd(A) just creates a nonzero structure K such that K'*K has the same nonzero structure as A and then calls the column minimum degree code for K. Here is a comparison of reverse Cuthill-McKee and minimum degree on the Bucky ball example mentioned in the symrcm reference page.
B = bucky+4*speye(60); r = symrcm(B); p = symmmd(B); R = B(r,r); S = B(p,p); subplot(2,2,1), spy(R), title('B(r,r)') subplot(2,2,2), spy(S), title('B(s,s)') subplot(2,2,3), spy(chol(R)), title('chol(B(r,r))') subplot(2,2,4), spy(chol(S)), title('chol(B(s,s))')
Examples
2-534
symmmd
B(r,r) 0 0
B(s,s)
20
20
40
40
60 0
20 40 nz = 240 chol(B(r,r))
60
60 0
20 40 nz = 240 chol(B(s,s))
60
0
0
20
20
40
40
60 0
20 40 nz = 514
60
60 0
20 40 nz = 360
60
Even though this is a very small problem, the behavior of both orderings is typical. RCM produces a matrix with a narrow bandwidth which fills in almost completely during the Cholesky factorization. Minimum degree produces a structure with large blocks of contiguous zeros which do not fill in during the factorization. Consequently, the minimum degree ordering requires less time and storage for the factorization.
See Also References
colamd, colmmd, colperm, symamd, symrcm
[1] Gilbert, John R., Cleve Moler, and Robert Schreiber, "Sparse Matrices in MATLAB: Design and Implementation," SIAM Journal on Matrix Analysis and Applications 13, 1992, pp. 333-356.
2-535
symrcm
Purpose Syntax Description
2symrcm
Sparse reverse Cuthill-McKee ordering
r = symrcm(S) r = symrcm(S) returns the symmetric reverse Cuthill-McKee ordering of S. This is a permutation r such that S(r,r) tends to have its nonzero elements
closer to the diagonal. This is a good preordering for LU or Cholesky factorization of matrices that come from long, skinny problems. The ordering works for both symmetric and nonsymmetric S. For a real, symmetric sparse matrix, S, the eigenvalues of S(r,r) are the same as those of S, but eig(S(r,r)) probably takes less time to compute than eig(S).
Algorithm
The algorithm first finds a pseudoperipheral vertex of the graph of the matrix. It then generates a level structure by breadth-first search and orders the vertices by decreasing distance from the pseudoperipheral vertex. The implementation is based closely on the SPARSPAK implementation described by George and Liu. The statement
B = bucky
Examples
uses an M-file in the demos toolbox to generate the adjacency graph of a truncated icosahedron. This is better known as a soccer ball, a Buckminster Fuller geodesic dome (hence the name bucky), or, more recently, as a 60-atom carbon molecule. There are 60 vertices. The vertices have been ordered by numbering half of them from one hemisphere, pentagon by pentagon; then reflecting into the other hemisphere and gluing the two halves together. With this numbering, the matrix does not have a particularly narrow bandwidth, as the first spy plot shows
subplot(1,2,1), spy(B), title('B')
The reverse Cuthill-McKee ordering is obtained with
p = symrcm(B); R = B(p,p);
2-536
symrcm
The spy plot shows a much narrower bandwidth.
subplot(1,2,2), spy(R), title('B(p,p)')
B 0 10 20 30 40 50 60 0 0 10 20 30 40 50 60 0 B(p,p)
20
40 nz = 180
60
20
40 nz = 180
60
This example is continued in the reference pages for symmmd. The bandwidth can also be computed with
[i,j] = find(B); bw = max(i-j) + 1
The bandwidths of B and R are 35 and 12, respectively.
See Also References
colamd, colmmd, colperm, symamd, symmmd
[1] George, Alan and Joseph Liu, Computer Solution of Large Sparse Positive Definite Systems, Prentice-Hall, 1981. [2] Gilbert, John R., Cleve Moler, and Robert Schreiber, "Sparse Matrices in MATLAB: Design and Implementation," to appear in SIAM Journal on Matrix Analysis, 1992. A slightly expanded version is also available as a technical report from the Xerox Palo Alto Research Center.
2-537
symvar
Purpose Syntax Description
2symvar
Determine the symbolic variables in an expression
symvar 'expr' s = symvar('expr') symvar 'expr' searches the expression, expr, for identifiers other than i, j, pi, inf, nan, eps, and common functions. symvar displays those variables that it finds or, if no such variable exists, displays an empty cell array, {}. s = symvar('expr') returns the variables in a cell array of strings, s. If no such variable exists, s is an empty cell array.
Examples
symvar finds variables beta1 and x, but skips pi and the cos function. symvar 'cos(pi*x - beta1)' ans = 'beta1' 'x'
See Also
findstr
2-538
startup
Purpose Description
2startup
MATLAB startup M-file for user-defined options
startup automatically executes the master M-file matlabrc.m and, if it exists, startup.m, when MATLAB starts. On multiuser or networked systems, matlabrc.m is reserved for use by the system manager. The file matlabrc.m invokes the file startup.m if it exists on the MATLAB search path.
You can create a startup.m file in your own MATLAB directory. The file can include physical constants, Handle Graphics defaults, engineering conversion factors, or anything else you want predefined in your workspace. There are other way to predefine aspects of MATLAB. See "Startup Options" and "Setting Preferences" in the MATLAB documentation.
Algorithm
Only matlabrc.m is actually invoked by MATLAB at startup. However, matlabrc.m contains the statements
if exist('startup')==2 startup end
that invoke startup.m. You can extend this process to create additional startup M-files, if required.
See Also
matlabrc, matlabroot, quit
2-539
system
Purpose Description
2system
Run operating system command and return result
system('command') calls upon the operating system to run command, for example dir or ls, and directs the output to MATLAB. If command runs successfully, ans is 0. If command fails or does not exist on your operating system, ans is a nonzero value and an explanatory message appears. [status, result] = system('command') calls upon the operating system to run command, and directs the output to MATLAB. If command runs successfully, status is 0 and result contains the output from command. If command fails or does not exist on your operating system, status is a nonzero value, result is an empty matrix, and an explanatory message appears.
Examples
Display the current directory by accessing the operating system.
system('pwd')
MATLAB displays the current directory and shows that the command executed correctly because ans is 0.
D:/mymfiles/ ans = 0
Similarly, run the operating system pwd command and assign the current directory to curr_dir.
[s, curr_dir] = system('pwd')
MATLAB displays
s = 0 curr_dir = D:/mymfiles/
See Also
! (exclamation point), dos, perl, unix
2-540
tan
Purpose Syntax Description
2tan
Tangent
Y = tan(X)
The tan function operates element-wise on arrays. The function's domains and ranges include complex values. All angles are in radians.
Y = tan(X) returns the circular tangent of each element of X.
Examples
Graph the tangent function over the domain / 2 < x < / 2 .
x = (-pi/2)+0.01:0.01:(pi/2)-0.01; plot(x,tan(x)), grid on
100 80 60 40 20 0 -20 -40 -60 -80 -100 -2 -1.5 -1 -0.5 0 0.5 1 1.5 2
The expression tan(pi/2) does not evaluate as infinite but as the reciprocal of the floating point accuracy eps since pi is only a floating-point approximation to the exact value of .
Definition
The tangent can be defined as sin ( z ) tan ( z ) = ---------------cos ( z )
2-541
tan
Algorithm
tan uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see http://www.netlib.org.
See Also
atan, atan2, tanh
2-542
tanh
Purpose Syntax Description
2tanh
Hyperbolic tangent
Y = tanh(X)
The tanh function operates element-wise on arrays. The function's domains and ranges include complex values. All angles are in radians.
Y = tanh(X) returns the hyperbolic tangent of each element of X.
Examples
Graph the hyperbolic tangent function over the domain 5 x 5 .
x = -5:0.01:5; plot(x,tanh(x)), grid on
1 0.8 0.6 0.4 0.2 0 -0.2 -0.4 -0.6 -0.8 -1 -5 0 5
Definition
The hyperbolic tangent can be defined as sinh ( z ) tanh ( z ) = ------------------cosh ( z )
Algorithm
tanh uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see http://www.netlib.org.
2-543
tanh
See Also
atan, atan2, tan
2-544
tempdir
Purpose Syntax Description
2tempdir
Return the name of the system's temporary directory
tmp_dir = tempdir tmp_dir = tempdir returns the name of the system's temporary directory, if
one exists. This function does not create a new directory. See Opening Temporary Files and Directories for more information.
See Also
tempname
2-545
tempname
Purpose Syntax Description
2tempname
Unique name for temporary file
tmp_nam = tempname tmp_nam = tempname returns a unique string, tmp_nam, suitable for use as a
temporary filename.
Note The filename that tempname generates is not guaranteed to be unique; however, it is likely to be so.
See Opening Temporary Files and Directories for more information.
See Also
tempdir
2-546
terminal
Purpose
2terminal
Set graphics terminal type
Note The terminal function will be removed in a future release.
Syntax Description
terminal terminal('type')
To add terminal-specific settings (e.g., escape characters, line length), edit the file terminal.m.
terminal displays a menu of graphics terminal types, prompts for a choice,
then configures MATLAB to run on the specified terminal.
terminal('type') accepts a terminal type string. Valid 'type' strings are
shown in the table.
Type tek401x tek4100 tek4105 retro sg100 sg200 vt240tek ergo graphon citoh xtermtek Description
Tektronix 4010/4014 Tektronix 4100 Tektronix 4105 Retrographics card Selanar Graphics 100 Selanar Graphics 200 VT240 & VT340 Tektronix mode Ergo terminal Graphon terminal C.Itoh terminal xterm, Tektronix graphics
2-547
terminal
Type wyse kermit hp2647 hds
Description (Continued)
Wyse WY-99GT MS-DOS Kermit 2.23 Hewlett-Packard 2647 Human Designed Systems
2-548
tetramesh
Purpose Syntax
2tetramesh
Tetrahedron mesh plot
tetramesh(T,X,c) tetramesh(T,X) h = tetramesh(...) tetramesh(...,'param','value','param','value'...) tetramesh(T,X,c) displays the tetrahedrons defined in the m-by-4 matrix T as mesh. T is usually the output of delaunayn. A row of T contains indices into X of the vertices of a tetrahedron. X is an n-by-3 matrix, representing n points in 3 dimension. The tetrahedron colors are defined by the vector C, which is used as indices into the current colormap.
Description
Note If T is the output of delaunay3, then X is the concatenation of the delaunay3 input arguments x, y, z interpreted as column vectors, i.e., X = [x(:) y(:) z(:)].
tetramesh(T,X) uses C = 1:m as the color for the m tetrahedrons. Each
tetrahedron has a different color (modulo the number of colors available in the current colormap).
h = tetramesh(...) returns a vector of tetrahedron handles. Each element of h is a handle to the set of patches forming one tetrahedron. You can use these handles to view a particular tetrahedron by turning the patch 'Visible' property 'on' or 'off'. tetramesh(...,'param','value','param','value'...) allows additional patch property name/property value pairs to be used when displaying the tetrahedrons. For example, the default transparency parameter is set to 0.9. You can overwrite this value by using the property name/property value pair ('FaceAlpha',value) where value is a number between 0 and 1. See Patch Properties for information about the available properties.
Examples
Generate a 3-dimensional Delaunay tesselation, then use tetramesh to visualize the tetrahedrons that form the corresponding simplex.
d = [-1 1];
2-549
tetramesh
[x,y,z] = meshgrid(d,d,d); % A cube x = [x(:);0]; y = [y(:);0]; z = [z(:);0]; % [x,y,z] are corners of a cube plus the center. X = [x(:) y(:) z(:)]; Tes = delaunayn(X) Tes = 9 3 2 2 2 7 7 8 8 8 8 8
1 9 9 3 3 9 3 7 2 2 3 7
5 1 1 9 9 5 9 9 9 9 9 3
6 5 6 4 1 6 5 6 6 4 4 9
tetramesh(Tes,X);camorbit(20,0)
2-550
tetramesh
See Also
delaunayn, patch, Patch Properties, trimesh, trisurf
2-551
texlabel
Purpose Syntax Description
2texlabel
Produce TeX format from character string
texlabel(f) texlabel(f,'literal') texlabel(f) converts the MATLAB expression f into the TeX equivalent for
use in text strings. It processes Greek variable names (e.g., lambda, delta, etc.) into a string that displays as actual Greek letters.
texlabel(f,'literal') prints Greek variable names as literals.
If the string is too long to fit into a figure window, then the center of the expression is replaced with a tilde ellipsis (~~~).
Examples
You can use texlabel as an argument to the title, xlabel, ylabel, zlabel, and text commands. For example,
title(texlabel('sin(sqrt(x^2 + y^2))/sqrt(x^2 + y^2)'))
By default, texlabel translates Greek variable names to the equivalent Greek letter. You can select literal interpretation by including the literal argument. For example, compare these two commands.
text(.5,.5,... texlabel('lambda12^(3/2)/pi - pi*delta^(2/3)')) text(.25,.25,... texlabel('lambda12^(3/2)/pi - pi*delta^(2/3)','literal'))
2-552
texlabel
1
0.9
0.8
0.7
0.6
0.5
3/2 / 12
- 2/3
0.4
0.3
lambda12
0.2
3/2
/pi - pi delta
2/3
0.1
0
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
See Also
text, title, xlabel, ylabel, zlabel, the text String property
"Annotating Plots" for related functions
2-553
text
Purpose Syntax
2text
Create text object in current axes
text(x,y,'string') text(x,y,z,'string') text(...'PropertyName',PropertyValue...) h = text(...) text is the low-level function for creating text graphics objects. Use text to
Description
place character strings at specified locations.
text(x,y,'string') adds the string in quotes to the location specified by the point (x,y). text(x,y,z,'string') adds the string in 3-D coordinates. text(x,y,z,'string','PropertyName',PropertyValue....) adds the string
in quotes to location defined by the coordinates and uses the values for the specified text properties. See the text property list section at the end of this page for a list of text properties.
text('PropertyName',PropertyValue....) omits the coordinates entirely
and specifies all properties using property name/property value pairs.
h = text(..) returns a column vector of handles to text objects, one handle per object. All forms of the text function optionally return this output
argument. See the String property for a list of symbols, including Greek letters.
Remarks
Specify the text location coordinates (the x, y, and z arguments) in the data units of the current axes (see "Examples"). The Extent, VerticalAlignment, and HorizontalAlignment properties control the positioning of the character string with regard to the text location point. If the coordinates are vectors, text writes the string at all locations defined by the list of points. If the character string is an array the same length as x, y, and z, text writes the corresponding row of the string array at each point specified. When specifying strings for multiple text objects, the string can be a cell array of strings
2-554
text
a padded string matrix a string vector using vertical slash characters (`|') as separators. Each element of the specified string array creates a different text object. When specifying the string for a single text object, cell arrays of strings and padded string matrices result in a text object with a multiline string, while vertical slash characters are not interpreted as separators and result in a single line string containing vertical slashes.
text is a low-level function that accepts property name/property value pairs as
input arguments, however; the convenience form,
text(x,y,z,'string')
is equivalent to:
text('XData',x,'YData',y,'ZData',z,'String','string')
You can specify other properties only as property name/property value pairs. See the text property list at the end of this page for a description of each property. You can specify properties as property name/property value pairs, structure arrays, and cell arrays (see the set and get reference pages for examples of how to specify these data types).
text does not respect the setting of the figure or axes NextPlot property. This allows you to add text objects to an existing axes without setting hold to on.
Examples
The statements,
plot(0:pi/20:2*pi,sin(0:pi/20:2*pi)) text(pi,0,' \leftarrow sin(\pi)','FontSize',18)
2-555
text
annotate the point at (pi,0) with the string sin().
1
0.8
0.6
0.4
0.2
0
sin()
-0.2
-0.4
-0.6
-0.8
-1
0
1
2
3
4
5
6
7
The statement,
text(x,y,'\ite^{i\omega\tau} = cos(\omega\tau) + i sin(\omega\tau)')
uses embedded TeX sequences to produce:
i e = cos() + i sin()
See Also
gtext, int2str, num2str, title, xlabel, ylabel, zlabel
The "Labeling Graphs" topic in the online Using MATLAB Graphics manual discusses positioning text.
2-556
text
Object Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Uicontextmenu
Image
Light
Line
Patch
Rectangle
Surface
Text
Setting Default Properties
You can set default text properties on the axes, figure, and root levels.
set(0,'DefaulttextProperty',PropertyValue...) set(gcf,'DefaulttextProperty',PropertyValue...) set(gca,'DefaulttextProperty',PropertyValue...)
Where Property is the name of the text property and PropertyValue is the value you are specifying. Use set and get to access text properties.
Property List
The following table lists all text properties and provides a brief description of each. The property name links take you to an expanded description of the properties.
Property Description Property Value
Property Name
Defining the character string Editing
Enable or disable editing mode. Enable or disable TeX interpretation The character string (including list of TeX character sequences)
Values: on, off Default: off Values: tex, none Default: tex Value: character string
Interpreter
String
2-557
text
Property Name
Property Description
Property Value
Positioning the character string Extent
Position and size of text object Horizontal alignment of text string Position of text Extent rectangle Orientation of text object Units for Extent and Position properties
Values: [left, bottom, width, height] Values: left, center, right Default: left Values: [x, y, z] coordinates Default: [] empty matrix Values: scalar (degrees) Default: 0 Values: pixels, normalized, inches, centimeters, points, data Default: data Values: top, cap, middle, baseline, bottom Default: middle
HorizontalAlignment
Position
Rotation
Units
VerticalAlignment
Vertical alignment of text string
Text Bounding Box BackgroundColor
Color of text extent rectangle Color of edge drawn around text extent rectangle Width of the line (in points) use to draw the box drawn around text extent rectangle Style of the line use to draw the box drawn around text extent rectangle Distance in pixels from the text extent to the edge of the box enclosing the text.
Values: ColorSpec Default: none Values: ColorSpec Default: none Values: scalar (points) Default: 0.5 Values: -, --, :, -., none Default: - Values: scalar (pixels) Default: 2
EdgeColor
LineWidth
LineStyle
Margin
2-558
text
Property Name Specifying the Font FontAngle
Property Description
Property Value
Select italic-style font
Values: normal, italic, oblique Default: normal Values: a font supported by your system or the string
FixedWidth Default: Helvetica
FontName
Select font family
FontSize
Size of font Units for FontSize property
Values: size in FontUnits Default: 10 points Values: points, normalized, inches, centimeters, pixels Default: points Values: light, normal, demi,
bold
FontUnits
FontWeight
Weight of text characters
Default: normal
Controlling the Appearance Clipping
Clipping to axes rectangle Method of drawing and erasing the text (useful for animation) Highlight text when selected (Selected property set to on) Make the text visible or invisible Color of the text
Values: on, off Default: on Values: normal, none, xor,
background Default: normal
EraseMode
SelectionHighlight
Values: on, off Default: on Values: on, off Default: on
ColorSpec
Visible
Color
Controlling Access to Text Objects
2-559
text
Property Name HandleVisibility
Property Description
Property Value
Determines if and when the the text's handle is visible to other functions Determines if the text can become the current object (see the figure CurrentObject property)
Values: on, callback, off Default: on Values: on, off Default: on
HitTest
General Information About Text Objects Children Parent
Text objects have no children The parent of a text object is always an axes object Indicate whether the text is in a "selected" state. User-specified label The type of graphics object (read only) User-specified data
Values: [] (empty matrix) Value: axes handle Values: on, off Default: off Value: any string Default: '' (empty string) Value: the string 'text' Values: any matrix Default: [] (empty matrix)
Selected
Tag
Type
UserData
Controlling Callback Routine Execution BusyAction
Specifies how to handle callback routine interruption Defines a callback routine that executes when a mouse button is pressed on over the text Defines a callback routine that executes when an text is created
Values: cancel, queue Default: queue Values: string or function handle Default: '' (empty string) Values: string or function handle Default: '' (empty string)
ButtonDownFcn
CreateFcn
2-560
text
Property Name DeleteFcn
Property Description
Property Value
Defines a callback routine that executes when the text is deleted (via close or delete) Determines if callback routine can be interrupted Associates a context menu with the text
Values: string or function handle Default: '' (empty string) Values: on, off Default: on (can be interrupted) Values: handle of a uicontextmenu
Interruptible
UIContextMenu
2-561
Text Properties
Modifying Properties
2Text Properties
You can set and query graphics object properties using the property editor or the set and get commands. The Property Editor is an interactive tool that enables you to see and change object property values. The set and get commands enable you to set and query the values of properties To change the default value of properties see Setting Default Property Values.
Text Property Descriptions
This section lists property names along with the types of values each accepts. Curly braces { } enclose default values.
BackgroundColor ColorSpec | {none}
Color of text extent rectangle. This property enables you define a color for the rectangle that encloses the text Extent. For example, the following code creates a text object that labels a plot and sets the background color to light green.
text(3*pi/4,sin(3*pi/4),... ['sin(3*pi/4) = ',num2str(sin(3*pi/4))],... 'HorizontalAlignment','center',... 'BackgroundColor',[.7 .9 .7]);
1 0.8 0.6 0.4 0.2 0 -0.2 -0.4 -0.6 -0.8 -1 0 1 2 3 4 5 6 7 sin(3*pi/4) = 0.70711
For additional features, see the following properties: EdgeColor -- Color of the rectangle's edge (none by default). LineStyle -- Style of the rectangle's edge line (first set EdgeColor).
2-562
Text Properties
LineWidth -- Width of the rectangle's edge line (first set EdgeColor) Margin -- Increase the size of the rectangle by adding a margin to the existing text extent rectangle. See also "Drawing Text in a Box" in the MATLAB Graphics documentation for an example using background color with contour labels.
BusyAction cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control how MATLAB handles events that potentially interrupt executing callback routines. If there is a callback routine executing, subsequently invoked callback routines always attempt to interrupt it. If the Interruptible property of the object whose callback is executing is set to on (the default), then interruption occurs at the next point where the event queue is processed. If the Interruptible property is set to off, the BusyAction property (of the object owning the executing callback) determines how MATLAB handles the event. The choices are: cancel -- Discard the event that attempted to execute a second callback routine queue -- Queue the event that attempted to execute a second callback routine until the current callback finishes
ButtonDownFcn
string or function handle
Button press callback routine. A callback routine that executes whenever you press a mouse button while the pointer is over the text object. Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace. See Function Handle Callbacks for information on how to use function handles to define the callback function.
Children
matrix (read only)
The empty matrix; text objects have no children.
Clipping on | {off}
Clipping mode. When Clipping is on, MATLAB does not display any portion of the text that is outside the axes.
2-563
Text Properties
Color
ColorSpec
Text color. A three-element RGB vector or one of the predefined names, specifying the text color. The default value for Color is white. See ColorSpec for more information on specifying color.
CreateFcn
string or function handle
Callback routine executed during object creation. This property defines a callback routine that executes when MATLAB creates a text object. You must define this property as a default value for text. For example, the statement,
set(0,'DefaultTextCreateFcn',... 'set(gcf,''Pointer'',''crosshair'')')
defines a default value on the root level that sets the figure Pointer property to a crosshair whenever you create a text object. MATLAB executes this routine after setting all text properties. Setting this property on an existing text object has no effect. The handle of the object whose CreateFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo. See Function Handle Callbacks for information on how to use function handles to define the callback function.
DeleteFcn
string or function handle
Delete text callback routine. A callback routine that executes when you delete the text object (e.g., when you issue a delete command or clear the axes or figure). MATLAB executes the routine before destroying the object's properties so these values are available to the callback routine. The handle of the object whose DeleteFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo. See Function Handle Callbacks for information on how to use function handles to define the callback function.
EdgeColor ColorSpec | {none}
Color of edge drawn around text extent rectangle. This property enables you to specify the color of a box drawn around the text Extent. For example, the following code draws a red rectangle around text that labels a plot.
text(3*pi/4,sin(3*pi/4),...
2-564
Text Properties
'\leftarrowsin(t) = .707',... 'EdgeColor','red');
1 0.8 0.6 0.4 0.2 0 -0.2 -0.4 -0.6 -0.8 -1 0 1 2 3 4 5 6 7 sin(t) = .707
For additional features, see the following properties: BackgroundColor -- Color of the rectangle's interior (none by default). LineStyle -- Style of the rectangle's edge line (first set EdgeColor). LineWidth -- Width of the rectangle's edge line (first set EdgeColor) Margin -- Increase the size of the rectangle by adding a margin to the existing text extent rectangle.
Editing on | {off}
Enable or disable editing mode. When this property is set to the default off, you cannot edit the text string interactively (i.e., you must change the String property to change the text). When this property is set to on, MATLAB places an insert cursor at the beginning of the text string and enables editing. To apply the new text string
1 Press the ESC key. 2 Clicking in any figure window (including the current figure). 3 Reset the Editing property to off.
MATLAB then updates the String property to contain the new text and resets the Editing property to off. You must reset the Editing property to on to resume editing.
2-565
Text Properties
EraseMode
{normal} | none | xor | background
Erase mode. This property controls the technique MATLAB uses to draw and erase text objects. Alternative erase modes are useful for creating animated sequences where controlling the way individual objects redraw is necessary to improve performance and obtain the desired effect. normal -- Redraw the affected region of the display, performing the three-dimensional analysis necessary to ensure that all objects are rendered correctly. This mode produces the most accurate picture, but is the slowest. The other modes are faster, but do not perform a complete redraw and are therefore, less accurate. none -- Do not erase the text when it is moved or destroyed. While the object is still visible on the screen after erasing with EraseMode none, you cannot print it because MATLAB stores no information about its former location. xor -- Draw and erase the text by performing an exclusive OR (XOR) with each pixel index of the screen beneath it. When the text is erased, it does not damage the objects beneath it. However, when text is drawn in xor mode, its color depends on the color of the screen beneath it. It is correctly colored only when over axes background Color, or the figure background Color if the axes Color is set to none. background -- Erase the text by drawing it in the axes background Color, or the figure background Color if the axes Color is set to none. This damages objects that are behind the erased text, but text is always properly colored.
Printing with Nonnormal Erase Modes. MATLAB always prints figures as if the EraseMode of all objects is set to normal. This means graphics objects created with EraseMode set to none, xor, or background can look differently on screen
than on paper. On screen, MATLAB may mathematically combine layers of colors (e.g., XORing a pixel color with that of the pixel behind it) and ignore three-dimensional sorting to obtain greater rendering speed. However, these techniques are not applied to the printed output. You can use the MATLAB getframe command or other screen capture application to create an image of a figure containing nonnormal mode objects.
Extent
position rectangle (read only)
Position and size of text. A four-element read-only vector that defines the size and position of the text string
2-566
Text Properties
[left,bottom,width,height]
If the Units property is set to data (the default), left and bottom are the x and y coordinates of the lower left corner of the text Extent. For all other values of Units, left and bottom are the distance from the lower left corner of the axes position rectangle to the lower left corner of the text Extent. width and height are the dimensions of the Extent rectangle. All measurements are in units specified by the Units property.
FontAngle {normal} | italic | oblique
Character slant. MATLAB uses this property to select a font from those available on your particular system. Generally, setting this property to italic or oblique selects a slanted font.
FontName
A name, such as Courier, or the string FixedWidth
Font family. A string specifying the name of the font to use for the text object. To display and print properly, this must be a font that your system supports. The default font is Helvetica.
Specifying a Fixed-Width Font
If you want text to use a fixed-width font that looks good in any locale, you should set FontName to the string FixedWidth:
set(text_handle,'FontName','FixedWidth')
This eliminates the need to hard code the name of a fixed-width font, which may not display text properly on systems that do not use ASCII character encoding (such as in Japan where multibyte character sets are used). A properly written MATLAB application that needs to use a fixed-width font should set FontName to FixedWidth (note that this string is case sensitive) and rely on FixedWidthFontName to be set correctly in the end-user's environment. End users can adapt a MATLAB application to different locales or personal environments by setting the root FixedWidthFontName property to the appropriate value for that locale from startup.m. Note that setting the root FixedWidthFontName property causes an immediate update of the display to use the new font.
2-567
Text Properties
FontSize
size in FontUnits
Font size. An integer specifying the font size to use for text in units determined by the FontUnits property. The default point size is 10 (1 point = 1/72 inch).
FontWeight light | {normal} | demi | bold
Weight of text characters. MATLAB uses this property to select a font from those available on your particular system. Generally, setting this property to bold or demi causes MATLAB to use a bold font.
FontUnits {points} | normalized | inches | centimeters | pixels
Font size units. MATLAB uses this property to determine the units used by the FontSize property. Normalized units interpret FontSize as a fraction of the height of the parent axes. When you resize the axes, MATLAB modifies the screen FontSize accordingly. pixels, inches, centimeters, and points are absolute units (1 point = 1/72 inch).
HandleVisibility {on} | callback | off
Control access to object's handle by command-line users and GUIs. This property determines when an object's handle is visible in its parent's list of children. HandleVisibility is useful for preventing command-line users from accidentally drawing into or deleting a figure that contains only user interface devices (such as a dialog box). Handles are always visible when HandleVisibility is set to on. Setting HandleVisibility to callback causes handles to be visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provides a means to protect GUIs from command-line users, while allowing callback routines to have complete access to object handles. Setting HandleVisibility to off makes handles invisible at all times. This may be necessary when a callback routine invokes a function that might potentially damage the GUI (such as evaluating a user-typed string), and so temporarily hides its own handles during the execution of that function. When a handle is not visible in its parent's list of children, it cannot be returned by functions that obtain handles by searching the object hierarchy or querying handle properties. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close.
2-568
Text Properties
When a handle's visibility is restricted using callback or off: The object's handle does not appear in its parent's Children property. Figures do not appear in the root's CurrentFigure property. Objects do not appear in the root's CallbackObject property or in the figure's CurrentObject property. Axes do not appear in their parent's CurrentAxes property. You can set the root ShowHiddenHandles property to on to make all handles visible, regardless of their HandleVisibility settings (this does not affect the values of the HandleVisibility properties). Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.
HitTest {on} | off
Selectable by mouse click. HitTest determines if the text can become the current object (as returned by the gco command and the figure CurrentObject property) as a result of a mouse click on the text. If HitTest is set to off, clicking on the text selects the object below it (which is usually the axes containing it). For example, suppose you define the button down function of an image (see the
ButtonDownFcn property) to display text at the location you click on with the
mouse. First define the callback routine.
function bd_function pt = get(gca,'CurrentPoint'); text(pt(1,1),pt(1,2),pt(1,3),... '{\fontsize{20}\oplus} The spot to label',... 'HitTest','off')
Now display an image, setting its ButtonDownFcn property to the callback routine.
load earth image(X,'ButtonDownFcn','bd_function'); colormap(map)
When you click on the image, MATLAB displays the text string at that location. With HitTest set to off, existing text cannot intercept any subsequent button
2-569
Text Properties
down events that occur over the text. This enables the image's button down function to execute.
HorizontalAlignment{left} | center | right
Horizontal alignment of text. This property specifies the horizontal justification of the text string. It determines where MATLAB places the string with regard to the point specified by the Position property. The following picture illustrates the alignment options.
HorizontalAlignment viewed with the VerticalAlignment set to middle
(the default).
Left
Center
Right
See the Extent property for related information.
Interpreter {tex} | none
Interpret Tex instructions. This property controls whether MATLAB interprets certain characters in the String property as Tex instructions (default) or displays all characters literally. See the String property for a list of supported Tex instructions.
Interruptible {on} | off
Callback routine interruption mode. The Interruptible property controls whether a text callback routine can be interrupted by subsequently invoked callback routines. Text objects have three properties that define callback routines: ButtonDownFcn, CreateFcn, and DeleteFcn. See the BusyAction property for information on how MATLAB executes callback routines.
LineStyle {-} | -- | : | -. | none
Edge line type. This property determines the line style used to draw the edges of the text Extent. The available line styles are shown in the following table.
Symbol - Line Style
solid line (default) dashed line
--
2-570
Text Properties
Symbol : -. none
Line Style
dotted line dash-dot line no line
For example, the following code draws a red rectangle wth a dotted line style around text that labels a plot.
text(3*pi/4,sin(3*pi/4),... '\leftarrowsin(t) = .707',... 'EdgeColor','red',... 'LineWidth',2,... 'LineStyle',':');
1 0.8 0.6 0.4 0.2 0 -0.2 -0.4 -0.6 -0.8 -1 0 1 2 3 4 5 6 7 sin(t) = .707
For additional features, see the following properties: BackgroundColor -- Color of the rectangle's interior (none by default) EdgeColor -- Color of the rectangle's edge (none by default) LineWidth -- Width of the rectangle's edge line (first set EdgeColor) Margin -- Increase the size of the rectangle by adding a margin to the existing text extent rectangle
2-571
Text Properties
LineWidth
scalar (points)
Width of line used to draw text extent rectangle. When you set the text EdgeColor property to a color (the default is none), MATLAB displays a rectangle around the text Extent. Use the LineWidth property to specify the width of the rectangle edge. For example, the following code draws a red rectangle around text that labels a plot and specifies a line width of 3 points:
text(3*pi/4,sin(3*pi/4),... '\leftarrowsin(t) = .707',... 'EdgeColor','red',... 'LineWidth',3);
1 0.8 0.6 0.4 0.2 0 -0.2 -0.4 -0.6 -0.8 -1 0 1 2 3 4 5 6 7 sin(t) = .707
For additional features, see the following properties: BackgroundColor -- Color of the rectangle's interior (none by default) EdgeColor -- Color of the rectangle's edge (none by default) LineStyle -- style of the rectangle's edge line (first set EdgeColor) Margin -- increase the size of the rectangle by adding a margin to the exsiting text extent rectangle
Margin
scalar (pixels)
Distance between the text extent and the rectangle edge. When you specify a color for the BackgroundColor or EdgeColor text properties, MATLAB draws a rectangle around the area defined by the text Extent plus the value specified
2-572
Text Properties
by the Margin. For example, the following code displays a light green rectangle with a 10-pixel margin.
text(5*pi/4,sin(5*pi/4),... ['sin(5*pi/4) = ',num2str(sin(5*pi/4))],... 'HorizontalAlignment','center',... 'BackgroundColor',[.7 .9 .7],... 'Margin',10);
1 0.8 0.6 0.4 0.2 0 -0.2 -0.4 -0.6 -0.8 -1 0 1 sin(5*pi/4) = -0.70711 2 3 4 5 6 7
For additional features, see the following properties: BackgroundColor -- Color of the rectangle's interior (none by default) EdgeColor -- Color of the rectangle's edge (none by default) LineStyle -- Style of the rectangle's edge line (first set EdgeColor) LineWidth -- Width of the rectangle's edge line (first set EdgeColor)
Parent
handle
Text object's parent. The handle of the text object's parent object. The parent of a text object is the axes in which it is displayed. You can move a text object to another axes by setting this property to the handle of the new parent.
Position [x,y,[z]]
Location of text. A two- or three-element vector, [x y [z]], that specifies the location of the text in three dimensions. If you omit the z value, it defaults to 0. All measurements are in units specified by the Units property. Initial value is [0 0 0].
2-573
Text Properties
Rotation
scalar (default = 0)
Text orientation. This property determines the orientation of the text string. Specify values of rotation in degrees (positive angles cause counterclockwise rotation).
Selected on | {off}
Is object selected? When this property is set to on, MATLAB displays selection handles if the SelectionHighlight property is also set to on. You can, for example, define the ButtonDownFcn to set this property, allowing users to select the object with the mouse.
SelectionHighlight {on} | off
Objects highlight when selected. When the Selected property is set to on, MATLAB indicates the selected state by drawing four edge handles and four corner handles. When SelectionHighlight is set to off, MATLAB does not draw the handles.
String
string
The text string. Specify this property as a quoted string for single-line strings, or as a cell array of strings, or a padded string matrix for multiline strings. MATLAB displays this string at the specified location. Vertical slash characters are not interpreted as linebreaks in text strings, and are drawn as part of the text string. See Mathematical Symbols, Greek Letters, and TeX Characters for an example. When the text Interpreter property is set to Tex (the default), you can use a subset of TeX commands embedded in the string to produce special characters such as Greek letters and mathematical symbols. The following table lists these characters and the character sequences used to define them.
Character Sequence \alpha \beta \gamma \delta Symbol Character Sequence \upsilon \phi \chi \psi Symbol Character Sequence \sim \leq \infty \clubsuit Symbol
2-574
Text Properties
Character Sequence \epsilon \zeta \eta \theta \vartheta \iota \kappa \lambda \mu \nu \xi \pi \rho \sigma \varsigma \tau \equiv \Im \otimes \cap \supset \int
Symbol
Character Sequence \omega \Gamma \Delta \Theta \Lambda \Xi \Pi \Sigma \Upsilon \Phi \Psi \Omega \forall \exists \ni \cong \approx \Re \oplus \cup \subseteq \in
Symbol
Character Sequence \diamondsuit \heartsuit \spadesuit \leftrightarrow \leftarrow \uparrow \rightarrow \downarrow \circ \pm \geq \propto \partial \bullet \div \neq \aleph \wp \oslash \supseteq \subset \o
Symbol
2-575
Text Properties
Character Sequence \rfloor
Symbol
Character Sequence \lceil
Symbol
Character Sequence \nabla
Symbol
... |
\lfloor
\perp
\cdot \neg \times \surd \varpi \rangle
\ldots \prime \0 \mid \copyright
\wedge \rceil \vee \langle
You can also specify stream modifiers that control the font used. The first four modifiers are mutually exclusive. However, you can use \fontname in combination with one of the other modifiers: \bf -- bold font \it -- italics font \sl -- oblique font (rarely available) \rm -- normal font \fontname{fontname} -- specify the name of the font family to use. \fontsize{fontsize} -- specify the font size in FontUnits. Stream modifiers remain in effect until the end of the string or only within the context defined by braces { }.
Specifying Subscript and Superscript Characters
The subscript character "_" and the superscript character "^" modify the character or substring defined in braces immediately following. To print the special characters used to define the Tex strings when Interpreter is Tex, prefix them with the backslash "\" character: \\, \{, \} \_, \^. See the example in the text reference page for more information.
2-576
Text Properties
When Interpreter is set to none, no characters in the String are interpreted, and all are displayed when the text is drawn.
Tag
string
User-specified object label. The Tag property provides a means to identify graphics objects with a user-specified label. This is particularly useful when constructing interactive graphics programs that would otherwise need to define object handles as global variables or pass them as arguments between callback routines. You can define Tag as any string.
Type
string (read only)
Class of graphics object. For text objects, Type is always the string 'text'.
Units pixels | normalized | inches | centimeters | points | {data}
Units of measurement. This property specifies the units MATLAB uses to interpret the Extent and Position properties. All units are measured from the lower left corner of the axes plotbox. Normalized units map the lower left corner of the rectangle defined by the axes to (0,0) and the upper right corner to (1.0,1.0). pixels, inches, centimeters, and points are absolute units (1 point = 1/72 inch). data refers to the data units of the parent axes. If you change the value of Units, it is good practice to return it to its default value after completing your computation so as not to affect other functions that assume Units is set to the default value.
UserData
matrix
User-specified data. Any data you want to associate with the text object. MATLAB does not use this data, but you can access it using set and get.
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the text. Assign this property the handle of a uicontextmenu object created in the same figure as the text. Use the uicontextmenu function to create the context menu. MATLAB displays the context menu whenever you right-click over the text.
2-577
Text Properties
VerticalAlignment top | cap | {middle} | baseline | bottom
Vertical alignment of text. This property specifies the vertical justification of the text string. It determines where MATLAB places the string with regard to the value of the Position property. The possible values mean top -- Place the top of the string's Extent rectangle at the specified y-position. cap -- Place the string so that the top of a capital letter is at the specified y-position. middle -- Place the middle of the string at specified y-position. baseline -- Place font baseline at the specified y-position. bottom -- Place the bottom of the string's Extent rectangle at the specified y-position. The following picture illustrates the alignment options. Text VerticalAlignment property viewed with the HorizontalAlignment property set to left (the default).
Middle Baseline
Visible
Top Bottom
{on} | off
Cap
Text visibility. By default, all text is visible. When set to off, the text is not visible, but still exists and you can query and set its properties.
2-578
textread
Purpose Graphical Interface Syntax
2textread
Read formatted data from text file As an alternative to textread, use the Import Wizard. To activate the Import Wizard, select Import Data from the File menu.
[A,B,C,...] = textread('filename','format') [A,B,C,...] = textread('filename','format',N) [...] = textread(...,'param','value',...) [A,B,C,...] = textread('filename','format') reads data from the file 'filename' into the variables A,B,C, and so on, using the specified format, until the entire file is read. textread is useful for reading text files with a
Description
known format. Both fixed and free format files can be handled.
textread matches and converts groups of characters from the input. Each
input field is defined as a string of non-whitespace characters that extends to the next whitespace or delimiter character, or to the maximum field width. Repeated delimiter characters are significant, while repeated whitespace characters are treated as one. The format string determines the number and types of return arguments. The number of return arguments is the number of items in the format string. The format string supports a subset of the conversion specifiers and conventions of the C language fscanf routine. Values for the format string are listed in the table below. Whitespace characters in the format string are ignored.
format Action Output
Literals (ordinary characters)
Ignore the matching characters. For example, in a file that has Dept followed by a number (for department number), to skip the Dept and read only the number, use 'Dept' in the format string. Read a signed integer value. Read an integer value. Read a floating point value.
None
%d %u %f
Double array Double array Double array
2-579
textread
format %s
Action
Output
Read a whitespace or delimiterseparated string. Read a string, which could be in double quotes.
Cell array of strings Cell array of strings. Does not include the double quotes. Character array Cell array of strings
%q
%c
Read characters, including white space. Read the longest string containing characters specified in the brackets. Read the longest non-empty string containing characters that are not specified in the brackets. Ignore the matching characters specified by *. Read field width specified by w. The %f format supports %w.pf, where w is the field width and p is the precision.
%[...]
%[^...]
Cell array of strings
%*...
No output
instead of %
%w...
instead of %
[A,B,C,...] = textread('filename','format',N) reads the data, reusing the format string N times, where N is an integer greater than zero. If N is smaller than zero, textread reads the entire file.
2-580
textread
[...] = textread(...,'param','value',...) customizes textread using param/value pairs, as listed in the table below. param whitespace value Any from the list below: ' ' \b \n \r \t delimiter Action
Treats vector of characters as whitespace. Default is ' \b\t'. Space Backspace New line Carriage return Horizontal tab Specifies delimiter character. Default is none. Default is eEdD. Specifies the maximum string length, in bytes. Default is 4095. Ignores the specified number of lines at the beginning of the file. Ignores characters after % Ignores characters after #. Ignores characters between /* and */. Ignores characters after //.
Delimiter character Exponent characters positive integer positive integer
matlab shell c c++
expchars
bufsize
headerlines
commentstyle commentstyle commentstyle commentstyle
Note When textread reads a consecutive series of whitespace values, it treats them as one whitespace. When it reads a consecutive series of delimiter values, it treats each as a separate delimiter.
2-581
textread
Examples Example 1 Read All Fields in Free Format File Using %
The first line of mydata.dat is
Sally Type1 12.34 45 Yes
Read the first line of the file as a free format file using the % format.
[names,types,x,y,answer] = textread('mydata.dat','%s %s %f ... %d %s',1)
returns
names = 'Sally' types = 'Type1' x = 12.34000000000000 y = 45 answer = 'Yes'
Example 2 Read as Fixed Format File, Ignoring the Floating Point Value
The first line of mydata.dat is
Sally Type1 12.34 45 Yes
Read the first line of the file as a fixed format file, ignoring the floating point value.
[names,types,y,answer] = textread('mydata.dat','%9c %5s %*f ... %2d %3s',1)
returns
names = Sally types = 'Type1' y = 45 answer =
2-582
textread
'Yes' %*f in the format string causes textread to ignore the floating point value, in this case, 12.34.
Example 3 Read Using Literal to Ignore Matching Characters
The first line of mydata.dat is
Sally Type1 12.34 45 Yes
Read the first line of the file, ignoring the characters Type in the second field.
[names,typenum,x,y,answer] = textread('mydata.dat','%s Type%d %f %d %s',1)
returns
names = 'Sally' typenum = 1 x = 12.34000000000000 y = 45 answer = 'Yes' Type%d in the format string causes the characters Type in the second field to be
ignored, while the rest of the second field is read as a signed integer, in this case, 1.
Example 4 Read M-file into a Cell Array of Strings
Read the file fft.m into cell array of strings.
file = textread('fft.m','%s','delimiter','\n','whitespace','');
See Also
dlmread, csvread, fscanf
ts and you can query and set its properties.
2-583
textwrap
Purpose Syntax Description
2textwrap
Return wrapped string matrix for given uicontrol
outstring = textwrap(h,instring) [outstring,position] = textwrap(h,instring) outstring = textwrap(h,instring) returns a wrapped string cell array, outstring, that fits inside the uicontrol with handle h. instring is a cell array, with each cell containing a single line of text. outstring is the wrapped string
matrix in cell array format. Each cell of the input string is considered a paragraph.
[outstring,position]=textwrap(h,instring) returns the recommended position of the uicontrol in the units of the uicontrol. position considers the
extent of the multiline text in the x and y directions.
Example
Place a textwrapped string in a uicontrol:
pos = [10 10 100 10]; h = uicontrol('Style','Text','Position',pos); string = {'This is a string for the uicontrol.', 'It should be correctly wrapped inside.'}; [outstring,newpos] = textwrap(h,string); pos(4) = newpos(4);
set(h,'String',outstring,'Position',[pos(1),pos(2),pos(3)+10,pos(4)])
See Also
uicontrol
2-584
tic, toc
Purpose Syntax
2tic, toc
Stopwatch timer
tic any statements toc t = toc
Description
tic starts a stopwatch timer. toc prints the elapsed time since tic was used. t = toc returns the elapsed time in t.
Examples
This example measures how the time required to solve a linear system varies with the order of a matrix.
for n = 1:100 A = rand(n,n); b = rand(n,1); tic x = A\b; t(n) = toc; end plot(t)
See Also
clock, cputime, etime, profile
2-585
timer
Purpose Syntax
2timer
Construct timer object
T = timer T = timer(`PropertyName1', PropertyValue1, 'PropertyName2', PropertyValue2,...) T = timer constructs a timer object with default attributes. T = timer('PropertyName1', PropertyValue1, 'PropertyName2', PropertyValue2,...) constructs a timer object in which the given Property
Description
name/value pairs are set on the object. See Timer Object Properties for a list of all the properties supported by the timer object. Note that the property name/property value pairs can be in any format supported by the set function, i.e., property/value string pairs, structures, and property/value cell array pairs.
Example
This example constructs a timer object with a timer callback function handle, mycallback, and a 10 second interval.
t = timer('TimerFcn',@mycallback, 'Period', 10.0);
See Also Timer Object Properties
delete, disp, get, isvalid, set, start, startat, stop, timerfind, wait
The timer object supports the following properties that control its attributes. The table includes information about the data type of each property and its default value.
2-586
timer
To view the value of the properties of a particular timer object, use the get function. To set the value of the properties of a timer object, use the set function.
Property Name AveragePeriod Property Description Datatypes, Values, and Defaults
The average time between TimerFcn executions since the timer started. Note: Value is NaN until timer executes two timer callbacks. Action taken when a timer has to execute TimerFcn before the completion of previous execution of TimerFcn. 'drop'--Do not execute the function. 'error'--Generate an error. 'queue'--Execute function at next opportunity.
Datatype: double Default: NaN Readonly: Always Datatype: Enumerated string Values: 'drop'
'queue' 'error' Default: 'drop'
BusyMode
Readonly: Only when Running='on'
ErrorFcn
Function that the timer executes when an error occurs. This function executes before the StopFcn. See Creating Timer Callback Functions for more information. Determines how the timer object schedules timer events. See Timer Execution Modes for more information.
Datatype: Text string, function handle, or cell array. Default: Readonly: Never Datatype: Enumerated string Values: 'singleShot'
'fixedSpacing' 'fixedDelay' 'fixedRate' Default: 'singleShot' Readonly: When Running='on'
ExecutionMode
InstantPeriod
The time between the last two executions of TimerFcn.
Datatype: double Default: NaN Readonly: Always
2-587
timer
Property Name Name
Property Description
Datatypes, Values, and Defaults
User-supplied name
Datatype: Text string Default: 'timer-i', where i is a number indicating the ith timer object created this session. Note: If you issue the clear classes command, the timer object resets i to 1. Readonly: Never Datatype: double Value: Any number <0.001 Default: 1.0 Readonly: When Running='on' Datatype: Enumerated string: Values: 'off' Default: Readonly: Always
'on' 'off'
Period
Specifies the delay, in seconds, between executions of TimerFcn.
Running
Indicates whether the timer is currently executing.
StartDelay
Specifies the delay, in seconds, between the start of the timer and the first execution of the function specified in TimerFcn. Function the timer calls when it starts. See Creating Timer Callback Functions for more information.
Datatype: double Value: Any number <=0 Default: 0 Readonly: When Running='on' Datatype: Text string, function handle, or cell array Default: Readonly: Never
StartFcn
2-588
timer
Property Name StopFcn
Property Description
Datatypes, Values, and Defaults
Function the timer calls when it stops. The timer stops when: You call the timer stop function When the timer finishes executing TimerFcn, i.e., the value of TasksExecuted reaches the limit set by the TasksToExecute. An error occurs (The ErrorFcn is called first, followed by the StopFcn.) See Creating Timer Callback Functions for more information.
Datatype: Text string, function handle, or cell array. Default: Readonly: Never
Tag
User supplied label Specifies the number of times the timer should execute the function specified in the TimerFcn property. The number of times the timer has executed TimerFcn since the timer was started Timer callback function. See Creating Timer Callback Functions for more information.
Datatype: Text string Default: ''(empty string) Datatype: double Value: Any number <0 Default: 1 Readonly: Never Datatype: double Value: Any number <=0 Default: 0 Readonly: Always Datatype: Text string, function handle, or cell array. Default: Readonly: Never
TasksToExecute
TasksExecuted
TimerFcn
2-589
timer
Property Name Type
Property Description
Datatypes, Values, and Defaults
Identifies the object type
Datatype: Text string Value: 'timer' Readonly: Always Datatype: User-defined Default: [] Readonly: Never
UserData
User-supplied data
2-590
timerfind
Purpose Syntax
2timerfind
Find timer objects
out out out out = = = = timerfind timerfind('P1', V1, 'P2', V2,...) timerfind(S) timerfind(obj, 'P1', V1, 'P2', V2,...)
Description
out = timerfind returns an array, out, of all the timer objects that exist in
memory.
out = timerfind('P1', V1, 'P2', V2,...) returns an array, out, of timer objects whose property values match those passed as param-value pairs, P1, V1, P2, V2. Param-value pairs may be specified as a cell array. out = timerfind(S) returns an array, out, of timer objects whose property values match those defined in the structure, S. The field names of S are timer
object property names and the field values are the corresponding property values.
out = timerfind(obj, 'P1', V1, 'P2', V2,...) restricts the search for matching parameter/value pairs to the timer objects listed in obj. obj can be an array of timer objects.
Note Param-value string pairs, structures, and param-value cell array pairs may be used in the same call to timerfind.
Note that, for most properties, timerfind performs case-sensitive searches of property values. For example, if the value of an object's Name property is 'MyObject', timerfind will not find a match if you specify 'myobject'. Use the get function to determine the exact format of a property value. However, properties which have an enumerated list of possible values, are not case-sensitive. For example, timerfind will find an object with an ExecutionMode property value of 'singleShot' or 'singleshot'.
Example
This example uses timerfind to find timer objects with the specified property values.
2-591
timerfind
t1 = t2 = out1 out2
timer('Tag', 'broadcastProgress', 'Period', 5); timer('Tag', 'displayProgress'); = timerfind('Tag', 'displayProgress') = timerfind({'Period', 'Tag'}, {5, 'broadcastProgress'})
See Also
timer, get
2-592
title
Purpose Syntax
2title
Add title to current axes
title('string') title(fname) title(...,'PropertyName',PropertyValue,...) h = title(...)
Description
Each axes graphics object can have one title. The title is located at the top and in the center of the axes.
title('string') outputs the string at the top and in the center of the current
axes.
title(fname) evaluates the function that returns a string and displays the
string at the top and in the center of the current axes.
title(...,'PropertyName',PropertyValue,...) specifies property name and property value pairs for the text graphics object that title creates. h = title(...) returns the handle to the text object used as the title.
Examples
Display today's date in the current axes:
title(date)
Include a variable's value in a title:
f = 70; c = (f--32)/1.8; title(['Temperature is ',num2str(c),'C'])
Include a variable's value in a title and set the color of the title to yellow:
n = 3; title(['Case number #',int2str(n)],'Color','y')
Include Greek symbols in a title:
title('\ite^{\omega\tau} = cos(\omega\tau) + isin(\omega\tau)')
Include a superscript character in a title:
title('\alpha^2')
2-593
title
Include a subscript character in a title:
title('X_1')
The text object String property lists the available symbols.
Remarks See Also
title sets the Title property of the current axes graphics object to a new text graphics object. See the text String property for more information. gtext, int2str, num2str, text, xlabel, ylabel, zlabel
"Annotating Plots" for related functions Adding Titles to Graphs for more information on ways to add titles.
2-594
toeplitz
Purpose Syntax Description
2toeplitz
Toeplitz matrix
T = toeplitz(c,r) T = toeplitz(r)
A Toeplitz matrix is defined by one row and one column. A symmetric Toeplitz matrix is defined by just one row. toeplitz generates Toeplitz matrices given just the row or row and column description.
T = toeplitz(c,r) returns a nonsymmetric Toeplitz matrix T having c as its first column and r as its first row. If the first elements of c and r are different, a message is printed and the column element is used. T = toeplitz(r) returns the symmetric or Hermitian Toeplitz matrix formed from vector r, where r defines the first row of the matrix.
Examples
A Toeplitz matrix with diagonal disagreement is
c = [1 2 3 4 5]; r = [1.5 2.5 3.5 4.5 5.5]; toeplitz(c,r) Column wins diagonal conflict: ans = 1.000 2.500 3.500 2.000 1.000 2.500 3.000 2.000 1.000 4.000 3.000 2.000 5.000 4.000 3.000
4.500 3.500 2.500 1.000 2.000
5.500 4.500 3.500 2.500 1.000
See Also
hankel
2-595
trace
Purpose Syntax Description Algorithm
2trace
Sum of diagonal elements
b = trace(A) b = trace(A) is the sum of the diagonal elements of the matrix A. trace is a single-statement M-file. t = sum(diag(A));
See Also
det, eig
2-596
trapz
Purpose Syntax
2trapz
Trapezoidal numerical integration
Z = trapz(Y) Z = trapz(X,Y) Z = trapz(...,dim) Z = trapz(Y) computes an approximation of the integral of Y via the
Description
trapezoidal method (with unit spacing). To compute the integral for spacing other than one, multiply Z by the spacing increment. If Y is a vector, trapz(Y) is the integral of Y. If Y is a matrix,trapz(Y) is a row vector with the integral over each column. If Y is a multidimensional array, trapz(Y) works across the first nonsingleton dimension.
Z = trapz(X,Y) computes the integral of Y with respect to X using trapezoidal
integration. If X is a column vector and Y an array whose first nonsingleton dimension is length(X), trapz(X,Y) operates across this dimension.
Z = trapz(...,dim) integrates across the dimension of Y specified by scalar dim. The length of X, if given, must be the same as size(Y,dim).
Examples
The exact value of
0 sin ( x ) dx
is 2.
To approximate this numerically on a uniformly spaced grid, use
X = 0:pi/100:pi; Y = sin(x);
Then both
Z = trapz(X,Y)
and
Z = pi/100*trapz(Y)
produce
2-597
trapz
Z = 1.9998
A nonuniformly spaced example is generated by
X = sort(rand(1,101)*pi); Y = sin(X); Z = trapz(X,Y);
The result is not as accurate as the uniformly spaced grid. One random sample produced
Z = 1.9984
See Also
cumsum, cumtrapz
2-598
treelayout
Purpose Syntax Description
2treelayout
Lay out tree or forest
[x,y] = treelayout(parent,post) [x,y,h,s] = treelayout(parent,post) [x,y] = treelayout(parent,post) lays out a tree or a forest. parent is the vector of parent pointers, with 0 for a root. post is an optional postorder permutation on the tree nodes. If you omit post, treelayout computes it. x and y are vectors of coordinates in the unit square at which to lay out the nodes of
the tree to make a nice picture.
[x,y,h,s] = treelayout(parent,post) also returns the height of the tree h and the number of vertices s in the top-level separator.
See Also
etree, treeplot, etreeplot, symbfact
2-599
treeplot
Purpose Syntax Description
2treeplot
Plot picture of tree
treeplot(p) treeplot(p,nodeSpec,edgeSpec) treeplot(p) plots a picture of a tree given a vector of parent pointers, with p(i) = 0 for a root. treeplot(p,nodeSpec,edgeSpec) allows optional parameters nodeSpec and edgeSpec to set the node or edge color, marker, and linestyle. Use '' to omit
one or both.
See Also
etree, etreeplot, treelayout
2-600
tril
Purpose Syntax Description
2tril
Lower triangular part of a matrix
L = tril(X) L = tril(X,k) L = tril(X) returns the lower triangular part of X. L = tril(X,k) returns the elements on and below the kth diagonal of X. k = 0 is the main diagonal, k > 0 is above the main diagonal, and k < 0 is below the
main diagonal.
k = 0 k < 0 k > 0
Examples
tril(ones(4,4),-1) ans = 0 1 1 1 0 0 1 1 0 0 0 1 0 0 0 0
See Also
diag, triu
2-601
trimesh
Purpose Syntax
2trimesh
Triangular mesh plot
trimesh(Tri,X,Y,Z) trimesh(Tri,X,Y,Z,C) trimesh(...'PropertyName',PropertyValue...) h = trimesh(...) trimesh(Tri,X,Y,Z) displays triangles defined in the m-by-3 face matrix Tri as a mesh. Each row of Tri defines a single triangular face by indexing into the vectors or matrices that contain the X, Y, and Z vertices. trimesh(Tri,X,Y,Z,C) specifies color defined by C in the same manner as the surf function. MATLAB performs a linear transformation on this data to
Description
obtain colors from the current colormap.
trimesh(...'PropertyName',PropertyValue...) specifies additional patch property names and values for the patch graphics object created by the function. h = trimesh(...) returns a handle to a patch graphics object.
Example
Create vertex vectors and a face matrix, then create a triangular mesh plot.
x = rand(1,50); y = rand(1,50); z = peaks(6*x3,6*x3); tri = delaunay(x,y); trimesh(tri,x,y,z)
See Also
patch, tetramesh, triplot, trisurf, delaunay
"Creating Surfaces and Meshes" for related functions
2-602
triplequad
Purpose Syntax
2triplequad
Numerically evaluate triple integral
triplequad(fun,xmin,xmax,ymin,ymax,zmin,zmax) triplequad(fun,xmin,xmax,ymin,ymax,zmin,zmax,tol) triplequad(fun,xmin,xmax,ymin,ymax,zmin,zmax,tol,method) triplequad(fun,xmin,xmax,ymin,ymax,zmin,zmax,tol,method,p1,p2,...) triplequad(fun,xmin,xmax,ymin,ymax,zmin,zmax) evaluates the triple integral fun(x,y,z) over the three dimensional rectangular region xmin <= x <= xmax, ymin <= y <= ymax, zmin <= z <= zmax. The function fun(x,y,z) must accept a vector x and scalars y and z, and return a vector of values of the integrand. triplequad(fun,xmin,xmax,ymin,ymax,zmin,zmax,tol) uses a tolerance tol instead of the default, which is 1.0e-6. triplequad(fun,xmin,xmax,ymin,ymax,zmin,zmax,tol,method) uses the quadrature function specified as method, instead of the default quad. Valid values for method are @quadl or the function handle of a user-defined quadrature method that has the same calling sequence as quad and quadl. triplequad(fun,xmin,xmax,ymin,ymax,zmin,zmax,tol,method,p1,p2,...) passes the additional parameters p1,p2,... to fun(x,y,p1,p2,...). Use [] as a placeholder if you do not specify tol or method. triplequad(fun,xmin,xmax,ymin,ymax,zmin,zmax,[],[],p1,p2,...) is the
Description
same as
triplequad(fun,xmin,xmax,ymin,ymax,zmin,zmax,1e-6,@quad,p1,p2,...)
Examples
fun can be an inline object Q = triplequad(inline('y*sin(x)+z*cos(x)'),0,pi,0,1,-1,1)
or a function handle
Q = triplequad(@integrnd,0,pi,0,1,-1,1)
where integrnd.m is the M-file
function f = integrnd(x,y,z) f = y*sin(x)+z*cos(x);
2-603
triplequad
This example integrates y*sin(x)+z*cos(x) over the region 0 <= x <= pi, 0 <= y <= 1, -1 <= z <= 1. Note that the integrand can be evaluated with a vector x and scalars y and z.
See Also
dblquad, inline, quad, quadl, @ (function handle)
2-604
triplot
Purpose Syntax
2 triplot
2-D triangular plot
triplot(TRI,x,y) triplot(TRI,x,y,color) h = triplot(...) triplot(...,'param','value','param','value'...) triplot(TRI,x,y) displays the triangles defined in the m-by-3 matrix TRI. A row of TRI contains indices into the vectors x and y that define a single triangle.
Description
The default line color is blue.
triplot(TRI,x,y,color) uses the string color as the line color. color can also be a line specification. See ColorSpec for a list of valid color strings. See LineSpec for information about line specifications. h = triplot(...) returns a vector of handles to the displayed triangles. triplot(...,'param','value','param','value'...) allows additional line property name/property value pairs to be used when creating the plot. See Line Properties for information about the available properties.
Examples
This code plots the Delaunay triangulation for 10 randomly generated points.
rand('state',7); x = rand(1,10); y = rand(1,10); TRI = delaunay(x,y); triplot(TRI,x,y,'red')
2-605
triplot
1
0.9
0.8
0.7
0.6
0.5
0.4
0.3
0.2
0.1
0
0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9
1
See Also
ColorSpec, delaunay, line, Line Properties, LineSpec, plot, trimesh, trisurf
2-606
trisurf
Purpose Syntax
2trisurf
Triangular surface plot
trisurf(Tri,X,Y,Z) trisurf(Tri,X,Y,Z,C) trisurf(...'PropertyName',PropertyValue...) h = trisurf(...) trisurf(Tri,X,Y,Z) displays triangles defined in the m-by-3 face matrix Tri as a surface. Each row of Tri defines a single triangular face by indexing into the vectors or matrices that contain the X, Y, and Z vertices. trisurf(Tri,X,Y,Z,C) specifies color defined by C in the same manner as the surf function. MATLAB performs a linear transformation on this data to
Description
obtain colors from the current colormap.
trisurf(...'PropertyName',PropertyValue...) specifies additional patch property names and values for the patch graphics object created by the function. h = trisurf(...) returns a patch handle.
Example
Create vertex vectors and a face matrix, then create a triangular surface plot.
x = rand(1,50); y = rand(1,50); z = peaks(6*x3,6*x3); tri = delaunay(x,y); trisurf(tri,x,y,z)
See Also
patch, surf, tetramesh, trimesh, triplot, delaunay
"Creating Surfaces and Meshes" for related functions
2-607
triu
Purpose Syntax Description
2triu
Upper triangular part of a matrix
U = triu(X) U = triu(X,k) U = triu(X) returns the upper triangular part of X. U = triu(X,k) returns the element on and above the kth diagonal of X. k = 0 is the main diagonal, k > 0 is above the main diagonal, and k < 0 is below the
main diagonal.
k = 0 k < 0 k > 0
Examples
triu(ones(4,4),-1) ans = 1 1 0 0 1 1 1 0 1 1 1 1 1 1 1 1
See Also
diag, tril
2-608
true
Purpose Syntax
2true
True array
true true(n) true(m,n) true(m,n,p,...) true(size(A)) true is shorthand for logical(1). true(n) is an n-by-n matrix of logical ones. true(m,n) or true([m,n]) is an m-by-n matrix of logical ones. true(m,n,p,...) or true([m n p ...]) is an m-by-n-by-p-by-... array of
Description
logical ones.
true(size(A)) is an array of logical ones that is the same size as array A.
Remarks See Also
true(n) is much faster and more memory efficient than logical(ones(n)). false, logical
2-609
try
Purpose Description
2try
Begin try block The general form of a try statement is:
try, statement, ..., statement, catch, statement, ..., statement, end
Normally, only the statements between the try and catch are executed. However, if an error occurs while executing any of the statements, the error is captured into lasterr, and the statements between the catch and end are executed. If an error occurs within the catch statements, execution stops unless caught by another try...catch block. The error string produced by a failed try block can be obtained with lasterr.
See Also
catch, end, eval, evalin
2-610
tsearch
Purpose Syntax Description
2tsearch
Search for enclosing Delaunay triangle
T = tsearch(x,y,TRI,xi,yi) T = tsearch(x,y,TRI,xi,yi) returns an index into the rows of TRI for each point in xi, yi. The tsearch command returns NaN for all points outside the convex hull. Requires a triangulation TRI of the points x,y obtained from delaunay. delaunay, delaunayn, dsearch, tsearchn
See Also
2-611
tsearchn
Purpose Syntax Description
2tsearchn
n-D closest simplex search
t = tsearchn(X,TES,XI) [t,P] = tsearchn(X,TES,XI) t = tsearchn(X,TES,XI) returns the indices t of the enclosing simplex of the Delaunay tessellation TES for each point in XI. X is an m-by-n matrix, representing m points in n-D space. XI is a p-by-n matrix, representing p points in n-D space. tsearchn returns NaN for all points outside the convex hull of X. tsearchn requires a tessellation TES of the points X obtained from delaunayn. [t,P] = tsearchn(X,TES,XI) also returns the barycentric coordinate P of XI in the simplex TES. P is a p-by-n+1 matrix. Each row of P is the Barencentric coordinate of the corresponding point in XI. It is useful for interpolation.
See Also
delaunayn, griddatan, tsearch
2-612
type
Purpose Syntax Description
2type
List file
type ('filename') type filename type('filename') displays the contents of the specified file in the MATLAB Command Window. Use the full path for filename, or use a MATLAB relative
partial pathname. If you do not specify a filename extension and there is no filename file without an extension, the type function adds the .m extension by default. The type function checks the directories specified in the MATLAB search path, which makes it convenient for listing the contents of M-files on the screen. Use type with more on to see the listing one screenful at a time.
type filename is the unquoted form of the syntax.
Examples
type('foo.bar') lists the contents of the file foo.bar. type foo lists the contents of the file foo. If foo does not exist, type foo lists the contents of the file foo.m.
See Also
cd, dbtype, delete, dir, more, partialpath, path, what, who
2-613
uicontextmenu
Purpose Syntax Description
2uicontextmenu
Create a context menu
handle = uicontextmenu('PropertyName',PropertyValue,...); uicontextmenu creates a context menu, which is a menu that appears when the
user right-clicks on a graphics object. You create context menu items using the uimenu function. Menu items appear in the order the uimenu statements appear. You associate a context menu with an object using the UIContextMenu property for the object and specifying the context menu's handle as the property value.
Properties
This table lists the properties that are useful to uicontextmenu objects, grouping them by function. Each property name acts as a link to a description of the property.
Property Description Property Value
Property Name
Controlling Style and Appearance Visible
Uicontextmenu visibility Location of uicontextmenu when Visible is set to on
Value: on, off Default: off Value: two-element vector Default: [0 0]
Position
General Information About the Object Children
The uimenus defined for the uicontextmenu Uicontextmenu object's parent User-specified object identifier Class of graphics object User-specified data
Value: matrix Value: scalar figure handle Value: string Value: string (read-only) Default: uicontrol Value: matrix
Parent Tag Type
UserData
Controlling Callback Routine Execution
2-614
uicontextmenu
Property Name BusyAction
Property Description
Property Value
Callback routine interruption Control action Callback routine executed during object creation Callback routine executed during object deletion Callback routine interruption mode
Value: cancel, queue Default: queue Value: string Value: string Value: string Value: on, off Default: on
Callback CreateFcn
DeleteFcn
Interruptible
Controlling Access to Objects HandleVisibility
Whether handle is accessible from command line and GUIs
Value: on, callback, off Default: on
Example
These statements define a context menu associated with a line. When the user extend-clicks anywhere on the line, the menu appears. Menu items enable the user to change the line style.
% Define the context menu cmenu = uicontextmenu; % Define the line and associate it with the context menu hline = plot(1:10, 'UIContextMenu', cmenu); % Define callbacks for context menu items cb1 = ['set(hline, ''LineStyle'', ''--'')']; cb2 = ['set(hline, ''LineStyle'', '':'')']; cb3 = ['set(hline, ''LineStyle'', ''-'')']; % Define the context menu items item1 = uimenu(cmenu, 'Label', 'dashed', 'Callback', cb1); item2 = uimenu(cmenu, 'Label', 'dotted', 'Callback', cb2); item3 = uimenu(cmenu, 'Label', 'solid', 'Callback', cb3);
2-615
uicontextmenu
When the user extend-clicks on the line, the context menu appears, as shown in this figure:
Object Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Uicontextmenu
Uimenu
Uimenu
See Also
uicontrol, uimenu
2-616
uicontextmenu Properties
Modifying Properties
2uicontextmenu Properties
You can set and query graphics object properties in two ways: The Property Editor is an interactive tool that enables you to see and change object property values. The set and get commands enable you to set and query the values of properties To change the default value of properties see Setting Default Property Values.
Uicontextmenu Property Descriptions
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control how MATLAB handles events that potentially interrupt executing callback routines. If a callback routine is executing, subsequently invoked callback routines always attempt to interrupt it. If the Interruptible property of the object whose callback is executing is set to on (the default), then interruption occurs at the next point where the event queue is processed. If the Interruptible property is off, the BusyAction property of the object whose callback is executing determines how MATLAB handles the event. The choices are: cancel discard the event that attempted to execute a second callback routine. queue queue the event that attempted to execute a second callback routine until the current callback finishes.
ButtonDownFcn
string
This property has no effect on uicontextmenu objects.
Callback
string
Control action. A routine that executes whenever you right-click on an object for which a context menu is defined. The routine executes immediately before the context menu is posted. Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace.
Children
matrix
The uimenus defined for the uicontextmenu.
2-617
uicontextmenu Properties
Clipping
{on} | off
This property has no effect on uicontextmenu objects.
CreateFcn
string
Callback routine executed during object creation. This property defines a callback routine that executes when MATLAB creates a uicontextmenu object. You must define this property as a default value for uicontextmenus. For example, this statement:
set(0,'DefaultUicontextmenuCreateFcn',... 'set(gcf,''IntegerHandle'',''off'')')
defines a default value on the root level that sets the figure IntegerHandle property to off whenever you create a uicontextmenu object. MATLAB executes this routine after setting all property values for the uicontextmenu. Setting this property on an existing uicontextmenu object has no effect. The handle of the object whose CreateFcn is being executed is accessible only through the root CallbackObject property, which can be queried using gcbo.
DeleteFcn
string
Delete uicontextmenu callback routine. A callback routine that executes when you delete the uicontextmenu object (e.g., when you issue a delete command or clear the figure containing the uicontextmenu). MATLAB executes the routine before destroying the object's properties so these values are available to the callback routine. The handle of the object whose DeleteFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo.
HandleVisibility {on} | callback | off
Control access to object's handle by command-line users and GUIs. This property determines when an object's handle is visible in its parent's list of children. HandleVisibility is useful for preventing command-line users from accidentally drawing into or deleting a figure that contains only user interface devices (such as a dialog box). Handles are always visible when HandleVisibility is on. Setting HandleVisibility to callback causes handles to be visible from within callback routines or functions invoked by callback routines, but not from
2-618
uicontextmenu Properties
within functions invoked from the command line. This provides a means to protect GUIs from command-line users, while allowing callback routines to have complete access to object handles. Setting HandleVisibility to off makes handles invisible at all times. This may be necessary when a callback routine invokes a function that might potentially damage the GUI (such as evaluating a user-typed string), and so temporarily hides its own handles during the execution of that function. When a handle is not visible in its parent's list of children, it cannot be returned by functions that obtain handles by searching the object hierarchy or querying handle properties. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close. When a handle's visibility is restricted using callback or off, the object's handle does not appear in its parent's Children property, figures do not appear in the root's CurrentFigure property, objects do not appear in the root's CallbackObject property or in the figure's CurrentObject property, and axes do not appear in their parent's CurrentAxes property. You can set the root ShowHiddenHandles property to on to make all handles visible, regardless of their HandleVisibility settings (this does not affect the values of the HandleVisibility properties). Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.
HitTest {on} | off
This property has no effect on uicontextmenu objects.
Interruptible {on} | off
Callback routine interruption mode. The Interruptible property controls whether a uicontextmenu callback routine can be interrupted by subsequently invoked callback routines. By default (on), execution of a callback routine can be interrupted. Only callback routines defined for the ButtonDownFcn and Callback properties are affected by the Interruptible property. MATLAB checks for events that can interrupt a callback routine only when it encounters a drawnow, figure, getframe, pause, or waitfor command in the routine.
2-619
uicontextmenu Properties
Parent
handle
Uicontextmenu's parent. The handle of the uicontextmenu's parent object. The parent of a uicontextmenu object is the figure in which it appears. You can move a uicontextmenu object to another figure by setting this property to the handle of the new parent.
Position
vector
Uicontextmenu's position. A two-element vector that defines the location of a context menu posted by setting the Visible property value to on. Specify Position as
[left bottom]
where vector elements represent the distance in pixels from the bottom left corner of the figure window to the top left corner of the context menu.
Selected on | {off}
This property has no effect on uicontextmenu objects.
SelectionHighlight {on} | off
This property has no effect on uicontextmenu objects.
Tag
string
User-specified object label. The Tag property provides a means to identify graphics objects with a user-specified label. This is particularly useful when constructing interactive graphics programs that would otherwise need to define object handles as global variables or pass them as arguments between callback routines. You can define Tag as any string.
Type
string
Class of graphics object. For uicontextmenu objects, Type is always the string 'uicontextmenu'.
UIContextMenu
handle
This property has no effect on uicontextmenus.
UserData
matrix
User-specified data. Any data you want to associate with the uicontextmenu object. MATLAB does not use this data, but you can access it using set and get.
2-620
uicontextmenu Properties
Visible
on | {off}
Uicontextmenu visibility. The Visible property can be used in two ways: Its value indicates whether the context menu is currently posted. While the context menu is posted, the property value is on; when the context menu is not posted, its value is off. Its value can be set to on to force the posting of the context menu. Similarly, setting the value to off forces the context menu to be removed. When used in this way, the Position property determines the location of the posted context menu.
2-621
uicontrol
Purpose Syntax Description
2uicontrol
Create user interface control object
handle = uicontrol(parent) handle = uicontrol(...,'PropertyName',PropertyValue,...) uicontrol creates uicontrol graphics objects (user interface controls). You
implement graphical user interfaces using uicontrols. When selected, most uicontrol objects perform a predefined action. MATLAB supports numerous styles of uicontrols, each suited for a different purpose: Check boxes Editable text fields Frames List boxes Pop-up menus Push buttons Radio buttons Sliders Static text labels Toggle buttons See User Interface Controls for information on using these uicontrols within GUIDE, the MATLAB GUI development environment.
Specifying the Uicontrol Style
To create a specific type of uicontrol, set the Style property as one of the following strings: 'checkbox' Check boxes generate an action when clicked on. These devices are useful when providing the user with a number of independent choices. To activate a check box, click the mouse button on the object. The state of the device is indicated on the display. 'edit' Editable text fields enable users to enter or modify text values. Use editable text when you want text as input. On Microsoft Windows systems, if an editable text box has focus, clicking on the menu bar does not cause the editable text callback routine to execute.
2-622
uicontrol
However, it does cause execution on UNIX systems. Therefore, after clicking on the menu bar, the statement
get(edit_handle,'String')
does not return the current contents of the edit box on Microsoft Windows systems because MATLAB must execute the callback routine to update the String property (even though the text string has changed on the screen). This behavior is consistent with the respective platform conventions. 'frame' Frames are rectangles that provide a visual enclosure for regions of a figure window. Frames can make a user interface easier to understand by grouping related controls. Frames have no callback routines associated with them. Only other uicontrols can appear within frames. Frames are opaque, not transparent, so the order you define uicontrols is important in determining whether uicontrols within a frame are covered by the frame or are visible. Stacking order determines the order objects are drawn: objects defined first are drawn first; objects defined later are drawn over existing objects. If you use a frame to enclose objects, you must define the frame before you define the objects. 'listbox' List boxes display a list of items (defined using the String property) and enable users to select one or more items. The Min and Max properties control the selection mode: If Max-Min>1, then multiple selection is allowed. If Max-Min<=1, then only single selection is allowed. The Value property indicates selected entries and contains the indices into the list of strings; a vector value indicates multiple selections. MATLAB evaluates the list box's callback routine after any mouse button up event that changes the Value property. Therefore, you may need to add a "Done" button to delay action caused by multiple clicks on list items. List boxes differentiate between single and double clicks and set the figure SelectionType property to normal or open accordingly before evaluating the list box's Callback property. 'popupmenu' Popup menus open to display a list of choices (defined using the String property) when pressed. When not open, a pop-up menu indicates the current choice. Pop-up menus are useful when you want to provide users with a number of mutually exclusive choices, but do not want to take up the
2-623
uicontrol
amount of space that a series of radio buttons requires. You must specify a value for the String property. 'pushbutton' Push buttons generate an action when pressed. To activate a push button, click the mouse button on the push button. 'radiobutton' Radio buttons are similar to check boxes, but are intended to be mutually exclusive within a group of related radio buttons (i.e., only one is in a pressed state at any given time). To activate a radio button, click the mouse button on the object. The state of the device is indicated on the display. Note that your code can implement the mutually exclusive behavior of radio buttons. 'slider' Sliders accept numeric input within a specific range by enabling the user to move a sliding bar. Users move the bar by pressing the mouse button and dragging the pointer over the bar, or by clicking in the trough or on an arrow. The location of the bar indicates a numeric value, which is selected by releasing the mouse button. You can set the minimum, maximum, and current values of the slider. 'text' Static text boxes display lines of text. Static text is typically used to label other controls, provide directions to the user, or indicate values associated with a slider. Users cannot change static text interactively and there is no way to invoke the callback routine associated with it. 'toggle' Toggle buttons are controls that execute callbacks when clicked on and indicate their state, either on or off. Toggle buttons are useful for building toolbars.
Remarks
The uicontrol function accepts property name/property value pairs, structures, and cell arrays as input arguments and optionally returns the handle of the created object. You can also set and query property values after creating the object using the set and get functions. Uicontrol objects are children of figures and therefore do not require an axes to exist when placed in a figure window.
2-624
uicontrol
Properties
This table lists all properties useful for uicontrol objects, grouping them by function. Each property name acts as a link to a description of the property.
Property Description Property Value
Property Name
Controlling Style and Appearance BackgroundColor
Object background color Truecolor image displayed on the control Color of text Object highlighted when selected Uicontrol label, also list box and pop-up menu items Uicontrol visibility
Value: ColorSpec Default: system dependent Value: matrix Value: ColorSpec Default: [0 0 0] Value: on, off Default: on Value: string Value: on, off Default: on
CData
ForegroundColor
SelectionHighlight
String
Visible
General Information About the Object Children Enable
Uicontrol objects have no children Enable or disable the uicontrol Uicontrol object's parent Whether object is selected Slider step size Value: on, inactive, off Default: on Value: scalar figure handle Value: on, off Default: off Value: two-element vector Default: [0.01 0.1]
Parent Selected
SliderStep
2-625
uicontrol
Property Name Style
Property Description
Property Value
Type of uicontrol object
Value: pushbutton, togglebutton, radiobutton, checkbox, edit, text, slider, frame, listbox, popupmenu Default: pushbutton Value: string Value: string Value: string (read-only) Default: uicontrol Value: matrix
Tag TooltipString Type
User-specified object identifier Content of object's tooltip Class of graphics object User-specified data
UserData
Controlling the Object Position Position
Size and location of uicontrol object Units to interpret position vector
Value: position rectangle Default: [20 20 60 20] Value: pixels, normalized, inches, centimeters, points, characters Default: pixels
Units
Controlling Fonts and Labels FontAngle
Character slant
Value: normal, italic, oblique Default: normal Value: string Default: system dependent Value: size in FontUnits Default: system dependent
FontName
Font family Font size
FontSize
2-626
uicontrol
Property Name FontUnits
Property Description
Property Value
Font size units
Value: points, normalized, inches, centimeters, pixels Default: points Value: light, normal, demi,
bold
FontWeight
Weight of text characters
Default: normal
HorizontalAlignment
Alignment of label string
Value: left, center, right Default: depends on uicontrol object Value: string
String
Uicontrol object label, also list box and pop-up menu items
Controlling Callback Routine Execution BusyAction
Callback routine interruption Button press callback routine Control action Callback routine executed during object creation Callback routine executed during object deletion Callback routine interruption mode Uicontextmenu object associated with the uicontrol
Value: cancel, queue Default: queue Value: string Value: string Value: string Value: string Value: on, off Default: on Value: handle
ButtonDownFcn Callback CreateFcn
DeleteFcn
Interruptible
UIContextMenu
Information About the Current State ListboxTop
Index of top-most string displayed in list box
Value: scalar Default: [1]
2-627
uicontrol
Property Name Max
Property Description
Property Value
Maximum value (depends on uicontrol object) Minimum value (depends on uicontrol object) Current value of uicontrol object
Value: scalar Default: object dependent Value: scalar Default: object dependent Value: scalar or vector Default: object dependent
Min
Value
Controlling Access to Objects HandleVisibility
Whether handle is accessible from command line and GUIs Whether selectable by mouse click
Value: on, callback, off Default: on Value: on, off Default: on
HitTest
Examples
The following statement creates a push button that clears the current axes when pressed:
h = uicontrol('Style', 'pushbutton', 'String', 'Clear',... 'Position', [20 150 100 70], 'Callback', 'cla');
You can create a uicontrol object that changes figure colormaps by specifying a pop-up menu and supplying an M-file name as the object's Callback:
hpop = uicontrol('Style', 'popup',... 'String', 'hsv|hot|cool|gray',... 'Position', [20 320 100 50],... 'Callback', 'setmap');
The above call to uicontrol defines four individual choices in the menu: hsv, hot, cool, and gray. You specify these choices with the String property, separating the choices with the "|" character. The Callback, in this case setmap, is the name of an M-file that defines a more complicated set of instructions than a single MATLAB command. setmap contains these statements:
val = get(hpop,'Value'); if val == 1
2-628
uicontrol
colormap(hsv) elseif val == 2 colormap(hot) elseif val == 3 colormap(cool) elseif val == 4 colormap(gray) end
The Value property contains a number that indicates the selected choice. The choices are numbered sequentially from one to four. The setmap M-file can get and then test the contents of the Value property to determine what action to take.
Object Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Uicontextmenu
Uimenu
Uimenu
See Also
textwrap, uimenu
2-629
Uicontrol Properties
Modifying Properties
2Uicontrol Properties
You can set and query graphics object properties in two ways: The Property Editor is an interactive tool that enables you to see and change object property values. The set and get commands enable you to set and query the values of properties To change the default value of properties see Setting Default Property Values.
Uicontrol Property Descriptions
You can set default uicontrol properties on the root and figure levels:
set(0,'DefaultUicontrolProperty',PropertyValue...) set(gcf,'DefaultUicontrolProperty',PropertyValue...)
where Property is the name of the uicontrol property whose default value you want to set and PropertyValue is the value you are specifying. Use set and get to access uicontrol properties. Curly braces { } enclose the default value.
BackgroundColor ColorSpec
Object background color. The color used to fill the uicontrol rectangle. Specify a color using a three-element RGB vector or one of the MATLAB predefined names. The default color is determined by system settings. See ColorSpec for more information on specifying color.
BusyAction cancel | {queue}
Callback routine interruption. If a callback is executing and the user triggers an event (such as a mouse click) on an object for which a callback is defined, that callback attempts to interrupt the first callback. The first callback can be interrupted only at a drawnow, figure, getframe, pause, or waitfor command; if the callback does not contain any of these commands, it cannot be interrupted. If the Interruptible property of the object whose callback is executing is off (the default value is on), the callback cannot be interrupted (except by certain callbacks; see the note below). The BusyAction property of the object whose callback is waiting to execute determines what happens to the callback: If the value is queue, the callback is added to the event queue and executes after the first callback finishes execution.
2-630
Uicontrol Properties
If the value is cancel, the event is discarded and the callback is not executed.
Note If the interrupting callback is a DeleteFcn or CreateFcn callback or a figure's CloseRequest or ResizeFcn callback, it interrupts an executing callback regardless of the value of that object's Interruptible property. The interrupting callback starts execution at the next drawnow, figure, getframe, pause, or waitfor statement.
ButtonDownFcn
string
Button press callback routine. A callback routine that executes whenever you press a mouse button while the pointer is in a five-pixel wide border around the uicontrol. When the uicontrol's Enable property is set to inactive or off, the ButtonDownFcn executes when you click the mouse in the five-pixel border or on the control itself. This is useful for implementing actions to interactively modify control object properties, such as size and position, when they are clicked on (using selectmoveresize, for example). Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace. The Callback property defines the callback routine that executes when you activate the enabled uicontrol (e.g., click on a push button).
Callback
string (GUIDE sets this property)
Control action. A routine that executes whenever you activate the uicontrol object (e.g., when you click on a push button or move a slider). Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace. To execute the callback routine for an editable text control, type in the desired text, then either: Move the focus off the object (click the mouse someplace else in the GUI), For a single line editable text box, press Return, or For a multiline editable text box, press Ctl-Return. Callback routines defined for frames and static text do not execute because no action is associated with these objects.
2-631
Uicontrol Properties
CData
matrix
Truecolor image displayed on control. A three-dimensional matrix of RGB values that defines a truecolor image displayed on either a push button or toggle button. Each value must be between 0.0 and 1.0.
Children
matrix
...