turbo-picard

Faster Rust implementations of common Picard commands, built for Picard-shaped pipelines.

turbo-picard keeps the workflow interface familiar: Picard command names, KEY=VALUE arguments, and an optional picard compatibility shim. Accelerated commands run natively. Commands outside the native surface can delegate to upstream Picard when fallback is configured.

Use it when you already have Picard steps in WDL, Nextflow, Snakemake, or shell pipelines and want to test faster execution without rewriting task interfaces.

Quick Start

Install from PyPI:

python3 -m pip install turbo-picard

Installing from PyPI currently gives you both commands:

• turbo-picard: the explicit command for evaluation and normal use.
• picard: a compatibility shim for environments where you deliberately want existing picard calls to resolve to this package.

Use the explicit turbo-picard command while testing. Add the shim to a pipeline environment only after the specific commands you need have been checked.

Check the install:

turbo-picard --version
turbo-picard MarkDuplicates --help
turbo-picard doctor
turbo-picard trial MarkDuplicates I=input.bam O=marked.bam M=metrics.txt

Run one familiar command:

turbo-picard MarkDuplicates I=input.bam O=marked.bam M=metrics.txt

From a repository checkout:

cargo install --locked --path crates/turbo-picard-cli --bin turbo-picard --bin picard

When It Helps

• You already run Picard commands and want to trial one slow step first.
• You need Picard-style command names and KEY=VALUE arguments to stay stable.
• You want a command-by-command rollout with upstream Picard available for unsupported or unchecked behavior.
• You can compare outputs on a representative BAM, CRAM, FASTQ, VCF, or metrics file before changing the workflow.

Good first trials are usually MarkDuplicates, SortSam, SamToFastq, FastqToSam, FixMateInformation, BuildBamIndex, and repeated metrics commands. Use turbo-picard trial <PicardCommand> ... to print a side-by-side Picard and turbo-picard evaluation contract before changing a workflow.

When To Stay With Picard

• You need an option or command that is not inside the documented native scope and cannot use fallback.
• You require Picard-equivalent chart rendering rather than checked metrics text.
• You have not compared the exact command, input shape, sidecars, metrics, exit code, and error behavior your workflow depends on.
• You need broad cohort evidence before trying a representative shard.

Documentation

The full docs are on Read the Docs:

https://turbo-picard.readthedocs.io/en/latest/

Useful starting points:

• Quickstart
• Is this for you?
• Choose your first command
• Evaluation playbook
• Command coverage
• Picard alternatives
• Trying it in a pipeline
• Parity guide
• Fallback to Picard
• Benchmarks
• Citation
• Packaging
• Troubleshooting

Starter workflow files live in packaging/workflows/. The smallest trial shape is packaging/workflows/one-command-trial.md. Migration patterns that usually keep the surrounding workflow stable include per-read-group SamToFastq, sequential-shard FastqToSam, and mate-repair boundaries around FixMateInformation.

Benchmarks

The saved public benchmark suite compares native turbo-picard commands against Picard 3.4.0 and checks stable outputs before reporting speed. Current saved results report 32/32 parity checks passing, with 94.36x top speedup: UpdateVcfSequenceDictionary, 6.86x floor speedup: RevertSam, 26.72x median speedup, and 24.94x geometric mean speedup.

Summary: 32/32 PASS; 94.36x top speedup: UpdateVcfSequenceDictionary; 6.86x floor speedup: RevertSam; 26.72x median speedup; 24.94x geometric mean speedup.

Benchmark details, scope notes, real-data evidence, and reproduction commands are in the benchmark docs. The parity guide explains what the comparisons do and do not prove. For CollectBaseDistributionByCycle, CollectGcBiasMetrics, CollectInsertSizeMetrics, MeanQualityByCycle, and QualityScoreDistribution, metrics text is the parity target; chart outputs are lightweight PDF summaries, not Picard-equivalent rendered plots.

Saved benchmark run:

• Date: 2026-06-13
• Command: python3 tools/bench_suite.py --repeats 3 --skip-build
• Raw log: docs/site/assets/bench-suite-output.txt
• benchmark exceptions: AccelerationStatus, doctor, explain, and trial are utility commands, not Picard workload comparisons.

Release evidence checks:

python3 tools/update_real_data_manifest.py
python3 tools/verify_benchmark_log_evidence.py
python3 tools/verify_benchmark_suite_coverage.py
python3 tools/verify_benchmark_thresholds.py
python3 tools/verify_real_data_evidence.py
python3 tools/verify_real_data_evidence.py --release-ready

Real-data evidence lives in benchmarks/real-data/ and records pinned input sources, command scopes, and input SHA-256 hashes. Current release-candidate dataset IDs are gatk-na12878-mito, picard-snvq, and gatk-na12878-mito-cram.

Workflow evaluation

The project publishes a workflow validation protocol, a compatibility contract, and a production-scale benchmark format. Use these before changing a workflow. The opt-in Nextflow process candidate is documented under packaging/nf-core.

A command-level speedup is not a universal replacement claim. Keep upstream Picard available until representative BAM/CRAM evidence, output parity, failure behaviour, and independent review pass for the exact workflow.

Packaging Status

The live PyPI release is 0.1.9. It publishes Linux x86_64 and macOS Apple Silicon wheels plus a source distribution.

Bioconda recipes are tracked under packaging/bioconda/. The main package installs turbo-picard; the separate shim package installs the picard command only for environments that choose it.

Citation

Cite the archived turbo-picard release you used with CITATION.cff. Benchmark and validation inputs should be cited separately with immutable source URLs, commits or accessions, and input SHA-256 hashes.

Docs source lives in docs/. JOSS submission notes are tracked in docs/joss-submission.rst.

Contributing

Bug reports, parity evidence, documentation fixes, and small command-coverage improvements are welcome. Start with CONTRIBUTING.md and the development docs.

Support: SUPPORT.md. Security: SECURITY.md.