Skip to content
Welcome to the Beacon2 CBI Tools Documentation !

beacon2-cbi-tools

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.

Overview

beacon2-cbi-tools is a suite of tools originally developed as part of the ELIXIR–Beacon v2 Reference Implementation, now continuing under CNAG Biomedical Informatics. It provides essential functionality around the Beacon Friendly Format (BFF) data exchange format, including:

  • Validating XLSX/JSON files against Beacon v2 schemas
  • Converting VCF and microarray files into BFF (genomicVariations)
  • Loading BFF data (metadata and genomic variations) into MongoDB

This toolkit streamlines data preparation, validation, and ingestion for federated genomic and phenotypic data sharing under Beacon v2. The resulting BFF-formatted data can be used with any implementation of the Beacon v2 API specification that operates on MongoDB.

Tools Included

BFF-Tools script (bin/bff-tools):

A command-line tool for converting VCF data into BFF format and inserting the resulting BFF data into a MongoDB instance.

The tool offers five modes:

  1. vcf: Convert a VCF.gz file into BFF format.

  2. 🆕 tsv: Convert a SNP microarray file (e.g., from 23andme) into BFF format.

  3. load: Load BFF-formatted data into a MongoDB instance.

  4. full: Perform both TSV/VCF conversion and MongoDB loading.

  5. validate: Validate XLSX or JSON metadata against Beacon v2 schemas and serialize into BFF. An Excel template is provided to help structure your metadata.

Utility Suite:

A collection of support tools to aid in data ingestion. Key among them:

  • BFF-Browser:

    A web application for interactive visualization of BFF data, particularly genomicVariations and individuals.

  • BFF-Portal:

    A simple API and web application to query BFF data via MongoDB.

CINECA Synthetic Cohort - EUROPE_UK1:

A synthetic dataset for testing and demonstration purposes.

System Diagram

            * Beacon v2 - CBI Tools *

                ___________
          XLSX  |          |
           or   | Metadata | (incl. Phenotypic data)
          JSON  |__________|
_________            |
|       |            |
|  TSV  |            | bff-tools validate
|______ |            |
    |                |                                    Beacon v2
    | bff-tools tsv  |
____v____        ____v____            __________          ______
|       |        |       |            |          |        |     | <---- Request
|  VCF  | -----> |  BFF  | ---------> | Database | <----> | API |
|_______|        |_ _____|            |__________|        |_____| ----> Response
                     |                  MongoDB
     bff-tools vcf   |   bff-tools load
                     |
                     |
                  Optional (utils)
                     |
                _____v_____
                |         |
                | utils/  |
                |  bff-   |
                | browser | Visualization
                | (beta)  |
                |_________|

-----------------------------------------------|||---------------------------
beacon2-cbi-tools                                     e.g. beacon2-ri-api
                                                           beacon2-pi-api
                                                           java-beacon-v2.api
                                                           ...