# INSTMOM is the jRidges module of jLab.

``` INSTMOM  Univariate and multivariate instantaneous moments.
don't need this because it really doesn't seep things up much from
using anatrans and instmome

[A,OMEGA,UPSILON]=INSTMOM(X), where X is an analytic signal, computes
the amplitude A, instantaneous *radian* frequency OMEGA, and
instantaneous bandwidth assuming a unit sample rate.

X is an array with the first dimension being "time".  Thus, X can be a
matrix of analytic signals oriented as column vectors, or a 2- or 3-D
wavelet transform such as output by WAVETRANS.

The output arrays are the same size as X.

The instantaneous frequency, bandwidth, and curvature are defined as

A    = abs X
OMEGA  = d/dt Im ln X = d/dt arg X
UPSILON = d/dt Re ln X = d/dt ln abs X

where i=SQRT(-1) as usual.

INSTMOM(X,DIM) computes the moments along dimension DIM, instead of
the default of computing the moments along the rows (DIM=1).

For details, see

Lilly & Olhede (2010), "Bivariate instantaneous frequency and
bandwidth", IEEE Trans. Sig. Proc., 58 (2), 591--603.
_____________________________________________________________________

Sample interval

INSTMOM(DT,...) uses sample interval DT, where DT is a scalar, for
computing time derivatives.  DT=1 is the default.
_____________________________________________________________________

Joint instantaneous moments

INSTMOM can also calculate the joint instananeous moments of
multivariate signals, as defined in Lilly and Olhede (2010).

[JA,JOMEGA,JUPSILON]=INSTMOM(X1,X2,...,XN,DIM) returns the *joint*
instantaneous moments calculated across the N signals X1,X2,... XN,
based on the univariate instantaneous moments along dimension DIM.

The joint instantaneous amplitude JA is the root-mean-square of the
component amplitudes across dimension JDIM, while JOMEGA is power-
weighted average of the component instantaneous frequencies.

For details and for the definition of the joint instantaneous bandwidth
JUPSILON, see Lilly and Olhede (2010).

[JA,JOMEGA,JUPSILON]=INSTMOM(X,DIM,JDIM) also works, where the joint
instantaneous moments are calculated across dimensions JDIM of X.

The joint instantaneous moments JA, JOMEGA, and JUPSILON then have the
same size as X, except along dimension JDIM where they have only one
entry.  Note that DIM is no longer optional when JDIM is used.
_____________________________________________________________________

Instantaneous curvature

INSTMOM can also return the next-higher order instantaneous moment,
which is more rarely encountered.

[A,OMEGA,UPSILON,XI]=INSTMOM(X) returns the instantaneous curvature XI,
defined as

XI   = d^2/dt^2 abs X / abs X + i d^2/dt^2 arg X
= UPSILON^2 + d/dt UPSILON + i d/dt OMEGA

Similarly [JA,JOMEGA,JUPSILON,JXI]=INSTMOM(X,DIM,JDIM) returns the
joint instantaneous curvature JXI for the multivariate signal X.

For details on the univariate and joint instantaneous curvature, see

Lilly and Olhede (2012a), "Analysis of modulated multivariate
oscillations", IEEE Trans. Sig. Proc., 60 (2), 600--612.
_____________________________________________________________________

Boundary conditions

The first and last points must be treated differently, as the central
difference is not defined there.  Three different methods can be used.

INSTMOM(...,STR) specifies the method: STR= 'endpoint' (the default),
'periodic', or 'nans'.  See VDIFF for details.
_____________________________________________________________________

'instmom --f' generates some sample figures.

Usage: [a,om]=instmom(x);
[a,om,up,xi]=instmom(dt,x);
[a,om,up,xi]=instmom(dt,x,dim);
[a,om,up,xi]=instmom(dt,x1,x2,x3,x4,dim);
[a,om,up,xi]=instmom(dt,x,dim,jdim);
__________________________________________________________________
This is part of JLAB --- type 'help jlab' for more information
(C) 2007--2019 J.M. Lilly --- type 'help jlab_license' for details
```