Introduction
When the question isn't just "does this event happen" but "how do different factors change the risk of it happening at any given moment" — customer churn, equipment failure, loan default — a plain regression on time-to-event isn't the right tool, especially with censored records where the event hasn't happened yet. ConductCoxProportionalHazardRegression fits a Cox Proportional Hazard model, estimating how each predictor scales the hazard rate over time without requiring you to assume a specific survival distribution, and returns hazard ratios that translate directly into "this factor makes the event X times more/less likely at any moment."
Teaching Note
Cox Proportional Hazard Regression is essential for:
- Predicting customer churn and identifying high-risk segments
- Analyzing patient survival rates in clinical and medical research
- Modeling time-to-failure in industrial reliability engineering
- Understanding factors influencing employee tenure and retention
- Assessing credit risk and time until loan default or delinquency
- Evaluating time on market for real estate or e-commerce listings
- Optimizing marketing interventions based on expected duration till next action
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dataframerequired | | — | The pandas DataFrame containing the survival data, including outcome, duration, and predictor status. |
outcome_columnrequired | | — | Name of the column containing the binary event status (e.g., 1 for event, 0 for censored) or categorical outcome. |
duration_columnrequired | | — | Name of the column containing the time-to-event or duration until the observation ended. |
list_of_predictor_columnsrequired | | — | A list of column names for the independent variables (covariates) to include in the regression model. |
plot_survival_curve | | True | If True, displays a visualization showing the count of surviving records over time for each group. Defaults to True. |
line_color | | '#3269a8' | The primary color for lines in the survival plot when hue is not applied. Defaults to '#3269a8'. |
line_alpha | | 0.8 | The transparency level for the lines in the plot, ranging from 0 to 1. Defaults to 0.8. |
color_palette | | 'Set2' | The seaborn color palette to use for distinguishing survival groups in the plot. Defaults to 'Set2'. |
markers | | 'o' | The marker style to use for data points on the survival lines (e.g., 'o', 's', 'x'). Defaults to 'o'. |
number_of_x_axis_ticks | | 20 | The number of major ticks to display on the x-axis (duration). Defaults to 20. |
x_axis_tick_rotation | | None | The rotation angle (in degrees) for the x-axis tick labels. Defaults to None. |
title_for_plot | | 'Survival Counts by Group' | The main title text to display at the top of the plot. Defaults to 'Survival Counts by Group'. |
subtitle_for_plot | | 'Shows the counts of "surviving" records by group over time' | The 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. |
figure_size | | (8, 5) | Tuple specifying the (width, height) of the figure in inches. Defaults to (8, 5). |
Returns
A fitted lifelines.CoxPHFitter model object, providing access to summary statistics, hazard ratios, and prediction methods.
Example
python
from analysistoolbox.hypothesis_testing import ConductCoxProportionalHazardRegression
import pandas as pd
# Analyze customer churn based on age and subscription type
df = pd.DataFrame({
'churn': [1, 0, 1, 1, 0, 1] * 10,
'tenure': [5, 12, 3, 8, 20, 2] * 10,
'age': [25, 45, 32, 54, 21, 38] * 10,
'is_premium': [1, 1, 0, 0, 1, 0] * 10
})
model = ConductCoxProportionalHazardRegression(
dataframe=df,
outcome_column='churn',
duration_column='tenure',
list_of_predictor_columns=['age', 'is_premium']
)