RFC: GeneBe Client interaction with GeneBe Hub

[pstawinski]

Introduction

GeneBe Client can be used for:

• Pulling from the GeneBe Hub and applying variant annotations to your VCF file.
• Creating new variant annotations and publishing them to the Hub.
• Other operations like renaming, exporting/importing to and from a tar file, and dumping to other formats like csv.

This is the main point of interaction with the GeneBe Hub.
The current GeneBe Client is written in Java, so it can be used on Windows, Linux, and macOS as long as the user has Java 21 (or newer) installed. In the near future, we plan to add pull functionality to pygenebe, the Python GeneBe client. This will enable easy integration of GeneBe databases with variant processing in Pandas.

The client has two operating modes: standard and interactive. You can run it as:

java -jar GeneBeClient.jar

to get an interactive shell, or execute a command directly:

java -jar GeneBeClient.jar annotation pull --id @genebe/clinvar:0.0.1-20250115

Every command has built-in help; simply call the command with the --help argument. You can also use tab completion to explore available commands.

---

Main Commands

The main command is used to annotate your VCF file:

java -jar GeneBeClient.jar vcf annotate --input-vcf sample.vcf \
    --annotations @genebe/ccrs_hg38:0.0.1 @genebe/clinvar:0.0.1-20250115 @genebe/gnomad-exomes-depth:0.0.1-4.1.0 \
    --output-vcf /tmp/output.vcf.gz \
    --output-tsv /tmp/output.tsv \
    --omit-base-annotation true

---

Problems

Steps

The annotate command presented above actually does three things:

1. Parses the VCF file.
2. Annotates it:
   1. Downloads databases if needed.
   2. Uploads data for remote annotation unless --omit-base-annotation true is used.
3. Saves the result to VCF and TSV files.

If we split this command into three separate commands, we could gain the ability to annotate any input file (e.g., JSON or TSV instead of just VCF) and write to any format as well.

Special Arguments

It may also be useful to have the ability to pass special arguments to annotators, for example, to change the applied suffix or disable certain columns. We could, for example, use:

@genebe/ccrs_hg38:0.0.1?suffix=ccrs&columns=score

to provide the annotator with two arguments: suffix=ccrs and columns=score. This is not yet implemented but seems necessary.

Remote Annotations

Some annotators are so complex that it's not feasible to run them locally—for example, applying ACMG automatic scores in GeneBe. This is why I believe a "remote annotator" feature is needed, where variant information is sent to a remote server, processed, and then returned for annotation.

A draft of this solution is already in place: if you don't include --omit-base-annotation true in your command, the GeneBe server is queried for ACMG classifications and other "base" annotations. This approach might also benefit users who want to apply dynamically computed annotations (e.g., SpliceAI) to their variants without running the computations locally.

Position Annotations

For SNVs, applying position annotations is straightforward. However, it becomes more challenging for MNVs, where we may need to retrieve data for all reference positions and apply an aggregation function. The same applies to deletions.

Insertions present a unique challenge: which position should be used? A deletion has both a left and right neighbor, and we probably shouldn't introduce any bias. We could apply an aggregation to both flanking positions, which works well for databases like GnomAD depth or conservation scores. This is the approach currently used in GeneBe Client. However, it is significantly slower and more computationally intensive than simply applying a value from the database that matches the pos, raising the question of whether the additional cost is justified.

Another question is which aggregation method should be applied. The current implementation uses ANY_VALUE, but we are considering allowing database authors to specify the aggregation method for each column in POSITION and RANGE databases when creating their datasets.

---

Try It Yourself

We encourage you to try GeneBe Client in action! Just follow the GeneBe Hub Getting Started Guide to download the client and annotations, and experiment with annotating a VCF file.

---

Call for Feedback

This is an early draft of the client. We welcome feedback, suggestions, and concerns before moving the implementation from alpha to beta. 😊

[pstawinski]

First Round of the RFC is Over – Thank You!

The first round of the RFC has officially concluded. A huge thank you to everyone who shared their ideas via private messages! Your input has been greatly appreciated.

While this round is over, the discussion remains open—if you still have suggestions, feel free to send them.

A summary of the first round will be shared soon. Stay tuned!