Analysis result aggregation

class soundscape_IR.soundscape_viewer.soundscape_viewer.data_organize

Aggregate analysis results of long-term spectrograms.

In soundscape ecology, we often want to investigate the diurnal and seasonal variations of geophony, biophony, and anthropophony. This class provides a set of methods to aggregate the analysis results of long-term spectrograms, such as the relative intensities produced from source separation procedures or clusters identified using an unsupervised learning algorithm.

At first, use a source separation model or clustering algorithm to analyze long-term spectrograms collected from the same recording site. Then, enter the array of segment time of spectrogram data and the associated analysis result. This class will automatically scan the data, calculate the duty cycle (according to the time difference between the first two segments), and fill the recording gaps. Once a column has been inserted, a heatmap can be generated to visualize changes in diurnal (y-axis) and seasonal (x-axis) cycles.

After repeating these procedures for multiple analysis results, the organized results can be saved in a csv file for further applications.

Examples

>>> from soundscape_IR.soundscape_viewer import data_organize
>>> analysis_result=data_organize()
>>>
>>> # Sound intensities of the median-based LTS
>>> analysis_result.time_fill(time_vec=model.time_vec, data=model.original_level, header='LTS_Median_Level')
>>> analysis_result.plot_diurnal(col=1)
>>>
>>> # Relative intensities of the first sound source
>>> analysis_result.time_fill(time_vec=model.time_vec, data=model.relative_level[0], header='Source1_Level')
>>> analysis_result.plot_diurnal(col=2)
>>>
>>> # Relative intensities of the second sound source
>>> analysis_result.time_fill(time_vec=model.time_vec, data=model.relative_level[1], header='Source2_Level')
>>> analysis_result.plot_diurnal(col=3)
>>>
>>> # Clusters of the first sound source
>>> analysis_result.time_fill(time_vec=cluster_result_S1.time_vec, data=cluster_result_S1.cluster, header='Source1_Cluster')
>>> analysis_result.plot_diurnal(col=4)
>>>
>>> # Clusters of the second sound source
>>> analysis_result.time_fill(time_vec=cluster_result_S2.time_vec, data=cluster_result_S2.cluster, header='Source2_Cluster')
>>> analysis_result.plot_diurnal(col=5)
>>>
>>> # Save analysis results in a csv file
>>> analysis_result.save_csv(filename='Analysis_result.csv')

Methods

plot_diurnal([col, day_correct, vmin, vmax, ...])	Generate a heatmap for visualizing soundscape changes in diurnal and seasonal cycles.
remove_column(col)	Remove a column of analysis result.
save_csv([filename, folder_id])	Save the analysis results to a csv file.
time_fill(time_vec, data, header[, value_input])	Create a new column for the input analsis result and fill the recording gaps (if any).

plot_diurnal(col=1, day_correct=0, vmin=None, vmax=None, fig_width=16, fig_height=6, empty_hr_remove=False, empty_day_remove=False, reduce_resolution=1, display_cluster=None, plot=True, nan_value=0)

Generate a heatmap for visualizing soundscape changes in diurnal and seasonal cycles.

Y-axis is the 24 hours and x-axis is the recording days of the input data.

Parameters

colint ≥ 1

Column number to plot.

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.

vmin, vmaxNone or float, default = None

The data range that the colormap covers.

By default (None), the colormap covers the complete value range of the long-term spectrogram.

fig_width, fig_heightfloat > 0

Figure width and height.

empty_hr_removeboolean, default = False

Set to True when there are known repetitive recording gaps among the 24-hr cycle.

empty_day_removeboolean, default = False

Set to True when there are known repetitive recording gaps among the seasonal cycle.

reduce_resolutionint > 1

Reduce the time resolution of y-axis (hour).

If the time resolution of long-term spectrogram is 5 min, set reduce_resolution to 6 will change the resolution hour axis to 30 min.

display_clusterint > 0

For clustering result, enter a specific cluster number to plot its presence and absence.

plotboolean, default = True

Set to False for not making a figure.

nan_valueNaN or float

Same as value_input, allowing the program to recognize segments without recording efforts.

Returns

plot_matrixndarray of shape (day, hour)

Matrix of diurnal and seasonal variations.

The first column is date, and the subsequent columns are values associated with hr.

hrndarray of shape (hour,)

Hour segments of the matrix of diurnal and seasonal variations.

remove_column(col)

Remove a column of analysis result.

Parameters

colint ≥ 1

Column number to remove.

Note that column 0 represents the Time column, which cannot be removed.

save_csv(filename='Soundscape_analysis.csv', folder_id=[])

Save the analysis results to a csv file.

Parameters

filenamestr, default = ‘Soundscape_analysis.csv’

Name of the csv file.

folder_id[] or str, default = []

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

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

time_fill(time_vec, data, header, value_input=0)

Create a new column for the input analsis result and fill the recording gaps (if any).

Parameters

time_vecndarray of shape (time,)

Array of segment time.

datandarray of shape (time,)

Array of analysis result.

The dimension of data should be the same as time_vec.

headerstr

Name of the input data.

value_inputNaN or float, default = 0

If recording gaps exist, this method will fill the recording gaps with the input value.