{"skill":{"slug":"survival-analysis-km","displayName":"Survival Analysis (KM)","summary":"Generates Kaplan-Meier survival curves, calculates survival statistics (log-rank test, median survival time), and estimates hazard ratios for clinical and bi...","description":"---\nname: survival-analysis-km\ndescription: Generates Kaplan-Meier survival curves, calculates survival statistics\n  (log-rank test, median survival time), and estimates hazard ratios for clinical\n  and biological survival data analysis. Triggered when user requests survival analysis,\n  Kaplan-Meier plots, time-to-event analysis, or asks about survival statistics in\n  biomedical contexts.\nversion: 1.0.0\ncategory: Bioinfo\ntags: []\nauthor: AIPOCH\nlicense: MIT\nstatus: Draft\nrisk_level: Medium\nskill_type: Tool/Script\nowner: AIPOCH\nreviewer: ''\nlast_updated: '2026-02-06'\n---\n\n# Survival Analysis (Kaplan-Meier)\n\nKaplan-Meier survival analysis tool for clinical and biological research. Generates publication-ready survival curves with statistical tests.\n\n## Features\n\n- **Kaplan-Meier Curve Generation**: Publication-quality survival plots with confidence intervals\n- **Statistical Tests**: Log-rank test, Wilcoxon test, Peto-Peto test\n- **Hazard Ratios**: Cox proportional hazards regression with 95% CI\n- **Summary Statistics**: Median survival time, restricted mean survival time (RMST)\n- **Multi-group Analysis**: Supports 2+ comparison groups\n- **Risk Tables**: Optional at-risk table below curves\n\n## Usage\n\n### Python Script\n\n```bash\npython scripts/main.py --input data.csv --time time_col --event event_col --group group_col --output results/\n```\n\n### Arguments\n\n| Argument | Description | Required |\n|----------|-------------|----------|\n| `--input` | Input CSV file path | Yes |\n| `--time` | Column name for survival time | Yes |\n| `--event` | Column name for event indicator (1=event, 0=censored) | Yes |\n| `--group` | Column name for grouping variable | Optional |\n| `--output` | Output directory for results | Yes |\n| `--conf-level` | Confidence level (default: 0.95) | Optional |\n| `--risk-table` | Include risk table in plot | Optional |\n\n### Input Format\n\nCSV with columns:\n- **Time column**: Numeric, time to event or censoring\n- **Event column**: Binary (1 = event occurred, 0 = censored/right-censored)\n- **Group column**: Categorical variable for stratification\n\nExample:\n```csv\npatient_id,time_months,death,treatment_group\nP001,24.5,1,Drug_A\nP002,36.2,0,Drug_A\nP003,18.7,1,Placebo\n```\n\n### Output Files\n\n- `km_curve.png`: Kaplan-Meier survival curve\n- `km_curve.pdf`: Vector version for publications\n- `survival_stats.csv`: Statistical summary (median survival, confidence intervals)\n- `hazard_ratios.csv`: Cox regression results with HR and 95% CI\n- `logrank_test.csv**: Pairwise comparison p-values\n- `report.txt**: Human-readable summary report\n\n## Technical Details\n\n### Statistical Methods\n\n1. **Kaplan-Meier Estimator**: Non-parametric maximum likelihood estimate of survival function\n   - Product-limit estimator: Ŝ(t) = Π(tᵢ≤t) (1 - dᵢ/nᵢ)\n   - Greenwood's formula for variance estimation\n\n2. **Log-Rank Test**: Most widely used test for comparing survival curves\n   - Null hypothesis: No difference between groups\n   - Weighted by number at risk at each event time\n\n3. **Cox Proportional Hazards**: Semi-parametric regression model\n   - h(t|X) = h₀(t) × exp(β₁X₁ + β₂X₂ + ...)\n   - Proportional hazards assumption checked via Schoenfeld residuals\n\n### Dependencies\n\n- `lifelines`: Core survival analysis library\n- `matplotlib`, `seaborn`: Visualization\n- `pandas`, `numpy`: Data handling\n- `scipy`: Statistical tests\n\n### Technical Difficulty: High ⚠️\n\nThis skill involves advanced statistical modeling. Results should be reviewed by a biostatistician, especially for:\n- Proportional hazards assumption violations\n- Small sample sizes (< 30 per group)\n- Heavy censoring (> 50%)\n- Time-varying covariates\n\n## References\n\nSee `references/` folder for:\n- Kaplan EL, Meier P (1958) original paper\n- Cox DR (1972) regression models paper\n- Sample datasets for testing\n- Clinical reporting guidelines (ATN, CONSORT)\n\n\n## Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `--input` | str | Required | Input CSV file path |\n| `--time` | str | Required | Column name for survival time |\n| `--event` | str | Required |  |\n| `--group` | str | Required |  |\n| `--output` | str | Required | Output directory for results |\n| `--conf-level` | float | 0.95 |  |\n| `--risk-table` | str | Required | Include risk table in plot |\n| `--figsize` | str | '10 |  |\n| `--dpi` | int | 300 |  |\n\n## Example\n\n```bash\n# Basic survival curve\npython scripts/main.py \\\n  --input clinical_data.csv \\\n  --time overall_survival_months \\\n  --event death \\\n  --group treatment_arm \\\n  --output ./results/ \\\n  --risk-table\n```\n\nOutput includes:\n- Survival curves with 95% confidence bands\n- Median survival: Drug A = 28.4 months (95% CI: 24.1-32.7), Placebo = 18.2 months (95% CI: 15.3-21.1)\n- Log-rank test p-value: 0.0023\n- Hazard ratio: 0.62 (95% CI: 0.45-0.85), p = 0.003\n\n## Risk Assessment\n\n| Risk Indicator | Assessment | Level |\n|----------------|------------|-------|\n| Code Execution | Python/R scripts executed locally | Medium |\n| Network Access | No external API calls | Low |\n| File System Access | Read input files, write output files | Medium |\n| Instruction Tampering | Standard prompt guidelines | Low |\n| Data Exposure | Output files saved to workspace | Low |\n\n## Security Checklist\n\n- [ ] No hardcoded credentials or API keys\n- [ ] No unauthorized file system access (../)\n- [ ] Output does not expose sensitive information\n- [ ] Prompt injection protections in place\n- [ ] Input file paths validated (no ../ traversal)\n- [ ] Output directory restricted to workspace\n- [ ] Script execution in sandboxed environment\n- [ ] Error messages sanitized (no stack traces exposed)\n- [ ] Dependencies audited\n## Prerequisites\n\n```bash\n# Python dependencies\npip install -r requirements.txt\n```\n\n## Evaluation Criteria\n\n### Success Metrics\n- [ ] Successfully executes main functionality\n- [ ] Output meets quality standards\n- [ ] Handles edge cases gracefully\n- [ ] Performance is acceptable\n\n### Test Cases\n1. **Basic Functionality**: Standard input → Expected output\n2. **Edge Case**: Invalid input → Graceful error handling\n3. **Performance**: Large dataset → Acceptable processing time\n\n## Lifecycle Status\n\n- **Current Stage**: Draft\n- **Next Review Date**: 2026-03-06\n- **Known Issues**: None\n- **Planned Improvements**: \n  - Performance optimization\n  - Additional feature support\n","topics":["Data Analysis"],"tags":{"Data-analysis":"1.0.0","Survival analysis":"1.0.0","latest":"1.0.0"},"stats":{"comments":0,"downloads":976,"installsAllTime":37,"installsCurrent":0,"stars":1,"versions":1},"createdAt":1772261117614,"updatedAt":1778993858160},"latestVersion":{"version":"1.0.0","createdAt":1772261117614,"changelog":"Initial release of the survival-analysis-km skill for biomedical survival data analysis.\n\n- Generates Kaplan-Meier survival curves and publication-ready plots\n- Performs log-rank, Wilcoxon, and Peto-Peto statistical tests\n- Calculates hazard ratios and median survival times\n- Supports multi-group analysis and optional at-risk tables\n- Outputs include plots, statistical summaries, hazard ratios, and human-readable reports\n- Designed for clinical and biological time-to-event data analysis in Python","license":null},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"aipoch-ai","userId":"s17fjw78yq6wtd4ep6zsaxwrn983hznr","displayName":"AIpoch","image":"https://avatars.githubusercontent.com/u/258999481?v=4"},"moderation":null}