From 1235d53074e09b1f9afba2650b9fbd37029e09eb Mon Sep 17 00:00:00 2001
From: "valentin.emiya" <valentin.emiya@lif.univ-mrs.fr>
Date: Wed, 3 Jun 2020 18:25:18 +0200
Subject: [PATCH] doc tf_tools
---
python/tffpy/tf_tools.py | 138 +++++++++++++++++++++++++++++++++++----
1 file changed, 127 insertions(+), 11 deletions(-)
diff --git a/python/tffpy/tf_tools.py b/python/tffpy/tf_tools.py
index c7f71e2..abc4bf8 100755
--- a/python/tffpy/tf_tools.py
+++ b/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)
--
GitLab