vivainsights.create_inc

Analyze the proportion of a population above or below a metric threshold.

vivainsights.create_inc.create_inc(data, metric, hrvar, mingroup=5, threshold=None, position=None, return_type='plot')

Create an incidence analysis showing the proportion of employees above or below a metric threshold.

When a single hrvar is supplied, a bar chart is returned. When two hrvar values are supplied, a heatmap is returned.

Parameters:

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

• metric (str) – Metric column name, e.g. "Collaboration_hours".

• hrvar (str or list of str) – HR variable(s) for grouping (at most length 2).

• mingroup (int) – Minimum group size. Defaults to 5.

• threshold (float, optional) – Value to split the population.

• position (str, optional) – "above" or "below".

• return_type (str) – "plot" (default) or "table".

Returns:

Plot or table depending on return_type.

Return type:

matplotlib.figure.Figure or pandas.DataFrame

Raises:

ValueError – If hrvar has more than two elements.

Examples

Bar chart showing incidence above a threshold (single HR variable):

>>> import vivainsights as vi
>>> pq_data = vi.load_pq_data()
>>> vi.create_inc(
...     pq_data,
...     metric="Collaboration_hours",
...     hrvar="LevelDesignation",
...     threshold=10,
...     position="above",
... )

Heatmap showing incidence with two HR variables:

>>> vi.create_inc(
...     pq_data,
...     metric="Collaboration_hours",
...     hrvar=["LevelDesignation", "Organization"],
...     threshold=15,
...     position="below",
... )

Return a summary table instead of a plot:

>>> vi.create_inc(
...     pq_data,
...     metric="Collaboration_hours",
...     hrvar="Organization",
...     threshold=10,
...     position="above",
...     return_type="table",
... )

vivainsights.create_inc.create_inc_bar(data, metric, hrvar, mingroup=5, threshold=None, position=None, return_type='plot', figsize=None)

Run incidence analysis with a single HR variable, returning a bar chart.

Parameters:

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

• metric (str) – Metric column name.

• hrvar (str) – HR variable for grouping.

• mingroup (int) – Minimum group size. Defaults to 5.

• threshold (float, optional) – Split threshold.

• position (str, optional) – "above" or "below".

• return_type (str) – "plot" (default) or "table".

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

Returns:

Bar chart or summary table.

Return type:

matplotlib.figure.Figure or pandas.DataFrame

Examples

Bar chart of incidence below a threshold:

>>> import vivainsights as vi
>>> pq_data = vi.load_pq_data()
>>> vi.create_inc_bar(
...     pq_data,
...     metric="Collaboration_hours",
...     hrvar="LevelDesignation",
...     threshold=20,
...     position="below",
... )

Return a summary table:

>>> vi.create_inc_bar(
...     pq_data,
...     metric="Collaboration_hours",
...     hrvar="Organization",
...     threshold=10,
...     position="above",
...     return_type="table",
... )

Customize figure size:

>>> vi.create_inc_bar(
...     pq_data,
...     metric="Collaboration_hours",
...     hrvar="LevelDesignation",
...     threshold=15,
...     position="above",
...     figsize=(10, 5),
... )

vivainsights.create_inc.create_inc_grid(data, metric, hrvar, mingroup=5, threshold=None, position=None, return_type='plot', figsize=None)

Run incidence analysis with two HR variables, returning a heatmap.

Parameters:

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

• metric (str) – Metric column name.

• hrvar (list of str) – Two HR variables for the heatmap axes.

• mingroup (int) – Minimum group size. Defaults to 5.

• threshold (float, optional) – Split threshold.

• position (str, optional) – "above" or "below".

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

• return_type (str) – "plot" (default) or "table".

Returns:

Heatmap or summary table.

Return type:

matplotlib.figure.Figure or pandas.DataFrame

Raises:

ValueError – If hrvar is not a list of length 2.

Examples

Generate a heatmap of incidence across two HR variables:

>>> import vivainsights as vi
>>> pq_data = vi.load_pq_data()
>>> vi.create_inc_grid(
...     pq_data,
...     metric="Collaboration_hours",
...     hrvar=["LevelDesignation", "Organization"],
...     threshold=15,
...     position="above",
... )

Return a summary table instead:

>>> vi.create_inc_grid(
...     pq_data,
...     metric="Collaboration_hours",
...     hrvar=["LevelDesignation", "Organization"],
...     threshold=10,
...     position="below",
...     return_type="table",
... )