# ftestc

## PURPOSE

computes the F-statistic for sine wave in locally-white noise (continuous data).

## SYNOPSIS

function [Fval,A,f,sig,sd] = ftestc(data,params,p,plt)

## DESCRIPTION

     computes the F-statistic for sine wave in locally-white noise (continuous data).

     [Fval,A,f,sig,sd] = ftestc(data,params,p,plt)

      Inputs:
           data        (data in [N,C] i.e. time x channels/trials or a single
           vector) - required.
           params      structure containing parameters - params has the
           following fields: tapers, Fs, fpass, pad
               tapers : precalculated tapers from dpss or in the one of the following
                        forms:
                        (1) A numeric vector [TW K] where TW is the
                            time-bandwidth product and K is the number of
                            tapers to be used (less than or equal to
                            2TW-1).
                        (2) A numeric vector [W T p] where W is the
                            bandwidth, T is the duration of the data and p
                            is an integer such that 2TW-p tapers are used. In
                            this form there is no default i.e. to specify
                            the bandwidth, you have to specify T and p as
                            well. Note that the units of W and T have to be
                            consistent: if W is in Hz, T must be in seconds
                            and vice versa. Note that these units must also
                            be consistent with the units of params.Fs: W can
                            be in Hz if and only if params.Fs is in Hz.
                            The default is to use form 1 with TW=3 and K=5

                Fs             (sampling frequency) -- optional. Defaults to 1.
               fpass       (frequency band to be used in the calculation in the form
                                       [fmin fmax])- optional.
                                       Default all frequencies between 0 and Fs/2
                pad            (padding factor for the FFT) - optional (can take values -1,0,1,2...).
                        -1 corresponds to no padding, 0 corresponds to padding
                        to the next highest power of 2 etc.
                           e.g. For N = 500, if PAD = -1, we do not pad; if PAD = 0, we pad the FFT
                           to 512 points, if pad=1, we pad to 1024 points etc.
                           Defaults to 0.
            p            (P-value to calculate error bars for) - optional.
                               Defaults to 0.05/N where N is the number of samples which
                         corresponds to a false detect probability of approximately 0.05.
           plt         (y/n for plot and no plot respectively)

      Outputs:
           Fval        (F-statistic in frequency x channels/trials form)
              A            (Line amplitude for X in frequency x channels/trials form)
            f            (frequencies of evaluation)
           sig         (F distribution (1-p)% confidence level)
           sd          (standard deviation of the amplitude C)

## CROSS-REFERENCE INFORMATION

This function calls:

- mtfftc Multi-taper fourier transform - continuous data
- mtspectrumc Multi-taper spectrum - continuous process
- change_row_to_column Helper routine to transform 1d arrays into column vectors that are needed
- dpsschk Helper function to calculate tapers and, if precalculated tapers are supplied,
- getfgrid Helper function that gets the frequency grid associated with a given fft based computation
- getparams Helper function to convert structure params to variables used by the

This function is called by:

- fitlinesc fits significant sine waves to data (continuous data).

## SOURCE CODE

    0001 function [Fval,A,f,sig,sd] = ftestc(data,params,p,plt)
    0002 % computes the F-statistic for sine wave in locally-white noise (continuous data).
    0003 %
    0004 % [Fval,A,f,sig,sd] = ftestc(data,params,p,plt)
    0005 %
    0006 %  Inputs:
    0007 %       data        (data in [N,C] i.e. time x channels/trials or a single
    0008 %       vector) - required.
    0009 %       params      structure containing parameters - params has the
    0010 %       following fields: tapers, Fs, fpass, pad
    0011 %           tapers : precalculated tapers from dpss or in the one of the following
    0012 %                    forms:
    0013 %                    (1) A numeric vector [TW K] where TW is the
    0014 %                        time-bandwidth product and K is the number of
    0015 %                        tapers to be used (less than or equal to
    0016 %                        2TW-1).
    0017 %                    (2) A numeric vector [W T p] where W is the
    0018 %                        bandwidth, T is the duration of the data and p
    0019 %                        is an integer such that 2TW-p tapers are used. In
    0020 %                        this form there is no default i.e. to specify
    0021 %                        the bandwidth, you have to specify T and p as
    0022 %                        well. Note that the units of W and T have to be
    0023 %                        consistent: if W is in Hz, T must be in seconds
    0024 %                        and vice versa. Note that these units must also
    0025 %                        be consistent with the units of params.Fs: W can
    0026 %                        be in Hz if and only if params.Fs is in Hz.
    0027 %                        The default is to use form 1 with TW=3 and K=5
    0028 %
    0029 %            Fs             (sampling frequency) -- optional. Defaults to 1.
    0030 %           fpass       (frequency band to be used in the calculation in the form
    0031 %                                   [fmin fmax])- optional.
    0032 %                                   Default all frequencies between 0 and Fs/2
    0033 %            pad            (padding factor for the FFT) - optional (can take values -1,0,1,2...).
    0034 %                    -1 corresponds to no padding, 0 corresponds to padding
    0035 %                    to the next highest power of 2 etc.
    0036 %                       e.g. For N = 500, if PAD = -1, we do not pad; if PAD = 0, we pad the FFT
    0037 %                       to 512 points, if pad=1, we pad to 1024 points etc.
    0038 %                       Defaults to 0.
    0039 %        p            (P-value to calculate error bars for) - optional.
    0040 %                           Defaults to 0.05/N where N is the number of samples which
    0041 %                     corresponds to a false detect probability of approximately 0.05.
    0042 %       plt         (y/n for plot and no plot respectively)
    0043 %
    0044 %  Outputs:
    0045 %       Fval        (F-statistic in frequency x channels/trials form)
    0046 %          A            (Line amplitude for X in frequency x channels/trials form)
    0047 %        f            (frequencies of evaluation)
    0048 %       sig         (F distribution (1-p)% confidence level)
    0049 %       sd          (standard deviation of the amplitude C)
    0050 if nargin < 1; error('Need data'); end;
    0051 if nargin < 2 || isempty(params); params=[]; end;
    0052 [tapers,pad,Fs,fpass,err,trialave,params]=getparams(params);
    0053 clear err trialave
    0054 data=change_row_to_column(data);
    0055 [N,C]=size(data);
    0056 if nargin<3 || isempty(p);p=0.05/N;end;
    0057 if nargin<4 || isempty(plt); plt='n';end;
    0058 tapers=dpsschk(tapers,N,Fs); % calculate the tapers
    0059 [N,K]=size(tapers);
    0060 nfft=max(2^(nextpow2(N)+pad),N);% number of points in fft
    0061 [f,findx]=getfgrid(Fs,nfft,fpass);% frequency grid to be returned
    0062 % errorchk = 0; % set error checking to default (no errors calculated)
    0063 % if nargout <= 3 % if called with 4 output arguments, activate error checking
    0064 %     errorchk = 0;
    0065 % else
    0066 %     errorchk = 1;
    0067 % end
    0068 Kodd=1:2:K;
    0069 Keven=2:2:K;
    0070 J=mtfftc(data,tapers,nfft,Fs);% tapered fft of data - f x K x C
    0071 Jp=J(findx,Kodd,:); % drop the even ffts and restrict fft to specified frequency grid - f x K x C
    0072 tapers=tapers(:,:,ones(1,C)); % add channel indices to the tapers - t x K x C
    0073 H0 = squeeze(sum(tapers(:,Kodd,:),1)); % calculate sum of tapers for even prolates - K x C
    0074 if C==1;H0=H0';end;
    0075 Nf=length(findx);% number of frequencies
    0076 H0 = H0(:,:,ones(1,Nf)); % add frequency indices to H0 - K x C x f
    0077 H0=permute(H0,[3 1 2]); % permute H0 to get dimensions to match those of Jp - f x K x C
    0078 H0sq=sum(H0.*H0,2);% sum of squares of H0^2 across taper indices - f x C
    0079 JpH0=sum(Jp.*squeeze(H0),2);% sum of the product of Jp and H0 across taper indices - f x C
    0080 A=squeeze(JpH0./H0sq); % amplitudes for all frequencies and channels
    0081 Kp=size(Jp,2); % number of even prolates
    0082 Ap=A(:,:,ones(1,Kp)); % add the taper index to C
    0083 Ap=permute(Ap,[1 3 2]); % permute indices to match those of H0
    0084 Jhat=Ap.*H0; % fitted value for the fft
    0085
    0086 num=(K-1).*(abs(A).^2).*squeeze(H0sq);%numerator for F-statistic
    0087 den=squeeze(sum(abs(Jp-Jhat).^2,2)+sum(abs(J(findx,Keven,:)).^2,2));% denominator for F-statistic
    0088 Fval=num./den; % F-statisitic
    0089 if nargout > 3
    0090    sig=finv(1-p,2,2*K-2); % F-distribution based 1-p% point
    0091    var=den./(K*squeeze(H0sq)); % variance of amplitude
    0092    sd=sqrt(var);% standard deviation of amplitude
    0093 end;
    0094 if nargout==0 || strcmp(plt,'y');
    0095    [S,f]=mtspectrumc(detrend(data),params);subplot(211); plot(f,10*log10(S));xlabel('frequency Hz'); ylabel('Spectrum dB');
    0096    subplot(212);plot(f,Fval); line(get(gca,'xlim'),[sig sig],'Color','r');xlabel('frequency Hz');
    0097    ylabel('F ratio');
    0098 end
    0099 A=A*Fs;