annotate_vcf

annotate_vcf annotates the variants of a VCF file with an annotation pipeline. It reads a VCF file, plain or gzip/bgzip-compressed, and a pipeline, a YAML file or a GRR pipeline resource id. It writes a copy of the VCF file with the attributes of the pipeline in the INFO column. Use it when the variants are in VCF format and the result must stay a VCF file. When the input is sorted, bgzip-compressed and tabix-indexed, the tool splits the job by genomic region and runs the parts in parallel.

Examples

annotate_vcf small_input.vcf custom_pipeline.yaml -o vcf.annotated.vcf

Annotates the variants of small_input.vcf with a pipeline file and writes the result to vcf.annotated.vcf.

annotate_vcf small_input.sorted.vcf.bgz custom_pipeline.yaml -r 30_000_000 -j 8

Splits a tabix-indexed VCF file into 30 Mbp regions and annotates them with 8 parallel jobs.

annotate_vcf annotated.vcf.gz new_pipeline.yaml --reannotate old_pipeline.yaml -o reannotated.vcf.gz

Annotates a VCF file that old_pipeline.yaml annotated before, and computes only the attributes that are new or changed in new_pipeline.yaml.

See also

• Annotating VCF input: annotate a VCF file and prepare it for parallel annotation.

• annotate_vcf: the common options.

• Notes on usage: the options that annotate_vcf shares with annotate_tabular.

• Running in parallel: the number of workers, the named clusters and the reruns.

Option reference

Annotate VCF

usage: annotate_vcf [-h] [-n] [--version] [-r REGION_SIZE] [-w WORK_DIR]
                    [-o OUTPUT] [--reannotate REANNOTATE]
                    [--full-reannotation] [--keep-parts] [--no-keep-parts]
                    [--keep-work-dir] [--batch-size BATCH_SIZE]
                    [--allow-remote-resources] [-g GRR_FILENAME]
                    [--grr-directory GRR_DIRECTORY]
                    [-R REFERENCE_GENOME_RESOURCE_ID]
                    [-G GENE_MODELS_RESOURCE_ID] [-ar] [-j JOBS]
                    [--process-pool] [-N DASK_CLUSTER_NAME]
                    [-c DASK_CLUSTER_CONFIG_FILE]
                    [--task-log-dir TASK_LOG_DIR] [-t TASK_IDS [TASK_IDS ...]]
                    [--keep-going] [--fork-tasks] [--force]
                    [-d TASK_STATUS_DIR] [--verbose] [--logfile LOGFILE]
                    [input] [pipeline] [{run,list,status}]

Positional Arguments

input

the input file; gzip/bgzip-compressed inputs (.gz/.bgz), optionally tabix-indexed, are detected by extension

Default: '-'

pipeline

The pipeline definition file. By default, or if the value is gpf_instance, the annotation pipeline from the configured gpf instance will be used.

Default: 'context'

Named Arguments

-n, --dry-run

Print the annotation/reannotation plan and exit without writing any output.

Default: False

--version

Show the GAIn version and exit

Default: False

-r, --region-size

region size to parallelize by; zero or negative values disable parallelization

Default: 300000000

-w, --work-dir

Directory to store intermediate output files in

-o, --output

Filename of the output result; a .gz/.bgz suffix produces a compressed, tabix-indexed output. If the suffix is omitted, a compressed input’s suffix is mirrored onto the output.

--reannotate

Old pipeline config to reannotate over

--full-reannotation, --fr

Ignore any previous annotation and run a full reannotation.

Default: False

--keep-parts, --keep-intermediate-files

Keep intermediate files after annotatio.

Default: False

--no-keep-parts, --no-keep-intermediate-files

Remove intermediate files after annotatio.

Default: True

--keep-work-dir

Keep the working directory after a successful annotation (by default a working directory the tool created is removed).

Default: False

--batch-size

Annotate in batches of

Default: 0

--allow-remote-resources

Skip the check that warns or aborts when annotating many variants against non-local (http/https/s3) genomic resources.

Default: False

-g, --grr-filename, --grr

The GRR configuration file. If the argument is absent, the a GRR repository from the current genomic context (i.e. gpf_instance) will be used or, if that fails, the default GRR configuration will be used.

--grr-directory

Local GRR directory to use as repository.

-R, --reference-genome-resource-id, --ref

The resource id for the reference genome. If the argument is absent the reference genome from the current genomic context will be used.

-G, --gene-models-resource-id, --genes

The resource is of the gene models resource. If the argument is absent the gene models from the current genomic context will be used.

-ar, --allow-repeated-attributes

Rename repeated attributes instead of raising an error.

Default: False

--verbose, -v, -V

Default: 0

--logfile

File to log output to. If not set, logs to console.

Task Graph Executor

-j, --jobs

Number of jobs to run in parallel. Defaults to the number of processors on the machine

--process-pool, --pp

Use a process pool executor with the specified number of processes instead of a dask distributed executor.

Default: False

-N, --dask-cluster-name, --dcn

The name of a named cluster in the dask config, under ‘gain_named_cluster.clusters’. The tasks run on it.

-c, --dccf, --dask-cluster-config-file

dask cluster config file

--task-log-dir

Path to directory where to store tasks’ logs

Execution Mode

command

Possible choices: run, list, status

Command to execute on the import configuration. run - runs the import process list - lists the tasks to be executed but doesn’t run them status - synonym for list

Default: 'run'

-t, --task-ids

--keep-going

Whether or not to keep executing in case of an error

Default: False

--fork-tasks, --fork-task, --fork

Whether to fork a new worker process for each task

Default: False

--force, -f

Ignore precomputed state and always rerun all tasks.

Default: False

-d, --task-status-dir, --tsd

Directory to store the task progress.