Turbo Picard

Picard workflows. Native speed.

Run selected Picard tools in Rust, using the command names and arguments your pipelines already understand. Accelerate a bottleneck, not a rewrite.

Turbo Picard is built for teams maintaining SAM/BAM/CRAM, VCF and sequencing-QC steps in Nextflow, WDL, Snakemake and shell workflows. Native commands avoid the JVM; the documented interface keeps migration local to the task you replace.

Familiar commands. Keep Picard command names and KEY=VALUE arguments. Inspectable results. Compare scientific outputs and retain an evidence bundle. Explicit execution. Distinguish native support from configured upstream fallback.

Start with one representative input. Native coverage is command- and option-specific; this is not the full upstream suite. Keep Picard for work outside the documented scope.

For coding agents and workflow generators, inspect the complete decision surface in one call:

turbo-picard capabilities --json

The schema-versioned response contains every Picard command's native/fallback status and trial fit together with the checked-in parity-gated benchmark evidence. Use turbo-picard trial --json <PicardCommand> ... for the exact task being considered. See the agentic-coder guide for the selection rule and safe substitution pattern.

Compact, native-only automation

Version 0.1.13 adds capabilities --json --command MarkDuplicates for compact discovery, executable argument arrays in trial JSON, and the strict TURBO_PICARD_REQUIRE_NATIVE=1 policy. See the agentic-coder guide. Inspection reports describe command scope, not proof that a particular input or option is validated.

Quick Start

Install from PyPI:

python3 -m pip install turbo-picard

For a containerized trial, use the published release image:

docker run --rm ghcr.io/dnncha/turbo-picard:0.1.13 --version

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 and print a trial contract before changing a workflow:

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

The trial command prints matching Picard and turbo-picard invocations, declared outputs, fallback state, and comparison notes. Then run the chosen command on a representative input:

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

Prove the switch on your data

The repository includes an evaluator that runs both implementations in separate output paths and records versions, timings and output digests. It does not upload your data. See the real-data evaluation guide for a copyable command and the interpretation of a match or mismatch.

The next-release evaluator uses disk-backed sorting for large comparisons, preserves existing evaluation directories, and retains failed runs for diagnosis. These repository-tooling improvements are not a claim about native command speed. It measures the comparison helper, not the native genomics commands.

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
• Agentic coder guide
• 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. If you run a real one-command evaluation, share the result through the trial report issue form; successful matches, mismatches, and adoption blockers are all useful evidence. If GitHub does not offer new-issue creation, add the same redacted report as a comment on the public trial report thread. From a repository checkout, tools/compare_real_data.py --shareable-report can create a reviewed, privacy-conscious starting point for that report.

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 272.12x top speedup: NormalizeFasta, 22.88x floor speedup: SetNmMdAndUqTags, 99.51x median speedup, and 84.52x geometric mean speedup.

Read these as small-fixture measurements, not whole-genome speedups. For example, the saved MarkDuplicates case used the generator's reads=50000 setting, with median wall times of 0.075464 seconds for Turbo Picard and 2.238986 seconds for Picard across three runs. Startup overhead matters at this scale. The reported speedup is the median of paired-run ratios, which need not equal the ratio of those independent medians. The machine-readable evidence now preserves timings, repeat counts and generator parameters alongside ratios.

Summary: 32/32 PASS; 272.12x top speedup: NormalizeFasta; 22.88x floor speedup: SetNmMdAndUqTags; 99.51x median speedup; 84.52x 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-08-14
• Command: python3 tools/bench_suite.py --repeats 3 --skip-build
• Raw log: docs/site/assets/bench-suite-output.txt
• benchmark exceptions: AccelerationStatus, capabilities, doctor, explain, and trial are utility commands, not Picard workload comparisons. CollectHsMetrics has separate ALL_READS and sidecar parity coverage, plus a real-data comparator path for pinned WES/capture intervals; representative capture-data performance evidence is still pending.

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 current source release is 0.1.13. Release builds target Linux x86_64 and ARM64, macOS Intel and Apple Silicon, plus a source distribution. Publication is gated on artifact validation and installation smoke tests; the release page and PyPI identify the published artifacts. The Linux ARM64 wheel is cross-built and artifact-validated.

Read the release notes for the release scope and evidence boundaries.

The submitted Bioconda recipe PR covers the main package and an optional shim. Use PyPI or the container image until Bioconda accepts the PR and the packages appear in its indexes. 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.