Collapsible Documentation Examples

This file shows different ways to create collapsible documentation sections.

Option 1: Simple Dropdowns

Basic Function Documentation
vivainsights.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),
... )
Function with Description

create_bubble - Creates bubble plots for dual-metric analysis

vivainsights.create_bubble(data, metric_x, metric_y, hrvar='Organization', mingroup=5, return_type='plot', bubble_size=(1, 100), figsize=None)[source]

Create a bubble plot of two metrics by organizational group.

Metrics are first aggregated per person, then per HR variable group. Bubble size represents the number of employees in each group.

Parameters:

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

  • metric_x (str) – Column name for the x-axis metric.

  • metric_y (str) – Column name for the y-axis metric.

  • hrvar (str, optional) – Organizational attribute for grouping. Defaults to "Organization".

  • mingroup (int, optional) – Minimum group size. Groups below this are excluded. Defaults to 5.

  • return_type (str, optional) – "plot" (default) returns a bubble chart; "table" returns a summary DataFrame.

  • bubble_size (tuple, optional) – (min_size, max_size) range for bubble scaling. Defaults to (1, 100).

  • figsize (tuple, optional) – Figure size as (width, height) in inches. Defaults to (8, 6).

Returns:

Bubble chart or summary table depending on return_type.

Return type:

matplotlib.figure.Figure or pandas.DataFrame

Examples

Return a bubble plot (default):

>>> import vivainsights as vi
>>> pq_data = vi.load_pq_data()
>>> vi.create_bubble(
...     data=pq_data,
...     metric_x="Collaboration_hours",
...     metric_y="Multitasking_hours",
...     hrvar="Organization",
... )

Return a summary table:

>>> vi.create_bubble(
...     data=pq_data,
...     metric_x="Collaboration_hours",
...     metric_y="Multitasking_hours",
...     hrvar="LevelDesignation",
...     return_type="table",
... )

Customize bubble size range, minimum group size, and figure size:

>>> vi.create_bubble(
...     data=pq_data,
...     metric_x="Collaboration_hours",
...     metric_y="Multitasking_hours",
...     hrvar="Organization",
...     bubble_size=(5, 200),
...     mingroup=10,
...     figsize=(12, 8),
... )

Option 2: Grouped Dropdowns

Core Visualization Functions

Functions for creating basic visualizations:

create_bar
vivainsights.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),
... )
create_boxplot
vivainsights.create_boxplot(data, metric, hrvar='Organization', mingroup=5, return_type='plot', figsize=None)[source]

Create a boxplot of metric distributions by organizational group.

Generates a boxplot showing the distribution of a selected metric across groups defined by an HR variable. Metrics are aggregated at the person level before plotting.

Parameters:

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

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

  • hrvar (str, default "Organization") – Name of the organizational attribute for grouping.

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

  • return_type (str, default "plot") – "plot" for a matplotlib figure, "table" for summary statistics, or "data" for the processed plot data.

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

Returns:

A boxplot figure, a summary table, or the processed data, depending on return_type.

Return type:

matplotlib.figure.Figure or pandas.DataFrame

Examples

Return a boxplot (default):

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

Return a summary table with mean, median, sd, min, max:

>>> vi.create_boxplot(pq_data, metric="Collaboration_hours", hrvar="Organization", return_type="table")

Return the processed person-level data:

>>> vi.create_boxplot(pq_data, metric="Collaboration_hours", hrvar="Organization", return_type="data")

Customize the figure size:

>>> vi.create_boxplot(
...     pq_data,
...     metric="Collaboration_hours",
...     hrvar="LevelDesignation",
...     figsize=(12, 8),
... )
create_bubble
vivainsights.create_bubble(data, metric_x, metric_y, hrvar='Organization', mingroup=5, return_type='plot', bubble_size=(1, 100), figsize=None)[source]

Create a bubble plot of two metrics by organizational group.

Metrics are first aggregated per person, then per HR variable group. Bubble size represents the number of employees in each group.

Parameters:

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

  • metric_x (str) – Column name for the x-axis metric.

  • metric_y (str) – Column name for the y-axis metric.

  • hrvar (str, optional) – Organizational attribute for grouping. Defaults to "Organization".

  • mingroup (int, optional) – Minimum group size. Groups below this are excluded. Defaults to 5.

  • return_type (str, optional) – "plot" (default) returns a bubble chart; "table" returns a summary DataFrame.

  • bubble_size (tuple, optional) – (min_size, max_size) range for bubble scaling. Defaults to (1, 100).

  • figsize (tuple, optional) – Figure size as (width, height) in inches. Defaults to (8, 6).

Returns:

Bubble chart or summary table depending on return_type.

Return type:

matplotlib.figure.Figure or pandas.DataFrame

Examples

Return a bubble plot (default):

>>> import vivainsights as vi
>>> pq_data = vi.load_pq_data()
>>> vi.create_bubble(
...     data=pq_data,
...     metric_x="Collaboration_hours",
...     metric_y="Multitasking_hours",
...     hrvar="Organization",
... )

Return a summary table:

>>> vi.create_bubble(
...     data=pq_data,
...     metric_x="Collaboration_hours",
...     metric_y="Multitasking_hours",
...     hrvar="LevelDesignation",
...     return_type="table",
... )

Customize bubble size range, minimum group size, and figure size:

>>> vi.create_bubble(
...     data=pq_data,
...     metric_x="Collaboration_hours",
...     metric_y="Multitasking_hours",
...     hrvar="Organization",
...     bubble_size=(5, 200),
...     mingroup=10,
...     figsize=(12, 8),
... )

Option 3: Tabs for Categories

identify_churn
vivainsights.identify_churn(data, n1=6, n2=6, return_type='message', flip=False, date_column='MetricDate', date_format='%Y-%m-%d')[source]

Identify employees who have churned from or joined the dataset.

Measures whether employees present in the first n1 weeks are still present in the last n2 weeks. Set flip=True to identify new joiners instead of churned employees.

Parameters:

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

  • n1 (int, default 6) – Number of initial weeks to check for presence.

  • n2 (int, default 6) – Number of final weeks to check for presence.

  • return_type (str, default "message") – "message" prints a diagnostic, "text" returns it as a string, "data" returns the set of matching PersonId values.

  • flip (bool, default False) – If True, identify new joiners rather than churned employees.

  • date_column (str, default "MetricDate") – Name of the date column.

  • date_format (str, default "%Y-%m-%d") – strftime format of dates in date_column.

Returns:

A printed message, a diagnostic string, or a set of PersonId values depending on return_type.

Return type:

None, str, or set

Examples

Return a diagnostic text summary:

>>> import vivainsights as vi
>>> pq_data = vi.load_pq_data()
>>> vi.identify_churn(pq_data, return_type="text")

Return the set of churned PersonIds:

>>> vi.identify_churn(pq_data, return_type="data")

Flip the logic to detect employees who appear only in later weeks:

>>> vi.identify_churn(pq_data, flip=True, return_type="text")

Customize the number of boundary weeks to compare:

>>> vi.identify_churn(pq_data, n1=3, n2=3, return_type="text")
identify_outlier
vivainsights.identify_outlier(data, group_var='MetricDate', metric='Collaboration_hours')[source]

Identify outlier weeks using z-scores for a metric.

Computes the mean of the metric per group (default: MetricDate) and the corresponding z-scores to flag outliers. Useful for detecting weeks with abnormally low collaboration, e.g. holidays.

Parameters:

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

  • group_var (str, default "MetricDate") – Grouping variable.

  • metric (str, default "Collaboration_hours") – Name of the metric column.

Returns:

A DataFrame indexed by group_var with the metric mean and a zscore column.

Return type:

pandas.DataFrame

Examples

Detect outlier groups using the default grouping variable:

>>> import vivainsights as vi
>>> pq_data = vi.load_pq_data()
>>> vi.identify_outlier(pq_data, metric="Collaboration_hours")

Specify a custom grouping variable:

>>> vi.identify_outlier(pq_data, metric="Collaboration_hours", group_var="LevelDesignation")

Option 4: Cards with Dropdowns

Core Visualizations
Available Functions

  • create_bar() - Bar charts

  • create_boxplot() - Distribution plots

  • create_bubble() - Bubble plots

  • create_line() - Line charts

Data Analysis
Available Functions

  • identify_churn() - Turnover analysis

  • identify_outlier() - Anomaly detection

  • identify_tenure() - Tenure analysis

Option 5: Summary Tables with Dropdowns