maui.visualizations.diel_plot

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

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)