Long-term spectrogram maker

class soundscape_IR.soundscape_viewer.lts_maker.lts_maker(sensitivity=0, channel=1, environment='wat', FFT_size=512, initial_skip=0, time_resolution=None)[source]

Making a long-term spectrogram to investigate the temporal and spectral variations of long-duration recordings.

This class generates a visualization of long-duration recordings called long-term spectrogram. Before running this program, copy a set of recordings obtained from the same recorder (presumably at the same location) to a folder. There are three procedures for making a long-term spectrogram. First, recordings are divided into short segments. Next, each segment is transformed into a spectrogram using discrete Fourier transform (DFT), and each spectrogram is compressed into a vector of power spectrum according to two statistical measurements (median and mean) to retain spectral variation. Finally, all power spectra are concatenated and saved as a mat file.

Parameters

sensitivityfloat, default = 0

Sensitivity of recording system (in dB re 1 V /μPa).

Use 0 when sensitivity is not available.

channelint ≥ 1, default = 1

Recording channel for analysis.

In stereo recordings, set to 1 for the left channel and set to 2 for the right channel.

environment{‘wat’, ‘air’}, default = ‘wat’

Recording environment (underwater or in air) of the audio file.

FFT_sizeint > 0, default = 512

Window size to perform discrete Fourier transform (in samples).

initial_skipfloat ≥ 0, default = 0

Initial duration (in seconds) of each audio recording to skip the audio analysis.

Some autonomous recorders, e.g., SoundTrap, support the function to investigate changes in microphone/hydrophone sensitivity by generating calibration tones in the beginning of each recording session. Use this parameter for removing the fragment containing calibration tones.

time_resolutionNone or float > 0, default = None

Time resolution of a long-term spectrogram (in seconds).

For each audio recording, lts_maker generates one power spectrum for each fragment according to time_resolution. However, if time_resolution is not set, only one power spectrum is generated for the entire audio recording. In this case, the time_resolution equals the duty cycle of recordings.

Examples

Generate a long-term spectrogram of locally saved audio recordings.

>>> from soundscape_IR.soundscape_viewer import lts_maker
>>> LTS_run=lts_maker(sensitivity=0, channel=1, environment='wat', FFT_size=512, initial_skip=0)
>>> LTS_run.collect_folder(path='./wav/')
>>> LTS_run.filename_check(dateformat='yymmddHHMMSS',initial='1207984160.',year_initial=2000)
>>> LTS_run.run(save_filename='LTS.mat')

Generate an LTS for audio recordings hosted on a Google Drive folder.

>>> from soundscape_IR.soundscape_viewer import lts_maker
>>> LTS_run=lts_maker(sensitivity=0, channel=1, environment='wat', FFT_size=512, initial_skip=0)
>>> LTS_run.collect_Gdrive(folder_id='XXXXXXXXXXXXXXXXXXXXXXXXXXX')
>>> LTS_run.filename_check(dateformat='yyyymm_ddHHMMSS',initial='TW_SiteA_',year_initial=0)
>>> LTS_run.run(save_filename='LTS.mat')

Attributes

fndarray of shape (frequency,)

Frequency of spectrogram data.

Result_medianndarray of shape (time, frequency+1)

Median-based long-term spectrogram.

The first column is time, and the subsequent columns are power spectral densities associated with f.

Result_meanndarray of shape (time, frequency+1)

Mean-based long-term spectrogram.

The first column is time, and the subsequent columns are power spectral densities associated with f.

Methods

`collect_Gdrive`(folder_id[, file_extension, ...])	Specify a Drive folder where the recording files are located.
`collect_folder`(path[, file_extension])	Specify the folder where the recording files are located.
`filename_check`([dateformat, initial, ...])	Check recording time information retrieved from the file name.
`run`([save_filename, folder_id, start, ...])	Initiate analysis procedures.

collect_Gdrive(folder_id, file_extension='.wav', subfolder=False)[source]

Specify a Drive folder where the recording files are located.

Parameters

folder_idstr

The folder ID of Google Drive folder for analysis.

See https://ploi.io/documentation/database/where-do-i-get-google-drive-folder-id for the detial of folder ID.

file_extension{‘.wav’, ‘.WAV’}, default = ‘.wav’

Data format for analysis.

subfolderboolean, default = False

Set to True if subfolders also contain recordings for analysis.

collect_folder(path, file_extension='.wav')[source]

Specify the folder where the recording files are located.

Parameters

folderstr: Folder path for analysis.
file_extension{‘.wav’, ‘.WAV’}, default = ‘.wav’: Data format for analysis.

filename_check(dateformat='yyyymmdd_HHMMSS', initial=[], year_initial=2000, filename=[])[source]

Check recording time information retrieved from the file name.

Enter the filename information to extract the recording date and time from each audio file. For example, if the file name is ‘KT08_20171118_123000.wav’, please enter initial='KT08_' and dateformat='yyyymmdd_HHMMSS'.

If the file name does not contain information of century (when dateformat='yymmdd_HHMMSS'), specify century in year_initial. For example, the recording ‘KT08_171118_123000.wav’ was made in 2017, then set year_initial=2000.

Example 1: TW-LHC01-150102-001530.wav

initial=’TW-LHC01-’
dateformat=’yymmdd-HHMMSS’
year_initial=2000

Example 2: TW-LHC-20150102 001530.wav

initial=’TW-LHC-’
dateformat=’yyyymmdd HHMMSS’
year_initial=0

Example 3: 190730053000.wav

initial=[]
dateformat=’yymmddHHMMSS’
year_initial=2000

Parameters

dateformatstr, default = ‘yyyymmdd_HHMMSS’

Recording date and time format on the file name, such as ‘yymmddHHMMSS’, ‘yyyymmddHHMMSS’, ‘yymmdd_HHMMSS’, ‘yyyymmdd_HHMMSS’.

initial= [] or str, default = []

File name initials before the recording date and time information.

year_initial= {0, 1900, 2000}, default = 2000

Century of recording date.

For dateformat = ‘yymmddHHMMSS’ or ‘yymmdd_HHMMSS’, use this parameter to declare the century in which the recording is made.

Set to 0 if dateformat = ‘yyyymmddHHMMSS’ or ‘yyyymmdd_HHMMSS’.

run(save_filename='LTS.mat', folder_id=[], start=1, num_file=None, duration_read=None)[source]

Initiate analysis procedures.

Parameters

save_filenamestr, default = ‘LTS.mat’

Name of the mat file.

folder_id[] or str, default = []

The folder ID of Google Drive folder for saving analysis result.

See https://ploi.io/documentation/database/where-do-i-get-google-drive-folder-id for the detial of folder ID.

startint ≥ 1, default = 1

The file number to begin LTS analysis.

num_fileNone or int ≥ 1, default = None

The number of files after start for LTS analysis.

duration_readNone or float > 0, default = None

When an audio file is too long (e.g., last several hours), reading the entire audio recording at once may occupy too much memory. Specifying the duration (in seconds) for each read can reduce the memory space used and speed up the analysis.