HmmIBDTasks

FilterVcfForHmmIBD

description
Pre-filter a VCF for IBD inference: mask low-depth genotypes (FMT/DP < min_depth), optionally preserve the original allele-frequency annotations, recompute AN/AC/AF (optionally per population), and drop alleles/sites that are no longer represented. Emits a compressed BCF ready for hmmibd-rs --from-bcf.
tool
bcftools
tool_version
1.22
tool_url
https://www.htslib.org/
tool_citation
Danecek P, Bonfield JK, Liddle J, et al. Twelve years of SAMtools and BCFtools. GigaScience. 2021;10(2):giab008.
author
Jonn Smith
outputs
{'filtered_bcf': 'Filtered, AN/AC/AF-recomputed callset as a compressed BCF', 'filtered_bcf_index': 'CSI index for filtered_bcf'}

Inputs

Required

  • input_vcf (File, required): VCF/BCF to filter prior to IBD inference. (required)
  • prefix (String, required): Basename for the output BCF. (required)

Optional

  • populations_file (File?): Optional sample-to-population file passed to bcftools +fill-tags -S; when given, AN/AC/AF are computed per population. When omitted, tags are computed across all samples. (default: none)
  • rename_annots_tsv (File?): Required when keep_original_af=true: two-column TSV of old-namenew-name passed to bcftools annotate --rename-annots. (default: none)
  • runtime_attr_override (RuntimeAttr?): Override the default runtime attributes. (default: none)

Defaults

  • biallelic_only (Boolean, default=true): Restrict to biallelic sites (bcftools view -m2 -M2). Recommended true: multiallelic sites (especially indels) can exceed hmmibd-rs --max-all and crash it until that is patched. (default: true)
  • extra_args (String, default=""): Additional bcftools view filters appended to the FINAL view (after AN/AC/AF are recomputed, so INFO-based expressions like MAF work). Whitespace-separated tokens; write expressions without internal spaces, e.g. "-e MAF<0.01" or "-i F_MISSING<0.1". Note the final view already applies -i 'MAX(INFO/AC) > 0'; supply extra exclusions with -e (a second -i would override the built-in one). (default: empty)
  • keep_original_af (Boolean, default=false): If true, rename the existing INFO annotations via rename_annots_tsv before recomputing AN/AC/AF, so the original frequencies are preserved under new tags. (default: false)
  • mask_gq0_genotypes (Boolean, default=false): Also set GQ0 genotypes to missing (in addition to the FORMAT/DP < min_depth mask). Older GATK (pre-4.6.0.0 GenotypeGVCFs; also GnarlyGenotyper) emitted no-/low-confidence hom-refs as 0/0 with GQ=0 instead of ./. (GATK issue #7792, fixed in PR #8741). Turning this on reproduces that fix downstream — the DP mask alone misses GQ0 calls whose DP >= min_depth. NOTE: this is the conservative choice — it drops ALL GQ0 hom-refs, including any that are genuinely well-covered ref; use a GVCF cross-reference if you need to keep those. (default: false)
  • max_variants (Int, default=0): Optional cap on the number of variants kept. When >0 and the filtered callset exceeds it, sites are thinned evenly across the genome down to at most this many (not truncated to the first N). (default: 0 = no limit)
  • min_depth (Int, default=5): Genotypes with FORMAT/DP below this value are set to missing (bcftools filter -S .). (default: 5)
  • split_multiallelics (Boolean, default=true): Split multiallelic records into biallelic ones (bcftools norm -m-any) so SNP alleles at multiallelic/spanning-deletion sites are recovered rather than dropped. Runs after the type pre-select to stay fast. (default: true)
  • variant_types (String, default="snps"): Which variant types to keep (bcftools view -v): 'snps', 'indels', or 'both'. SNPs are the standard hmmIBD marker set; Pf indels are error-prone. (default: snps)

Outputs

  • filtered_bcf (File)
  • filtered_bcf_index (File)

HmmIBDrs

description
Run hmmibd-rs (the Rust reimplementation of hmmIBD) directly on a BCF to infer identity-by-descent segments and per-pair IBD fractions. Every hmmibd-rs flag is exposed as an input with its upstream default, including the output-mode switches (suppress_frac, bcf_to_bin_file, bcf_to_bin_file_by_chromosome) that change which files are produced. Outputs are glob-backed so each is present only when the chosen flags actually write it: a normal run yields ibd_segments + ibd_fraction; suppress_frac drops ibd_fraction; a bcf-to-bin mode skips the HMM and yields binary_genotypes instead.
tool
hmmibd-rs
tool_version
0.1.5
tool_url
https://github.com/bguo068/hmmibd-rs
tool_citation
Guo B, Schaffner SF, Taylor AR, et al. hmmibd-rs. Malar J. 2026;25:110.
author
Jonn Smith
outputs
{'ibd_segments': 'Per sample-pair IBD/non-IBD segments with assigned state and variant counts (.hmm.txt); empty when a bcf-to-bin mode skips the HMM', 'ibd_fraction': 'Per sample-pair summary; key column fract_sites_IBD (.hmm_fract.txt); empty when suppress_frac=true or a bcf-to-bin mode is used', 'binary_genotypes': 'Binary genotype file(s) (*.bin); non-empty only under bcf_to_bin_file or bcf_to_bin_file_by_chromosome'}

Inputs

Required

  • input_bcf (File, required): Genotype input for hmmibd-rs. With from_bcf=true (default): a BCF/VCF read via --from-bcf. With from_bcf=false: an hmmIBD text genotype table (-i), e.g. from BcfToSampleTable. (required)
  • prefix (String, required): Output prefix; produces .hmm.txt and .hmm_fract.txt. (required)

Optional

  • bad_samples_file (File?): Optional list of sample IDs to exclude (-b/--bad-file). (default: none)
  • bcf_filter_config (File?): Optional TOML BCF filter config (--bcf-filter-config); a default is generated when omitted. (default: none)
  • buffer_size_frac (Int?): Write buffer size in bytes for the fraction output (--buffer-size-frac). (default: none; hmmibd-rs uses 8Kb)
  • buffer_size_segments (Int?): Write buffer size in bytes for the segments output (--buffer-size-segments). (default: none; hmmibd-rs uses 8Kb)
  • data_file2 (File?): Optional second-population genotypes (-I/--data-file2). (default: none)
  • filt_max_tmrca (Float?): Drop pairs with k_rec above this threshold (--filt-max-tmrca). (default: none)
  • filt_min_seg_cm (Float?): Drop output segments shorter than this many cM (--filt-min-seg-cm). (default: none)
  • freq_file1 (File?): Optional allele-frequency file for population 1 (-f/--freq-file1); computed from data when omitted. (default: none)
  • freq_file2 (File?): Optional allele-frequency file for population 2 (-F/--freq-file2). (default: none)
  • genome (File?): Optional genome/recombination-map spec (--genome); mutually exclusive with rec_rate, and takes precedence when set. (default: none)
  • good_pairs_file (File?): Optional list of sample pairs to analyze (-g/--good-file). (default: none)
  • k_rec_max (Float?): Cap on inferred number of generations (-n/--k-rec-max). (default: none; hmmibd-rs uses Inf = no cap)
  • runtime_attr_override (RuntimeAttr?): Override the default runtime attributes. (default: none)

Defaults

  • bcf_read_mode (String, default="dominant-allele"): How to read genotypes from the BCF (--bcf-read-mode): dominant-allele | first-ploidy | each-ploidy. (default: dominant-allele)
  • bcf_to_bin_file (Boolean, default=false): Convert the BCF to a single binary genotype file and skip the HMM (--bcf-to-bin-file); yields binary_genotypes, leaves ibd_segments/ibd_fraction empty. (default: false)
  • bcf_to_bin_file_by_chromosome (Boolean, default=false): Convert the BCF to one binary genotype file per chromosome and skip the HMM (--bcf-to-bin-file-by-chromosome); yields binary_genotypes, leaves ibd_segments/ibd_fraction empty. (default: false)
  • eps (Float, default=0.001): Genotyping error rate (--eps). (default: 0.001)
  • extra_args (String, default=""): Additional command-line args appended verbatim to the hmmibd-rs invocation. (default: empty)
  • filt_ibd_only (Boolean, default=false): Omit non-IBD segments from the output (--filt-ibd-only). (default: false)
  • fit_thresh_dk (Float, default=0.01): Convergence threshold on k (--fit-thresh-dk). (default: 0.01)
  • fit_thresh_dpi (Float, default=0.001): Convergence threshold on pi (--fit-thresh-dpi). (default: 0.001)
  • fit_thresh_drelk (Float, default=0.001): Convergence threshold on relative k (--fit-thresh-drelk). (default: 0.001)
  • from_bcf (Boolean, default=true): Read the input as BCF/VCF (--from-bcf, applies --bcf-read-mode). Set false to read a pre-built hmmIBD text genotype table instead. (default: true)
  • max_all (Int, default=8): Maximum number of unique alleles per site (--max-all). (default: 8)
  • max_discord (Float, default=1.0): Maximum discordance fraction to consider a pair (--max-discord). (default: 1.0)
  • max_iter (Int, default=5): Max EM iterations (-m/--max-iter). (default: 5)
  • min_discord (Float, default=0.0): Minimum discordance fraction to consider a pair (--min-discord). (default: 0.0)
  • min_inform (Int, default=10): Minimum number of informative sites for a pair (--min-inform). (default: 10)
  • min_snp_sep (Int, default=5): Minimum bp separation between SNPs (--min-snp-sep). (default: 5)
  • num_threads (Int, default=0): Number of threads; 0 = all CPUs (--num-threads). (default: 0)
  • par_chunk_size (Int, default=120): Sample-pairs per chunk (par-mode 0) or samples per chunk (par-mode 1) (--par-chunk-size). (default: 120)
  • par_mode (Int, default=0): Parallelization mode: 0 = small sample sets, 1 = large sample sets (--par-mode). (default: 0)
  • rec_rate (String, default="0.00000074"): Constant recombination rate per generation per bp (-r/--rec-rate); ignored when genome is set. (default: 0.00000074)
  • suppress_frac (Boolean, default=false): Suppress the per-pair fraction output (--suppress-frac); leaves ibd_fraction empty. (default: false)

Outputs

  • ibd_segments (Array[File])
  • ibd_fraction (Array[File])
  • binary_genotypes (Array[File])

BcfToVcf

description
Re-emit a BCF as a bgzipped, tabix-indexed VCF (bcftools view -Oz). Convenience conversion so the filtration workflow can hand back a VCF.
tool
bcftools
tool_version
1.22
tool_url
https://www.htslib.org/
author
Jonn Smith
outputs
{'filtered_vcf': 'The input BCF re-emitted as a bgzipped VCF', 'filtered_vcf_index': 'Tabix (.tbi) index for filtered_vcf'}

Inputs

Required

  • input_bcf (File, required): BCF (or VCF) to re-emit as bgzipped VCF. (required)
  • prefix (String, required): Basename for the output VCF. (required)

Optional

  • runtime_attr_override (RuntimeAttr?): Override the default runtime attributes. (default: none)

Outputs

  • filtered_vcf (File)
  • filtered_vcf_index (File)

BcfToSampleTable

description
Convert a bi-allelic BCF/VCF to the hmmIBD text genotype table: a tab-delimited matrix with columns chrom(int) pos then one call per sample, alleles coded 0/1/... and -1 for missing, using the first allele of each GT (matches hmmibd-rs --bcf-read-mode first-ploidy). Also emits a matching bi-allelic allele-frequency file (same sites and order) computed from the matrix, so it can be supplied to both hmmIBD and hmmibd-rs. Non-numeric contigs (MIT/API) are dropped because hmmIBD requires integer chromosomes.
tool
bcftools
tool_version
1.22
tool_url
https://www.htslib.org/
author
Jonn Smith
outputs
{'sample_gt_table': 'hmmIBD text genotype table (.sample_gt.txt); hmmibd-rs input in text mode (from_bcf=false)', 'sample_freq_table': 'Bi-allelic allele-frequency file (.sample_freq.txt), same sites/order as the genotype table'}

Inputs

Required

  • input_bcf (File, required): Bi-allelic, SNP-filtered BCF/VCF (as produced by FilterVcfForHmmIBD) to convert. (required)
  • prefix (String, required): Basename for the output tables. (required)

Optional

  • runtime_attr_override (RuntimeAttr?): Override the default runtime attributes. (default: none)

Outputs

  • sample_gt_table (File)
  • sample_freq_table (File)