Skip to main content

Quick Start

This page shows the shortest path for testing bff-tools after installation with bundled files.

Use this page when you want to confirm that the runtime works. Use What Should I Run? when you are deciding which mode matches your own data.

Assumptions​

This page assumes you are running commands from the repository root or from a container where the repository is available at the current working directory. If you installed with Docker or Apptainer, open the runtime shell first and then run the commands below.

If you have not installed the toolkit yet, start with one of these pages:

Research-use disclaimer

This toolkit is intended for research use. Do not use generated annotations or results for medical decisions.

1. Check the command​

bin/bff-tools --help

Expected result: the command prints available modes such as validate, vcf, tsv, load, and full.

2. Validate metadata​

mkdir bff_out
bin/bff-tools validate -i utils/bff_validator/Beacon-v2-Models_template.xlsx --out-dir bff_out

This validates metadata and writes BFF JSON collections to bff_out.

Expected result: JSON collections such as individuals.json, biosamples.json, runs.json, and datasets.json.

3. Convert genomic data​

VCF input​

bin/bff-tools vcf -i testdata/vcf/test_1000G.vcf.gz -p testdata/vcf/param.yaml

SNP-array TSV input​

bin/bff-tools tsv -i testdata/tsv/input.txt.gz -p testdata/tsv/param.yaml

Use vcf for VCF or VCF.gz input. Use tsv for SNP-array style TSV or TXT input.

Expected result: a run-specific directory containing generated genomic variation output, usually under beacon_*/vcf/ or beacon_*/tsv/.

4. Load into MongoDB​

Once you have BFF metadata plus genomic variations and MongoDB is configured, load them with:

bin/bff-tools load -p param.yaml

If you want conversion plus loading in one step, use:

bin/bff-tools full -i input.vcf.gz -p param.yaml

Expected result: BFF collections are inserted into MongoDB and indexes are created or updated.

Next steps​

  • If you are not sure which mode matches your data, see What should I run?.
  • To understand generated files and logs, see Outputs.
  • For the full workflow, continue to the tutorial.
  • For installation details, go back to the installation overview.
  • For troubleshooting and edge cases, see the FAQ.