sonusai 0.18.9__py3-none-any.whl → 0.19.5__py3-none-any.whl

sonusai/doc/doc.py

@@ -3,22 +3,27 @@ from sonusai.mixture import get_default_config
 
 def doc_seed() -> str:
     default = f"\nDefault value: {get_default_config()['seed']}"
+    # fmt: off
     return """
 'seed' is a mixture database configuration parameter that sets the random number
 generator seed.
 """ + default
+    # fmt: on
 
 
 def doc_feature() -> str:
     default = f"\nDefault value: {get_default_config()['feature']}"
+    # fmt: off
     return """
 'feature' is a mixture database configuration parameter that sets the feature
 to use.
 """ + default
+    # fmt: on
 
 
 def doc_target_level_type() -> str:
     default = f"\nDefault value: {get_default_config()['target_level_type']}"
+    # fmt: off
     return """
 'target_level_type' is a mixture database configuration parameter that sets the
 algorithm to use to determine target energy level for SNR calculations.
@@ -27,10 +32,12 @@ Supported values are:
  default    mean of squares
  speech     ITU-T P.56 active speech level method B
 """ + default
+    # fmt: on
 
 
 def doc_targets() -> str:
     default = f"\nDefault value: {get_default_config()['targets']}"
+    # fmt: off
     return """
 'targets' is a mixture database configuration parameter that sets the list of
 targets to use.
@@ -48,46 +55,11 @@ Required field:
 
 Optional fields:
 
- 'truth_settings'
-                Local overrides for truth. Contains any or all of the
-                following:
-
-  'function'    Name of truth function <str>
-  'config'      Truth function config <dict>
-  'index'       Truth index <int> or list(<int>)
-
-                'index' indicates which truth fields should be set.
-                0 indicates none, 1 is first element in truth output
-                vector, 2 2nd element, etc.
-
-                Examples:
-                  index = 5       truth in class 5, truth(4, 1)
-                  index = [1, 5]  truth in classes 1 and 5, truth([0, 4], 1)
-
-                In mutually-exclusive mode, a frame is expected to only
-                belong to one class and thus all probabilities must sum to
-                1, and there should be a class for "other" or "none". This
-                is effectively truth for a classifier with multichannel
-                softmax output. SonusAI will automatically calculate class
-                num_classes as 1 - sum(truth(1:num_classes-1). For
-                example, a classifier for (dog, cat) must have
-                num_classes=3 to include "none" in truth(3).
-
-                For multi-label classification each class is an individual
-                probability for that class and any given frame can be
-                assigned to multiple classes/labels, i.e., the classes are
-                not mutually-exclusive. For example, a NN classifier with
-                multichannel sigmoid output. In this case, index could
-                also be a vector with multiple class indices. num_classes
-                should be set to the number of classes/categories.
-
-  'class_balancing_augmentation'
-                Target-specific class balancing augmentation override.
-                This target will not use the global class balancing
-                augmentation rule, but will use this rule instead for
-                class balancing operations. If this rule is specified and
-                empty, then this target will not be used for class
-                balancing.
+ 'truth_configs'
+                Local overrides for truth configs. Contains the following:
+  'name'        Name of truth config
+    '<param1>'  Target-specific override for truth configuration parameter
+    '<param2>'  Target-specific override for truth configuration parameter
 
   'target_level_type'
                 Target-specific override for target_level_type.
@@ -96,23 +68,23 @@ Example:
 
 targets:
   - name: data/esc50/ESC-50-master/audio/1-*.wav
-    truth_settings:
-      function: sed
-      config:
+    truth_configs:
+      sed:
         thresholds: [-38, -41, -48]
-      index: 2
+        index: 2
+        class_balancing_augmentation: { }
   - name: target.mp3
-    truth_settings:
-      function: sed
-      config:
-        thresholds: [-38, -41, -48]
-      index: 5
-    class_balancing_augmentation: { }
+    truth_configs:
+      sed:
+        thresholds: [-37, -40, -46]
+        index: 5
 """ + default
+    # fmt: on
 
 
 def doc_num_classes() -> str:
     default = f"\nDefault value: {get_default_config()['num_classes']}"
+    # fmt: off
     return """
 'num_classes' is a mixture database configuration parameter that sets the number of
 classes in this dataset. The number of classes is the total number of parameters
@@ -123,69 +95,38 @@ Note that the model output 'parameters' dimension is NOT necessarily the same si
 as the truth 'num_classes' dimension; there may be multiple truth functions combined
 in the truth, e.g., for use in loss function calculations.
 """ + default
+    # fmt: on
 
 
 def doc_class_labels() -> str:
     default = f"\nDefault value: {get_default_config()['class_labels']}"
+    # fmt: off
     return """
 'class_labels' is a mixture database configuration parameter that sets class labels
 in this dataset.
 """ + default
+    # fmt: on
 
 
-def doc_class_weights_threshold() -> str:
-    default = f"\nDefault value: {get_default_config()['class_weights_threshold']}"
-    return """
-'class_weights_threshold' is a mixture database configuration parameter that sets
-the threshold for class weights calculation to quantize truth to binary for counting.
-
-Supports scalar or list:
-
- scalar     use for all classes
- list       must be of num_classes length
-""" + default
-
-
-def doc_truth_mode() -> str:
-    default = f"\nDefault value: {get_default_config()['truth_mode']}"
-    return """
-'truth_mode' is a mixture database configuration parameter that sets the truth output
-mode.
-
-Supported values:
-
- normal     multi-label (no automatic calculation of other class)
-            Set 'num_classes' to the actual number of classification categories.
-
- mutex      mutually-exclusive
-            Set 'num_classes' to the actual number of classification categories plus 1
-            to include a "none" category which will be set to 1 - truth (where truth is
-            active for only one label) for all frames, to guarantee that the sum of all
-            truth outputs is equal to 1. This is required to support softmax()
-            neural-net outputs for multi-class classification (single label case).
-""" + default
-
-
-def doc_truth_reduction_function() -> str:
-    default = f"\nDefault value: {get_default_config()['truth_reduction_function']}"
-    return """
-'truth_reduction_function' is a mixture database configuration parameter that set the
-truth reduction function. It is used during feature generation to reduce sample-based
-truth down to transform frame-based truth. The feature generator further reduces this
-down to feature frame-based truth (based on stride and decimation).
-
-Supported values:
-
- max        Returns the max value in a transform frame
- mean       Returns the mean of a transform frame
- index0     Returns the first value in a transform frame
-""" + default
+# def doc_class_weights_threshold() -> str:
+#     default = f"\nDefault value: {get_default_config()['class_weights_threshold']}"
+#     # fmt: off
+#     return """
+# 'class_weights_threshold' is a mixture database configuration parameter that sets
+# the threshold for class weights calculation to quantize truth to binary for counting.
+#
+# Supports scalar or list:
+#
+#  scalar     use for all classes
+#  list       must be of num_classes length
+# """ + default
+#     # fmt: on
 
 
 def get_truth_functions() -> str:
     from sonusai.mixture import truth_functions
 
-    functions = [function for function in dir(truth_functions) if not function.startswith('__')]
+    functions = [function for function in dir(truth_functions) if not function.startswith("__")]
     text = "\nSupported truth functions:\n\n"
     for function in functions:
         docs = getattr(truth_functions, function).__doc__
@@ -196,65 +137,67 @@ def get_truth_functions() -> str:
     return text
 
 
-def doc_truth_settings() -> str:
+def doc_truth_configs() -> str:
     import yaml
 
-    default = f"\nDefault value:\n\n{yaml.dump(get_default_config()['truth_settings'])}"
+    default = f"\nDefault value:\n\n{yaml.dump(get_default_config()['truth_configs'])}"
+    # fmt: off
     return """
-'truth_settings' is a mixture database configuration parameter that sets the truth
-generation settings for targets. There is a global 'truth_settings' and there may be
-target-specific 'truth_settings'.
+'truth_configs' is a mixture database configuration parameter that sets the truth
+generation configurations for targets. There is a global 'truth_configs' and there may be
+target-specific 'truth_configs'.
 
-A truth setting creates a type of truth and is associated with target file(s).
+A truth config creates a type of truth and is associated with target file(s).
 Target files may have multiple truth settings.
-Truth may be non-temporal, per sample, or per feature frame and each value may be scalar
-or vector.
+
+Truth is always generated per transform frame.
 
 Note that there is a difference between transform frames and feature frames: a feature
-frame can potentially have a stride dimension (which aggregates multiple transform
-frames in a single feature).
+frame may be decimated and may have a stride dimension greater than 1 (which aggregates
+multiple transform frames in a single feature).
 
 There are two notions of truth data: truth_t and truth_f. truth_t is what the truth
-functions always generate and it is in the time domain. truth_f, or truth in the feature
-domain, is created from truth_t in the following manner. First, the
-'truth_reduction_function' specified by the config reduces truth_t into truth data in
-the transform frame domain. Then, this transform frame domain truth data is passed
-into the feature generator which produces feature frame domain truth data. 
-
-The 'truth_settings' parameter specifies the following:
-
- 'function'     Name of truth function
- 'config'       Truth function specific config dictionary
- 'index'        Truth index is either a single int or a list of ints
-
-                'index' indicates which truth fields should be set.
-                0 indicates none, 1 is the first element in the truth output
-                vector, 2 is the 2nd element, etc.
-
-                Examples:
-                  index = 5       truth in class 5, truth(4, 1)
-                  index = [1, 5]  truth in classes 1 and 5, truth([0, 4], 1)
-
-                In mutually-exclusive mode, a frame is expected to only
-                belong to one class and thus all probabilities must sum to
-                1, and there should be a class for "other" or "none". This
-                is effectively truth for a classifier with multichannel
-                softmax output. SonusAI will automatically calculate class
-                num_classes as 1 - sum(truth(1:num_classes-1). For
-                example, a classifier for (dog, cat) must have
-                num_classes=3 to include "none" in truth(3).
-
-                For multi-label classification each class is an individual
-                probability for that class and any given frame can be
-                assigned to multiple classes/labels, i.e., the classes are
-                not mutually-exclusive. For example, a NN classifier with
-                multichannel sigmoid output. In this case, index could
-                also be a vector with multiple class indices. num_classes
-                should be set to the number of classes/categories.
+functions always generate and is in the transform frame domain [transform_frames, truth_parameters].
+truth_f, or truth in the feature domain, is created by passing truth_t into the feature
+generator which produces feature frame domain truth data [feature_frames, stride or 1, truth_parameters].
+
+The stride dimension may be reduced using the 'stride_reduction' parameter. Supported stride
+reduction methods:
+    'none'      preserve the stride dimension with no change
+    'max'       reduce the stride dimension to 1 by taking the max
+    'mean'      reduce the stride dimension to 1 by taking the mean
+    'first'     reduce the stride dimension to 1 by taking the value in the first stride index
+
+The 'truth_configs' parameter specifies the following:
+
+  'name'        Name of truth configuration
+    'function'  Name of truth function to use
+    'stride_reduction'
+                Name of stride reduction method to use
+    '<param1>'  Function-specific configuration parameter
+    '<paramN>'  Function-specific configuration parameter
+    'class_balancing_augmentation'
+                Class balancing augmentation.
+                This truth configuration will use this rule for class balancing operations.
+                If this rule is empty or unspecified, then this truth function will not
+                perform class balancing.
+
+                Class balancing ensures that each class in a sound classification dataset
+                is represented equally (i.e., each class has the same number of augmented
+                targets). This is achieved by creating new class balancing augmentation
+                rules and applying them to targets in underrepresented classes to create
+                more augmented targets for those classes.
+
+                This rule must contain at least one random entry in order to guarantee
+                unique additional data.
+
+                See 'augmentations' for details on augmentation rules.
 """ + get_truth_functions() + default
+    # fmt: on
 
 
 def doc_augmentations() -> str:
+    # fmt: off
     return """
 Augmentation Rules
 
@@ -369,50 +312,26 @@ This rule expands to 6 unique augmentations being applied to each target
   tempo: 0.9, eq1: ["rand(100, 7500)", 0.8, 10]
   tempo: 1.0, eq1: ["rand(100, 7500)", 0.8, 10]
   tempo: 1.1, eq1: ["rand(100, 7500)", 0.8, 10]"""
+    # fmt: on
 
 
 def doc_target_augmentations() -> str:
     import yaml
 
     default = f"\nDefault value:\n\n{yaml.dump(get_default_config()['target_augmentations'])}"
+    # fmt: off
     return """
 'target_augmentations' is a mixture database configuration parameter that
 specifies a list of augmentation rules to use for each target.
 
 See 'augmentations' for details on augmentation rules.
 """ + default
-
-
-def doc_class_balancing_augmentation() -> str:
-    import yaml
-
-    default = f"\nDefault value:\n\n{yaml.dump(get_default_config()['class_balancing_augmentation'])}"
-    return """
-'class_balancing_augmentation' is a mixture database configuration parameter
-that sets the default augmentation rule to use for generating class balancing
-target data. This rule must contain at least one random entry in order to
-guarantee unique additional data.
-
-See 'augmentations' for details on augmentation rules.
-""" + default
-
-
-def doc_class_balancing() -> str:
-    default = f"\nDefault value: {get_default_config()['class_balancing']}"
-    return """
-'class_balancing' is a mixture database configuration parameter that
-enables/disables class balancing.
-
-Class balancing ensures that each class in a sound classification dataset is
-represented equally (i.e., each class has the same number of augmented targets).
-This is achieved by creating new class balancing augmentation rules and applying
-them to targets in underrepresented classes to create more augmented targets
-for those classes.
-""" + default
+    # fmt: on
 
 
 def doc_noises() -> str:
     default = f"\nDefault value: {get_default_config()['class_balancing']}"
+    # fmt: off
     return """
 'noises' is a mixture database configuration parameter that sets the list of
 noises to use.
@@ -428,22 +347,27 @@ Required field:
    .txt         Each line in the given text file indicates an item which
                 may be anything in this list (audio, glob, .yml, or .txt)
 """ + default
+    # fmt: on
 
 
 def doc_noise_augmentations() -> str:
     import yaml
 
     default = f"\nDefault value:\n\n{yaml.dump(get_default_config()['noise_augmentations'])}"
+
+    # fmt: off
     return """
 'noise_augmentations' is a mixture database configuration parameter that
 specifies a list of augmentation rules to use for each noise.
 
 See 'augmentations' for details on augmentation rules.
 """ + default
+    # fmt: on
 
 
 def doc_snrs() -> str:
     default = f"\nDefault value: {get_default_config()['snrs']}"
+    # fmt: off
     return """
 'snrs' is a mixture database configuration parameter that specifies a list
 of required signal-to-noise ratios (in dB).
@@ -457,10 +381,12 @@ Special values:
  -99    Noise only mixture (no target)
  99     Target only mixture (no noise)
 """ + default
+    # fmt: on
 
 
 def doc_random_snrs() -> str:
     default = f"\nDefault value: {get_default_config()['random_snrs']}"
+    # fmt: off
     return """
 'random_snrs' is a mixture database configuration parameter that specifies a
 list of random signal-to-noise ratios. The value(s) must be specified as
@@ -473,10 +399,12 @@ to achieve the desired SNR. However, unlike ordered SNRs, the desired SNR is
 randomized (per the given rule(s)) for each mixture, i.e., previous random
 SNRs are not saved and reused.
 """ + default
+    # fmt: on
 
 
 def doc_noise_mix_mode() -> str:
     default = f"\nDefault value: {get_default_config()['noise_mix_mode']}"
+    # fmt: off
     return """
 'noise_mix_mode' is a mixture database configuration parameter that sets
 how to mix noises with targets.
@@ -492,20 +420,24 @@ Supported modes:
                      and loops back to the beginning if the end of a
                      noise/augmentation is reached.
 """ + default
+    # fmt: on
 
 
 def doc_impulse_responses() -> str:
     default = f"\nDefault value: {get_default_config()['impulse_responses']}"
+    # fmt: off
     return """
 'impulse_responses' is a mixture database configuration parameter that specifies a
 list of impulse response files to use.
 
 See 'augmentations' for details.
 """ + default
+    # fmt: on
 
 
 def doc_spectral_masks() -> str:
     default = f"\nDefault value: {get_default_config()['spectral_masks']}"
+    # fmt: off
     return """
 'spectral_masks' is a mixture database configuration parameter that specifies
 a list of spectral mask rules.
@@ -521,16 +453,17 @@ Rules must specify all the following parameters:
  't_num'            Number of time masks to apply (set to 0 to apply none)
  't_max_percent'    Upper bound on the width of the time mask in percent
 """ + default
+    # fmt: on
 
 
 def doc_config() -> str:
     from sonusai.mixture import VALID_CONFIGS
 
-    text = '\n'
-    text += 'The SonusAI database is defined using a config.yml file.\n\n'
-    text += 'See the following for details:\n\n'
+    text = "\n"
+    text += "The SonusAI database is defined using a config.yml file.\n\n"
+    text += "See the following for details:\n\n"
     for c in VALID_CONFIGS:
-        text += f' {c}\n'
+        text += f" {c}\n"
     return text
 
 
@@ -539,6 +472,7 @@ def doc_asr_configs() -> str:
 
     default = f"\nDefault value: {get_default_config()['asr_configs']}"
     engines = get_available_engines()
+    # fmt: off
     text = """
 'asr_configs' is a mixture database configuration parameter that sets the list of
 ASR engine(s) to use.
@@ -548,7 +482,7 @@ Required fields:
  'name'         Unique identifier for the ASR engine.
  'engine'       ASR engine to use. Available engines:
 """
-    text += f'                {", ".join(engines)}\n'
+    text += f"                {', '.join(engines)}\n"
     text += """
 Optional fields:
 
@@ -576,4 +510,5 @@ asr_configs:
 
 Creates two ASR engines for use named faster_tiny_cuda and google.
 """
+    # fmt: on
     return text + default

sonusai/doc.py

@@ -20,26 +20,26 @@ def main() -> None:
 
     from sonusai import doc
 
-    topic = args['TOPIC']
+    topic = args["TOPIC"]
 
-    print(f'SonusAI {sonusai.__version__} Documentation')
-    print('')
+    print(f"SonusAI {sonusai.__version__} Documentation")
+    print("")
 
-    topics = sorted([item[4:] for item in dir(doc) if item.startswith('doc_')])
+    topics = sorted([item[4:] for item in dir(doc) if item.startswith("doc_")])
 
     if topic not in topics:
         if topic is not None:
-            print(f'Unknown topic: {topic}')
-            print('')
+            print(f"Unknown topic: {topic}")
+            print("")
 
-        print('Available topics:')
+        print("Available topics:")
         for item in topics:
-            print(f'  {item}')
+            print(f"  {item}")
         return
 
-    text = getattr(doc, 'doc_' + topic)()
+    text = getattr(doc, "doc_" + topic)()
     print(text[1:])
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()