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

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])

britekit/core/plot.py

@@ -16,14 +16,14 @@ def plot_spec(
     Plot and save a spectrogram image.
 
     Args:
-        spec (np.ndarray): Spectrogram of shape (height, width)
-        output_path (str): Path to save the image (e.g., "output.png")
-        show_dims (bool): Whether to show frequency and time scales
-        spec_duration (float, optional): Number of seconds represented.
-        height (int, optional): Output image height in pixels. If not specified,
-            the existing square behavior is preserved.
-        width (int, optional): Output image width in pixels. If not specified,
-            the existing square behavior is preserved.
+    - spec (np.ndarray): Spectrogram of shape (height, width)
+    - output_path (str): Path to save the image (e.g., "output.png")
+    - show_dims (bool): Whether to show frequency and time scales
+    - spec_duration (float, optional): Number of seconds represented.
+    - height (int, optional): Output image height in pixels. If not specified,
+        the existing square behavior is preserved.
+    - width (int, optional): Output image width in pixels. If not specified,
+        the existing square behavior is preserved.
     """
     import matplotlib.pyplot as plt
     import numpy as np

britekit/core/predictor.py

@@ -1,10 +1,13 @@
 # Defer some imports to improve initialization performance.
+from copy import deepcopy
 import importlib.util
 import logging
 import math
 import os
 from typing import Sequence, Optional, List
 
+import numpy as np
+
 from britekit.core.config_loader import get_config
 from britekit.core.exceptions import InferenceError
 from britekit.core import util
@@ -30,10 +33,10 @@ class Predictor:
         Initialize the Predictor with a model or ensemble of models.
 
         Args:
-            model_path (str): Path to a checkpoint (.ckpt) or ONNX (.onnx) file,
-                or a directory containing multiple checkpoint/ONNX files for an ensemble.
-            device (str, optional): Device to use for inference ('cuda', 'cpu', or 'mps').
-                If None, automatically selects the best available device.
+        - model_path (str): Path to a checkpoint (.ckpt) or ONNX (.onnx) file,
+            or a directory containing multiple checkpoint/ONNX files for an ensemble.
+        - device (str, optional): Device to use for inference ('cuda', 'cpu', or 'mps').
+            If None, automatically selects the best available device.
         """
         from britekit.core.audio import Audio
 
@@ -62,12 +65,13 @@ class Predictor:
 
         self._load_models(model_path)
 
-    def get_raw_scores(self, recording_path: str):
+    def get_raw_scores(self, recording_path: str, start_seconds: float = 0):
         """
         Get scores in array format from the loaded models for the given recording.
 
         Args:
-            recording_path (str): Path to the audio recording file.
+        - recording_path (str): Path to the audio recording file.
+        - start_seconds (float): Where to start processing the recording, in seconds from the start.
 
         Returns:
             tuple: A tuple containing:
@@ -94,7 +98,7 @@ class Predictor:
 
         increment = max(0.5, self.cfg.audio.spec_duration - self.cfg.infer.overlap)
         end_offset = max(increment, audio_duration - increment)
-        start_times = util.get_range(0, end_offset, increment)
+        start_times = util.get_range(start_seconds, end_offset, increment)
         specs, _ = self.audio.get_spectrograms(start_times)
         if specs is None or len(specs) == 0:
             return None, None, []
@@ -139,8 +143,8 @@ class Predictor:
         Given an array of raw segment-level scores, return dict of labels.
 
         Args:
-            scores (np.ndarray): Array of scores of shape (num_spectrograms, num_species).
-            start_times (list[float]): Start time in seconds for each spectrogram.
+        - scores (np.ndarray): Array of scores of shape (num_spectrograms, num_species).
+        - start_times (list[float]): Start time in seconds for each spectrogram.
 
         Returns:
             dict[str, list]: Dictionary mapping species names to lists of Label objects.
@@ -187,7 +191,7 @@ class Predictor:
         Given a frame map, return dict of labels.
 
         Args:
-            frame_map (np.ndarray): Array of scores of shape (num_frames, num_species).
+        - frame_map (np.ndarray): Array of scores of shape (num_frames, num_species).
 
         Returns:
             dict[str, list]: Dictionary mapping species names to lists of Label objects.
@@ -283,11 +287,11 @@ class Predictor:
         Given an array of raw scores, return as a pandas dataframe.
 
         Args:
-            score_array (np.ndarray): Array of scores of shape (num_spectrograms, num_species).
-            frame_map (np.ndarray, optional): Frame-level scores of shape (num_frames, num_species).
-                If provided, uses frame-level labels; otherwise uses segment-level labels.
-            start_times (list[float]): Start time in seconds for each spectrogram.
-            recording_name (str): Name of the recording for the dataframe.
+        - score_array (np.ndarray): Array of scores of shape (num_spectrograms, num_species).
+        - frame_map (np.ndarray, optional): Frame-level scores of shape (num_frames, num_species).
+            If provided, uses frame-level labels; otherwise uses segment-level labels.
+        - start_times (list[float]): Start time in seconds for each spectrogram.
+        - recording_name (str): Name of the recording for the dataframe.
 
         Returns:
             pd.DataFrame: DataFrame with columns ['recording', 'name', 'start_time', 'end_time', 'score']
@@ -321,6 +325,30 @@ class Predictor:
         df["score"] = score_list
         return df
 
+    def log_scores(self, scores):
+        """
+        Given an array of raw segment-level scores, log them by descending score.
+
+        Args:
+        - scores (np.ndarray): Array of scores of shape (num_spectrograms, num_species).
+        """
+        assert self.class_names is not None
+
+        labels: dict[str, list] = {}  # name -> [(score, start_time, end_time)]
+        if scores is None or len(scores) == 0:
+            return labels
+
+        names = self._get_names()
+
+        # ensure labels are sorted by name/code before start_time,
+        # which is useful when inspecting label files during testing
+        num_classes = scores.shape[1]
+        scores = deepcopy(scores[0])
+        for i in range(min(num_classes, 10)):
+            j = np.argmax(scores)
+            logging.info(f"{names[j]}: {scores[j]:.4f}")
+            scores[j] = 0
+
     def save_audacity_labels(
         self,
         scores,
@@ -332,11 +360,11 @@ class Predictor:
         Given an array of raw scores, convert to Audacity labels and save in the given file.
 
         Args:
-            scores (np.ndarray): Segment-level scores of shape (num_spectrograms, num_species).
-            frame_map (np.ndarray, optional): Frame-level scores of shape (num_frames, num_species).
-                If provided, uses frame-level labels; otherwise uses segment-level labels.
-            start_times (list[float]): Start time in seconds for each spectrogram.
-            file_path (str): Output path for the Audacity label file.
+        - scores (np.ndarray): Segment-level scores of shape (num_spectrograms, num_species).
+        - frame_map (np.ndarray, optional): Frame-level scores of shape (num_frames, num_species).
+            If provided, uses frame-level labels; otherwise uses segment-level labels.
+        - start_times (list[float]): Start time in seconds for each spectrogram.
+        - file_path (str): Output path for the Audacity label file.
 
         Returns:
             None: Writes the labels directly to the specified file.
@@ -369,9 +397,9 @@ class Predictor:
         Use mean rather than max or weighted values.
 
         Args:
-            frame_scores: (num_specs, num_classes, T_spec) scores in [0, 1].
-            offsets_sec: start time (s) for each spectrogram within the recording.
-            recording_duration_sec: total recording length in seconds.
+        - frame_scores: (num_specs, num_classes, T_spec) scores in [0, 1].
+        - offsets_sec: start time (s) for each spectrogram within the recording.
+        - recording_duration_sec: total recording length in seconds.
 
         Returns:
             global_frames: (num_classes, T_global) tensor of scores in [0, 1].

britekit/core/reextractor.py

@@ -22,12 +22,12 @@ class Reextractor:
     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'.
     """
 
     def __init__(

britekit/core/util.py

@@ -135,6 +135,42 @@ def get_range(min_val: float, max_val: float, incr: float) -> List[float]:
     return [float(v) for v in values]
 
 
+def _get_seconds_from_time_string(time_str: str) -> int:
+    """
+    Convert a time string into an integer number of seconds.
+
+    Supports the following formats:
+    - "71" → 71 seconds
+    - "1:11" → 71 seconds
+    - "0:01:11" → 71 seconds
+    - "1:02:03" → 3723 seconds (1 hour, 2 minutes, 3 seconds)
+
+    Args:
+        time_str (str): Time string in seconds or colon-separated format.
+
+    Returns:
+        int: Total number of seconds.
+    """
+    parts = time_str.strip().split(":")
+
+    # Only seconds provided
+    if len(parts) == 1:
+        return int(float(parts[0]))
+
+    # Minutes and seconds
+    elif len(parts) == 2:
+        minutes, seconds = map(float, parts)
+        return int(minutes * 60 + seconds)
+
+    # Hours, minutes, and seconds
+    elif len(parts) == 3:
+        hours, minutes, seconds = map(float, parts)
+        return int(hours * 3600 + minutes * 60 + seconds)
+
+    else:
+        raise ValueError(f"Unrecognized time format: '{time_str}'")
+
+
 def set_logging(level=logging.INFO, timestamp=False):
     """Initialize logging."""
     if timestamp:
@@ -166,7 +202,7 @@ def cfg_to_pure(obj: Any) -> JSONValue:
     str, int, float, bool) that can be safely serialized.
 
     Args:
-        obj: Any object to convert to JSON-serializable format
+    - obj: Any object to convert to JSON-serializable format
 
     Returns:
         JSON-serializable representation of the input object
@@ -284,8 +320,8 @@ def get_audio_files(path: str, short_names: bool = False) -> List[str]:
     Return list of audio files in the given directory.
 
     Args:
-        path (str): Directory path
-        short_names (bool): If true, return file names, else return full paths
+    - path (str): Directory path
+    - short_names (bool): If true, return file names, else return full paths
 
     Returns:
         List of audio files in the given directory
@@ -325,8 +361,8 @@ def get_file_lines(path: str, encoding: str = "utf-8") -> List[str]:
     and lines that start with #.
 
     Args:
-        path: Path to text file
-        encoding: File encoding (default: utf-8)
+    - path: Path to text file
+    - encoding: File encoding (default: utf-8)
 
     Returns:
         List of lines
@@ -354,7 +390,7 @@ def get_source_name(filename: str) -> str:
     Return a source name given a recording file name.
 
     Args:
-        filename: Recording file name
+    - filename: Recording file name
 
     Returns:
         Source name
@@ -390,7 +426,7 @@ def compress_spectrogram(spec) -> bytes:
     Compress a spectrogram in preparation for inserting into database.
 
     Args:
-        spec: Uncompressed spectrogram
+    - spec: Uncompressed spectrogram
 
     Returns:
         Compressed spectrogram
@@ -421,7 +457,7 @@ def expand_spectrogram(spec: bytes):
     Decompress a spectrogram, then convert from bytes to floats and reshape it.
 
     Args:
-        spec: Compressed spectrogram
+    - spec: Compressed spectrogram
 
     Returns:
         Uncompressed spectrogram

britekit/occurrence_db/occurrence_data_provider.py

@@ -10,7 +10,7 @@ class OccurrenceDataProvider:
     you must call the refresh method.
 
     Args:
-        db (OccurrenceDatabase): The database object.
+    - db (OccurrenceDatabase): The database object.
     """
 
     def __init__(self, db: OccurrenceDatabase):
@@ -31,8 +31,8 @@ class OccurrenceDataProvider:
         Return county info for a given latitude/longitude, or None if not found.
 
         Args:
-            latitude (float): Latitude.
-            longitude (float): Longitude.
+        - latitude (float): Latitude.
+        - longitude (float): Longitude.
 
         Returns:
             County object, or None if not found.
@@ -54,8 +54,8 @@ class OccurrenceDataProvider:
         For each week, return the maximum of it and the adjacent weeks.
 
         Args:
-            county_code (str): County code
-            class_name (str): Class name
+        - county_code (str): County code
+        - class_name (str): Class name
 
         Returns:
             List of smoothed occurrence values.
@@ -75,8 +75,8 @@ class OccurrenceDataProvider:
         Return list of occurrence values for given county code and class name.
 
         Args:
-            county_code (str): County code
-            class_name (str): Class name
+        - county_code (str): County code
+        - class_name (str): Class name
 
         Returns:
             List of occurrence values.
@@ -97,9 +97,9 @@ class OccurrenceDataProvider:
         If area_weight = True, weight each county by its area.
 
         Args:
-            county_prefix (str): County code prefix
-            class_name (str): Class name
-            area_weight (bool, Optional): If true, weight by county area (default = False)
+        - county_prefix (str): County code prefix
+        - class_name (str): Class name
+        - area_weight (bool, Optional): If true, weight by county area (default = False)
 
         Returns:
             Numpy array of 48 average occurrence values (one per week, using 4-week months).
@@ -139,9 +139,9 @@ class OccurrenceDataProvider:
         county don't occur in the same week.
 
         Args:
-            county_prefix (str): County code prefix
-            class_name (str): Class name
-            area_weight (bool, Optional): If true, weight by county area (default = False)
+        - county_prefix (str): County code prefix
+        - class_name (str): Class name
+        - area_weight (bool, Optional): If true, weight by county area (default = False)
 
         Returns:
             Numpy average maximum occurrence value.