time-dependent-roc
Use when performing time-dependent ROC curve analysis for survival data with follow-up time, event status, and a numeric marker. Supports CSV/TXT/TSV/Excel input, `risk_score` as the default marker unless `--marker_col` is provided, parameter validation, standardized output directories, AUC table export, ROC point export, and PDF figure generation.
- License 许可
- MIT
- 最近更新
- 2026-10-12
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- time-dependent-roc
- author
- AIPOCH
- license
- MIT
- description
- Use when performing time-dependent ROC curve analysis for survival data with follow-up time, event status, and a numeric marker. Supports CSV/TXT/TSV/Excel input, `risk_score` as the default marker unless `--marker_col` is provided, parameter validation, standardized output directories, AUC table export, ROC point export, and PDF figure generation.
02 资源文件 10
- 参考文档references/algorithm.md2.7 KB
- 参考文档references/cli-guide.md3.4 KB
- 参考文档references/troubleshooting.md4.3 KB
- 脚本scripts/functions.R9.0 KB
- 脚本scripts/main.R6.5 KB
- 脚本scripts/run_analysis.R1.9 KB
- 脚本scripts/utils.R4.9 KB
- 参考文档tests/data/time_roc_sample1.txt15.7 KB
- 参考文档tests/data/time_roc_sample2.txt5.5 KB
- 参考文档tests/data/time_roc_sample3.txt21.1 KB
03 SKILL.md 正文
Time-Dependent ROC Analysis
Use this skill to compute and plot time-dependent ROC curves for survival outcomes.
Use This Skill When
- You have survival data with
futimeandfustatcolumns. - You need time-specific ROC curves and AUC values for a numeric risk marker.
- You want a command-line workflow with parameter validation and standardized outputs.
- Your file contains a numeric marker column named
risk_score, or you will provide another marker explicitly with--marker_col.
Primary Command
Rscript scripts/main.R \
--data_file <input_file> \
--times <comma_separated_times> \
--output_dir <output_dir>
Prerequisites
Rscriptis available in the shell.- Required R packages:
optparse,timeROC,survival,ggplot2. - Optional package for Excel input:
openxlsx. - Install missing packages with
Rscript -e 'install.packages(c("optparse", "timeROC", "survival", "ggplot2", "openxlsx"), repos="https://cloud.r-project.org")'.
Core Arguments
| Argument | Required | Description |
|---|---|---|
--data_file |
Yes | Input data file in CSV, TXT, TSV, TAB, XLS, or XLSX format |
--times |
No | Prediction time points, comma-separated. Default 1,3,5 |
--marker_col |
No | Marker column name. Default risk_score; provide this option when your file uses a different marker |
--output_dir |
No | Output directory, default ./TimeROC_Results |
--time_unit |
No | Time unit label for plot/output: year, month, or day. Default year |
--auto_convert_days |
No | If TRUE, convert large futime values from days to the selected unit when appropriate. Default TRUE |
--weighting |
No | IPCW weighting method: aalen, marginal, or cox. Default aalen |
--cause |
No | Event code treated as the outcome of interest. Default 1 |
Input Requirements
- The input file must contain
futimeandfustatcolumns. - The selected marker column must exist and be numeric or coercible to numeric.
- If
--marker_colis omitted, the input file must containrisk_score. futimemust be numeric or coercible to numeric.fustatmust be numeric or coercible to numeric.- Rows with missing
futime,fustat, or marker values are excluded. - At least 5 complete rows and at least 1 event for the requested
causeare required.
Example input:
id fustat futime risk_score risk_group GPR161 RIBC2
TCGA-C5-A1M5 1 5.6219 -1.1070 low 2.8252 5.3532
TCGA-EA-A5O9 0 2.1589 -0.8964 low 2.6046 4.4293
TCGA-C5-A3HL 0 1.7014 -0.9044 low 4.1248 4.9166
Minimal Workflow
- Confirm the input file exists and includes
futime,fustat, andrisk_score, or plan to pass--marker_col. - Run
scripts/main.Rwith the requested time points. - Check the output directory for the AUC table and PDF figure.
If you omit --data_file, the script exits with SKILL_MISSING_INPUT.
Outputs
Expected output structure:
<output_dir>/
├── data/
│ └── time_roc_points.<csv|txt>
├── session_info.txt
├── figure/
│ └── time_roc.pdf
└── table/
└── time_roc_auc.<csv|txt>
Primary output files:
data/time_roc_points.csvordata/time_roc_points.txttable/time_roc_auc.csvortable/time_roc_auc.txtfigure/time_roc.pdfsession_info.txt
Exported result fields include:
timetime_unitaucmarker_coln_completen_events
Exported ROC point fields include:
false_positive_ratesensitivitytimetime_unitauccurve_label
Read These Files When Needed
| Need | File |
|---|---|
| Statistical details and assumptions | references/algorithm.md |
| More CLI examples | references/cli-guide.md |
| Error diagnosis | references/troubleshooting.md |
| Main execution entry point | scripts/main.R |
| Sample test data | tests/data/ |
Quick Examples
Basic analysis:
Rscript scripts/main.R \
--data_file tests/data/time_roc_sample1.txt \
--times 1,3,5 \
--output_dir tests/output_basic
Specify marker column and plot styling:
Rscript scripts/main.R \
--data_file tests/data/time_roc_sample2.txt \
--marker_col GPR161 \
--times 1,2,4 \
--line_colors "#4DBBD5,#E64B35,#00A087" \
--legend_position bottom \
--output_dir tests/output_gpr161
Validation
Rscript scripts/main.R --help
Rscript scripts/main.R \
--data_file tests/data/time_roc_sample1.txt \
--times 1,3,5 \
--output_dir tests/validation_output
After running analysis, verify that these files exist:
tests/validation_output/data/time_roc_points.csvtests/validation_output/table/time_roc_auc.csvtests/validation_output/figure/time_roc.pdftests/validation_output/session_info.txt
Common Errors
SKILL_FILE_NOT_FOUND: Input file path is wrong or inaccessible.SKILL_MISSING_COLUMNS:futimeorfustatis missing.SKILL_INVALID_DATA: The marker column is non-numeric, no complete rows remain, event coding is unsuitable, or requested time points yield unusable AUC values.SKILL_INVALID_PARAMETER: An argument value is invalid.SKILL_INSUFFICIENT_DATA: Too few complete rows or no target events remain.SKILL_DEPENDENCY_MISSING: A required R package such asoptparse,timeROC,survival,ggplot2, oropenxlsxis unavailable.
If the issue is not obvious, read references/troubleshooting.md.
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.