bioaccx 0.1.0__py3-none-any.whl

bioaccx/__init__.py

@@ -0,0 +1,6 @@
+"""bioaccx — bioacoustic custom classifier generator."""
+from bioaccx.config import BioaccxConfig, load_config
+from bioaccx.train import run
+
+__all__ = ["BioaccxConfig", "load_config", "run"]
+__version__ = "0.1.0"

bioaccx/__main__.py

@@ -0,0 +1,10 @@
+import signal
+
+from bioaccx.cli import main
+
+# The GUI cancels a run on Windows with Ctrl+Break (see gui/jobs.py), which
+# would otherwise end the process without the clean "Interrupted." exit.
+if hasattr(signal, "SIGBREAK"):
+    signal.signal(signal.SIGBREAK, signal.default_int_handler)
+
+main()

bioaccx/_click.py

@@ -0,0 +1,49 @@
+"""The Click that Typer drives.
+
+Typer 0.26 vendored Click into ``typer._click`` and dropped its dependency on
+the standalone package. A command built by ``typer.main.get_command`` therefore
+raises ``typer._click`` exceptions — which ``except click.UsageError`` does not
+catch when ``click`` is the separately installed one — and its parameters are
+not instances of ``click.Argument``. Both were silent behaviour changes: unknown
+options started printing a traceback instead of a usage error.
+
+So the CLI and the docs generator import their Click from here, and this module
+resolves whichever copy Typer is actually using. The fallback keeps working on
+Typer < 0.26, which drove the standalone package.
+
+Only the names bioaccx needs are re-exported. There is deliberately no ``Group``
+or ``Argument``: the vendored copy has neither (Typer supplies ``TyperGroup``
+and ``TyperArgument``), so a group is recognised by having ``.commands`` and an
+argument by ``param.param_type_name == "argument"``.
+"""
+
+from __future__ import annotations
+
+try:  # Typer >= 0.26 — the vendored copy, and the only one Typer raises from.
+    from typer import Abort as Abort
+    from typer import Exit as Exit
+    from typer._click.core import Command as Command
+    from typer._click.core import Context as Context
+    from typer._click.core import Parameter as Parameter
+    from typer._click.exceptions import ClickException as ClickException
+    from typer._click.exceptions import UsageError as UsageError
+    from typer._click.globals import get_current_context as get_current_context
+except ImportError:  # pragma: no cover - Typer < 0.26
+    from click.core import Command as Command
+    from click.core import Context as Context
+    from click.core import Parameter as Parameter
+    from click.exceptions import Abort as Abort
+    from click.exceptions import ClickException as ClickException
+    from click.exceptions import Exit as Exit
+    from click.exceptions import UsageError as UsageError
+    from click.globals import get_current_context as get_current_context
+
+
+def is_group(command: Command) -> bool:
+    """True when *command* holds subcommands."""
+    return hasattr(command, "commands")
+
+
+def is_argument(param: Parameter) -> bool:
+    """True for a positional argument, false for an option."""
+    return param.param_type_name == "argument"

bioaccx/_legacy_cli.py

@@ -0,0 +1,166 @@
+"""Translation of the pre-subcommand flag interface into subcommand argv.
+
+Before subcommands, every mode was a top-level flag on one command
+(``bioaccx cfg.yaml --dataset --no-split``).  Scripts and documentation in the
+wild still use that form, so it keeps working: :func:`is_legacy` recognises it
+and :func:`translate` rewrites it into the equivalent subcommand invocation,
+which :mod:`bioaccx.cli` then dispatches normally.
+
+Everything here exists only to serve those older invocations — including the
+cross-flag validation that subcommands make unnecessary, since a subcommand
+simply cannot be handed a flag belonging to another mode.  When the legacy
+form is eventually dropped, this whole module goes with it and nothing in
+``cli.py`` needs untangling.
+"""
+from __future__ import annotations
+
+import argparse
+
+#: Subcommand names, so a first argument naming one is never treated as legacy.
+SUBCOMMANDS = frozenset({
+    "train", "validate", "dataset", "embeddings",
+    "merge", "extract-head", "convert-head", "registry", "gui",
+})
+
+#: Flags that only ever existed on the old interface. Their presence marks an
+#: invocation as legacy even when it starts with an option rather than a path.
+_LEGACY_FLAGS = frozenset({
+    "--validate", "--dataset", "--embeddings", "--registry",
+    "--convert-head", "--convert_head",
+    "--merge", "--extract-head", "--extract_head",
+    "--no-split", "--backbone", "--embed-dim",
+})
+
+
+def is_legacy(argv: list[str]) -> bool:
+    """True when *argv* uses the old flag interface rather than a subcommand.
+
+    A first argument that is not an option decides on its own: a subcommand
+    name is new-style, anything else is the old bare-config form.  Only when
+    the first argument *is* an option do the legacy flags get a say, so that
+    ``merge HEAD --backbone 0xbb00`` is correctly read as new-style even though
+    ``--backbone`` also appears in old invocations.
+
+    >>> is_legacy(["cfg.yaml"])
+    True
+    >>> is_legacy(["train", "cfg.yaml"])
+    False
+    >>> is_legacy(["merge", "head.onnx", "--backbone", "0xbb00"])
+    False
+    >>> is_legacy(["--registry"])
+    True
+    >>> is_legacy(["--help"])
+    False
+    >>> is_legacy([])
+    False
+    """
+    if not argv:
+        return False
+    first = argv[0]
+    if not first.startswith("-"):
+        return first not in SUBCOMMANDS
+    return any(arg in _LEGACY_FLAGS for arg in argv)
+
+
+def _parser() -> argparse.ArgumentParser:
+    """The old parser, kept intact so legacy invocations fail exactly as before.
+
+    It never prints help — ``--help`` routes to the subcommand interface — so
+    it carries no description or epilog, only the arguments needed to read an
+    old command line and the errors that rejected bad combinations.
+    """
+    parser = argparse.ArgumentParser(prog="bioaccx", add_help=False)
+    parser.add_argument("config", nargs="?")
+    parser.add_argument("--registry", action="store_true")
+    parser.add_argument("--validate", action="store_true")
+    parser.add_argument("--dataset", action="store_true")
+    parser.add_argument("--no-split", action="store_true")
+    parser.add_argument("--embeddings", action="store_true")
+    parser.add_argument("--merge", nargs="?", const=True, metavar="HEAD")
+    parser.add_argument("--extract-head", "--extract_head", dest="extract_head",
+                        nargs="?", const=True, metavar="MODEL")
+    parser.add_argument("--convert-head", "--convert_head", dest="convert_head",
+                        metavar="HEAD")
+    parser.add_argument("-o", "--out", metavar="PATH")
+    parser.add_argument("--backbone", metavar="ID|PATH")
+    parser.add_argument("--embed-dim", type=int, metavar="N")
+    parser.add_argument("--labels", metavar="PATH")
+    parser.add_argument("--format", choices=("onnx", "tflite", "both"), default="both")
+    return parser
+
+
+def translate(argv: list[str]) -> list[str]:
+    """Rewrite a legacy command line as its subcommand equivalent.
+
+    Rejects the flag combinations the old interface never allowed, with the
+    same messages and exit code 2, then returns argv in subcommand form.
+
+    >>> translate(["cfg.yaml"])
+    ['train', 'cfg.yaml']
+    >>> translate(["cfg.yaml", "--dataset", "--no-split"])
+    ['dataset', 'cfg.yaml', '--no-split']
+    >>> translate(["--registry"])
+    ['registry']
+    """
+    parser = _parser()
+    args = parser.parse_args(argv)
+
+    if args.no_split and not args.dataset:
+        parser.error("--no-split is only valid together with --dataset")
+
+    # `--merge HEAD` (a string) takes its inputs from the command line;
+    # a bare `--merge` (True) reads them from the config file instead.
+    cli_merge = isinstance(args.merge, str)
+    cli_extract = isinstance(args.extract_head, str)
+
+    if args.out and not (args.convert_head or cli_merge or cli_extract):
+        parser.error(
+            "-o/--out is only valid with --convert-head, or with --merge / --extract-head "
+            "when their inputs are given on the command line"
+        )
+    if (args.backbone or args.embed_dim or args.labels) and not (cli_merge or cli_extract):
+        parser.error(
+            "--backbone / --embed-dim / --labels are only valid with --merge <HEAD> or "
+            "--extract-head <MODEL>; with a config file these come from the config"
+        )
+    if args.config and (cli_merge or cli_extract):
+        parser.error(
+            "give either a config file or the command-line inputs, not both — "
+            "the config already carries the head/model path and the output location"
+        )
+
+    out = ["-o", args.out] if args.out else []
+
+    if args.convert_head:
+        return ["convert-head", args.convert_head, *out]
+    if cli_merge:
+        backbone = ["--backbone", args.backbone] if args.backbone else []
+        embed_dim = ["--embed-dim", str(args.embed_dim)] if args.embed_dim else []
+        return ["merge", args.merge, *backbone, *embed_dim, *out]
+    if cli_extract:
+        backbone = ["--backbone", args.backbone] if args.backbone else []
+        embed_dim = ["--embed-dim", str(args.embed_dim)] if args.embed_dim else []
+        labels = ["--labels", args.labels] if args.labels else []
+        return ["extract-head", args.extract_head, *backbone, *embed_dim, *labels,
+                "--format", args.format, *out]
+
+    if args.registry:
+        return ["registry"]
+
+    if args.config is None:
+        parser.error(
+            "a config file is required unless --registry / --convert-head is used, or "
+            "--merge / --extract-head are given their inputs directly"
+        )
+
+    if args.validate:
+        return ["validate", args.config]
+    if args.merge:
+        return ["merge", args.config]
+    if args.extract_head:
+        return ["extract-head", args.config]
+    if args.dataset:
+        return ["dataset", args.config, *(["--no-split"] if args.no_split else [])]
+    if args.embeddings:
+        return ["embeddings", args.config]
+    return ["train", args.config]

bioaccx/arbimon.py

@@ -0,0 +1,228 @@
+"""Arbimon audio fetching and caching via the rfcx SDK.
+
+Each row in the ext_table identifies a specific 1-minute recording by:
+  stream_id  — Arbimon recording site ID
+  date       — local date (YYYY-MM-DD)
+  time       — local time (HH:MM or HH:MM:SS)
+  utc_offset — UTC offset for the local time in hours (numeric: -3, +5.5, 0)
+
+The label falls back to ``stream_id`` when the table row has no label.
+
+Authentication
+--------------
+A persisted rfcx credentials file is required.  On first use, run::
+
+    import rfcx
+    client = rfcx.Client()
+    client.authenticate(persisted_credentials_path="/path/to/.rfcx_credentials")
+
+This opens a browser URL for device authorisation and saves the token.
+Subsequent calls load the token from the file without user interaction.
+
+Install the rfcx SDK (not on PyPI; install from the GitHub release wheel)::
+
+    pip install https://github.com/rfcx/rfcx-sdk-python/releases/download/0.3.1/rfcx-0.3.1-py3-none-any.whl
+
+Cache layout::
+
+    <cache_dir>/
+        arbimon/
+            <stream_id>/
+                <files downloaded by rfcx SDK>
+"""
+from __future__ import annotations
+
+import datetime
+import re
+from pathlib import Path
+from typing import Optional
+
+
+_AUDIO_EXTS: frozenset[str] = frozenset({".wav", ".flac", ".mp3", ".ogg"})
+_TIMESTAMP_RE = re.compile(r"\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}")
+
+# Module-level rfcx client singleton — authenticated once per credentials path.
+_client = None
+_authenticated_path: Optional[str] = None
+
+
+def _get_client(credentials_path: Optional[str]):
+    """Return (and cache) a fully authenticated rfcx.Client singleton.
+
+    Re-authenticates only when a different credentials_path is passed, so
+    repeated calls within the same process are essentially free.  The rfcx SDK
+    is imported lazily so that the heavy TensorFlow dependency it pulls in does
+    not affect users who never call Arbimon functions.
+    """
+    global _client, _authenticated_path
+    # Fast path: reuse the existing client if the credentials path hasn't changed.
+    if _client is not None and credentials_path == _authenticated_path:
+        return _client
+    try:
+        import rfcx
+    except ImportError as exc:
+        raise ImportError(
+            "The rfcx SDK is required for Arbimon downloads. Install it with:\n"
+            "  pip install https://github.com/rfcx/rfcx-sdk-python/releases/"
+            "download/0.3.1/rfcx-0.3.1-py3-none-any.whl"
+        ) from exc
+    if not credentials_path:
+        raise ValueError(
+            "arbimon_credentials_path must be set to authenticate with Arbimon."
+        )
+    cred = Path(credentials_path)
+    if not cred.exists():
+        raise FileNotFoundError(
+            f"Arbimon credentials file not found: {credentials_path}\n"
+            "Run rfcx.Client().authenticate(persisted_credentials_path=...) once "
+            "to create it."
+        )
+    # authenticate() reads the token from disk without browser interaction when
+    # the credentials file already exists.
+    c = rfcx.Client()
+    c.authenticate(persisted_credentials_path=str(cred))
+    _client = c
+    _authenticated_path = credentials_path
+    return _client
+
+
+def _parse_utc_offset(val: float | str) -> float:
+    """Parse a UTC offset to a float number of hours.
+
+    Accepts integers, floats, or strings such as ``"-3"``, ``"+5.5"``,
+    ``"UTC-3"``, ``"UTC+5:30"`` (treated as 5.5 hours).
+    """
+    if isinstance(val, (int, float)):
+        return float(val)
+    s = str(val).strip().upper().replace("UTC", "").strip()
+    if ":" in s:
+        sign = -1 if s.startswith("-") else 1
+        parts = s.lstrip("+-").split(":")
+        hours = float(parts[0])
+        minutes = float(parts[1]) if len(parts) > 1 else 0.0
+        return sign * (hours + minutes / 60.0)
+    return float(s)
+
+
+def _to_utc(date_str: str, time_str: str, utc_offset: float) -> datetime.datetime:
+    """Convert a local date + time string to a naive UTC datetime.
+
+    Subtracts the UTC offset from the local time; no timezone objects are
+    created — the result is a plain naive datetime understood to be UTC.
+    """
+    d = datetime.date.fromisoformat(date_str.strip())
+    parts = time_str.strip().split(":")
+    h, m = int(parts[0]), int(parts[1])
+    s = int(parts[2]) if len(parts) > 2 else 0
+    local_dt = datetime.datetime(d.year, d.month, d.day, h, m, s)
+    return local_dt - datetime.timedelta(hours=utc_offset)
+
+
+def _list_audio(directory: Path) -> set[Path]:
+    """Return the set of all audio files (by extension) under *directory*."""
+    return {p for p in directory.rglob("*") if p.suffix.lower() in _AUDIO_EXTS}
+
+
+def _sentinel_path(cache_dir: Path, utc_dt: datetime.datetime) -> Path:
+    """Return the path of the sentinel file for a given UTC timestamp.
+
+    The sentinel stores the path of the downloaded audio file so that future
+    calls can locate it without listing the directory again.
+    """
+    return cache_dir / f"{utc_dt.strftime('%Y-%m-%d_%H-%M-%S')}.cached"
+
+
+def _read_sentinel(cache_dir: Path, utc_dt: datetime.datetime) -> Optional[Path]:
+    """Return the cached audio path from a sentinel file, or None if missing/stale."""
+    sentinel = _sentinel_path(cache_dir, utc_dt)
+    if not sentinel.exists():
+        return None
+    audio_path = Path(sentinel.read_text(encoding="utf-8").strip())
+    if audio_path.exists():
+        return audio_path
+    sentinel.unlink()  # stale — audio was deleted
+    return None
+
+
+def _write_sentinel(cache_dir: Path, utc_dt: datetime.datetime, audio_path: Path) -> None:
+    """Persist the path of the downloaded audio file in the sentinel file."""
+    _sentinel_path(cache_dir, utc_dt).write_text(str(audio_path), encoding="utf-8")
+
+
+def get_audio(
+    stream_id: str,
+    date_str: str,
+    time_str: str,
+    utc_offset: float | str,
+    cache_dir: Path,
+    credentials_path: Optional[str] = None,
+) -> tuple[Path, str]:
+    """Return ``(local_audio_path, stream_id)`` for an Arbimon recording.
+
+    Downloads and caches the 1-minute segment that starts at the given local
+    date/time.  Subsequent calls with the same stream/time read from the cache
+    without any network access.
+
+    Parameters
+    ----------
+    stream_id:
+        Arbimon stream (recording site) ID.
+    date_str:
+        Recording date in local time, ISO format: ``"YYYY-MM-DD"``.
+    time_str:
+        Recording start time in local time: ``"HH:MM"`` or ``"HH:MM:SS"``.
+    utc_offset:
+        UTC offset for the local time in hours (e.g. ``-3``, ``+5.5``).
+    cache_dir:
+        Root cache directory.  Arbimon files are stored under
+        ``<cache_dir>/arbimon/<stream_id>/``.
+    credentials_path:
+        Path to the rfcx persisted credentials file created by
+        ``rfcx.Client().authenticate(persisted_credentials_path=...)``.
+    """
+    # Convert local time to UTC so the rfcx SDK receives timezone-aware values.
+    utc_offset_h = _parse_utc_offset(utc_offset)
+    utc_dt = _to_utc(date_str, time_str, utc_offset_h)
+
+    stream_cache = cache_dir / "arbimon" / stream_id
+    stream_cache.mkdir(parents=True, exist_ok=True)
+
+    # Return early if this exact minute was already downloaded.
+    cached = _read_sentinel(stream_cache, utc_dt)
+    if cached is not None:
+        return cached, stream_id
+
+    # Snapshot the directory before downloading so we can detect newly added files.
+    before = _list_audio(stream_cache)
+
+    client = _get_client(credentials_path)
+    # The rfcx API uses a [min_date, max_date) window; 1-minute recordings sit
+    # entirely within the requested 60-second span.
+    min_date = utc_dt
+    max_date = utc_dt + datetime.timedelta(minutes=1)
+    print(
+        f"  [arbimon] downloading stream={stream_id} "
+        f"{utc_dt.strftime('%Y-%m-%d %H:%M:%S')} UTC …"
+    )
+    client.download_segments(
+        dest_path=str(stream_cache),
+        stream=stream_id,
+        min_date=min_date,
+        max_date=max_date,
+        parallel=False,
+    )
+
+    # Identify which files the SDK wrote (set difference, then sort for determinism).
+    after = _list_audio(stream_cache)
+    new_files = sorted(after - before)
+    if not new_files:
+        raise RuntimeError(
+            f"No audio downloaded for stream={stream_id!r} at "
+            f"{utc_dt.strftime('%Y-%m-%d %H:%M:%S')} UTC. "
+            "Verify the stream ID, time window, and that your account has access."
+        )
+
+    # Take the first (alphabetically earliest) newly downloaded file and cache it.
+    result = new_files[0]
+    _write_sentinel(stream_cache, utc_dt, result)
+    return result, stream_id

bioaccx/audio.py

@@ -0,0 +1,142 @@
+"""Audio I/O and preprocessing utilities."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+from scipy.signal import butter, resample_poly, sosfilt
+
+
+def load_mono(
+    path: Path,
+    target_sr: int,
+    offset: float = 0.0,
+    duration: float | None = None,
+) -> np.ndarray:
+    """Load audio as float32 mono at *target_sr*, optionally reading a segment.
+
+    Converts multi-channel files to mono by averaging channels.  Resamples
+    using a polyphase filter (resample_poly) when the file's native sample rate
+    differs from *target_sr*; the GCD-reduced up/down ratio minimises the
+    filter size.
+
+    Parameters
+    ----------
+    path:
+        Audio file readable by soundfile (WAV, FLAC, OGG, etc.).
+    target_sr:
+        Desired output sample rate in Hz.
+    offset:
+        Start of the segment in seconds (0 = beginning of file).
+    duration:
+        Length of the segment in seconds; None reads to end of file.
+    """
+    # sf.info() is called before sf.read() to convert time-based offsets to
+    # frame counts, which is the only unit soundfile's read() accepts.
+    start_frame = int(offset * sf.info(str(path)).samplerate) if offset > 0 else 0
+    frames = (
+        int(duration * sf.info(str(path)).samplerate) if duration is not None else -1
+    )
+    audio, sr = sf.read(
+        str(path),
+        start=start_frame,
+        frames=frames if frames > 0 else -1,
+        always_2d=False,
+    )
+    # Collapse stereo/multi-channel by averaging; no-op for mono arrays.
+    if audio.ndim > 1:
+        audio = audio.mean(axis=1)
+    # Resample only when necessary; reducing the ratio by GCD avoids unnecessarily
+    # large polyphase filter orders.
+    if sr != target_sr:
+        gcd = np.gcd(target_sr, sr)
+        audio = resample_poly(audio, target_sr // gcd, sr // gcd)
+    return audio.astype(np.float32)
+
+
+def to_fixed_length(audio: np.ndarray, n_samples: int) -> np.ndarray:
+    """Trim or zero-pad *audio* to exactly *n_samples*."""
+    if len(audio) >= n_samples:
+        return audio[:n_samples]
+    return np.pad(audio, (0, n_samples - len(audio))).astype(np.float32)
+
+
+AUDIO_EXTENSIONS: frozenset[str] = frozenset(
+    {".wav", ".flac", ".mp3", ".ogg", ".m4a", ".aiff"}
+)
+
+
+def apply_filter(
+    audio: np.ndarray,
+    sr: int,
+    filter_type: str,
+    freq: float | list[float],
+    order: int = 5,
+) -> np.ndarray:
+    """Apply a zero-phase Butterworth filter.
+
+    filter_type: 'hpf' | 'lpf' | 'bpf'
+    freq: cutoff Hz (scalar) for hpf/lpf; [low_hz, high_hz] for bpf
+    """
+    nyq = sr / 2.0
+    if filter_type in ("hpf", "lpf"):
+        Wn = float(freq) / nyq  # type: ignore[arg-type]
+        btype = "high" if filter_type == "hpf" else "low"
+        sos = butter(order, Wn, btype=btype, output="sos")
+    elif filter_type == "bpf":
+        if not hasattr(freq, "__len__") or len(freq) != 2:  # type: ignore[arg-type]
+            raise ValueError("bpf requires filter_freq as [low_hz, high_hz]")
+        Wn = [float(freq[0]) / nyq, float(freq[1]) / nyq]  # type: ignore[index]
+        sos = butter(order, Wn, btype="band", output="sos")
+    else:
+        raise ValueError(f"Unknown filter_type {filter_type!r}; use 'hpf', 'lpf', or 'bpf'")
+    return sosfilt(sos, audio).astype(np.float32)
+
+
+def mix_at_snr(signal: np.ndarray, noise: np.ndarray, snr_db: float) -> np.ndarray:
+    """Mix *signal* with *noise* at the requested power-based SNR (dB).
+
+    Scale factor derivation:
+        SNR_dB = 10 * log10(P_signal / P_noise_scaled)
+        scale  = sqrt(P_signal / (P_noise * 10^(snr_db/10)))
+
+    If either signal or noise has zero power the signal is returned unchanged.
+    """
+    sig_power = float(np.mean(signal ** 2))
+    noise_power = float(np.mean(noise ** 2))
+    if sig_power == 0.0 or noise_power == 0.0:
+        return signal
+    scale = float(np.sqrt(sig_power / (noise_power * 10.0 ** (snr_db / 10.0))))
+    return (signal + scale * noise).astype(np.float32)
+
+
+def place_in_window(audio: np.ndarray, n_samples: int, offset_samples: int = 0) -> np.ndarray:
+    """Place *audio* into a zero-padded window of *n_samples* at *offset_samples*.
+
+    Signal samples that extend past the end of the window are clipped.
+    """
+    out = np.zeros(n_samples, dtype=np.float32)
+    end = min(offset_samples + len(audio), n_samples)
+    sig_end = end - offset_samples
+    if sig_end > 0:
+        out[offset_samples:end] = audio[:sig_end]
+    return out
+
+
+def apply_speed(audio: np.ndarray, speed: float) -> np.ndarray:
+    """Change playback speed via resampling (no pitch correction).
+
+    speed > 1.0 → shorter duration (faster); speed < 1.0 → longer (slower).
+
+    The speed ratio is converted to a rational up/down pair so that
+    resample_poly receives integers.  limit_denominator(1000) keeps the
+    polyphase filter order manageable while keeping the approximation error
+    below 0.1% for typical speed values.
+    """
+    if speed == 1.0:
+        return audio
+    from fractions import Fraction
+    # Inverting speed gives the resampling ratio: output_len / input_len.
+    ratio = Fraction(1.0 / speed).limit_denominator(1000)
+    return resample_poly(audio, ratio.numerator, ratio.denominator).astype(np.float32)