taf-bustools

TAFFISH wrapper for bustools, a command line toolkit for manipulating BUS files from single-cell RNA-seq workflows.

This repository packages upstream bustools 0.45.1 as a TAFFISH tool app. It builds bustools from the official v0.45.1 source release in a Debian 12 container image and exposes the upstream bustools command through the versioned taf-bustools command.

Installation

Install from the public TAFFISH Hub index:

taf update
taf install bustools

Install the exact release:

taf install bustools 0.45.1-r2

For local testing before the app is published to the public index:

taf install --from .

Usage

Show TAFFISH app help:

taf-bustools --help

Show the in-container bustools command summary:

taf-bustools
taf-bustools bustools

Show upstream bustools version and citation information:

taf-bustools bustools version
taf-bustools bustools cite

Inspect common subcommand help:

taf-bustools bustools sort
taf-bustools bustools correct
taf-bustools bustools count
taf-bustools bustools inspect
taf-bustools bustools text
taf-bustools bustools fromtext

Convert a small tab-delimited BUS representation into binary BUS format and back to text:

printf "AAAAAAAAAAAAAAAA\tCCCCCCCCCCCC\t0\t1\n" > input.txt
taf-bustools bustools fromtext -o input.bus input.txt
taf-bustools bustools text -p input.bus

A typical manual kallisto-bustools workflow starts with BUS output and metadata generated by kallisto bus, then uses bustools operations such as:

taf-bustools bustools inspect output.bus
taf-bustools bustools correct -w whitelist.txt -o corrected.bus output.bus
taf-bustools bustools sort -t 8 -o sorted.bus corrected.bus
taf-bustools bustools count \
  -o counts \
  -g t2g.txt \
  -e matrix.ec \
  -t transcripts.txt \
  --genecounts \
  sorted.bus

The exact options depend on the single-cell technology, barcode on-list, reference metadata, and quantification target. For complete FASTQ-to-counts automation, upstream commonly recommends kb-python, which wraps kallisto and bustools into higher-level kb ref and kb count commands.

Because this is a command-mode TAFFISH tool, the first non-option argument is treated as an executable inside the container. bustools subcommands such as sort, count, and inspect are subcommands of the bustools executable, not standalone commands. For normal bustools workflows, name the upstream command explicitly:

taf-bustools bustools sort -o sorted.bus output.bus
taf-bustools bustools count -o counts -e matrix.ec -t transcripts.txt sorted.bus

Do not use taf-bustools sort ...; TAFFISH would look for a standalone sort executable in the container rather than running bustools sort ....

Package

name: bustools
command: taf-bustools
version: 0.45.1-r2
kind: tool
image: ghcr.io/taffish/bustools:0.45.1-r2

Container

The container image is built from docker/Dockerfile. It starts from debian:12-slim, downloads the upstream v0.45.1 source archive from GitHub, compiles bustools with CMake and GCC, and installs the resulting binary into /usr/local/bin.

The image includes:

bustools

Runtime dependencies are shared libraries rather than extra user-facing commands:

libstdc++6
zlib1g

This app intentionally does not bundle kallisto or kb-python. Those tools generate BUS files and reference metadata in broader workflows, but bustools itself does not shell out to them at runtime. Keeping this app focused makes it small, composable, and suitable for TAFFISH flows that connect separate tools.

The image is built and validated for:

linux/amd64
linux/arm64

The TAFFISH metadata declares a Docker smoke check:

exist: bustools
test:  bustools reports version 0.45.1
test:  bustools prints command summary and citation information
test:  common subcommand help paths are available
test:  extended upstream subcommand and alias help paths are available
test:  a tiny fromtext -> BUS -> text round-trip succeeds

During TAFFISH Hub indexing, this smoke metadata verifies that the published image exposes the bustools binary, reports the pinned upstream version, includes the expected upstream command surface, and can read and write a minimal BUS file.

Upstream

• Project: bustools
• Homepage: https://www.kallistobus.tools/
• Manual: https://kallisto.readthedocs.io/en/latest/manuals/bustools.html
• Source: https://github.com/BUStools/bustools
• Releases: https://github.com/BUStools/bustools/releases
• Release: https://github.com/BUStools/bustools/releases/tag/v0.45.1
• Upstream license: BSD-2-Clause
• Citation: Melsted et al. 2021, doi:10.1038/s41587-021-00870-2, PMID:33795888
• BUS format background: Melsted et al. 2019, doi:10.1093/bioinformatics/btz279

Maintainer Notes

Useful checks before publishing:

taf check
taf compile -- version
taf publish --release --dry-run
docker build -t ghcr.io/taffish/bustools:0.45.1-r2 -f docker/Dockerfile .
docker build --platform linux/amd64 -t ghcr.io/taffish/bustools:0.45.1-r2-amd64-test -f docker/Dockerfile .
docker run --rm ghcr.io/taffish/bustools:0.45.1-r2 bustools version
docker run --rm ghcr.io/taffish/bustools:0.45.1-r2 bustools fromtext

The repository wrapper files are licensed under Apache-2.0. Upstream bustools is distributed under the BSD-2-Clause license, and third-party runtime components are distributed under their own upstream licenses.