ConductSurvivalAnalysis — Analysis Tool Box

Introduction

What fraction of customers, patients, or machines are still "surviving" — hasn't churned, hasn't relapsed, hasn't failed — at each point in time, and does that survival pattern differ meaningfully between groups? ConductSurvivalAnalysis fits Kaplan-Meier estimators to answer both questions: it produces a survival table and cumulative survival curve with confidence intervals, and when you provide a grouping column, it runs a log-rank test to tell you whether the survival curves for different cohorts are statistically distinguishable rather than just visually different.

Teaching Note

Survival analysis is essential for:

Analyzing customer churn and estimating subscription lifecycle
Evaluating patient outcomes and survival rates in clinical trials
Modeling time-to-failure in mechanical and engineering systems
Understanding employee retention patterns and attrition timing
Assessing credit risk and time-to-default for financial products
Tracking conversion cycles and time-to-purchase in sales funnels
Predicting project completion times and delivery durations

Parameters

Parameter	Default	Description
`dataframe`required	—	The pandas DataFrame containing the survival data to be analyzed.
`outcome_column`required	—	Name of the column containing the binary event status (e.g., 1 for event occurred, 0 for censored).
`time_duration_column`required	—	Name of the column containing the time-to-event or duration until the end of the observation period.
`group_column`	`None`	Optional name of the column used to segment the data into groups for comparative analysis. Defaults to None.
`return_time_table`	`True`	If True, includes the detailed event and survival probability table in the returned dictionary. Defaults to True.
`plot_survival_curve`	`True`	If True, generates and displays a Kaplan-Meier survival curve plot. Defaults to True.
`conduct_log_rank_test`	`True`	If True, performs a log-rank test to compare survival curves across groups when a group_column is provided. Defaults to True.
`significance_level`	`0.05`	The alpha level for statistical significance in the log-rank test. Defaults to 0.05.
`print_log_rank_test_results`	`True`	If True, prints a summary of the log-rank test results to the console. Defaults to True.
`line_color`	`'#3269a8'`	Color of the survival line for non-grouped analysis. Defaults to '#3269a8'.
`line_alpha`	`0.8`	Transparency level for the survival lines and shaded confidence intervals, ranging from 0 to 1. Defaults to 0.8.
`sns_color_palette`	`'Set2'`	Seaborn color palette used for the lines and intervals when comparing groups. Defaults to 'Set2'.
`add_point_in_time_survival_curve`	`False`	If True, adds a secondary line to the plot showing point-in-time survival probabilities (non-grouped analysis only). Defaults to False.
`point_in_time_survival_color`	`'#3269a8'`	Color used for the point-in-time survival line. Defaults to '#3269a8'.
`title_for_plot`	`'Cumulative Survival Curve'`	Main title text to display at the top of the plot. Defaults to 'Cumulative Survival Curve'.
`subtitle_for_plot`	`'Shows the cumulative survival probability over time'`	Subtitle text to display below the main title.
`caption_for_plot`	`None`	Caption text displayed at the bottom of the plot. Defaults to None.
`data_source_for_plot`	`None`	Optional text identifying the data source, displayed in the caption area. Defaults to None.
`x_indent`	`-0.127`	Horizontal position for left-aligning the title, subtitle, and caption. Defaults to -0.127.
`title_y_indent`	`1.125`	Vertical position for the main title relative to the axes. Defaults to 1.125.
`subtitle_y_indent`	`1.05`	Vertical position for the subtitle relative to the axes. Defaults to 1.05.
`caption_y_indent`	`-0.3`	Vertical position for the caption relative to the axes. Defaults to -0.3.
`y_axis_label_indent`	`0.78`	Vertical position for the y-axis label. Defaults to 0.78.
`x_axis_label_indent`	`0.925`	Horizontal position for the x-axis label. Defaults to 0.925.
`figure_size`	`(8, 6)`	Tuple specifying the (width, height) of the figure in inches. Defaults to (8, 6).

Returns

A dictionary with 'survival_table' (a DataFrame of event counts and survival probabilities over time) and, if group_column is provided, one entry per group name holding that group's fitted KaplanMeierFitter object.

Example

python

from analysistoolbox.hypothesis_testing import ConductSurvivalAnalysis
import pandas as pd

# Compare customer churn between subscription tiers
subscription_df = pd.DataFrame({
    'churned': [1, 1, 0, 1, 0, 0] * 30,
    'months': [3, 6, 24, 1, 12, 18] * 30,
    'tier': ['Basic', 'Premium', 'Basic', 'Standard', 'Premium', 'Standard'] * 30
})
results = ConductSurvivalAnalysis(
    dataframe=subscription_df,
    outcome_column='churned',
    time_duration_column='months',
    group_column='tier',
    title_for_plot='Customer Retention by Subscription Tier',
    sns_color_palette='viridis'
)