Add support for annotating tabular files (including BED)

[jdidion]

This PR adds tab and bed features (enabled by default).

The tab feature supports reading a generic tab file with the first four columns being chrom, pos (1-based), ref, alt.

The bed feature pulls in noodles-bed dependency and uses it for BED file reading/writing. The user can optionally specify the indices of the ref and alt columns (if any), otherwise separate output records are written for each alt allele of each multi-allelic variant. A header comment line is added to the output with the column names.

Note this is stacked on jdidion:arm-support-stream-vbyte-scalar.

[gemini-code-assist]

Summary of Changes

Hello @jdidion, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly extends the echtvar tool's annotation capabilities by introducing native support for BED files. It enables users to annotate genomic regions defined in BED format with data from echtvar files, offering both allele-specific and position-based annotation modes. The changes involve integrating new dependencies, developing a dedicated BED annotation module, and refining core variant handling logic to support this new input type, all while maintaining performance through conditional compilation and optimized data processing.

Highlights

• BED File Annotation Support: Introduced a new bed feature, enabled by default, which allows for annotating BED files using the noodles-bed dependency. This feature adds a new bed_annotate_cmd module to handle the specific logic for BED file processing.
• Flexible Allele Handling: The BED annotation command supports both allele-specific annotation (when ref-col and alt-col are provided) and position-scan annotation for multi-allelic variants, ensuring comprehensive coverage.
• Conditional Compilation for Performance and Modularity: Implemented conditional compilation (#[cfg(feature = "bed")]) for BED-related code, ensuring that the noodles dependency and BED annotation logic are only included when the bed feature is active. Additionally, stream-vbyte encoding/decoding now uses platform-specific SIMD features (SSSE3/SSE41 for x86_64) or scalar fallback for other architectures.
• Enhanced Variant Decoding: Added new utility functions (decode_var in kmer16.rs and decode_to_alleles in var32.rs) to efficiently decode reference and alternate alleles from encoded variant data, which is crucial for the new BED annotation functionality.
• Updated CLI for Annotation Command: The anno subcommand now includes new arguments: --format to specify input type (auto, vcf, or bed), --ref-col, and --alt-col for allele-specific BED annotation, and a unified INPUT and OUTPUT argument for flexibility.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• Cargo.toml
  • Added a new bed feature, enabled by default, which pulls in the noodles dependency with its bed feature.
  • Updated stream-vbyte dependency to conditionally enable x86_ssse3 and x86_sse41 features only for x86_64 targets, falling back to scalar for others.
  • Added flate2 dependency for handling compressed BED files.
• src/commands/bed_annotate_cmd.rs
  • Added a new module bed_annotate_cmd containing the bed_annotate_main function, which implements the core logic for annotating BED files.
  • Defined BedVariant struct and its Variant trait implementation for BED-specific variant representation.
  • Implemented logic for reading BED input, handling headers, and writing annotated output, supporting both allele-specific and position-scan annotation modes.
  • Integrated fasteval for expression evaluation and flate2 for GZipped input/output.
• src/commands/encoder_cmd.rs
  • Modified stream-vbyte encoder usage to dynamically select Sse41 for x86_64 architectures and Scalar for others, improving cross-platform compatibility.
• src/commands/mod.rs
  • Conditionally added the bed_annotate_cmd module, ensuring it's only compiled when the bed feature is enabled.
• src/lib/echtvar.rs
  • Modified stream-vbyte decoder usage to dynamically select Ssse3 for x86_64 architectures and Scalar for others.
  • Added set_position_by_name function to efficiently navigate to a specific chromosomal position.
  • Implemented variants_at_position function to retrieve all unique variants at a given genomic position from echtvar data.
• src/lib/kmer16.rs
  • Added RLOOKUP constant for reverse lookup of base codes.
  • Implemented decode_var function to convert encoded kmer16 sequences back into reference and alternate alleles.
  • Added new unit tests for decode_var to ensure correct round-trip encoding and decoding for various allele lengths.
• src/lib/var32.rs
  • Implemented decode_to_alleles function to decode var32 encoded variants into reference and alternate alleles.
  • Added new unit tests for decode_to_alleles, covering round-trip, SNV, and sentinel cases.
• src/main.rs
  • Added detect_format function to automatically determine input file format (VCF or BED) based on extension or explicit override.
  • Updated the anno subcommand's CLI arguments to include --format, --ref-col, --alt-col, and unified INPUT/OUTPUT paths.
  • Integrated bed_annotate_cmd::bed_annotate_main into the anno subcommand's dispatch logic, conditionally compiling it based on the bed feature.
  • Added validation for --ref-col and --alt-col arguments, ensuring they are used correctly with BED input.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds support for annotating BED files, introducing a new bed feature and a corresponding annotation command. The changes are well-structured, including making the stream-vbyte dependency portable across architectures. I've identified a critical issue with argument parsing that could lead to a panic, a high-severity issue with error handling on file parsing, and several medium-severity opportunities for performance and code clarity improvements. Overall, this is a great addition, and with these changes, it will be even more robust and efficient.

[brentp]

I'd also want some update to the README and some end-to-end tests for this. It's a big change and I haven't scrutinized it completely.

[brentp]

so if it's not bed, we assume 1-based start?

[jdidion]

Yes - the assumption for the "generic" tab-delimited format is that the first four columns are chromosome, position (1-based), ref, alt.

Another option would be to only assume the first two columns are chromosome, position. If it is bed format, then we also assume the position is 0-based and the third column is end position, otherwise the position is 1-based. Rather than assuming the ref and alt columns, we could always require the user to specify them with the --ref-col and --alt-col options. I guess if it's not a bed file and the ref and alt columns aren't specified, you just treat every variant as length 1.

[brentp]

Hi @jdidion sorry for letting this sit for so long. Have you been using this without problems for a while? Still interested in getting it merged?

[jdidion]

Yes! Working well for me so far. Thanks! Lmk if you see any improvements/fixes you’d like before merging.

…

On Apr 30, 2026, at 8:02 AM, Brent Pedersen ***@***.***> wrote: brentp left a comment (brentp/echtvar#54) <#54 (comment)> Hi @jdidion <https://github.com/jdidion> sorry for letting this sit for so long. Have you been using this without problems for a while? Still interested in getting it merged? — Reply to this email directly, view it on GitHub <#54 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAA6XHW53WLOBX7AL7SR7UD4YNTIPAVCNFSM6AAAAACVJXG2F2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DGNJTGU4DIMJTGM>. You are receiving this because you were mentioned.