Long-term spectrogram viewer

class soundscape_IR.soundscape_viewer.soundscape_viewer.lts_viewer(path=None, folder_id=[], f_range=None, time_sort=True, parameter_check=False, subfolder=False)

Using long-term spectrograms to visualize soundscape dynamics.

This class loads a set of long-term spectrograms to analyze soundscape changes. Before running this program, copy a set of mat files (presumably from the same recording site) to a folder. All the mat files will be combined in chronological order. There are three types of long-term spectrograms. According to the statistics used, they can visualize different sound sources (See Lin et al. 2017 for the application of forest soundscapes and Lin et al. 2021 for the application of marine soundscapes).

• Median-based LTS: biological chorus (mass phenomena like frog/bird/insect/fish/crustacean chorus), environmental noise (heavy rainfall, strong waves), and long-duration anthropogenic noise (shipping, traffic, construction).

• Mean-based LTS: all sound sources, including continuous and transient sounds.

• Difference-based LTS (mean-median): high-intensity transient sounds produced from animals (bird songs, whale calls) and human activities.

Parameters

pathNone or str, default = None

Folder path for analysis.

folder_id[] or str, default = []

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.

f_rangeNone or list of 2 scalars [min, max], default = None

Minimum and maximum frequency values of the spectrogram.

time_sortboolean, default = True

Sort the time frames in ascending order. Set to False if long-term spectrograms are collected from multiple sites.

parameter_checkboolean, default = False

Set to True for checking spectrogram parameters (long-term spectrograms will not be combined).

subfolderboolean, default = False

Combine long-term spectrograms from subfolders.

References

1

Lin, T.-H., Wang, Y.-H., Yen, H.-W., Lu, S.-S., Tsao, Y. (2017) Computing biodiversity change via a soundscape monitoring network. PNC 2017 Annual Conference and Joint Meetings. https://doi.org/10.23919/PNC.2017.8203533

2

Lin, T.-H., Akamatsu, T.*, Sinniger, F., Harii, S. (2021) Exploring coral reef biodiversity via underwater soundscapes. Biological Conservation, 253: 108901. https://doi.org/10.1016/j.biocon.2020.108901

Examples

Load mat files from a local folder.

>>> from soundscape_IR.soundscape_viewer import lts_viewer
>>> LTS=lts_viewer(path='D:/Data')
>>> LTS.plot_lts()

Load mat files saved in a Drive folder.

>>> from soundscape_IR.soundscape_viewer import lts_viewer
>>> LTS=lts_viewer(folder_id='XXXXXXXXXXXXXXXXXXXXXXX')
>>> LTS.plot_lts()

Select a specific part of long-term spectrogram and use Plotly interactive heatmap for visualization.

>>> from soundscape_IR.soundscape_viewer import lts_viewer
>>> LTS=lts_viewer(path='D:/Data')
>>> input_data,f=LTS.input_selection('median', begin_date='20160901', end_date='20161001', f_range=[0, 22000], prewhiten_percent=10)
>>>
>>> from soundscape_IR.soundscape_viewer import interactive_matrix
>>> interactive_matrix(input_data, f/1000, y_title='Frequency (kHz)', figure_title='Long-term spectrogram', figure_plot=True, fig_width=800, fig_height=400)

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.

Result_diffndarray of shape (time, frequency+1)

Difference-based long-term spectrogram (mean-median).

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

locationndarray of shape (time, )

Location name of the input long-term spectrograms.

This attribute is only available when subfolder is True.

Methods

input_selection([var_name, begin_date, ...])	Extract a specific part of long-term spectrogram.
plot_lts([day_correct, fig_width, ...])	Plot the three types of long-term spectrograms.

input_selection(var_name='median', begin_date=None, end_date=None, f_range=None, prewhiten_percent=0, gap_fill=False, annotation=None, padding=0, annotation_target=None)

Extract a specific part of long-term spectrogram.

This method selects a specific time period and frequency range from a chosen type of long-term spectrogram. This method also supports the application of spectrogram prewhitening in suppressing background noise.

Parameters

var_name{‘median’, ‘mean’, ‘diff’}, default = ‘median’

Types of long-term spectrogram.

begin_date, end_dateNone or str, default = None

Time period to extract the combined long-term spectrograms.

Format of date and time: ‘yyyymmdd’ or ‘yyyymmdd_HHMMSS’

f_rangeNone or list of 2 scalars [min, max], default = None

Minimum and maximum frequency values of the long-term spectrogram.

prewhiten_percentNone or float [0, 100), default = None

Percentile of power spectral densities in each frequency bin for spectrogram prewhitening.

If prewhiten_percent is not set, spectrogram prewhitening is deactivated.

gap_fillboolean, default = True

Set to True when there are known time gaps among recording files.

Set to False when long-term spectrograms are collected from multiple recording sites.

Returns

input_datandarray of shape (time, frequency+1)

The selected long-term spectrogram.

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

fndarray of shape (frequency,)

Frequency of spectrogram data.

plot_lts(day_correct=0, fig_width=12, fig_height=18, gap_fill=True)

Plot the three types of long-term spectrograms.

Parameters

day_correctfloat or ‘windows’

A value to correct the display date.

There is a known issue that the date displayed in the Windows system is different from Linux system. Set day_correct = 'windows' to solve this issue.

fig_width, fig_heightfloat > 0

Figure width and height.

gap_fillboolean, default = True

Set to True when there are known time gaps among recording files.

Set to False when long-term spectrograms are collected from multiple recording sites.