<!-- Generated by tools/generate_discovery.py from vivainsights/discovery/workflows.yml. Do not edit manually. -->

# Find the right function

This guide maps analysis tasks to **vivainsights** functions so analysts and
AI agents can use established package workflows instead of rebuilding Viva
Insights aggregation and visualization logic.

Person queries consistently use `PersonId` and `MetricDate`. Metric and
organizational attribute names vary by query, product version, and language
locale, so they are passed explicitly through arguments such as `metric` and
`hrvar`.

## Task index

| Task | Function | Returns |
| --- | --- | --- |
| Import a Viva Insights query export | `import_query()` | DataFrame with cleaned column names |
| Validate a loaded query before analysis | `check_query()` | `message`, `text` |
| Summarize organizational attributes and their data quality | `hrvar_count_all()` | Summary DataFrame of attributes, distinct values, and missing counts |
| Count distinct people in each group | `hrvar_count()` | `plot`, `table` |
| Compare the average of a metric across groups | `create_bar()` | `plot`, `table` |
| Compare the distribution of a metric across groups | `create_boxplot()` | `plot`, `table`, `data` |
| Rank groups on a metric | `create_rank()` | `plot`, `table` |
| Track a metric over time by group | `create_line()` | `plot`, `table` |
| Show week-by-week patterns for a metric | `create_trend()` | `plot`, `table` |
| Scan several metrics across groups at once | `keymetrics_scan()` | `plot`, `table` |
| Compare two metrics across groups | `create_bubble()` | `plot`, `table` |
| Profile groups across several metrics on one chart | `create_radar()` | `plot`, `table` |
| Measure how many people fall above or below a threshold | `create_inc()` | `plot`, `table`, `data` |
| Measure how concentrated a metric is across the population | `create_lorenz()` | `plot`, `table`, `gini` |
| Plot a summary table that is already aggregated | `create_bar_asis()` | Bar chart figure |
| Visualize movement between two categorical states | `create_sankey()` | Plotly Sankey figure |
| Rank predictors of a binary outcome | `create_IV()` | `plot`, `summary`, `IV`, `list`, `plot-WOE` |
| Calculate odds ratios for an outcome | `create_odds_ratios()` | `table`, `plot` |
| Measure association between two metrics | `xicor()` | Correlation coefficient |
| Reshape a person query for survival analysis | `create_survival_prep()` | Person-level DataFrame with time and event columns |
| Estimate time until an event occurs | `create_survival()` | `plot`, `table` |
| Segment people by how consistently they use a behaviour | `identify_usage_segments()` | `data`, `plot`, `table` |
| Identify habitual behaviour over a rolling window | `identify_habit()` | `data`, `plot`, `summary` |
| Identify people who left or joined the dataset | `identify_churn()` | `message`, `text`, `data` |
| Summarize employee tenure | `identify_tenure()` | `message`, `text`, `plot`, `data`, `data_cleaned`, `data_dirty` |
| Find weeks that deviate from the norm | `identify_outlier()` | DataFrame of weekly values with z-scores |
| Flag weeks where a person was unusually inactive | `identify_inactiveweeks()` | `text`, `data`, `cleaned_data`, `dirty_data` |
| Detect and remove holiday weeks | `identify_holidayweeks()` | `text`, `plot`, `holidayweeks_data`, `cleaned_data`, `labelled_data` |
| Identify populations with very low collaboration | `identify_nkw()` | `data_summary`, `data_with_flag`, `text`, `data_clean` |
| Find the date range covered by a query | `extract_date_range()` | `table`, `text` |
| Determine whether data is daily, weekly, or monthly | `identify_datefreq()` | One of daily, weekly, or monthly |
| Find which columns are organizational attributes | `extract_hr()` | `names`, `vars`, `suggestion` |
| Check that required columns exist before running an analysis | `check_inputs()` | Nothing when all required columns are present |
| Analyze collaboration between groups | `network_g2g()` | `plot`, `table`, `data`, `network` |
| Analyze a person-to-person collaboration network | `network_p2p()` | `plot`, `plot-pdf`, `table`, `data`, `network`, `sankey` |
| Summarize centrality for a network | `network_summary()` | `table`, `network`, `plot` |
| Simulate a person-to-person network for testing | `p2p_data_sim()` | Simulated person-to-person DataFrame |
| Load bundled sample datasets | `load_pq_data()` | Sample DataFrame |
| Add a constant column to analyse the whole population | `totals_col()` | DataFrame with an added constant column |
| Convert column names into readable labels | `us_to_space()` | Formatted string |
| Save or copy an analysis output | `export()` | Writes a file or displays the object |

## Workflow details

### Import a Viva Insights query export

- **Function**: [`import_query()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.import_query.html)
- **Use when**: load a Viva Insights CSV export; read a person query into Python; start an analysis from an exported query
- **Input**: Viva Insights CSV export
- **Columns**: none
- **Returns**: DataFrame with cleaned column names
- **Privacy**: Import applies no disclosure thresholds; validate and aggregate before sharing results.
- **Related**: `check_query()`, `extract_hr()`, `extract_date_range()`
- **R counterpart**: `import_query()` (partial)

```python
import vivainsights as vi

vi.import_query("query.csv")
```

### Validate a loaded query before analysis

- **Function**: [`check_query()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.check_query.html)
- **Use when**: check whether my query is valid; run data validation on a person query; sanity check a Viva Insights dataset
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`, `MetricDate`
- **Returns**: Printed message or descriptive text
- **Privacy**: Validation reports population counts; review before sharing externally.
- **Related**: `hrvar_count_all()`, `extract_hr()`, `extract_date_range()`, `identify_datefreq()`
- **R counterpart**: `check_query()` (partial)

```python
import vivainsights as vi

vi.check_query(vi.load_pq_data(), return_type="text")
```

### Summarize organizational attributes and their data quality

- **Function**: [`hrvar_count_all()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.hrvar_count.html)
- **Use when**: list the HR attributes in my data; check missing values in organizational attributes; see how many distinct values each attribute has
- **Input**: Person-period query
- **Columns**: selected: `hrvar_list`
- **Returns**: Summary DataFrame of attributes, distinct values, and missing counts
- **Privacy**: Distinct-value counts can be small; apply disclosure policy before sharing.
- **Related**: `hrvar_count()`, `extract_hr()`, `check_query()`
- **R counterpart**: `hrvar_count_all()` (partial)

```python
import vivainsights as vi

vi.hrvar_count_all(vi.load_pq_data())
```

### Count distinct people in each group

- **Function**: [`hrvar_count()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.hrvar_count.html)
- **Use when**: how many employees are in each organization; count headcount by HR attribute; check group sizes before analysis
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`; selected: `hrvar`
- **Returns**: Bar chart or summary table of distinct people per group
- **Privacy**: Small groups may be identifying; apply disclosure policy before sharing.
- **Related**: `hrvar_count_all()`, `totals_col()`, `create_bar()`
- **R counterpart**: `hrvar_count()` (partial)

```python
import vivainsights as vi

vi.hrvar_count(vi.load_pq_data(), hrvar="Organization", return_type="table")
```

### Compare the average of a metric across groups

- **Function**: [`create_bar()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_bar.html)
- **Use when**: compare organizations on a metric; plot average collaboration by HR attribute; summarize group averages
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`; selected: `metric`, `hrvar`
- **Returns**: Bar chart or summary table
- **Privacy**: Groups with fewer than mingroup distinct people are excluded.
- **Related**: `create_boxplot()`, `create_rank()`, `create_bubble()`, `create_bar_asis()`
- **R counterpart**: `create_bar()` (partial)

```python
import vivainsights as vi

vi.create_bar(vi.load_pq_data(), metric="Emails_sent", hrvar="Organization", return_type="table")
```

### Compare the distribution of a metric across groups

- **Function**: [`create_boxplot()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_boxplot.html)
- **Use when**: show the spread of a metric by group; compare medians and outliers across organizations; create a boxplot by HR attribute
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`, `MetricDate`; selected: `metric`, `hrvar`
- **Returns**: Boxplot, summary table, or person-level data
- **Privacy**: Groups with fewer than mingroup distinct people are excluded.
- **Related**: `create_bar()`, `create_lorenz()`, `create_inc()`
- **R counterpart**: `create_boxplot()` (partial)

```python
import vivainsights as vi

vi.create_boxplot(vi.load_pq_data(), metric="Emails_sent", hrvar="Organization", return_type="table")
```

### Rank groups on a metric

- **Function**: [`create_rank()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_rank.html)
- **Use when**: which groups are highest and lowest on a metric; rank organizations by collaboration; find top and bottom groups
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`; selected: `metric`, `hrvar`
- **Returns**: Ranked plot or table
- **Privacy**: Groups with fewer than mingroup distinct people are excluded.
- **Related**: `create_bar()`, `keymetrics_scan()`
- **R counterpart**: `create_rank()` (partial)

```python
import vivainsights as vi

vi.create_rank(vi.load_pq_data(), metric="Emails_sent", hrvar="Organization", return_type="table")
```

### Track a metric over time by group

- **Function**: [`create_line()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_line.html)
- **Use when**: show a metric trend over time; plot weekly collaboration by organization; has this metric changed over time
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`, `MetricDate`; selected: `metric`, `hrvar`
- **Returns**: Line chart or summary table
- **Privacy**: Groups with fewer than mingroup distinct people are excluded.
- **Related**: `create_trend()`, `keymetrics_scan()`
- **R counterpart**: `create_line()` (partial)

```python
import vivainsights as vi

vi.create_line(vi.load_pq_data(), metric="Emails_sent", hrvar="Organization", return_type="table")
```

### Show week-by-week patterns for a metric

- **Function**: [`create_trend()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_trend.html)
- **Use when**: create a heatmap of weekly activity; show how a metric varies week by week; visualize seasonality by group
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`, `MetricDate`; selected: `metric`, `hrvar`
- **Returns**: Heatmap or summary table
- **Privacy**: Groups with fewer than mingroup distinct people are excluded.
- **Related**: `create_line()`, `identify_outlier()`
- **R counterpart**: `create_trend()` (partial)

```python
import vivainsights as vi

vi.create_trend(vi.load_pq_data(), metric="Emails_sent", hrvar="Organization", return_type="table")
```

### Scan several metrics across groups at once

- **Function**: [`keymetrics_scan()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.keymetrics_scan.html)
- **Use when**: compare many metrics by organization; build a key metrics overview; scan a scorecard of metrics
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`; selected: `metrics`, `hrvar`
- **Returns**: Heatmap or summary table of metrics by group
- **Privacy**: Groups with fewer than mingroup distinct people are excluded.
- **Related**: `create_rank()`, `create_radar()`, `create_bar()`
- **R counterpart**: `keymetrics_scan()` (partial)

```python
import vivainsights as vi

vi.keymetrics_scan(vi.load_pq_data(), hrvar="Organization", metrics=["Emails_sent", "Collaboration_hours"], return_type="table")
```

### Compare two metrics across groups

- **Function**: [`create_bubble()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_bubble.html)
- **Use when**: plot one metric against another by group; show the relationship between two metrics; create a bubble chart of groups
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`; selected: `metric_x`, `metric_y`, `hrvar`
- **Returns**: Bubble chart or summary table
- **Privacy**: Groups with fewer than mingroup distinct people are excluded.
- **Related**: `create_bar()`, `create_boxplot()`, `xicor()`
- **R counterpart**: `create_bubble()` (partial)

```python
import vivainsights as vi

vi.create_bubble(vi.load_pq_data(), metric_x="Emails_sent", metric_y="Collaboration_hours", hrvar="Organization", return_type="table")
```

### Profile groups across several metrics on one chart

- **Function**: [`create_radar()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_radar.html)
- **Use when**: create a radar chart comparing groups; show a multi-metric profile by organization; compare groups on several metrics at once
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`; selected: `metrics`, `hrvar`
- **Returns**: Radar chart or indexed summary table
- **Privacy**: Groups with fewer than mingroup distinct people are excluded.
- **Related**: `keymetrics_scan()`, `create_rank()`
- **R counterpart**: `create_radar()` (partial)

```python
import vivainsights as vi

vi.create_radar(vi.load_pq_data(), metrics=["Emails_sent", "Collaboration_hours"], hrvar="Organization", return_type="table")
```

### Measure how many people fall above or below a threshold

- **Function**: [`create_inc()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_inc.html)
- **Use when**: what proportion of people exceed a threshold; show incidence above a metric value; compare threshold rates across groups
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`; selected: `metric`, `hrvar`, `threshold`, `position`
- **Returns**: Incidence plot, summary table, or underlying data
- **Privacy**: Groups with fewer than mingroup distinct people are excluded.
- **Related**: `create_bar()`, `create_boxplot()`, `create_lorenz()`
- **R counterpart**: `create_inc()` (partial)

```python
import vivainsights as vi

vi.create_inc(vi.load_pq_data(), metric="Emails_sent", hrvar="Organization", threshold=20, position="above", return_type="table")
```

### Measure how concentrated a metric is across the population

- **Function**: [`create_lorenz()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_lorenz.html)
- **Use when**: calculate a Gini coefficient; plot a Lorenz curve; is this metric concentrated in a few people
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`; selected: `metric`
- **Returns**: Lorenz curve, summary table, or Gini coefficient
- **Privacy**: Curves describe the whole population; apply disclosure policy before sharing.
- **Related**: `create_inc()`, `create_boxplot()`
- **R counterpart**: `create_lorenz()` (partial)

```python
import vivainsights as vi

vi.create_lorenz(vi.load_pq_data(), metric="Emails_sent", return_type="gini")
```

### Plot a summary table that is already aggregated

- **Function**: [`create_bar_asis()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_bar_asis.html)
- **Use when**: plot a table I already calculated; create a bar chart without re-aggregating; visualize a precomputed summary
- **Input**: Pre-aggregated summary table
- **Columns**: selected: `group_var`, `bar_var`
- **Returns**: Bar chart figure
- **Privacy**: Apply disclosure thresholds when computing the summary table.
- **Related**: `create_bar()`, `export()`
- **R counterpart**: `create_bar_asis()` (partial)

```python
import vivainsights as vi

vi.create_bar_asis(vi.create_bar(vi.load_pq_data(), metric="Emails_sent", hrvar="Organization", return_type="table"), group_var="Organization", bar_var="metric")
```

### Visualize movement between two categorical states

- **Function**: [`create_sankey()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_sankey.html)
- **Use when**: show how people move between segments; create a Sankey chart of transitions; visualize flows between categories
- **Input**: Two-column count table
- **Columns**: selected: `var1`, `var2`, `count`
- **Returns**: Plotly Sankey figure
- **Privacy**: Small flows may be identifying; apply disclosure policy before sharing.
- **Related**: `identify_usage_segments()`, `network_p2p()`
- **R counterpart**: `create_sankey()` (partial)

```python
import vivainsights as vi

vi.create_sankey(transitions, var1="UsageSegments_previous", var2="UsageSegments", count="n")
```

### Rank predictors of a binary outcome

- **Function**: [`create_IV()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_IV.html)
- **Use when**: which metrics predict an outcome; calculate information value; find drivers of a binary flag
- **Input**: Person-period query with a binary outcome column
- **Columns**: fixed: `PersonId`; selected: `predictors`, `outcome`
- **Returns**: Plot, summary table, information value scores, or a list of outputs
- **Privacy**: Outcome flags can be sensitive; apply disclosure policy before sharing.
- **Related**: `create_odds_ratios()`, `xicor()`
- **R counterpart**: `create_IV()` (partial)

```python
import vivainsights as vi

vi.create_IV(data, predictors=["Emails_sent", "Collaboration_hours"], outcome="IsHighUsage", return_type="summary")
```

### Calculate odds ratios for an outcome

- **Function**: [`create_odds_ratios()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_odds_ratios.html)
- **Use when**: calculate odds ratios; how much more likely is an outcome; quantify the effect of ordinal metrics
- **Input**: Person-period query with a binary outcome column
- **Columns**: fixed: `PersonId`; selected: `ord_metrics`, `metric`
- **Returns**: Odds ratio table or plot
- **Privacy**: Outcome flags can be sensitive; apply disclosure policy before sharing.
- **Related**: `create_IV()`, `xicor()`
- **R counterpart**: `create_odds_ratios()` (partial)

```python
import vivainsights as vi

vi.create_odds_ratios(data, ord_metrics=["Emails_sent"], metric="IsHighUsage", return_type="table")
```

### Measure association between two metrics

- **Function**: [`xicor()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.xicor.html)
- **Use when**: correlate two metrics; measure dependence between variables; calculate the Chatterjee coefficient
- **Input**: Two numeric series
- **Columns**: selected: `x`, `y`
- **Returns**: Correlation coefficient
- **Privacy**: Correlations are population level; apply disclosure policy before sharing.
- **Related**: `create_IV()`, `create_bubble()`
- **R counterpart**: `xicor()` (partial)

```python
import vivainsights as vi

vi.xicor(vi.load_pq_data()["Emails_sent"], vi.load_pq_data()["Collaboration_hours"])
```

### Reshape a person query for survival analysis

- **Function**: [`create_survival_prep()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_survival_prep.html)
- **Use when**: prepare data for survival analysis; build time and event columns; convert a panel query to person-level survival format
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`, `MetricDate`; selected: `metric`, `event_condition`, `hrvar`
- **Returns**: Person-level DataFrame with time and event columns
- **Privacy**: Person-level survival data is identifying; aggregate before sharing.
- **Related**: `create_survival()`, `identify_churn()`
- **R counterpart**: `create_survival_prep()` (partial)

```python
import vivainsights as vi

vi.create_survival_prep(vi.load_pq_data(), metric="Emails_sent")
```

### Estimate time until an event occurs

- **Function**: [`create_survival()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.create_survival.html)
- **Use when**: run a survival analysis; plot Kaplan-Meier curves; how long until people adopt a behaviour
- **Input**: Person-level survival table
- **Columns**: fixed: `PersonId`; selected: `time_col`, `event_col`, `hrvar`
- **Returns**: Survival curve plot or survival table
- **Privacy**: Groups with fewer than mingroup distinct people are excluded.
- **Related**: `create_survival_prep()`, `identify_churn()`
- **R counterpart**: `create_survival()` (partial)

```python
import vivainsights as vi

vi.create_survival(surv_data, time_col="time", event_col="event", hrvar="Organization", return_type="table")
```

### Segment people by how consistently they use a behaviour

- **Function**: [`identify_usage_segments()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_usage_segments.html)
- **Use when**: segment users by usage intensity; find power users and habitual users; classify adoption segments
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`, `MetricDate`; selected: `metric`, `metric_str`
- **Returns**: Classified data, stacked bar chart, or summary table
- **Privacy**: Segment tables count distinct people; apply disclosure policy before sharing.
- **Related**: `identify_habit()`, `create_sankey()`
- **R counterpart**: `identify_usage_segments()` (partial)

```python
import vivainsights as vi

vi.identify_usage_segments(vi.load_pq_data(), metric="Emails_sent", version="12w", return_type="table")
```

### Identify habitual behaviour over a rolling window

- **Function**: [`identify_habit()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_habit.html)
- **Use when**: who uses this consistently; detect habits from a metric; measure sustained adoption
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`, `MetricDate`; selected: `metric`, `hrvar`
- **Returns**: Habit data, plot, or summary
- **Privacy**: Person-level habit flags are identifying; aggregate before sharing.
- **Related**: `identify_usage_segments()`
- **R counterpart**: `identify_habits()` (partial)

```python
import vivainsights as vi

vi.identify_habit(vi.load_pq_data(), metric="Emails_sent", threshold=1, width=4, max_window=4, return_type="data")
```

### Identify people who left or joined the dataset

- **Function**: [`identify_churn()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_churn.html)
- **Use when**: who churned between two periods; find new joiners; compare population at start and end
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`, `MetricDate`
- **Returns**: Message, descriptive text, or the identifiers involved
- **Privacy**: Person identifiers are returned with return_type="data"; aggregate before sharing.
- **Related**: `identify_tenure()`, `create_survival()`
- **R counterpart**: `identify_churn()` (partial)

```python
import vivainsights as vi

vi.identify_churn(vi.load_pq_data(), n1=6, n2=6, return_type="text")
```

### Summarize employee tenure

- **Function**: [`identify_tenure()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_tenure.html)
- **Use when**: calculate tenure from hire date; show the tenure distribution; find implausible hire dates
- **Input**: Person-period query with a hire date column
- **Columns**: fixed: `PersonId`, `MetricDate`; selected: `beg_date`, `end_date`
- **Returns**: Message, text, plot, or cleaned and flagged data
- **Privacy**: Hire dates are identifying; aggregate before sharing.
- **Related**: `identify_churn()`
- **R counterpart**: `identify_tenure()` (partial)

```python
import vivainsights as vi

vi.identify_tenure(data, beg_date="HireDate", end_date="MetricDate", return_type="text")
```

### Find weeks that deviate from the norm

- **Function**: [`identify_outlier()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_outlier.html)
- **Use when**: find unusual weeks; detect outliers over time; which weeks look anomalous
- **Input**: Person-period query
- **Columns**: fixed: `MetricDate`; selected: `group_var`, `metric`
- **Returns**: DataFrame of weekly values with z-scores
- **Privacy**: Weekly aggregates only; apply disclosure policy before sharing.
- **Related**: `identify_inactiveweeks()`, `identify_holidayweeks()`, `create_trend()`
- **R counterpart**: `identify_outlier()` (partial)

```python
import vivainsights as vi

vi.identify_outlier(vi.load_pq_data(), group_var="MetricDate", metric="Collaboration_hours")
```

### Flag weeks where a person was unusually inactive

- **Function**: [`identify_inactiveweeks()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_inactiveweeks.html)
- **Use when**: find inactive weeks; remove low activity weeks; clean out non-working periods
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`, `MetricDate`
- **Returns**: Text summary, flagged data, or cleaned data
- **Privacy**: Person-week flags are identifying; aggregate before sharing.
- **Related**: `identify_holidayweeks()`, `identify_outlier()`
- **R counterpart**: `identify_inactiveweeks()` (partial)

```python
import vivainsights as vi

vi.identify_inactiveweeks(vi.load_pq_data(), sd=2, return_type="text")
```

### Detect and remove holiday weeks

- **Function**: [`identify_holidayweeks()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_holidayweeks.html)
- **Use when**: find holiday weeks; exclude vacation periods; remove weeks with unusually low collaboration
- **Input**: Person-period query
- **Columns**: fixed: `MetricDate`
- **Returns**: Text summary, plot, flagged weeks, or cleaned data
- **Privacy**: Weekly aggregates only; apply disclosure policy before sharing.
- **Related**: `identify_inactiveweeks()`, `identify_outlier()`
- **R counterpart**: `identify_holidayweeks()` (partial)

```python
import vivainsights as vi

vi.identify_holidayweeks(vi.load_pq_data(), sd=1, return_type="text")
```

### Identify populations with very low collaboration

- **Function**: [`identify_nkw()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_nkw.html)
- **Use when**: find non-knowledge workers; exclude low collaboration populations; check who should be out of scope
- **Input**: Person-period query
- **Columns**: fixed: `PersonId`; selected: `collab_threshold`
- **Returns**: Summary by group, flagged data, text, or a cleaned dataset
- **Privacy**: Person-level flags are identifying; aggregate before sharing.
- **Related**: `check_query()`, `hrvar_count_all()`
- **R counterpart**: `identify_nkw()` (partial)

```python
import vivainsights as vi

vi.identify_nkw(vi.load_pq_data(), collab_threshold=5, return_type="data_summary")
```

### Find the date range covered by a query

- **Function**: [`extract_date_range()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.extract_date_range.html)
- **Use when**: what period does this data cover; find the first and last week; describe the date range
- **Input**: Person-period query
- **Columns**: fixed: `MetricDate`
- **Returns**: Single-row table or descriptive text
- **Privacy**: Date ranges are not identifying.
- **Related**: `identify_datefreq()`, `check_query()`
- **R counterpart**: `extract_date_range()` (partial)

```python
import vivainsights as vi

vi.extract_date_range(vi.load_pq_data(), return_type="text")
```

### Determine whether data is daily, weekly, or monthly

- **Function**: [`identify_datefreq()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.identify_daterange.html)
- **Use when**: is this data weekly or daily; check the date granularity; identify the query interval
- **Input**: Date column
- **Columns**: fixed: `MetricDate`
- **Returns**: One of daily, weekly, or monthly
- **Privacy**: Date frequency is not identifying.
- **Related**: `extract_date_range()`, `check_query()`
- **R counterpart**: `identify_datefreq()` (partial)

```python
import vivainsights as vi

vi.identify_datefreq(vi.load_pq_data()["MetricDate"])
```

### Find which columns are organizational attributes

- **Function**: [`extract_hr()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.extract_hr.html)
- **Use when**: which columns can I group by; list HR attributes; suggest grouping variables
- **Input**: Person-period query
- **Columns**: none
- **Returns**: Printed names, a filtered DataFrame, or a list of column names
- **Privacy**: Attribute names only; values are not returned with return_type="names".
- **Related**: `hrvar_count_all()`, `check_query()`
- **R counterpart**: `extract_hr()` (partial)

```python
import vivainsights as vi

vi.extract_hr(vi.load_pq_data(), return_type="suggestion")
```

### Check that required columns exist before running an analysis

- **Function**: [`check_inputs()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.check_inputs.html)
- **Use when**: verify required columns are present; fail early if a column is missing; validate inputs before analysis
- **Input**: Any DataFrame
- **Columns**: selected: `requirements`
- **Returns**: Nothing when all required columns are present
- **Privacy**: No data values are returned.
- **Related**: `check_query()`, `extract_hr()`
- **R counterpart**: `check_inputs()` (partial)

```python
import vivainsights as vi

vi.check_inputs(vi.load_pq_data(), ["PersonId", "MetricDate"])
```

### Analyze collaboration between groups

- **Function**: [`network_g2g()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.network_g2g.html)
- **Use when**: show collaboration across organizations; build a group-to-group network; which teams work together
- **Input**: Group-to-group query
- **Columns**: selected: `primary`, `secondary`, `metric`
- **Returns**: Network plot, interaction matrix, long-format data, or an igraph object
- **Privacy**: Group-level flows can be small; apply disclosure policy before sharing.
- **Related**: `network_summary()`, `load_g2g_data()`
- **R counterpart**: `network_g2g()` (partial)

```python
import vivainsights as vi

vi.network_g2g(vi.load_g2g_data(), return_type="table")
```

### Analyze a person-to-person collaboration network

- **Function**: [`network_p2p()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.network_p2p.html)
- **Use when**: build a person network; find network communities; visualize how individuals collaborate
- **Input**: Person-to-person query
- **Columns**: selected: `hrvar`, `community`, `centrality`
- **Returns**: Plot, PDF plot, table, node data, Sankey chart, or an igraph object
- **Privacy**: Network outputs can identify individuals; apply organizational privacy and disclosure policy.
- **Related**: `network_summary()`, `p2p_data_sim()`, `create_sankey()`
- **R counterpart**: `network_p2p()` (partial)

```python
import vivainsights as vi

vi.network_p2p(vi.p2p_data_sim(size=100), return_type="network")
```

### Summarize centrality for a network

- **Function**: [`network_summary()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.network_summary.html)
- **Use when**: calculate network centrality; who is most connected; summarize node statistics
- **Input**: igraph network object
- **Columns**: selected: `hrvar`
- **Returns**: Centrality table, grouped summary, or plot
- **Privacy**: Node-level centrality is identifying; aggregate before sharing.
- **Related**: `network_p2p()`, `network_g2g()`
- **R counterpart**: `network_summary()` (partial)

```python
import vivainsights as vi

vi.network_summary(vi.network_p2p(vi.p2p_data_sim(size=100), return_type="network"), return_type="table")
```

### Simulate a person-to-person network for testing

- **Function**: [`p2p_data_sim()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.p2p_data_sim.html)
- **Use when**: generate sample network data; simulate a collaboration network; create test data for network analysis
- **Input**: Simulation parameters
- **Columns**: none
- **Returns**: Simulated person-to-person DataFrame
- **Privacy**: Simulated data contains no real people.
- **Related**: `network_p2p()`, `load_p2p_data()`
- **R counterpart**: `p2p_data_sim()` (partial)

```python
import vivainsights as vi

vi.p2p_data_sim(size=100)
```

### Load bundled sample datasets

- **Function**: [`load_pq_data()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.pq_data.html)
- **Use when**: get sample Viva Insights data; load demo data to try the package; find example datasets
- **Input**: None
- **Columns**: none
- **Returns**: Sample DataFrame
- **Privacy**: Sample data is de-identified and safe to share.
- **Related**: `load_mt_data()`, `load_g2g_data()`, `load_p2p_data()`, `load_p2g_data()`, `p2p_data_sim()`
- **R counterpart**: `pq_data()` (partial)

```python
import vivainsights as vi

vi.load_pq_data()
```

### Add a constant column to analyse the whole population

- **Function**: [`totals_col()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.totals_col.html)
- **Use when**: analyse everyone without grouping; add a total column; compare the organization against itself
- **Input**: Person-period query
- **Columns**: selected: `total_value`
- **Returns**: DataFrame with an added constant column
- **Privacy**: Adds a constant column only.
- **Related**: `create_bar()`, `hrvar_count()`
- **R counterpart**: `totals_col()` (partial)

```python
import vivainsights as vi

vi.totals_col(vi.load_pq_data())
```

### Convert column names into readable labels

- **Function**: [`us_to_space()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.us_to_space.html)
- **Use when**: make metric names readable; replace underscores in labels; format a column name for a chart title
- **Input**: Column name
- **Columns**: none
- **Returns**: Formatted string
- **Privacy**: Formats text only.
- **Related**: `create_bar()`, `export()`
- **R counterpart**: `us_to_space()` (partial)

```python
import vivainsights as vi

vi.us_to_space("Collaboration_hours")
```

### Save or copy an analysis output

- **Function**: [`export()`](https://microsoft.github.io/vivainsights-py/_api/vivainsights.export.html)
- **Use when**: export a table to CSV; save a plot to file; copy results to the clipboard
- **Input**: DataFrame or figure
- **Columns**: none
- **Returns**: Writes a file or displays the object
- **Privacy**: Exported files inherit the disclosure properties of the analysis output.
- **Related**: `create_bar()`, `create_rank()`
- **R counterpart**: `export()` (partial)

```python
import vivainsights as vi

vi.export(summary_table, file_format="csv", path="summary")
```