CBIcall: a configuration-driven framework for variant calling in large sequencing cohorts

CBIcall is an open-source, configuration-driven framework that ensures reproducible and standardized variant calling across diverse computing environments by validating parameters and dispatching workflows via a single YAML file, as demonstrated in large-scale cohort analyses like the EU HEREDITARY project.

The Gist

Imagine you are trying to bake the exact same cake in 50 different kitchens around the world. You have the same recipe, but one kitchen has a gas oven, another has an electric one, one uses metric cups, and another uses imperial cups. Even if you follow the recipe perfectly, the cakes might end up tasting slightly different.

In the world of genetics, scientists are trying to do the same thing: analyze DNA from thousands of people across different hospitals and research centers to find the causes of diseases. But instead of ovens and cups, they have different computers, different software versions, and different rules. This makes it hard to get consistent results, which is dangerous when trying to cure diseases.

Enter CBIcall: The "Universal Recipe Manager"

The paper introduces a new tool called CBIcall (Configuration-Driven Framework for Variant Calling). Think of CBIcall not as a new oven, but as a super-smart project manager that sits between the scientists and their computers.

Here is how it works, using simple analogies:

1. The Problem: The "Tower of Babel" of Science

Currently, if a scientist in Spain wants to analyze DNA, they might use a specific set of computer instructions. If a scientist in France wants to do the exact same analysis, their computer might speak a slightly different "language" (different software versions or operating systems). When they try to compare their results, the data doesn't match up perfectly. It's like trying to compare a cake measured in grams with one measured in ounces without a conversion chart.

2. The Solution: The "Single Source of Truth" (The YAML File)

CBIcall solves this by using a single configuration file (called a YAML file).

• The Analogy: Imagine a master blueprint. Instead of telling every kitchen exactly how to turn on their specific stove, you just hand them this one blueprint that says, "Make a chocolate cake."
• How it works: The scientist fills out this simple file with their goals (e.g., "Analyze these 1,000 DNA samples"). CBIcall reads this file and automatically checks: "Okay, does your computer have the right tools? Are the software versions compatible? Is the recipe valid?"

3. The "Traffic Cop" (Validation)

Before CBIcall lets the analysis start, it acts like a strict traffic cop.

• It checks if the tools you want to use actually work together.
• It ensures that the "recipe" (the pipeline) is compatible with your computer's "kitchen" (the operating system).
• If something is wrong, it stops you before you waste time baking a bad cake. This prevents "workflow divergence," which is just a fancy way of saying "making sure everyone ends up with the same result."

4. The "Universal Translator" (Backends)

CBIcall is "workflow-agnostic," which is a fancy way of saying it doesn't care what kind of computer engine you use.

• The Analogy: Whether your kitchen uses a gas stove (Bash) or an induction cooktop (Snakemake), CBIcall translates the master blueprint into instructions that that specific stove understands.
• It can run the same DNA analysis on a massive supercomputer in a hospital or a smaller server in a university, and it will produce the exact same result.

5. The "Black Box" Recorder (Provenance)

Every time CBIcall runs an analysis, it keeps a detailed logbook (a JSON file).

• The Analogy: It's like a flight recorder on a plane. If the cake tastes weird later, you can look at the logbook and see exactly which oven was used, what temperature it was set to, and who flipped the switch. This makes the science reproducible. Anyone can look at the log and say, "Ah, I see exactly how they got this result."

The Real-World Test: The "Big Cake Bake"

The authors tested CBIcall on a massive project called HEREDITARY.

• They took DNA from 1,111 people (some with Parkinson's disease, some without) from different sources.
• They ran the analysis through CBIcall on a supercomputer.
• The Result: It worked perfectly. They were able to compare the DNA of the sick patients with the healthy controls without any "noise" caused by different computer systems. They found that the tool could handle both nuclear DNA (the main instruction manual) and mitochondrial DNA (the tiny battery pack inside our cells) with ease.

Why Does This Matter?

In the past, if two hospitals wanted to collaborate on a genetic study, they might spend months just trying to make their computers talk to each other. With CBIcall, they can just load the "Universal Blueprint," hit "Go," and get reliable, comparable results immediately.

In short: CBIcall is the standardized operating system for genetic research. It ensures that when scientists around the world study DNA, they are all speaking the same language, using the same rules, and getting results they can trust to save lives.

Technical Summary

1. Problem Statement

The paper addresses the critical challenge of deploying standardized, reproducible variant-calling pipelines across heterogeneous computing environments in large-scale, collaborative genomic studies (e.g., federated analysis models).

• Context: Large-scale projects often require institutions to process sensitive data locally due to legal and ethical constraints.
• The Bottleneck: While many robust workflow templates exist, deploying them across different High-Performance Computing (HPC) centers is difficult due to:
  • Heterogeneous software stacks and computing policies.
  • Lack of a standardized validation layer to enforce configuration correctness and tool compatibility.
  • The need for site-specific manual wrappers, which leads to workflow divergence and inconsistent results.
• Goal: To create a framework that ensures identical, validated pipelines run "out of the box" across diverse environments without compromising reproducibility.

2. Methodology: The CBIcall Framework

CBIcall is a workflow-agnostic, configuration-driven framework designed to sit above existing workflow engines (Bash and Snakemake). It does not replace these engines but provides a validation and execution layer.

Core Architecture

• Two-Layer Configuration Model:
  1. User Parameters YAML: Defines analysis intent (input samples, pipeline selection, genome build, tool parameters).
  2. Workflow Registry YAML: Maps pipeline definitions to executable scripts (Bash or Snakemake) and references shared components.
  • Benefit: Separating these layers minimizes configuration drift and prevents divergence between runs.
• Execution Driver (Python 3):
  • Acts as the central controller.
  • Validation: Loads user YAML and validates inputs against controlled vocabularies. It enforces strict compatibility rules regarding analysis modes, genome builds, workflow backends, and specific tool versions (e.g., GATK 3.5 vs. 4.6).
  • Schema Validation: Uses JSON Schema Draft 2020-12 to validate workflow definitions.
  • Provenance: Records structured metadata (software versions, parameters, runtime context, task-level provenance) into a log.json file for auditing and reproducible reanalysis.
• Supported Backends:
  • Bash: Includes ready-to-use pipelines for Whole-Exome Sequencing (WES), Whole-Genome Sequencing (WGS), and mitochondrial DNA (mtDNA).
  • Snakemake: Provides a validated reference implementation for WES/WGS (GATK 4.6) and allows integration of external workflows (e.g., from WorkflowHub or Dockstore) via the registry.
• Portability:
  • Distributed as a container image (Docker/Apptainer/Singularity) containing the framework and Python dependencies.
  • External resources (reference genomes, databases, third-party tools like GATK/BWA-MEM) are mounted separately, ensuring the core framework remains lightweight and adaptable to HPC constraints.

Validated Pipelines

• Nuclear Germline (WES/WGS): Follows GATK Best Practices.
  • Legacy: GATK 3.5 (for b37/hg19 compatibility).
  • Current: GATK 4.6.
  • Workflow: Alignment (BWA-MEM) $\rightarrow$ Sorting/Duplicate Marking $\rightarrow$ Base Quality Recalibration $\rightarrow$ gVCF generation (HaplotypeCaller) $\rightarrow$ Joint Genotyping (GenotypeGVCFs) $\rightarrow$ Variant Quality Score Recalibration (VQSR).
• Mitochondrial DNA (mtDNA): Uses MToolBox (GATK 3.5) for variant calling, producing VCFs, prioritized annotations, and interactive HTML reports.

3. Key Contributions

1. Configuration-Driven Execution: Shifts the burden of pipeline management from manual scripting to a single YAML configuration file, ensuring consistency across sites.
2. Strict Compatibility Enforcement: Automatically validates that tool versions, genome builds, and analysis modes are compatible before execution, preventing runtime errors and subtle result variations.
3. Structured Provenance: Automatically generates detailed JSON logs for every run, facilitating audit trails and reproducible science.
4. Extensibility: The architecture supports multiple workflow engines (Bash, Snakemake) and is designed to integrate others (e.g., Nextflow) without altering the core execution logic.
5. Production-Ready Pipelines: Provides fully validated pipelines for WES, WGS, and mtDNA analysis that adhere to GATK Best Practices.

4. Results and Validation

The framework was validated using real-world data from the EU HEREDITARY project and public datasets.

• Dataset: A cohort of 1,111 samples processed on an institutional HPC system.
  • 608 WES samples from the NINDS Parkinson's Disease study (dbGaP).
  • 503 control samples from the 1000 Genomes Project (WGS/WES mix).
• Use Case 1: Nuclear Variant Calling (WES)
  • Comparison: Compared Single-Sample Mode (individual gVCFs merged via bcftools) vs. Cohort-Joint Genotyping Mode (joint genotyping via GATK GenotypeGVCFs).
  • Findings: The joint-genotyping approach retained more variants that were filtered out in the single-sample merged approach, confirming the expected statistical advantages of cohort-level analysis.
  • Quality Control: Principal Component Analysis (PCA) and variant count distributions showed no systematic batch effects or population stratification between the two source cohorts, confirming the pipeline's ability to harmonize data.
• Use Case 2: Mitochondrial Variant Calling
  • Performance: Successfully called variants in ~95% of samples.
  • Coverage: WES data provided sufficient off-target mtDNA coverage for the vast majority of samples.
  • Analysis: Heteroplasmic variants (fraction > 0.3) were analyzed. The distribution of variants across loci was consistent between cases and controls, and the number of variants correlated with locus size, matching expected biological patterns.

5. Significance

• Reproducibility in Federated Studies: CBIcall solves the "deployment gap" in federated genomic studies, allowing different institutions to run identical, validated pipelines on local HPC clusters without manual intervention.
• Scalability: Successfully demonstrated processing of over 1,000 samples, proving its suitability for large-scale cohort analyses.
• Standardization: By enforcing strict configuration rules and recording provenance, it reduces the risk of workflow divergence, a major barrier in multi-center research.
• Open Source: The tool is open-source (GPLv3) and includes documentation for dependency management, making it accessible to the broader bioinformatics community.

In summary, CBIcall is a robust middleware solution that bridges the gap between complex workflow engines and the practical needs of large-scale, multi-institutional genomic research, ensuring that results are consistent, reproducible, and scientifically rigorous regardless of the underlying computing infrastructure.