emd-0.2.0.0: Empirical Mode Decomposition and Hilbert-Huang Transform

Copyright(c) Justin Le 2019
LicenseBSD3
Maintainerjustin@jle.im
Stabilityexperimental
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell2010

Numeric.HHT

Contents

Description

Hilbert-Huang transform in pure Haskell.

The main data type is HHT, which can be generated using hht or hhtEmd. See Numeric.EMD for information on why this module uses "sized vectors", and how to convert unsized vectors to sized vectors.

Since: 0.1.2.0

Synopsis

Hilbert-Huang Transform

data HHT v n a Source #

A Hilbert-Huang Transform. An HHT v n a is a Hilbert-Huang transform of an n-item time series of items of type a represented using vector v.

Create using hht or hhtEmd.

Constructors

HHT 

Fields

Instances
(Eq a, Eq (v a)) => Eq (HHT v n a) Source # 
Instance details

Defined in Numeric.HHT

Methods

(==) :: HHT v n a -> HHT v n a -> Bool #

(/=) :: HHT v n a -> HHT v n a -> Bool #

(Ord a, Ord (v a)) => Ord (HHT v n a) Source # 
Instance details

Defined in Numeric.HHT

Methods

compare :: HHT v n a -> HHT v n a -> Ordering #

(<) :: HHT v n a -> HHT v n a -> Bool #

(<=) :: HHT v n a -> HHT v n a -> Bool #

(>) :: HHT v n a -> HHT v n a -> Bool #

(>=) :: HHT v n a -> HHT v n a -> Bool #

max :: HHT v n a -> HHT v n a -> HHT v n a #

min :: HHT v n a -> HHT v n a -> HHT v n a #

(Show a, Show (v a)) => Show (HHT v n a) Source # 
Instance details

Defined in Numeric.HHT

Methods

showsPrec :: Int -> HHT v n a -> ShowS #

show :: HHT v n a -> String #

showList :: [HHT v n a] -> ShowS #

Generic (HHT v n a) Source # 
Instance details

Defined in Numeric.HHT

Associated Types

type Rep (HHT v n a) :: Type -> Type #

Methods

from :: HHT v n a -> Rep (HHT v n a) x #

to :: Rep (HHT v n a) x -> HHT v n a #

(Vector v a, KnownNat n, Binary (v a), Binary a) => Binary (HHT v n a) Source #

Since: 0.1.3.0

Instance details

Defined in Numeric.HHT

Methods

put :: HHT v n a -> Put #

get :: Get (HHT v n a) #

putList :: [HHT v n a] -> Put #

(NFData (v a), NFData a) => NFData (HHT v n a) Source #

Since: 0.1.5.0

Instance details

Defined in Numeric.HHT

Methods

rnf :: HHT v n a -> () #

type Rep (HHT v n a) Source # 
Instance details

Defined in Numeric.HHT

type Rep (HHT v n a) = D1 (MetaData "HHT" "Numeric.HHT" "emd-0.2.0.0-inplace" False) (C1 (MetaCons "HHT" PrefixI True) (S1 (MetaSel (Just "hhtLines") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [HHTLine v n a]) :*: S1 (MetaSel (Just "hhtResidual") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Vector v (n + 1) a))))

data HHTLine v n a Source #

A Hilbert Trasnform of a given IMF, given as a "skeleton line".

Constructors

HHTLine 

Fields

  • hlMags :: !(Vector v (n + 1) a)

    IMF HHT Magnitude as a time series.

    It may be useful to "zip" this vector with hlFreqs. To do this, use a function like init or tail to make these two vectors contain the same length, or 'weaken'/'shift' to make indices in hlFreqs usable as indices in hlMags.

    Prior to v0.1.9.0, this was a length-n vector, just like hlFreqs. To get the same behavior, use init on this new field's value.

  • hlFreqs :: !(Vector v n a)

    IMF HHT instantaneous frequency as a time series (between 0 and 1).

    In reality, these frequencies are the frequencies "in between" each step in hlMags.

  • hlInitPhase :: !a

    Initial phase of skeleton line (between -pi and pi)

    Since: 0.1.9.0

Instances
(Eq a, Eq (v a)) => Eq (HHTLine v n a) Source # 
Instance details

Defined in Numeric.HHT

Methods

(==) :: HHTLine v n a -> HHTLine v n a -> Bool #

(/=) :: HHTLine v n a -> HHTLine v n a -> Bool #

(Ord a, Ord (v a)) => Ord (HHTLine v n a) Source # 
Instance details

Defined in Numeric.HHT

Methods

compare :: HHTLine v n a -> HHTLine v n a -> Ordering #

(<) :: HHTLine v n a -> HHTLine v n a -> Bool #

(<=) :: HHTLine v n a -> HHTLine v n a -> Bool #

(>) :: HHTLine v n a -> HHTLine v n a -> Bool #

(>=) :: HHTLine v n a -> HHTLine v n a -> Bool #

max :: HHTLine v n a -> HHTLine v n a -> HHTLine v n a #

min :: HHTLine v n a -> HHTLine v n a -> HHTLine v n a #

(Show a, Show (v a)) => Show (HHTLine v n a) Source # 
Instance details

Defined in Numeric.HHT

Methods

showsPrec :: Int -> HHTLine v n a -> ShowS #

show :: HHTLine v n a -> String #

showList :: [HHTLine v n a] -> ShowS #

Generic (HHTLine v n a) Source # 
Instance details

Defined in Numeric.HHT

Associated Types

type Rep (HHTLine v n a) :: Type -> Type #

Methods

from :: HHTLine v n a -> Rep (HHTLine v n a) x #

to :: Rep (HHTLine v n a) x -> HHTLine v n a #

(Vector v a, KnownNat n, Binary (v a), Binary a) => Binary (HHTLine v n a) Source #

Since: 0.1.3.0

Instance details

Defined in Numeric.HHT

Methods

put :: HHTLine v n a -> Put #

get :: Get (HHTLine v n a) #

putList :: [HHTLine v n a] -> Put #

(NFData (v a), NFData a) => NFData (HHTLine v n a) Source #

Since: 0.1.5.0

Instance details

Defined in Numeric.HHT

Methods

rnf :: HHTLine v n a -> () #

type Rep (HHTLine v n a) Source # 
Instance details

Defined in Numeric.HHT

type Rep (HHTLine v n a) = D1 (MetaData "HHTLine" "Numeric.HHT" "emd-0.2.0.0-inplace" False) (C1 (MetaCons "HHTLine" PrefixI True) (S1 (MetaSel (Just "hlMags") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Vector v (n + 1) a)) :*: (S1 (MetaSel (Just "hlFreqs") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (Vector v n a)) :*: S1 (MetaSel (Just "hlInitPhase") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 a))))

hhtEmd :: forall v n a. (Vector v a, Vector v (Complex a), KnownNat n, FFTWReal a) => EMD v (n + 1) a -> HHT v n a Source #

Compute the Hilbert-Huang transform from a given Empirical Mode Decomposition.

hht :: forall v n a. (Vector v a, Vector v (Complex a), KnownNat n, FFTWReal a) => EMDOpts v (n + 1) a -> Vector v (n + 1) a -> HHT v n a Source #

Directly compute the Hilbert-Huang transform of a given time series. Essentially is a composition of hhtEmd and emd. See hhtEmd for a more flexible version.

ihhtEmd :: (Vector v a, Floating a) => HHT v n a -> EMD v (n + 1) a Source #

Invert a Hilbert-Huang transform back to an Empirical Mode Decomposition

Since: 0.1.9.0

ihht :: (Vector v a, Floating a) => HHT v n a -> Vector v (n + 1) a Source #

Construct a time series correpsonding to its hilbert-huang transform.

Since: 0.1.9.0

Hilbert-Huang Spectrum

hhtSpectrum Source #

Arguments

:: (Vector v a, KnownNat n, Ord k, Num a) 
=> (a -> k)

binning function. takes rev/tick freq between 0 and 1.

-> HHT v n a 
-> Vector n (Map k a) 

Compute the full Hilbert-Huang Transform spectrum. At each timestep is a sparse map of frequency components and their respective magnitudes. Frequencies not in the map are considered to be zero.

Takes a "binning" function to allow you to specify how specific you want your frequencies to be.

See hhtSparseSpectrum for a sparser version, and hhtDenseSpectrum for a denser version.

hhtSparseSpectrum Source #

Arguments

:: (Vector v a, KnownNat n, Ord k, Num a) 
=> (a -> k)

binning function. takes rev/tick freq between 0 and 1.

-> HHT v n a 
-> Map (Finite n, k) a 

A sparser vesion of hhtSpectrum. Compute the full Hilbert-Huang Transform spectrum. Returns a sparse matrix representing the power at each time step (the Finite n) and frequency (the k).

Takes a "binning" function to allow you to specify how specific you want your frequencies to be.

Since: 0.1.4.0

hhtDenseSpectrum Source #

Arguments

:: (Vector v a, KnownNat n, KnownNat m, Num a) 
=> (a -> Finite m)

binning function. takes rev/tick freq between 0 and 1.

-> HHT v n a 
-> Vector n (Vector m a) 

A denser version of hhtSpectrum. Compute the full Hilbert-Huang Transform spectrum, returning a dense matrix (as a vector of vectors) representing the power at each time step and each frequency.

Takes a "binning" function that maps a frequency to one of m discrete slots, for accumulation in the dense matrix.

Since: 0.1.4.0

Properties of spectrum

meanMarginal Source #

Arguments

:: (Vector v a, KnownNat n, Ord k, Fractional a) 
=> (a -> k)

binning function. takes rev/tick freq between 0 and 1.

-> HHT v n a 
-> Map k a 

Compute the mean marginal spectrum given a Hilbert-Huang Transform. It is similar to a Fourier Transform; it provides the "total power" over the entire time series for each frequency component, averaged over the length of the time series.

A binning function is accepted to allow you to specify how specific you want your frequencies to be.

Since: 0.1.8.0

marginal Source #

Arguments

:: (Vector v a, KnownNat n, Ord k, Num a) 
=> (a -> k)

binning function. takes rev/tick freq between 0 and 1.

-> HHT v n a 
-> Map k a 

Compute the marginal spectrum given a Hilbert-Huang Transform. It provides the "total power" over the entire time series for each frequency component. See meanMarginal for a version that averages over the length of the time series, making it more close in nature to the purpose of a Fourier Transform.

A binning function is accepted to allow you to specify how specific you want your frequencies to be.

instantaneousEnergy :: forall v n a. (Vector v a, KnownNat n, Num a) => HHT v n a -> Vector v n a Source #

Compute the instantaneous energy of the time series at every step via the Hilbert-Huang Transform.

degreeOfStationarity Source #

Arguments

:: (Vector v a, KnownNat n, Ord k, Fractional a, Eq a) 
=> (a -> k)

binning function. takes rev/tick freq between 0 and 1.

-> HHT v n a 
-> Map k a 

Degree of stationarity, as a function of frequency.

expectedFreq :: forall v n a. (Vector v a, KnownNat n, Fractional a) => HHT v n a -> Vector v n a Source #

Returns the "expected value" of frequency at each time step, calculated as a weighted average of all contributions at every frequency at that time step.

Since: 0.1.4.0

dominantFreq :: forall v n a. (Vector v a, KnownNat n, Ord a) => HHT v n a -> Vector v n a Source #

Returns the dominant frequency (frequency with largest magnitude contribution) at each time step.

Since: 0.1.4.0

foldFreq Source #

Arguments

:: (Vector v a, Vector u c, KnownNat n, Monoid b) 
=> (a -> a -> b)

Combining function, taking frequency, then magnitude

-> (b -> c)

Projecting function

-> HHT v n a 
-> Vector u n c 

Fold and collapse a Hilbert-Huang transform along the frequency axis at each step in time along some monoid.

Since: 0.1.8.0

Options

data EMDOpts v n a Source #

Options for EMD composition.

Constructors

EO 

Fields

Instances
Generic (EMDOpts v n a) Source # 
Instance details

Defined in Numeric.EMD.Internal

Associated Types

type Rep (EMDOpts v n a) :: Type -> Type #

Methods

from :: EMDOpts v n a -> Rep (EMDOpts v n a) x #

to :: Rep (EMDOpts v n a) x -> EMDOpts v n a #

(Vector v a, Fractional a, Ord a) => Default (EMDOpts v n a) Source #

Since: 0.1.3.0

Instance details

Defined in Numeric.EMD

Methods

def :: EMDOpts v n a #

type Rep (EMDOpts v n a) Source # 
Instance details

Defined in Numeric.EMD.Internal

type Rep (EMDOpts v n a) = D1 (MetaData "EMDOpts" "Numeric.EMD.Internal" "emd-0.2.0.0-inplace" False) (C1 (MetaCons "EO" PrefixI True) (S1 (MetaSel (Just "eoSifter") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Sifter v n a)) :*: (S1 (MetaSel (Just "eoSplineEnd") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (SplineEnd a)) :*: S1 (MetaSel (Just "eoBoundaryHandler") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe BoundaryHandler)))))

defaultEO :: (Vector v a, Fractional a, Ord a) => EMDOpts v n a Source #

Default EMDOpts

Note: If you immediately use this and set eoSifter, then v will be ambiguous. Explicitly set v with type applications to appease GHC

defaultEO @(Data.Vector.Vector)
   { eoSifter = scTimes 100
   }

data BoundaryHandler Source #

Boundary conditions for splines.

Constructors

BHClamp

Clamp envelope at end points (Matlab implementation)

BHSymmetric

Extend boundaries symmetrically

Instances
Eq BoundaryHandler Source # 
Instance details

Defined in Numeric.EMD.Internal

Ord BoundaryHandler Source # 
Instance details

Defined in Numeric.EMD.Internal

Show BoundaryHandler Source # 
Instance details

Defined in Numeric.EMD.Internal

Generic BoundaryHandler Source # 
Instance details

Defined in Numeric.EMD.Internal

Associated Types

type Rep BoundaryHandler :: Type -> Type #

Binary BoundaryHandler Source #

Since: 0.1.3.0

Instance details

Defined in Numeric.EMD.Internal

type Rep BoundaryHandler Source # 
Instance details

Defined in Numeric.EMD.Internal

type Rep BoundaryHandler = D1 (MetaData "BoundaryHandler" "Numeric.EMD.Internal" "emd-0.2.0.0-inplace" False) (C1 (MetaCons "BHClamp" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "BHSymmetric" PrefixI False) (U1 :: Type -> Type))

defaultSifter :: (Vector v a, Fractional a, Ord a) => Sifter v n a Source #

Default Sifter

defaultSifter = siftStdDev 0.3 siftOr siftTimes 50

R package uses siftTimes 20, Matlab uses no limit

data SplineEnd a Source #

End condition for spline

Constructors

SENotAKnot

"Not-a-knot" condition: third derivatives are continuous at endpoints. Default for matlab spline.

SENatural

"Natural" condition: curve becomes a straight line at endpoints.

SEClamped a a

"Clamped" condition: Slope of curves at endpoints are explicitly given.

Since: 0.1.2.0

Instances
Eq a => Eq (SplineEnd a) Source # 
Instance details

Defined in Numeric.EMD.Internal.Spline

Methods

(==) :: SplineEnd a -> SplineEnd a -> Bool #

(/=) :: SplineEnd a -> SplineEnd a -> Bool #

Ord a => Ord (SplineEnd a) Source # 
Instance details

Defined in Numeric.EMD.Internal.Spline

Show a => Show (SplineEnd a) Source # 
Instance details

Defined in Numeric.EMD.Internal.Spline

Generic (SplineEnd a) Source # 
Instance details

Defined in Numeric.EMD.Internal.Spline

Associated Types

type Rep (SplineEnd a) :: Type -> Type #

Methods

from :: SplineEnd a -> Rep (SplineEnd a) x #

to :: Rep (SplineEnd a) x -> SplineEnd a #

Binary a => Binary (SplineEnd a) Source #

Since: 0.1.3.0

Instance details

Defined in Numeric.EMD.Internal.Spline

Methods

put :: SplineEnd a -> Put #

get :: Get (SplineEnd a) #

putList :: [SplineEnd a] -> Put #

type Rep (SplineEnd a) Source # 
Instance details

Defined in Numeric.EMD.Internal.Spline

type Rep (SplineEnd a) = D1 (MetaData "SplineEnd" "Numeric.EMD.Internal.Spline" "emd-0.2.0.0-inplace" False) (C1 (MetaCons "SENotAKnot" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "SENatural" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "SEClamped" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 a) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 a))))

Hilbert transforms (internal usage)

hilbert :: forall v n a. (Vector v a, Vector v (Complex a), KnownNat n, FFTWReal a) => Vector v n a -> Vector v n (Complex a) Source #

Real part is original series and imaginary part is hilbert transformed series. Creates a "helical" form of the original series that rotates along the complex plane.

Note that since 0.1.7.0, this uses the same algorithm as the matlab implementation https://www.mathworks.com/help/signal/ref/hilbert.html

hilbertIm :: forall v n a. (Vector v a, Vector v (Complex a), KnownNat n, FFTWReal a) => Vector v n a -> Vector v n a Source #

Hilbert transformed series. Essentially the same series, but phase-shifted 90 degrees. Is so-named because it is the "imaginary part" of the proper hilbert transform, hilbert.

Note that since 0.1.7.0, this uses the same algorithm as the matlab implementation https://www.mathworks.com/help/signal/ref/hilbert.html

hilbertPolar :: forall v n a. (Vector v a, Vector v (Complex a), KnownNat n, FFTWReal a) => Vector v (n + 1) a -> (Vector v (n + 1) a, Vector v (n + 1) a) Source #

The polar form of hilbert: returns the magnitude and phase of the discrete hilbert transform of a series.

The computation of magnitude is unique, but computing phase gives us some ambiguity. The interpretation of the hilbert transform for instantaneous frequency is that the original series "spirals" around the complex plane as time progresses, like a helix. So, we impose a constraint on the phase to uniquely determine it: \(\phi_{t+1}\) is the minimal valid phase such that \(\phi_{t+1} \geq \phi_{t}\). This enforces the phase to be monotonically increasing at the slowest possible detectable rate.

Since: 0.1.6.0

hilbertMagFreq :: forall v n a. (Vector v a, Vector v (Complex a), KnownNat n, FFTWReal a) => Vector v (n + 1) a -> (Vector v (n + 1) a, (Vector v n a, a)) Source #

Given a time series, return a time series of the magnitude of the hilbert transform and the frequency of the hilbert transform, in units of revolutions per tick. Is only expected to taken in proper/legal IMFs.

The frequency will always be between 0 and 1, since we can't determine anything faster given the discretization, and we exclude negative values as physically unmeaningful for an IMF.