Bundle v1

CBIcall production workflows require a CBIcall-provided bundle containing third-party executables, reference genomes, known-sites files, interval lists, and auxiliary databases.

The current bundle is selected in the run YAML with:

resource: "cbicall-germline-resources-v1"

CBIcall resolves this key against the resource catalog, the JSON inventory of resource entries and their compatibility metadata:

resources/cbicall-resource-catalog.json

The resource catalog can contain different resource types. This page documents the current bundle type and the CBIcall-provided bundle used by the packaged workflows.

The scripts/download_cbicall_bundle.py utility installs CBIcall bundle entries from the resource catalog. It uses the local catalog when available and otherwise retrieves the canonical catalog. It does not install arbitrary local or third-party resource layouts.

Bundle Identity

Field	Value
Resource key	cbicall-germline-resources-v1
Version	v1

Why this is explicit

The resource key is the identifier users select with resource. log.json records this key, the resource version, and a catalog fingerprint, so two runs can be checked for the same declared external dependency set.

Bundle Scope

This bundle supplies the external tools and reference data used by the cbicall-core workflows. See the canonical compatibility matrix for supported pipelines, modes, software stacks, and backends.

CBIcall checks compatibility using the exact versioned workflow keys declared in the resource catalog, for example nextflow/wgs/cohort/gatk-4.6/v1. External nf-core workflows manage their own dependencies and do not use this bundle.

Downloaded Files

The production bundle is distributed as a small identifier JSON, split archive parts, and a checksum file.

File	Purpose
cbicall-resource-id.json	Declares the resource key and is pinned by SHA-256 in the catalog.
data.tar.gz.md5	MD5 checksum file. The current bundle records the split archive parts.
data.tar.gz.part-00	Split archive part.
data.tar.gz.part-01	Split archive part.
data.tar.gz.part-02	Split archive part.
data.tar.gz.part-03	Split archive part.
data.tar.gz.part-04	Split archive part.
data.tar.gz.part-05	Split archive part.

The setup utility verifies the files covered by data.tar.gz.md5. For the current bundle, this means the split archive parts are checked before they are reassembled and extracted.

An optional small remote identifier file can also be used:

{"resource_key": "cbicall-germline-resources-v1"}

When available, this file is named cbicall-resource-id.json. Its SHA-256 can be pinned in the local catalog to confirm that the remote bundle declares the expected resource key.

Expected Layout

After extraction, DATADIR should contain:

DATADIR/
  Databases/
  NGSutils/

The bundle layout uses these conventional top-level names:

Variable	Meaning
CBICALL_DATA	User-facing environment variable that selects the installed bundle root for all native backends.
DATADIR	Root of the installed CBIcall-provided bundle.
DBDIR	DATADIR/Databases
NGSUTILS	DATADIR/NGSutils

CBIcall resolves CBICALL_DATA into the backend-specific DATADIR/datadir value. Workflow files such as Bash env.sh and Snakemake/Nextflow/Cromwell config.yaml then resolve the bundle layout into concrete executable and reference paths. Packaged workflow files should not be edited to select an installation directory.

Tools

Tool	Version	Path hint
GATK 4	4.6.2.0	NGSutils/gatk/gatk-4.6.2.0/gatk
BWA	0.7.18	NGSutils/bwa-0.7.18/bwa
Samtools	0.1.19	NGSutils/samtools-0.1.19/samtools

note

Some workflow branches may use architecture-specific executable paths or legacy tool paths. The catalog records the intended bundle identity; the workflow logs and log.json record the concrete paths resolved during a run.

When a bundled executable is incompatible

The bundle includes precompiled executables for both amd64 and arm64 architectures. These binaries should work on most common Linux distributions, such as Ubuntu and CentOS, but compatibility with every Linux environment cannot be guaranteed.

In some environments, precompiled executables for external dependencies such as BWA or Samtools may fail to run because of missing or incompatible shared libraries (.so files) or other system-level dependencies.

If a bundled executable is incompatible with the target system, we recommend rebuilding the same pinned tool version from source in a separate, site-specific directory. Before using the rebuilt executable in production, run a small smoke test and, if successful, select it in the institutional runtime profile.

It is also possible to use a different tool version available on the system—for example, on an HPC cluster via module load foo.new. However, using versions other than those pinned by the bundle may affect reproducibility. In that case, we cannot guarantee that the integration tests will produce exactly the same results across different machines or environments.

For example, during the CNAG migration from CentOS to AlmaLinux, the WES contract continued to pass when upstream processing used BWA 0.7.19 and Samtools 1.22.1. However, the downstream mtDNA test produced 1,106 prioritized records and 711 filtered JSON records, compared with the reference values of 1,119 and 716, respectively.

Rebuilding and selecting the pinned BWA 0.7.18 and Samtools 0.1.19/1.3 versions restored the reference outputs, including both expected hashes.

Reference Resources

b37

Resource	Path hint
Reference FASTA	Databases/GATK_bundle/b37/references_b37_Homo_sapiens_assembly19.fasta
dbSNP	Databases/dbSNP/human_9606_b144_GRCh37p13/All_20160408.vcf.gz
Mills / 1000G INDELs	Databases/GATK_bundle/b37/b37_Mills_and_1000G_gold_standard.indels.b37.vcf.gz

hg38

Resource	Path hint
Reference FASTA	Databases/GATK_bundle/hg38/resources_broad_hg38_v0_Homo_sapiens_assembly38.fasta

rsrs / mtDNA

The mtDNA workflows use MToolBox-related mitochondrial files from the bundle.

Provenance in Runs

The selected resource bundle is stored in log.json under config.resources.bundle.

Example:

{
  "key": "cbicall-germline-resources-v1",
  "compatible": true,
  "fingerprint": "..."
}

Two runs used the same declared external dependency set when their config.resources.bundle.fingerprint values match.

Installation Manifest

The setup utility also writes:

cbicall-resource-installation.json

This local manifest records the installed resource key, archive checksum result, source files, extraction status, and optional remote identifier provenance.

Runtime Check

Before launching a native workflow, CBIcall resolves the bundle directory from CBICALL_DATA. If the variable is unset, the selected institutional profile or backend configuration provides the fallback. CBIcall passes the resolved value to Bash, Snakemake, Nextflow, or Cromwell without modifying packaged files.

If bundle metadata exists beside DATADIR, CBIcall validates it:

File	Runtime check
cbicall-resource-id.json	Resource key must match the selected resource; SHA-256 must match the catalog when pinned.
cbicall-resource-installation.json	Installed resource key must match the selected resource; the manifest catalog entry must match the local catalog fingerprint.

This check is intentionally small. It validates the installed bundle identity without hashing the full resource archive on every run.