Merge pull request #118 from hyperion-ml/tyche-cleanup

Tyche cleanup

Author: jesus-villalba

egs/sre19-av-v/v0.1/datapath.sh

@@ -5,7 +5,7 @@
 
 #paths to databases
 if [ "$(hostname --domain)" == "clsp.jhu.edu" ];then
-  ldc_root=/export/corpora/LDC
+  ldc_root=/export/corpora5/LDC
   sre19_dev_root=$ldc_root/LDC2019E56
   sre19_eval_root=$ldc_root/LDC2019E57
   janus_root=$ldc_root/LDC2019E55/Janus_Multimedia_Dataset

egs/sre19-av-v/v0.2/datapath.sh

@@ -5,7 +5,7 @@
 
 #paths to databases
 if [ "$(hostname --domain)" == "clsp.jhu.edu" ];then
-  ldc_root=/export/corpora/LDC
+  ldc_root=/export/corpora5/LDC
   sre19_dev_root=$ldc_root/LDC2019E56
   sre19_eval_root=$ldc_root/LDC2019E57
   janus_root=$ldc_root/LDC2019E55/Janus_Multimedia_Dataset

egs/sre19-av-v/v0.2/steps_insightface/extract-face-embed-from-bbox-plus-face-det-v4.py

@@ -180,7 +180,7 @@ def __init__(self):
                 overlap_score = np.expand_dims(overlap_score, axis=0)
                 d_score = np.expand_dims(d_score, axis=0)
 
-                x_f = extract_embed_in_frame_v4(
+                x_f, q_f = extract_embed_in_frame_v4(
                     embed_extractor,
                     frame,
                     landmarks,

egs/sre19-av-v/v0.2/steps_insightface/extract-face-embed-from-image.py

@@ -128,7 +128,7 @@ def __init__(self):
                 )
                 continue
 
-            x = extract_embed_in_frame_v4(
+            x, _ = extract_embed_in_frame_v4(
                 embed_extractor,
                 frame,
                 landmarks,

egs/sre21-av-v/v0.1/datapath.sh

@@ -5,7 +5,7 @@
 
 #paths to databases
 if [ "$(hostname --domain)" == "clsp.jhu.edu" ];then
-  ldc_root=/export/corpora/LDC
+  ldc_root=/export/corpora5/LDC
   # sre19_dev_root=$ldc_root/LDC2019E56
   # sre19_eval_root=$ldc_root/LDC2019E57
   sre21_dev_root=$ldc_root/LDC2021E09

egs/sre21-av-v/v0.2/datapath.sh

@@ -5,7 +5,7 @@
 
 #paths to databases
 if [ "$(hostname --domain)" == "clsp.jhu.edu" ];then
-  ldc_root=/export/corpora/LDC
+  ldc_root=/export/corpora5/LDC
   # sre19_dev_root=$ldc_root/LDC2019E56
   # sre19_eval_root=$ldc_root/LDC2019E57
   sre21_dev_root=$ldc_root/LDC2021E09

hyperion/__init__.py

@@ -18,4 +18,4 @@
 
 # from . import generators
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

hyperion/clustering/ahc.py

@@ -15,6 +15,17 @@
 
 
 class AHC(HypModel):
+    """Agglomerative Hierarchical Clustering class.
+
+    Attributes:
+      method: linkage method to calculate the distance between a new agglomerated
+              cluster and the rest of clusters.
+              This can be ["average", "single", "complete", "weighted", "centroid", "median", "ward"].
+              See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.cluster.hierarchy.linkage.html
+      metric: indicates the type of metric used to calculate the input scores.
+              It can be: "llr" (log-likelihood ratios), "prob" (probabilities), "distance": (distance metric).
+    """
+
     def __init__(self, method="average", metric="llr", **kwargs):
         super().__init__(**kwargs)
         self.method = method
@@ -23,6 +34,15 @@ def __init__(self, method="average", metric="llr", **kwargs):
         self.flat_clusters = None
 
     def fit(self, x, mask=None):
+        """Performs the clustering.
+           It stores the AHC tree in the Z property of the object.
+
+        Args:
+          x: input score matrix (num_samples, num_samples).
+             It will use the upper triangular matrix only.
+          mask: boolean mask where False in position i,j means that
+                nodes i and j should not be merged.
+        """
 
         if mask is not None:
             x = copy(x)
@@ -44,12 +64,27 @@ def fit(self, x, mask=None):
             self.Z = linkage(scores, method=self.method, metric=self.metric)
 
     def get_flat_clusters(self, t, criterion="threshold"):
+        """Computes the flat clusters from the AHC tree.
+
+        Args:
+          t: threshold or number of clusters
+          criterion: if "threshold" with llr/prob larger than threshold or
+                    distance lower than threshold.
+                     if "num_clusters" returns the clusters corresponding
+                     to selecting a given number of clusters.
+
+        Returns:
+          Clusters assigments for x as numpy integer vector (num_samples,).
+        """
         if criterion == "threshold":
             return self.get_flat_clusters_from_thr(t)
         else:
             return self.get_flat_clusters_from_num_clusters(t)
 
     def get_flat_clusters_from_num_clusters(self, num_clusters):
+        """Computes the flat clusters from the AHC tree using
+        num_clusters criterion"
+        """
         N = self.Z.shape[0] + 1
         num_clusters = min(N, num_clusters)
         p_idx = N - num_clusters
@@ -67,14 +102,23 @@ def get_flat_clusters_from_num_clusters(self, num_clusters):
         return flat_clusters
 
     def get_flat_clusters_from_thr(self, thr):
+        """Computes the flat clusters from the AHC tree using
+        threshold criterion"
+        """
         if self.metric == "llr" or self.metric == "prob":
             idx = self.Z[:, 2] >= thr
         else:
             idx = self.Z[:, 2] <= thr
         num_clusters = self.Z.shape[0] + 1 - np.sum(idx)
         return self.get_flat_clusters_from_num_clusters(num_clusters)
 
-    def compute_flat_clusters():
+    def compute_flat_clusters(self):
+        """Computes the flat clusters for all possible number of clusters
+
+        Returns:
+            numpy matrix (num_samples, num_samples) where row i contains the
+            clusters assignments for the case of choosing num_samples - i clusters.
+        """
         N = self.Z.shape[0] + 1
         flat_clusters = np.zeros((N, N), dtype=int)
         flat_clusters[0] = np.arange(N, dtype=int)
@@ -86,20 +130,29 @@ def compute_flat_clusters():
             flat_clusters[i + 1][segm_idx] = N + i
 
         for i in range(1, N):
-            _, flat_clusters[i] = np.unique(flat_clusters, return_inverse=True)
+            _, flat_clusters[i] = np.unique(flat_clusters[i], return_inverse=True)
         self.flat_clusters = flat_clusters
 
-    def evaluate_impurity_det(self, labels_true):
+    def evaluate_homogeneity_completeness_tradeoff(self, true_labels):
+        """Evaluates the curve homogeneity versus completeness where
+              Homogeneity: each cluster contains only members of a single class. (cluster purity)
+              Completeness: all members of a given class are assigned to the same cluster. (class purity)
+
+        Args:
+          true_labels: true cluster labels
+
+        Returns:
+            homogeneity vector (num_samples,)
+            completenes vector (num_samples,)
+        """
         if self.flat_clusters is None:
             self.compute_flat_clusters()
 
-        # homogeneity: each cluster contains only members of a single class. (cluster purity)
-        # completeness: all members of a given class are assigned to the same cluster. (class purity)
         N = self.flat_clusters.shape[0]
         h = np.zeros((N,), dtype=float_cpu())
         c = np.zeros((N,), dtype=float_cpu())
         for i in range(self.flat_clusters.shape[0]):
-            h[i] = homogeneity_score(labels_true, self.flat_clusters[i])
-            c[i] = completeness_score(labels_true, self.flat_clusters[i])
+            h[i] = homogeneity_score(true_labels, self.flat_clusters[i])
+            c[i] = completeness_score(true_labels, self.flat_clusters[i])
 
-        return 1 - h, 1 - c
+        return h, c

hyperion/clustering/kmeans.py

@@ -13,13 +13,31 @@
 
 
 class KMeans(HypModel):
+    """K-Means clustering class.
+
+    Attributes:
+      num_clusters: number of clusters.
+      mu: cluster centers.
+      rtol: minimum delta in loss function used as stopping criterion.
+    """
+
     def __init__(self, num_clusters, mu=None, rtol=0.001, **kwargs):
         super(KMeans, self).__init__(**kwargs)
         self.num_clusters = num_clusters
         self.mu = mu
         self.rtol = rtol
 
     def fit(self, x, epochs=100):
+        """Performs the clustering.
+
+        Args:
+          x: input data (num_samples, feat_dim).
+          epochs: max. number of epochs.
+
+        Returns:
+          loss: value of loss function (num_epochs,).
+          cluster_index: clustering labels as int numpy array with shape=(num_samples,)
+        """
         loss = np.zeros((epochs,), dtype=float_cpu())
         self.mu = self._choose_seeds(x)
         cluster_index, err2 = self.predict(x)
@@ -36,6 +54,14 @@ def fit(self, x, epochs=100):
         return loss, cluster_index
 
     def _choose_seeds(self, x):
+        """Chooses the initial seeds for the clustering.
+
+        Args:
+          x: input data (num_samples, feat_dim).
+
+        Returns:
+          Initial centers (num_clusters, feat_dim)
+        """
         mu = np.zeros((self.num_clusters, x.shape[-1]), dtype=float_cpu())
         mu[0] = x[0]
         for i in range(1, self.num_clusters):
@@ -47,6 +73,15 @@ def _choose_seeds(self, x):
         return mu
 
     def _compute_centroids(self, x, index):
+        """Compute the centroids given cluster assigments.
+
+        Args:
+          x: input data (num_samples, feat_dim)
+          index: cluster assignments as integers with shape=(num_samples,)
+
+        Returns:
+          Cluster centroids (num_clusters, feat_dim)
+        """
         mu = np.zeros((self.num_clusters, x.shape[-1]), dtype=float_cpu())
         for k in range(self.num_clusters):
             r = index == k
@@ -55,6 +90,15 @@ def _compute_centroids(self, x, index):
         return mu
 
     def predict(self, x):
+        """Compute the cluster labels for new data.
+
+        Args:
+          x: input data (num_samples, feat_dim)
+
+        Returns:
+          Cluster assignments as integer array (num_samples,)
+          Square distance of each element to the center of its cluster.
+        """
         err2 = np.zeros((x.shape[0], self.num_clusters), dtype=float_cpu())
         for k in range(self.num_clusters):
             err2[:, k] = np.sum(np.square(x - self.mu[k]), axis=-1)

hyperion/diarization/diar_ahc_plda.py

@@ -19,6 +19,30 @@
 
 
 class DiarAHCPLDA(object):
+    """Class to perform diarization using
+    Agglomerative clustering using scores computed by a PLDA model.
+
+    The steps are:
+    - It applies a pre-processing transformation to the data, such as LDA and
+      Length normalization (optional).
+    - Trains PCA on the test data and reduces test data dimension. It also
+      transforms the parameters of the PLDA model using the PCA projection matrix (optional).
+    - Gets affinity matrix using PLDA scoring.
+    - It applies unsupervised calibration to scores using GMM model (optional).
+    - Performs AHC.
+
+    Attributes:
+      plda_model: pre-trained PLDA model.
+      preproc: preprocessing transformation class.
+               If None, no transformation is applied.
+      threshold: stopping threshold for AHC.
+      pca_var_r: ratio of variance to keep when doing PCA on features after
+                 the preprocessing. If "pca_var_r=1", PCA is not applied.
+      do_unsup_cal: applies unsupervised calibration to PLDA scores.
+      use_bic: uses Bayesian Information Criterion to decide if there is 1 or 2 components
+               in the GMM used for calibration.
+    """
+
     def __init__(
         self,
         plda_model,
@@ -39,7 +63,7 @@ def __init__(
 
     @staticmethod
     def _plot_score_hist(scores, output_file, thr=None, gmm=None):
-
+        """Plots the score histograms and GMM."""
         output_dir = Path(output_file).parent
         output_dir.mkdir(parents=True, exist_ok=True)
 
@@ -72,6 +96,7 @@ def _plot_score_hist(scores, output_file, thr=None, gmm=None):
 
     @staticmethod
     def _unsup_gmm_calibration(scores):
+        """Performs unsupervised calibration on the scores by training a GMM."""
         mask = np.triu(np.ones(scores.shape, dtype=np.bool), 1)
         scores_r = scores[mask].ravel()[:, None]  # N x 1
         gmm_1c = GMM(num_comp=1)
@@ -95,6 +120,15 @@ def _unsup_gmm_calibration(scores):
         return scores, bic, gmm_2c
 
     def cluster(self, x, hist_file=None):
+        """Peforms the diarization clustering.
+
+        Args:
+          x: input data (num_frames, feat_dim)
+          hist_file: file to plot the score histogram (optional).
+
+        Returns:
+          Cluster assigments as (num_frames,) integer array.
+        """
         x = self.preproc.predict(x)
         if self.pca_var_r < 1:
             pca = PCA(pca_var_r=self.pca_var_r, whiten=True)