format_timeseries (df:pandas.core.frame.DataFrame, participant_id:int=None, array_index:int=None, time_range:Tuple[str,str]=None, x_start:str='collection_timestamp', x_end:str='collection_timestamp', unique:bool=False)
*Reformat and filter a time series DataFrame based on participant ID, array index, and date range.
Args:
df (pd.DataFrame): The DataFrame to filter.
participant_id (int): The participant ID to filter by.
array_index (int): The array index to filter by.
time_range: The date range to filter by. Can be a tuple of two dates / times or two strings.
x_start (str): The name of the column containing the start time.
x_end (str): The name of the column containing the end time.
unique (bool): Whether to remove duplicate rows.Returns:
pd.DataFrame: The filtered DataFrame*format_xticks (ax:matplotlib.axes._axes.Axes, xticks:Iterable=None, format:str='%d/%m\n%H:%M', **kwargs)
Format datestrings on x axis
TimeSeriesFigure (figsize:tuple=(10, 6), padding:float=0.05)
*Initialize a TimeSeriesFigure instance. This class is used to create and manage a figure with multiple axes for time series data.
Args:
figsize (tuple): Size of the figure (width, height) in inches.
padding (float): The amount of padding to add between axes as a fraction of the figure height.*get_color_map (data:pandas.core.frame.DataFrame, hue:str, palette:str)
*Get a color map for a specific column in the data.
Args:
data (pd.DataFrame): The data to get the color map from.
hue (str): The column name to use for the color map.
palette (str): The name of the colormap to use.Returns:
pd.DataFrame: A DataFrame with the color map.*get_events_period (events_filtered:pandas.core.frame.DataFrame, period_start:str, period_end:str, period_name:str, col:str='event', first_start:bool=True, first_end:bool=True, include_start:bool=True, include_end:bool=True, x_start:str='collection_timestamp', x_end:str='event_end')
*Get the period of time between the start and end events.
Args:
events_filtered (pd.DataFrame): The events DataFrame.
period_start (str): The label of the start event.
period_end (str): The label of the end event.
period_name (str): The label to assign to the period.
col (str): The column name for the event labels. Default is 'event'.
first_start (bool): If True, get the first start event. Default is True.
first_end (bool): If True, get the first end event. Default is True.
include_start (bool): If True, include the start event in the period. Default is True.
include_end (bool): If True, include the end event in the period. Default is True.
x_start (str): The column name for the start time of the event. Default is 'collection_timestamp'.
x_end (str): The column name for the end time of the event. Default is 'event_end'.Returns:
pd.DataFrame: The period of events in the same format as the input DataFrame.*prep_to_plot_timeseries (data:pandas.core.frame.DataFrame, x_start:str, x_end:str, hue:str, label:str, participant_id:int, array_index:int, time_range:Tuple[str,str], y_include:Iterable[str], y_exclude:Iterable[str], add_columns:Iterable[str]=None, palette='muted')
*Prepare timeseries / events data for plotting.
Args:
events (pd.DataFrame): The timeseries / events dataframe.
x_start (str): The column name for the start time of the event.
x_end (str): The column name for the end time of the event.
hue (str): The column name for the color of the event.
label (str): The column name for the label of the event.
participant_id (int): The participant ID to filter events by.
array_index (int): The array index to filter events by.
time_range (Iterable[str]): The time range to filter events by.
y_include (Iterable[str]): The list of values to include in the plot.
y_exclude (Iterable[str]): The list of values to exclude from the plot.
add_columns (Iterable[str]): Additional columns to include in the plot.
palette (str): The name of the colormap to use for coloring events.Returns:
Tuple[pd.DataFrame, pd.DataFrame]: The filtered events dataframe and the color map.*plot_events_fill (events:pandas.core.frame.DataFrame, x_start:str='collection_timestamp', x_end:str='event_end', hue:str='channel', label:str=None, participant_id:Optional[int]=None, array_index:Optional[int]=None, time_range:Optional[Tuple[str,str]]=None, y_include:Optional[Iterable[str]]=None, y_exclude:Optional[Iterable[str]]=None, legend:bool=True, palette:str='muted', alpha:Optional[float]=0.5, ax:Optional[matplotlib.axes._axes.Axes]=None, figsize:Iterable[float]=[12, 6])
*Plot events as filled regions on a time series plot.
Args:
events (pd.DataFrame): The events dataframe.
x_start (str): The column name for the start time of the event.
x_end (str): The column name for the end time of the event.
hue (str): The column name for the color of the event.
label (str): The column name for the label of the event.
participant_id (int): The participant ID to filter events by.
array_index (int): The array index to filter events by.
time_range (Iterable[str]): The time range to filter events by.
y_include (Iterable[str]): The list of values to include in the plot.
y_exclude (Iterable[str]): The list of values to exclude from the plot.
legend (bool): Whether to show the legend.
palette (str): The name of the palette to use for coloring events.
alpha (float): The transparency of the filled regions.
ax (plt.Axes): The axis to plot on. If None, a new figure is created.
figsize (Tuple[float, float]): The size of the figure (width, height) in inches.*plot_events_bars (events:pandas.core.frame.DataFrame, x_start:str='collection_timestamp', x_end:str='event_end', y:str='event', hue:str='channel', participant_id:Optional[int]=None, array_index:Optional[int]=None, time_range:Optional[Tuple[str,str]]=None, y_include:Optional[Iterable[str]]=None, y_exclude:Optional[Iterable[str]]=None, legend:bool=True, palette:str='muted', alpha:Optional[float]=0.7, ax:Optional[matplotlib.axes._axes.Axes]=None, figsize:Tuple[float,float]=(12, 6))
*Plot events as bars on a time series plot.
Args:
events (pd.DataFrame): The events dataframe.
x_start (str): The column name for the start time of the event.
x_end (str): The column name for the end time of the event.
y (str): The column name for the y-axis values.
hue (str): The column name for the color of the event.
participant_id (int): The participant ID to filter events by.
array_index (int): The array index to filter events by.
time_range (Tuple[str, str]): The time range to filter events by.
y_include (Iterable[str]): The list of values to include in the plot.
y_exclude (Iterable[str]): The list of values to exclude from the plot.
legend (bool): Whether to show the legend.
palette (str): The name of the colormap to use for coloring events.
alpha (float): The transparency of the bars. Default is 0.7.
ax (plt.Axes): The axis to plot on. If None, a new figure is created.
figsize (Tuple[float, float]): The size of the figure (width, height) in inches.*The class TimeSeriesFigure provides a user-friendly interface for plotting multiple channels of time series data.
First, we will load time series DFs from the sleep monitoring dataset. The data includes sleep events, and sensor channels for heart rate, respiratory movement, and oxygen saturation.
from pheno_utils import PhenoLoader
pl = PhenoLoader('sleep')
channels_df = pl.load_bulk_data('channels_time_series', pivot='source')
events_df = pl.load_bulk_data('events_time_series')/home/ec2-user/projects/pheno-utils/pheno_utils/pheno_loader.py:610: UserWarning: No date field found
warnings.warn(f'No date field found')Any plotting function that accepts an ax argument can be used with TimeSeriesFigure. The pheno-utils package includes a number of functions that are useful for plotting time series data, such as plot_events_bars and plot_events_fill, however standard seaborn plotting functions (and others) can also be used.
sns.set_style('whitegrid')
g = TimeSeriesFigure()
channels_df = format_timeseries(channels_df).set_index('collection_timestamp')
g.plot(sns.lineplot, channels_df, x='collection_timestamp', y='heart_rate',
name='heart_rate') # Named axis 'heart_rate'
# You can also use the `sharex` argument to share the x-axis between plots
# Named axes, such as 'heart_rate', can be referred to by name
g.plot(sns.lineplot, channels_df, x='collection_timestamp', y='spo2',
sharex='heart_rate')
# You can increase the relative height of the plot by passing a `height` argument
g.plot(sns.lineplot, channels_df, x='collection_timestamp', y='respiratory_movement',
sharex='heart_rate', height=1.5)
# You may add a plot to an existing axes by passing an `ax` argument to the plotting function
# Named axes, such as 'heart_rate', can be referred to by name
stage_events = ['Wake', 'Light Sleep', 'Deep Sleep', 'REM'] # Include only sleep stage events
g.plot(plot_events_fill, events_df, hue='event', y_include=stage_events,
ax='heart_rate')
apnea_events = ['Resp. Event', 'Desaturation', 'A/H obstructive', 'A/H central', 'A/H unclassified']
g.plot(plot_events_bars, events_df, hue='event', y_include=apnea_events, height=1.5)
# Control functions to conveniently modify all axes
g.set_periodic_ticks('1h')
g.set_axis_padding(0.05)
g.set_axis_properties(xlabel='')