References

Release:0.1.5
Date:February 09, 2021

tffpy.create_subregions module

tffpy.create_subregions.create_subregions(mask_bool, dgt_params, signal_params, tol, fig_dir=None, return_norms=False)[source]

Create sub-regions from boolean mask and tolerance on sub-region distance.

See Algorithm 3 Finding sub-regions for TFF-P in the reference paper.

Parameters:

mask_bool : nd-array

Time-frequency boolean mask

dgt_params : dict

DGT parameters

signal_params : dict

Signal parameters

tol : float

Tolerance on sub-region distance (spectral norm of the composition of the Gabor multipliers related to two candidate sub-regions).

fig_dir : Path

If not None, folder where figures are stored. If None, figures are not plotted.

return_norms : bool

If True, the final distance matrix is returned as a second output.
Returns:

mask_labeled : nd-array

Time-frequency mask with one positive integer for each sub-region and zeros outside sub-regions.

pq_norms : nd-array

Matrix of distances between sub-regions.

tffpy.datasets module

tffpy.datasets.get_dataset()[source]

Get dataset for isolated wideband and localized sources before mixing.

Returns:

dataset : dict

dataset[‘wideband’] (resp. dataset[‘localized’]) is a dictionary containing the Path object for all the wideband (resp. localized) sounds.
tffpy.datasets.get_mix(loc_source, wideband_src, crop=None, wb_to_loc_ratio_db=0, win_dur=0.016, win_type='gauss', hop_ratio=0.25, n_bins_ratio=4, n_iter_closing=2, n_iter_opening=2, delta_mix_db=0, delta_loc_db=30, closing_first=True, or_mask=False, fig_dir=None, prefix='')[source]

Build the mix two sounds and the related time-frequency boolean mask.

Parameters:

loc_source : Path

Localized sound file.

wideband_src : Path

Wideband sound file.

crop : int or None

If not None, a cropped, centered portion of the sound will be extracted with the specified length, in samples.

wb_to_loc_ratio_db : float

Wideband source to localized source energy ratio to be adjusted in the mix.

win_dur : float

Window duration, in seconds.

win_type : str

Window name

hop_ratio : float

Ratio of the window length that will be set as hop size for the DGT.

n_bins_ratio : float

Factor that will be applied to the window length to compute the number of bins in the DGT.

delta_mix_db : float

Coefficient energy ratio, in dB, between the wideband source and the localized source in the mixture in order to select coefficients in the mask.

delta_loc_db : float

Dynamic range, in dB, for the localized source in order to select coefficients in the mask.

or_mask : bool

If True, the mask is build by taking the union of the two masks obtained using thresholds delta_mix_db and delta_loc_db. If False, the intersection is taken.

n_iter_closing : int

Number of successive morphological closings with radius 1 (a.k.a. radius of one single closing)

n_iter_opening : int

Number of successive morphological openings with radius 1 (a.k.a. radius of one single opening)

closing_first : bool

If True, morphological closings are applied first, followed by openings. If False, the reverse way is used.

fig_dir : None or str or Path

If not None, folder where figures are stored. If None, figures are not plotted.

prefix : str

If not None, this prefix is used when saving the figures.
Returns:

x_mix : Waveform

Mix signal (sum of outputs x_loc and x_wb)

dgt_params : dict

DGT parameters

signal_params : dict

Signal parameters

mask : nd-array

Time-frequency binary mask

x_loc : Waveform

Localized source signal

x_wb : Waveform

Wideband source signal

tffpy.interpolation_solver module

tffpy.interpolation_solver.solve_by_interpolation(x_mix, mask, dgt_params, signal_params, fig_dir=None)[source]

Time-frequency fading solver using linear interpolation and random phases

Parameters:

x_mix : nd-array

Mix signal

mask : nd-array

Time-frequency mask

dgt_params : dict

DGT parameters

signal_params : dict

Signal parameters

fig_dir : str or Path

If not None, folder where figures are stored. If None, figures are not plotted.
Returns:

nd-array

Estimated signal

tffpy.tf_fading module

Class GabMulTff is the main object to solve a time-frequency fading problem.

class tffpy.tf_fading.GabMulTff(x_mix, mask, dgt_params, signal_params, tol_subregions=None, fig_dir=None)[source]

Bases: object

Time-frequency fading using Gabor multipliers

Main object to solve the TFF problem

Parameters:

x_mix : nd-array

Mix signal

mask : nd-array

Time-frequency mask

dgt_params : dict

DGT parameters

signal_params : dict

Signal parameters

tol_subregions : None or float

If None, the mask is considered as a single region. If float, tolerance to split the mask into sub-regions using create_subregions().

fig_dir : str or Path

If not None, folder where figures are stored. If None, figures are not plotted.
compute_decomposition(tolerance_arrf, proba_arrf, rand_state=0)[source]

Decompose each Gabor multiplier using a random EVD

The decomposition is obtained using skpomade.range_approximation.adaptive_randomized_range_finder() followed by skpomade.factorization_construction.evd_nystrom(). The rank of each decomposition is estimated using parameters tolerance_arrf and proba_arrf. Running times to compute the range approximation, the EVD itself and the additional matrix products for subsequent computations are stored in attributes t_arrf, t_evdn and t_uh_x, respectively.

Parameters:

tolerance_arrf : float

Tolerance for adaptive_randomized_range_finder()

proba_arrf : float

Probability of error for adaptive_randomized_range_finder()

rand_state : RandomState, int or None

If RandomState, random generator. If int or None, random seed used to initialize the pseudo-random number generator.
compute_decomposition_fixed_rank(rank, rand_state=0)[source]

Decompose each Gabor multiplier using a random EVD with given rank

The decomposition is obtained using skpomade.range_approximation.randomized_range_finder() followed by skpomade.factorization_construction.evd_nystrom(). Running times are stored in attributes t_rrf, t_evdn and t_uh_x.

Parameters:

rank : int

Rank of the decompostion

rand_state : RandomState, int or None

If RandomState, random generator. If int or None, random seed used to initialize the pseudo-random number generator.
compute_estimate(lambda_coef)[source]

Compute the signal estimate for a given hyperparameter \(\lambda_i\) for each sub-region \(i\).

Prior decomposition should have been performed using compute_decomposition() or compute_decomposition_fixed_rank().

Parameters:

lambda_coef : nd-array or float

If nd-array, hyperparameters \(\lambda_i\) for each sub-region \(i\). If float, the same value \(\lambda\) is used for each sub-region.
Returns:

nd-array

Reconstructed signal
compute_lambda(x_mix, e_target=None)[source]

Estimate hyperparameters \(\lambda_i\) from target energy in each sub-region \(i\).

Parameters:

x_mix : nd-array

Mix signal

e_target : nd-array or None

Target energy for each sub-region/. If None, function estimate_energy_in_mask() is used to estimate the target energies.
Returns:

lambda_est : nd-array

Hyperparameters \(\lambda_i\) for each sub-region \(i\).

t_est : nd-array

Running time to estimate each hyperparameter.
n_areas

Number of sub-regions

tffpy.tf_fading.compute_lambda_oracle_sdr(gmtff, x_wb)[source]

Compute oracle value for hyperparameter \(\lambda_i\) from true solution.

If only one region is considered, the Brent’s algorithm is used (see scipy.optimize.minimize_scalar()). If multiple sub-regions are considered the BFGS algorithm is used (see scipy.optimize.minimize()).

Parameters:

gmtff : GabMulTff

x_wb : nd-array

True signal for the wideband source.
Returns:

lambda_oracle : nd-array

Oracle values for hyperparameters \(\lambda_i\) for each sub-region \(i\).

t_oracle : nd-array

Running times for the computation of each hyperparameter
tffpy.tf_fading.estimate_energy_in_mask(x_mix, mask, dgt_params, signal_params, fig_dir=None, prefix=None)[source]

Estimate energy in time-frequency mask

Parameters:

x_mix : nd-array

Mix signal

mask: nd-array

Time-frequency mask for each sub-region

dgt_params : dict

DGT parameters

signal_params : dict

Signal parameters

fig_dir : str or Path

If not None, folder where figures are stored. If None, figures are not plotted.

prefix : str

If not None, this prefix is used when saving the figures.
Returns:

nd-array

Estimated energy in each sub-region.
tffpy.tf_fading.reconstruction(x_mix, lambda_coef, u_mat, s_vec)[source]

tffpy.tf_tools module

Base functions and classes.

class tffpy.tf_tools.GaborMultiplier(mask, dgt_params, signal_params)[source]

Bases: scipy.sparse.linalg.interface.LinearOperator

Gabor multipliers

Parameters:

mask : nd-array

Time-frequency mask

dgt_params : dict

DGT parameters

signal_params : dict

Signal parameters
compute_ambiguity_function(fftshift=True)[source]

Compute the ambiguity function of the window

Parameters:

fftshift : bool

If true, shift the window in time before computing its DGT.
dgt(sig)[source]

Apply the DGT related to the Gabor multiplier

Parameters:

sig : nd-array

Real signal to be transformed
Returns:

nd-array

DGT coefficients
idgt(tf_mat)[source]

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
plot_ambiguity_function(dynrange=100, fftshift=True)[source]

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.
plot_mask()[source]

Plot the time-frequency mask

plot_win(label=None)[source]

Plot the window in the current figure.

Parameters:

label : str or None

If not None, label to be assigned to the curve.
tffpy.tf_tools.generate_rectangular_mask(n_bins, hop, sig_len, t_lim, f_lim)[source]

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)
tffpy.tf_tools.get_dgt_params(win_type, approx_win_len, hop, n_bins, phase_conv='freqinv', sig_len=None)[source]

Build dictionary of DGT parameter

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 length rounded to the nearest power of two).
  • dgt_params[‘phase_conv’]: the phase convention ‘freqinv’ or ‘timeinv’, see pt argument in ltfatpy.gabor.dgtreal()
Parameters:

win_type : str

Window name, e.g. ‘hann’, ‘gauss’ (see ltfatpy.arg_firwin())

approx_win_len : int

Approximate window length

hop : int

Hop size

n_bins : int

Number of frequency bins

phase_conv : ‘freqinv’ or ‘timeinv’

Phase convention

sig_len : int

Signal length
Returns:

dict

DGT parameters (see above)
tffpy.tf_tools.get_signal_params(sig_len, fs)[source]

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

tffpy.utils module

Utils classes and functions for tffpy.

tffpy.utils.db(x)[source]

Linear to decibel (dB) conversion

Parameters:

x : scalar or nd-array

Values to be converted
Returns:

scalar or nd-array

Conversion of input x in dB.
tffpy.utils.dgt(sig, dgt_params)[source]

Discrete Gabor transform of a signal

Parameters:

sig : nd-array

Input signal

dgt_params : dict

DGT parameters (see tffpy.tf_tools.get_dgt_params)
Returns:

nd-array

DGT coefficients
tffpy.utils.generate_config()[source]

Generate an empty configuration file.

tffpy.utils.get_config_file()[source]

User configuration file

Returns:Path
tffpy.utils.get_data_path()[source]

Read data folder from user configuration file.

Returns:Path
tffpy.utils.idgt(tf_mat, dgt_params, sig_len)[source]

Inverse discrete Gabor transform

Parameters:

tf_mat : nd-array

DGT coefficients

dgt_params : dict

DGT parameters (see tffpy.tf_tools.get_dgt_params)

sig_len : int

Signal length
Returns:

nd-array

Reconstructed signal
tffpy.utils.is_div(x_ref, x_est)[source]

Itakura-Saito divergence

Parameters:

x_ref : nd-array

Reference array

x_est : nd-array

Estimation of the reference array
Returns:

float
tffpy.utils.is_div_spectrum(x_ref, x_est)[source]

Itakura-Saito divergence computed via discrete Fourier transform

Parameters:

x_ref : nd-array

Reference signal

x_est : nd-array

Estimation of the reference signal
Returns:

float
tffpy.utils.plot_mask(mask, hop, n_bins, fs)[source]

Plot time-frequency mask

Parameters:

mask : nd-array

Time-frequency mask

hop : int

Hop size

n_bins : int

Number of frequency bins

fs : int

Sampling frequency
tffpy.utils.plot_spectrogram(x, dgt_params, fs, dynrange=100, clim=None)[source]

Plot spectrogram of a signal

Parameters:

x : nd-array

Signal

dgt_params : dict

DGT parameters (see tffpy.tf_tools.get_dgt_params)

fs : int

Sampling frequency

dynrange : float

Dynamic range to be displayed.

clim : sequence

Min and max values for the colorbar. If both clim and dynrange are specified, then clim takes precedence.
tffpy.utils.plot_win(win, fs, label=None)[source]

Plot window

Parameters:

win : nd-array

Window array

fs : int

Sampling frequency

label : str or None

If not None, label to be assigned to the curve.
tffpy.utils.sdr(x_ref, x_est)[source]

Signal to distortion ratio

Parameters:

x_ref : nd-array

Reference signal

x_est : nd-array

Estimation of the reference signal
Returns:

float
tffpy.utils.snr(x_signal, x_noise)[source]

Signal to noise ratio

Parameters:

x_signal : nd-array

Signal of interest

x_noise : nd-array

Noise signal
Returns:

float

tffpy.experiments.exp_solve_tff module

Class SolveTffExperiment uses the yafe.base.Experiment experiment framework to handle the main time-frequency fading experiment: It includes loading the data, generating the problems, applying solvers, and exploiting results.

See the documentation of package yafe for the technical details.

class tffpy.experiments.exp_solve_tff.Problem(crop, win_choice, delta_mix_db, delta_loc_db, wb_to_loc_ratio_db, or_mask, n_iter_closing, n_iter_opening, closing_first, fig_dir)[source]

Bases: object

Problem generation for the SolveTffExperiment experiment.

Parameters:

crop : int or None

If not None, a cropped, centered portion of the sound will be extracted with the specified length, in samples.

win_choice : str

String of the form ‘name len’ where ‘name’ is a window name and ‘len’ is a window length, e.g. ‘hann 512’, ‘gauss 256.

delta_mix_db : float

Coefficient energy ratio, in dB, between the wideband source and the localized source in the mixture in order to select coefficients in the mask.

delta_loc_db : float

Dynamic range, in dB, for the localized source in order to select coefficients in the mask.

wb_to_loc_ratio_db : float

Wideband source to localized source energy ratio to be adjusted in the mix.

or_mask : bool

If True, the mask is build by taking the union of the two masks obtained using thresholds delta_mix_db and delta_loc_db. If False, the intersection is taken.

n_iter_closing : int

Number of successive morphological closings with radius 1 (a.k.a. radius of one single closing)

n_iter_opening : int

Number of successive morphological openings with radius 1 (a.k.a. radius of one single opening)

closing_first : bool

If True, morphological closings are applied first, followed by openings. If False, the reverse way is used.

fig_dir : None or str or Path

If not None, folder where figures are stored. If None, figures are not plotted.
__call__(loc_source, wideband_src)[source]

Generate the problem from input data.

Parameters:

loc_source : Path

File for the source localized in time-frequency (perturbation)

wideband_src : Path

File for the source of interest.
Returns:

problem_data : dict

Dictionary to be given to a solver, with keys ‘x_mix’ (mix signal), mask (time-frequency mask), dgt_params (DGT parameters) and signal_params (signal parameters).

solution_data : dict

Dictionary containing problem solutions, with keys ‘x_loc’ ( localized signal ) and x_wb (wideband signal).
class tffpy.experiments.exp_solve_tff.SolveTffExperiment(force_reset=False, suffix='', keep_eigenvectors='all')[source]

Bases: yafe.base.Experiment

The main experiment to solve time-frequency fading problems with a number of sounds mixtures and solvers.

Parameters:

force_reset : bool

If true, reset the experiment by erasing all previous results in order to run it from scratch. If False, the existing results are kept in order to proceed with the existing experiment.

suffix : str

Suffix that is appended to the name of the experiment, useful to save results in a specific folder.

keep_eigenvectors : ‘all’ or list

Use this parameter to remove eigenvectors from GabMulTff object after computing performance in order to save space. In this case, the GabMulTff will not be usable anymore after the computation of the performance results. If ‘all’, all eigenvectors are kept. To keep only some eigenvectors, set this parameter to the list of task IDs for which eigenvectors should be kept (usefull if you want to use or plot some task data after the experiments, e.g., using method plot_task). If the list is empty, all eigenvectors will be removed.
export_task_params(csv_path=None)[source]

Export task parameters to a csv file and to a pandas.DataFrame object.

Parameters:

csv_path : str or Path

Name of the csv file to be written. If None, file is located in the experiment folder with name ‘task_params.csv’.
Returns:

pandas.DataFrame
generate_tasks()[source]

Generate tasks and export params to a csv file

See yafe.Experiment.generate_tasks()

static get_experiment(setting='full', force_reset=False, keep_eigenvectors=None)[source]

Get the experiment instance with default values in order to handle it.

Parameters:

setting : {‘full’, ‘light’}

If ‘full’, the default values are set to run the full experiment. If ‘light’, the default values are set to have a very light experiment with few tasks, running fast, for test purposes.

force_reset : bool

If true, reset the experiment by erasing all previous results in order to run it from scratch. If False, the existing results are kept in order to proceed with the existing experiment.

keep_eigenvectors = ‘all’ or list

See constructor of SolveTffExperiment. If None, default values are used.
Returns:

SolveTffExperiment
get_idt_from_params(data_params, problem_params, solver_params)[source]
get_misc_file(task_params=None, idt=None)[source]

Get file with some additional task results.

This has been set up in order to pass additional data in a way that could not be handled by the yafe framework.

Parameters:

task_params : dict

Task parameters.

idt : int

Task identifier. Either task_params or idt should be given in order to specify the task.
Returns:

Path

File containing additional task results.
plot_results()[source]

Plot and save results of the experiment

plot_task(idt, fontsize=16)[source]

Plot and save figures for a specific task

Parameters:

idt : int

Task identifier

fontsize : int

Fontsize to be used in Figures.
n_tasks

Number of tasks

Returns:int
class tffpy.experiments.exp_solve_tff.Solver(tol_subregions, tolerance_arrf, proba_arrf, rand_state=0)[source]

Bases: object

Solver for the SolveTffExperiment experiment.

This solver is computing

Parameters:

tol_subregions : None or float

Tolerance to split the mask into sub-regions in GabMulTff.

tolerance_arrf : float

Tolerance for the randomized EVD in GabMulTff, see method compute_decomposition().

proba_arrf : float

Probability of error for the randomized EVD in GabMulTff, see method compute_decomposition().
__call__(x_mix, mask, dgt_params, signal_params)[source]

Apply the solver to estimate solutions from the problem data.

The output dictionary is composed of data with keys:

  • ‘x_tff’: solution estimated by GabMulTff
  • ‘x_zero’: solution when applying the Gabor multiplier (i.e., \(\lambda=1\))
  • ‘x_interp’: solution from function solve_by_interpolation()
  • ‘gmtff’: GabMulTff instance
  • ‘t_lambda_tff’: running times to estimate hyperparameter in method compute_lambda()
  • ‘t_arrf’: running times to compute range approximation in method compute_decomposition()
  • ‘t_evdn’: running times to compute EVD in method compute_decomposition()
  • ‘t_uh_x’: running times to compute additional matrix products in method compute_decomposition()
  • ‘t_subreg’: running times to split mask into sub-regions in class GabMulTff
  • ‘lambda_tff’: estimated values for hyper-parameters \(\lambda_i\) estimated by GabMulTff().compute_lambda`
Parameters:

x_mix : nd-array

Mix signal

mask : nd-array

Time-frequency mask

dgt_params : dict

DGT parameters

signal_params : dict

Signal parameters
Returns:

dict

The estimated solution and additional information
tffpy.experiments.exp_solve_tff.create_and_run_light_experiment()[source]

Create a light experiment and run it

tffpy.experiments.exp_solve_tff.get_data(loc_source, wideband_src)[source]

Prepare the input data information for the SolveTffExperiment experiment.

This function is only embedding its input in a dictionary

Parameters:

loc_source : Path

File for the source localized in time-frequency (perturbation)

wideband_src : Path

File for the source of interest.
Returns:

dict

Dictionary to be given when calling the problemm ( see Problem.__call__()), with keys ‘loc_source’ and wideband_src.
tffpy.experiments.exp_solve_tff.perf_measures(task_params, source_data, problem_data, solution_data, solved_data, exp=None)[source]

Performance measure, including computation of oracle solutions

Parameters:

task_params : dict

Task parameters

source_data : dict

Input data

problem_data : dict

Problem data

solution_data : dict

Solver output

solved_data : dict

True solution data

exp : SolveTffExperiment

The experiment
Returns:

dict

All data useful for result analysis including SDR and Itakura-Saito performance, running times, hyperparameter values, mask size, number of sub-regions, estimated rank (summed over sub-regions), lowest singular value.