Skip to contents

Kaplan–Meier Survival Curve

Source: R/create_survival.R
create_survival.Rd

Computes Kaplan–Meier survival curves and returns a step-function plot by default, with an option to return the underlying long-format survival table.

Although this function is built on survival analysis, the framing applies equally to positive milestones in a workforce context. In classical survival analysis the "event" is typically something negative (death, failure); here it is often a positive outcome — first use of a tool, first week as a power user, first week crossing a collaboration threshold. The curve is therefore better read as a time-to-adoption, conversion, or graduation curve:

  • The y-axis ("survival probability") represents the share of people who have not yet reached the milestone.

  • A curve that drops steeply early means most people converted quickly.

  • A curve that stays high means many people had not yet converted by the end of the observation window.

Supports:

  • Flexible grouping via hrvar

  • Privacy filtering via mingroup

This function expects one row per person with a pre-computed time-to-event column and an event indicator. Use create_survival_prep to derive these from a Standard Person Query panel dataset.

Usage

create_survival(
  data,
  time_col,
  event_col,
  hrvar = NULL,
  mingroup = 5,
  na.rm = TRUE,
  return = "plot"
)

Arguments

data

A person-level data frame with one row per person, as produced by create_survival_prep. Must contain time_col, event_col, and (when hrvar is not NULL) the grouping column.

time_col

Character string containing the name of the time-to-event column.

event_col

Character string containing the name of the event indicator column. Accepted forms:

  • Logical (TRUE/FALSE)

  • Numeric 0/1

  • Numeric event-like (>=0): values >0 treated as event, 0 as censored

  • Character tokens ("true"/"false", "yes"/"no", "1"/"0")

hrvar

Character string containing the name of the grouping column. Supply NULL (without quotes) to compute a single overall curve.

mingroup

Numeric value setting the privacy threshold / minimum group size. Defaults to 5.

na.rm

A logical value indicating whether NA should be stripped before computation proceeds. Defaults to TRUE.

return

String specifying what to return. This must be one of:

  • "plot" (default)

  • "table"

Value

A different output is returned depending on the value passed to the return argument:

  • "plot": 'ggplot' object. A Kaplan–Meier survival curve by group.

  • "table": data frame. A long-format survival table by group.

See also

Other Visualization: afterhours_dist(), afterhours_fizz(), afterhours_line(), afterhours_rank(), afterhours_summary(), afterhours_trend(), collaboration_area(), collaboration_dist(), collaboration_fizz(), collaboration_line(), collaboration_rank(), collaboration_sum(), collaboration_trend(), create_bar(), create_bar_asis(), create_boxplot(), create_bubble(), create_dist(), create_fizz(), create_inc(), create_line(), create_line_asis(), create_period_scatter(), create_radar(), create_rank(), create_rogers(), create_sankey(), create_scatter(), create_stacked(), create_tracking(), create_trend(), email_dist(), email_fizz(), email_line(), email_rank(), email_summary(), email_trend(), external_dist(), external_fizz(), external_line(), external_rank(), external_sum(), hr_trend(), hrvar_count(), hrvar_trend(), keymetrics_scan(), meeting_dist(), meeting_fizz(), meeting_line(), meeting_rank(), meeting_summary(), meeting_trend(), one2one_dist(), one2one_fizz(), one2one_freq(), one2one_line(), one2one_rank(), one2one_sum(), one2one_trend()

Other Flexible: create_bar(), create_bar_asis(), create_boxplot(), create_bubble(), create_density(), create_dist(), create_fizz(), create_hist(), create_inc(), create_line(), create_line_asis(), create_period_scatter(), create_radar(), create_rank(), create_sankey(), create_scatter(), create_stacked(), create_tracking(), create_trend()

Examples

if (FALSE) { # \dontrun{
library(vivainsights)
data("pq_data", package = "vivainsights")

# Step 1: convert panel data to person-level survival format
surv_data <- create_survival_prep(
  data = pq_data,
  metric = "Copilot_actions_taken_in_Teams"
)

# Step 2: plot Kaplan-Meier curves by organisation
create_survival(
  data = surv_data,
  time_col = "time",
  event_col = "event",
  hrvar = "Organization"
)

# Return the survival table instead
create_survival(
  data = surv_data,
  time_col = "time",
  event_col = "event",
  hrvar = "Organization",
  return = "table"
)
} # }