timefrequencyuni.jl

This unit implements average time-frequency univariate measures based on unit timefrequency.jl and tools.jl.

These measures here implemented are weighted version of the measures described in Congedo (2018).

They can be obtained from TFAnalyticSignalVector objects or from raw data. Some of them can be obtained also from TFAmplitudeVector objects.

The measures are always estimated as the average across several analytic signals at all points in a time-frequency region or as the grand-average across several analytic signals of all the points in a time-frequency region. In the following an average process is denoted by angle brackets $\left<\cdot\right>$ and is used to indicate generically both averaging processes. Analytic signal in a time-frequency region, it does not matter if this is actually a single point, a vector or a matrix, is denoted such as

$z=x+\textit{i}y=re^{i\phi}$,

where $𝑖$ is the imaginary unit, $r=\mid z \mid$ is the amplitude (modulus) of $z$ and $\phi=\textrm{ArcTan}\space (x/y)$ the phase (argument) of $z$.

Also, $w$ denotes non-negative weights normalized so that their average is $1.0$. $w$ weights the different analytic signals on which the average is computed. Setting all weights equal to $1.0$ gives the unweighted version of all measures.

Some of the measures come in a linear and non-linear form. It is adopted throughout the convention of prepending 'phase' to the name of a measure to signal it is non-linear. The reason is that non-linear measures are not sensitive to amplitude, but only to phase. See Congedo (2018) for a throughout discussion.

The implemented measures are:

(weighted) mean amplitude

$(w)MAmp=w\left<\mid z \mid\right>\big /\left<w\right>=w\left<r\right>\big /\left<w\right>$.

(weighted) concentration

$(w)Con=\mid\left<wz\right>\mid\big /\left<w\right>=\mid\left<wre^{i\phi}\right>\mid\big /\left<w\right>$.

(weighted) phase concentration

$(w)PCon=\mid\left<we^{i\phi}\right>\mid\big /\left<w\right>$.

This is the non-linear version of the (weighted) concentration. In the litetrature it is also known as circular mean resultant length, inter-trial phase coherence, inter-trial phase clustering and phase coherence, among other names (Congedo, 2018).

(weighted) mean direction

$(w)MDir=\textrm{ArcTan}\space \big((\left<wy\right>/\left<wx\right>)\big/ \left<w\right>\big)$

(weighted) phase mean direction

$(w)PMDir=\textrm{ArcTan}\space \big((\left<wy/r\right>/\left<wx/r\right>)\big/ \left<w\right>\big)$

This is the non-linear version of the (weighted) phase mean direction

FourierAnalysis.meanAmplitude — Function

(1)
function meanAmplitude( 𝐀      :: TFAmplitudeVector,
                        frange :: fInterval,
                        trange :: tInterval;
                    mode   :: Function = extract,
                    func   :: Function = identity,
                    w      :: Vector   = [],
                    check  :: Bool     = true)

(2)
function meanAmplitude( 𝐙 :: TFAnalyticSignalVector,
                    < same arguments as method (1) >

(3)
function meanAmplitude( 𝐱      :: Vector{Vector{T}},
                        sr     :: Int,
                        wl     :: Int,
                        frange :: fInterval,
                        trange :: tInterval,
                     bandwidth :: IntOrReal    = 2;
                 mode          :: Function     = extract,
                 func          :: Function     = identity,
                 w             :: Vector       = [],
                 check         :: Bool         = true,
                 filtkind      :: FilterDesign = Butterworth(2),
                 fmin          :: IntOrReal    = bandwidth,
                 fmax          :: IntOrReal    = sr÷2,
                 fsmoothing    :: Smoother     = noSmoother,
                 tsmoothing    :: Smoother     = noSmoother,
                 planner       :: Planner      = getplanner,
                 ⏩           :: Bool         = true) where T<:Real

alias: mamp

(1)

Given a TFAmplitudeVector object, estimate the (weighted) mean amplitude measure across those objects. The time-frequency planes of all the objects in 𝐀 should be congruent.

arguments:

frange and trange define a time-frequency region on which the estimation is sought. frange is a fInterval type and delimits center frequencies of the filter bank. trange is a tInterval type and delimits time samples. To obtain the estimation in the whole time-frequency plane use the column (:) sign for both arguments.

optional keyword arguments

If mode=extract is passed (default), the measure will be computed for all points in the chosen time-frequency region. If mode=mean is passed, it will be computed on the mean of these points (grand-average). The extract and mean functions are generic methods of FourierAnalysis.

Note: with mode=mean the output of the function is always a real number, whereas with mode=extract the output may be a real number, a real row or column vector or a real matrix, depending on the shape of the chosen time-frequency region.

Passing a function with the func argument you can derive your own time-frequency measures.

w may be a vector of non-negative real weights associated to each input object. By default the unweighted version of the measure is computed.

If check is true (default), check that if the column sign is passed

as frange argument, all input objects have the same number of rows (center frequencies);
as trange argument, all input objects have the same number of columns (time samples).

If either check fails, print an error message and return Nothing. No other range checks are performed.

(2)

Given a TFAnalyticSignalVector object, compute the amplitude of all objects in 𝐙 and estimate the (weighted) mean amplitude measure across those objects as per method (1). In addition, since using this method all TFAnalyticSignal in 𝐙 must be linear, if check is true (default) and this is not the case, print an error and return Nothing. The checks on frange and trange performed by method (1) are also performed by this method.

(3)

Estimate the amplitude of all data vectors in 𝐱 calling the TFamplitude constructor and then estimate the (weighted) mean amplitude measure across the constructed amplitude objects as per method (1).

frange, trange, mode, func, w and check have the same meaning as in method (1). The other arguments are passed to the TFamplitude constructor, to which the reader is referred for their meaning.

Examples:

using FourierAnalysis

# generate 100 vectors of data
sr, t, bandwidth=128, 512, 2
h=taper(harris4, t)
𝐱=[sinusoidal(2, 10, sr, t, 0).*h.y+randn(t) for i=1:100]

𝐘=TFanalyticsignal(𝐱, sr, t, bandwidth; fmax=32)
𝐀=TFamplitude(𝐘)

# mean amplitude in a TF region from a TFAnalyticSignalVector object
MAmp=meanAmplitude(𝐘, (4, 16), :)
heatmap(MAmp; c=:fire) # y axis labels are not correct

# mean amplitude in a TF region from a TFAmplitudeVector object
MAmp=meanAmplitude(𝐀, (4, 16), :)

# mean amplitude in a TF region directly from data
MAmp=meanAmplitude(𝐱, sr, t, (4, 16), :, bandwidth)

# NB: in the above, the analytic signal objects must all
# be linear, since meanAmplitude is computed from amplitude
# and the amplitude of non-linear analytic signal is uniformy equal to 1.

# All these computations can be obtained averaging in a TF region, e.g.,
MAmp=meanAmplitude(𝐘, (4, 16), :; mode=mean) # output a real number

# and can be obtained on smoothed Amplitude, e.g.,
MAmp=meanAmplitude(𝐱, sr, t, (4, 16), :;
                   fsmoothing=blackmanSmoother,
                   tsmoothing=blackmanSmoother)
# or, equivalently, and using the alias `mamp`,
MAmp=mamp(smooth(blackmanSmoother, blackmanSmoother, 𝐀), (4, 16), :)

# A similar syntax is used for the other univariate measures, e.g.,
# concentration averaging in a TF region from a TFAnalyticSignalVector object
ConM=concentration(𝐘, (4, 16), (128, 384); mode=mean)

# concentration in a TF region directly from data (using the alias `con`)
ConE=con(𝐱, sr, t, (4, 16), (128, 384), bandwidth; mode=extract)
heatmap(Con; c=:fire) # y axis labels are not correct

NB: ConM is not at all equivalent to mean(ConE) !

# mean direction averaging in a TF region directly from data
MDir=meanDirection(𝐱, sr, t, (4, 16), :, bandwidth; mode=mean)

# mean direction in a TF region from a TFAnalyticSignalVector object
MDir=meanDirection(𝐘, (4, 16), :)

# and for the non-linear counterpart:
# phase concentration in a TF region directly from data
Con=concentration(𝐱, sr, t, (8, 12), :; nonlinear=true)

# phase concentration at a single TF point
Con=concentration(𝐱, sr, t, 10, 256; nonlinear=true)

# phase mean direction averaging in a TF region directly from data
# and using the alias `mdir`
MDir=mdir(𝐱, sr, t, (8, 12), :; mode=mean, nonlinear=true)

# If you try to compute a non-linear measure from a linear
# AnalyticSignal object you will get en error (see the REPL), e.g.,
Con=con(𝐘, (8, 12), (1, 512); mode=mean, nonlinear=true)

# In order to compute non-linear measures from analytic signal objects
# first we need to compute non-linear analytic signal objects:
𝐘=TFanalyticsignal(𝐱, sr, t, bandwidth; fmax=32, nonlinear=true)

# then, we can obtain for example the phase concentration
Con=con(𝐘, (8, 12), :; mode=mean, nonlinear=true)

# and the phase mean direction
MDir=meanDirection(𝐘, (8, 12), :; nonlinear=true)

source

FourierAnalysis.concentration — Function

(1)
function concentration( 𝐙       :: TFAnalyticSignalVector,
                        frange  :: fInterval,
                        trange  :: tInterval;
                    nonlinear :: Bool     = false,
                    mode      :: Function = extract,
                    func      :: Function = identity,
                    w         :: Vector   = [],
                    check     :: Bool     = true)

(2)
function concentration( 𝐱      :: Vector{Vector{T}},
                        sr     :: Int,
                        wl     :: Int,
                        frange :: fInterval,
                        trange :: tInterval,
                     bandwidth :: IntOrReal    = 2;
                 nonlinear  :: Bool         = false,
                 mode       :: Function     = extract,
                 func       :: Function     = identity,
                 w          :: Vector       = [],
                 check         :: Bool      = true,
                 filtkind   :: FilterDesign = Butterworth(2),
                 fmin       :: IntOrReal    = bandwidth,
                 fmax       :: IntOrReal    = sr÷2,
                 fsmoothing :: Smoother     = noSmoother,
                 tsmoothing :: Smoother     = noSmoother,
                 planner    :: Planner      = getplanner,
                 ⏩        :: Bool         = true) where T<:Real

alias: con

If optional keyword parameter nonlinear is false (default), estimate the (weighted) concentration measure, otherwise estimate the (weighted) phase concentration measure.

(1) The desired measure is obtained averaging across the TFAnalyticSignal objects in 𝐙. Since this method uses pre-computed analytic signal objects, their .nonlinear field must agree with the nonlinear argument passed to this function.

frange, trange, w, mode and func have the same meaning as in the meanAmplitude function, however keep in mind that the two possible mode functions, i.e., extract and mean, in this function operate on complex numbers.

The checks performed in the meanAmplitude function are performed here too. In addition, if check is true, also check that

if nonlinear is true, all objects in 𝐙 are nonlinear;
if nonlinear is false, all objects in 𝐙 are linear.

If either check fails, print an error message and return Nothing.

(2) Estimate the analytic signal of all data vectors in 𝐱 calling the TFanalyticsignal constructor and then use method (1) to obtained the desired measure.

frange, trange, mode, func, w and check have the same meaning as in the meanAmplitude function. The other arguments are passed to the TFanalyticsignal constructor, to which the reader is referred for understanding their action.

Examples: see the examples of meanAmplitude function.

source

FourierAnalysis.meanDirection — Function

(1)
function meanDirection( 𝐙         :: TFAnalyticSignalVector,
                        frange    :: fInterval,
                        trange    :: tInterval;
                    nonlinear :: Bool       = false,
                    mode      :: Function   = extract,
                    func      :: Function   = identity,
                    w         :: Vector     = [],
                    check     :: Bool       = true)

(2)
function meanDirection( 𝐱      :: Vector{Vector{T}},
                        sr     :: Int,
                        wl     :: Int,
                        frange :: fInterval,
                        trange :: tInterval,
                     bandwidth :: IntOrReal    = 2;
                 nonlinear     :: Bool         = false,
                 mode          :: Function     = extract,
                 func          :: Function     = identity,
                 w             :: Vector       = [],
                 check         :: Bool         = true,
                 filtkind      :: FilterDesign = Butterworth(2),
                 fmin          :: IntOrReal    = bandwidth,
                 fmax          :: IntOrReal    = sr÷2,
                 fsmoothing    :: Smoother     = noSmoother,
                 tsmoothing    :: Smoother     = noSmoother,
                 planner       :: Planner      = getplanner,
                 ⏩           :: Bool         = true) where T<:Real

This function features two methods that use exactly the same syntax as the two corresponding methods of the concentration function. All arguements have exactly the same meaning as therein. Only the output differs:

if optional keyword parameter nonlinear is false (default), estimate the (weighted) mean direction measure, otherwise estimate the (weighted) phase mean direction measure.

alias: mdir

Examples: see the examples of meanAmplitude.

source