add doc - fix

matlab/tfgm/subregions/create_subregions.m

 function  [mask_labeled, varargout] = create_subregions(mask, dgt, idgt, ...,
     dgt_params, signal_params, tol, fig_dir)
 
-%% [mask_labeled, varargout] = create_subregions(mask, dgt, idgt, dgt_params, signal_params, tol, fig_dir)
-%  This function splits the whole region $\Omega$ in such sub-regions.[1]
+%% [mask_labeled, varargout] = create_subregions(mask, dgt, idgt, ...,
+%    dgt_params, signal_params, tol, fig_dir)
+% See Algorithm 3 *Finding sub-regions for TFF-P* in the reference paper[1].
 %
 % Inputs:
-%      - mask: original mask
-%      - dgt, idgt : Gabor transform and its inverse operator
-%      - dgt_params : Discrete Gabor Transform parameters(hop, nbins,win, ect..)
-%      -signal_params: Signals parameters(sig_len, fs)
-%      - tol: tolerance .see [1]
+%      - mask: Time-frequency boolean mask
+%      - idgt,dgt (handle): DGT and IDGT . see utils/get_stft_operators.m
+% Outputs:
+%      - dgt_params (struct): DGT parameters
+%      - signal_params (struct): Signals parameters
+%      - tol: Tolerance on sub-region distance (spectral norm of the composition
+%        of the Gabor multipliers related to two candidate sub-regions).see [1]
 %      - fig_dir :  Figures directory
 %
 % Outputs:
-%     - mask_labeled: mask with P regions
-%     -pq_norms_val: norms between two Gabor multipliers
+%     - mask_labeled: Time-frequency mask with one positive integer for
+%         each sub-region and zeros outside sub-regions.
+
+%     -pq_norms_val:  Matrix of distances between sub-regions.
 %
 %
 % Reference:
@@ -23,8 +28,8 @@ function  [mask_labeled, varargout] = create_subregions(mask, dgt, idgt, ...,
 %
 % Author: Marina KREME
 %%
-mask = boolean(mask);
-[mask_labeled, n_labels] = bwlabel(mask);
+mask_bool = boolean(mask);
+[mask_labeled, n_labels] = bwlabel(mask_bool);
 sig_len = signal_params.sig_len;
 pq_norms_val = get_pq_norms(sig_len, dgt, idgt, mask_labeled);
 
@@ -35,9 +40,9 @@ title('Initial subregions')
 saveas(gcf,fullfile(fig_dir, 'initial_subregions.pdf'));
 
 figure;
-imagesc(real(log10(pq_norms_val+pq_norms_val')))
-ylabel('p')
-xlabel('q')
+imagesc(real(log10(pq_norms_val+pq_norms_val.')))
+ylabel('Sub-region index')
+xlabel('Sub-region index')
 colorbar()
 title('Initial norms of Gabor multiplier composition')
 saveas(gcf,fullfile(fig_dir, 'initial_norms.pdf'));
@@ -48,7 +53,7 @@ n_labels_max = n_labels;
 
 while max(pq_norms_val(:))>tol
     %Merge each pair (p, q), q < p, such that pq_norms[p, q] > tol
-    to_be_updated = boolean(zeros(n_labels,1));
+    to_be_updated = true(zeros(n_labels,1));
     
     while max(pq_norms_val(:))>tol
         [i_p, i_q] =  find(pq_norms_val == max(pq_norms_val(:)));
@@ -80,9 +85,9 @@ while max(pq_norms_val(:))>tol
     
     
     figure;
-    imagesc(real(log10(pq_norms_val+pq_norms_val')))
-    ylabel('p-1')
-    xlabel('q-1')
+    imagesc(real(log10(pq_norms_val+pq_norms_val.')))
+    ylabel('Sub-region index')
+    xlabel('Sub-region index')
     colorbar()
     title('norms of Gabor multiplier composition')
     saveas(gcf,fullfile(fig_dir, ['norms_i', num2str(n_labels_max-n_labels),'.pdf']));
@@ -102,9 +107,9 @@ saveas(gcf,fullfile(fig_dir,'final_subregions.pdf'));
 
 
 figure;
-imagesc(real(log10(pq_norms_val+pq_norms_val')))
-ylabel('p-1')
-xlabel('q-1')
+imagesc(real(log10(pq_norms_val+pq_norms_val.')))
+ylabel('Sub-region index')
+xlabel('Sub-region index')
 colorbar()
 title('Final norms of Gabor multiplier composition')
 saveas(gcf,fullfile(fig_dir, 'final_norms.pdf'));

matlab/tfgm/subregions/get_pq_norms.m

 function pq_norms_val = get_pq_norms(sig_len, dgt, idgt, mask_labeled)
 
 %%  pq_norms_val = get_pq_norms(sig_len, dgt, idgt, mask_labeled)
-% This function compute norms between two Gabor multiplier
+% This function Compute distance matrix between sub-regions.
 %
 % Inputs:
-%     - sig_len : signal length
-%     - dgt, idgt: Discrete Gabor Transform parameters(hop, nbins,win, ect..)
+%     - sig_len (int): signal length
+%     - idgt,dgt (handle): DGT and IDGT . see utils/get_stft_operators.m
 %     - mask_labeled: mask with P regions
 % Output:
-%     - pq_norms_val :  array with all norms between all p and q regions
+%     - pq_norms_val (nd array) :  Matrix of distances between sub-regions.
 %
 % Author: Marina KREME
 %

matlab/tfgm/subregions/merge_subregions.m

 function[mask, pq_norms_val] = merge_subregions(mask, pq_norms_val, i_p, i_q)
 
 %% [mask, pq_norms_val] = merge_subregions(mask, pq_norms_val, i_p, i_q)
-% This function merge two regions. See [1]
+% This function merge two sub-regions indexed by *i_p* and *i_q*. See [1]
 %
+% In the time-frequency mask, the label of the region indexed by *i_p*
+%   will be replace by the label of the region indexed by *i_q* and index
+%    *i_p* will be used to relabel the region with highest label.
+%
+%   In the distance matrix, rows and columns will be moved consequently. The
+%  distance between the new, merged sub-region and all other sub-regions is
+%  not updated; it can be done by calling *update_pq_norms*.
+
 % Inputs:
-%     -mask: mask with P regions (mask labeled)
-%     -pq_norms_val:  array with all norms between all p and q regions
-%     - i_p, i_q: ineteger
+%     - mask_labeled (nd array): Time-frequency mask with one positive integer
+%       for each sub-region and zeros outside sub-regions.
+%     - pq_norms_val:  Matrix of distances between sub-regions, updated in-place.
+%     - i_p (int):  Index of sub-region that will be removed after merging.
+%     - i_q (int): Index of sub-region that will receive the result.
 % Outputs:
-%     -mask:final mask
-%     - pq_norms_val: array with all norms between all p and q regions
+%     -mask (nd array):updated time-frequency mask with one positive integer
+%                       for each sub-region and zeros outside sub-regions.
+
+%     - pq_norms_val (nd array):  Updated distance matrix (except for distance
+%                        with the new sub-region).
 
 % Reference:
 % [1]Time-frequency fading algorithms based on Gabor multipliers,2020.

matlab/tfgm/subregions/update_pq_norms.m

 function pq_norms_val = update_pq_norms(mask_labeled, pq_norms_val, i_p, signal_params, dgt, idgt)
 
-
 %% pq_norms_val = update_pq_norms(mask_labeled, pq_norms_val, i_p, signal_params, dgt, idgt)
 %
-% This function compute  bit faster norms between two Gabor multiplier.
+% Update (in-place) distance between one particular sub-region and all
+% sub-regions in distance matrix.
+%
 %  This is an improvement of the function get_pq_norms.m
 %
 % Inputs:
-%     - mask_labeled: mask labeled-mask with P regions
-%     -pq_norms_val: array with all norms between all p and q regions
-%     -i_p: ineteger
-%     -signal_params: Signals parameters(sig_len, fs)
-%     - dgt, idgt: Discrete Gabor Transform parameters(hop, nbins,win, ect..)
+%     - mask_labeled (nd array): Time-frequency mask with one positive integer
+%       for each sub-region and zeros outside sub-regions.
+%     - pq_norms_val:  Matrix of distances between sub-regions, updated in-place.
+%     - i_p (int):  Index of sub-region to be updated
+%     - signal_params (struct): Signals parameters
+%    - idgt,dgt (handle): DGT and IDGT . see utils/get_stft_operators.m
 % Output:
-%     - pq_norms_val :  array with all norms between all p and q regions
+%     - pq_norms_val :  Matrix of distances between sub-regions.
 %
 % Author: Marina KREME