Function: constructphase
CONSTRUCTPHASE  Construct phase for DGT
  Usage:  c=constructphase(s,g,a);
          c=constructphase(s,g,a,tol);
          c=constructphase(c,g,a,tol,mask);
          c=constructphase(c,g,a,tol,mask,usephase);
          [c,newphase,usedmask,tgrad,fgrad] = constructphase(...);

  Input parameters:
        s        : Initial coefficients.
        g        : Analysis Gabor window.
        a        : Hop factor.
        tol      : Relative tolerance.
        mask     : Mask for selecting known phase.
        usephase : Explicit known phase.
  Output parameters:
        c        : Coefficients with the constructed phase.
        newphase : Just the (unwrapped) phase.
        usedmask : Mask for selecting coefficients with the new phase.
        tgrad    : Relative time phase derivative.
        fgrad    : Relative frequency phase derivative.

  CONSTRUCTPHASE(s,g,a) will construct a suitable phase for the postive
  valued coefficients s. 
 
  If s is the absolute values of the Gabor coefficients of a signal
  obtained using the window g and time-shift a, i.e.:

    c=dgt(f,g,a,M);
    s=abs(c);

  then constuctphase(s,g,a) will attempt to reconstruct c.

  The window g must be Gaussian, i.e. g must have the value 'gauss'
  or be a cell array {'gauss',tfr}. 

  CONSTRUCTPHASE(s,g,a,tol) does as above, but sets the phase of
  coefficients less than tol to random values. 
  By default, tol has the value 1e-10.

  CONSTRUCTPHASE(c,g,a,M,tol,mask) accepts real or complex valued
  c and real valued mask of the same size. Values in mask which can
  be converted to logical true (anything other than 0) determine
  coefficients with known phase which is used in the output. Only the
  phase of remaining coefficients (for which mask==0) is computed.

  CONSTRUCTPHASEreal(c,g,a,M,tol,mask,usephase) does the same as before
  but uses the known phase values from usephase rather than from c.

  In addition, tol can be a vector containing decreasing values. In 
  that case, the algorithm is run numel(tol) times, initialized with
  the result from the previous step in the 2nd and the further steps.

  Further, the function accepts the following flags:

     'freqinv'  The constructed phase complies with the frequency
                invariant phase convention such that it can be directly
                used in IDGTREAL.
                This is the default.

     'timeinv'  The constructed phase complies with the time-invariant
                phase convention. The same flag must be used in the other
                functions e.g. IDGTREAL

  This function requires a computational subroutine that is only
  available in C. Use LTFATMEX to compile it.


  References:
    Z. Průša, P. Balazs, and P. L. Soendergaard. A Non-iterative Method for
    STFT Phase (Re)Construction. IEEE/ACM Transactions on Audio, Speech,
    and Language Processing, 2016. In preparation. Preprint will be
    available at http://ltfat.github.io/notes/ltfatnote040.pdf.
    

Url: http://ltfat.github.io/doc/gabor/constructphase.html

See also: dgt, gabphasegrad, ltfatmex.

Package: ltfat