Events

events.AUC(df: DataFrame) → float

Calculates the total Area-Under-Curve (AUC) for the given CGM trace

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing the CGM trace to calculate the AUC of

Returns:

the AUC of the given CGM trace

Return type:

float

events.baseline(df: DataFrame) → float

Returns the baseline glucose level for the given CGM trace

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing the CGM trace to retrieve the baseline glucose level for

Returns:

the baseline glucose level of the given CGM trace

Return type:

float

events.create_event_features(df: DataFrame, events: DataFrame) → DataFrame

Returns a multi-indexed Pandas DataFrame containing metrics for the patient data during their respective ‘events’

Parameters:

  • df ('pandas.Series') – a Pandas DataFrame containing all the relevant patient CGM data to generate event metrics for

  • events ('pandas.DataFrame') – a single indexed Pandas DataFrame, with each row specifying a single event in the form of an id, a datetime, # of hours before the datetime to include, # of hours after to include, and a desc

Returns:

a multi-indexed Pandas DataFrame containing metrics for the patient data during their respective ‘events’

events.create_event_features_helper(df: DataFrame, sub_events: DataFrame, event_type: str) → dict[str, float]

Calculates aggregate event-based metrics for a single patient and type of event. Helper method for ‘create_event_features()’.

Parameters:

  • df ('pandas.DataFrame') – Pandas DataFrame containing the CGM trace for a single patient

  • sub_events ('pandas.DataFrame') – Pandas DataFrame containing events of only one type solely for the patient whose CGM trace is also given

  • event_type (str) – the type of event that ‘sub_events’ contains

Returns:

a dictionary with str-type keys that refer to the name of the calculated features and float-type values

Return type:

dict[str, float]

events.delta(df: DataFrame) → float

Returns the difference in maximum and baseline glucose levels (delta) for the given CGM trace

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing the CGM trace to retrieve the delta for

Returns:

the delta of the given CGM trace

Return type:

float

events.event_metrics(df: DataFrame, event: Series, post_times: list[int] = [60, 120], post_auc_times: list[int] = [120]) → DataFrame

Calculates basic metrics for events (baseline, peak, delta, iAUC, and 0-h, 1-h, and 2-h post event glucose values, and 2-h post event AUC)

Parameters:

  • df (pandas.DataFrame) – Pandas DataFrame containing preprocessed CGM data

  • event (pandas.Series) – Pandas Series with fields that represent an ‘event’

  • post_times (list[int], optional (defaults to [0, 60, 120] for 0-h, 1-h and 2-h post event)) – A list of integers representing the number of minutes after event_time for which to find the glucose values

Returns:

Pandas DataFrame containing the basic metrics for the given event

Return type:

pandas.DataFrame

events.event_summary(events: DataFrame) → Series

Returns the number of events per unique event type found within ‘events’

Parameters:

events ('pandas.DataFrame') – a Pandas DataFrame containing events (as per package guidelines)

Returns:

a Pandas Series containing the number of events per unique event type found within ‘events’

Return type:

‘pandas.Series’

events.get_curated_events(df: DataFrame) → DataFrame

Retrieves all curated events (episodes and excursions) for all the patients within the given DataFrame

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing preprocessed CGM data

Returns:

a Pandas DataFrame (in the usual event structure defined by the package) containing all curated events for all the patients within the given DataFrame

Return type:

‘pandas.DataFrame’

events.get_episodes(df: DataFrame, hypo_lvl2: int = 54, hypo_lvl1: int = 70, hyper_lvl0: int = 140, hyper_lvl1: int = 180, hyper_lvl2: int = 250, min_length: int = 15, end_length: int = 15) → DataFrame

Retrieves all episodes within the given CGM data

Parameters:

  • df (pandas.DataFrame) – Pandas DataFrame containing preprocessed CGM data

  • hypo_lvl2 (int, optional) – threshold (in mg/dL) below which glucose values are considered level 2 hypoglycemic, defaults to 54

  • hypo_lvl1 (int, optional) – threshold (in mg/dL) below which glucose values are considered level 1 hypoglycemic, defaults to 70

  • hyper_lvl0 (int, optional) – threshold (in mg/dL) above which glucose values are considered level 0 hyperglycemic, defaults to 140

  • hyper_lvl1 (int, optional) – threshold (in mg/dL) above which glucose values are considered level 1 hyperglycemic, defaults to 180

  • hyper_lvl2 (int, optional) – threshold (in mg/dL) above which glucose values are considered level 2 hyperglycemic, defaults to 250

  • min_length (int, optional) – minimum duration (in minutes) required for excursions, defaults to 15

  • end_length (int, optional) – minimum amount of time (in minutes) that the glucose values must be within typical ranges at the end of an excursion, defaults to 15

Returns:

a Pandas DataFrame containing all episodes within the given CGM data

Return type:

pandas.DataFrame

events.get_excursions(df: DataFrame, z: int = 2, min_length: int = 15, end_length: int = 15) → DataFrame

Retrieves all excursions within the given CGM data

Parameters:

  • df (pandas.DataFrame) – Pandas DataFrame containing preprocessed CGM data

  • z (int, optional) – the number of standard deviations away from the mean that should define an ‘excursion’, defaults to 2

  • min_length (int, optional) – minimum duration (in minutes) required for excursions, defaults to 15

  • end_length (int, optional) – minimum amount of time (in minutes) that the glucose values must be within typical ranges at the end of an excursion, defaults to 15

Returns:

a Pandas DataFrame containing all excursions within the given CGM data

Return type:

pandas.DataFrame

events.iAUC(df: DataFrame, level: float) → float

Calculates the incremental Area-Under-Curve (iAUC) for the given CGM trace

Parameters:

  • df ('pandas.DataFrame') – a Pandas DataFrame containing the CGM trace to calculate the AUC of

  • level (float) – the threshold above which to calculate iAUC

Returns:

the iAUC of the given CGM trace

Return type:

float

events.import_events(path: str, id: str, name: str = None, day_col: str = 'Day', time_col: str = 'Time', before: int = 30, after: int = 180, type: str = 'imported event') → DataFrame

Bulk imports events from standalone .csv files or from those within a given directory or .zip file

Parameters:

  • path (str) – the path of the directory/zip/csv to import from

  • id (str) – the identification of the patient that the imported events belong to

  • day_col (str, optional) – the name of the column specifying the day the event occurred (year, month, and specific day), defaults to ‘Day’

  • time_col (str, optional) – the name of the column specifying what time during the day the event occurred, defaults to ‘Time’

  • before (int, optional) – the amount of minutes to also look at before the event timestamp, defaults to 30

  • after (int, optional) – the amount of minutes to also look at after the event timestamp, defaults to 180

  • type (str, optional) – the type of event to classify all the imported events as, defaults to ‘imported event’

Returns:

a Pandas DataFrame containing all the imported events

Return type:

‘pandas.DataFrame’

events.import_events_csv(path: str, id: str, day_col: str = 'Day', time_col: str = 'Time', before: int = 30, after: int = 180, type: str = 'imported event') → DataFrame

Bulk imports events from a single .csv file

Parameters:

  • path (str) – the path of the .csv file to import from

  • id (str) – the identification of the patient that the imported events belong to

  • day_col (str, optional) – the name of the column specifying the day the event occurred (year, month, and specific day), defaults to ‘Day’

  • time_col (str, optional) – the name of the column specifying what time during the day the event occurred, defaults to ‘Time’

  • before (int, optional) – the amount of minutes to also look at before the event timestamp, defaults to 30

  • after (int, optional) – the amount of minutes to also look at after the event timestamp, defaults to 180

  • type (str, optional) – the type of event to classify all the imported events as, defaults to ‘imported event’

Returns:

a Pandas DataFrame containing all the imported events

Return type:

‘pandas.DataFrame’

events.import_events_directory(path: str, id: str, day_col: str = 'Day', time_col: str = 'Time', before: int = 30, after: int = 180, type: str = 'imported event') → DataFrame

Bulk imports events from .csv files within a given directory

Parameters:

  • path (str) – the path of the directory to import from

  • id (str) – the identification of the patient that the imported events belong to

  • day_col (str, optional) – the name of the column specifying the day the event occurred (year, month, and specific day), defaults to ‘Day’

  • time_col (str, optional) – the name of the column specifying what time during the day the event occurred, defaults to ‘Time’

  • before (int, optional) – the amount of minutes to also look at before the event timestamp, defaults to 30

  • after (int, optional) – the amount of minutes to also look at after the event timestamp, defaults to 180

  • type (str, optional) – the type of event to classify all the imported events as, defaults to ‘imported event’

Returns:

a Pandas DataFrame containing all the imported events

Return type:

‘pandas.DataFrame’

events.nadir(df: DataFrame) → float

Returns the minimum glucose level for the given CGM trace

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing the CGM trace to retrieve the minimum glucose level for

Returns:

the minimum glucose level of the given CGM trace

Return type:

float

events.peak(df: DataFrame) → float

Returns the maximum glucose level for the given CGM trace

Parameters:

df ('pandas.DataFrame') – a Pandas DataFrame containing the CGM trace to retrieve the maximum glucose level for

Returns:

the maximum glucose level of the given CGM trace

Return type:

float

events.post_event_aucs(data: DataFrame, event_time: Timestamp, durations: list[int], glucose_col: str = 'Glucose') → dict

Calculates AUC values for multiple durations (in minutes) starting from the given event_time.

Parameters:

  • data (pd.DataFrame) – Pandas DataFrame containing the CGM data

  • event_time (pd.Timestamp) – The time of the event

  • durations (list[int]) – A list of integers representing the number of minutes after event_time for which to calculate the AUC

  • glucose_col (str, optional) – The name of the glucose column in the data, defaults to GLUCOSE

Returns:

A dictionary where keys are strings like “X-min AUC” and values are the corresponding AUC readings or np.nan if no data is available

Return type:

dict

events.post_event_glucoses(data: DataFrame, event_time: Timestamp, times: list[int], glucose_col: str = 'Glucose') → dict

Returns the glucose values closest to the specified times (in minutes) after the given event_time.

Parameters:

  • data (pd.DataFrame) – Pandas DataFrame containing the CGM data

  • event_time (pd.Timestamp) – The time of the event

  • times (list[int]) – A list of integers representing the number of minutes after event_time for which to find the glucose values

  • glucose_col (str, optional) – The name of the glucose column in the data, defaults to GLUCOSE

Returns:

A dictionary where keys are strings like “X-min Post Event” and values are the corresponding glucose readings or np.nan if not found

Return type:

dict

events.retrieve_event_data(df: DataFrame, events: DataFrame) → DataFrame

Returns a multiindexed Pandas DataFrame containing only patient data during the respective given events :param df: a Pandas DataFrame containing the preprocessed CGM traces to retrieve event subsets from :type df: ‘pandas.DataFrame’ :param events: a single indexed Pandas DataFrame, with each row specifying a single event in the form of

an id, a datetime, # of hours before the datetime to include, # of hours after to include, and a description

Returns:

a multi-indexed Pandas DataFrame, with each index referring to a subset of CGM trace that was found within ‘df’ and occurs during a single event within ‘events’

Return type:

‘pandas.DataFrame’