-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Empirical Mode Decomposition and Hilbert-Huang Transform
--   
--   Please see the README on GitHub at
--   <a>https://github.com/mstksg/emd#readme</a>
@package emd
@version 0.1.2.0


-- | Internal splining functionality exported for testing purposes only.
--   This will likely go away in future versions, so please do not depend
--   on this!
module Numeric.EMD.Internal.Spline

-- | 1D Cubic spline
data Spline a

-- | End condition for spline
data SplineEnd a
SENotAKnot :: SplineEnd a
SENatural :: SplineEnd a
SEClamped :: a -> a -> SplineEnd a

-- | Build a cubic spline based on control points using given end
--   conditions (not-a-knot, or natural)
--   
--   <a>https://en.wikipedia.org/wiki/Spline_interpolation</a>
makeSpline :: forall a. (Ord a, Fractional a) => SplineEnd a -> Map a a -> Maybe (Spline a)

-- | Sample a spline at a given point.
sampleSpline :: (Fractional a, Ord a) => Spline a -> a -> a
instance GHC.Show.Show a => GHC.Show.Show (Numeric.EMD.Internal.Spline.SplineCoef a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Numeric.EMD.Internal.Spline.SplineEnd a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Numeric.EMD.Internal.Spline.SplineEnd a)
instance GHC.Show.Show a => GHC.Show.Show (Numeric.EMD.Internal.Spline.SplineEnd a)


-- | Empirical Mode Decomposition in pure Haskell.
--   
--   Main interface is <a>emd</a>, with <a>defaultEO</a>. A tracing version
--   that outputs a log to stdout is also available, as <a>emdTrace</a>.
--   This can be used to help track down a specific IMF that might be
--   taking more time than desired.
--   
--   This package uses "sized vectors" as its main interface, to ensure:
--   
--   <ol>
--   <li>The resulting <a>EMD</a> contains IMFs that are all the same
--   length as the input vector</li>
--   <li>We provide a vector of size of at least one.</li>
--   </ol>
--   
--   There are many functions to convert unsized vectors to sized vectors
--   in <a>Data.Vector.Sized</a> and associated modules, including
--   <tt>toSized</tt> (for when you know the size at compile-time) and
--   <tt>withSized</tt> (for when you don't).
module Numeric.EMD

-- | EMD decomposition of a given time series with a given sifting stop
--   condition.
--   
--   Takes a sized vector to ensure that:
--   
--   <ol>
--   <li>The resulting <a>EMD</a> contains IMFs that are all the same
--   length as the input vector</li>
--   <li>We provide a vector of size of at least one.</li>
--   </ol>
emd :: (Vector v a, KnownNat n, Fractional a, Ord a) => EMDOpts a -> Vector v (n + 1) a -> EMD v (n + 1) a

-- | <a>emd</a>, but tracing results to stdout as IMFs are found. Useful
--   for debugging to see how long each step is taking.
emdTrace :: (Vector v a, KnownNat n, Fractional a, Ord a, MonadIO m) => EMDOpts a -> Vector v (n + 1) a -> m (EMD v (n + 1) a)

-- | <a>emd</a> with a callback for each found IMF.
emd' :: (Vector v a, KnownNat n, Fractional a, Ord a, Applicative m) => (SiftResult v (n + 1) a -> m r) -> EMDOpts a -> Vector v (n + 1) a -> m (EMD v (n + 1) a)

-- | An <tt><a>EMD</a> v n a</tt> is an Empirical Mode Decomposition of a
--   time series with <tt>n</tt> items of type <tt>a</tt> stored in a
--   vector <tt>v</tt>.
data EMD v n a
EMD :: ![Vector v n a] -> !(Vector v n a) -> EMD v n a
[emdIMFs] :: EMD v n a -> ![Vector v n a]
[emdResidual] :: EMD v n a -> !(Vector v n a)

-- | Options for EMD composition.
data EMDOpts a
EO :: SiftCondition a -> SplineEnd a -> Maybe BoundaryHandler -> EMDOpts a

-- | stop condition for sifting
[eoSiftCondition] :: EMDOpts a -> SiftCondition a

-- | end conditions for envelope splines
[eoSplineEnd] :: EMDOpts a -> SplineEnd a

-- | process for handling boundary
[eoBoundaryHandler] :: EMDOpts a -> Maybe BoundaryHandler

-- | Default <a>EMDOpts</a>
defaultEO :: Fractional a => EMDOpts a
data BoundaryHandler

-- | Clamp envelope at end points (Matlab implementation)
BHClamp :: BoundaryHandler

-- | Extend boundaries symmetrically
BHSymmetric :: BoundaryHandler

-- | Stop conditions for sifting process
data SiftCondition a

-- | Stop using standard SD method
SCStdDev :: !a -> SiftCondition a

-- | Stop after a fixed number of sifting iterations
SCTimes :: !Int -> SiftCondition a

-- | One or the other
SCOr :: (SiftCondition a) -> (SiftCondition a) -> SiftCondition a

-- | Stop when both conditions are met
SCAnd :: (SiftCondition a) -> (SiftCondition a) -> SiftCondition a

-- | Default <a>SiftCondition</a>
defaultSC :: Fractional a => SiftCondition a

-- | End condition for spline
data SplineEnd a
SENotAKnot :: SplineEnd a
SENatural :: SplineEnd a
SEClamped :: a -> a -> SplineEnd a

-- | Iterated sifting process, used to produce either an IMF or a residual.
sift :: (Vector v a, KnownNat n, Fractional a, Ord a) => EMDOpts a -> Vector v (n + 1) a -> SiftResult v (n + 1) a

-- | The result of a sifting operation. Each sift either yields a residual,
--   or a new IMF.
data SiftResult v n a
SRResidual :: !(Vector v n a) -> SiftResult v n a

-- | number of sifting iterations
SRIMF :: !(Vector v n a) -> !Int -> SiftResult v n a

-- | Returns cubic splines of local minimums and maximums. Returns
--   <a>Nothing</a> if there are not enough local minimum or maximums to
--   create the splines.
envelopes :: (Vector v a, KnownNat n, Fractional a, Ord a) => SplineEnd a -> Maybe BoundaryHandler -> Vector v (n + 1) a -> Maybe (Vector v (n + 1) a, Vector v (n + 1) a)
instance GHC.Show.Show (v a) => GHC.Show.Show (Numeric.EMD.EMD v n a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Numeric.EMD.EMDOpts a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Numeric.EMD.EMDOpts a)
instance GHC.Show.Show a => GHC.Show.Show (Numeric.EMD.EMDOpts a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Numeric.EMD.SiftCondition a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Numeric.EMD.SiftCondition a)
instance GHC.Show.Show a => GHC.Show.Show (Numeric.EMD.SiftCondition a)
instance GHC.Classes.Ord Numeric.EMD.BoundaryHandler
instance GHC.Classes.Eq Numeric.EMD.BoundaryHandler
instance GHC.Show.Show Numeric.EMD.BoundaryHandler


-- | Hilbert-Huang transform in pure Haskell.
--   
--   The main data type is <a>HHT</a>, which can be generated using
--   <a>hht</a> or <a>hhtEmd</a>. See <a>Numeric.EMD</a> for information on
--   why this module uses "sized vectors", and how to convert unsized
--   vectors to sized vectors.
module Numeric.HHT

-- | Compute the Hilbert-Huang transform from a given Empirical Mode
--   Decomposition.
hhtEmd :: forall v n a. (Vector v a, KnownNat n, RealFloat a) => EMD v (n + 1) a -> HHT v n a

-- | Directly compute the Hilbert-Huang transform of a given time series.
--   Essentially is a composition of <a>hhtEmd</a> and <a>emd</a>. See
--   <a>hhtEmd</a> for a more flexible version.
hht :: forall v n a. (Vector v a, KnownNat n, RealFloat a) => EMDOpts a -> Vector v (n + 1) a -> HHT v n 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.
hhtSpectrum :: forall n a k. (KnownNat n, Ord k, Num a) => (a -> k) -> HHT Vector n a -> Vector n (Map k a)

-- | Compute the marginal spectrum given a Hilbert-Huang Transform. A
--   binning function is accepted to allow you to specify how specific you
--   want your frequencies to be.
marginal :: forall v n a k. (Vector v a, KnownNat n, Ord k, Num a) => (a -> k) -> HHT v n a -> Map k a

-- | Compute the instantaneous energy of the time series at every step via
--   the Hilbert-Huang Transform.
instantaneousEnergy :: forall v n a. (Vector v a, KnownNat n, Num a) => HHT v n a -> Vector v n a

-- | Degree of stationarity, as a function of frequency.
degreeOfStationarity :: forall v n a k. (Vector v a, KnownNat n, Ord k, Fractional a) => (a -> k) -> HHT v n a -> Map k a

-- | A Hilbert-Huang Transform. An <tt><a>HHT</a> v n a</tt> is a
--   Hilbert-Huang transform of an <tt>n</tt>-item time series of items of
--   type <tt>a</tt> represented using vector <tt>v</tt>.
--   
--   Create using <a>hht</a> or <a>hhtEmd</a>.
newtype HHT v n a
HHT :: [HHTLine v n a] -> HHT v n a
[hhtLines] :: HHT v n a -> [HHTLine v n a]

-- | A Hilbert Trasnform of a given IMF, given as a "skeleton line".
data HHTLine v n a
HHTLine :: !(Vector v n a) -> !(Vector v n a) -> HHTLine v n a

-- | IMF HHT Magnitude as a time series
[hlMags] :: HHTLine v n a -> !(Vector v n a)

-- | IMF HHT instantaneous frequency as a time series (between 0 and 1)
[hlFreqs] :: HHTLine v n a -> !(Vector v n a)

-- | Options for EMD composition.
data EMDOpts a
EO :: SiftCondition a -> SplineEnd a -> Maybe BoundaryHandler -> EMDOpts a

-- | stop condition for sifting
[eoSiftCondition] :: EMDOpts a -> SiftCondition a

-- | end conditions for envelope splines
[eoSplineEnd] :: EMDOpts a -> SplineEnd a

-- | process for handling boundary
[eoBoundaryHandler] :: EMDOpts a -> Maybe BoundaryHandler

-- | Default <a>EMDOpts</a>
defaultEO :: Fractional a => EMDOpts a
data BoundaryHandler

-- | Clamp envelope at end points (Matlab implementation)
BHClamp :: BoundaryHandler

-- | Extend boundaries symmetrically
BHSymmetric :: BoundaryHandler

-- | Stop conditions for sifting process
data SiftCondition a

-- | Stop using standard SD method
SCStdDev :: !a -> SiftCondition a

-- | Stop after a fixed number of sifting iterations
SCTimes :: !Int -> SiftCondition a

-- | One or the other
SCOr :: (SiftCondition a) -> (SiftCondition a) -> SiftCondition a

-- | Stop when both conditions are met
SCAnd :: (SiftCondition a) -> (SiftCondition a) -> SiftCondition a

-- | Default <a>SiftCondition</a>
defaultSC :: Fractional a => SiftCondition a

-- | End condition for spline
data SplineEnd a
SENotAKnot :: SplineEnd a
SENatural :: SplineEnd a
SEClamped :: a -> a -> SplineEnd a

-- | 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.
--   
--   Numerically assumes that the signal is zero everywhere outside of the
--   vector, instead of the periodic assumption taken by matlab's version.
hilbert :: forall v n a. (Vector v a, Vector v (Complex a), KnownNat n, Floating a) => Vector v n a -> Vector v n (Complex a)

-- | 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, <a>hilbert</a>.
--   
--   Numerically assumes that the signal is zero everywhere outside of the
--   vector, instead of the periodic assumption taken by matlab's version.
hilbertIm :: forall v n a. (Vector v a, KnownNat n, Floating a) => Vector v n a -> Vector v n a

-- | Given a time series, return a time series of the <i>magnitude</i> of
--   the hilbert transform and the <i>frequency</i> 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.
hilbertMagFreq :: forall v n a. (Vector v a, KnownNat n, RealFloat a) => Vector v (n + 1) a -> (Vector v (n + 1) a, Vector v n a)
instance GHC.Classes.Ord (v a) => GHC.Classes.Ord (Numeric.HHT.HHTLine v n a)
instance GHC.Classes.Eq (v a) => GHC.Classes.Eq (Numeric.HHT.HHTLine v n a)
instance GHC.Show.Show (v a) => GHC.Show.Show (Numeric.HHT.HHTLine v n a)