Function reference for vivaglint Python

This page provides a complete listing of all exported vivaglint Python functions grouped by theme, along with reference tables for the Glint Score formula, favorability thresholds, and standard column names.

Function summary

Import and validation

Function Purpose Returns Plot support
read_glint_survey() Import and validate a Viva Glint CSV export GlintSurvey No
extract_questions() Parse column names and return question metadata DataFrame No
join_attributes() Join employee attribute data to a survey GlintSurvey or DataFrame No

Reshape

Function Purpose Returns Plot support
pivot_long() Reshape survey from wide to long format DataFrame or dict No
split_survey_data() Separate numeric responses from comment data dict No

Analysis

Function Purpose Returns Plot support
summarize_survey() Per-question mean, SD, Glint Score, favorability DataFrame Yes
get_response_dist() Count and percentage per response value per question DataFrame Yes
compare_cycles() Metrics and change scores across multiple cycles DataFrame Yes
get_correlations() Pairwise inter-question correlations with p-values DataFrame or matrix Yes (long format)
extract_survey_factors() Exploratory factor analysis with loading summary dict Yes
analyze_attrition() Attrition rates by favorability group across time windows DataFrame Yes
analyze_by_attributes() Survey metrics segmented by employee attributes DataFrame Yes
search_comments() Full-text search across all comment columns DataFrame No

Hierarchy

Function Purpose Returns Plot support
aggregate_by_manager() Survey metrics rolled up to manager-team level DataFrame Yes

Function details

read_glint_survey

Import and validate a Viva Glint survey CSV export.

read_glint_survey(file_path, emp_id_col, encoding="UTF-8")
Parameter Type Default Description
file_path str or Path (required) Path to the CSV export file
emp_id_col str (required) Employee ID column name in the export
encoding str "UTF-8" File encoding; use a different encoding if characters appear garbled

Returns: GlintSurvey object with .data (DataFrame) and .metadata (dict).

extract_questions

Parse column names and return a DataFrame mapping each question stem to its related columns.

extract_questions(data, emp_id_col=None)
Parameter Type Default Description
data GlintSurvey or DataFrame (required) Survey data
emp_id_col str None Required when data is a DataFrame

Returns: DataFrame with columns question, response_col, comment_col, topics_col, flag_col.

join_attributes

Join employee attribute data to a survey for demographic analysis.

join_attributes(survey, attribute_source, emp_id_col=None)
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) Survey to enrich
attribute_source str or DataFrame (required) CSV file path or DataFrame containing attributes
emp_id_col str None Employee ID column name; resolved from metadata when possible

Returns: Enriched GlintSurvey (if input was GlintSurvey) or joined DataFrame.

pivot_long

Reshape survey data from wide format to long format.

pivot_long(survey, data_type="all", include_empty=False, include_standard_cols=True)
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) Survey data
data_type str "all" "all", "comments", or "both"
include_empty bool False Include empty comment rows when data_type is "comments"
include_standard_cols bool or list[str] True Include standard columns, or pass a list to subset

Returns: DataFrame with question, response, comment, comment_topics, sensitive_flag. If data_type="both", returns a dict with keys "all" and "comments".

split_survey_data

Separate a survey into quantitative (numeric responses) and qualitative (comments) components.

split_survey_data(survey, emp_id_col=None)
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) Survey data
emp_id_col str None Required when survey is a DataFrame

Returns: dict with keys "quantitative" and "qualitative".

summarize_survey

Calculate per-question metrics including mean, SD, Glint Score, response counts, and favorability percentages.

summarize_survey(survey, scale_points, questions="all", emp_id_col=None, plot=False)
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) Survey data
scale_points int (required) Number of scale points (2-11)
questions list[str] or "all" "all" Question text(s) to analyze
emp_id_col str None Employee ID column name (resolved from metadata if omitted)
plot bool False Display a Glint Score bar chart

Returns: DataFrame with question, mean, sd, glint_score, n_responses, n_skips, n_total, pct_favorable, pct_neutral, pct_unfavorable.

get_response_dist

Calculate the count and percentage of respondents selecting each scale value for every question.

get_response_dist(survey, questions="all", plot=False, emp_id_col=None)
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) Survey data
questions list[str] or "all" "all" Question text(s) to analyze
plot bool False Display a stacked distribution chart
emp_id_col str None Employee ID column name (resolved from metadata if omitted)

Returns: DataFrame with question plus count_X and pct_X columns for each response value.

compare_cycles

Compare question metrics across two or more survey cycles, adding change scores relative to the prior cycle.

compare_cycles(*surveys, scale_points, cycle_names=None, plot=False)
Parameter Type Default Description
*surveys GlintSurvey or DataFrame (required) Two or more survey objects in chronological order
scale_points int (required) Number of scale points (2-11)
cycle_names list[str] None Cycle labels; defaults to "Cycle 1", "Cycle 2", ...
plot bool False Display a Glint Score trend chart

Returns: DataFrame with cycle, question, all summary metrics, plus change_from_previous, pct_change_from_previous, glint_score_change_from_previous.

get_correlations

Calculate pairwise correlations between all survey question response columns.

get_correlations(survey, method="pearson", format="long", use="pairwise", plot=False, emp_id_col=None)
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) Survey data
method str "pearson" "pearson", "spearman", or "kendall"
format str "long" "long" (one row per pair) or "matrix"
use str "pairwise" Missing value handling; R-style values accepted
plot bool False Display a correlation heatmap (long format only)
emp_id_col str None Employee ID column name (resolved from metadata if omitted)

Returns: Long-format DataFrame with question1, question2, correlation, p_value, n, or a square correlation matrix DataFrame when format="matrix".

extract_survey_factors

Run exploratory factor analysis on survey responses to identify latent constructs.

extract_survey_factors(survey, n_factors=None, rotation="oblimin", min_loading=0.3, fm="minres", plot=False)
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) Survey data
n_factors int or None None Factors to extract; None runs parallel analysis
rotation str "oblimin" Rotation method
min_loading float 0.3 Minimum absolute loading to include
fm str "minres" Factoring method
plot bool False Display a factor loading plot

Returns: dict with factor_summary (DataFrame) and fa_object (factor model object).

analyze_attrition

Link survey responses to termination records and calculate attrition rates by favorability group.

analyze_attrition(survey, attrition_file, emp_id_col=None, term_date_col=None,
                  scale_points=None, time_periods=None, attribute_cols=None,
                  min_group_size=5, plot=False)
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) Survey data
attrition_file str or DataFrame (required) CSV path or DataFrame with employee IDs and termination dates
emp_id_col str None Employee ID column name
term_date_col str None Termination date column name
scale_points int (required) Number of scale points (2-11)
time_periods list[int] [90, 180, 365] Days after survey to measure attrition
attribute_cols str or list[str] None Optional attribute columns for segmented results
min_group_size int 5 Minimum employees per attribute group
plot bool False Display an attrition chart

Returns: DataFrame with question, days, favorable_n, favorable_attrition, unfavorable_n, unfavorable_attrition, attrition_ratio, plus attribute columns and group_size if segmented.

analyze_by_attributes

Calculate survey metrics segmented by employee attribute groups.

analyze_by_attributes(survey, attribute_file=None, scale_points=None,
                      attribute_cols=None, emp_id_col=None, min_group_size=5, plot=False)
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) Survey data
attribute_file str None CSV with employee attributes (optional if already joined)
scale_points int (required) Number of scale points (2-11)
attribute_cols str or list[str] (required) Column(s) to group by
emp_id_col str None Employee ID column name
min_group_size int 5 Minimum employees per group
plot bool False Display a faceted dot plot

Returns: DataFrame with attribute columns, group_size, and all summarize_survey() columns.

search_comments

Full-text search across all comment columns using exact or fuzzy matching.

search_comments(survey, query, exact=False, max_distance=0.2)
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) Survey data
query str (required) Non-empty search string
exact bool False Case-sensitive literal substring match
max_distance float 0.2 Fuzzy match tolerance (0-1)

Returns: DataFrame with question, response, comment, topics (empty DataFrame if no matches).

aggregate_by_manager

Roll up survey metrics to the manager level.

aggregate_by_manager(survey, scale_points, emp_id_col=None, manager_id_col="Manager ID",
                     full_tree=False, plot=False)
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) Survey data
scale_points int (required) Number of scale points (2-11)
emp_id_col str None Employee ID column name
manager_id_col str "Manager ID" Manager ID column name
full_tree bool False Include all indirect reports when True
plot bool False Display a ranked lollipop chart

Returns: DataFrame with manager_id, manager_name, question, team_size, and all summarize_survey() columns.

Glint Score formula

The Glint Score normalizes any response scale (2-11 points) to a 0-100 range.

Glint Score = round(((mean - 1) / (scale_points - 1)) * 100)

Favorability thresholds

Favorability classification follows Viva Glint's standard definitions.

Scale points Favorable Neutral Unfavorable
2 2 - 1
3 3 2 1
4 4 2, 3 1
5 4, 5 3 1, 2
6 4, 5, 6 - 1, 2, 3
7 6, 7 4, 5 1, 2, 3
8 6, 7, 8 4, 5 1, 2, 3
9 7, 8, 9 4, 5, 6 1, 2, 3
10 8, 9, 10 4, 5, 6, 7 1, 2, 3
11 10, 11 8, 9 1, 2, 3, 4, 5, 6, 7

Standard columns

read_glint_survey() expects a complete export that includes the following standard columns. Manager ID is optional but required for manager roll-ups.

Column name Required Description
First Name Yes Respondent first name
Last Name Yes Respondent last name
Email Yes Respondent email address
Status Yes Survey completion status
(your emp_id_col) Yes Employee ID — primary join key for attributes and attrition
Survey Cycle Completion Date Yes Required for attrition analysis
Survey Cycle Sent Date Yes Survey sent timestamp
Manager ID No Manager employee ID — required for aggregate_by_manager()
  • Last updated on