vivainsights.create_bar

Calculate and visualize the mean of a metric by organizational group.

The code defines a function create_bar that calculates and visualizes the mean of a selected metric, grouped by a selected HR variable.

The metrics are first aggregated at a user-level prior to being aggregated at the level of the HR variable. The function create_bar returns either a plot object or a table, depending on the value passed to return_type.

vivainsights.create_bar.create_bar_calc(data, metric, hrvar, mingroup=5, stats=False)[source]

Calculate the mean of a metric, grouped by an HR variable.

Aggregates at the person level first, then at the level of the grouping variable. Used internally by create_bar.

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, default 5) – Minimum group size; groups below this threshold are dropped.

  • stats (bool, default False) – If True, append standard deviation, median, min, and max.

Returns:

Summary table with the mean of the metric per group.

Return type:

pandas.DataFrame

vivainsights.create_bar.create_bar_viz(data, metric, hrvar, mingroup=5, percent=False, plot_title=None, plot_subtitle=None, figsize=None)[source]

Create a horizontal bar chart of mean metric values by group.

Used internally by create_bar when return_type="plot".

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, default 5) – Minimum group size.

  • percent (bool, default False) – Whether to format the x-axis as percentages.

  • plot_title (str or None, default None) – Custom plot title. Defaults to a cleaned version of metric.

  • plot_subtitle (str or None, default None) – Custom subtitle.

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

Returns:

The bar chart figure.

Return type:

matplotlib.figure.Figure

vivainsights.create_bar.create_bar(data, metric, hrvar, mingroup=5, percent=False, return_type='plot', plot_title=None, plot_subtitle=None, figsize=None)[source]

Calculate and visualize the mean of a metric by organizational group.

Metrics are first aggregated at the person level before being aggregated at the level of the HR variable. Returns either a plot or a summary table depending on return_type. Internally delegates to create_bar_calc and create_bar_viz.

Parameters:

  • data (pandas.DataFrame) – Person query data.

  • metric (str) – Name of the metric to analyse.

  • hrvar (str) – Name of the organizational attribute for grouping.

  • mingroup (int, default 5) – Minimum group size; smaller groups are excluded.

  • percent (bool, default False) – Whether to display values as percentages.

  • return_type (str, default "plot") – "plot" for a matplotlib figure, "table" for a DataFrame.

  • plot_title (str or None, default None) – Custom plot title.

  • plot_subtitle (str or None, default None) – Custom plot subtitle.

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

Returns:

A bar chart figure or a summary table.

Return type:

matplotlib.figure.Figure or pandas.DataFrame

Examples

Return a bar plot (default):

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

Return a summary table instead of a plot:

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

Display values as percentages with a custom title and figure size:

>>> vi.create_bar(
...     pq_data,
...     metric="Collaboration_hours",
...     hrvar="Organization",
...     percent=True,
...     plot_title="Collaboration Hours",
...     plot_subtitle="Percentage by Organization",
...     figsize=(10, 5),
... )