Beacon v2 CBI Tools Documentation

beacon2-cbi-tools helps you prepare data for Beacon v2 deployments based on the Beacon Friendly Format (BFF).

With this toolkit you can:

• validate metadata from XLSX or JSON files against Beacon v2 schemas
• convert VCF or SNP-array TSV input into BFF genomicVariations
• load BFF collections into MongoDB
• optionally inspect the resulting data with lightweight utilities

Genetic Data Interpretation Disclaimer

This tool provides research-based annotations of genetic data from SNP microarray formats (e.g., 23andMe) and VCF (Variant Call Format) files. It is intended for research use only and is not a medical device. It does not provide medical or clinical advice.

• 🩺 Do not use results for medical decisions. Always consult a qualified healthcare professional.
• 😰 Results may cause emotional or psychological distress. You may learn about increased risks for serious health conditions.
• 🔬 Genetic data and interpretations have limitations. Not all variants are covered, and scientific understanding continues to evolve.
• 🔐 You are responsible for safeguarding your genetic data. Use caution when storing or sharing results; privacy or legal implications may apply.
• ⚡ Use at your own risk. The authors assume no responsibility for how the results are interpreted or used.

By using this tool, you confirm that you understand and accept these terms.

Typical workflow

Most users follow this sequence:

1. Prepare and validate metadata with bff-tools validate.
2. Convert genomic data with bff-tools vcf or bff-tools tsv.
3. Load the generated BFF collections into MongoDB with bff-tools load or bff-tools full.

Choose your path

I want to install the toolkit

• Docker installation
• Apptainer installation
• Non-containerized installation

I want the fastest way to try it

• Quick Start

I want the full end-to-end explanation

• Tutorial: data beaconization

I want examples or troubleshooting help

• Examples
• FAQ

Main commands

The main entry point is bff-tools.

• bff-tools validate: validate metadata and write BFF JSON collections
• bff-tools vcf: convert a VCF or VCF.gz file into BFF
• bff-tools tsv: convert a SNP-array TSV file into BFF
• bff-tools load: load BFF collections into MongoDB
• bff-tools full: run conversion plus loading in one step

Utilities

The toolkit also includes optional utilities for browsing or queueing jobs:

• bff-browser: browse static BFF files without a database
• bff-portal: query BFF data stored in MongoDB
• bff-queue: run and monitor many ingestion jobs on a workstation

Project background

This project was originally developed as part of the Beacon v2 Reference Implementation and is now maintained as beacon2-cbi-tools by CNAG Biomedical Informatics.