Function: isgram
ISGRAM  Spectrogram inversion
  Usage:  f=isgram(c,g,a);
          f=isgram(c,g,a,Ls);
          [f,relres,iter]=isgram(...);

  Input parameters:
        c       : Array of coefficients.
        g       : Window function.
        a       : Length of time shift.
        Ls      : length of signal.
  Output parameters:
        f       : Signal.
        relres  : Vector of residuals.
        iter    : Number of iterations done.

  ISGRAM(s,g,a) attempts to invert a spectrogram computed by :

    s = abs(dgt(f,g,a,M)).^2;

  using an iterative method.

  ISGRAM(c,g,a,Ls) does as above but cuts or extends f to length Ls.

  If the phase of the spectrogram is known, it is much better to use
  idgt.

  [f,relres,iter]=ISGRAM(...) additionally return the residuals in a
  vector relres and the number of iteration steps iter.

  Generally, if the spectrogram has not been modified, the iterative
  algorithm will converge slowly to the correct result. If the
  spectrogram has been modified, the algorithm is not guaranteed to
  converge at all.  

  ISGRAM takes the following parameters at the end of the line of input
  arguments:

    'lt',lt      Specify the lattice type. See the help on MATRIX2LATTICETYPE.

    'zero'       Choose a starting phase of zero. This is the default

    'rand'       Choose a random starting phase.

    'int'        Construct a starting phase by integration. Only works
                 for Gaussian windows.

    'griflim'    Use the Griffin-Lim iterative method, this is the
                 default.

    'bfgs'       Use the limited-memory Broyden Fletcher Goldfarb
                 Shanno (BFGS) method.  

    'tol',t      Stop if relative residual error is less than the specified tolerance.  

    'maxit',n    Do at most n iterations.

    'print'      Display the progress.

    'quiet'      Don't print anything, this is the default.

    'printstep',p  If 'print' is specified, then print every p'th
                   iteration. Default value is p=10;

  The BFGS method makes use of the minFunc software. To use the BFGS method, 
  please install the minFunc software from:
  http://www.cs.ubc.ca/~schmidtm/Software/minFunc.html.

  Examples:
  ---------

  To reconstruct the phase of 'greasy', use the following:

    % Setup the problem and the coefficients
    f=greasy;
    g='gauss';
    a=20; M=200;
    c=dgt(f,g,a,M);
    s=abs(c).^2;
    theta=angle(c);

    % Reconstruct and get spectrogram and angle
    r=isgram(s,g,a);
    c_r=dgt(r,g,a,M);
    s_r=abs(c_r).^2;
    theta_r=angle(c_r);

    % Compute the angular difference
    d1=abs(theta-theta_r);
    d2=2*pi-d1;
    anglediff=min(d1,d2);

    % Plot the difference in spectrogram and phase
    figure(1);
    plotdgt(s./s_r,a,16000,'clim',[-10,10]);
    colormap([bone;flipud(bone)])
    title('Relative difference in spectrogram');

    figure(2);
    plotdgt(anglediff,a,16000,'lin');
    colormap(bone);
    title('Difference in angle');


  References:
    R. Decorsiere and P. L. Soendergaard. Modulation filtering using an
    optimization approach to spectrogram reconstruction. In Proceedings of
    the Forum Acousticum, 2011.
    
    D. Griffin and J. Lim. Signal estimation from modified short-time
    Fourier transform. IEEE Trans. Acoust. Speech Signal Process.,
    32(2):236--243, 1984.
    
    D. Liu and J. Nocedal. On the limited memory BFGS method for large
    scale optimization. Mathematical programming, 45(1):503--528, 1989.
    

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

See also: isgramreal, frsynabs, dgt.

Package: ltfat