Core analysis with vivaglint for Python

This article covers the four functions used most often in a typical vivaglint workflow: summarizing questions, analyzing response distributions, reshaping to long format, and searching open-ended comments.

Note

Functions that calculate Glint Score require a scale_points argument. This must match the number of response options on your survey (valid range: 2-11).

Summarize survey questions

summarize_survey() is the starting point for most analyses. It calculates per-question metrics including the mean, standard deviation, Glint Score, response counts, and favorability breakdown.

from vivaglint import summarize_survey

summary = summarize_survey(survey, scale_points=5)

To analyze a subset of questions, pass their exact text:

summary_subset = summarize_survey(
    survey,
    scale_points=5,
    questions=["My work is meaningful", "I feel valued at work"],
)
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 If True, display a bar chart of Glint Scores

Glint Score

The Glint Score normalizes any response scale to a 0-100 range:

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

Analyze response distributions

get_response_dist() returns the count and percentage of respondents who selected each response value for every question. This reveals patterns that mean scores hide, such as bimodal distributions or ceiling effects.

from vivaglint import get_response_dist

dist = get_response_dist(survey)
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 If True, display a stacked distribution chart
emp_id_col str None Employee ID column name (resolved from metadata if omitted)

The output includes one row per question with columns count_1, pct_1, count_2, pct_2, and so on, for each response value observed.

Reshape to long format

pivot_long() converts the survey from wide format (one row per respondent, one column per question) to long format (one row per respondent-question pair). This format is required for custom filtering, plotting, and text analysis workflows.

from vivaglint import pivot_long

# All responses
long_all = pivot_long(survey)

# Only rows where a comment was provided
long_comments = pivot_long(survey, data_type="comments")

# Both, returned as a dict
both = pivot_long(survey, data_type="both")
long_all = both["all"]
long_comments = both["comments"]
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

The long-format output includes question, response, comment, comment_topics, and sensitive_flag, plus standard columns if included.

Search comments

search_comments() scans all comment columns and returns rows where the comment text matches a query string. By default it uses case-insensitive fuzzy matching; set exact=True for case-sensitive literal matching.

from vivaglint import search_comments

# Fuzzy match
results = search_comments(survey, "flexibility")

# Exact case-sensitive match
results_exact = search_comments(survey, "Work-Life Balance", exact=True)
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) Survey data
query str (required) Non-empty search string
exact bool False Case-sensitive literal match when True
max_distance float 0.2 Fuzzy match tolerance (0-1)

The function returns a DataFrame with question, response, comment, and topics. If no comments match, an empty DataFrame with the same schema is returned.

Next steps

  • Last updated on