% A second example of a MATLAB file, which illustrates
%   loops, if statements, and MATLAB function files.
%
% Suppose first that you want to define a 2x5 matrix A whose
%   first row is 1 to 5 and whose second row is the squares
%   of the entries in the first row.
% We can do this using a for loop:
%
  A = zeros(2,5);    % Define a 2x5 matrix with entries to fill
  for i=1:5;  A(1,i)=i;  A(2,i)=i*i;  end;
  A		     % Display A when done

% The `for` loop must `end` with end; even if there is only
% one statement. The 3rd line displays the new A. MATLAB displays
%
% A =
%
%     1     2     3     4     5
%     1     4     9    16    25

% You can also define A using built-in MATLAB commands:

  x = (1:5);      % x is a 1x5 row vector with those integers
  A = [x; x.*x]	  % x.*x  means COMPONENTWISE multiplication
                  %  so that the values become squares
                  % A is a 2x1 matrix whose entries are row vectors

% MATLAB displays
%
% A =
%
%     1     2     3     4     5
%     1     4     9    16    25
%
% exactly as before.

% The next example illustrates a literal Disp (display) statement
%   and a double loop.
% Suppose that you want to define a 4x4 matrix C(i,j) whose entries
%   are i+j. One way to do this is

  disp('Define a matrix C whose entries are i+j')
  C = zeros(4,4);   % Define a 4x4 matrix to fill
  for i=1:4;  for j=1:4;  C(i,j)=i+j;  end;  end;
  C	 % Display C

% Note that you need two `end`s to terminate the two loops.
% MATLAB responds

% Define a matrix C whose entries are i+j
%
% C =
%
%     2     3     4     5
%     3     4     5     6
%     4     5     6     7
%     5     6     7     8

% The next example shows an `if` statement. The key is that
%   an `if` statement must always end with `end`.

  disp('Replace the entries with C(i,j)=5 by zero and the rest by 7:')
  for i=1:4;  for j=1:4;  
    if C(i,j)==5  C(i,j)=0;  else C(i,j)=7;  end;  end;  end;
  C	 % Display C

% Note (i) The syntax of `if` is `if Condition DO_THIS; end;`
%   or else `if Condition DO_THIS; else DO_THAT; end;`
%   Both DO_THIS and DO_THAT can be multiple statements.
% (ii) Use == for `logical equals` (if 3 equals 5)
%   and = for assignment (set x equal to 3)
% (iii) the double loop must end with THREE `end`s:
%   The first `end` to end the `if` statement and two `end`s
%   to end the double loop.
%
% MATLAB responds

% Replace the entries with C(i,j)=5 by zero and the rest by 7:
% 
% C =
% 
%      7     7     7     0
%      7     7     0     7
%      7     0     7     7
%      0     7     7     7
     
% DEFINING AND USING YOUR OWN FUNCTIONS
%
% MATLAB does not support P-values for standard probability
%   distributions unless you have the MATLAB Statistics Toolbox, 
%   which does not come with all MATLAB installations.
%
% However, basic MATLAB does support the complementary error
%   function and the incomplete beta and gamma functions,
%   which can be used to obtain P-values based on the normal,
%   chi-square, Student-t, F-distribution, and Bernoulli
%   distributions.
%
%
% To make your own MATLAB function, called for example myfun(),
%   (or myfun(x) or myfun(x,y) or myfun(x,y,z)),
%   (i) write a `MATLAB function file`  myfun.m  with syntax
%     (for example, ignoring comments)
%
%   function  A = myfun(x,y,z)
%       (compute the return value A here)
%
%   The final value of A in the computation is what the function returns.
%   A is usually a number, but can be a vector or matrix.
%   (See the example below)
%   (ii) Make sure that the file  myfun.m  is either in the MATLAB
%     Current Directory is else is on the MATLAB search path
%     (if you want to put several function files in one subdirectory)
%
% For example, the enclosed function file  normpval.m  has lines
%
%  % Return two-sided normal Pvalue Prob(|N(0,1)| >= |xx|)
%  % The constant is sqrt(2)
%  function pval = normpval(xx)
%    pval = erfc(abs(xx)/(1.41421356237309504880));

% This defines the two-sided normal P-value from the complementary
%   error function  erfc(x)

% The MATLAB command     p=normpval(x)  will then return the
% a (two-sided) normal P-value.  The function  normpval(x) is
% `vectorized`, so that  normpval  can be applied to a vector
% or matrix. As an example:

% A row vector of values that  normpval  will be applied to:
x = [0.67449  1.64485  1.95996  2.32635	 2.57583];

% A row vector with two-sided normal P-values:
pv = normpval(x);

% A nicer format would be to display  x  and  pv  in a 5x3 table
% with row numbers in the first column,  x in the second column,
% and pv in the third column. The next command does this.

NormTable = [(1:5)'  x'  pv'];   %' Define the table, no display

% Now the display:

disp('Examples of two-sided normal P-values:')

NormTable     % Display the 5x3 table with 5 normal P-values

% While the table looks nicer, it is still rather crude. You can
%   get nicer output by using the MATLAB function  fprintf(),
%   which is very similar to the same function in C:

disp('Table with better output formatting using `fprintf`:')
disp(' ')

fprintf ('        Value    Normal P-value (2-sided)\n')
fprintf ('  %d.   %7.5f   %8.6f\n', NormTable')   %'

% For each row of NormTable (or COLUMN of NormTable`), this
%   displays the first entry as an integer (%d) (Here 1-5),
%   the second entry with (minimal) width=7 with 5 numbers
%   beyond the decimal point, and the third entry (the P-values)
%   with minimal width=8 and 6 numbers beyond the decimal point.
%
% The final \n in each line tells MATLAB to end the line at that point.
%
% The function  fprintf()  is vectorized, in the sense that
%   you only have to give one command for all 5 rows of NormTable.
%   However, fprintf() is vectorized by COLUMNS rather than
%   rows. Hence if you have a matrix of data that you want
%   to display, with each row of data to be displayed as
%   one row in the output, you must apply  fprintf() to the
%   TRANSPOSE of the data matrix, as we did above.
%
% The function  fprintf()  can also be used to write output
%   to a text file. Using fprintf() in this way seems to be
%   the best way to get nice-looking hard copy from MATLAB.
%
