survival-analysis-km

name	survival-analysis-km
description	Generates Kaplan-Meier survival curves, calculates survival statistics

Survival Analysis (Kaplan-Meier)

Kaplan-Meier survival analysis tool for clinical and biological research. Generates publication-ready survival curves with statistical tests.

Features

• Kaplan-Meier Curve Generation: Publication-quality survival plots with confidence intervals
• Statistical Tests: Log-rank test, Wilcoxon test, Peto-Peto test
• Hazard Ratios: Cox proportional hazards regression with 95% CI
• Summary Statistics: Median survival time, restricted mean survival time (RMST)
• Multi-group Analysis: Supports 2+ comparison groups
• Risk Tables: Optional at-risk table below curves

Usage

Python Script

python scripts/main.py --input data.csv --time time_col --event event_col --group group_col --output results/

Arguments

Argument	Description	Required
--input	Input CSV file path	Yes
--time	Column name for survival time	Yes
--event	Column name for event indicator (1=event, 0=censored)	Yes
--group	Column name for grouping variable	Optional
--output	Output directory for results	Yes
--conf-level	Confidence level (default: 0.95)	Optional
--risk-table	Include risk table in plot	Optional

Input Format

CSV with columns:

• Time column: Numeric, time to event or censoring
• Event column: Binary (1 = event occurred, 0 = censored/right-censored)
• Group column: Categorical variable for stratification

Example:

patient_id,time_months,death,treatment_group
P001,24.5,1,Drug_A
P002,36.2,0,Drug_A
P003,18.7,1,Placebo

Output Files

• km_curve.png: Kaplan-Meier survival curve
• km_curve.pdf: Vector version for publications
• survival_stats.csv: Statistical summary (median survival, confidence intervals)
• hazard_ratios.csv: Cox regression results with HR and 95% CI
• `logrank_test.csv**: Pairwise comparison p-values
• `report.txt**: Human-readable summary report

Technical Details

Statistical Methods

1. Kaplan-Meier Estimator: Non-parametric maximum likelihood estimate of survival function

   • Product-limit estimator: Ŝ(t) = Π(tᵢ≤t) (1 - dᵢ/nᵢ)
   • Greenwood's formula for variance estimation

2. Log-Rank Test: Most widely used test for comparing survival curves

   • Null hypothesis: No difference between groups
   • Weighted by number at risk at each event time

3. Cox Proportional Hazards: Semi-parametric regression model

   • h(t|X) = h₀(t) × exp(β₁X₁ + β₂X₂ + ...)
   • Proportional hazards assumption checked via Schoenfeld residuals

Dependencies

• lifelines: Core survival analysis library
• matplotlib, seaborn: Visualization
• pandas, numpy: Data handling
• scipy: Statistical tests

Technical Difficulty: High ⚠️

This skill involves advanced statistical modeling. Results should be reviewed by a biostatistician, especially for:

• Proportional hazards assumption violations
• Small sample sizes (< 30 per group)
• Heavy censoring (> 50%)
• Time-varying covariates

References

See references/ folder for:

• Kaplan EL, Meier P (1958) original paper
• Cox DR (1972) regression models paper
• Sample datasets for testing
• Clinical reporting guidelines (ATN, CONSORT)

Parameters

Parameter	Type	Default	Description
--input	str	Required	Input CSV file path
--time	str	Required	Column name for survival time
--event	str	Required
--group	str	Required
--output	str	Required	Output directory for results
--conf-level	float	0.95
--risk-table	str	Required	Include risk table in plot
--figsize	str	'10
--dpi	int	300

Example

# Basic survival curve
python scripts/main.py \
  --input clinical_data.csv \
  --time overall_survival_months \
  --event death \
  --group treatment_arm \
  --output ./results/ \
  --risk-table

Output includes:

• Survival curves with 95% confidence bands
• Median survival: Drug A = 28.4 months (95% CI: 24.1-32.7), Placebo = 18.2 months (95% CI: 15.3-21.1)
• Log-rank test p-value: 0.0023
• Hazard ratio: 0.62 (95% CI: 0.45-0.85), p = 0.003

Risk Assessment

Risk Indicator	Assessment	Level
Code Execution	Python/R scripts executed locally	Medium
Network Access	No external API calls	Low
File System Access	Read input files, write output files	Medium
Instruction Tampering	Standard prompt guidelines	Low
Data Exposure	Output files saved to workspace	Low

Security Checklist

• No hardcoded credentials or API keys
• No unauthorized file system access (../)
• Output does not expose sensitive information
• Prompt injection protections in place
• Input file paths validated (no ../ traversal)
• Output directory restricted to workspace
• Script execution in sandboxed environment
• Error messages sanitized (no stack traces exposed)
• Dependencies audited

Prerequisites

# Python dependencies
pip install -r requirements.txt

Evaluation Criteria

Success Metrics

• Successfully executes main functionality
• Output meets quality standards
• Handles edge cases gracefully
• Performance is acceptable

Test Cases

1. Basic Functionality: Standard input → Expected output
2. Edge Case: Invalid input → Graceful error handling
3. Performance: Large dataset → Acceptable processing time

Lifecycle Status

• Current Stage: Draft
• Next Review Date: 2026-03-06
• Known Issues: None
• Planned Improvements:
  • Performance optimization
  • Additional feature support