base

audioclass.batch.base

Module for defining base classes and functions for batch processing.

This module provides abstract classes and utility functions for creating iterators that generate batches of audio data from various sources, such as lists of files, directories, or pandas DataFrames. These iterators are designed to be used with audio classification models to process large amounts of audio data efficiently.

Classes:

Name	Description
BaseIterator	Abstract base class for audio batch iterators.

Functions:

Name	Description
recordings_from_dataframe	Create a list of Recording objects from a pandas DataFrame.
recordings_from_directory	Create a list of Recording objects from audio files in a directory.
recordings_from_files	Create a list of Recording objects from a list of file paths.

Attributes:

Name	Type	Description
Batch	TypeAlias	A single batch of audio data consisting of:
BatchGenerator	TypeAlias	A generator that yields batches of audio data.

Attributes

AudioArray: TypeAlias = np.ndarray module-attribute

A 2D array of audio samples of shape (batch_size, n_samples).

Batch: TypeAlias = Tuple[AudioArray, List[data.Recording], FrameArray] module-attribute

A single batch of audio data consisting of:

• AudioArray: The audio data as a numpy array.
• List[data.Recording]: The corresponding list of Recording objects.
• FrameArray: The frame indices for each audio clip in the batch.

BatchGenerator: TypeAlias = Generator[Batch, None, None] module-attribute

A generator that yields batches of audio data.

FrameArray: TypeAlias = np.ndarray module-attribute

A 1D array of frame indices of shape (batch_size, ).

These numbers correspond to the frame number in the audio file. In case an audio file is split into multiple frames, this number will be the frame number.

IndexArray: TypeAlias = np.ndarray module-attribute

A 1D array of indices of shape (batch_size, ).

These indices correspond to the index of the file in the list of files being iterated over.

Classes

BaseIterator(recordings, samplerate, input_samples, batch_size=BATCH_SIZE, audio_dir=None)

Bases: ABC

Abstract base class for audio batch iterators.

This class defines the common interface for iterators that generate batches of audio data from different sources. It provides methods for creating iterators from files, directories, and pandas DataFrames.

Parameters:

Name	Type	Description	Default
recordings	List[Recording]	A list of Recording objects representing the audio files to be processed.	required
samplerate	int	The target sample rate for resampling the audio data (in Hz).	required
input_samples	int	The number of samples per audio frame.	required
batch_size	int	The number of audio frames per batch. Defaults to BATCH_SIZE.	BATCH_SIZE
audio_dir	Optional[Path]	The directory containing the audio files. Defaults to None.	None

Methods:

Name	Description
from_dataframe	Create a batch iterator from a pandas DataFrame.
from_directory	Create a batch iterator from a directory of audio files.
from_files	Create a batch iterator from a list of audio files.

Attributes:

Name	Type	Description
audio_dir	Optional[Path]	The directory containing the audio files.
batch_size	int	The number of audio frames per batch.
input_samples	int	The number of samples per audio frame.
recordings	List[Recording]	The list of Recording objects to be processed.
samplerate	int	The target sample rate for resampling the audio data (in Hz).

Attributes

audio_dir: Optional[Path] = audio_dir instance-attribute

The directory containing the audio files.

batch_size: int = batch_size instance-attribute

The number of audio frames per batch.

input_samples: int = input_samples instance-attribute

The number of samples per audio frame.

recordings: List[data.Recording] = recordings instance-attribute

The list of Recording objects to be processed.

samplerate: int = samplerate instance-attribute

The target sample rate for resampling the audio data (in Hz).

Functions

from_dataframe(df, samplerate, input_samples, batch_size=BATCH_SIZE, audio_dir=None, path_col='path', latitude_col='latitude', longitude_col='longitude', recorded_on_col='recorded_on', additional_cols=None) classmethod

Create a batch iterator from a pandas DataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	A DataFrame containing information about the audio files.	required
samplerate	int	The target sample rate for resampling the audio data (in Hz).	required
input_samples	int	The number of samples per audio frame.	required
batch_size	int	The number of audio frames per batch. Defaults to BATCH_SIZE.	BATCH_SIZE
audio_dir	Optional[Path]	The directory containing the audio files. Defaults to None.	None
path_col	str	The name of the column in the DataFrame containing the paths to the audio files. Defaults to "path".	'path'
latitude_col	Optional[str]	The name of the column in the DataFrame containing the latitudes of the recording locations. Defaults to "latitude".	'latitude'
longitude_col	Optional[str]	The name of the column in the DataFrame containing the longitudes of the recording locations. Defaults to "longitude".	'longitude'
recorded_on_col	Optional[str]	The name of the column in the DataFrame containing the recording timestamps. Defaults to "recorded_on".	'recorded_on'
additional_cols	Optional[list[str]]	A list of additional columns in the DataFrame to include as tags in the Recording objects. Defaults to None.	None

Returns:

Type	Description
BaseIterator	A batch iterator for the audio files specified in the DataFrame.

from_directory(directory, samplerate, input_samples, batch_size=BATCH_SIZE, recursive=True) classmethod

Create a batch iterator from a directory of audio files.

Parameters:

Name	Type	Description	Default
directory	Path	The path to the directory containing the audio files.	required
samplerate	int	The target sample rate for resampling the audio data (in Hz).	required
input_samples	int	The number of samples per audio frame.	required
batch_size	int	The number of audio frames per batch. Defaults to BATCH_SIZE.	BATCH_SIZE
recursive	bool	Whether to search for audio files recursively in subdirectories. Defaults to True.	True

Returns:

Type	Description
BaseIterator	A batch iterator for the audio files in the specified directory.

from_files(files, samplerate, input_samples, batch_size=BATCH_SIZE, audio_dir=None) classmethod

Create a batch iterator from a list of audio files.

Parameters:

Name	Type	Description	Default
files	List[Path]	A list of paths to the audio files.	required
samplerate	int	The target sample rate for resampling the audio data (in Hz).	required
input_samples	int	The number of samples per audio frame.	required
batch_size	int	The number of audio frames per batch. Defaults to BATCH_SIZE.	BATCH_SIZE
audio_dir	Optional[Path]	The directory containing the audio files. Defaults to None.	None

Returns:

Type	Description
BaseIterator	A batch iterator for the specified audio files.

Functions

recordings_from_dataframe(df, path_col='path', latitude_col='latitude', longitude_col='longitude', recorded_on_col='recorded_on', additional_cols=None)

Create a list of Recording objects from a pandas DataFrame.

The DataFrame should contain a column with file paths (specified by path_col), and optionally columns for latitude, longitude, recorded_on timestamp, and any additional columns to be included as tags in the Recording objects.

Parameters:

Name	Type	Description	Default
df	DataFrame	A pandas DataFrame containing information about the audio files.	required
path_col	str	The name of the column containing the file paths. Defaults to "path".	'path'
latitude_col	Optional[str]	The name of the column containing the latitudes. Defaults to "latitude".	'latitude'
longitude_col	Optional[str]	The name of the column containing the longitudes. Defaults to "longitude".	'longitude'
recorded_on_col	Optional[str]	The name of the column containing the recorded_on timestamps. Defaults to "recorded_on".	'recorded_on'
additional_cols	Optional[list[str]]	A list of additional column names to include as tags in the Recording objects. Defaults to None.	None

Returns:

Type	Description
List[Recording]	A list of Recording objects corresponding to the rows in the DataFrame.

Raises:

Type	Description
ValueError	If the DataFrame does not contain the required columns.

recordings_from_directory(directory, recursive=True)

Create a list of Recording objects from audio files in a directory.

Parameters:

Name	Type	Description	Default
directory	Path	The path to the directory containing the audio files.	required
recursive	bool	Whether to search for audio files recursively in subdirectories. Defaults to True.	True

Returns:

Type	Description
List[Recording]	A list of Recording objects corresponding to the audio files found in the directory.

recordings_from_files(files)

Create a list of Recording objects from a list of file paths.

Parameters:

Name	Type	Description	Default
files	List[Path]	A list of paths to audio files.	required

Returns:

Type	Description
List[Recording]	A list of Recording objects corresponding to the input files.