taf-bcftools

taf-bcftools packages BCFtools and the matching HTSlib release for TAFFISH.

Package identity:

• name: bcftools
• command: taf-bcftools
• kind: tool
• version: 1.24-r1
• image: ghcr.io/taffish/bcftools:1.24-r1
• native platforms: linux/amd64, linux/arm64
• TAFFISH app license: Apache-2.0
• upstream release: BCFtools 1.24
• runtime identity: bcftools 1.24, Using htslib 1.24

What This App Packages

The image compiles the official BCFtools 1.24 and HTSlib 1.24 release tarballs. It keeps the upstream command surface, all installed BCFtools plugins, HTSlib companion programs, and the helper scripts installed by upstream make install.

The source archives are pinned by SHA256:

• BCFtools: 8caddc22610ee2851666047c859bb91da0c1e32d0c2ec553db6f153ad130e46f
• HTSlib: 28a8de191381c7a97a35675ceac76fa1ea95e7b678d6a2e9d600a7874e4077de

BCFtools is built with GNU Scientific Library support, so GSL-dependent commands such as bcftools polysomy and bcftools cnv are available.

Scope

This app supports:

• BCFtools commands for viewing, querying, calling, filtering, normalizing, annotating, merging, indexing, statistics, consensus, CNV and RoH work
• the packaged plugin system through bcftools +PLUGIN or bcftools plugin PLUGIN
• bgzip, tabix, htsfile, annot-tsv, and ref-cache from HTSlib
• upstream helper scripts for GFF conversion, RoH processing and visualization, ploidy plots, VCF utilities, and vcfstats plots
• local files and HTSlib-supported remote URLs when the selected backend has network access

This app does not:

• bundle reference genomes, annotation resources, or project-specific data
• bundle pdflatex or tectonic for the optional final vcfstats summary PDF
• perform workflow orchestration or choose scientifically appropriate filtering, calling, normalization, or annotation parameters

BCFtools 1.24 Notes

Important upstream changes include:

• +trio-dnm2 was removed and replaced by the new +trio-dnm3 plugin
• bcftools csq gained --greedy
• bcftools norm gained --no-realign[=NUM]
• bcftools merge gained -m exact
• +split-vep gained SnpEff support
• MAC/MAF filtering, annotation, CNV/RoH quality, localized alleles, per-sample statistics, symbolic allele handling, and multiple other paths received correctness fixes
• HTSlib 1.24 adds security and input-validation fixes and removes experimental CRAM 4.0 support

Review the upstream release notes before depending on changed plugin or CRAM behavior.

Installation

taf update
taf install bcftools 1.24-r1

For local testing before publication:

taf install --from .

Usage

Show TAFFISH wrapper help:

taf-bcftools --help

Show upstream help and version:

taf-bcftools -- --help
taf-bcftools -- --version
taf-bcftools bcftools --version

Run common workflows:

taf-bcftools bcftools view input.vcf.gz
taf-bcftools bcftools stats input.vcf.gz > input.vchk
taf-bcftools bcftools norm -f reference.fa input.vcf.gz -Oz -o normalized.vcf.gz
taf-bcftools bcftools filter -i 'QUAL>=30' input.vcf.gz -Oz -o filtered.vcf.gz
taf-bcftools bcftools index filtered.vcf.gz
taf-bcftools bcftools +fill-tags input.vcf.gz -Oz -o tagged.vcf.gz -- -t AC,AN,AF

Use companion commands:

taf-bcftools bgzip -c input.vcf > input.vcf.gz
taf-bcftools tabix -p vcf input.vcf.gz
taf-bcftools htsfile input.vcf.gz
taf-bcftools plot-vcfstats -P -p stats-plots input.vchk
taf-bcftools roh-viz --help

Command Mode

This is a thin <taf-app:container:...> wrapper. A first non-option argument is treated as an executable inside the image. BCFtools subcommands are not standalone executables, so use:

taf-bcftools bcftools view input.vcf.gz

Do not use:

taf-bcftools view input.vcf.gz

Use taf-bcftools -- --help or taf-bcftools -- --version to pass option-leading arguments to the default bcftools command.

Container Contents

Main commands:

• bcftools
• bgzip
• tabix
• htsfile
• annot-tsv
• ref-cache

Installed upstream helper scripts:

• color-chrs.pl
• gff2gff, gff2gff.py
• guess-ploidy.py
• plot-vcfstats, plot-roh.py
• roh-viz, run-roh.pl
• vcfutils.pl, vrfs-variances

Runtime support includes Perl, Python 3, gffutils, NumPy, Matplotlib, gzip/gunzip, Bash, and wget. These are included because upstream helper scripts invoke or import them.

roh-viz --embed-d3 1 uses wget to retrieve D3/Pako resources while generating a self-contained report, so that mode requires network access. Without embedding, the generated HTML references upstream CDN resources when opened.

Inputs and Outputs

BCFtools accepts VCF, compressed VCF, BCF, and command-specific alignment, reference, region, annotation, sample, or index inputs. Exact requirements depend on the selected subcommand.

Output may be VCF/BCF, compressed streams, indexes, tables, statistics, consensus sequences, plots, or HTML. BCFtools writes many results to stdout by default; use shell redirection or the upstream -o option as documented. Paths must be visible to the selected container backend.

Plotting Boundary

plot-vcfstats -P generates plot files without the final summary PDF and is fully supported in this image. The default PDF mode additionally requires pdflatex or tectonic; neither TeX engine is bundled because it would add a large document toolchain to this general-purpose BCFtools image. Generate the plots with -P, then create the PDF in a separate TeX environment when needed.

Testing

The offline, independent smoke tests cover:

• exact BCFtools and HTSlib runtime versions
• core help, GSL-enabled commands, and BCFtools 1.24 option markers
• the +trio-dnm3 transition and removal of +trio-dnm2
• a real +fill-tags plugin execution on a tiny VCF
• real bgzip compression, tabix indexing, and BCFtools reading
• real bcftools stats and Matplotlib-backed plot-vcfstats -P output
• real roh-viz HTML generation through its gzip/gunzip and BCFtools path
• Python imports, helper discovery, gzip/gunzip, and all installed HTSlib commands

Smoke does not test production-scale calling, remote services, the network-dependent roh-viz --embed-d3 1 mode, or the external TeX/PDF path.

License and Citation

The TAFFISH app packaging is Apache-2.0. Upstream BCFtools and HTSlib retain their own licenses. BCFtools is generally available under MIT/Expat terms, but this image enables GSL and the resulting BCFtools binary is distributed under GPL terms as documented by upstream. The original BCFtools and HTSlib license texts are retained under /opt/bcftools/share/licenses/ in the image.

Please cite:

Danecek P, et al. Twelve years of SAMtools and BCFtools. GigaScience. 2021. DOI: 10.1093/gigascience/giab008.

Upstream documentation:

• https://samtools.github.io/bcftools/bcftools.html
• https://github.com/samtools/bcftools