doc tffpy.create_subregions

python/tffpy/create_subregions.py

@@ -15,8 +15,37 @@ from tffpy.tf_tools import GaborMultiplier
 
 def create_subregions(mask_bool, dgt_params, signal_params, tol,
                       fig_dir=None, return_norms=False):
+    """
+    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.
+    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.
+    """
     mask_labeled, n_labels = label(mask_bool)
-    pq_norms = get_pq_norms(mask=mask_labeled,
+    pq_norms = _get_pq_norms(mask=mask_labeled,
                              dgt_params=dgt_params, signal_params=signal_params)
 
     if fig_dir is not None:
@@ -47,7 +76,7 @@ def create_subregions(mask_bool, dgt_params, signal_params, tol,
         while pq_norms.max() > tol:
             i_p, i_q = np.unravel_index(np.argmax(pq_norms, axis=None),
                                         pq_norms.shape)
-            mask_labeled, pq_norms = merge_subregions(mask=mask_labeled,
+            mask_labeled, pq_norms = _merge_subregions(mask=mask_labeled,
                                                        pq_norms=pq_norms,
                                                        i_p=i_p, i_q=i_q)
             to_be_updated[i_q] = True
@@ -56,7 +85,7 @@ def create_subregions(mask_bool, dgt_params, signal_params, tol,
             n_labels -= 1
         for i_p in range(n_labels):
             if to_be_updated[i_p]:
-                update_pq_norms(mask=mask_labeled,
+                _update_pq_norms(mask=mask_labeled,
                                  pq_norms=pq_norms, i_p=i_p,
                                  dgt_params=dgt_params,
                                  signal_params=signal_params)
@@ -104,7 +133,25 @@ def create_subregions(mask_bool, dgt_params, signal_params, tol,
         return mask_labeled
 
 
-def get_pq_norms(mask, dgt_params, signal_params):
+def _get_pq_norms(mask, dgt_params, signal_params):
+    """
+    Compute distance matrix between sub-regions.
+
+    Parameters
+    ----------
+    mask : nd-array
+        Time-frequency mask with one positive integer for each sub-region
+        and zeros outside sub-regions.
+    dgt_params : dict
+        DGT parameters
+    signal_params : dict
+        Signal parameters
+
+    Returns
+    -------
+    pq_norms : nd-array
+        Matrix of distances between sub-regions.
+    """
     n_labels = np.unique(mask).size - 1
     pq_norms = np.zeros((n_labels, n_labels))
     for i_p in range(n_labels):
@@ -121,7 +168,26 @@ def get_pq_norms(mask, dgt_params, signal_params):
     return pq_norms
 
 
-def update_pq_norms(mask, pq_norms, i_p, dgt_params, signal_params):
+def _update_pq_norms(mask, pq_norms, i_p, dgt_params, signal_params):
+    """
+    Update (in-place) distance between one particular sub-region and all
+    sub-regions in distance matrix.
+
+    Parameters
+    ----------
+    mask : 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, updated in-place.
+    i_p : int
+        Index of sub-region to be updated
+    dgt_params : dict
+        DGT parameters
+    signal_params : dict
+        Signal parameters
+
+    """
     n_labels = pq_norms.shape[0]
     gabmul_p = GaborMultiplier(mask=(mask == i_p + 1),
                                dgt_params=dgt_params,
@@ -141,10 +207,39 @@ def update_pq_norms(mask, pq_norms, i_p, dgt_params, signal_params):
             pq_norms[i_q, i_p] = gabmul_pq_norm
 
 
-def merge_subregions(mask, pq_norms, i_p, i_q):
-    # assert i_q < i_p
-    if not i_q < i_p:
-        pass
+def _merge_subregions(mask, pq_norms, i_p, i_q):
+    """
+    Merge two sub-regions indexed by `i_p` and `i_q`
+
+
+    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 :py:func:`_update_pq_norms`.
+
+    Parameters
+    ----------
+    mask : 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.
+    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.
+    Returns
+    -------
+    mask : nd-array
+        Updated time-frequency mask with one positive integer for each
+        sub-region and zeros outside sub-regions.
+    pq_norms : nd-array
+        Updated distance matrix (except for distance with the new sub-region).
+
+    """
     p = i_p + 1
     q = i_q + 1