multstat(x,p)

function [m,v,s] = multstat(x,p)
% MULTSTAT Mean, variance and standard deviation of the multinomial distribution.
%  [M,V,S] = MULTSTAT(N,P) returns the mean, variance and
%  standard deviation of the multinomial distribution with parameters
%  N and P.
%  The Expected Value (i.e., averages): 
%  Expected Value = m = Sum(Xi  Pi), the sum is over all i's. 
%  Expected value is another name for the mean and (arithmetic) average.
%  The Variance is: 
%  Variance = s2 = v = Sum[Xi2  Pi] - m2, the sum is over all i's. 
%  The variance is not expressed in the same units as the expected value.
%  So, the variance is hard to understand and to explain as a result of 
%  the squared term in its computation. This can be alleviated by working
%  with the square root of the variance, which is called the Standard 
%  (i.e., having the same unit as the data have) Deviation: 
%  Standard Deviation = s = (Variance)  
%
%  Syntax: function [m,v,s] = multstat(x,p) 
%      
%  Inputs:
%       x - vector of the interested values.
%       p - vector of associated probabilities. 
%  Outputs:
%       m - multinomial mean value (default).
%       v - multinomial variance value (optional).
%       s - multinomial standard deviation value (optional).
%
%  Example from the Dr. Hossein Arsham Statistic Site (http://www.staff.vu.edu.au/
%  sarath/Business-stats/opre504.htm). For a multinomial distribution function
%  (http://www.staff.vu.edu.au/sarath/Business-stats/opre504.htm#rmultinomial). 
%  Consider two investment alternatives, Investment I and Investment II with the
%  characteristics outlined in the following table: 
%
%                - Two Investments -  
%           Investment I  Investment II 
%           Payoff  Prob.  Payoff  Prob. 
%              1    0.25      3    0.33 
%              7    0.50      5    0.33 
%             12    0.25      8    0.34 
%
%  Performance of Two Investments. To rank these two investments under the
%  Standard Dominance Approach in Finance, first we must compute the mean 
%  and standard deviation and then analyze the results. We notice that the
%  Investment I has mean = 6.75% and standard deviation = 3.9%, while the
%  second investment has mean = 5.36% and standard deviation = 2.06%.
%
%  For the investment I,
%
%  Calling on Matlab the function: 
%             [m,v,s] = multstat(x,p)
%
%  where x = [1,7,12]  and  p = [.25,.5,.25]
%
%  Answer is:
%
%  m =  6.7500
%  v = 15.1875
%  s =  3.8971
%
%  Created by A. Trujillo-Ortiz, R. Hernandez-Walls and A. Castro-Perez
%             Facultad de Ciencias Marinas
%             Universidad Autonoma de Baja California
%             Apdo. Postal 453
%             Ensenada, Baja California
%             Mexico.
%             [e-mail]
%  Copyright (C) January 12, 2005.
%
%  To cite this file, this would be an appropriate format:
%  Trujillo-Ortiz, A., R. Hernandez-Walls and A. Castro-Perez. (2005). multstat:
%    Multinomial mean, variance and standard deviation.. A MATLAB file. [WWW document]. 
%    URL http://www.mathworks.com/matlabcentral/fileexchange/loadFile.do?objectId=6787
%
%  References:
% 
%  Arsham, H. Statistic Site http://www.staff.vu.edu.au/sarath/Business-stats/opre504.htm
%          http://www.staff.vu.edu.au/sarath/Business-stats/opre504.htm#rmultinomial
%

if nargin < 2, 
   error('You need to input two arguments.');
   return,
end;

k = length(x);
l = length(p);

if k ~= l, 
   error('The input arguments have unequal size.');
   return,
end;

pp = sum(p);

if pp ~= 1,
    error('The sum of the input probabilities must be equal 1.')
    return
end;

m = sum(x.*p);
v = sum(x.^2.*p)-m^2;
s = sqrt(v);

return,