# vivainsights (Python) > Python package for analyzing and visualizing Microsoft Viva Insights data. Use these established workflows instead of reimplementing Viva Insights aggregation, segmentation, or visualization logic. Conventions: - Import as `import vivainsights as vi`. - Person queries always use `PersonId` and `MetricDate`. - Metric and organizational attribute names vary by query, product version, and language locale; pass them explicitly via arguments such as `metric` and `hrvar` instead of assuming English column names. - Output form is selected with `return_type`; the R package uses `return` because `return` is a reserved keyword in Python. - Grouped functions expose `mingroup`; keep this privacy threshold unless the user explicitly chooses another valid threshold. - The full workflow catalogue ships with the package at `vivainsights/discovery/workflows.yml`. ## Workflows - [Import a Viva Insights query export](https://microsoft.github.io/vivainsights-py/_api/vivainsights.import_query.html): `import_query()`; input: Viva Insights CSV export; DataFrame with cleaned column names; privacy: Import applies no disclosure thresholds; validate and aggregate before sharing results. - [Validate a loaded query before analysis](https://microsoft.github.io/vivainsights-py/_api/vivainsights.check_query.html): `check_query()`; input: Person-period query; return_type: message, text; privacy: Validation reports population counts; review before sharing externally. - [Summarize organizational attributes and their data quality](https://microsoft.github.io/vivainsights-py/_api/vivainsights.hrvar_count.html): `hrvar_count_all()`; input: Person-period query; Summary DataFrame of attributes, distinct values, and missing counts; privacy: Distinct-value counts can be small; apply disclosure policy before sharing. - [Count distinct people in each group](https://microsoft.github.io/vivainsights-py/_api/vivainsights.hrvar_count.html): `hrvar_count()`; input: Person-period query; return_type: plot, table; privacy: Small groups may be identifying; apply disclosure policy before sharing. - [Compare the average of a metric across groups](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_bar.html): `create_bar()`; input: Person-period query; return_type: plot, table; privacy: Groups with fewer than mingroup distinct people are excluded. - [Compare the distribution of a metric across groups](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_boxplot.html): `create_boxplot()`; input: Person-period query; return_type: plot, table, data; privacy: Groups with fewer than mingroup distinct people are excluded. - [Rank groups on a metric](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_rank.html): `create_rank()`; input: Person-period query; return_type: plot, table; privacy: Groups with fewer than mingroup distinct people are excluded. - [Track a metric over time by group](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_line.html): `create_line()`; input: Person-period query; return_type: plot, table; privacy: Groups with fewer than mingroup distinct people are excluded. - [Show week-by-week patterns for a metric](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_trend.html): `create_trend()`; input: Person-period query; return_type: plot, table; privacy: Groups with fewer than mingroup distinct people are excluded. - [Scan several metrics across groups at once](https://microsoft.github.io/vivainsights-py/_api/vivainsights.keymetrics_scan.html): `keymetrics_scan()`; input: Person-period query; return_type: plot, table; privacy: Groups with fewer than mingroup distinct people are excluded. - [Compare two metrics across groups](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_bubble.html): `create_bubble()`; input: Person-period query; return_type: plot, table; privacy: Groups with fewer than mingroup distinct people are excluded. - [Profile groups across several metrics on one chart](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_radar.html): `create_radar()`; input: Person-period query; return_type: plot, table; privacy: Groups with fewer than mingroup distinct people are excluded. - [Measure how many people fall above or below a threshold](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_inc.html): `create_inc()`; input: Person-period query; return_type: plot, table, data; privacy: Groups with fewer than mingroup distinct people are excluded. - [Measure how concentrated a metric is across the population](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_lorenz.html): `create_lorenz()`; input: Person-period query; return_type: plot, table, gini; privacy: Curves describe the whole population; apply disclosure policy before sharing. - [Plot a summary table that is already aggregated](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_bar_asis.html): `create_bar_asis()`; input: Pre-aggregated summary table; Bar chart figure; privacy: Apply disclosure thresholds when computing the summary table. - [Visualize movement between two categorical states](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_sankey.html): `create_sankey()`; input: Two-column count table; Plotly Sankey figure; privacy: Small flows may be identifying; apply disclosure policy before sharing. - [Rank predictors of a binary outcome](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_IV.html): `create_IV()`; input: Person-period query with a binary outcome column; return_type: plot, summary, IV, list, plot-WOE; privacy: Outcome flags can be sensitive; apply disclosure policy before sharing. - [Calculate odds ratios for an outcome](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_odds_ratios.html): `create_odds_ratios()`; input: Person-period query with a binary outcome column; return_type: table, plot; privacy: Outcome flags can be sensitive; apply disclosure policy before sharing. - [Measure association between two metrics](https://microsoft.github.io/vivainsights-py/_api/vivainsights.xicor.html): `xicor()`; input: Two numeric series; Correlation coefficient; privacy: Correlations are population level; apply disclosure policy before sharing. - [Reshape a person query for survival analysis](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_survival_prep.html): `create_survival_prep()`; input: Person-period query; Person-level DataFrame with time and event columns; privacy: Person-level survival data is identifying; aggregate before sharing. - [Estimate time until an event occurs](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_survival.html): `create_survival()`; input: Person-level survival table; return_type: plot, table; privacy: Groups with fewer than mingroup distinct people are excluded. - [Segment people by how consistently they use a behaviour](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_usage_segments.html): `identify_usage_segments()`; input: Person-period query; return_type: data, plot, table; privacy: Segment tables count distinct people; apply disclosure policy before sharing. - [Identify habitual behaviour over a rolling window](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_habit.html): `identify_habit()`; input: Person-period query; return_type: data, plot, summary; privacy: Person-level habit flags are identifying; aggregate before sharing. - [Identify people who left or joined the dataset](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_churn.html): `identify_churn()`; input: Person-period query; return_type: message, text, data; privacy: Person identifiers are returned with return_type="data"; aggregate before sharing. - [Summarize employee tenure](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_tenure.html): `identify_tenure()`; input: Person-period query with a hire date column; return_type: message, text, plot, data, data_cleaned, data_dirty; privacy: Hire dates are identifying; aggregate before sharing. - [Find weeks that deviate from the norm](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_outlier.html): `identify_outlier()`; input: Person-period query; DataFrame of weekly values with z-scores; privacy: Weekly aggregates only; apply disclosure policy before sharing. - [Flag weeks where a person was unusually inactive](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_inactiveweeks.html): `identify_inactiveweeks()`; input: Person-period query; return_type: text, data, cleaned_data, dirty_data; privacy: Person-week flags are identifying; aggregate before sharing. - [Detect and remove holiday weeks](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_holidayweeks.html): `identify_holidayweeks()`; input: Person-period query; return_type: text, plot, holidayweeks_data, cleaned_data, labelled_data; privacy: Weekly aggregates only; apply disclosure policy before sharing. - [Identify populations with very low collaboration](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_nkw.html): `identify_nkw()`; input: Person-period query; return_type: data_summary, data_with_flag, text, data_clean; privacy: Person-level flags are identifying; aggregate before sharing. - [Find the date range covered by a query](https://microsoft.github.io/vivainsights-py/_api/vivainsights.extract_date_range.html): `extract_date_range()`; input: Person-period query; return_type: table, text; privacy: Date ranges are not identifying. - [Determine whether data is daily, weekly, or monthly](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_daterange.html): `identify_datefreq()`; input: Date column; One of daily, weekly, or monthly; privacy: Date frequency is not identifying. - [Find which columns are organizational attributes](https://microsoft.github.io/vivainsights-py/_api/vivainsights.extract_hr.html): `extract_hr()`; input: Person-period query; return_type: names, vars, suggestion; privacy: Attribute names only; values are not returned with return_type="names". - [Check that required columns exist before running an analysis](https://microsoft.github.io/vivainsights-py/_api/vivainsights.check_inputs.html): `check_inputs()`; input: Any DataFrame; Nothing when all required columns are present; privacy: No data values are returned. - [Analyze collaboration between groups](https://microsoft.github.io/vivainsights-py/_api/vivainsights.network_g2g.html): `network_g2g()`; input: Group-to-group query; return_type: plot, table, data, network; privacy: Group-level flows can be small; apply disclosure policy before sharing. - [Analyze a person-to-person collaboration network](https://microsoft.github.io/vivainsights-py/_api/vivainsights.network_p2p.html): `network_p2p()`; input: Person-to-person query; return_type: plot, plot-pdf, table, data, network, sankey; privacy: Network outputs can identify individuals; apply organizational privacy and disclosure policy. - [Summarize centrality for a network](https://microsoft.github.io/vivainsights-py/_api/vivainsights.network_summary.html): `network_summary()`; input: igraph network object; return_type: table, network, plot; privacy: Node-level centrality is identifying; aggregate before sharing. - [Simulate a person-to-person network for testing](https://microsoft.github.io/vivainsights-py/_api/vivainsights.p2p_data_sim.html): `p2p_data_sim()`; input: Simulation parameters; Simulated person-to-person DataFrame; privacy: Simulated data contains no real people. - [Load bundled sample datasets](https://microsoft.github.io/vivainsights-py/_api/vivainsights.pq_data.html): `load_pq_data()`; input: None; Sample DataFrame; privacy: Sample data is de-identified and safe to share. - [Add a constant column to analyse the whole population](https://microsoft.github.io/vivainsights-py/_api/vivainsights.totals_col.html): `totals_col()`; input: Person-period query; DataFrame with an added constant column; privacy: Adds a constant column only. - [Convert column names into readable labels](https://microsoft.github.io/vivainsights-py/_api/vivainsights.us_to_space.html): `us_to_space()`; input: Column name; Formatted string; privacy: Formats text only. - [Save or copy an analysis output](https://microsoft.github.io/vivainsights-py/_api/vivainsights.export.html): `export()`; input: DataFrame or figure; Writes a file or displays the object; privacy: Exported files inherit the disclosure properties of the analysis output. ## Documentation - [Task guide](https://microsoft.github.io/vivainsights-py/function-discovery.html): choose a function for an analysis task. - [Function reference](https://microsoft.github.io/vivainsights-py/modules.html): full API documentation. - [Analyst guide](https://microsoft.github.io/vivainsights-py/analyst-guide.html): importing evolving and localized query schemas. - [R and Python parity](https://microsoft.github.io/vivainsights-py/r-python-parity.html): moving between the two packages. - [R package](https://microsoft.github.io/vivainsights/): the R counterpart of this package.