PGHI - Phase Gradient Heap Integration

function [c,newphase,usedmask,tgrad,fgrad]=pghi(s,gamma,a,M,varargin)
%PGHI Phase Gradient Heap Integration
%   Usage:  c=pghi(s,gamma,a,M);
%           c=pghi(c,gamma,a,M,mask);
%           c=pghi(c,gamma,a,M,mask,usephase);
%           [c,newphase,usedmask,tgrad,fgrad] = pghi(...);
%
%   Input parameters:
%         s        : Initial coefficients.
%         gamma    : Window "width" factor.
%         a        : Hop factor.
%         M        : Number of channels.
%         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 used for selecting coefficients with the new phase.
%         tgrad    : Relative time phase derivative.
%         fgrad    : Relative frequency phase derivative.
% 
%   PGHI(s,gamma,a,M) creates complex DGT coefficients from their
%   absolute values s using the Phase Gradient Heap Integration algorithm.
%   s must have been obtained as:
%
%       c = dgtreal(f,g,a,M,'timeinv');
%       s = abs(c);
%
%   and the algorithm attempts to recover c. Parameter gamma is window 
%   g specific and it can be computed using PGHI_FINDGAMMA.
%
%   PGHI(c,gamma,a,M,mask) does the same as above except it reuses phase
%   of coefficients c for which the corresponding element from mask*
%   is nonzero.
%
%   PGHI(c,gamma,a,M,mask,usephase) does the same as above but the known
%   phase usephase is passed explicitly.
%
%   This is just a wrapper around CONSTRUCTPHASEREAL from LTFAT. Please
%   see its help for more details.
%
%   See also: dgtreal, idgtreal, rtpghi, pghi_findgamma
%
%   References:
%     Z. Průša, P. Balazs, and P. L. Søndergaard. A Noniterative Method for
%     Reconstruction of Phase from STFT Magnitude. IEEE/ACM Trans. on Audio,
%     Speech, and Lang. Process., 25(5), May 2017.
%     
%     Z. Průša and P. L. Søndergaard. Real-Time Spectrogram Inversion Using
%     Phase Gradient Heap Integration. In Proc. Int. Conf. Digital Audio
%     Effects (DAFx-16), Sep 2016.
%     
%
%
%   Url: http://ltfat.github.io/phaseret/doc/gabor/pghi.html

% Copyright (C) 2016 Zdenek Prusa <zdenek.prusa@gmail.com>.
% This file is part of PHASERET version 0.2.1
%
% This program is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program.  If not, see <http://www.gnu.org/licenses/>.

% AUTHOR: Zdenek Prusa

if ~isscalar(gamma)
    error('%s: gamma must be scalar.',upper(mfilename));
end

N = size(s,2);
L = N*a;
g = {'gauss',gamma/L};

definput.keyvals.tol=[1e-1,1e-10];
definput.keyvals.mask=[];
definput.keyvals.usephase=[];
definput.flags.phase={'timeinv','freqinv'};
[flags,kv]=ltfatarghelper({'mask','usephase'},definput,varargin);

[c,newphase,usedmask,tgrad,fgrad]=...
    constructphasereal(s,g,a,M,'tol',kv.tol,'mask',kv.mask,'usephase',kv.usephase,flags.phase);