% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/create_survival.R
\name{create_survival}
\alias{create_survival}
\title{Kaplan–Meier Survival Curve}
\usage{
create_survival(
  data,
  time_col,
  event_col,
  hrvar = NULL,
  mingroup = 5,
  na.rm = TRUE,
  return = "plot"
)
}
\arguments{
\item{data}{A person-level data frame with one row per person, as produced by
\code{\link{create_survival_prep}}. Must contain \code{time_col}, \code{event_col}, and
(when \code{hrvar} is not \code{NULL}) the grouping column.}

\item{time_col}{Character string containing the name of the time-to-event column.}

\item{event_col}{Character string containing the name of the event indicator column.
Accepted forms:
\itemize{
\item Logical (TRUE/FALSE)
\item Numeric 0/1
\item Numeric event-like (>=0): values >0 treated as event, 0 as censored
\item Character tokens ("true"/"false", "yes"/"no", "1"/"0")
}}

\item{hrvar}{Character string containing the name of the grouping column.
Supply \code{NULL} (without quotes) to compute a single overall curve.}

\item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.}

\item{na.rm}{A logical value indicating whether \code{NA} should be stripped before computation proceeds.
Defaults to \code{TRUE}.}

\item{return}{String specifying what to return. This must be one of:
\itemize{
\item \code{"plot"} (default)
\item \code{"table"}
}}
}
\value{
A different output is returned depending on the value passed to the \code{return} argument:
\itemize{
\item \code{"plot"}: 'ggplot' object. A Kaplan–Meier survival curve by group.
\item \code{"table"}: data frame. A long-format survival table by group.
}
}
\description{
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 \strong{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 \strong{time-to-adoption}, \strong{conversion}, or \strong{graduation} curve:
\itemize{
\item The y-axis ("survival probability") represents the share of people who have
\emph{not yet} reached the milestone.
\item A curve that drops steeply early means most people converted quickly.
\item A curve that stays high means many people had not yet converted by the end
of the observation window.
}

Supports:
\itemize{
\item Flexible grouping via \code{hrvar}
\item Privacy filtering via \code{mingroup}
}

This function expects \strong{one row per person} with a pre-computed time-to-event
column and an event indicator. Use \code{\link{create_survival_prep}} to derive
these from a Standard Person Query panel dataset.
}
\examples{
\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"
)
}
}
\seealso{
Other Visualization: 
\code{\link{afterhours_dist}()},
\code{\link{afterhours_fizz}()},
\code{\link{afterhours_line}()},
\code{\link{afterhours_rank}()},
\code{\link{afterhours_summary}()},
\code{\link{afterhours_trend}()},
\code{\link{collaboration_area}()},
\code{\link{collaboration_dist}()},
\code{\link{collaboration_fizz}()},
\code{\link{collaboration_line}()},
\code{\link{collaboration_rank}()},
\code{\link{collaboration_sum}()},
\code{\link{collaboration_trend}()},
\code{\link{create_bar}()},
\code{\link{create_bar_asis}()},
\code{\link{create_boxplot}()},
\code{\link{create_bubble}()},
\code{\link{create_dist}()},
\code{\link{create_fizz}()},
\code{\link{create_inc}()},
\code{\link{create_line}()},
\code{\link{create_line_asis}()},
\code{\link{create_period_scatter}()},
\code{\link{create_radar}()},
\code{\link{create_rank}()},
\code{\link{create_rogers}()},
\code{\link{create_sankey}()},
\code{\link{create_scatter}()},
\code{\link{create_stacked}()},
\code{\link{create_tracking}()},
\code{\link{create_trend}()},
\code{\link{email_dist}()},
\code{\link{email_fizz}()},
\code{\link{email_line}()},
\code{\link{email_rank}()},
\code{\link{email_summary}()},
\code{\link{email_trend}()},
\code{\link{external_dist}()},
\code{\link{external_fizz}()},
\code{\link{external_line}()},
\code{\link{external_rank}()},
\code{\link{external_sum}()},
\code{\link{hr_trend}()},
\code{\link{hrvar_count}()},
\code{\link{hrvar_trend}()},
\code{\link{keymetrics_scan}()},
\code{\link{meeting_dist}()},
\code{\link{meeting_fizz}()},
\code{\link{meeting_line}()},
\code{\link{meeting_rank}()},
\code{\link{meeting_summary}()},
\code{\link{meeting_trend}()},
\code{\link{one2one_dist}()},
\code{\link{one2one_fizz}()},
\code{\link{one2one_freq}()},
\code{\link{one2one_line}()},
\code{\link{one2one_rank}()},
\code{\link{one2one_sum}()},
\code{\link{one2one_trend}()}

Other Flexible: 
\code{\link{create_bar}()},
\code{\link{create_bar_asis}()},
\code{\link{create_boxplot}()},
\code{\link{create_bubble}()},
\code{\link{create_density}()},
\code{\link{create_dist}()},
\code{\link{create_fizz}()},
\code{\link{create_hist}()},
\code{\link{create_inc}()},
\code{\link{create_line}()},
\code{\link{create_line_asis}()},
\code{\link{create_period_scatter}()},
\code{\link{create_radar}()},
\code{\link{create_rank}()},
\code{\link{create_sankey}()},
\code{\link{create_scatter}()},
\code{\link{create_stacked}()},
\code{\link{create_tracking}()},
\code{\link{create_trend}()}
}
\concept{Flexible}
\concept{Visualization}
