Skip to main content

Worked Examples

The runnable inputs, parameter file, and HPC example are kept in the repository's examples/ directory.

GRCh38 / hg38​

The repository includes test_1000G_hg38.vcf.gz, a compact, multisample 1000 Genomes-derived input. It uses GRCh38 coordinates with UCSC-style chr22 contigs.

Run the Included Input​

Prepare the external annotation data and update ../bin/config.yaml, then run from examples/:

../bin/bff-tools vcf \
  -i test_1000G_hg38.vcf.gz \
  -p param_hg38.yaml \
  -c ../bin/config.yaml \
  -o example-hg38

param_hg38.yaml selects hg38 and enables annotation. The pipeline normalizes the VCF and applies SnpEff, dbNSFP, ClinVar, and COSMIC before conversion.

The primary result is:

example-hg38/vcf/genomicVariationsVcf.json.gz

Validate it and optionally generate the standalone report:

../bin/bff-tools validate \
  -i example-hg38/vcf/genomicVariationsVcf.json.gz --gv-vcf

../bin/bff-tools vcf \
  -i test_1000G_hg38.vcf.gz \
  -p param_hg38.yaml \
  -c ../bin/config.yaml \
  --browser \
  -o example-hg38-browser

Run directories are not overwritten. Use a new -o value for each attempt.

Recreate the Input Subset​

The source is the 2,504-sample chromosome 22 GRCh38 callset from the 1000 Genomes Project. One maintained mirror is the UCSC 1000 Genomes directory.

Download and index the chromosome file:

wget https://hgdownload.soe.ucsc.edu/gbdb/hg38/1000Genomes/ALL.chr22.shapeit2_integrated_snvindels_v2a_27022019.GRCh38.phased.vcf.gz

bcftools index -t \
  ALL.chr22.shapeit2_integrated_snvindels_v2a_27022019.GRCh38.phased.vcf.gz

The source records use contig 22, while the configured hg38 resources use chr22. Subset the original coordinates and rename the contig with bcftools:

printf '22\tchr22\n' > rename-chrs.txt

bcftools view \
  -r 22:10516173-11016173 \
  -Ou \
  ALL.chr22.shapeit2_integrated_snvindels_v2a_27022019.GRCh38.phased.vcf.gz \
  | bcftools annotate --rename-chrs rename-chrs.txt \
      -Oz -o test_1000G_hg38.vcf.gz

bcftools index -t test_1000G_hg38.vcf.gz

This is a contig-name normalization within the same GRCh38 coordinate system. It is not a liftover. Preserve the source URL, checksum, region, rename map, and commands with any regenerated fixture.

Use Existing Compatible Annotations​

To skip re-annotation, the VCF must already contain a compatible SnpEff ANN header and annotations:

../bin/bff-tools vcf \
  -i cohort.hg38.annotated.vcf.gz \
  --genome hg38 \
  --dataset-id cohort-1 \
  --no-annotate \
  -o cohort-hg38-bff

dbNSFP and ClinVar fields remain strongly recommended for complete BFF output.

GRCh37 / hs37​

The compact GRCh37 integration fixture and versioned reference output are under src/bff_tools/integration_assets. Use hs37 for hs37d5-style contigs such as 22; use hg19 only with matching hg19 coordinates, contigs, FASTA, and annotation resources.

The full CINECA chromosome 22 release fixture is also GRCh37/hs37d5. Its raw VCF, tabix index, and versioned BFF reference output are available from the public CINECA_synthetic_cohort_EUROPE_UK1/vcf folder.

Metadata​

The populated CINECA synthetic cohort is the real-world metadata example. It accompanies the packaged workbook template and serves as the 10,018-record validator parity fixture.

Full VCF release acceptance uses the external CINECA chromosome 22 data with 2,504 samples. Those files are not committed to Git or included in the PyPI package.