powerZ(Z,c,a)

function [powerZ] = powerZ(Z,c,a)
%Power estimation of a performed Z test about mean(s).
%(Estimates the statistical power of a performed Z test about mean(s).
%It recalls you the statistical result of the test you should have arrived.)
%
%   Syntax: function [powerZ] = powerZ(Z,c,a) 
%      
%     Inputs:
%          Z - Z statistic. 
%          c - specified direction testing (1 = one-tailed; 2 = two-tailed).
%          a - significance level (default = 0.05).
%     Outputs:
%          Specified direction test.
%          (Statistical result of the test you should have arrived).
%          Power.
%
%    Example: From the example 6.6 of Zar (1999, p.81), the estimation of power
%             of a one-sample Z test for a two-tailed hypothesis (c = 2) with a 
%             significance level = 0.05 (Z = 1.7917, c = 2).
%                                       
%     Calling on Matlab the function: 
%             powerZ(1.7917,2)
%
%       Answer is:
%
%    It is a two-tailed hypothesis test.
%    (The null hypothesis was not statistically significative.)
%    Power is: 0.4333
%

%  Created by A. Trujillo-Ortiz and R. Hernandez-Walls
%             Facultad de Ciencias Marinas
%             Universidad Autonoma de Baja California
%             Apdo. Postal 453
%             Ensenada, Baja California
%             Mexico.
%             [e-mail]
%
%  January 2, 2003.
%
%  To cite this file, this would be an appropriate format:
%  Trujillo-Ortiz, A. and R. Hernandez-Walls. (2003). powerZ: Power estimation of a performed
%    Z test about mean(s). A MATLAB file. [WWW document]. URL http://www.mathworks.com/
%    matlabcentral/fileexchange/loadFile.do?objectId=2908&objectType=file
%
%  References:
% 
%  Zar, J. H. (1999), Biostatistical Analysis. 4th. ed.   
%           New-Jersey:Upper Saddle River. p. 81, and it must follows the same 
%           statistical procedure that for the Student's t test (p. 107-108,
%           135-136,164.)
%

if nargin < 3, 
    a = 0.05; 
end 

if nargin < 2, 
    error('Requires at least two input arguments.'); 
end 

Z=abs(Z);

if c==1;
   disp('It is a one-tailed hypothesis test.');
   a=a;
   P=1-normcdf(Z);
   if P >= a;
      disp('(The null hypothesis was not statistically significative.)');
      Zp=norminv(1-a) - Z;  %Power estimation.
      Power=1-normcdf(Zp);
      disp('  ');
      fprintf('Power is: %2.4f\n\n', Power)
   else
      disp('(The null hypothesis was statistically significative.)');
      Zb=Z - norminv(1-a);  %Power estimation.
      Power=normcdf(Zb);
      disp('  ');
      fprintf('Power is: %2.4f\n\n', Power)
   end
else c==2;
   disp('It is a two-tailed hypothesis test.');
   a=a/2;
   P=1-normcdf(Z);
   if P >= a;
      disp('(The null hypothesis was not statistically significative.)');
      Zp1=norminv(1-a) - Z;  %Power estimation.
      Power1=1-normcdf(Zp1);
      Zp2=Z + norminv(1-a);
      Power2=1-normcdf(Zp2);
      Power=Power1 + Power2;
      disp('  ');
      fprintf('Power is: %2.4f\n\n', Power)
   else
      disp('(The null hypothesis was statistically significative.)');
      Zb1=Z - norminv(1-a);  %Power estimation.
      b1=1-normcdf(Zb1);
      Zb2=Z + norminv(1-a);
      b2=1-normcdf(Zb2);
      Power=1 - (b1 - b2);
      disp('  ');
      fprintf('Power is: %2.4f\n\n', Power)
   end
end