callcut.io.CallDataset

class callcut.io.CallDataset(recordings, extractor, window_s=2.0, window_hop_s=0.5)

PyTorch Dataset for frame-level call detection.

Provides windowed samples of features with per-frame binary labels for training call detection models.

Parameters:

recordingslist of RecordingInfo

Recording metadata from scan_recordings().

extractorBaseExtractor

Feature extractor instance.

window_sfloat

Window length in seconds for each sample.

window_hop_sfloat

Hop between consecutive windows in seconds.

Attributes

n_recordings	Number of recordings in the dataset.
n_windows	Total number of windows (samples).
window_frames	Window length in frames.
window_hop_frames	Window hop in frames.

Methods

compute_pos_weight()

Compute positive class weight for imbalanced data.

Notes

Lazy loading: Features are computed on-demand in __getitem__ rather than pre-loaded into memory. Results are cached via LRU cache.

Examples

>>> from pathlib import Path
>>> from callcut.extractors import SNRExtractor
>>> from callcut.io import CallDataset, scan_recordings
>>> from torch.utils.data import DataLoader
>>>
>>> extractor = SNRExtractor(sample_rate=32000, hop_ms=8.0, n_bands=8)
>>> recordings = scan_recordings(list(Path("data/").glob("*.wav")))
>>> dataset = CallDataset(
...     recordings=recordings,
...     extractor=extractor,
...     window_s=2.0,
...     window_hop_s=0.5,
... )
>>> len(dataset)
1250
>>> X, y = dataset[0]
>>> X.shape  # (n_bands, window_frames)
torch.Size([8, 250])

compute_pos_weight()

Compute positive class weight for imbalanced data.

Useful for torch.nn.BCEWithLogitsLoss(pos_weight=...).

Returns:

pos_weightTensor of shape (1,)

Weight for positive class: n_negative / n_positive.

Notes

This method loads all recordings to compute exact label statistics. For large datasets, this may take some time.

property extractor

Feature extractor used by this dataset.

Type:

BaseExtractor

property n_recordings

Number of recordings in the dataset.

Type:

int

property n_windows

Total number of windows (samples).

Type:

int

property recordings

Recordings in this dataset.

Type:

list of RecordingInfo

property window_frames

Window length in frames.

Type:

int

property window_hop_frames

Window hop in frames.

Type:

int

property window_hop_s

Window hop in seconds.

Type:

float

property window_s

Window length in seconds.

Type:

float