% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/identify_retention.R
\name{identify_retention}
\alias{identify_retention}
\title{Identify Retention Rate Between Two Time Periods}
\usage{
identify_retention(
  data,
  start_x,
  end_x,
  start_y,
  end_y = NULL,
  category,
  category_values = TRUE,
  return = "summary"
)
}
\arguments{
\item{data}{A data frame containing person-level time series data with at
minimum \code{PersonId}, \code{MetricDate}, and the column specified in \code{category}.}

\item{start_x}{Start date for the first time period (Date or character in
\code{"YYYY-MM-DD"} format).}

\item{end_x}{End date for the first time period (exclusive).}

\item{start_y}{Start date for the second time period.}

\item{end_y}{End date for the second time period (exclusive). If \code{NULL},
uses all data from \code{start_y} onwards.}

\item{category}{A string specifying the column name containing the
binary/categorical variable to evaluate (e.g. \code{"IsHabitualUser"}).}

\item{category_values}{A character vector of values in \code{category} that
define the "positive" condition (e.g. \code{c("Power User", "Habitual User")}).
Defaults to \code{TRUE} for binary columns.}

\item{return}{A string specifying the return type. Valid options are:
\itemize{
\item \code{"summary"} (default): A tibble with retention statistics.
\item \code{"data"}: A list with person-level retention status and breakdown.
\item \code{"message"}: Prints a formatted message and returns the summary tibble
invisibly.
}}
}
\value{
Depending on \code{return}:
\itemize{
\item \code{"summary"}: A tibble with the following columns:
\itemize{
\item \code{PeriodX_Start}, \code{PeriodX_End}: Start and end dates of period X.
\item \code{PeriodY_Start}, \code{PeriodY_End}: Start and end dates of period Y.
\item \code{Category}: The category column name.
\item \code{CategoryValues}: The category values used.
\item \code{N_Original}: Number of individuals meeting the condition in period X.
\item \code{N_Tracked}: Number of those individuals found in period Y.
\item \code{N_Lost}: Number of individuals not found in period Y.
\item \code{N_Retained}: Number still meeting the condition in period Y.
\item \code{RetentionPct}: Retention percentage.
}
\item \code{"data"}: A list containing \code{summary}, \code{person_status}, and \code{breakdown}.
\item \code{"message"}: Prints a formatted message; returns the summary tibble
invisibly.
}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}

This function calculates the retention rate of individuals who meet a
specific category condition in one time period and checks whether they still
meet that condition in a subsequent time period. This function complements
\code{identify_usage_segments()}.
}
\examples{
\dontrun{
# Retention of Power/Habitual users from Nov 2025 to Jan 2026
identify_retention(
  data = pq_week_df,
  start_x = "2025-11-01",
  end_x = "2025-12-01",
  start_y = "2026-01-01",
  end_y = "2026-02-01",
  category = "UsageSegments_12w",
  category_values = c("Power User", "Habitual User")
)
}

}
\author{
Martin Chan
}
