Command Line Interface (CLI)
kreview exposes all primary pipeline orchestrations explicitly through the terminal using typer.
kreview
ctDNA fragmentomics feature evaluation
Usage:
Options:
--version
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or
customize the installation.
eval
Model evaluation commands
Usage:
ablate
Feature group ablation — finds optimal feature subset per evaluator
Usage:
cpu
CPU feature group ablation (LR, RF, XGB) with nested CV.
Evaluates feature subsets across outer folds using inner CV
to find the best feature group combination per model.
Output: {evaluator}_ablation_cpu.json
Usage:
Options:
--matrix <path> Path to selected matrix parquet [required]
--output <path> Output directory for ablation JSON [default: .]
--n-outer-folds <int> Outer CV folds (must match eval) [default: 5]
--n-inner-folds <int> Inner CV folds for subset selection [default: 3]
--seed <int> Random seed [default: 42]
gpu
GPU feature group ablation (TabPFN, TabICL) with nested CV.
Uses ZERO-SHOT inference only in the inner CV loop (no fine-tuning).
Output: {evaluator}_ablation_gpu.json
Usage:
Options:
--matrix <path> Path to selected matrix parquet [required]
--output <path> Output directory for ablation JSON [default: .]
--models <str> Comma-separated GPU model names [default:
tabpfn,tabicl]
--n-outer-folds <int> Outer CV folds (must match CPU ablation)
[default: 5]
--n-inner-folds <int> Inner CV folds for subset selection [default: 3]
--seed <int> Random seed [default: 42]
--device <str> PyTorch device [default: cuda]
--max-gpu-features <int> Feature cap for GPU models [default: 150]
--eval-stats <path> Path to eval_stats parquet for score-based feature
capping
merge
Merge CPU + GPU ablation results into best_subset.json.
Produces a unified per-model per-fold feature list consumed by
kreview eval cpu --best-subset and kreview eval gpu --best-subset.
Usage:
Options:
--cpu-json <path> Path to *_ablation_cpu.json [required]
--gpu-json <path> Path to *_ablation_gpu.json (optional)
--output <path> Output directory for best_subset.json [default: .]
cpu
Per-evaluator evaluation using LR, RF, XGBoost (CPU).
Iterates over all _matrix.parquet files in --matrices-dir, trains the specified models, and writes _model_results.json to --output.
Usage:
Options:
--matrices-dir <path> Directory containing *_matrix.parquet files
from kreview extract [required]
--output <path> Output directory [default: output/]
--models <str> Comma-separated CPU models: lr,rf,xgb
[default: lr,rf,xgb]
--cv-folds <int> Cross-validation folds [default: 5]
--resume Skip evaluators with existing results
--seed <int> Random seed for reproducibility. [default:
42]
--deterministic / --no-deterministic
Enable PyTorch deterministic mode (slower
but reproducible). [default: deterministic]
--best-subset <path> Path to *_best_subset.json from ablation
merge (enables nested CV)
gpu
Per-evaluator evaluation using TabPFN, TabICL (GPU).
Each model name encodes its variant: 'tabpfn' = zero-shot, 'tabpfn_ft' = fine-tuned, 'tabicl' = zero-shot, 'tabicl_ft' = fine-tuned. Iterates over all *_matrix.parquet files and writes results JSONs.
Usage:
Options:
--matrices-dir <path> Directory containing *_matrix.parquet files
from kreview extract [required]
--output <path> Output directory [default: output/]
--models <str> Comma-separated GPU models:
tabpfn,tabpfn_ft,tabicl,tabicl_ft [default:
tabpfn,tabicl]
--cv-folds <int> Cross-validation folds [default: 5]
--finetune-epochs <int> Fine-tuning epochs for _ft variants
[default: 50]
--finetune-lr <float> Fine-tuning learning rate for _ft variants
[default: 1e-05]
--device <str> PyTorch device: cuda, cpu [default: cuda]
--shap Compute SHAP values
--shap-samples <int> Max SHAP samples [default: 500]
--resume Skip evaluators with existing results
--skip-gpu-joblib Skip saving GPU model joblib files (can be
>200MB each)
--seed <int> Random seed for reproducibility. [default:
42]
--deterministic / --no-deterministic
Enable PyTorch deterministic mode (slower
but reproducible). [default: deterministic]
--max-gpu-features <int> Maximum features for GPU models. If feature
count exceeds this, the top N are selected
by mutual information from eval_stats. Set
to 0 to disable capping. [default: 150]
--best-subset <path> Path to *_best_subset.json from ablation
merge (enables nested CV)
multimodal
Cross-evaluator multimodal evaluation (stacking + ablation)
Usage:
ablation
Stage 3: Leave-one-evaluator-out ablation analysis.
Uses the best stacking model to measure each evaluator's marginal
contribution. Produces ablation_results.json.
Usage:
Options:
--stacking-matrix <path> Path to stacking_matrix.parquet from
multimodal prep [required]
--stacking-results-dir <path> Directory with stacking_*_results.json from
multimodal single [required]
--cv-folds <int> Cross-validation folds [default: 5]
--seed <int> Random seed [default: 42]
--output <path> Output directory [default: output/]
merge
Stage 4: Merge partial results into unified multimodal_results.json.
Combines prep metadata, per-model stacking results, and optional ablation into a single output matching the monolithic schema.
Usage:
Options:
--stacking-results-dir <path> Directory with stacking_*_results.json from
multimodal single [required]
--prep-metadata <path> Path to prep_metadata.json from multimodal
prep [required]
--ablation-results <path> Optional path to ablation_results.json from
multimodal ablation
--output <path> Output directory [default: output/]
prep
Stage 1: Build stacking + raw-feature matrices from evaluator results.
Produces stacking_matrix.parquet, optionally
raw_features_matrix.parquet, and prep_metadata.json.
Usage:
Options:
--results-dir <path> Directory with *_model_results.json files from
eval cpu/gpu [required]
--super-matrix <path> Optional path to super_matrix.parquet for raw-
feature strategy
--multimodal-selection <str> Feature selection for raw features: grootcv
(default since #96 — most stable all-relevant
selector, measured), mi (fast exploration),
leshy, or boruta_shap (DEPRECATED — needs
kreview[legacy-boruta], conflicts with the
arfs extra). grootcv/leshy require: pip
install kreview[arfs] [default: grootcv]
--top-percentile <float> Top N%% features for MI selection [default:
10.0]
--selection-cutoff <float> GrootCV shadow-importance divisor; higher
admits more features (#96 measured default)
[default: 3.0]
--selection-n-iter <int> GrootCV shadow-test iterations (#96: 0.96
agreement with 50 at 6x speed) [default: 10]
--selection-n-jobs <int> LightGBM threads for GrootCV (0 = library
default; set to the scheduler allocation on
HPC) [default: 0]
--seed <int> Random seed [default: 42]
--output <path> Output directory [default: output/]
run
Cross-evaluator multimodal evaluation with stacking and ablation.
Reads per-evaluator model_results.json files for OOF probabilities and combines them into a stacking matrix. Three strategies are run:
- Stacking: Meta-learner on OOF probabilities across evaluators
- Raw features (if --super-matrix provided): MI or Boruta-SHAP selected features
- Ablation: Leave-one-evaluator-out importance analysis
Usage:
Options:
--results-dir <path> Directory with *_model_results.json files
from eval cpu/gpu [required]
--super-matrix <path> Optional path to super_matrix.parquet for
raw-feature strategy
--output <path> Output directory [default: output/]
--models <str> Comma-separated CPU models for multimodal
evaluation (lr,rf,xgb) [default: rf,xgb]
--gpu-models <str> Comma-separated GPU models:
tabpfn_ft,tabicl_ft. Empty = CPU only.
--top-percentile <float> Top N%% features for MI selection (matches
per-evaluator pipeline) [default: 10.0]
--multimodal-selection <str> Multimodal feature selection: grootcv
(default since #96 — most stable all-
relevant selector, measured), mi (fast
exploration), leshy, or boruta_shap
(DEPRECATED — needs kreview[legacy-boruta],
conflicts with the arfs extra).
grootcv/leshy require: pip install
kreview[arfs] [default: grootcv]
--selection-cutoff <float> GrootCV shadow-importance divisor; higher
admits more features (#96 measured default)
[default: 3.0]
--selection-n-iter <int> GrootCV shadow-test iterations (#96: 0.96
agreement with 50 at 6x speed) [default:
10]
--selection-n-jobs <int> LightGBM threads for GrootCV (0 = library
default; set to the scheduler allocation on
HPC) [default: 0]
--cv-folds <int> Cross-validation folds [default: 5]
--device <str> PyTorch device: cuda, cpu [default: cuda]
--finetune-epochs <int> GPU fine-tuning epochs for _ft variants
[default: 50]
--finetune-lr <float> GPU fine-tuning learning rate [default:
1e-05]
--seed <int> Random seed for reproducibility. [default:
42]
--deterministic / --no-deterministic
Enable PyTorch deterministic mode (slower
but reproducible). [default: deterministic]
single
Stage 2: Train one model on the stacking (+ optional raw) matrix.
Produces stacking_{model}_results.json.
Usage:
Options:
--stacking-matrix <path> Path to stacking_matrix.parquet from
multimodal prep [required]
--model <str> Model to train: rf, xgb, lr, tabpfn_ft,
tabicl_ft [default: rf]
--raw-features-matrix <path> Optional path to raw_features_matrix.parquet
from prep
--cv-folds <int> Cross-validation folds [default: 5]
--device <str> PyTorch device [default: cuda]
--finetune-epochs <int> GPU fine-tuning epochs [default: 50]
--finetune-lr <float> GPU fine-tuning learning rate [default:
1e-05]
--best-single-auc <float> Best single-evaluator AUC for delta
computation [default: 0.0]
--seed <int> Random seed [default: 42]
--deterministic / --no-deterministic
Enable PyTorch deterministic mode.
[default: deterministic]
--output <path> Output directory [default: output/]
extract
Label samples and extract feature matrices (no eval/model/report).
Runs the labeling pipeline, then extracts features for each matched
evaluator into *_matrix.parquet files. This is the first half of
kreview run, designed for parallelized Nextflow execution.
Usage:
Options:
--cancer-samplesheet <path> Cancer samplesheet CSV [required]
--healthy-xs1-samplesheet <path>
Healthy XS1 samplesheet CSV [required]
--healthy-xs2-samplesheet <path>
Healthy XS2 samplesheet CSV [required]
--cbioportal-dir <path> Directory with cBioPortal files [required]
--krewlyzer-dir <str> krewlyzer output directory [required]
--output <path> Output directory for matrices [default:
output/]
--min-vaf <float> Min VAF for Possible ctDNA+ (default 1%)
[default: 0.01]
--min-fragments <int> Min fragments PF for Depth QC (samples below
are Insufficient Data) [default: 2000]
--min-variants <int> Min # variants passing VAF for Possible
ctDNA+ [default: 1]
--ch-hotspot-maf <path> Optional TSV of CH hotspot variants for CH-
only demotion.
--features <str> Comma-separated evaluator names (default:
all)
--tier <int> Run only this tier
--chunk-size <str> Samples per DuckDB read batch. 'auto'
(default) probes parquet row density at
runtime, or pass an integer to override
(e.g. --chunk-size 200). [default: auto]
--labels <path> Path to a pre-computed labels.parquet file.
When provided, skips the internal labeling
step entirely. Used by Nextflow multistage
to avoid re-running labeling per evaluator.
--duckdb-threads <int> Max threads for DuckDB query execution
(match SLURM cpus). [default: 8]
--duckdb-memory <str> DuckDB memory limit (e.g., '32GB', '16GB').
Controls peak memory for parquet
aggregation. [default: 32GB]
features-list
List all registered feature evaluators.
Usage:
fuse
Fuse per-evaluator matrices into a single super-matrix.
Discovers all *_matrix.parquet files in --output-dir, extracts
their feature columns (prefixed with evaluator name), outer-joins on
SAMPLE_ID, and writes super_matrix.parquet for downstream multimodal
evaluation.
Usage:
Options:
--output-dir <path> Directory containing *_matrix.parquet files
[required]
--min-evaluators <int> Minimum number of evaluators a sample must appear in
to be retained [default: 1]
--output-name <str> Filename for the fused super-matrix (written to
--output-dir) [default: super_matrix.parquet]
label
Generate ctDNA labels without feature evaluation.
Usage:
Options:
--cancer-samplesheet <path> Cancer samplesheet CSV [required]
--healthy-xs1-samplesheet <path>
Healthy XS1 samplesheet CSV [required]
--healthy-xs2-samplesheet <path>
Healthy XS2 samplesheet CSV [required]
--cbioportal-dir <path> Directory with cBioPortal files [required]
--krewlyzer-dir <str> krewlyzer output directory (repeatable).
Supplies per-sample fragment counts: without
it the --min-fragments Insufficient-Data
rule cannot fire and total_fragments_pf is
emitted as unknown (#122).
--output <path> Output parquet file [default:
labels.parquet]
--min-vaf <float> Min VAF for Possible ctDNA+ (default 1%)
[default: 0.01]
--min-fragments <int> Min fragments PF for Depth QC (samples below
are Insufficient Data) [default: 2000]
--min-variants <int> Min # variants passing VAF for Possible
ctDNA+ [default: 1]
--ch-hotspot-maf <path> Optional TSV of CH hotspot variants for CH-
only demotion. Samples with only CH
mutations are demoted to Possible ctDNA−.
report
Render the single-page evaluation report from a pipeline output directory.
One self-contained HTML (plotly inlined, no CDN) built from the run's artifacts: scoreboard, per-model metrics with CIs, OOF-computed ROC/PR/calibration/decision curves, subgroup AUCs, feature-group ablation stability, multimodal stacking, and cohort composition. Aggregates only — the PHI guard refuses to emit sample ids.
Always writes report_manifest.json next to the page (#98): the loud record of
what the report covers, and of the failure if rendering crashed.
Usage:
Options:
--outdir <path> Pipeline output directory (labels/, models/, matrices/,
scoreboard parquet) [required]
--out-dir <path> Directory for the rendered report + manifest [default:
reports/]
--run-label <str> Free-text label shown in the report header
--trace <path> Optional Nextflow execution_trace.txt for the run-
diagnostics tab
select
Score features and apply feature selection to extracted matrices.
Reads all *_matrix.parquet files from --matrices-dir, computes
feature scores (univariate AUC + mutual information), and selects the
top features using mRMR (default, redundancy-aware) or hybrid union
(top N%% by AUC ∪ top N%% by MI).
Writes selected matrices, eval stats, and QC metadata to --output
(or overwrites originals when --overwrite is set).
Usage:
Options:
--matrices-dir <path> Directory with *_matrix.parquet files from
kreview extract [required]
--top-percentile <float> Top X%% of features to select (controls K
for mRMR, or per-metric cutoff for
hybrid_union) [default: 50.0]
--strategy <str> Feature selection strategy: mrmr (default,
redundancy-aware) or hybrid_union (AUC∪MI)
[default: mrmr]
--cv-folds <int> Cross-validation folds for univariate AUC
scoring [default: 5]
--impute-strategy <str> Imputation strategy for variance check:
median, mean, zero [default: median]
--output <path> Output directory for selected matrices
(ignored when --overwrite is set) [default:
output/]
--overwrite Overwrite original matrices in --matrices-
dir instead of writing to --output
--compute-univariate-auc / --no-compute-univariate-auc
Compute per-feature univariate AUC (disable
for MI-only selection) [default: compute-
univariate-auc]
--seed <int> Random seed for reproducibility. [default:
42]