doc tf_tools

python/tffpy/tf_tools.py

@@ -20,13 +20,13 @@ def get_dgt_params(win_type, approx_win_len, hop, n_bins,
 
     The output dictionary `dgt_params` is composed of:
 
-    * dgt_params['win'] : the window array (nd-array)
-    * dgt_params['hop'] : the hop size (int)
-    * dgt_params['n_bins'] : the number of frequency bins (int)
-    * dgt_params['input_win_len'] : the effective window length (input window
+    * `dgt_params['win']`: the window array (nd-array)
+    * `dgt_params['hop']`: the hop size (int)
+    * `dgt_params['n_bins']`: the number of frequency bins (int)
+    * `dgt_params['input_win_len']`: the effective window length (input window
       length rounded to the nearest power of two).
-    * dgt_params['phase_conv'] : the phase convention 'freqinv' or 'timeinv',
-      see `pt` argument in :py:func:`ltfatpy.gabor.dgtreal`
+    * `dgt_params['phase_conv']`: the phase convention `'freqinv'` or
+      `'timeinv'`, see `pt` argument in :py:func:`ltfatpy.gabor.dgtreal`
 
     Parameters
     ----------
@@ -71,10 +71,46 @@ def get_dgt_params(win_type, approx_win_len, hop, n_bins,
 
 
 def get_signal_params(sig_len, fs):
+    """
+    Build dictionary of DGT parameter
+
+    The output dictionary `signal_params` is composed of:
+
+    * `signal_params['sig_len']` : the signal length
+    * `signal_params['fs']` : the sampling frequency
+
+    This function is only embedding the input parameters into a dictionary
+    without changing their values.
+
+    Parameters
+    ----------
+    sig_len : int
+        Signal length
+    fs : int
+        Sampling frequency
+
+    Returns
+    -------
+    dict
+        See above
+    """
     return dict(sig_len=sig_len, fs=fs)
 
 
 class GaborMultiplier(LinearOperator):
+    """
+    Gabor multipliers
+
+    Parameters
+    ----------
+    mask : nd-array
+        Time-frequency mask
+    dgt_params : dict
+        DGT parameters
+    signal_params : dict
+        Signal parameters
+    """
+
     def __init__(self, mask, dgt_params, signal_params):
         self.sig_len = signal_params['sig_len']
         LinearOperator.__init__(self,
@@ -94,6 +130,16 @@ class GaborMultiplier(LinearOperator):
     #     return self.sig_len, self.sig_len
 
     def _adjoint(self):
+        """
+        Adjoint of the Gabor multiplier
+
+        Note that since the Gabor multiplier is self-adjoint, this method
+        returns the object itself.
+
+        Returns
+        -------
+        GaborMultiplier
+        """
         return self
 
     def _matvec(self, x):
@@ -102,38 +148,108 @@ class GaborMultiplier(LinearOperator):
         return self.idgt(tf_mat=self.dgt(sig=x) * self.mask)
 
     def dgt(self, sig):
+        """
+        Apply the DGT related to the Gabor multiplier
+
+        Parameters
+        ----------
+        sig : nd-array
+            Real signal to be transformed
+
+        Returns
+        -------
+        nd-array
+            DGT coefficients
+        """
         return dgtreal(f=sig, g=self.win, a=self.hop, M=self.n_bins,
                        L=self.sig_len, pt=self.phase_conv)[0]
 
     def idgt(self, tf_mat):
+        """
+        Apply the invers DGT related to the Gabor multiplier
+
+        Parameters
+        ----------
+        tf_mat : nd-array
+            Time-frequency coefficients (non-negative frequencies only)
+        Returns
+        -------
+        nd-array
+            Real signal
+        """
         return idgtreal(coef=tf_mat, g=self.win, a=self.hop, M=self.n_bins,
                         Ls=self.sig_len, pt=self.phase_conv)[0]
 
     def plot_win(self, label=None):
+        """
+        Plot the window in the current figure.
+
+        Parameters
+        ----------
+        label : str or None
+            If not None, label to be assigned to the curve.
+        """
         plot_win(win=self.win, fs=self.fs, label=label)
 
     def plot_mask(self):
+        """
+        Plot the time-frequency mask
+        """
         plot_mask(mask=self.mask, hop=self.hop, n_bins=self.n_bins, fs=self.fs)
 
     def compute_ambiguity_function(self, fftshift=True):
+        """
+        Compute the ambiguity function of the window
+
+        Parameters
+        ----------
+        fftshift : bool
+            If true, shift the window in time before computing its DGT.
+        """
         if fftshift:
             w = self.win.copy()
-            # w.resize(self.sig_len)
-            # plt.figure()
-            # plt.plot(w)
-            # plt.plot(-self.win)
-            # plt.figure()
             return self.dgt(np.fft.fftshift(w))
         else:
             return self.dgt(self.win)
 
     def plot_ambiguity_function(self, dynrange=100, fftshift=True):
+        """
+        Plot the ambiguity function of the window in the current figure.
+
+        Parameters
+        ----------
+        dynrange : float
+            Dynamic range to be displayed
+        fftshift : bool
+            If true, shift the window in time before computing its DGT.
+        """
         plotdgtreal(
             coef=self.compute_ambiguity_function(fftshift=fftshift),
             a=self.hop, M=self.n_bins, fs=self.fs, dynrange=dynrange)
 
 
 def generate_rectangular_mask(n_bins, hop, sig_len, t_lim, f_lim):
+    """
+    Generate a rectangular time-frequency mask
+
+    Parameters
+    ----------
+    n_bins : int
+        Number of frequency bins
+    hop : int
+        Hop size
+    sig_len : int
+        Signal length
+    t_lim : sequence (2,)
+        Time boundaries of the mask
+    f_lim : sequence (2,)
+        Frequency boundaries of the mask
+
+    Returns
+    -------
+    nd-array
+        The boolean 2D array containing the time-frequency mask (True values)
+    """
     f_lim = np.array(f_lim)
     t_lim = np.array(t_lim)
     mask = np.zeros((n_bins // 2 + 1, sig_len // hop), dtype=bool)