PySurv

PySurv is a Python package for generating and plotting Kaplan-Meier survival curves. It is designed to be simple and intuitive and is inspired from MatSurv.

Features

• Generate Kaplan-Meier (KM) survival curves
• Calculate hazard ratios (HR) with 95% confidence intervals using Cox PH method
• Option to show or hide confidence intervals (CI) for KM curves
• Flexible plotting with customizable styles, colors, and labels
• Generate synthetic time-to-event data by specifying hazard ratio and censoring rate.

Installation

You can install PySurv via PyPI:

pip install pysurv

Usage

Here’s a detailed example of how to use PySurv for generating data, plotting KM curves, and customizing the output:

import pysurv

# Generate synthetic data
data = pysurv.generate_time_to_event_data(n_samples=2000, hazard_ratio=0.5, censoring_rate=0.3)

# Plot Kaplan-Meier curve with custom labels and colors
pysurv.plot_km_curve(
    data, 
    time_col='time', 
    event_col='event', 
    group_col='group', 
    group_labels=('Control Group', 'Treatment Group'),
    title="Kaplan-Meier Survival Curve",
    y_label="Survival Probability",
    x_label="Time (months)",
    colors=['orange', 'blue'], 
    show_ci=True,
    survival_time_points=[12, 24],  # Show % survival at 12 and 24 months
    return_summary=False,
    savepath='./KMCurve.svg'
)

Output:

• A Kaplan-Meier curve
• Summary statistics, including median survival time and percentage survival at given time point(s)
• Hazard ratio and p-value displayed on the plot

Function Reference

plot_km_curve

Plots Kaplan-Meier survival curves and calculates hazard ratios, p-values, and confidence intervals.

Parameters:

• data: A Pandas DataFrame containing time-to-event data.
• time_col: Column name for the time data.
• event_col: Column name for the event data (1 for event, 0 for censored).
• group_col: Column name for the binary group data.
• group_labels: Labels for the groups (default: None).
• title: Title for the plot (default: None).
• y_label: Label for the y-axis (default: 'Survival Probability').
• x_label: Label for the x-axis (default: 'Time (months)').
• colors: List of colors for the groups (default: ['r', 'b']). If more than two groups, please manually provide a list of colors.
• line_styles: Line styles for the groups (default: ’-‘).
• fontsize: Font size for text on KM curve including title, axis labels, and risk tables (default: 18).
• linewidth: Line width of KM curves (default: 2.5).
• show_ci: Whether to show confidence intervals on the KM curves (default: False).
• show_inverted_hr: Whether to show inverted hazard ratio (default: False).
• survival_time_points: One or more time point(s) at which to estimate percentage survival (default: None).
• return_summary: Whether to return a summary of survival and hazard ratio statistics (default: False).
• savepath: Complete path (including filename and extension) to save the KM curve plot (default: None).
• **kwargs: Additional matplotlib arguments to pass for plotting KM curves.

*Note:

• PySurv uses a univariable Cox regression model on the 'group_col' variable to compute hazard ratios and p-values.
• MatSurv deafaults to the 'Mantel-Haenszel' (MH) and 'log rank' method.
• Under the proportional hazards assumption, Cox regression is equivalent, if not better, to the MH/log-rank method.
• For more information, see this and this.

Maintained by

• Pushkar Mutha
• Email: pmutha@emory.edu
• LinkedIn: https://www.linkedin.com/in/pushkar-mutha/

If you would like to request a new feature, please feel free to raise an issue on GitHub or reach out via email. If you found this code useful, you can support by leaving a star.