vivainsights.identify_habit

Identify recurring behavioral habits from Viva Insights metrics.

vivainsights.identify_habit.identify_habit(data, metric, threshold=1, width=1, max_window=4, hrvar=None, return_type='plot', plot_mode='time', figsize=None, fill_col=('#E5E5E5', '#0078D4'))[source]

Identify recurring behavioral habits from a metric.

Analyses a dataset to determine whether a habit exists based on a specified metric and thresholds. Can return classified data, plots, or summary statistics.

Parameters:

  • data (pandas.DataFrame) – Person query data. Must include PersonId, MetricDate, and the metric column.

  • metric (str) – Column name of the metric to analyse.

  • threshold (int, default 1) – Minimum value for a week to count as a qualifying event.

  • width (int, default 1) – Number of qualifying events required to establish a habit.

  • max_window (int, default 4) – Maximum number of periods to consider for a habit.

  • hrvar (str or None, default None) – Column name for grouping (used with plot_mode="boxplot").

  • return_type (str, default "plot") – "data" for a classified DataFrame, "plot" for a chart, or "summary" for summary statistics.

  • plot_mode (str, default "time") – "time" for a stacked bar time series, "boxplot" for a boxplot by group.

  • figsize (tuple or None, default None) – Figure size (width, height) in inches. Defaults to (8, 6).

  • fill_col (tuple, default ("#E5E5E5", "#0078D4")) – Colours for the plot.

Returns:

Classified data, a plot, or summary statistics depending on return_type.

Return type:

pandas.DataFrame, matplotlib.figure.Figure, or dict

Examples

Return classified data with habit labels:

>>> import vivainsights as vi
>>> pq_data = vi.load_pq_data()
>>> vi.identify_habit(pq_data, metric='Multitasking_hours', threshold=1, width=9, max_window=12, return_type="data")

Return a plot of habit classification over time:

>>> vi.identify_habit(pq_data, metric='Multitasking_hours', threshold=1, width=9, max_window=12, return_type="plot")

Return a summary dictionary of habit statistics:

>>> vi.identify_habit(pq_data, metric='Multitasking_hours', threshold=1, width=9, max_window=12, return_type="summary")

Group results by an HR variable:

>>> vi.identify_habit(
...     pq_data,
...     metric='Multitasking_hours',
...     threshold=1,
...     width=9,
...     max_window=12,
...     hrvar='Organization',
...     return_type="plot",
... )