Find the right vivainsights function
Source:vignettes/function-discovery.Rmd
function-discovery.RmdFind the right function
Start with the task below before writing custom dplyr,
ggplot2, or network code. The package functions apply
established Viva Insights aggregation and privacy conventions.
| Task | Start with | Input | Returns | Python parity |
|---|---|---|---|---|
| Import and prepare a Viva Insights query | import_query() |
Viva Insights CSV export | data frame |
import_query() (partial) |
| Validate query structure and data quality | validation_report() |
Person or meeting query | HTML validation report | r_only |
| Inspect available HR attributes | hrvar_count_all() |
Person query | message or table |
hrvar_count_all() (partial) |
| Compare a metric across groups | create_bar() |
Person-period query | ggplot or summary table |
create_bar() (partial) |
| Plot a metric over time | create_line() |
Person-period query | ggplot or summary table |
create_line() (partial) |
| Inspect a metric distribution | create_dist() |
Person-period query | ggplot or summary table | r_only |
| Rank groups by a metric | create_rank() |
Person-period query | ggplot or ranking table |
create_rank() (partial) |
| Summarize collaboration workload | collaboration_summary() |
Person-period query | ggplot or summary table | r_only |
| Segment people by product usage | identify_usage_segments() |
Person-period query | person-level data, table, or plot |
identify_usage_segments() (partial) |
| Measure retention between periods | identify_retention() |
Person-period data with a category column | message, table, or detailed data | r_only |
| Compare a profile of several metrics | create_radar() |
Person-period query | ggplot or indexed data |
create_radar() (partial) |
| Analyze time to adoption or another event | create_survival() |
Person-period event data | ggplot or survival calculation data |
create_survival() (partial) |
| Analyze a person-to-person collaboration network | network_p2p() |
Single-date person-to-person query | plot, table, node data, Sankey chart, or igraph object |
network_p2p() (partial) |
| Analyze a group-to-group collaboration network | network_g2g() |
Group-to-group query | plot or igraph object |
network_g2g() (partial) |
| Anonymize identifiers and HR attributes | anonymise() |
Viva Insights query | anonymized data frame | r_only |
| Generate a reusable analysis report | generate_report() |
Person query | rendered report files | r_only |
Workflow details
Import and prepare a Viva Insights query
Use: import_query()
Typical requests: read a Viva Insights CSV, import a person query, prepare query data
Required columns: None specified
Privacy: Import does not apply disclosure thresholds; validate and aggregate before sharing results.
Returns: data frame
import_query("Person Query.csv")Related functions: check_query(),
prep_query(), validation_report()
Validate query structure and data quality
Use: validation_report()
Typical requests: validate a query, check data quality, diagnose missing Viva Insights fields
Required columns: None specified
Privacy: Validation reports may describe small groups; review output before sharing.
Returns: HTML validation report
validation_report(pq_data)Related functions: check_query(),
extract_hr(), hrvar_count_all()
Inspect available HR attributes
Use: hrvar_count_all()
Typical requests: find grouping variables, count HR attribute levels, choose an HR variable
Required columns: PersonId
Privacy: Use the counts to avoid selecting attributes that create groups below the disclosure threshold.
Returns: message or table
hrvar_count_all(pq_data, return = "table")Related functions: extract_hr(),
identify_privacythreshold()
Compare a metric across groups
Use: create_bar()
Typical requests: compare organizations, plot a metric by HR attribute, summarize group averages
Required columns: PersonId
Privacy: Groups with fewer than mingroup distinct people are excluded.
Returns: ggplot or summary table
create_bar(pq_data, metric = "Collaboration_hours", hrvar = "Organization")Related functions: create_boxplot(),
create_rank(), create_bar_asis()
Plot a metric over time
Use: create_line()
Typical requests: create a time trend, compare weekly metrics, plot change over time
Required columns: PersonId, MetricDate
Privacy: Groups with fewer than mingroup distinct people are excluded.
Returns: ggplot or summary table
create_line(pq_data, metric = "Collaboration_hours", hrvar = "Organization")Related functions: create_trend(),
hr_trend(), collaboration_trend()
Inspect a metric distribution
Use: create_dist()
Typical requests: plot a distribution, inspect metric spread, compare distributions by group
Required columns: PersonId
Privacy: Groups with fewer than mingroup distinct people are excluded.
Returns: ggplot or summary table
create_dist(pq_data, metric = "Collaboration_hours", hrvar = "Organization")Related functions: create_density(),
create_hist(), create_boxplot()
Rank groups by a metric
Use: create_rank()
Typical requests: rank organizations, identify high and low groups, compare group performance
Required columns: PersonId
Privacy: Groups with fewer than mingroup distinct people are excluded.
Returns: ggplot or ranking table
create_rank(pq_data, metric = "Collaboration_hours", hrvar = "Organization")Related functions: create_bar(),
create_rank_combine()
Summarize collaboration workload
Typical requests: analyze collaboration hours, summarize meetings and email, compare collaboration patterns
Required columns: PersonId
Privacy: Groups with fewer than mingroup distinct people are excluded.
Returns: ggplot or summary table
collaboration_summary(pq_data, hrvar = "Organization")Related functions:
collaboration_area(), collaboration_dist(),
collaboration_rank()
Segment people by product usage
Use: identify_usage_segments()
Typical requests: classify usage segments, find power users, analyze adoption maturity
Required columns: PersonId, MetricDate
Privacy: Review segment counts before sharing; downstream summaries should apply disclosure thresholds.
Returns: person-level data, table, or plot
identify_usage_segments(pq_data, metric = "Copilot_Chat_active_days")Related functions: identify_habit(),
create_rogers(), identify_retention()
Measure retention between periods
Use: identify_retention()
Typical requests: calculate retention, track retained power users, compare category membership over time
Required columns: PersonId, MetricDate
Privacy: Review returned counts and suppress small categories before sharing.
Returns: message, table, or detailed data
identify_retention(data, start_x = "2026-01-01", end_x = "2026-02-01", start_y = "2026-02-01", end_y = "2026-03-01", category = "Segment", category_values = "Power User")Related functions:
identify_usage_segments(),
identify_churn()
Compare a profile of several metrics
Use: create_radar()
Typical requests: create a radar chart, compare groups across metrics, normalize a metric profile
Required columns: PersonId
Privacy: Groups with fewer than mingroup distinct people are excluded.
Returns: ggplot or indexed data
create_radar(pq_data, metrics = c("Email_hours", "Meeting_hours"), hrvar = "Organization")Related functions: create_radar_calc(),
create_radar_viz()
Analyze time to adoption or another event
Use: create_survival()
Typical requests: create a survival curve, analyze time to adoption, compare event timing by group
Required columns: PersonId, MetricDate
Privacy: Apply an appropriate mingroup threshold to group comparisons.
Returns: ggplot or survival calculation data
create_survival(surv_data, time_col = "time", event_col = "event", hrvar = "Organization")Related functions:
create_survival_prep(),
create_survival_calc(),
create_survival_viz()
Analyze a person-to-person collaboration network
Use: network_p2p()
Typical requests: create a person network, find network communities, calculate network centrality
Required columns: PrimaryCollaborator_PersonId, SecondaryCollaborator_PersonId
Privacy: Network outputs can identify individuals; apply organizational privacy and disclosure policy.
Returns: plot, table, node data, Sankey chart, or igraph object
network_p2p(p2p_data, return = "network")Related functions: network_summary(),
p2p_data_sim(), create_sankey()
Analyze a group-to-group collaboration network
Use: network_g2g()
Typical requests: create an organization network, compare group connections, analyze collaboration between teams
Required columns: None specified
Privacy: Confirm source query groups meet disclosure requirements.
Returns: plot or igraph object
network_g2g(g2g_data)Related functions: network_p2p(),
network_summary()
Anonymize identifiers and HR attributes
Use: anonymise()
Typical requests: anonymize employee data, remove identifying information, prepare sample data safely
Required columns: None specified
Privacy: Anonymization reduces direct identifiers but does not replace disclosure review.
Returns: anonymized data frame
anonymise(pq_data)Related functions: anonymize(),
jitter_metrics(),
identify_privacythreshold()
Generate a reusable analysis report
Use: generate_report()
Typical requests: create an HTML report, generate a wellbeing report, automate analysis output
Required columns: PersonId
Privacy: Review the generated report and its grouping thresholds before distribution.
Returns: rendered report files
generate_report(title = "Viva Insights report", filename = "report", outputs = output_list, titles = title_list, subheaders = rep("", length(output_list)), echos = rep(FALSE, length(output_list)), levels = rep(2, length(output_list)))Related functions: generate_report2(),
validation_report()