% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/create_survival_prep.R
\name{create_survival_prep}
\alias{create_survival_prep}
\title{Prepare Survival Data from a Panel Dataset}
\usage{
create_survival_prep(
  data,
  metric,
  event_condition = function(x) x > 0,
  hrvar = "Organization"
)
}
\arguments{
\item{data}{A Standard Person Query dataset in the form of a data frame.}

\item{metric}{Character string containing the name of the metric column to
evaluate the event condition on.}

\item{event_condition}{A function that takes a numeric vector and returns a
logical vector. Applied to \code{metric} to mark whether the event occurred
in a given period. Defaults to \code{function(x) x > 0} (any non-zero
value is treated as the event).}

\item{hrvar}{Character string containing the name of the HR attribute column
to carry through into the output. The most recent (last observed) value per
person is used. Defaults to \code{"Organization"}. Set to \code{NULL} to
omit.}
}
\value{
A data frame with one row per person containing:
\itemize{
\item \code{PersonId}
\item \code{time}: numeric — periods until event, or total observed periods
if censored
\item \code{event}: integer — \code{1} (event) or \code{0} (censored)
\item The \code{hrvar} column, if supplied
}
}
\description{
Converts a Standard Person Query (panel) dataset into a person-level survival
table suitable for direct use with \code{\link{create_survival}}.

Each person's weekly rows are reduced to a single row containing:
\itemize{
\item \code{time}: the number of periods from the first observation until
the event condition is first met. If the condition is never met,
\code{time} equals the total number of observed periods (censored).
\item \code{event}: \code{1} if the condition was met at any point in the
observation window, \code{0} if the person was censored (never met it).
}

Although rooted in survival analysis, the \code{event_condition} is typically
a \strong{positive milestone} in a workforce context — first use of a tool, first
week as a power user, first week crossing a collaboration threshold.
The resulting curve is therefore often better described as a
\strong{time-to-adoption}, \strong{conversion}, or \strong{graduation} curve.
See \code{\link{create_survival}} for further framing guidance.
}
\examples{
# \dontrun{
# library(vivainsights)
# data("pq_data", package = "vivainsights")
#
# # Step 1: derive person-level survival data
# surv_data <- create_survival_prep(
#   data = pq_data,
#   metric = "Copilot_actions_taken_in_Teams",
#   event_condition = function(x) x > 0
# )
#
# # Step 2: visualise
# create_survival(
#   data = surv_data,
#   time_col = "time",
#   event_col = "event",
#   hrvar = "Organization"
# )
# }
}
\seealso{
\code{\link{create_survival}}
}
\concept{Transformation}
