filter

Random forest filter for structural variants

Last updated: 2026-07-24

Overview

The filter command trains a random forest classifier on user-provided positive and negative SV sites, then applies the model to assign a confidence score (RF_SCORE) to each SV call in per-sample VCFs. Multi-sample input is handled via a manifest file.

Input requirements

Manifest:
- Format: tab-separated file with header.
- Columns:
  - file: path to per-sample VCF/BCF file
  - sample: sample name
Per-sample VCF:
- Format: bi-allelic VCF/BCF files following the VCF specification
- INFO: SVTYPE, AC, SUPP_CALLER, SUPP_METHOD, MAX_REand all feature INFO tags specified by --feature.
- ID: unique within each per-sample VCF. Training-site matching is performed on this ID directly.
Training sites (--train-sites):
- Format: tab-separated file without header.
- Columns: ID, label (1 = true positive, 0 = true negative)
Benchmark sites (--bench-sites, optional):
- Format: same as training sites.
- Used for independent evaluation only; bench SV IDs are excluded from training.

Output

Per-sample VCF: {output}.{SVTYPE}.{sample}.vcf.gz
- INFO: RF_SCORE — random forest probability score (0–1) for the target SVTYPE. Non-target variants are written unchanged without the score.
- ID: same as the input VCF.
Model file: {output}.{SVTYPE}.model — pickled RandomForestClassifier.
Training statistics:
- {output}.cv_summary.txt — cross-validation results from hyperparameter search.
- {output}.test.score_distribution.pdf — score density plot on the held-out test set.
- {output}.test.cutoff_summary.txt — performance at various score cutoffs.
Benchmark statistics (if --bench-sites provided):
- {output}.bench.score_distribution.pdf
- {output}.bench.cutoff_summary.txt

Training workflow

The filter command performs the following steps:

Data loading: All per-sample VCFs listed in the manifest are loaded into a single dataframe. Only variants matching --sv-type and with AC > 0 are retained.
Site-level labeling: Each SV call is labeled as positive (1) or negative (0) if its ID appears in --train-sites. Unlabeled calls are assigned -9 and excluded from training.
Call-level confidence filtering (optional):
- --min-re: SV calls at positive sites with MAX_RE below this threshold are excluded from training (likely false positive SV calls).
- --min-support-caller / --min-support-method: SV calls at negative sites with SUPP_CALLER or SUPP_METHOD at or above this threshold are excluded from training (likely false negative SV calls).
Balanced train/test split: Positive and negative training examples are balanced via downsampling to the minority class size, then split according to --train-size.
Model training: A random forest classifier is trained with hyperparameter tuning via randomized search cross-validation (--k-fold folds, --n-iter iterations).
Per-sample application: The trained model predicts RF_SCORE for each SV call, and annotated VCFs are written per sample.
Benchmark evaluation (optional): If --bench-sites provided, the model is evaluated on the benchmark sites after per-sample VCFs are written. If --bench-sample is specified, only those samples are used for benchmark evaluation, otherwise all samples are used.

Suggestions on training and benchmark sites

Training sites: training sites can be generated by comparing the representative SVs to multiple high-quality SV dataset (e.g., HGSVC, 1000 Genomes, GIAB, gnomAD-SV). Sites that are present in multiple SV dataset can be labeled as positive, while novel sites that are not present in any SV dataset can be labeled as negative. The --min-re and --min-support-caller / --min-support-method options ensure that only high-confidence positive and negative SV calls are used for training.
Benchmark sites: it is recommended to include a few benchmark samples (e.g., HG002, HPRC samples) with ground truth SVs as benchmark sites. If both --train-sites and --bench-sites are provided in the same run, the benchmark sites will be excluded from training to ensure independent evaluation of the model. If training and benchmark are performed in separate runs, the benchmark sites should be manually excluded from the training sites.

Usage

# Model training
harmonisv filter \
  --manifest manifest.txt \
  --output output_prefix \
  --sv-type INS \
  --feature "SVLEN,MEAN_VAF,STD_VAF,DP_MINIMAP2_CUTESV,VAF_MINIMAP2_CUTESV" \
  --train-sites train_sites.txt \
  --min-re 5 \
  --min-support-method 3

# Apply a pre-trained model on benchmark sample
harmonisv filter \
  --manifest manifest.txt \
  --output output_prefix \
  --sv-type INS \
  --feature "SVLEN,MEAN_VAF,STD_VAF,DP_MINIMAP2_CUTESV,VAF_MINIMAP2_CUTESV" \
  --apply-model pretrained.model \
  --bench-sites bench_sites.txt \
  --bench-sample HG002

Arguments

Input/Output arguments:

--manifest FILE: tab-delimited manifest file with columns: file (path to per-sample VCF), sample (sample name)
-o, --output PREFIX: output prefix for all output files
--sv-type TYPE: SVTYPE to work on (e.g., INS, DEL, DUP, INV)
--feature TAGS: comma-separated list of INFO tags used as training features (e.g., SVLEN,MAX_RE,SUPP_CALLER)

Training arguments:

--train-sites FILE: tab-separated file of training SV sites (without header). Columns: SV_ID, label (1 = positive, 0 = negative). Required unless --apply-model is used.
--train-size FLOAT: proportion of SVs used for training; the remainder is held out as a test set (default: 0.9)
--max-train N: maximum number of SVs used for training (default: no limit)
--min-re N: call-level filter: positive-labeled calls with MAX_RE below this value are excluded from training (default: None)
--min-support-caller N: call-level filter: negative-labeled calls with SUPP_CALLER at or above this value are excluded from training, as they are too high-confidence to be true negatives (default: None)
--min-support-method N: same as --min-support-caller but using SUPP_METHOD; overrides --min-support-caller if both are specified (default: None)
--bench-sites FILE: tab-separated file of benchmark SV sites for independent evaluation. Bench SV IDs are excluded from training and evaluated separately after per-sample VCFs are written.
--bench-sample SAMPLE: comma-separated list of sample names to use for benchmark evaluation (default: all samples)

Model arguments:

--n-estimator N: number of trees in the random forest (default: 300)
--k-fold N: number of folds for randomized search cross-validation (default: 10)
--n-iter N: number of parameter settings sampled in randomized search (default: 100)
--max-features STR: hyperparameter search range for max_features. Format: single value, comma-separated list, or from:to:step (default: auto — 1/2 √n_features to 2/3 n_features)
--max-depth STR: hyperparameter search range for max_depth. Format: same as --max-features (default: 7:14:1)
--min-samples-leaf STR: hyperparameter search range for min_samples_leaf. Format: same as --max-features (default: 1,2,5,10,20,50)
--apply-model FILE: skip training and apply a pre-trained model (pickled RandomForestClassifier). --train-sites is not required when this option is used.
--model-thread N: number of threads for RandomForestClassifier (default: 4)
--cv-thread N: number of threads for cross-validation (default: 4). Total cores used = --model-thread × --cv-thread.

Other arguments:

--seed N: random seed for reproducibility (default: 42)