timefrequency.jl

This unit implements time-frequency representations based on analytic signal estimations. It uses the filters.jl unit for filtering the signals in a filter bank and the hilbert.jl unit for computing the Hilbert transform.

The main object in the time-frequency domain is the TFAnalyticSignal, from which the TFAmplitude and TFPhase objects are derived. Taken together these three objects are referred to as TFobjects and vectors of them are a TFobjectsVector type.

Object	Vector type	Constructors from data
TFAnalyticSignal	TFAnalyticSignalVector	`TFanalyticsignal`
TFAmplitude	TFAmplitudeVector	`TFamplitude`
TFPhase	TFPhaseVector	`TFphase`

TFAnalyticSignal

Categories: data objects, TFobjects.

An analytic signal object has the following structure:

struct TFAnalyticSignal
    y          :: Matrix{T} where T<:Complex
    bandwidth  :: IntOrReal
    flabels    :: Vector{S} where S<:Real
    nonlinear  :: Bool
    fsmoothing :: Smoother
    tsmoothing :: Smoother
end

Fields:

y: a complex matrix holding the analytic signal in the time-frequency domain, with frequency band-pass regions (in Hz) in rows and time (samples) in columns.

bandwidth: the bandwidth (in Hz) of the filter bank band-pass regions. See constructor TFanalyticsignal for details. It can be an integer or a real number.

flabels: a vector holding all center frequencies (in Hz) of the filter bank band-pass regions. Those are the frequency labels for the rows of y.

non-linear: a flag indicating whether the analytic signal has been normalized so as to have amplitude1.0 at all points. Such normalization allows non-linear univariate and bivariate estimations (see timefrequencyuni.jl and timefrequencybi.jl).

fsmoothing: a flag of the Smoother type indicating whether the analytic signal has been smoothed across adjacent frequency band-pass regions. If no frequency smoothing has been applied, it is equal to noSmoother, which is the default in all constructors.

tsmoothing: a flag of the Smoother type indicating whether the analytic signal has been smoothed across adjacent samples (time). If no time smoothing has been applied, it is equal to noSmoother, which is the default in all constructors.

Note: In Julia the fields are accessed by the usual dot notation, e.g., you may verify that for TFAnalyticSignal object Y,

length(Y.flabels) == dim(Y.z, 1)

A vector of TFAnalyticSignal objects is of type TFAnalyticSignalVector.

Methods for TFAnalyticSignal and TFAnalyticSignalVector objects

method	TFAnalyticSignal	TFAnalyticSignalVector
`amplitude`	✔	✔
`phase`	✔	✔
`polar`	✔
`extract`	✔	✔
`mean`	✔	✔
`smooth`	✔	✔
`sameParams`		✔
`isLinear`		✔
`isNonLinear`		✔
`meanAmplitude`		✔
`concentration`		✔
`comodulation`		✔
`meanDirection`		✔
`coherence`		✔

Generic Constructors:

In order to construct a TFAnalyticSignal object from univariate data, FourierAnalysis provides two TFanalyticsignal constuctors, which is what you will use in practice most of the time.

Manual constructors are also possible, for which you have to provide appropriate arguments. The default manual constructor of TFAnalyticSignal objects is

TFAnalyticSignal(y, bandwidth, flabels, nonlinear, fsmoothing, tsmoothing).

No other generic constructor is provided for this object.

TFAmplitude

Categories: data objects, TFobjects.

An amplitude object has the following structure:

struct TFAmplitude
    y          :: Matrix{T} where T<:Real
    bandwidth  :: IntOrReal
    flabels    :: Vector{S} where S<:Real
    fsmoothing :: Smoother
    tsmoothing :: Smoother
    func       :: Function
end

Fields:

y: a real matrix holding the amplitude (modulus) of an analytic signal in the time-frequency domain, often referred to as the envelope, with frequency band-pass regions (in Hz) in rows and time (samples) in columns.

bandwidth: the bandwidth (in Hz) of the filter bank band-pass regions. See constructor TFanalyticsignal for details. It can be an integer or a real number.

flabels: a vector holding all center frequencies (in Hz) of the filter bank band-pass regions. Those are the frequency labels for the rows of y.

fsmoothing: a flag of the Smoother type indicating whether the amplitude has been smoothed across adjacent frequency band-pass regions. If no frequency smoothing has been applied, it is equal to noSmoother, which is the default in all constructors.

tsmoothing: a flag of the Smoother type indicating whether the amplitude has been smoothed across adjacent samples (time). If no time smoothing has been applied, it is equal to noSmoother, which is the default in all constructors.

Note: Smoothing flags in this object indicate that the amplitude has been smoothed, whereas in the TFAnalyticSignal object indicate that the analytic signal has been smoothed. Note that it is not equivalent to obtain amplitude from smoothed analytic signal (e.g., using the amplitude function) or to smooth the amplitude of analytic signal, e.g., using the TFamplitude constructor.

func: a name of a function that has been applied element-wise to the matrix .y holding the amplitude. All constructors from data by default use the identity (do nothing) function.

A vector of TFAmplitude objects is of type TFAmplitudeVector.

Methods for TFAmplitude and TFAmplitudeVector objects

method	TFAmplitude	TFAmplitudeVector
`extract`	✔	✔
`mean`	✔	✔
`smooth`	✔	✔
`sameParams`		✔
`isLinear`		✔
`isNonLinear`		✔
`meanAmplitude`		✔
`comodulation`		✔

Generic Constructors:

In order to construct a TFAmplitude object from univariate data, FourierAnalysis provides four TFamplitude constuctors, which is what you will use in practice most of the time.

Manual constructors are also possible, for which you have to provide appropriate arguments. The default manual constructor of TFAmplitude objects is

TFAmplitude(y, bandwidth, flabels, fsmoothing, tsmoothing, func).

Other generic constructors are also provided:

TFAmplitude(y, bandwidth, flabels, fsmoothing, tsmoothing)

enables construction giving only y, bandwidth, flabels, fsmoothing and tsmoothing. func is set automatically to identity;

TFAmplitude(y, bandwidth, flabels)

acts like the constructor above, but sets by default also both fsmoothing and tsmoothing to noSmoother.

TFPhase

Categories: data objects, TFobjects.

A phase object has the following structure:

struct TFPhase
    y          :: Matrix{T} where T<:Real
    bandwidth  :: IntOrReal
    flabels    :: Vector{S} where S<:Real
    nonlinear  :: Bool
    fsmoothing :: Smoother
    tsmoothing :: Smoother
    unwrapped  :: Bool
    func       :: Function
end

Fields:

y: a real matrix holding the phase (argument) of an analytic signal in the time-frequency domain, with frequency band-pass regions (in Hz) in rows and time (samples) in columns. By default the phase is represented in [−π, π].

bandwidth: the bandwidth (in Hz) of the filter bank band-pass regions. See constructor TFanalyticsignal for details. It can be an integer or a real number.

flabels: a vector holding all center frequencies (in Hz) of the filter bank band-pass regions. Those are the frequency labels for the rows of y.

non-linear: a flag indicating whether the phase has been estimated from analytic signal normalized so as to have amplitude1.0 at all points. Such normalization allows non-linear univariate and bivariate estimations (see timefrequencyuni.jl and timefrequencybi.jl).

fsmoothing: a flag of Smoother indicating whether the phase has been smoothed across adjacent frequency band-pass regions. If no frequency smoothing has been applied, it is equal to noSmoother, which is the default in all constructors.

tsmoothing: a flag of the Smoother type indicating whether the phase has been smoothed across adjacent samples (time). If no time smoothing has been applied, it is equal to noSmoother, which is the default in all constructors.

Note: Smoothing raw phase estimates is unappropriate since the phase is a discontinous function, however it makes sense to smooth phase if the phase is unwrapped (see below).

Note: Smoothing flags in this object indicate that the (unwrapped) phase has been smoothed, whereas in the TFAnalyticSignal object indicate that the analytic signal has been smoothed. Note that it is not equivalent to obtain unwrapped phase from smoothed analytic signal (e.g., using the phase function) or to smooth the unwrapped phase of analytic signal, e.g., using the TFphase constructor.

unwrapped: a flag indicating if the phase has been unwrapped. The unwrapped phase is defined as the cumulative sum of the phase along the time dimension once the phase is represented in [0, 2π].

func: a name of a function that has been applied element-wise to the matrix .y holding the phase. All constructors from data by default use the identity (do nothing) function. Examples of possible functions:

func=x->x+π return the phase in [0, 2π],
func=x->x/π return the phase in [-1, 1],
func=sin return the sine of the phase.

A vector of TFPhase objects is of type TFPhaseVector.

Methods for TFPhase and TFPhaseVector objects

method	TFAmplitude	TFAmplitudeVector
`unwrapPhase`	✔	✔
`isUnwrapped`	✔	✔
`extract`	✔	✔
`mean`	✔	✔
`smooth`	✔	✔
`sameParams`		✔
`isLinear`		✔
`isNonLinear`		✔

Generic Constructors:

In order to construct a TFPhase object from univariate data, FourierAnalysis provides four TFphase constuctors, which is what you will use in practice most of the time.

Manual constructors are also possible, for which you have to provide appropriate arguments. The default manual constructor of TFPhase objects is

TFPhase(y, bandwidth, flabels, nonlinear,
        fsmoothing, tsmoothing, unwrapped, func).

Other generic constructors are also provided:

TFPhase(y, bandwidth, flabels, nonlinear, fsmoothing, tsmoothing)

enables construction giving only y, bandwidth, flabels, fsmoothing and tsmoothing. unwrapped is set to false and func is set to identity;

TFPhase(y, bandwidth, flabels)

acts like the constructor above, but sets by default also nonlinear to true and both fsmoothing and tsmoothing to noSmoother.

Constructors from data:

TFanalyticsignal
TFamplitude
TFphase

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

timefrequency.md

timefrequency.md

timefrequency.jl

TFAnalyticSignal

TFAmplitude

TFPhase

Files

timefrequency.md

Latest commit

History

timefrequency.md

File metadata and controls

timefrequency.jl

TFAnalyticSignal

TFAmplitude

TFPhase