Visualizations¶

The module visualizations has a collection of functions to create visualizations over sudios and its acoustic indices.

`indices_radar_plot`(df, indices, agg_type[, ...])	Create a radar plot to compare indices in a DataFrame.
`indices_histogram_plot`(df, indices[, ...])	Create histogram plots to visualize the distribution of indices in a DataFrame.
`indices_violin_plot`(df, indices[, group_by, ...])	Create violin plots to visualize the distribution of indices in a DataFrame.
`spectrogram_plot`(file_path[, mode, window, ...])	Create a spectrogram plot from an audio file.
`false_color_spectrogram_plot`(df, ...[, ...])	Generate and optionally display a false color spectrogram from acoustic indices.
`diel_plot`(df, date_col, time_col, ...[, ...])	Create a diel plot (heatmap) based on time and date columns.
`polar_bar_plot`(df, date_time_col, categories_col)	Generate a polar bar plot to visualize category occurrences over the year.
`parallel_coordinates_plot`(df, indices, color_col)	Plots a parallel coordinates chart for comparing acoustic indices for some categorical variable.

maui.visualizations.diel_plot(df, date_col, time_col, duration_col, time_bin_size, color_map_col, agg_type=None, show_plot=True, **kwargs)[source]

Create a diel plot (heatmap) based on time and date columns.

Parameters:

dfpd.DataFrame: Input DataFrame containing date, time, and color mapping columns.
date_colstr: Column name for the date in the DataFrame.
time_colstr: Column name for the time in the DataFrame.
duration_colstr: Column name for the duration of each event in the DataFrame.
time_bin_sizeint: The size of the time bin in minutes. Must be between 1 and 60.
color_map_colstr: Column used to color the plot. Can be numeric or categorical.
agg_typestr, optional: Aggregation type for numeric color_map_col. Default is None.
show_plotbool, optional: Whether to show the plot. Default is True.
**kwargsdict: Additional arguments for plot customization, such as height and width.

Returns:

plotly.graph_objects.Figure: The generated diel plot as a Plotly figure.

Raises:

AttributeError: If the time_bin_size is not between 1 and 60, or if color_map_col is not of numeric or string type.

Warning

UserWarning: If any rows have durations greater than the time_bin_size, or if the date column contains invalid dates.

Examples

>>> from maui import samples, utils, visualizations
>>> df = samples.get_audio_sample(dataset="leec")
>>> def convert_to_seconds(duration_str):
>>> try:
>>>     minutes, seconds = map(int, duration_str.split(':'))
>>>     return minutes * 60 + seconds
>>> except ValueError:
>>>     # Handle the case where the input is not in "mm:ss" format
>>>     raise ValueError(f"Invalid duration format: {duration_str}")
>>>
>>> # Apply the function to the 'duration' column
>>> df = pd.read_csv('xc_data.csv')
>>> df['length'] = df['length'].apply(convert_to_seconds)
>>>
>>> df = df[~df['time'].str.contains(r'?', na=False)]
>>> df = df[df['time'] != 'am']
>>> df = df[df['time'] != 'pm']
>>> df = df[df['time'] != 'xx:xx']
>>> df = df[df['time'] != '?:?']
>>> fig = visualizations.diel_plot(df, date_col='date',
>>>                                 time_col='time', duration_col='length',
>>>                                 time_bin_size=1, color_map_col='group',
>>>                                 show_plot= True)

maui.visualizations.false_color_spectrogram_plot(df, datetime_col, indices, display=True, unit='scale_60', **kwargs)[source]

Generate and optionally display a false color spectrogram from acoustic indices.

This function creates a false color spectrogram by normalizing and combining selected acoustic indices from a DataFrame. The spectrogram can be displayed using Plotly and is returned as a 3D numpy array.

Return type:

array

Parameters:

dfpd.DataFrame

DataFrame containing the acoustic indices and timestamp data.

datetime_colstr

Name of the column in df that contains datetime values.

indiceslist

List of column names corresponding to the acoustic indices to be used for the R, G, and B channels of the spectrogram.

displaybool, optional

If True, the spectrogram is displayed using Plotly. Default is True.

unitstr, optional

The time unit to truncate the timestamps from 0.2 seconds to 60 seconds. Must be one of [‘scale_02’, ‘scale_04’, ‘scale_06’, ‘scale_2’, ‘scale_4’, ‘scale_6’, ‘scale_12’, ‘scale_24’]. Default is ‘scale_60’.

**kwargsdict, optional

Additional arguments for customizing the display:

fig_size (dict): Dictionary specifying the figure size with ‘width’ and ‘height’ keys.
tick_interval (int): Interval for selecting ticks on the x-axis.

Returns:

np.array: A 3D numpy array representing the false color spectrogram, where the third dimension corresponds to the color channels (R, G, B).

Raises:

IndexError: If indices is None or empty.
AssertionError: If any of the specified indices are not found in the DataFrame columns.
Exception: If unit is not one of the available units.

Notes

The function first checks that the selected indices are available in the DataFrame and that the specified time unit is valid.
The DataFrame is sorted by timestamp, and timestamps are truncated according to the specified unit.
Acoustic indices are normalized to the range [0, 255] and combined to form the false color spectrogram.
If display is True, the spectrogram is displayed using Plotly, with customizable figure size and tick interval.

Examples

>>> from maui import samples, utils, visualizations
>>> df = samples.get_audio_sample(dataset="leec")
>>> df["dt"] = pd.to_datetime(df["timestamp_init"]).dt.date
>>> def pre_calculation_method(s, fs):
>>>     Sxx_power, tn, fn, ext = maad.sound.spectrogram (s, fs)
>>>     Sxx_noNoise= maad.sound.median_equalizer(Sxx_power, display=False, extent=ext)
>>>     Sxx_dB_noNoise = maad.util.power2dB(Sxx_noNoise)
>>>
>>>     Sxx, tn, fn, ext = maad.sound.spectrogram(s, fs, mode='amplitude')
>>>
>>>     pre_calc_vars = {'Sxx': Sxx, 'tn':tn , 'fn':fn , 'ext':ext,
>>>                      'Sxx_dB_noNoise':Sxx_dB_noNoise }
>>>     return pre_calc_vars
>>>
>>> def get_aci(pre_calc_vars):
>>>     aci_xx, aci_per_bin, aci_sum = (
>>>             maad.features.acoustic_complexity_index(pre_calc_vars['Sxx']))
>>>     indices = {'aci_xx': aci_xx, 'aci_per_bin':aci_per_bin , 'aci_sum':aci_sum}
>>>     return indices
>>>
>>> def get_spectral_events(pre_calc_vars):
>>>     EVNspFract_per_bin, EVNspMean_per_bin, EVNspCount_per_bin, EVNsp = (
>>>             maad.features.spectral_events(
>>>                 pre_calc_vars['Sxx_dB_noNoise'],
>>>                 dt=pre_calc_vars['tn'][1] - pre_calc_vars['tn'][0],
>>>                 dB_threshold=6,
>>>                 rejectDuration=0.1,
>>>                 display=False,
>>>                 extent=pre_calc_vars['ext'])
>>>             )
>>>
>>>     indices = {'EVNspFract_per_bin': EVNspFract_per_bin,
>>>                'EVNspMean_per_bin':EVNspMean_per_bin,
>>>                'EVNspCount_per_bin':EVNspCount_per_bin, 'EVNsp':EVNsp}
>>>     return indices
>>> def get_spectral_activity(pre_calc_vars):
>>>     ACTspfract_per_bin, ACTspcount_per_bin, ACTspmean_per_bin = (
                    maad.features.spectral_activity(pre_calc_vars['Sxx_dB_noNoise']))
>>>     indices = {'ACTspfract_per_bin': ACTspfract_per_bin,
>>>                'ACTspcount_per_bin':ACTspcount_per_bin,
>>>                'ACTspmean_per_bin':ACTspmean_per_bin}
>>>     return indices
>>> acoustic_indices_methods = [get_aci, get_spectral_activity, get_spectral_events]
>>>
>>> df_temp = df.iloc[0:1]
>>> segmented_df = utils.false_color_spectrogram_prepare_dataset(
>>>     df_temp,
>>>     datetime_col = 'timestamp_init',
>>>     duration_col = 'duration',
>>>     file_path_col = 'file_path',
>>>     indices = ['acoustic_complexity_index', 'spectral_activity', 'spectral_events'],
>>>     output_dir = './segmented_indices',
>>>     store_audio_segments = True,
>>>     unit = 'scale_02',
>>>     acoustic_indices_methods = acoustic_indices_methods,
>>>     pre_calculation_method = pre_calculation_method,
>>>     temp_dir = os.path.abspath('./temp_ac_files/'),
>>>     parallel = True
>>> )
>>>
>>> fcs = visualizations.false_color_spectrogram_plot(
>>>             segmented_df,
>>>             datetime_col = 'start_time',
>>>             indices = ['aci_per_bin', 'ACTspfract_per_bin', 'EVNspCount_per_bin'],
>>>             display = True,
>>>             unit = 'scale_02'
>>>         )

maui.visualizations.indices_histogram_plot(df, indices, group_by=None, max_cols=3, fig_size=None, show_plot=True)[source]

Create histogram plots to visualize the distribution of indices in a DataFrame.

This function generates histogram plots to visualize the distribution of one or more indices from a DataFrame. It provides the option to group data by a single category column.

Parameters:

dfpandas.DataFrame: The input DataFrame containing the data.
indiceslist: A list of column names in the DataFrame representing the indices to be plotted.
group_bystr, optional: A column name for grouping data (default is None).
max_colsint, optional: Maximum number of columns for subplots (default is 3).
fig_sizedict, optional: A dictionary specifying the height and width of the plot (default is None).
show_plotbool, optional: Whether to display the plot (default is True).

Returns:

plotly.graph_objs._figure.Figure: A Plotly Figure object representing the histogram plot.

Raises:

AssertionError: If the arguments are not correctly specified.
Exception: If the input data or arguments are invalid.

Notes

The ‘group_by’ argument is optional, but if provided, only one index can be plotted.
‘fig_size’ should be a dictionary with ‘height’ and ‘width’ keys.

Examples

>>> from maui import samples, acoustic_indices, visualizations
>>> df = samples.get_leec_audio_sample()
>>> indices_list = ['median_amplitude_envelope', 'temporal_entropy']
>>> df = acoustic_indices.calculate_acoustic_indices(df, indices_list, parallel=False)
>>> fig = visualizations.indices_histogram_plot(df, indices=['m', 'ht'],
group_by=None, max_cols=3)

maui.visualizations.indices_radar_plot(df, indices, agg_type, group_by=None, max_cols=3, fig_size=None, show_plot=True)[source]

Create a radar plot to compare indices in a DataFrame.

This function generates a radar plot to compare multiple indices from a DataFrame. It allows aggregating data based on specified aggregation types and grouping by one or two columns from the DataFrame.

Parameters:

dfpandas.DataFrame: The input DataFrame containing the data.
indiceslist: A list of column names in the DataFrame representing the indices to be compared.
agg_typestr: The type of aggregation to be applied (‘mean’, ‘median’, ‘stddev’, ‘var’, ‘max’, ‘min’).
group_bylist, optional: A list of one or two column names for grouping data (default is None).
max_colsint, optional: Maximum number of columns for subplots (default is 3).
fig_sizedict, optional: A dictionary specifying the height and width of the plot (default is None).
show_plotbool, optional: Whether to display the plot (default is True).

Returns:

plotly.graph_objs._figure.Figure: A Plotly Figure object representing the radar plot.

Raises:

AssertionError: If the arguments are not correctly specified.
Exception: If the input data or arguments are invalid.

Notes

The ‘agg_type’ argument must be one of [‘mean’, ‘median’, ‘stddev’, ‘var’, ‘max’, ‘min’].
The ‘group_by’ argument can contain one or two columns for grouping data.
‘fig_size’ should be a dictionary with ‘height’ and ‘width’ keys.

Examples

>>> from maui import samples, acoustic_indices, visualizations
>>> df = samples.get_leec_audio_sample()
>>> indices_list = ['median_amplitude_envelope', 'temporal_entropy']
>>> df = acoustic_indices.calculate_acoustic_indices(df, indices_list, parallel=False)
>>> fig = visualizations.indices_radar_plot(df, indices=['m', 'ht'],
        agg_type='mean', group_by=['environment'], max_cols=3)
# Generates a radar plot comparing 'Index1' and 'Index2' aggregated by 'Category'.

maui.visualizations.indices_violin_plot(df, indices, group_by=None, fig_size=None, show_plot=True)[source]

Create violin plots to visualize the distribution of indices in a DataFrame.

This function generates violin plots to visualize the distribution of one or more indices from a DataFrame. It provides the option to group data by a single category column.

Parameters:

dfpandas.DataFrame: The input DataFrame containing the data.
indiceslist: A list of column names in the DataFrame representing the indices to be plotted.
group_bystr, optional: A column name for grouping data (default is None).
fig_sizedict, optional: A dictionary specifying the height and width of the plot (default is None).
show_plotbool, optional: Whether to display the plot (default is True).

Returns:

plotly.graph_objs._figure.Figure: A Plotly Figure object representing the violin plot.

Raises:

AssertionError: If the arguments are not correctly specified.
Exception: If the input data or arguments are invalid.

Notes

The ‘group_by’ argument is optional and allows grouping data by a single category column.
‘fig_size’ should be a dictionary with ‘height’ and ‘width’ keys.

Examples

>>> from maui import samples, acoustic_indices, visualizations
>>> df = samples.get_leec_audio_sample()
>>> indices_list = ['median_amplitude_envelope', 'temporal_entropy']
>>> df = acoustic_indices.calculate_acoustic_indices(df, indices_list, parallel=False)
>>> fig = visualizations.indices_violin_plot(df, indices=['m', 'ht'], group_by=None)

maui.visualizations.parallel_coordinates_plot(df, indices, color_col, show_plot=True)[source]

Plots a parallel coordinates chart for comparing acoustic indices for some categorical variable.

Return type:

Figure

Parameters:

dfpandas.DataFrame: Input DataFrame containing the data to plot.
indiceslist: List of column names (strings) from df that represents the acoustic indices to be used as parallel axes. All must be numerical.
color_colstr, optional: Name of the column to use for coloring the lines. Can be categorical or numerical. Required.
show_plotbool, default True: If True, the plot is displayed interactively. If False, the Plotly figure object is returned without displaying.

Returns:

figplotly.graph_objects.Figure: The Plotly Figure object containing the parallel coordinates plot.

Raises:

IndexError: If indices is empty or has fewer than two elements.
AssertionError: If any value in indices or color_col is not a column in df.

Notes

For categorical colors, colors and legend associations are assigned

automatically. - The legend for categories appears below the plot and is adjusted to avoid overlapping plot elements. - If the coloring column is numerical, a standard colorbar is shown. - Only numerical columns can be used for parallel axes.

maui.visualizations.polar_bar_plot(df, date_time_col, categories_col, percent=False, show_plot=True, **kwargs)[source]

Generate a polar bar plot to visualize category occurrences over the year. It will group data by day of the year, keep this in mind if you have more than one year of data.

Return type:

Figure

Parameters:

dfpandas.DataFrame: The input dataframe containing the data to plot.
date_time_colstr: The name of the column in df containing date or datetime values.
categories_colstr: The name of the column in df representing the categorical variable.
percentbool, optional, default: False: If True, the plot will display the data as percentages of total occurrences for each day. If False, raw counts will be used.
show_plotbool, optional, default: True: If True, the plot will be displayed. If False, the plot will be returned without displaying it.
**kwargsdict, optional: Additional keyword arguments passed to the plot layout, such as height and width for figure dimensions.

Returns:

plotly.graph_objects.Figure: The generated polar bar plot figure.

Raises:

AssertionError: If date_time_col or categories_col is not in df.
AttributeError: If categories_col contains continuous data instead of discrete categories.

Warns:

UserWarning: If date_time_col contains invalid date values, a warning is issued, and those rows are ignored in the plot.

Notes

The date_time_col is converted to the day of the year (1 to 366, to account for leap years).
If percent=True, the data is normalized by day to represent the proportion of occurrences.

Examples

>>> df = pd.DataFrame({
>>>     'date': pd.date_range(start='2023-01-01', periods=366, freq='D'),
>>>     'category': ['A', 'B', 'C'] * 122
>>> })
>>> fig = polar_bar_plot(df, 'date', 'category', percent=True)
>>> fig.show()

maui.visualizations.spectrogram_plot(file_path, mode=None, window='hann', nperseg=1024, noverlap=None, verbose=False, fig_size=None, show_plot=True)[source]

Create a spectrogram plot from an audio file.

This function loads an audio file, computes its spectrogram, and generates a heatmap plot to visualize the frequency content over time.

Parameters:

file_pathstr: The path to the audio file.
modestr, optional: The spectrogram mode (‘psd’, ‘mean’, ‘complex’). Default is None.
windowstr, optional: The window function to be used for the spectrogram calculation. Default is ‘hann’.
npersegint, optional: The number of data points used in each block for the FFT. Default is 1024.
noverlapint, optional: The number of points of overlap between blocks. Default is None.
verbosebool, optional: Whether to display verbose information during computation. Default is False.
fig_sizedict, optional: A dictionary specifying the height and width of the plot. Default is None.
show_plotbool, optional: Whether to display the plot. Default is True.

Returns:

plotly.graph_objs._figure.Figure: A Plotly Figure object representing the spectrogram plot.

Raises:

AssertionError: If the arguments are not correctly specified.
Exception: If there are errors in the file loading or spectrogram computation.

Notes

The ‘mode’ parameter specifies the type of spectrogram to be computed: Power Spectral Density (‘psd’), Amplitude Spectrogram (‘amplitude’), or Complex Spectrogram (‘complex’).
‘fig_size’ should be a dictionary with ‘height’ and ‘width’ keys.

Examples

>>> from maui import samples, visualizations
>>> df = samples.get_leec_audio_sample()
>>> file_path = df.at[df.index[1],'file_path']
>>> mode = 'psd'
>>> fig = visualizations.spectrogram_plot(file_path, mode=mode)