nkululeko 0.81.4__py3-none-any.whl → 0.81.6__py3-none-any.whl

nkululeko/autopredict/estimate_snr.py

@@ -1,20 +1,30 @@
 # estimate.snr
-import numpy as np
+"""
+Module for estimating SNR (signal to noise ratio) from an audio signal.
+
+This module provides a class `SNREstimator` which calculates the SNR based on
+the log energy and energy thresholds of the audio signal.
+
+"""
+
+import argparse
+
 import audiofile
 import matplotlib.pyplot as plt
+import numpy as np
 from scipy.signal.windows import hamming
-import argparse
 
 
 class SNREstimator:
-    """Estimate SNR from audio signal using log energy and energy thresholds
+    """Estimate SNR from audio signal using log energy and energy thresholds.
+
     Args:
         input_data (ndarray): Input audio signal
         sample_rate (int): Sampling rate of input audio signal
         window_size (int): Window size in samples
         hop_size (int): Hop size in samples
 
-        Returns:
+    Returns:
         object: SNREstimator object
         estimated_snr (float): Estimated SNR in dB, extracted from SNREstimator.estimate_snr()
 
@@ -34,7 +44,7 @@ class SNREstimator:
         num_frames = 1 + (len(signal) - self.frame_length) // self.hop_length
         frames = [
             signal[
-                i * self.hop_length : (i * self.hop_length) + self.frame_length
+                i * self.hop_length: (i * self.hop_length) + self.frame_length
             ]
             for i in range(num_frames)
         ]
@@ -54,7 +64,8 @@ class SNREstimator:
             for frame in frames
         ]
 
-        energy_threshold_low = np.percentile(log_energies, 25)  # First quartile
+        energy_threshold_low = np.percentile(
+            log_energies, 25)  # First quartile
         energy_threshold_high = np.percentile(
             log_energies, 75
         )  # Third quartile

nkululeko/constants.py

@@ -1,2 +1,2 @@
-VERSION="0.81.4"
+VERSION="0.81.6"
 SAMPLING_RATE = 16000

nkululeko/data/dataset.py

@@ -76,6 +76,7 @@ class Dataset:
         if rename_cols:
             col_dict = ast.literal_eval(rename_cols)
             df = df.rename(columns=col_dict)
+            self.util.debug(f"renamed data columns: {col_dict}")
         return df
 
     def _report_load(self):
@@ -281,13 +282,19 @@ class Dataset:
                 # try to get the age values
                 df_local["age"] = source_df["age"].astype(int)
                 got_age = True
-            except (KeyError, ValueError, audformat.errors.BadKeyError) as e:
+            except (KeyError, ValueError, audformat.errors.BadKeyError):
                 pass
             try:
                 # also it might be possible that the sex is part of the speaker description
                 df_local["gender"] = db[table]["speaker"].get(map="gender")
                 got_gender = True
-            except (ValueError, audformat.errors.BadKeyError) as e:
+            except (ValueError, audformat.errors.BadKeyError):
+                pass
+            try:
+                # also it might be possible that the sex is part of the speaker description
+                df_local["gender"] = db[table]["speaker"].get(map="sex")
+                got_gender = True
+            except (ValueError, audformat.errors.BadKeyError):
                 pass
             try:
                 # also it might be possible that the age is part of the speaker description

nkululeko/demo.py

@@ -2,20 +2,35 @@
 # Demonstration code to use the ML-experiment framework
 # Test the loading of a previously trained model and demo mode
 # needs the project config file to run before
+"""
+This script is used to test the loading of a previously trained model and run it in demo mode.
+It requires the project config file to be run before.
 
-import os
+Usage:  
+python -m nkululeko.demo [--config CONFIG] [--file FILE] [--list LIST] [--folder FOLDER] [--outfile OUTFILE]  
+
+Options:   \n
+--config CONFIG     The base configuration file (default: exp.ini) \n  
+--file FILE         A file that should be processed (16kHz mono wav) \n  
+--list LIST         A file with a list of files, one per line, that should be processed (16kHz mono wav) \n  
+--folder FOLDER     A name of a folder where the files within the list are in   (default: ./) \n   
+--outfile OUTFILE   A filename to store the results in CSV  (default: None)  
+"""
 import argparse
 import configparser
+import os
 
+import nkululeko.glob_conf as glob_conf
+from nkululeko.constants import VERSION
 from nkululeko.experiment import Experiment
 from nkululeko.utils.util import Util
-from nkululeko.constants import VERSION
-import nkululeko.glob_conf as glob_conf
 
 
 def main(src_dir):
-    parser = argparse.ArgumentParser(description="Call the nkululeko framework.")
-    parser.add_argument("--config", default="exp.ini", help="The base configuration")
+    parser = argparse.ArgumentParser(
+        description="Call the nkululeko DEMO framework.")
+    parser.add_argument("--config", default="exp.ini",
+                        help="The base configuration")
     parser.add_argument(
         "--file", help="A file that should be processed (16kHz mono wav)"
     )

nkululeko/demo_predictor.py

@@ -1,8 +1,11 @@
+# demo_predictor.py
 import os
-import pandas as pd
-import numpy as np
-import audiofile
+
 import audformat
+import audiofile
+import numpy as np
+import pandas as pd
+
 import nkululeko.glob_conf as glob_conf
 from nkululeko.utils.util import Util
 

nkululeko/experiment.py

@@ -695,7 +695,7 @@ class Experiment:
             pickle.dump(self.__dict__, f)
             f.close()
         except TypeError:
-            self.feature_extractor.featExtractor.model = None
+            self.feature_extractor.feat_extractor.model = None
             f = open(filename, "wb")
             pickle.dump(self.__dict__, f)
             f.close()

nkululeko/explore.py

@@ -1,17 +1,20 @@
 # explore.py
 # explore the feature sets
 
-from nkululeko.experiment import Experiment
-import configparser
-from nkululeko.utils.util import Util
-from nkululeko.constants import VERSION
 import argparse
+import configparser
 import os
 
+from nkululeko.constants import VERSION
+from nkululeko.experiment import Experiment
+from nkululeko.utils.util import Util
+
 
 def main(src_dir):
-    parser = argparse.ArgumentParser(description="Call the nkululeko framework.")
-    parser.add_argument("--config", default="exp.ini", help="The base configuration")
+    parser = argparse.ArgumentParser(
+        description="Call the nkululeko EXPLORE framework.")
+    parser.add_argument("--config", default="exp.ini",
+                        help="The base configuration")
     args = parser.parse_args()
     if args.config is not None:
         config_file = args.config
@@ -46,9 +49,11 @@ def main(src_dir):
 
     # split into train and test
     expr.fill_train_and_tests()
-    util.debug(f"train shape : {expr.df_train.shape}, test shape:{expr.df_test.shape}")
+    util.debug(
+        f"train shape : {expr.df_train.shape}, test shape:{expr.df_test.shape}")
 
-    plot_feats = eval(util.config_val("EXPL", "feature_distributions", "False"))
+    plot_feats = eval(util.config_val(
+        "EXPL", "feature_distributions", "False"))
     tsne = eval(util.config_val("EXPL", "tsne", "False"))
     scatter = eval(util.config_val("EXPL", "scatter", "False"))
     spotlight = eval(util.config_val("EXPL", "spotlight", "False"))

nkululeko/feat_extract/feats_agender.py

@@ -32,10 +32,7 @@ class AudModelAgenderSet(Featureset):
             audeer.extract_archive(archive_path, model_root)
         device = self.util.config_val("MODEL", "device", "cpu")
         self.model = audonnx.load(model_root, device=device)
-        pytorch_total_params = sum(p.numel() for p in self.model.parameters())
-        self.util.debug(
-            f"initialized agender model with {pytorch_total_params} parameters in total"
-        )
+        self.util.debug(f"initialized agender model")
         self.model_loaded = True
 
     def extract(self):

nkululeko/feat_extract/{feats_audmodel_dim.py → feats_auddim.py}

@@ -13,11 +13,12 @@ from nkululeko.feat_extract.featureset import Featureset
 import nkululeko.glob_conf as glob_conf
 
 
-class AudModelDimSet(Featureset):
-    """
-    Emotional dimensions from the wav2vec2. based model finetuned on MSPPodcast emotions, described in the paper
+class AuddimSet(Featureset):
+    """Emotional dimensions from the wav2vec2 model finetuned on MSPPodcast emotions.
+
+    Described in the paper
     "Dawn of the transformer era in speech emotion recognition: closing the valence gap"
-    https://arxiv.org/abs/2203.07378
+    https://arxiv.org/abs/2203.07378.
     """
 
     def __init__(self, name, data_df):

nkululeko/feat_extract/feats_audmodel.py

@@ -11,11 +11,12 @@ import torch
 from nkululeko.feat_extract.featureset import Featureset
 
 
-class AudModelSet(Featureset):
-    """
-    Embeddings from the wav2vec2. based model finetuned on MSPPodcast emotions, described in the paper
+class AudmodelSet(Featureset):
+    """Embeddings from the wav2vec2 based model finetuned on MSPPodcast emotions.
+
+    Described in the paper:
     "Dawn of the transformer era in speech emotion recognition: closing the valence gap"
-    https://arxiv.org/abs/2203.07378
+    https://arxiv.org/abs/2203.07378.
     """
 
     def __init__(self, name, data_df):

nkululeko/feat_extract/feats_import.py

@@ -8,7 +8,7 @@ from nkululeko.utils.util import Util
 from nkululeko.feat_extract.featureset import Featureset
 
 
-class Importset(Featureset):
+class ImportSet(Featureset):
     """Class to import features that have been compiled elsewhere"""
 
     def __init__(self, name, data_df):

nkululeko/feat_extract/feats_mos.py

@@ -10,6 +10,7 @@ pip uninstall -y torch torchvision torchaudio
 pip install --pre torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/nightly/cpu
 
 """
+
 import os
 import pandas as pd
 from tqdm import tqdm
@@ -23,7 +24,7 @@ from nkululeko.utils.util import Util
 from nkululeko.feat_extract.featureset import Featureset
 
 
-class MOSSet(Featureset):
+class MosSet(Featureset):
     """Class to predict MOS (mean opinion score)"""
 
     def __init__(self, name, data_df):

nkululeko/feat_extract/feats_praat.py

@@ -1,17 +1,19 @@
 # feats_praat.py
-from nkululeko.feat_extract.featureset import Featureset
+import ast
 import os
-import pandas as pd
+
 import numpy as np
-import nkululeko.glob_conf as glob_conf
+import pandas as pd
+
 from nkululeko.feat_extract import feinberg_praat
-import ast
+from nkululeko.feat_extract.featureset import Featureset
+import nkululeko.glob_conf as glob_conf
 
 
-class Praatset(Featureset):
-    """
-    a feature extractor for the Praat software, based on
-    David R. Feinberg's Praat scripts for the parselmouth python interface.
+class PraatSet(Featureset):
+    """A feature extractor for the Praat software.
+
+    Based on David R. Feinberg's Praat scripts for the parselmouth python interface.
     https://osf.io/6dwr3/
 
     """

nkululeko/feat_extract/feats_snr.py

@@ -1,14 +1,17 @@
-""" feats_snr.py
-    Estimate snr (signal to noise ratio as acoustic features)
+""" feats_snr.py is to estimate snr.
+
+SNR (signal to noise ratio) is extracted as acoustic features.
 """
 import os
-from tqdm import tqdm
-import pandas as pd
+
 import audiofile
+import pandas as pd
+from tqdm import tqdm
+
 import nkululeko.glob_conf as glob_conf
-from nkululeko.utils.util import Util
-from nkululeko.feat_extract.featureset import Featureset
 from nkululeko.autopredict.estimate_snr import SNREstimator
+from nkululeko.feat_extract.featureset import Featureset
+from nkululeko.utils.util import Util
 
 
 class SNRSet(Featureset):
@@ -16,14 +19,17 @@ class SNRSet(Featureset):
 
     def __init__(self, name, data_df):
         """Constructor."""
+
         super().__init__(name, data_df)
 
     def extract(self):
         """Estimate the features or load them from disk if present."""
+
         store = self.util.get_path("store")
         store_format = self.util.config_val("FEATS", "store_format", "pkl")
         storage = f"{store}{self.name}.{store_format}"
-        extract = self.util.config_val("FEATS", "needs_feature_extraction", False)
+        extract = self.util.config_val(
+            "FEATS", "needs_feature_extraction", False)
         no_reuse = eval(self.util.config_val("FEATS", "no_reuse", "False"))
         if extract or no_reuse or not os.path.isfile(storage):
             self.util.debug("estimating SNR, this might take a while...")
@@ -40,7 +46,8 @@ class SNRSet(Featureset):
                 snr = self.get_snr(signal[0], sampling_rate)
                 snr_series[idx] = snr
             print("")
-            self.df = pd.DataFrame(snr_series.values.tolist(), index=self.data_df.index)
+            self.df = pd.DataFrame(
+                snr_series.values.tolist(), index=self.data_df.index)
             self.df.columns = ["snr"]
             self.util.write_store(self.df, storage, store_format)
             try:
@@ -53,10 +60,11 @@ class SNRSet(Featureset):
 
     def get_snr(self, signal, sampling_rate):
         r"""Estimate SNR from raw audio signal.
+
         Args:
             signal: audio signal
             sampling_rate: sample rate
-        Returns
+        Returns:
             snr: estimated signal to noise ratio
         """
         snr_estimator = SNREstimator(signal, sampling_rate)

nkululeko/feat_extract/feats_squim.py

@@ -1,36 +1,33 @@
-""" feats_squim.py
-predict SQUIM ( SPEECH QUALITY AND INTELLIGIBILITY
-MEASURES) features
+"""Predict SQUIM ( SPEECH QUALITY AND INTELLIGIBILITY MEASURES) features.
 
-
-    Wideband Perceptual Estimation of Speech Quality (PESQ) [2]
-    Short-Time Objective Intelligibility (STOI) [3]
-    Scale-Invariant Signal-to-Distortion Ratio (SI-SDR) [4]
-
-
-adapted from
+Wideband Perceptual Estimation of Speech Quality (PESQ) [2].
+    Short-Time Objective Intelligibility (STOI) [3].
+    Scale-Invariant Signal-to-Distortion Ratio (SI-SDR) [4].
+Adapted from
 from https://pytorch.org/audio/main/tutorials/squim_tutorial.html#sphx-glr-tutorials-squim-tutorial-py
-paper: https://arxiv.org/pdf/2304.01448.pdf
-
-needs 
+paper: https://arxiv.org/pdf/2304.01448.pdf.
+Needs
 pip uninstall -y torch torchvision torchaudio
 pip install --pre torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/nightly/cpu
 
 """
 
 import os
-from tqdm import tqdm
+
 import pandas as pd
 import torch
 import torchaudio
 from torchaudio.pipelines import SQUIM_OBJECTIVE
+from tqdm import tqdm
+
 import audiofile
+
+from nkululeko.feat_extract.featureset import Featureset
 import nkululeko.glob_conf as glob_conf
 from nkululeko.utils.util import Util
-from nkululeko.feat_extract.featureset import Featureset
 
 
-class SQUIMSet(Featureset):
+class SquimSet(Featureset):
     """Class to predict SQUIM features"""
 
     def __init__(self, name, data_df):

nkululeko/feature_extractor.py

@@ -1,22 +1,25 @@
-"""
-feature_extractor.py
-
-Helper class to encapsulate feature extraction methods
+"""Extract acoustic features from audio samples.
 
+Extract acoustic features using several feature extractors 
+(appends the features column-wise)
 """
+
 import pandas as pd
 
 from nkululeko.utils.util import Util
 
 
 class FeatureExtractor:
-    """
-    Extract acoustic features from audio samples, using several feature extractors (appends the features column-wise)
+    """Extract acoustic features from audio samples.
+
+    Extract acoustic features using several feature extractors (appends the features column-wise).
+
     Args:
         data_df (pandas.DataFrame): dataframe with audiofile paths as index
-        feats_types (array of strings): designations of acoustic feature extractors to be used
-        data_name (string): names of databases that are extracted (for the caching)
-        feats_designation (string): the type of split (train/test), also is used for the cache name.
+        feats_types (List[str]): designations of acoustic feature extractors to be used
+        data_name (str): name of databases that are extracted (for caching)
+        feats_designation (str): the type of split (train/test), also is used for the cache name.
+
     Returns:
         df (pandas.DataFrame): dataframe with same index as data_df and acoustic features in columns
     """
@@ -25,7 +28,6 @@ class FeatureExtractor:
     df = None
     data_df = None  # dataframe to get audio paths
 
-    # def __init__
     def __init__(self, data_df, feats_types, data_name, feats_designation):
         self.data_df = data_df
         self.data_name = data_name
@@ -34,147 +36,69 @@ class FeatureExtractor:
         self.feats_designation = feats_designation
 
     def extract(self):
-        # feats_types = self.util.config_val_list('FEATS', 'type', ['os'])
-        self.featExtractor = None
         self.feats = pd.DataFrame()
-        _scale = True
         for feats_type in self.feats_types:
             store_name = f"{self.data_name}_{feats_type}"
-            if feats_type == "os":
-                from nkululeko.feat_extract.feats_opensmile import Opensmileset
-
-                self.featExtractor = Opensmileset(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type == "spectra":
-                from nkululeko.feat_extract.feats_spectra import Spectraloader
-
-                self.featExtractor = Spectraloader(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type == "trill":
-                from nkululeko.feat_extract.feats_trill import TRILLset
-
-                self.featExtractor = TRILLset(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type.startswith("wav2vec"):
-                from nkululeko.feat_extract.feats_wav2vec2 import Wav2vec2
-
-                self.featExtractor = Wav2vec2(
-                    f"{store_name}_{self.feats_designation}",
-                    self.data_df,
-                    feats_type,
-                )
-            elif feats_type.startswith("hubert"):
-                from nkululeko.feat_extract.feats_hubert import Hubert
-
-                self.featExtractor = Hubert(
-                    f"{store_name}_{self.feats_designation}",
-                    self.data_df,
-                    feats_type,
-                )
-
-            elif feats_type.startswith("wavlm"):
-                from nkululeko.feat_extract.feats_wavlm import Wavlm
-
-                self.featExtractor = Wavlm(
-                    f"{store_name}_{self.feats_designation}",
-                    self.data_df,
-                    feats_type,
-                )
-
-            elif feats_type.startswith("spkrec"):
-                from nkululeko.feat_extract.feats_spkrec import Spkrec
-
-                self.featExtractor = Spkrec(
-                    f"{store_name}_{self.feats_designation}",
-                    self.data_df,
-                    feats_type,
-                )
-            elif feats_type == "audmodel":
-                from nkululeko.feat_extract.feats_audmodel import AudModelSet
-
-                self.featExtractor = AudModelSet(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type == "auddim":
-                from nkululeko.feat_extract.feats_audmodel_dim import (
-                    AudModelDimSet,
-                )
-
-                self.featExtractor = AudModelDimSet(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type == "agender":
-                from nkululeko.feat_extract.feats_agender import (
-                    AudModelAgenderSet,
-                )
-
-                self.featExtractor = AudModelAgenderSet(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type == "agender_agender":
-                from nkululeko.feat_extract.feats_agender_agender import (
-                    AgenderAgenderSet,
-                )
-
-                self.featExtractor = AgenderAgenderSet(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type == "snr":
-                from nkululeko.feat_extract.feats_snr import SNRSet
-
-                self.featExtractor = SNRSet(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type == "mos":
-                from nkululeko.feat_extract.feats_mos import MOSSet
-
-                self.featExtractor = MOSSet(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type == "squim":
-                from nkululeko.feat_extract.feats_squim import SQUIMSet
-
-                self.featExtractor = SQUIMSet(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type == "clap":
-                from nkululeko.feat_extract.feats_clap import Clap
-
-                self.featExtractor = Clap(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type == "praat":
-                from nkululeko.feat_extract.feats_praat import Praatset
-
-                self.featExtractor = Praatset(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type == "mld":
-                from nkululeko.feat_extract.feats_mld import MLD_set
-
-                self.featExtractor = MLD_set(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            elif feats_type == "import":
-                from nkululeko.feat_extract.feats_import import Importset
-
-                self.featExtractor = Importset(
-                    f"{store_name}_{self.feats_designation}", self.data_df
-                )
-            else:
-                self.util.error(f"unknown feats_type: {feats_type}")
-
-            self.featExtractor.extract()
-            self.featExtractor.filter()
-            # remove samples that were not extracted by MLD
-            # self.df_test = self.df_test.loc[self.df_test.index.intersection(featExtractor_test.df.index)]
-            # self.df_train = self.df_train.loc[self.df_train.index.intersection(featExtractor_train.df.index)]
-            self.util.debug(f"{feats_type}: shape : {self.featExtractor.df.shape}")
-            self.feats = pd.concat([self.feats, self.featExtractor.df], axis=1)
+            self.feat_extractor = self._get_feat_extractor(store_name, feats_type)
+            self.feat_extractor.extract()
+            self.feat_extractor.filter()
+            self.feats = pd.concat([self.feats, self.feat_extractor.df], axis=1)
         return self.feats
 
     def extract_sample(self, signal, sr):
-        return self.featExtractor.extract_sample(signal, sr)
+        return self.feat_extractor.extract_sample(signal, sr)
+
+    def _get_feat_extractor(self, store_name, feats_type):
+        feat_extractor_class = self._get_feat_extractor_class(feats_type)
+        if feat_extractor_class is None:
+            self.util.error(f"unknown feats_type: {feats_type}")
+        return feat_extractor_class(
+            f"{store_name}_{self.feats_designation}", self.data_df
+        )
+
+    def _get_feat_extractor_class(self, feats_type):
+        if feats_type == "os":
+            from nkululeko.feat_extract.feats_opensmile import Opensmileset
+
+            return Opensmileset
+        elif feats_type == "spectra":
+            from nkululeko.feat_extract.feats_spectra import Spectraloader
+
+            return Spectraloader
+        elif feats_type == "trill":
+            from nkululeko.feat_extract.feats_trill import TRILLset
+
+            return TRILLset
+        elif feats_type.startswith(("wav2vec", "hubert", "wavlm", "spkrec")):
+            return self._get_feat_extractor_by_prefix(feats_type)
+        elif feats_type in (
+            "audmodel",
+            "auddim",
+            "agender",
+            "agender_agender",
+            "snr",
+            "mos",
+            "squim",
+            "clap",
+            "praat",
+            "mld",
+            "import",
+        ):
+            return self._get_feat_extractor_by_name(feats_type)
+        else:
+            return None
+
+    def _get_feat_extractor_by_prefix(self, feats_type):
+        prefix, _, ext = feats_type.partition("_")
+        from importlib import import_module
+
+        module = import_module(f"nkululeko.feat_extract.feats_{prefix.lower()}")
+        class_name = f"{prefix.capitalize()}{ext.capitalize()}set"
+        return getattr(module, class_name)
+
+    def _get_feat_extractor_by_name(self, feats_type):
+        from importlib import import_module
+
+        module = import_module(f"nkululeko.feat_extract.feats_{feats_type.lower()}")
+        class_name = f"{feats_type.capitalize()}Set"
+        return getattr(module, class_name)