# chronux

## PURPOSE

This library performs time-frequency analysis (mostly using the

## SYNOPSIS

function chronux

## DESCRIPTION

     This library performs time-frequency analysis (mostly using the
     multi-taper spectral estimation method) of univariate and multivariate
     data, both for continuous processes such as LFP/EEG and for point
     processes such as spike times. Point process can either be stored as
     times or as a binned process of counts. The routines in this library
     are named differently for the three cases. For calculations
     that can be performed for each of the three data types, we use suffixes
     c, pb, or pt to refer to continuous, point process binned counts, or
     point process times. For example, the spectrum calculation is performed
     mtspectrumc for continuous processes, mtspectrumpb for a binned point
     process, and mtspectrumpt for a point process consisting of times. There
     are also routines for calculating hybrid quantities involving one continuous
     and one point process. These are suffixed in a similar manner. For
     example, coherencycpb calculates the coherency between a binned point process
     and a continuous process.

     Certain variables are used repeatedly in this library.

     DATA
     data in most cases can be univariate or multivariate, and either point process,
     or continuous.

          Continuous data: Continuous data is assumed to be a matrix with
                           dimensions samples x channels/trials.

          Point Process: A single time series of spike times can be in the form of
                         a column vector.
                         Multichannel/trial spike time data is not amenable to this
                         storage format, since there are generally different
                         number of spikes in each channel/trial. Instead,
                         multichannel/trial spike data is stored in a structure
                         array. A structure is a matlab data object with various
                         fields. These fields contain the elements
                           e.g. The command data=struct('times',[]); creates an empty
                                structure with field 'times'. Similarly, the command
                                data=struct('times',[1 2 3]); creates the structure with
                                the field 'times' containing integers 1, 2, and 3.

                         We can also have a structure array (or an array of structures)
                         defined for example, by
                         data(1)=struct('times',rand(1,100)); and
                         data(2)=struct('times',rand(1,200));
                         This is a 2 dimensional structure array where the
                         first field is a 100 dimensional random vector, and
                         the second field is a 200 dimensional random vector.
                         This format allows storage of multichannel point
                         process times in a single variable data.

                         The above holds for point processes stored as times.
                         If instead, the point processes are binned, then one
                         can use a matrix to represent them

          Summary: data - array of continuous data with dimensions time x channels
                          structural array of spike times with dimensions
                                   equal to the number of channels
                          1d array of spike times as a column vector
                          array of binned spike counts with dimensions time x channels

     PARAMETERS:
     These are various parameters used in the spectral calculations. Since
     these parameters are used by most routines in Chronux, they are stored in
     a single structure params. The fields of params are

     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

     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.

     Fs:sampling frequency.optional (default 1)

     fpass: frequencies in an fft calculation can range from 0 to Fs/2 where
            Fs is the sampling frequency. Sometimes it may be useful to
            compute fourier transforms (and resulting quantities like the
            spectrum over a smaller range of frequencies). This is specified
            by fpass, which can be in the form [fmin fmax] where fmin >=0 and
            fmax<=Fs/2. optional (default [0 Fs/2])

     err=[errtype p] calculates theoretical error bars (confidence levels)
                     when errtype=1 and jackknife error bars when errchk=2. In each case, the
                     error is calculated at a p value specified by p. -
                     optional (default 0)

     trialave: trialave controls whether or not to average over channels/trials for
               multichannel/trial analyses. trialave=0 (default) implies no trial
               averaging, trialave=1 implies that the quantity of interest is averaged
               over channels/trials. optional (default 0)

     Other parameters are discussed in individual routines as and when they
     are used.

## CROSS-REFERENCE INFORMATION

This function calls:

This function is called by:

- testAvg3 This is a calling routine to test & check out the power spectrum &
- testAvg4 This is a calling routine to test & check out the power spectrum &

## SOURCE CODE

    0001 function chronux
    0002 % This library performs time-frequency analysis (mostly using the
    0003 % multi-taper spectral estimation method) of univariate and multivariate
    0004 % data, both for continuous processes such as LFP/EEG and for point
    0005 % processes such as spike times. Point process can either be stored as
    0006 % times or as a binned process of counts. The routines in this library
    0007 % are named differently for the three cases. For calculations
    0008 % that can be performed for each of the three data types, we use suffixes
    0009 % c, pb, or pt to refer to continuous, point process binned counts, or
    0010 % point process times. For example, the spectrum calculation is performed
    0011 % mtspectrumc for continuous processes, mtspectrumpb for a binned point
    0012 % process, and mtspectrumpt for a point process consisting of times. There
    0013 % are also routines for calculating hybrid quantities involving one continuous
    0014 % and one point process. These are suffixed in a similar manner. For
    0015 % example, coherencycpb calculates the coherency between a binned point process
    0016 % and a continuous process.
    0017 %
    0018 % Certain variables are used repeatedly in this library.
    0019 %
    0020 % DATA
    0021 % data in most cases can be univariate or multivariate, and either point process,
    0022 % or continuous.
    0023 %
    0024 %      Continuous data: Continuous data is assumed to be a matrix with
    0025 %                       dimensions samples x channels/trials.
    0026 %
    0027 %      Point Process: A single time series of spike times can be in the form of
    0028 %                     a column vector.
    0029 %                     Multichannel/trial spike time data is not amenable to this
    0030 %                     storage format, since there are generally different
    0031 %                     number of spikes in each channel/trial. Instead,
    0032 %                     multichannel/trial spike data is stored in a structure
    0033 %                     array. A structure is a matlab data object with various
    0034 %                     fields. These fields contain the elements
    0035 %                       e.g. The command data=struct('times',[]); creates an empty
    0036 %                            structure with field 'times'. Similarly, the command
    0037 %                            data=struct('times',[1 2 3]); creates the structure with
    0038 %                            the field 'times' containing integers 1, 2, and 3.
    0039 %
    0040 %                     We can also have a structure array (or an array of structures)
    0041 %                     defined for example, by
    0042 %                     data(1)=struct('times',rand(1,100)); and
    0043 %                     data(2)=struct('times',rand(1,200));
    0044 %                     This is a 2 dimensional structure array where the
    0045 %                     first field is a 100 dimensional random vector, and
    0046 %                     the second field is a 200 dimensional random vector.
    0047 %                     This format allows storage of multichannel point
    0048 %                     process times in a single variable data.
    0049 %
    0050 %                     The above holds for point processes stored as times.
    0051 %                     If instead, the point processes are binned, then one
    0052 %                     can use a matrix to represent them
    0053 %
    0054 %
    0055 %      Summary: data - array of continuous data with dimensions time x channels
    0056 %                      structural array of spike times with dimensions
    0057 %                               equal to the number of channels
    0058 %                      1d array of spike times as a column vector
    0059 %                      array of binned spike counts with dimensions time x channels
    0060 %
    0061 % PARAMETERS:
    0062 % These are various parameters used in the spectral calculations. Since
    0063 % these parameters are used by most routines in Chronux, they are stored in
    0064 % a single structure params. The fields of params are
    0065 %
    0066 % tapers : precalculated tapers from dpss or in the one of the following
    0067 %          forms:
    0068 %          (1) A numeric vector [TW K] where TW is the
    0069 %              time-bandwidth product and K is the number of
    0070 %              tapers to be used (less than or equal to
    0071 %              2TW-1).
    0072 %          (2) A numeric vector [W T p] where W is the
    0073 %              bandwidth, T is the duration of the data and p
    0074 %              is an integer such that 2TW-p tapers are used. In
    0075 %              this form there is no default i.e. to specify
    0076 %              the bandwidth, you have to specify T and p as
    0077 %              well. Note that the units of W and T have to be
    0078 %              consistent: if W is in Hz, T must be in seconds
    0079 %              and vice versa. Note that these units must also
    0080 %              be consistent with the units of params.Fs: W can
    0081 %              be in Hz if and only if params.Fs is in Hz.
    0082 %              The default is to use form 1 with TW=3 and K=5
    0083 %
    0084 %
    0085 % pad:   (padding factor for the FFT) - optional (can take values -1,0,1,2...).
    0086 %         -1 corresponds to no padding, 0 corresponds to padding
    0087 %         to the next highest power of 2 etc.
    0088 %              e.g. For N = 500, if PAD = -1, we do not pad; if PAD = 0, we pad the FFT
    0089 %                   to 512 points, if pad=1, we pad to 1024 points etc.
    0090 %                   Defaults to 0.
    0091 %
    0092 % Fs:sampling frequency.optional (default 1)
    0093 %
    0094 %
    0095 % fpass: frequencies in an fft calculation can range from 0 to Fs/2 where
    0096 %        Fs is the sampling frequency. Sometimes it may be useful to
    0097 %        compute fourier transforms (and resulting quantities like the
    0098 %        spectrum over a smaller range of frequencies). This is specified
    0099 %        by fpass, which can be in the form [fmin fmax] where fmin >=0 and
    0100 %        fmax<=Fs/2. optional (default [0 Fs/2])
    0101 %
    0102 % err=[errtype p] calculates theoretical error bars (confidence levels)
    0103 %                 when errtype=1 and jackknife error bars when errchk=2. In each case, the
    0104 %                 error is calculated at a p value specified by p. -
    0105 %                 optional (default 0)
    0106 %
    0107 % trialave: trialave controls whether or not to average over channels/trials for
    0108 %           multichannel/trial analyses. trialave=0 (default) implies no trial
    0109 %           averaging, trialave=1 implies that the quantity of interest is averaged
    0110 %           over channels/trials. optional (default 0)
    0111 %
    0112 % Other parameters are discussed in individual routines as and when they
    0113 % are used.