Skip to content

aux_targets

birdnet_stm32.data.aux_targets

Where and when each training recording was made, as targets for a training-only auxiliary head.

The head (birdnet_stm32.training.embedding_distillation) predicts, from the pooled embedding, the recording's location as a unit vector on the sphere (x, y, z) and its day of year as (sin, cos). Learning these pushes the embedding to encode the species composition of a place and season, which a single-label classification loss does not ask for.

The table lives in a folder of memory-mapped arrays, so every loader worker shares one copy:

keys.npy     uint64, sorted: an 8-byte BLAKE2b hash of each sample id (the audio file's stem)
targets.npy  float16 [N, 5]: x, y, z, sin(day), cos(day)
valid.npy    uint8 [N, 2]: location known, date known
meta.json    counts and the build inputs

Build it from a dataset manifest (sample_id, latitude, longitude, event_date, source) with python -m birdnet_stm32.data.aux_targets <manifest.csv> <out_dir> [--site_coords sites.json]; sites.json maps a source to [lat, lon] for collections recorded at one known site whose rows carry no coordinates (e.g. a soundscape set).

AuxTargets

Memory-mapped lookup of a recording's auxiliary targets by sample id.

Source code in birdnet_stm32/data/aux_targets.py
class AuxTargets:
    """Memory-mapped lookup of a recording's auxiliary targets by sample id."""

    def __init__(self, folder: str | Path):
        d = Path(folder)
        self.keys = np.load(d / "keys.npy", mmap_mode="r")
        self.targets = np.load(d / "targets.npy", mmap_mode="r")
        self.valid = np.load(d / "valid.npy", mmap_mode="r")

    def lookup(self, sample_id: str) -> tuple[np.ndarray, np.ndarray]:
        """(targets float32 [5], valid float32 [2]); zeros when the recording is not in the table."""
        k = np.uint64(sample_key(sample_id))
        i = int(np.searchsorted(self.keys, k))
        if i < len(self.keys) and self.keys[i] == k:
            return np.asarray(self.targets[i], np.float32), np.asarray(self.valid[i], np.float32)
        return np.zeros(AUX_DIM, np.float32), np.zeros(2, np.float32)

    def __contains__(self, sample_id: str) -> bool:
        k = np.uint64(sample_key(sample_id))
        i = int(np.searchsorted(self.keys, k))
        return i < len(self.keys) and self.keys[i] == k

lookup(sample_id)

(targets float32 [5], valid float32 [2]); zeros when the recording is not in the table.

Source code in birdnet_stm32/data/aux_targets.py
def lookup(self, sample_id: str) -> tuple[np.ndarray, np.ndarray]:
    """(targets float32 [5], valid float32 [2]); zeros when the recording is not in the table."""
    k = np.uint64(sample_key(sample_id))
    i = int(np.searchsorted(self.keys, k))
    if i < len(self.keys) and self.keys[i] == k:
        return np.asarray(self.targets[i], np.float32), np.asarray(self.valid[i], np.float32)
    return np.zeros(AUX_DIM, np.float32), np.zeros(2, np.float32)

geo_unit(lat, lon)

[N, 3] unit vectors for latitude / longitude in degrees.

Source code in birdnet_stm32/data/aux_targets.py
def geo_unit(lat: np.ndarray, lon: np.ndarray) -> np.ndarray:
    """[N, 3] unit vectors for latitude / longitude in degrees."""
    la, lo = np.radians(lat), np.radians(lon)
    return np.stack([np.cos(la) * np.cos(lo), np.cos(la) * np.sin(lo), np.sin(la)], axis=1)

day_angle(day_of_year)

[N, 2] (sin, cos) of the day of year on a 365.25-day circle.

Source code in birdnet_stm32/data/aux_targets.py
def day_angle(day_of_year: np.ndarray) -> np.ndarray:
    """[N, 2] (sin, cos) of the day of year on a 365.25-day circle."""
    a = 2 * np.pi * (np.asarray(day_of_year, np.float64) - 1) / 365.25
    return np.stack([np.sin(a), np.cos(a)], axis=1)