britekit 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

britekit/commands/_pickle.py

@@ -1,6 +1,7 @@
 # File name starts with _ to keep it out of typeahead for API users.
 # Defer some imports to improve --help performance.
 import logging
+import os
 from pathlib import Path
 from typing import Optional
 
@@ -27,13 +28,13 @@ def pickle(
     or specific classes specified by a CSV file.
 
     Args:
-        cfg_path (str, optional): Path to YAML file defining configuration overrides.
-        classes_path (str, optional): Path to CSV file containing class names to include.
-                                     If omitted, includes all classes in the database.
-        db_path (str, optional): Path to the training database. Defaults to cfg.train.train_db.
-        output_path (str, optional): Output pickle file path. Defaults to "data/training.pkl".
-        max_per_class (int, optional): Maximum number of spectrograms to include per class.
-        spec_group (str): Spectrogram group name to extract from. Defaults to 'default'.
+    - cfg_path (str, optional): Path to YAML file defining configuration overrides.
+    - classes_path (str, optional): Path to CSV file containing class names to include.
+        If omitted, includes all classes in the database.
+    - db_path (str, optional): Path to the training database. Defaults to cfg.train.train_db.
+    - output_path (str, optional): Output pickle file path. Defaults to "data/training.pkl".
+    - max_per_class (int, optional): Maximum number of spectrograms to include per class.
+    - spec_group (str): Spectrogram group name to extract from. Defaults to 'default'.
     """
     from britekit.core.pickler import Pickler
 
@@ -41,6 +42,11 @@ def pickle(
     if db_path is None:
         db_path = cfg.train.train_db
 
+    if classes_path is not None:
+        if not os.path.exists(classes_path):
+            logging.error(f"Error: file {classes_path} not found.")
+            return
+
     if output_path is None:
         output_path = str(Path(root_dir) / "data" / "training.pkl")
 

britekit/commands/_plot.py

@@ -76,15 +76,15 @@ def plot_db(
     number of spectrograms plotted.
 
     Args:
-        cfg_path (str, optional): Path to YAML file defining configuration overrides.
-        class_name (str): Name of the class to plot spectrograms for (e.g., "Common Yellowthroat").
-        db_path (str, optional): Path to the training database. Defaults to cfg.train.train_db.
-        ndims (bool): If True, do not show time and frequency dimensions on the spectrogram plots.
-        max_count (int, optional): Maximum number of spectrograms to plot. If omitted, plots all available.
-        output_path (str): Directory where spectrogram images will be saved.
-        prefix (str, optional): Only include recordings that start with this filename prefix.
-        power (float, optional): Raise spectrograms to this power for visualization. Lower values show more detail.
-        spec_group (str, optional): Spectrogram group name to plot from. Defaults to "default".
+    - cfg_path (str, optional): Path to YAML file defining configuration overrides.
+    - class_name (str): Name of the class to plot spectrograms for (e.g., "Common Yellowthroat").
+    - db_path (str, optional): Path to the training database. Defaults to cfg.train.train_db.
+    - ndims (bool): If True, do not show time and frequency dimensions on the spectrogram plots.
+    - max_count (int, optional): Maximum number of spectrograms to plot. If omitted, plots all available.
+    - output_path (str): Directory where spectrogram images will be saved.
+    - prefix (str, optional): Only include recordings that start with this filename prefix.
+    - power (float, optional): Raise spectrograms to this power for visualization. Lower values show more detail.
+    - spec_group (str, optional): Spectrogram group name to plot from. Defaults to "default".
     """
     from britekit.core.plot import plot_spec
     from britekit.training_db.training_db import TrainingDatabase
@@ -158,7 +158,7 @@ def plot_db(
     "--ndims",
     "ndims",
     is_flag=True,
-    help="If specified, do not show time and frequency dimensions on the spectrogram plots.",
+    help="If specified, do not show seconds on x-axis and frequencies on y-axis.",
 )
 @click.option(
     "--max",
@@ -237,13 +237,13 @@ def plot_dir(
     overlapping segments.
 
     Args:
-        cfg_path (str, optional): Path to YAML file defining configuration overrides.
-        ndims (bool): If True, do not show time and frequency dimensions on the spectrogram plots.
-        input_path (str): Directory containing audio recordings to process.
-        output_path (str): Directory where spectrogram images will be saved.
-        all (bool): If True, plot each recording as one spectrogram. If False, break into segments.
-        overlap (float): Spectrogram overlap in seconds when breaking recordings into segments. Default is 0.
-        power (float): Raise spectrograms to this power for visualization. Lower values show more detail. Default is 1.0.
+    - cfg_path (str, optional): Path to YAML file defining configuration overrides.
+    - ndims (bool): If True, do not show time and frequency dimensions on the spectrogram plots.
+    - input_path (str): Directory containing audio recordings to process.
+    - output_path (str): Directory where spectrogram images will be saved.
+    - all (bool): If True, plot each recording as one spectrogram. If False, break into segments.
+    - overlap (float): Spectrogram overlap in seconds when breaking recordings into segments. Default is 0.
+    - power (float): Raise spectrograms to this power for visualization. Lower values show more detail. Default is 1.0.
     """
     from britekit.core.audio import Audio
 
@@ -284,7 +284,7 @@ def plot_dir(
     "--ndims",
     "ndims",
     is_flag=True,
-    help="If specified, show seconds on x-axis and frequencies on y-axis.",
+    help="If specified, do not show seconds on x-axis and frequencies on y-axis.",
 )
 @click.option(
     "-i",
@@ -353,13 +353,13 @@ def plot_rec(
     overlapping segments.
 
     Args:
-        cfg_path (str, optional): Path to YAML file defining configuration overrides.
-        ndims (bool): If True, do not show time and frequency dimensions on the spectrogram plots.
-        input_path (str): Path to the audio recording file to process.
-        output_path (str): Directory where spectrogram images will be saved.
-        all (bool): If True, plot the entire recording as one spectrogram. If False, break into segments.
-        overlap (float): Spectrogram overlap in seconds when breaking the recording into segments. Default is 0.
-        power (float): Raise spectrograms to this power for visualization. Lower values show more detail. Default is 1.0.
+    - cfg_path (str, optional): Path to YAML file defining configuration overrides.
+    - ndims (bool): If True, do not show time and frequency dimensions on the spectrogram plots.
+    - input_path (str): Path to the audio recording file to process.
+    - output_path (str): Directory where spectrogram images will be saved.
+    - all (bool): If True, plot the entire recording as one spectrogram. If False, break into segments.
+    - overlap (float): Spectrogram overlap in seconds when breaking the recording into segments. Default is 0.
+    - power (float): Raise spectrograms to this power for visualization. Lower values show more detail. Default is 1.0.
     """
     from britekit.core.audio import Audio
 
@@ -394,7 +394,7 @@ def plot_rec(
     "--ndims",
     "ndims",
     is_flag=True,
-    help="If specified, show seconds on x-axis and frequencies on y-axis.",
+    help="If specified, do not show seconds on x-axis and frequencies on y-axis.",
 )
 @click.option(
     "-i",

britekit/commands/_reextract.py

@@ -30,12 +30,12 @@ def reextract(
     updating the database.
 
     Args:
-        cfg_path (str, optional): Path to YAML file defining configuration overrides.
-        db_path (str, optional): Path to the training database. Defaults to cfg.train.training_db.
-        class_name (str, optional): Name of a specific class to reextract. If omitted, processes all classes.
-        classes_path (str, optional): Path to CSV file listing classes to reextract. Alternative to class_name.
-        check (bool): If True, only check that all recording paths are accessible without updating database.
-        spec_group (str): Spectrogram group name for storing the extracted spectrograms. Defaults to 'default'.
+    - cfg_path (str, optional): Path to YAML file defining configuration overrides.
+    - db_path (str, optional): Path to the training database. Defaults to cfg.train.training_db.
+    - class_name (str, optional): Name of a specific class to reextract. If omitted, processes all classes.
+    - classes_path (str, optional): Path to CSV file listing classes to reextract. Alternative to class_name.
+    - check (bool): If True, only check that all recording paths are accessible without updating database.
+    - spec_group (str): Spectrogram group name for storing the extracted spectrograms. Defaults to 'default'.
     """
     from britekit.core.reextractor import Reextractor
     cfg = get_config(cfg_path)

britekit/commands/_reports.py

@@ -27,8 +27,8 @@ def rpt_ann(
     breakdowns.
 
     Args:
-        annotations_path (str): Path to CSV file containing per-segment annotations.
-        output_path (str): Directory where summary reports will be saved.
+    - annotations_path (str): Path to CSV file containing per-segment annotations.
+    - output_path (str): Directory where summary reports will be saved.
     """
     import pandas as pd
 
@@ -136,9 +136,9 @@ def rpt_db(cfg_path: Optional[str] = None,
     and can be used for data management and quality control.
 
     Args:
-        cfg_path (str, optional): Path to YAML file defining configuration overrides.
-        db_path (str, optional): Path to the training database. Defaults to cfg.train.train_db.
-        output_path (str): Directory where database reports will be saved.
+    - cfg_path (str, optional): Path to YAML file defining configuration overrides.
+    - db_path (str, optional): Path to the training database. Defaults to cfg.train.train_db.
+    - output_path (str): Directory where database reports will be saved.
     """
     from britekit.training_db.training_db import TrainingDatabase
     from britekit.training_db.training_data_provider import TrainingDataProvider
@@ -202,10 +202,10 @@ def rpt_epochs(
     This is useful to determine the number of training epochs needed.
 
     Args:
-        cfg_path (str, optional): Path to YAML file defining configuration overrides.
-        input_path (str): Checkpoint directory generated by training.
-        annotations_path (str): Path to CSV file containing ground truth annotations.
-        output_path (str): Directory where the graph image will be saved.
+    - cfg_path (str, optional): Path to YAML file defining configuration overrides.
+    - input_path (str): Checkpoint directory generated by training.
+    - annotations_path (str): Path to CSV file containing ground truth annotations.
+    - output_path (str): Directory where the graph image will be saved.
     """
     import matplotlib.pyplot as plt
     from matplotlib.ticker import MaxNLocator
@@ -397,9 +397,9 @@ def rpt_labels(
     across different recordings and classes.
 
     Args:
-        label_dir (str): Directory containing inference output (CSV or Audacity labels).
-        output_path (str): Directory where summary reports will be saved.
-        min_score (float, optional): Ignore detections below this confidence threshold.
+    - label_dir (str): Directory containing inference output (CSV or Audacity labels).
+    - output_path (str): Directory where summary reports will be saved.
+    - min_score (float, optional): Ignore detections below this confidence threshold.
     """
     import pandas as pd
 
@@ -544,21 +544,21 @@ def rpt_test(
     F1 scores, and various visualization plots to help understand model behavior.
 
     Args:
-        cfg_path (str, optional): Path to YAML file defining configuration overrides.
-        granularity (str): Evaluation granularity ("recording", "block", or "segment"). Default is "segment".
-        annotations_path (str): Path to CSV file containing ground truth annotations.
-        label_dir (str): Directory containing model prediction labels (Audacity format).
-        output_path (str): Directory where test reports will be saved.
-        recordings_path (str, optional): Directory containing audio recordings. Defaults to annotations directory.
-        min_score (float, optional): Provide detailed reports for this confidence threshold.
-        block_size (int, optional): block_size in seconds (default=60).
-        precision (float): For recording granularity, report true positive seconds at this precision. Default is 0.95.
+    - cfg_path (str, optional): Path to YAML file defining configuration overrides.
+    - granularity (str): Evaluation granularity ("recording", "block", or "segment"). Default is "segment".
+    - annotations_path (str): Path to CSV file containing ground truth annotations.
+    - label_dir (str): Directory containing model prediction labels (Audacity format).
+    - output_path (str): Directory where test reports will be saved.
+    - recordings_path (str, optional): Directory containing audio recordings. Defaults to annotations directory.
+    - min_score (float, optional): Provide detailed reports for this confidence threshold.
+    - block_size (int, optional): block_size in seconds (default=60).
+    - precision (float): For recording granularity, report true positive seconds at this precision. Default is 0.95.
     """
     from britekit.testing.per_block_tester import PerBlockTester
     from britekit.testing.per_recording_tester import PerRecordingTester
     from britekit.testing.per_segment_tester import PerSegmentTester
 
-    cfg = get_config()
+    cfg = get_config(cfg_path)
     try:
         if not recordings_path:
             recordings_path = str(Path(annotations_path).parent)

britekit/commands/_search.py

@@ -33,18 +33,18 @@ def search(
     based on embedding similarity. Results are plotted and saved to the output directory.
 
     Args:
-        cfg_path (str): Path to YAML configuration file defining model settings.
-        db_path (str): Path to the training database containing spectrograms to search.
-        class_name (str): Name of the class/species to search within the database.
-        max_dist (float): Maximum distance threshold. Results with distance greater than this are excluded.
-        exp (float): Exponent to raise spectrograms to for visualization (shows background sounds).
-        num_to_plot (int): Maximum number of similar spectrograms to plot and save.
-        output_path (str): Directory where search results and plots will be saved.
-        input_path (str): Path to the audio file containing the target spectrogram.
-        offset (float): Time offset in seconds where the target spectrogram is extracted.
-        exclude_db (str, optional): Path to an exclusion database. Spectrograms in this database are excluded from results.
-        class_name2 (str, optional): Class name in the exclusion database. Defaults to the search class name.
-        spec_group (str): Spectrogram group name in the database. Defaults to 'default'.
+    - cfg_path (str): Path to YAML configuration file defining model settings.
+    - db_path (str): Path to the training database containing spectrograms to search.
+    - class_name (str): Name of the class/species to search within the database.
+    - max_dist (float): Maximum distance threshold. Results with distance greater than this are excluded.
+    - exp (float): Exponent to raise spectrograms to for visualization (shows background sounds).
+    - num_to_plot (int): Maximum number of similar spectrograms to plot and save.
+    - output_path (str): Directory where search results and plots will be saved.
+    - input_path (str): Path to the audio file containing the target spectrogram.
+    - offset (float): Time offset in seconds where the target spectrogram is extracted.
+    - exclude_db (str, optional): Path to an exclusion database. Spectrograms in this database are excluded from results.
+    - class_name2 (str, optional): Class name in the exclusion database. Defaults to the search class name.
+    - spec_group (str): Spectrogram group name in the database. Defaults to 'default'.
     """
 
     class SpecInfo:

britekit/commands/_train.py

@@ -26,8 +26,8 @@ def train(
     automatically. The final trained model can be used for inference and evaluation.
 
     Args:
-        cfg_path (str, optional): Path to YAML file defining configuration overrides.
-                                 If not specified, uses default configuration.
+    - cfg_path (str, optional): Path to YAML file defining configuration overrides.
+        If not specified, uses default configuration.
     """
     from britekit.core.trainer import Trainer
 
@@ -82,10 +82,10 @@ def find_lr(cfg_path: str, num_batches: int):
     avoiding rates that are too high (causing instability) or too low (slow convergence).
 
     Args:
-        cfg_path (str, optional): Path to YAML file defining configuration overrides.
-                                 If not specified, uses default configuration.
-        num_batches (int): Number of training batches to analyze for learning rate finding.
-                          Default is 100. Higher values provide more accurate results but take longer.
+    - cfg_path (str, optional): Path to YAML file defining configuration overrides.
+        If not specified, uses default configuration.
+    - num_batches (int): Number of training batches to analyze for learning rate finding.
+        Default is 100. Higher values provide more accurate results but take longer.
     """
     from britekit.core.trainer import Trainer
 

britekit/commands/_tune.py

@@ -41,18 +41,18 @@ def tune(
     The param_path specifies a YAML file that defines the parameters to be tuned, as described in the README.
 
     Args:
-        cfg_path (str, optional): Path to YAML file defining configuration overrides.
-        param_path (str, optional): Path to YAML file defining hyperparameters to tune and their search space.
-        output_path (str): Directory where reports will be saved.
-        annotations_path (str): Path to CSV file containing ground truth annotations.
-        metric (str): Metric used to compare runs. Options include various MAP and ROC metrics.
-        recordings_path (str, optional): Directory containing audio recordings. Defaults to annotations directory.
-        train_log_path (str, optional): Training log directory. Defaults to "logs/fold-0".
-        num_trials (int): Number of random trials to run. If 0, performs exhaustive search.
-        num_runs (int): Number of runs to average for each parameter combination. Default is 1.
-        extract (bool): Extract new spectrograms before training, to tune spectrogram parameters.
-        skip_training (bool): Iterate on inference only, using checkpoints from the last training run.
-        classes_path (str, optional): Path to CSV containing class names for extract option. Default is all classes.
+    - cfg_path (str, optional): Path to YAML file defining configuration overrides.
+    - param_path (str, optional): Path to YAML file defining hyperparameters to tune and their search space.
+    - output_path (str): Directory where reports will be saved.
+    - annotations_path (str): Path to CSV file containing ground truth annotations.
+    - metric (str): Metric used to compare runs. Options include various MAP and ROC metrics.
+    - recordings_path (str, optional): Directory containing audio recordings. Defaults to annotations directory.
+    - train_log_path (str, optional): Training log directory. Defaults to "logs".
+    - num_trials (int): Number of random trials to run. If 0, performs exhaustive search.
+    - num_runs (int): Number of runs to average for each parameter combination. Default is 1.
+    - extract (bool): Extract new spectrograms before training, to tune spectrogram parameters.
+    - skip_training (bool): Iterate on inference only, using checkpoints from the last training run.
+    - classes_path (str, optional): Path to CSV containing class names for extract option. Default is all classes.
     """
     import yaml
     from britekit.core.tuner import Tuner
@@ -72,7 +72,7 @@ def tune(
             recordings_path = str(Path(annotations_path).parent)
 
         if not train_log_path:
-            train_log_path = str(Path("logs") / "fold-0")
+            train_log_path = "logs"
 
         if param_path is not None:
             with open(param_path) as input_file:

britekit/commands/_wav2mp3.py

@@ -24,8 +24,8 @@ def wav2mp3(
     requirements for large audio datasets.
 
     Args:
-        dir (str): Path to directory containing audio files to convert.
-        sampling_rate (int): Output sampling rate in Hz. Default is 32000 Hz.
+    - dir (str): Path to directory containing audio files to convert.
+    - sampling_rate (int): Output sampling rate in Hz. Default is 32000 Hz.
     """
     CONVERT_TYPES = {
         ".flac",

britekit/commands/_xeno.py

@@ -75,13 +75,13 @@ def xeno(
     Then specify the key in the --key argument, or set the environment variable XCKEY=<key>.
 
     Args:
-        key (str): Xeno-Canto API key for authentication. Can also be set via XCKEY environment variable.
-        output_dir (str): Directory where downloaded recordings will be saved.
-        max_downloads (int): Maximum number of recordings to download. Default is 500.
-        name (str): Species name to search for (common name or scientific name).
-        ignore_licence (bool): If True, ignore license restrictions. By default, excludes BY-NC-ND licensed recordings.
-        scientific_name (bool): If True, treat the name as a scientific name rather than common name.
-        seen_only (bool): If True, only download recordings where the animal was seen (animal-seen=yes).
+    - key (str): Xeno-Canto API key for authentication. Can also be set via XCKEY environment variable.
+    - output_dir (str): Directory where downloaded recordings will be saved.
+    - max_downloads (int): Maximum number of recordings to download. Default is 500.
+    - name (str): Species name to search for (common name or scientific name).
+    - ignore_licence (bool): If True, ignore license restrictions. By default, excludes BY-NC-ND licensed recordings.
+    - scientific_name (bool): If True, treat the name as a scientific name rather than common name.
+    - seen_only (bool): If True, only download recordings where the animal was seen (animal-seen=yes).
     """
     import requests
 

britekit/commands/_youtube.py

@@ -17,9 +17,9 @@ def youtube(
     Download an audio recording from Youtube, given a Youtube ID.
 
     Args:
-        id (str): ID of the clip to download.
-        output_dir (str): Directory where downloaded recordings will be saved.
-        sampling_rate (float): Output sampling rate in Hz. Default is 32000.
+    - id (str): ID of the clip to download.
+    - output_dir (str): Directory where downloaded recordings will be saved.
+    - sampling_rate (float): Output sampling rate in Hz. Default is 32000.
     """
     import librosa
     import numpy as np

britekit/core/analyzer.py

@@ -56,21 +56,29 @@ class Analyzer:
         with open(Path(output_path) / "manifest.yaml", "w") as out_file:
             out_file.write(info_str)
 
-    def _process_recordings(self, recording_paths, output_path, rtype, thread_num):
+    def _process_recordings(
+        self, recording_paths, output_path, rtype, start_seconds, thread_num, debug_mode=False
+    ):
         """
         This runs on its own thread and processes all recordings in the given list.
 
         Args:
-            recording_paths (list): Individual recording paths.
-            output_path (str): Where to write the output.
-            rtype (str): Output format: "audacity", "csv" or "both".
+        - recording_paths (list): Individual recording paths.
+        - output_path (str): Where to write the output.
+        - rtype (str): Output format: "audacity", "csv" or "both".
+        - start_seconds (float): Where to start processing each recording, in seconds from start.
         """
         from britekit.core.predictor import Predictor
 
         predictor = Predictor(self.cfg.misc.ckpt_folder)
         for recording_path in recording_paths:
             logging.info(f"[Thread {thread_num}] Processing {recording_path}")
-            scores, frame_map, offsets = predictor.get_raw_scores(recording_path)
+            scores, frame_map, offsets = predictor.get_raw_scores(
+                recording_path, start_seconds
+            )
+            if debug_mode:
+                predictor.log_scores(scores)  # log the scores for debugging
+
             recording_name = Path(recording_path).stem
             if rtype in {"audacity", "both"}:
                 file_path = str(Path(output_path) / f"{recording_name}_scores.txt")
@@ -82,6 +90,9 @@ class Analyzer:
                 )
                 self.dataframes.append(dataframe)
 
+            if debug_mode:
+                break
+
         if thread_num == 1:
             self._save_manifest(output_path, predictor)
 
@@ -91,8 +102,8 @@ class Analyzer:
         Split the input list into `n` lists based on index modulo `n`.
 
         Args:
-            input_list (list): The input list to split.
-            n (int): Number of resulting groups.
+        - input_list (list): The input list to split.
+        - n (int): Number of resulting groups.
 
         Returns:
             List[List]: A list of `n` lists, where each sublist contains elements
@@ -103,14 +114,24 @@ class Analyzer:
             result[i % n].append(item)
         return result
 
-    def run(self, input_path: str, output_path: str, rtype: str = "audacity"):
+    def run(
+        self,
+        input_path: str,
+        output_path: str,
+        rtype: str = "audacity",
+        start_seconds: float = 0,
+        debug_mode: bool = False
+    ):
         """
         Run inference.
 
         Args:
-            input_path (str): Recording or directory containing recordings.
-            output_path (str): Output directory.
-            rtype (str): Output format: "audacity", "csv" or "both".
+        - input_path (str): Recording or directory containing recordings.
+        - output_path (str): Output directory.
+        - rtype (str): Output format: "audacity", "csv" or "both".
+        - start_seconds (float): Where to start processing each recording, in seconds.
+        - debug_mode (bool): If true, log scores for the first spectrogram, then stop.
+        For example, '71' and '1:11' have the same meaning, and cause the first 71 seconds to be ignored. Default = 0.
         """
         import pandas as pd
 
@@ -127,14 +148,23 @@ class Analyzer:
         self.dataframes = []
         num_threads = min(self.cfg.infer.num_threads, len(recording_paths))
         if num_threads == 1:
-            self._process_recordings(recording_paths, output_path, rtype, 1)
+            self._process_recordings(
+                recording_paths, output_path, rtype, start_seconds, 1, debug_mode,
+            )
         else:
             recordings_per_thread = self._split_list(recording_paths, num_threads)
             threads = []
             for i in range(num_threads):
                 thread = threading.Thread(
                     target=self._process_recordings,
-                    args=(recordings_per_thread[i], output_path, rtype, i + 1),
+                    args=(
+                        recordings_per_thread[i],
+                        output_path,
+                        rtype,
+                        start_seconds,
+                        i + 1,
+                        debug_mode,
+                    ),
                 )
                 thread.start()
                 threads.append(thread)

britekit/core/audio.py

@@ -46,7 +46,7 @@ class Audio:
         so we downsample rather than upsampling.
 
         Args:
-            cfg (Optional[BaseConfig]): Configuration object. If None, uses default config.
+        - cfg (Optional[BaseConfig]): Configuration object. If None, uses default config.
         """
         import torchaudio as ta
 
@@ -113,7 +113,7 @@ class Audio:
         if choose_channel is enabled in the configuration.
 
         Args:
-            path (str): Path to the audio recording file.
+        - path (str): Path to the audio recording file.
 
         Returns:
             tuple: (signal, sampling_rate) where:
@@ -168,18 +168,18 @@ class Audio:
         Returns both normalized (0-1 range) and unnormalized versions of the spectrograms.
 
         Args:
-            start_times (list[float]): List of start times in seconds from the beginning
-                of the recording for each spectrogram.
-            spec_duration (Optional[float]): Length of each spectrogram in seconds.
-                Defaults to cfg.audio.spec_duration.
-            freq_scale (Optional[str]): Frequency scale to use ('linear', 'log', 'mel').
-                Defaults to cfg.audio.freq_scale.
-            decibels (Optional[float]): Whether to convert to decibels.
-                Defaults to cfg.audio.decibels.
-            top_db (Optional[int]): Maximum decibel value for normalization.
-                Defaults to cfg.audio.top_db.
-            db_power (Optional[int]): Power to apply after decibel conversion.
-                Defaults to cfg.audio.db_power.
+        - start_times (list[float]): List of start times in seconds from the beginning
+            of the recording for each spectrogram.
+        - spec_duration (Optional[float]): Length of each spectrogram in seconds.
+            Defaults to cfg.audio.spec_duration.
+        - freq_scale (Optional[str]): Frequency scale to use ('linear', 'log', 'mel').
+            Defaults to cfg.audio.freq_scale.
+        - decibels (Optional[float]): Whether to convert to decibels.
+            Defaults to cfg.audio.decibels.
+        - top_db (Optional[int]): Maximum decibel value for normalization.
+            Defaults to cfg.audio.top_db.
+        - db_power (Optional[int]): Power to apply after decibel conversion.
+            Defaults to cfg.audio.db_power.
 
         Returns:
             tuple: (normalized_specs, unnormalized_specs) where:

britekit/core/augmentation.py

@@ -1,10 +1,14 @@
 # Defer some imports to improve initialization performance.
+import ctypes
 from functools import partial
+import logging
+from multiprocessing import Value
 import random
 
 from britekit.core.base_config import BaseConfig
 
 AUGMENTATION_REGISTRY = {}
+_have_real_noise = Value(ctypes.c_bool, True)
 
 
 def register_augmentation(name):
@@ -60,7 +64,27 @@ class AugmentationPipeline:
         """
         Add an actual noise spectrogram but, unlike mixup, do not update the label.
         """
+        global _have_real_noise
+        if not _have_real_noise.value:
+            return spec
+
         noise_spec = self.dataset.get_random_noise()
+        if noise_spec is None:
+            # with multiple workers, only do this once
+            with _have_real_noise.get_lock():
+                if _have_real_noise.value:
+                    _have_real_noise.value = False
+                    logging.error("")
+                    logging.error("*** WARNING:")
+                    logging.error(
+                        "No noise class is defined, but add_real_noise is enabled."
+                    )
+                    logging.error("In most cases it is best to provide noise data.")
+                    logging.error(
+                        "The add_real_noise augmentation will be disabled in this run."
+                    )
+                    logging.error("")
+            return spec
 
         # Validate shapes match
         if noise_spec.shape != spec.shape:

britekit/core/data_module.py

@@ -124,7 +124,7 @@ class DataModule(LightningDataModule):
         Load data from a pickle file with error handling.
 
         Args:
-            path (str): Path to the pickle file
+        - path (str): Path to the pickle file
 
         Returns:
             Tuple containing (class_names, class_codes, alt_names, alt_codes, specs, labels)
@@ -175,7 +175,7 @@ class DataModule(LightningDataModule):
         Prepare train/validation split for a specific fold.
 
         Args:
-            fold_index (int): Index of the fold to prepare
+        - fold_index (int): Index of the fold to prepare
 
         Raises:
             ValueError: If fold_index is invalid or val_portion is invalid

britekit/core/dataset.py

@@ -5,7 +5,6 @@ from torch.utils.data import Dataset
 from typing import Any, Callable, List, Optional
 
 from britekit.core.augmentation import AugmentationPipeline
-from britekit.core.exceptions import TrainingError
 from britekit.core.config_loader import get_config
 from britekit.core.util import expand_spectrogram
 
@@ -115,9 +114,7 @@ class SpectrogramDataset(Dataset):
         Return a random noise spec from the training data
         """
         if not self.noise_indexes:
-            raise TrainingError(
-                "Attempt to use noise during augmentation when none defined"
-            )
+            return None
 
         idx = random.randint(0, len(self.noise_indexes) - 1)
         return self._get_spec(self.noise_indexes[idx])