ZTransSCi.m

function Res = ZtransSCi(SCi,varargin)
% ZTRANSCI Z-transforms a smooth classification image.
% 	In ZtransCi(SCi, meanSCi, stdSCi) the mean (meanSCi) and the standard 
% 	deviation (stdSCi) of the classification image are provided by the user.
% 		E.g.,
% 		mask = double(imread('faceMask.tif'));
% 		mask = (mask - min(mask(:))) / (max(mask(:)) - min(mask(:)));
% 		Ci = double(imread('GenderFG.tiff'));
% 		vecCi = Ci(eq(mask, 0));
% 		ZCi = ZTransCi(Ci, mean(vecCi(:)), std(vecCi(:)));
% 
% 	In ZtransCi(SCi, meanSCi) the mean (meanSCi) of the classification image 
% 	is provided by the user and the standard deviation is estimated from the data.
% 
% 	In ZtransCi(SCi) the mean and the standard deviation of the classification image 
% 	are estimated from the data.
% 
% 	In ZtransCi(Ci1, n1, Ci2, n2, sigmaNoise, smoothFilter),
% 		Ci1 = sum of white noise fields that led to a type 1 response (e.g., correct)  
% 		n1 = number of type 1 response
% 		Ci2 = sum of white noise fields that led to a type 2 response (e.g., incorrect)  
% 		n2 = number of type 2 response 
% 		sigmaNoise = standard deviation of white noise
% 		smoothFilter = Gaussian filter used to smooth the classification image
% 	For an explanation, see:
% 		Chauvin, Worsley, Schyns, Arguin & Gosselin (2004). A sensitive statistical 
% 		test for smooth classification images.
% 
% See also SMOOTHCI, DEMOSTAT4CI
%  
% The Stat4Ci toolbox is free (http://mapageweb.umontreal.ca/gosselif/stat4ci.html); if you use 
% it in your research, please, cite us:
%	Chauvin, A., Worsley, K. J., Schyns, P. G., Arguin, M. & Gosselin, F. (2004).  A sensitive 
%	statistical test for smooth classification images.
% 
% Alan Chauvin & FrŽdŽric Gosselin (frederic.gosselin@umontreal.ca), 20/08/2004


% the mean and the std are estimated if not provided
switch nargin
case 6,

	cCi = SCi; 
	nc = varargin{1};
	iCi = varargin{2};
	ni = varargin{3};
	sigmaNoise = varargin{4};
	smoothFilter = varargin{5};
	
	n = ni + nc;				% number of trial
	
	rhoC = (cCi/nc-iCi/ni)*nc*ni/n;
	
	NvarX = n*sigmaNoise^2*sum(smoothFilter(:).^2);
	NvarY = nc*ni/n;
	
	% Z transform
	Res.ZSCi = sqrt(n)*rhoC/sqrt(NvarX)/sqrt(NvarY);

case 5,

	Ci = SCi; 
	nc = varargin{1};
	ni = varargin{2};
	sigmaNoise = varargin{3};
	smoothFilter = varargin{4};
	
	n = ni + nc;				% number of trial
	
	rhoC = Ci;
	
	NvarX = n*sigmaNoise^2*sum(smoothFilter(:).^2);
	NvarY = nc*ni/n;
	
	% Z transform
	Res.ZSCi = sqrt(n)*rhoC/sqrt(NvarX)/sqrt(NvarY);
	
case 3

	muCi = varargin{1};
	stdCi = varargin{2};
	% Z transform
	Res.ZSCi = (SCi - muCi) / stdCi;
	
case 2

	stdCi = std(SCi(:));
	muCi = varargin{1};
	
	% Z transform
	Res.ZSCi = (SCi - muCi) / stdCi;
	
case nargin == 1

    muCi = mean(SCi(:));
    stdCi = std(SCi(:));
    
    % Z transform
    Res.ZSCi = (SCi - muCi) / stdCi;

otherwise

	error('Incorrect number of arguments.')

end