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

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/models/base_model.py

@@ -252,7 +252,6 @@ class BaseModel(pl.LightningModule):
         }
 
     def on_save_checkpoint(self, checkpoint):
-        print("on_save_checkpoint")
         """Save model metadata to checkpoint."""
         if not hasattr(self, "identifier"):
             self.identifier = str(uuid.uuid4()).upper()

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.

britekit/testing/per_recording_tester.py

@@ -329,10 +329,10 @@ class PerRecordingTester(BaseTester):
         rpt.append(
             f"   Recall (recording) = {100 * self.details_dict['recall_annotated']:.2f}%\n"
         )
-        print()
+        logging.info("")
         with open(os.path.join(self.output_dir, "summary_report.txt"), "w") as summary:
             for rpt_line in rpt:
-                print(rpt_line[:-1])
+                logging.info(rpt_line[:-1])
                 summary.write(rpt_line)
 
         # write recording details (row per segment)

britekit/training_db/extractor.py

@@ -109,13 +109,45 @@ class Extractor:
 
         return offsets_per_file
 
+    def _insert_by_dict(self, recording_dir, destination_dir, offsets_per_file):
+        """
+        Given a recording directory and a dict from recording stems to offsets,
+        insert the corresponding spectrograms.
+        """
+        num_inserted = 0
+        recording_paths = util.get_audio_files(recording_dir)
+        for recording_dir in recording_paths:
+            filename = Path(recording_dir).stem
+            if filename not in offsets_per_file:
+                continue
+
+            if destination_dir is not None:
+                dest_path = os.path.join(destination_dir, Path(recording_dir).name)
+                if not os.path.exists(dest_path):
+                    shutil.copy(recording_dir, dest_path)
+
+                recording_dir = dest_path
+
+            logging.info(f"Processing {recording_dir}")
+            try:
+                self.audio.load(recording_dir)
+            except Exception as e:
+                logging.error(f"Caught exception: {e}")
+                continue
+
+            num_inserted += self.insert_spectrograms(
+                recording_dir, offsets_per_file[filename]
+            )
+
+        return num_inserted
+
     def insert_spectrograms(self, recording_path, offsets):
         """
         Insert a spectrogram at each of the given offsets of the specified file.
 
         Args:
-            recording_path (str): Path to audio recording.
-            offsets (list[float]): List of offsets, where each represents number of seconds to start of spectrogram.
+        - recording_path (str): Path to audio recording.
+        - offsets (list[float]): List of offsets, where each represents number of seconds to start of spectrogram.
 
         Returns:
             Number of spectrograms inserted.
@@ -156,7 +188,7 @@ class Extractor:
         Extract spectrograms for all recordings in the given directory.
 
         Args:
-            dir_path (str): Directory containing recordings.
+        - dir_path (str): Directory containing recordings.
 
         Returns:
             Number of spectrograms inserted.
@@ -187,45 +219,48 @@ class Extractor:
 
         return num_inserted
 
-    def extract_by_image(
-        self, rec_dir: str, spec_dir: str, dest_dir: Optional[str] = None
+    def extract_by_csv(
+        self, rec_dir: str, csv_path: str, dest_dir: Optional[str] = None
     ):
         """
         Extract spectrograms that match names of spectrogram images in a given directory.
         Typically the spectrograms were generated using the 'search' or 'plot-db' commands.
 
         Args:
-            rec_dir (str): Directory containing recordings.
-            spec_dir (str): Directory containing spectrogram images.
-            dest_dir (str, optional): Optionally copy used recordings to this directory.
+        - rec_dir (str): Directory containing recordings.
+        - csv_path (str): Path to CSV file containing two columns (recording and offset) to identify segments to extract.
+        - dest_dir (str, optional): Optionally copy used recordings to this directory.
 
         Returns:
             Number of spectrograms inserted.
         """
-        offsets_per_file = self._process_image_dir(spec_dir)
-        num_inserted = 0
-        recording_paths = util.get_audio_files(rec_dir)
-        for recording_path in recording_paths:
-            filename = Path(recording_path).stem
-            if filename not in offsets_per_file:
-                continue
+        import pandas as pd
 
-            if dest_dir is not None:
-                dest_path = os.path.join(dest_dir, Path(recording_path).name)
-                if not os.path.exists(dest_path):
-                    shutil.copy(recording_path, dest_path)
+        df = pd.read_csv(csv_path)
+        offsets_per_file: dict[str, list] = {}
+        for i, row in df.iterrows():
+            recording = row["recording"]
+            if recording not in offsets_per_file:
+                offsets_per_file[recording] = []
 
-                recording_path = dest_path
+            offsets_per_file[recording].append(row["offset"])
 
-            logging.info(f"Processing {recording_path}")
-            try:
-                self.audio.load(recording_path)
-            except Exception as e:
-                logging.error(f"Caught exception: {e}")
-                continue
+        return self._insert_by_dict(rec_dir, dest_dir, offsets_per_file)
 
-            num_inserted += self.insert_spectrograms(
-                recording_path, offsets_per_file[filename]
-            )
+    def extract_by_image(
+        self, rec_dir: str, spec_dir: str, dest_dir: Optional[str] = None
+    ):
+        """
+        Extract spectrograms that match names of spectrogram images in a given directory.
+        Typically the spectrograms were generated using the 'search' or 'plot-db' commands.
 
-        return num_inserted
+        Args:
+        - rec_dir (str): Directory containing recordings.
+        - spec_dir (str): Directory containing spectrogram images.
+        - dest_dir (str, optional): Optionally copy used recordings to this directory.
+
+        Returns:
+            Number of spectrograms inserted.
+        """
+        offsets_per_file = self._process_image_dir(spec_dir)
+        return self._insert_by_dict(rec_dir, dest_dir, offsets_per_file)

britekit/training_db/training_data_provider.py

@@ -8,7 +8,7 @@ class TrainingDataProvider:
     Data access layer on top of TrainingDatabase.
 
     Args:
-        db (TrainingDatabase): The database object.
+    - db (TrainingDatabase): The database object.
     """
 
     def __init__(self, db: TrainingDatabase):