SONIC API

Subpackages

• sonicdb.database package
  • Submodules
  • sonicdb.database.base module
  • sonicdb.database.channel module
    • Channel
      • Channel.id
      • Channel.number
      • Channel.type_class
      • Channel.gain
      • Channel.sensor_id
      • Channel.sensor
      • Channel.files
      • Channel.samples
      • Channel.events
      • Channel.dict()
      • Channel.events
      • Channel.files
      • Channel.gain
      • Channel.get_end()
      • Channel.get_start()
      • Channel.id
      • Channel.number
      • Channel.samples
      • Channel.sensor
      • Channel.sensor_id
      • Channel.type_class
  • sonicdb.database.event module
    • Event
      • Event.id
      • Event.name
      • Event.start
      • Event.end
      • Event.description
      • Event.subject_id
      • Event.subject
      • Event.samples
      • Event.channels
      • Event.channels
      • Event.description
      • Event.end
      • Event.id
      • Event.name
      • Event.samples
      • Event.start
      • Event.subject
      • Event.subject_id
    • EventChannel
      • EventChannel.event_id
      • EventChannel.event
      • EventChannel.channel_id
      • EventChannel.channel
      • EventChannel.channel
      • EventChannel.channel_id
      • EventChannel.event
      • EventChannel.event_id
  • sonicdb.database.sample module
    • Sample
      • Sample.id
      • Sample.event_id
      • Sample.event
      • Sample.sensor_id
      • Sample.sensor
      • Sample.channel_id
      • Sample.channel
      • Sample.subject_id
      • Sample.subject
      • Sample.datetime
      • Sample.file_id
      • Sample.file
      • Sample.channel
      • Sample.channel_id
      • Sample.datetime
      • Sample.event
      • Sample.event_id
      • Sample.file
      • Sample.file_id
      • Sample.get_audio()
      • Sample.id
      • Sample.sensor
      • Sample.sensor_id
      • Sample.subject
      • Sample.subject_id
  • sonicdb.database.sensor module
    • Sensor
      • Sensor.id
      • Sensor.name
      • Sensor.subname
      • Sensor.manufacturer
      • Sensor.type_class
      • Sensor.number_of_channels
      • Sensor.channels
      • Sensor.samples
      • Sensor.files
      • Sensor.channels
      • Sensor.files
      • Sensor.id
      • Sensor.manufacturer
      • Sensor.name
      • Sensor.number_of_channels
      • Sensor.samples
      • Sensor.subname
      • Sensor.type_class
  • sonicdb.database.subject module
    • Subject
      • Subject.id
      • Subject.name
      • Subject.samples
      • Subject.events
      • Subject.events
      • Subject.id
      • Subject.name
      • Subject.samples
  • Module contents

Submodules

sonicdb.audio module

class sonicdb.audio.Audio(filepath=None, audio=None, sample_rate=None, start=None)

Bases: object

A class for handling audio files, providing functionalities such as loading, trimming, resampling, filtering, and visualization.

filepath

Path to the audio file.

Type:

str

filename

Name of the audio file.

Type:

str

audio

Audio data as a NumPy array.

Type:

np.ndarray

sample_rate

Sampling rate of the audio.

Type:

int

duration

Duration of the audio in seconds.

Type:

float

length

Length of the audio data in samples.

Type:

int

metadata

Metadata of the audio file.

Type:

dict

extension

File extension of the audio file.

Type:

str

data

DataFrame containing audio signal and time-related information.

Type:

pd.DataFrame

start

Start time of the audio.

Type:

datetime

end

End time of the audio.

Type:

datetime

add_data(filepath)

Append audio data from another file to the current audio object.

Parameters:

filepath (str) – Path to the audio file to append.

bandpass_filter(lowcut, highcut, order=4, type='sos', overwrite=False)

Apply a bandpass Butterworth filter to the audio.

Parameters:

• lowcut (int) – Low cutoff frequency in Hz.

• highcut (int) – High cutoff frequency in Hz.

• order (int, optional) – Filter order. Defaults to 4.

• type (str, optional) – Filter type (‘sos’ or ‘ab’). Defaults to “sos”.

• overwrite (bool, optional) – Whether to overwrite the current audio. Defaults to False.

Returns:

Filtered audio if overwrite is False.

Return type:

list | None

envelope(overwrite=False)

Compute the envelope of the audio signal using the Hilbert transform.

Parameters:

overwrite (bool, optional) – Whether to overwrite the current audio. Defaults to False.

Returns:

Envelope of the audio signal.

Return type:

np.ndarray

fade_in(fade_time=0.1, window='hann', overwrite=False)

Apply a fade-in effect to the audio.

Parameters:

• fade_time (float, optional) – Duration of the fade-in effect in seconds. Defaults to 0.1.

• window (str, optional) – Window function to use. Defaults to “hann”.

• overwrite (bool, optional) – Whether to overwrite the current audio. Defaults to False.

Returns:

Audio with fade-in effect if overwrite is False.

Return type:

np.ndarray | None

fade_out(fade_time=0.1, window='hann', overwrite=False)

Apply a fade-out effect to the audio.

Parameters:

• fade_time (float, optional) – Duration of the fade-out effect in seconds. Defaults to 0.1.

• window (str, optional) – Window function to use. Defaults to “hann”.

• overwrite (bool, optional) – Whether to overwrite the current audio. Defaults to False.

Returns:

Audio with fade-out effect if overwrite is False.

Return type:

np.ndarray | None

highpass_filter(cutoff, order=4, overwrite=False, type='sos')

Apply a highpass Butterworth filter to the audio.

Parameters:

• cutoff (int) – Cutoff frequency in Hz.

• order (int, optional) – Filter order. Defaults to 4.

• overwrite (bool, optional) – Whether to overwrite the current audio. Defaults to False.

• type (str, optional) – Filter type (‘sos’ or ‘ab’). Defaults to “sos”.

Returns:

Filtered audio if overwrite is False.

Return type:

list | None

lowpass_filter(cutoff, order=4, overwrite=False, type='sos')

Apply a lowpass Butterworth filter to the audio.

Parameters:

• cutoff (int) – Cutoff frequency in Hz.

• order (int, optional) – Filter order. Defaults to 4.

• overwrite (bool, optional) – Whether to overwrite the current audio. Defaults to False.

• type (str, optional) – Filter type (‘sos’ or ‘ab’). Defaults to “sos”.

Returns:

Filtered audio if overwrite is False.

Return type:

list | None

plot_envelope(time_format='datetime')

Plot the envelope of the audio signal.

Parameters:

time_format (str, optional) – Format of the time axis (‘datetime’, ‘samples’, ‘seconds’, ‘ms’). Defaults to “datetime”.

Returns:

Figure and axis objects.

Return type:

tuple

plot_melspectrogram(window='hann', nmels=8192, window_size=8192, nfft=8192, noverlap=4096, nperseg=8192, zmin=None, zmax=None, gain=0, showscale=False, cmap='jet', aspect='auto', time_format='datetime', ax=None, fmin=0, fmax=None)

Plot the mel spectrogram of the audio.

Parameters:

• window (str, optional) – Window function to use. Defaults to “hann”.

• nmels (int, optional) – Number of mel bands to generate. Defaults to 8192.

• window_size (int, optional) – Size of the window in samples. Defaults to 8192.

• nfft (int, optional) – Number of FFT points. Defaults to 8192.

• noverlap (int, optional) – Number of overlapping samples. Defaults to 4096.

• nperseg (int, optional) – Number of samples per segment. Defaults to 8192.

• zmin (int, optional) – Minimum z-value for color scale. Defaults to None.

• zmax (int, optional) – Maximum z-value for color scale. Defaults to None.

• gain (int, optional) – Gain to apply to the spectrogram. Defaults to 0.

• showscale (bool, optional) – Whether to show color scale. Defaults to False.

• cmap (str, optional) – Colormap to use. Defaults to “jet”.

• aspect (str, optional) – Aspect ratio. Defaults to “auto”.

• time_format (str, optional) – Format of the time axis (‘datetime’, ‘samples’, ‘seconds’, ‘ms’). Defaults to “datetime”.

• ax (matplotlib.axes.Axes, optional) – Axis object to plot on. Defaults to None.

• fmin (int, optional) – Minimum frequency. Defaults to 0.

• fmax (int, optional) – Maximum frequency. Defaults to None.

Returns:

Figure and axis objects if a figure is created.

Return type:

tuple

plot_psd(window_size=4096)

Plot the power spectral density (PSD) of the audio.

Parameters:

window_size (int, optional) – Size of the window in samples. Defaults to 4096.

Returns:

Figure and axis objects.

Return type:

tuple

plot_spectrogram(window='hann', window_size=8192, nfft=8192, noverlap=4096, nperseg=8192, zmin=None, zmax=None, gain=0, showscale=False, cmap='jet', aspect='auto', time_format='datetime', fig=None, ax=None)

Plot the spectrogram of the audio.

Parameters:

• window (str, optional) – Window function to use. Defaults to “hann”.

• window_size (int, optional) – Size of the window in samples. Defaults to 8192.

• nfft (int, optional) – Number of FFT points. Defaults to 8192.

• noverlap (int, optional) – Number of overlapping samples. Defaults to 4096.

• nperseg (int, optional) – Number of samples per segment. Defaults to 8192.

• zmin (int, optional) – Minimum z-value for color scale. Defaults to None.

• zmax (int, optional) – Maximum z-value for color scale. Defaults to None.

• gain (int, optional) – Gain to apply to the spectrogram. Defaults to 0.

• showscale (bool, optional) – Whether to show color scale. Defaults to False.

• cmap (str, optional) – Colormap to use. Defaults to “jet”.

• aspect (str, optional) – Aspect ratio. Defaults to “auto”.

• time_format (str, optional) – Format of the time axis (‘datetime’, ‘samples’, ‘seconds’, ‘ms’). Defaults to “datetime”.

• fig (matplotlib.figure.Figure, optional) – Figure object to plot on. Defaults to None.

• ax (matplotlib.axes.Axes, optional) – Axis object to plot on. Defaults to None.

Returns:

Figure and axis objects if a figure is created.

Return type:

tuple

plot_waveform(time_format='datetime', ax=None)

Plot the waveform of the audio.

Parameters:

• time_format (str, optional) – Format of the time axis (‘datetime’, ‘samples’, ‘seconds’, ‘ms’). Defaults to “datetime”.

• ax (matplotlib.axes.Axes, optional) – Axis object to plot on. Defaults to None.

Returns:

Figure and axis objects if a figure is created.

Return type:

tuple

psd(window_size=4096)

Compute the power spectral density (PSD) of the audio.

Parameters:

window_size (int, optional) – Size of the window in samples. Defaults to 4096.

Returns:

Frequency and power values.

Return type:

tuple

resample(sample_rate)

Resample the audio to a new sample rate.

Parameters:

sample_rate (int) – Target sample rate.

Return type:

None

spectrogram(window='hann', window_size=8192, nfft=8192, noverlap=4096, nperseg=8192, time_format='datetime')

Generate a spectrogram of the audio.

Parameters:

• window (str, optional) – Window function to use. Defaults to “hann”.

• window_size (int, optional) – Size of the window in samples. Defaults to 8192.

• nfft (int, optional) – Number of FFT points. Defaults to 8192.

• noverlap (int, optional) – Number of overlapping samples. Defaults to 4096.

• nperseg (int, optional) – Number of samples per segment. Defaults to 8192.

• time_format (str, optional) – Format of the time axis (‘datetime’, ‘samples’, ‘seconds’, ‘ms’). Defaults to “datetime”.

Returns:

Time, frequency, and power spectral density (Pxx).

Return type:

tuple

trim(start, end=None, length=None, time_format='datetime', restart=False)

Trim the audio to a specified start and end time or length.

Parameters:

• start (datetime | str | float | int) – Start time of the trim.

• end (datetime | str | float | int, optional) – End time of the trim. Defaults to None.

• length (float, optional) – Length of the trimmed audio in seconds, milliseconds, or samples. Defaults to None.

• time_format (str, optional) – Format of the time (‘datetime’, ‘samples’, ‘seconds’, ‘ms’). Defaults to “datetime”.

• restart (bool, optional) – Whether to reset the time indices. Defaults to False.

Returns:

A new Audio object with the trimmed data.

Return type:

Audio

write_audio(filepath)

Write the audio data to a file.

Parameters:

filepath (str) – Path to save the audio file. The file will be saved as a WAV file.

Return type:

None

sonicdb.audio.autocorrelation(signal)

sonicdb.audio.average_hold(data, window=1024, sample_rate=24000)

sonicdb.audio.butter_bandpass(lowcut, highcut, fs, order=5, type='sos')

Design a bandpass Butterworth filter.

Parameters:

• lowcut (float) – Low cutoff frequency in Hz.

• highcut (float) – High cutoff frequency in Hz.

• fs (float) – Sampling rate in Hz.

• order (int, optional) – Order of the filter. Defaults to 5.

• type (str, optional) – Type of the filter (‘sos’ or ‘ab’). Defaults to “sos”.

Returns:

Filter coefficients.

Return type:

np.ndarray | tuple

sonicdb.audio.butter_bandpass_filter(data, lowcut, highcut, fs, order=5, type='sos')

Apply a bandpass Butterworth filter to the data.

Parameters:

• data (array-like) – Input data to be filtered.

• lowcut (float) – Low cutoff frequency in Hz.

• highcut (float) – High cutoff frequency in Hz.

• fs (float) – Sampling rate in Hz.

• order (int, optional) – Order of the filter. Defaults to 5.

• type (str, optional) – Type of the filter (‘sos’ or ‘ab’). Defaults to “sos”.

Returns:

Filtered data.

Return type:

array-like

sonicdb.audio.butter_highpass(cutoff, fs, order=5, type='sos')

Design a highpass Butterworth filter.

Parameters:

• cutoff (float) – Cutoff frequency in Hz.

• fs (float) – Sampling rate in Hz.

• order (int) – Order of the filter.

• type (str, optional) – Type of the filter (‘sos’ or ‘ab’). Defaults to “sos”.

Returns:

Filter coefficients.

Return type:

np.ndarray | tuple

sonicdb.audio.butter_highpass_filter(data, cutoff, fs, order=5, type='sos')

Apply a highpass Butterworth filter to the data.

Parameters:

• data (array-like) – Input data to be filtered.

• cutoff (float) – Cutoff frequency in Hz.

• fs (float) – Sampling rate in Hz.

• order (int, optional) – Order of the filter. Defaults to 5.

• type (str, optional) – Type of the filter (‘sos’ or ‘ab’). Defaults to “sos”.

Returns:

Filtered data.

Return type:

array-like

sonicdb.audio.butter_lowpass(cutoff, fs, order, type='sos')

Design a lowpass Butterworth filter.

Parameters:

• cutoff (float) – Cutoff frequency in Hz.

• fs (float) – Sampling rate in Hz.

• order (int) – Filter order.

• type (str, optional) – Filter type (‘sos’ or ‘ab’). Defaults to “sos”.

Returns:

Filter coefficients.

Return type:

np.ndarray | tuple

sonicdb.audio.butter_lowpass_filter(data, cutoff, fs, order=5, type='sos')

Apply a lowpass Butterworth filter to the data.

Parameters:

• data (array-like) – Input data to be filtered.

• cutoff (float) – Cutoff frequency in Hz.

• fs (float) – Sampling rate in Hz.

• order (int, optional) – Order of the filter. Defaults to 5.

• type (str, optional) – Type of the filter (‘sos’ or ‘ab’). Defaults to “sos”.

Returns:

Filtered data.

Return type:

array-like

sonicdb.audio.combine_audio(list_of_files)

Combine multiple audio files into one.

Parameters:

list_of_files (list) – List of file paths to combine.

Returns:

Combined audio object.

Return type:

Audio

sonicdb.audio.echo(data, sample_rate, delay=0.1, decay=0.5)

Adds echo to audio data.

Parameters:

• data (array | np.array | pd.Series) – audio data to add echo to

• sample_rate (int | float) – sample rate of audio data

• delay (int | float, optional) – delay in the echo. Defaults to 0.1.

• decay (int | float, optional) – decay of the echo. Defaults to 0.5.

Returns:

_description_

Return type:

list|np.array|pd.Series

sonicdb.audio.fade_in(data, sample_rate, fade_time=0.1, window='hann')

sonicdb.audio.fade_out(data, sample_rate, fade_time=0.1, window='hann')

sonicdb.audio.mp3_to_wav(input, output, output_format='wav')

Converts mp3 file to wav file.

Parameters:

• file (file) – filepath of input

• output (str) – filepath of output

• output_format (str, optional) – Output format. Defaults to “wav”.

• input (str)

Return type:

None

sonicdb.audio.peak_hold(data, window=8192, sample_rate=24000)

sonicdb.audio.psd(x, sample_rate, window_size=4096, window='blackmanharris', scaling='spectrum', time_format='amplitude')

Parameters:

• x (list)

• sample_rate (int)

• window_size (int)

• window (str)

• scaling (str)

Return type:

tuple

sonicdb.audio.psd2(x, sample_rate, window_size=4096)

Compute the power spectral density of a signal.

Parameters:

• x (array) – signal

• sample_rate (int) – sample rate of the signal

• sample_window (int, optional) – length of the window to use for the FFT. Defaults to 4096.

• window_size (int)

Returns:

power spectral density

Return type:

tuple

sonicdb.audio.spectral_subtraction(signal, noise, scaling_factor=1.0)

Perform spectral subtraction with optional scaling of the noise spectrum.

Parameters:

• signal (array-like) – The input signal.

• noise (array-like) – The noise signal.

• scaling_factor (float) – A factor to scale the noise spectrum before subtraction.

Returns:

The cleaned signal after spectral subtraction.

Return type:

array-like

sonicdb.audio.spectrogram(data, sample_rate, window_size=8192, window='hann', nfft=4096, noverlap=4096, nperseg=8192, time_format='datetime', start=None, end=None)

Generates spectrogram of audio

Parameters:

• data (list or pd.Series) – Data to generate spectrogram of

• sample_rate (int) – Sample rate of data

• window_size (int, optional) – Window size in samples. Defaults to 8192.

• nfft (int, optional) – FFT number. Defaults to 4096.

• noverlap (int, optional) – Overlap amount in samples. Defaults to 4096.

• nperseg (int, optional) – Number of samples per segment. Defaults to 8192.

• start (datetime, optional) – Start time. Defaults to None.

• end (datetime, optional) – End time. Defaults to None.

• time_format (str)

Returns:

time, frequency, Pxx

Return type:

tuple

sonicdb.audio.wavelet_denoise(signal, wavelet='db4', level=4)

sonicdb.audio.write_audio(data, filepath, sample_rate)

Writes audiofile of data with set samplerate. Omit extension, will output only wav.

Parameters:

• data (list or pd.Series) – data to output

• filepath (str) – filepath of output

• sample_rate (int) – desired file sample rate

Return type:

None

sonicdb.models module

sonicdb.sonic module

class sonicdb.sonic.Database(db)

Bases: object

SONIC Database class

Parameters:

db (str)

get_audio(start=None, end=None, event=None, sensor=None, channel=None, channel_number=None)

Get audio data from the database.

Parameters:

• start (datetime) – Start time of the audio data.

• end (datetime) – End time of the audio data.

• event (Event) – Event object to get the audio data from.

• sensor (Sensor) – Sensor object to get the audio data from.

• channel (Channel) – Channel object to get the audio data from.

• channel_number (int) – Channel number to get the audio data from.

Returns:

Audio object containing the audio data.

Return type:

audio.Audio

get_channel(channel, sensor=None)

Get a channel from the database.

Parameters:

• channel (Channel | int | dict[str, int]) – Channel object, channel ID, or channel details as a dictionary. If a dictionary is passed, it should contain the key “number”.

• sensor (Sensor | None) – Sensor object or sensor ID associated with the channel.

Returns:

Channel object if found, None otherwise.

Return type:

Channel | None

get_sensor(sensor)

Get a sensor from the database.

Parameters:

sensor (Sensor | int | dict[str, int] | str) – Sensor object, sensor ID, or sensor name. If a dictionary is passed, it should contain the keys “name” and “subname”.

Returns:

Sensor object if found, None otherwise.

Return type:

Sensor | None

get_subject(subject)

Get a subject from the database.

Parameters:

subject (Subject | int | dict[str, int] | str) – Subject object, subject ID, or subject name. If a dictionary is passed, it should contain the key “name”.

Returns:

Subject object if found, None otherwise.

Return type:

Subject | None

sample_database(duration=60, overlap=0, events_only=False, to_file=False)

Populates the sample table with the audio data segmented by the specified duration and overlap.

Parameters:

• duration (int, optional) – Duration of each sample in seconds. Defaults to 60.

• overlap (int, optional) – Overlap between samples in seconds. Defaults to 0.

• events_only (bool)

• to_file (bool)

Return type:

None

session

Inherits the DBSession class from SQLAlchemy. Available here.

sonicdb.utilities module

sonicdb.utilities.lower_keys(tree)

Normalize a dictionary to have lowercase and snake_case keys.

Parameters:

tree (dict) – Dictionary to normalize.

Returns:

Normalized dictionary.

Return type:

dict[str, int]

sonicdb.utilities.metadata(filepath, extended=False)

Generate metadata for a file.

Parameters:

• filepath (str) – Filepath of the file.

• extended (bool, optional) – Whether to include extended metadata. Defaults to False.

Returns:

Metadata of the file.

Return type:

dict

sonicdb.utilities.metadatas(filepaths, extended=False, stevens=False)

Generate metadata for multiple files.

Parameters:

• filepaths (list) – List of filepaths.

• extended (bool, optional) – Whether to include extended metadata. Defaults to False.

• stevens (bool, optional) – Whether to adjust metadata for Stevens’ format. Defaults to False.

Returns:

Metadata of the files.

Return type:

pd.DataFrame

sonicdb.utilities.read_datetime(string)

Read and convert a datetime string to a datetime object.

Parameters:

string (str) – Datetime string to convert.

Returns:

Converted datetime object.

Return type:

datetime

Module contents

sonicdb.