Getting started with vivaglint for Python: import and validate survey data

This article covers installation, loading your first Viva Glint survey export, inspecting the data structure, and joining employee attributes for segmented analysis.

Prerequisites

  • Python with pip installed
  • A Viva Glint Raw Data Export CSV downloaded from the Glint platform (Raw Data Export)
  • vivaglint installed (see below)

Install and import vivaglint

Install the package from PyPI:

pip install vivaglint

Import the functions you need:

from vivaglint import read_glint_survey, extract_questions, join_attributes

Import a survey export

Use read_glint_survey() to load a Viva Glint Raw Data Export CSV (Raw Data Export). The function validates the file structure, parses date columns, and returns a GlintSurvey object ready for analysis.

survey = read_glint_survey("path/to/survey_export.csv", emp_id_col="Employee ID")
Parameter Type Default Description
file_path str (required) Path to the Viva Glint CSV export file
emp_id_col str (required) Employee ID column name in your export
encoding str "UTF-8" File encoding. Change if characters appear garbled

read_glint_survey() performs these validation checks:

  • Confirms the file exists and is a readable CSV
  • Verifies required standard columns are present (see next section)
  • Confirms every question has all four suffix columns (_COMMENT, _COMMENT_TOPICS, _SENSITIVE_COMMENT_FLAG)
  • Parses Survey Cycle Completion Date and Survey Cycle Sent Date from DD-MM-YYYY HH:MM format

Note

The Viva Glint API is in private preview and may not be available yet for all users. API import is supported in the R package; the Python package currently supports Raw Data Export CSV only.

Required standard columns

The Python package expects a complete export with the following standard columns:

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 column (organization-specific name)
Survey Cycle Completion Date Yes Survey completion timestamp
Survey Cycle Sent Date Yes Survey sent timestamp
Manager ID No Manager employee ID (required for manager roll-ups)

If any required standard columns are missing, read_glint_survey() raises a descriptive error and stops.

The GlintSurvey object

read_glint_survey() returns a GlintSurvey object with two components:

  • survey.data — a pandas DataFrame with all respondent rows and columns
  • survey.metadata — a dict with:
Key Description
standard_columns List of standard column names detected at import
emp_id_col Employee ID column name supplied at import
questions DataFrame with one row per question (question, response_col, comment_col, topics_col, flag_col)
n_respondents Count of survey rows
n_questions Count of detected questions
file_path Original file path used for import
attribute_cols Populated by join_attributes() 
# Check how many respondents and questions were detected
survey.metadata["n_respondents"]
survey.metadata["n_questions"]

All vivaglint analysis functions accept both GlintSurvey objects and plain DataFrames, so you can pass survey or survey.data.

Inspect question names

Use extract_questions() to see exactly how questions are named in your export. Analysis functions reference questions by their exact text.

questions = extract_questions(survey)
print(questions)

The result is a DataFrame with one row per question:

Column Description
question Question stem text (use in analysis functions)
response_col Column containing numeric responses
comment_col Column containing open-ended comments
topics_col Column containing topic tags
flag_col Column containing sensitive comment flags

Note

Question detection depends on the suffix columns (_COMMENT, _COMMENT_TOPICS, _SENSITIVE_COMMENT_FLAG). If those columns are missing, questions will not be detected.

Join employee attributes

To segment results by department, job level, tenure, or other attributes, join an employee attribute file using join_attributes().

survey_enriched = join_attributes(survey, attribute_source="employee_attributes.csv")

When survey is a GlintSurvey, emp_id_col is resolved automatically from metadata. If you pass a plain DataFrame, supply it explicitly:

survey_enriched = join_attributes(df, "employee_attributes.csv", emp_id_col="Employee ID")
Parameter Type Default Description
survey GlintSurvey or DataFrame (required) The survey object to enrich
attribute_source str or DataFrame (required) Path to a CSV or a preloaded DataFrame
emp_id_col str None Employee ID column; resolved from metadata when possible

Attribute columns are stored in survey.metadata["attribute_cols"] for later reference.

Split survey data

Use split_survey_data() to separate numeric responses and comment data.

from vivaglint import split_survey_data

parts = split_survey_data(survey)
quant = parts["quantitative"]
qual  = parts["qualitative"]

The quantitative DataFrame includes standard columns plus numeric response columns. The qualitative DataFrame includes the employee ID plus comment, topic, and sensitive flag columns.

Next steps

  • Last updated on