vivainsights.create_trend¶

Create a week-by-week heatmap of a selected Viva Insights metric.

The create_trend function provides a week by week view of a selected Viva Insights metric, allowing you to either return a week by week heatmap bar plot or a summary table. By default, create_trend returns a week by week heatmap bar plot, highlighting the points intime with most activity. Additional options available to return a summary table.

vivainsights.create_trend.create_trend(data, metric, palette=['#0c3c44', '#1d627e', '#34b1e2', '#bfe5ee', '#fcf0eb', '#fbdacd', '#facebc', '#fe7f4f'], hrvar='Organization', mingroup=5, return_type='plot', legend_title='Hours', date_column='MetricDate', date_format='%Y-%m-%d', figsize=None, size_x_axis_label=5)[source]¶

Create a week-by-week heatmap of a selected metric.

Produces a heatmap bar plot highlighting activity hotspots over time, or returns a summary table.

Parameters:

data (pandas.DataFrame) – Person query data.
metric (str) – Name of the metric column to plot.
palette (list of str) – Colours used for the heatmap gradient.
hrvar (str, default "Organization") – Name of the organizational attribute for grouping.
mingroup (int, default 5) – Minimum group size.
return_type (str, default "plot") – "plot" for a heatmap figure, "table" for a pivoted DataFrame.
legend_title (str, default "Hours") – Label for the colour-bar legend.
date_column (str, default "MetricDate") – Name of the date column.
date_format (str, default "%Y-%m-%d") – strftime format of dates in date_column.
figsize (tuple or None, default None) – Figure size (width, height) in inches. Defaults to (8, 6).
size_x_axis_label (int, default 5) – Font size for x-axis bracket labels.

Returns:

A heatmap figure or a pivoted summary table.

Return type:

matplotlib.figure.Figure or pandas.DataFrame

Examples

Return a heatmap (default):

>>> import vivainsights as vi
>>> pq_data = vi.load_pq_data()
>>> vi.create_trend(pq_data, metric="Collaboration_hours", hrvar="LevelDesignation")

Return a pivoted summary table:

>>> vi.create_trend(pq_data, metric="Collaboration_hours", hrvar="LevelDesignation", return_type="table")

Customize the legend title, figure size, and date format:

>>> vi.create_trend(
...     pq_data,
...     metric="Collaboration_hours",
...     hrvar="Organization",
...     legend_title="Avg Hours",
...     figsize=(12, 6),
...     date_format="%Y-%m-%d",
... )

vivainsights.create_trend.create_trend_calc(data, metric, hrvar, mingroup, date_column, date_format)[source]¶

Compute weekly group-level metric averages for trend analysis.

Used internally by create_trend.

Parameters:

data (pandas.DataFrame) – Person query data.
metric (str) – Name of the metric column.
hrvar (str) – Name of the organizational attribute for grouping.
mingroup (int) – Minimum group size.
date_column (str) – Name of the date column.
date_format (str) – strftime format of dates in date_column.

Returns:

Aggregated table with date, group, employee count, and metric mean.

Return type:

pandas.DataFrame

vivainsights.create_trend.create_trend_viz(data, metric, palette, hrvar, mingroup, legend_title, date_column, date_format, size_x_axis_label, figsize=None)[source]¶

Create a heatmap visualization of a metric over time by group.

Used internally by create_trend when return_type="plot".

Parameters:

data (pandas.DataFrame) – Person query data.
metric (str) – Name of the metric column.
palette (list of str) – Colours for the heatmap gradient.
hrvar (str) – Name of the organizational attribute for grouping.
mingroup (int) – Minimum group size.
legend_title (str) – Label for the colour-bar legend.
date_column (str) – Name of the date column.
date_format (str) – strftime format of dates in date_column.
size_x_axis_label (int) – Font size for x-axis bracket labels.
figsize (tuple or None, default None) – Figure size (width, height) in inches.

Returns:

The heatmap figure.

Return type:

matplotlib.figure.Figure