Annotate a VCF

Annotate a VCF and download it back

Upload a VCF, wait for VariantGrid to import + annotate any novel variants, then download the cohort-level annotated export (all samples, single-sample VCFs included).

The quick way

The whole flow is a one-liner with annotate_vcf():

from variantgrid_api.api_client import VariantGridAPI

api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")

# export_type is "vcf" (gzipped *.vcf.gz) or "csv" (zipped *.csv.zip)
path = api.annotate_vcf("input.vcf", export_type="vcf", dest_path="/data/results/")
print(f"Annotated VCF written to {path}")

Drive each step yourself

annotate_vcf() just chains upload → wait → download. Do it by hand when you want control over each step:

# For ad-hoc uploads pass path=None so the upload isn't treated as a SeqAuto backend-link hint
upload = api.upload_file("input.vcf", path=None)
uploaded_file_id = upload["uploaded_file_id"]           # or upload["sha256_hash"]
api.wait_for_annotation(uploaded_file_id, timeout=3600, poll_interval=10)  # raises on error/timeout
path = api.download_annotated(uploaded_file_id, export_type="csv", dest_path="/data/results/")

Inspecting status directly

poll_upload_status(uploaded_file_id) returns the raw status dict (including annotation_complete, progress_percent, error, vcf_id, samples, ...) if you want to inspect progress directly. All of these accept sha256=<hash> instead of uploaded_file_id - the server dedups on the content hash, so it is stable across machines and useful if you didn't retain the id.

Submit now, download later

Annotating a large VCF (or one with many novel variants) can take a while, so you often don't want to block a process on it. Upload, persist the returned handle, then come back later - even on another machine or the next day - and download once it's ready. Use sha256_hash as the handle since it is stable across machines:

import json
from variantgrid_api.api_client import VariantGridAPI, AnnotationError

api = VariantGridAPI(server="https://variantgrid.com", api_token="YOUR_API_TOKEN")

# --- Submit: upload and record the handle, then walk away ---
upload = api.upload_file("input.vcf", path=None)
with open("pending.json", "w") as f:
    json.dump({"sha256": upload["sha256_hash"]}, f)

# --- Later (any machine): check if it's ready, download only if it is ---
sha256 = json.load(open("pending.json"))["sha256"]
status = api.poll_upload_status(sha256=sha256)

if status.get("error"):
    raise AnnotationError(status["error"], status)
elif status["annotation_complete"]:
    path = api.download_annotated(sha256=sha256, export_type="vcf", dest_path="/data/results/")
    print(f"Ready - written to {path}")
else:
    print(f"Not ready yet (progress {status.get('progress_percent')}%) - check again later")

wait_for_annotation() / annotate_vcf() are the blocking convenience wrappers - they poll this same status in a loop for you until it's complete (or timeout elapses). Reach for the manual poll_upload_status check above when you'd rather not hold a process open.

Notes

• The annotate_vcf wrapper already uploads with path=None. Only pass a path to upload_file for SeqAuto uploads that link to a registered JointCalledVCF / SingleSampleVCF (that is what path is for - it is ignored on non-SeqAuto deployments).
• Include a full ##contig header in the VCF so the server can detect the genome build - a partial contig set can leave the build undetectable.
• Downloads require the target deployment to have the cohort export analysis templates configured (ANALYSIS_TEMPLATES_AUTO_COHORT_EXPORT) - otherwise a clear error is returned.