MATLAB Programming scripts functions Scripts It is possible

MATLAB Programming: scripts & functions

Scripts • It is possible to achieve a lot simply by executing one command at a time on the command line (even possible to run loops, if…then conditional statements, etc). • It is easier & more efficient to save extended sets of commands as a script – a simple ascii file with a ‘. m’ file extension, containing all the commands you wish to run. The script is run by entering its filename (without. m extension) • In order for MATLAB to see a script it must be: – In the current working directory, or – In a directory on the current path

• Scripts are executed in the current workspace – they have access to all existing variables. New variables or changes to existing variables made by the script remain in the workspace after script has finished.

Functions • A MATLAB function is very similar to a script, but: – Starts with a function declaration line – May have defined input arguments – May have defined output arguments function [out 1, out 2]=function_name(in 1) – Executes in its own workspace: it CANNOT see, or modify variables in the calling workspace – values must be passed as input & output variables

function [x 1, x 2, x 3]=powers 1 to 3(n) % calculate first three powers of [1: n] % (a trivial example function) x 1=[1: n]; x 2=x 1. ^2; x 3=x 1. ^3; >> [x 1, x 2, x 3]=powers 1 to 3(4) x 1 = 1 2 3 4 >> [x 1, x 2]=powers 1 to 3(4) x 1 = 1 2 3 4 x 2 = 1 4 9 16 x 3 = 1 8 27 64 1 4 9 16 If fewer output parameters used than are declared, only those used are returned.

• There are many functions built-in or supplied with MATLAB. – A few very basic functions are built in to the matlab executable – Very many more are supplied as m-files; the code can be viewed by entering: >> type function_name – Supplied m-files can be found, grouped by category, in $matlab_root/toolbox/catagory

• For users on the ENV network: – ~ibrooks/matlab (env-fs-05u 12ibrooksmatlab from windows) lots of (>500) m-files related (more or less) to atmospheric science.

Function Help • MATLAB uses the ‘%’ character to start a comment – everything on line after ‘%’ is ignored • A contiguous block of comment lines following the first comment, is treated as the ‘help’ text for the function. This block is echoed to screen when you enter >> help function_name This is very useful…use it when writing code!

e. g. help text from a function to calculate equivalent potential temperature >> help epot MATLAB FUNCTION EPOT Calculates theta_e by Bolton's formula (Monthly Weather Review 1980 vol. 108, 1046 -1053) usage: epot=epot(ta, dp, pr) outputs epot inputs ta dp pr : : equivalent potential temperature (K) air temp (K) dew point (K) static pressure (mb) IM Brooks : july 22 1994

function epot=epot(ta, dp, pr) % MATLAB FUNCTION EPOT % Calculates theta_e by Bolton's formula (Monthly Weather % Review 1980 vol. 108, 1046 -1053) % % usage: epot=epot(ta, dp, pr) % % outputs % epot : equivalent potential temperature (K) % inputs ta : air temp (K) % dp : dew point (K) % pr : static pressure ( mb) % % IM Brooks : july 22 1994 What it does How it’s called What input and outputs are (and units!) % ensure temperatures are in kelvin ta(ta<100)=ta(ta<100)+273. 15; dp(dp<100)=dp(dp<100)+273. 15; % where dewpoint>temp, set dewpoint equal to temp dp(dp>ta)=ta(dp>ta); % calculate water vapour pressure and mass mixing ratio mr=mmr(dp, pr); vap=vp(dp); % calculate temperature at the lifing condensation level TL=(2840. /(3. 5*log(ta) - log(vap) - 4. 805))+55; % calculate theta_e epot=ta. *((1000. /pr). ^(0. 2854*(1 -0. 28 E-3* mr))). *. . . exp((3. 376. /TL - 0. 00254). * mr. *(1+0. 81 E-3*mr)); Good coding practice, note what and why…you will forget

Function arguments • [out 1, out 2]=afunction(in 1, in 2, in 3, in 4) Have seen that it is not necessary to use ALL of the output arguments when calling the function. It is possible to write functions to handle variable numbers of inputs & outputs – e. g. use of optional inputs, or changing behaviour in response to number of outputs called. • You CANNOT use more inputs/outputs than defined in function declaration.

• nargin – returns number of input arguments used in function call • nargout – returns number of output arguments used in function call function [x, y]=afunction(a, b, c) % …help text… if nargin<3 c=1; end …rest of code… Set a default value if an input variable is not supplied

• Two special input & output arguments – varargin and varargout – can be used for variable-length input and output argument arrays. function varargout=afunction(varargin) Can call a function declared like this with any number of input and output arguments…it is up to the programmer to handle them. Use nargin, nargout to determine number of arguments.

Program Control • Most programming languages have a similar set of program control features: – Loops • ‘for’ loops – counter controlled • ‘while’ or ‘repeat until’ loops - condition controlled – If-then conditions – switch/case conditions

If, elseif Generic form: if condition statements; else statements; end example if A<0 disp(‘A is negative’) elseif A>0 disp(‘A is positive’) else disp(‘A is neither’) end

switch, case Generic form: switch statement case value 1 statements; case value 2 statements; otherwise statements; end example switch A*B case 0 disp(‘A or B is zero’) case 1 disp(‘A*B equals 1’) case C*D disp(‘A*B equals C*D’) otherwise disp(‘no cases match’) end A case is matched when the switch statement equals the case value (may be the result of a statement). Only first matching case is executed, then switch statement exits, remaining cases are not tested.

for loops Generic form: for n=firstn: dn: lastn statements; end example for n = 1: 10 x(n)=n^2; end N. B. loops are rather inefficient in MATLAB (and IDL), the example above would execute much faster if vectorized as >> x=[1: 10]. ^2; If you can vectorize code instead of using a loop, do so. for variable=expression statements; end More generally (but rarely used), if expression returns a matrix, then each column in turn is returned to the control variable

while Generic form: while condition statements; end example n = 1; while n <= 10 x(n)=n^2; n=n+1; end The statements within the while loop are executed repeatedly while the condition is true. Example does exactly the same as the for loop in previous example (another inefficient loop). If the condition is false when first tested, the statements in the while loop will never be executed.

continue, break, return • continue – forces current iteration of loop to stop and execution to resume at the start of next iteration. • break – forces loop to exit, and execution to resume at first line after loop. • return – forces current function to terminate, and control to be passed back to the calling function or keyboard.

strings • MATLAB treats strings as arrays of characters – A 2 D ‘string’ matrix must have the same number of characters on each row! >> name = [‘Ian’, ’Brooks’] name = Ian. Brooks >> name=[‘Ian'; ‘Brooks'] ? ? ? Error using ==> vertcat All rows in the bracketed expression must have the same number of columns >> name=[‘Ian Name = Ian Brooks '; ‘Brooks']

• Can concatenate strings as: >> firstname = ‘Ian’; >> secondname = ‘Brooks’; >> fullname = [firstname, ‘ ’, secondname] fullname = Ian Brooks • Strings defined within single quotation marks quotation mark within a string needs double quoting >> sillyname = 'Ian ''matlab-guru'' Brooks' sillyname = Ian 'matlab-guru' Brooks

Evaluating strings • The ‘eval’ function takes a string argument and evaluates it as a MATLAB command line – this can be a useful way of building commands to execute without knowing in advance all of the terms to include. >> filename = input(‘enter filename to save to: ’, ’s’); enter filename to save to: My. Data >> eval([‘save ‘, filename]) First line requests input as a string from the user, this is assigned to the variable ‘filename’ – here the string ‘My. Data’ has been entered Second line evaluates/executes the string as ‘save My. Data’

>> leg 1=‘time>45225&time<45825’; >> plot(time(eval(leg 1)), alt(eval(leg 1))); >> ii=eval(leg 1); >> plot(time(ii), alt(ii)); Above is an example of the way I use string evaluation with aircraft data. Flight legs are defined as periods with well defined heading, altitude, etc… I create a set of flight leg definition variables leg 1, leg 2, etc that can be loaded with the aircraft data. These are simply strings that contain an expression that evaluates to a logical index into the timeseries. One such definition is defined above, the two plot statements (of altitude against time) are equivalent, but one evaluates the expression within the plot statement, the other evaluates it separately.

Functional forms of basic commands • Most of MATLAB’s basic commands for determining workspace/environment information (who, whos, pwd, dir, …) have a functional form that returns information to a variable rather than simply echoing it to screen. >> vars = who vars = ‘alt’ ‘time’ ‘P’ ‘T 2’ Note – strings are of different lengths…how?

Can also pass a regular expression as an input to match a subset of the variables >> vars = who(‘T*’) vars = ‘T’ ‘T 2’ The different length strings are possible because the ‘who’ function does not return a regular array, but a cell array.

Cell arrays • Cell arrays are arrays of arbitrary data objects, as a whole they are dimensioned similar to regular arrays/matrices, but each element can hold any valid matlab data object: a single number, a matrix or array, a string, another cell array… • They are indexed in the same manner as ordinary arrays, but with curly brackets >> X{1}=[1 2 3 4]; >> X{2}=‘some random text’ X = [1 x 4 double] 'some random text'

Index an array element within a cell, by concatenating the indices: >> X{1} ans = 1 >> X{1}(2) ans = 2 2 3 4 Cell arrays are particularly useful for storing arrays of strings, rather than arrays of characters. >> drinks = {‘beer’, ’whisky’, ’gin’, ’wine’, ’water’} drinks = ‘beer’ ‘whisky’ ‘gin’ ‘wine’ ‘water’ >> drinks{4} ans = ‘wine’

Structure arrays • MATLAB supports structured variables with named fields in a similar manner to other programming languages. The fields can contain any data type. Structured arrays are returned by the functional forms of ‘whos’ and ‘dir’. >> dir. . . demo. 2 D. mat demo. m demo. profiles. mat demo. timeseries. mat demomovie. m demowindmovie. m movieframes. mat run. Qmovie. m Simple ‘dir’ command echos directory contents to screen. . .

>> dlist=dir dlist = 10 x 1 struct array with fields: name date bytes isdir Functional form of ‘dir’ returns filenames, timestamp, size, and a logical flag to indicate if the file is a directory >> dlist(1) ans = name: '. ' date: '29 -Mar-2005 12: 03: 54' bytes: 0 isdir: 1

>> dlist(3) ans = name: 'demo. 2 D. mat' date: '29 -Mar-2005 12: 23: 40' bytes: 54436504 isdir: 0 >> dlist(4). name ans = demo. m Again, a pattern matching expression can be provided as input to dir to limit the range of files returned. Could use this as a means to load and process a set of files: >> dlist=dir(‘*. mat’); >> for n=1: length(dlist), eval([‘load ‘, dlist(n). name]), run_my_processing(inputs. . . ); clear all, end >> Note loop run from command line!