univariate-multivariable-cox-regression
Use when running prognostic survival analysis on a clinical cohort with time-to-event data to estimate univariate and multivariable Cox proportional hazards models, export result tables, and generate forest plots. NOT for: nomogram construction, calibration curves, time-dependent ROC analysis, or model training/feature selection beyond the built-in univariate screening rule.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-12
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- univariate-multivariable-cox-regression
- description
- Use when running prognostic survival analysis on a clinical cohort with time-to-event data to estimate univariate and multivariable Cox proportional hazards models, export result tables, and generate forest plots. NOT for: nomogram construction, calibration curves, time-dependent ROC analysis, or model training/feature selection beyond the built-in univariate screening rule.
02 资源文件 20
- 参考文档references/algorithm.md3.7 KB
- 参考文档references/cli-guide.md3.2 KB
- 参考文档references/troubleshooting.md4.7 KB
- 脚本scripts/cli.R3.6 KB
- 脚本scripts/cox_helpers.R2.3 KB
- 脚本scripts/functions.R4.3 KB
- 脚本scripts/io.R484 B
- 脚本scripts/main.R2.8 KB
- 脚本scripts/plotting.R2.7 KB
- 脚本scripts/run_analysis.R3.1 KB
- 脚本scripts/utils.R2.5 KB
- 脚本scripts/validation.R1.9 KB
- 资产文件tests/data/sample_clinical_survival_data.csv42.1 KB
- 其他tests/expected_output/data/analysis_data.rds4.4 KB
- 参考文档tests/expected_output/plot/session_info.txt1.6 KB
- 参考文档tests/expected_output/session_info.txt1.5 KB
- 资产文件tests/expected_output/table/prognosis_multi_cox_results.xlsx6.5 KB
- 资产文件tests/expected_output/table/prognosis_uni_cox_results.xlsx6.8 KB
- 其他tests/run_smoke_test.R2.4 KB
- 脚本tests/run_smoke_test.sh127 B
03 SKILL.md 正文
Univariate and Multivariable Cox Regression
When to Use
Use this skill when you need to:
- run univariate and multivariable Cox regression on a clinical survival cohort;
- identify prognostic clinical variables associated with time-to-event outcomes;
- export hazard-ratio tables and then render forest plots from those results.
Typical user requests:
- "Run single-factor and multi-factor Cox regression on this survival dataset."
- "Find prognostic variables from my clinical cohort and give me forest plots."
- "Use futime and fustat to do Cox regression for age, stage, and risk."
When Not to Use
Do not use this skill for:
- nomogram construction or calibration analysis;
- time-dependent ROC analysis or external prognostic model validation;
- feature discovery pipelines beyond the built-in univariate screening rule;
- non-survival outcomes such as binary diagnosis or differential expression.
When to Read External Files
| Situation | File to Read | Purpose |
|---|---|---|
| Need algorithm details | references/algorithm.md |
Statistical workflow, assumptions, and feature-selection rule |
| Need to run analysis | scripts/main.R |
Execute Rscript scripts/main.R <command> [options] |
| Encounter errors | references/troubleshooting.md |
Common SKILL_* errors and fixes |
| Need CLI examples | references/cli-guide.md |
Command-specific argument examples |
| Need test data | tests/data/ |
Minimal runnable cohort for smoke testing |
Usage
1. Run Cox Analysis
Rscript scripts/main.R analyze \
--data_file ./clinical_data.csv \
--features age,gender,stage,risk \
--time_col futime \
--event_col fustat \
--output_dir ./output/ \
--seed 42
2. Generate Univariate Forest Plot
Rscript scripts/main.R forest-plot \
--data_file ./output/table/prognosis_uni_cox_results.xlsx \
--plot_save ./output/plot/uni_forest_plot.pdf
3. Generate Multivariable Forest Plot
Rscript scripts/main.R multi-forest-plot \
--data_file ./output/table/prognosis_multi_cox_results.xlsx \
--plot_save ./output/plot/multi_forest_plot.pdf
Arguments
Analyze Command
| Short | Long | Type | Default | Description |
|---|---|---|---|---|
-d |
--data_file |
character | required | Clinical CSV file with sample IDs as row names |
-f |
--features |
character | age,gender,stage,Tstage,Nstage,Mstage,risk |
Comma-separated features for Cox analysis |
-t |
--time_col |
character | futime |
Survival time column |
-e |
--event_col |
character | fustat |
Event column encoded as 1=event, 0=censored |
-u |
--skip_univariate |
character | false |
Skip univariate screening and fit multivariable model on all requested features |
-o |
--output_dir |
character | ./output/ |
Output directory |
--overwrite |
flag | FALSE |
Allow writing into a non-empty output directory | |
-s |
--seed |
integer | 42 |
Random seed for reproducibility |
-T |
--timeout_seconds |
integer | 0 |
Elapsed time limit in seconds; 0 disables timeout |
Forest Plot Commands
These arguments apply to both forest-plot and multi-forest-plot.
| Short | Long | Type | Default | Description |
|---|---|---|---|---|
-d |
--data_file |
character | required | Cox result table in .xlsx, .xls, or .csv format |
-p |
--plot_save |
character | required | Output PDF path |
-w |
--width |
double | 8 |
Plot width in inches |
-H |
--height |
double | 6 |
Plot height in inches |
-F |
--font_size |
double | 11 |
Font size for forest-plot labels |
-s |
--seed |
integer | 42 |
Random seed for reproducibility |
-T |
--timeout_seconds |
integer | 0 |
Elapsed time limit in seconds; 0 disables timeout |
Input Format
Clinical Data (--data_file for analyze)
CSV file with sample IDs as row names and one column per feature/end-point variable.
",age,gender,stage,futime,fustat,risk
SAMPLE_001,65,Male,StageIII,365,1,high
SAMPLE_002,52,Female,StageII,730,0,low
SAMPLE_003,78,Male,StageIV,180,1,high
Requirements
- The file must be CSV.
- Sample IDs must be stored in the first column as row names.
time_colmust contain finite numeric values greater than0.event_colmust contain only0and1.- All requested
features,time_col, andevent_colmust exist. - At least 10 complete samples and at least 2 events are required after filtering incomplete rows.
Cox Result Table (--data_file for plot commands)
The plotting commands read the output table created by analyze.
Required columns:
CharacteristicsTotal(N)HR (95% CI)P value
Output Files
Analyze Command
| File | Description |
|---|---|
table/prognosis_uni_cox_results.xlsx |
Univariate Cox result table. Present unless --skip_univariate true |
table/prognosis_multi_cox_results.xlsx |
Multivariable Cox result table |
data/analysis_data.rds |
Serialized complete-case dataset used for Cox fitting |
session_info.txt |
Session info and recorded run parameters |
Plot Commands
| File | Description |
|---|---|
plot/uni_forest_plot.pdf |
PDF forest plot generated by forest-plot |
plot/multi_forest_plot.pdf |
PDF forest plot generated by multi-forest-plot |
plot/session_info.txt |
Session info and plotting parameters written beside the PDF |
Result Table Columns
| Column | Description |
|---|---|
Characteristics |
Variable name for continuous terms, or level label for categorical terms |
Total(N) |
Number of complete-case samples used for modeling |
HR (95% CI) |
Hazard ratio with 95% confidence interval |
P value |
Wald-test p-value formatted to three decimals or <0.001 |
feature |
Source feature corresponding to each row |
Workflow
Step 1: Validate and Prepare Data
- Read the clinical CSV.
- Check required columns and data types.
- Convert character predictors to factors.
- Remove rows with missing values across requested model variables.
Step 2: Run Univariate Cox Models
- Fit one Cox model per feature when
--skip_univariate false. - Export hazard ratios, confidence intervals, and p-values.
Step 3: Run Multivariable Cox Model
- Use all significant univariate features with
p < 0.05. - If fewer than 3 significant features are found, fall back to all requested features.
- Export adjusted hazard ratios, confidence intervals, and p-values.
Step 4: Generate Forest Plots
- Read the result table.
- Parse
HR (95% CI)values. - Render a one-page PDF forest plot.
Examples
Basic Analysis
Rscript scripts/main.R analyze \
-d tests/data/sample_clinical_survival_data.csv \
-o tests/expected_output/ \
--overwrite
Analysis With Selected Features and Overwrite
Rscript scripts/main.R analyze \
-d clinical_data.csv \
-f age,gender,stage,risk \
-o ./results/ \
--overwrite \
-T 600
Direct Multivariable Fit Without Univariate Screening
Rscript scripts/main.R analyze \
-d clinical_data.csv \
-f age,stage,risk \
-u true \
-o ./results/
Plot Generation
Rscript scripts/main.R forest-plot \
-d ./results/table/prognosis_uni_cox_results.xlsx \
-p ./results/plot/uni_forest_plot.pdf \
-w 10 -H 7 -F 12
Rscript scripts/main.R multi-forest-plot \
-d ./results/table/prognosis_multi_cox_results.xlsx \
-p ./results/plot/multi_forest_plot.pdf \
-w 10 -H 7 -F 12
Error Handling
| Error | Cause | Solution |
|---|---|---|
SKILL_INVALID_PARAMETER |
Missing required CLI value, invalid extension, unknown command, unreadable CSV input, invalid clinical values, too few complete samples/events, or Cox model fitting failure caused by unsupported input data | Check argument names, file types, clinical value constraints, and model input suitability |
SKILL_FILE_NOT_FOUND |
Input file path does not exist | Verify the input path |
SKILL_MISSING_COLUMNS |
Required columns are absent from the clinical file or plot table | Check column names and spelling |
SKILL_EMPTY_DATA |
Input file or plot table contains no usable rows | Verify file content and export process |
SKILL_PACKAGE_NOT_FOUND |
Required R package is missing | Install the listed CRAN package(s) |
IF error persists, READ: references/troubleshooting.md
Testing
Smoke Test With Included Data
Rscript scripts/main.R --help
Rscript scripts/main.R analyze \
-d tests/data/sample_clinical_survival_data.csv \
-o tests/expected_output/ \
--overwrite
Rscript scripts/main.R forest-plot \
-d tests/expected_output/table/prognosis_uni_cox_results.xlsx \
-p tests/expected_output/plot/uni_forest_plot.pdf
Rscript scripts/main.R multi-forest-plot \
-d tests/expected_output/table/prognosis_multi_cox_results.xlsx \
-p tests/expected_output/plot/multi_forest_plot.pdf
Automated Smoke Test Script
Rscript tests/run_smoke_test.R
Optional shell wrapper:
bash tests/run_smoke_test.sh
Expected Outputs
tests/expected_output/
|-- data/analysis_data.rds
|-- plot/multi_forest_plot.pdf
|-- plot/session_info.txt
|-- plot/uni_forest_plot.pdf
|-- session_info.txt
|-- table/prognosis_multi_cox_results.xlsx
`-- table/prognosis_uni_cox_results.xlsx
References
- Cox DR (1972). Regression Models and Life-Tables. Journal of the Royal Statistical Society: Series B.
- Therneau TM, Grambsch PM (2000). Modeling Survival Data: Extending the Cox Model.
- Harrell FE (2015). Regression Modeling Strategies.
For detailed algorithm, READ: references/algorithm.md
Implementation Checklist
- [x] CLI parsing with
optparse - [x]
set.seed()for reproducibility - [x]
requireNamespace()dependency checks - [x] Session info recording
- [x] Timeout parameter exposed as CLI option
- [x] File reading instructions in
SKILL.md - [x] Modular script structure in
scripts/ - [x] Test data provided in
tests/data/ - [x] Error handling with
SKILL_*codes - [x] References documented in
references/
Last updated: 2026-04-16 | Version: 1.1.0
04 同仓库更多 Skills
bio-workflows-metabolomics-pipeline
Orchestrates the untargeted LC-MS metabolomics pipeline end-to-end (xcms 4.x feature extraction, QC/drift/normalization, confidence-stratified annotation, permutation-validated statistics, background-aware pathway mapping), naming what each stage decides and where it silently fails. Use when running a full LC-MS metabolomics study from raw mzML to enriched pathways and needing the honest handoffs between stages. Each stage defers to its component skill for parameters and traps; for stable-isotope flux (a separate branch, not this untargeted flow) see metabolomics/isotope-tracing.
bio-metabolomics-xcms-preprocessing
Programmatic untargeted LC-MS feature extraction in R with the modern xcms 4.x MsExperiment/XcmsExperiment API, taking raw mzML to a feature table via CentWave peak detection, retention-time alignment, peak-density correspondence, gap-filling, CAMERA redundancy collapse, and built-in QC feature filtering. Use when converting centroided LC-MS runs into a features-by-samples matrix and deciding centWave/grouping/alignment parameters. For drift correction and QC/CV filtering execution see metabolomics/normalization-qc; for metabolite identification see metabolomics/metabolite-annotation; for the MS-DIAL GUI alternative with MS2Dec deconvolution see metabolomics/msdial-preprocessing; for downstream statistics see metabolomics/statistical-analysis.
bio-metabolomics-statistical-analysis
Decision-grade statistical analysis for metabolomics intensity tables. Covers transformation and scaling (Pareto vs unit-variance as a hidden hypothesis), unsupervised structure (PCA/HCA for QC), permutation-validated PLS-DA/OPLS-DA (R2 vs Q2, double CV, VIP as heuristic), univariate testing (Welch/Mann-Whitney/ANOVA/LMM with covariate adjustment), and dependence-aware multiple testing. Use when testing which metabolites differ, building or validating a discriminant model, choosing a scaling, or correcting many correlated tests. For sample-wise normalization/drift correction see metabolomics/normalization-qc; for ML classifiers and selection-inside-CV leakage see machine-learning/biomarker-discovery and machine-learning/model-validation; for pathway interpretation see metabolomics/pathway-mapping; for design/power/multiplicity regime see experimental-design/multiple-testing.
bio-metabolomics-pathway-mapping
Maps metabolomics results to biological pathways via over-representation (ORA), metabolite-set enrichment (MSEA/QEA), mummichog/PSEA on raw m/z peaks, and network-diffusion enrichment (FELLA), with correct background-set construction and honest interpretive ceilings. Use when interpreting differential metabolites or an untargeted LC-MS feature table in pathway context, choosing ORA vs MSEA vs mummichog vs topology, or setting the reference/background set. For annotation confidence levels feeding ORA see metabolomics/metabolite-annotation; for gene-set concepts see pathway-analysis/go-enrichment and pathway-analysis/gsea; for joint gene+metabolite pathways see multi-omics-integration/mofa-integration.
bio-metabolomics-normalization-qc
Designs QC, corrects signal drift, removes batch effects, filters features, normalizes samples, and imputes missing values for untargeted LC-MS/GC-MS metabolomics, framing each step as a measurement model that can create or erase biological signal. Use when processing a peak/feature table before statistical analysis, choosing a drift-correction or sample-normalization method, deciding QC RSD vs D-ratio filtering, or handling left-censored missing values. The feature table is produced by metabolomics/xcms-preprocessing or metabolomics/msdial-preprocessing; transformation/scaling for modeling defers to metabolomics/statistical-analysis; cross-study design issues link to experimental-design/batch-design.
bio-metabolomics-msdial-preprocessing
Runs the MS-DIAL preprocessing workflow (peak picking, MS2Dec spectral deconvolution, alignment, gap-filling) and imports the alignment-result table into R or Python with honest filtering. Use when preprocessing LC-MS DDA/DIA (SWATH) or GC-MS raw data with MS-DIAL, deciding MS-DIAL vs XCMS, configuring the MSDIALCUI console run, or parsing an MS-DIAL export into a clean feature matrix. For programmatic R peak detection and the feature-table-as-artifact framing see metabolomics/xcms-preprocessing; for lipid annotation mode see metabolomics/lipidomics; for MSI-level confidence honesty see metabolomics/metabolite-annotation; for drift correction and QC see metabolomics/normalization-qc.