# ELLPARAMS is the jEllipse module of jLab.

``` ELLPARAMS  Ellipse parameters of a modulated bivariate or trivariate oscillation.

[KAPPA,LAMBDA,THETA,PHI]=ELLPARAMS(X,Y) where X and Y are analytic
signals, returns the parameters of the complex-valued signal
Z=REAL(X)+i REAL(Y), expressed as a modulated ellipse.

Here KAPPA is the RMS ellipse amplitude, LAMBDA is the linearity,
THETA is the orientation, and PHI is the instantaneous orbital phase.

ELLPARAMS(M), where M is matrix with two columns, also works.

See Lilly and Gascard (2006) and Lilly and Olhede (2010a) for details.

ELLPARAMS is inverted by ELLSIG, which returns the X and Y signals
given the ellipse parameters.

ELLPARAMS(...,DIM) performs the analysis with time running along
dimension DIM, as opposed to the default behavior of DIM=1.
_______________________________________________________________________

Trivariate signals

ELLPARAMS also works for trivariate signals, which can be expressed as
a modulated ellipse in three dimensions.

[KAPPA,LAMBDA,THETA,PHI,ALPHA,BETA]=ELLPARAMS(X,Y,Z), where X, Y, and Z
are all analytic signals, also returns the zenith angle ALPHA and the
azimuth angle BETA in addition to the other ellipse parameters.

ELLPARAMS(M), where M is matrix with three columns, also works.

See Lilly (2010) for details on the trivariate case.
_______________________________________________________________________

Cell array input / output

[KAPPA,LAMBDA,THETA,PHI]=ELLPARAMS(C) also works if C is a cell array
containing, say K different X and Y signals, each as a 2-column matrix,

C{1}(:,1)=X1, C{1}(:,2)=Y1
C{2}(:,1)=X2, C{2}(:,2)=Y2, ...
C{K}(:,1)=XK, C{2}(:,2)=YK.

In this case, the output variables will also be length K cell arrays.

The trivariate form described above also works, with each cell now
being a matrix with three columns.

This format works with the cell array output format of RIDGEWALK.
__________________________________________________________________

'ellparams --t' runs a test.