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

britekit/commands/_find_dup.py

@@ -31,11 +31,11 @@ def find_dup(
     using cosine distance.
 
     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.
-        class_name (str): Name of the class to scan for duplicates (e.g., "Common Yellowthroat").
-        delete (bool): If True, remove duplicate recordings from the database. If False, only report them.
-        spec_group (str): Spectrogram group name to use for embedding comparison. 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.train_db.
+    - class_name (str): Name of the class to scan for duplicates (e.g., "Common Yellowthroat").
+    - delete (bool): If True, remove duplicate recordings from the database. If False, only report them.
+    - spec_group (str): Spectrogram group name to use for embedding comparison. Defaults to "default".
     """
 
     class Recording:

britekit/commands/_inat.py

@@ -54,10 +54,10 @@ def inat(
     The command respects the maximum download limit and can optionally add filename prefixes.
 
     Args:
-        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 (e.g., "Common Yellowthroat", "Geothlypis trichas").
-        no_prefix (bool): If True, skip adding "N" prefix to filenames. Default adds prefix.
+    - 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 (e.g., "Common Yellowthroat", "Geothlypis trichas").
+    - no_prefix (bool): If True, skip adding "N" prefix to filenames. Default adds prefix.
     """
     import pyinaturalist
 

britekit/commands/_init.py

@@ -32,7 +32,7 @@ def init(dest: Optional[Path]=None) -> None:
     a default directory structure.
 
     Args:
-        dest (Path): Directory to copy files into. Subdirectories are created as needed.
+    - dest (Path): Directory to copy files into. Subdirectories are created as needed.
 
     Examples:
         britekit init --dest .

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
 
@@ -528,6 +528,7 @@ def rpt_test(
     output_path: str = "",
     recordings_path: Optional[str] = None,
     min_score: Optional[float] = None,
+    block_size: int = 60,
     precision: float = 0.95,
 ):
     """
@@ -536,27 +537,28 @@ def rpt_test(
     This command evaluates model performance by comparing inference results against
     ground truth annotations. It supports three granularity levels:
     - "recording": Evaluate at the recording level (presence/absence)
-    - "minute": Evaluate at the minute level (presence/absence per minute)
+    - "block": Evaluate at the block level (presence/absence per block)
     - "segment": Evaluate at the segment level (detailed temporal alignment)
 
     The command generates detailed performance metrics including precision, recall,
     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", "minute", 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.
-        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_minute_tester import PerMinuteTester
+    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)
@@ -582,13 +584,14 @@ def rpt_test(
                 min_score,
                 precision,
             ).run()
-        elif granularity.startswith("min"):
-            PerMinuteTester(
+        elif granularity.startswith("bl"):
+            PerBlockTester(
                 annotations_path,
                 recordings_path,
                 labels_path,
                 output_path,
                 min_score,
+                block_size,
             ).run()
         elif granularity.startswith("seg"):
             PerSegmentTester(
@@ -600,7 +603,7 @@ def rpt_test(
             ).run()
         else:
             logging.error(
-                'Invalid granularity (expected "recording", "minute" or "segment").'
+                'Invalid granularity (expected "recording", "block" or "segment").'
             )
 
     except InputError as e:
@@ -626,7 +629,7 @@ def rpt_test(
     "granularity",
     type=str,
     default="segment",
-    help='Test annotation and reporting granularity ("recording", "minute" or "segment"). Default = "segment".',
+    help='Test annotation and reporting granularity ("recording", "block" or "segment"). Default = "segment".',
 )
 @click.option(
     "-a",
@@ -668,6 +671,15 @@ def rpt_test(
     required=False,
     help="Provide detailed reports for this threshold.",
 )
+@click.option(
+    "-b",
+    "--block",
+    "block_size",
+    type=int,
+    required=False,
+    default=60,
+    help="Block size in seconds, when granularity=block (default=60).",
+)
 @click.option(
     "--precision",
     required=False,
@@ -683,6 +695,7 @@ def _rpt_test_cmd(
     output_path: str,
     recordings_path: Optional[str],
     min_score: Optional[float],
+    block_size: int,
     precision: float,
 ):
     util.set_logging()
@@ -694,5 +707,6 @@ def _rpt_test_cmd(
         output_path,
         recordings_path,
         min_score,
+        block_size,
         precision,
     )

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)