# 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.

**See also**: `concentration`

, `meanDirection`

, timefrequencybi.jl.

**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)
```

`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.

**See also**: `meanAmplitude`

, `meanDirection`

, timefrequencybi.jl.

**Examples**: see the examples of `meanAmplitude`

function.

`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

**See also**: `meanAmplitude`

, `concentration`

, timefrequencybi.jl.

**Examples**: see the examples of `meanAmplitude`

.