Welcome to variant-mapper

The variant-mapper is a package to map genetic variants to the genome, in order to validate them and assign an rs ID.

This will:

1. Localise the genetic variant based on chromosome position, using either a file join approach or tabix.

2. Determine if the ref/alt alleles match to a known variant site, it assumes that ref/alt can be flipped.

3. If a site can be identified then it will annotate the variant with function information.

4. If no site can be identified

5. If an INDEL, normalise the alleles and attempt mapping again.

6. Finally, is still can’t be mapped validate one of the alleles against the reference genome assembly

7. This can also handle cases where only a single allele is known, assuming the site is bi-alleilic and the ref allele can be localised.

The mapper works by having a common mapper file and a full mapper file. The common mapper file contains common variants usually used in GWAS studies and the full mapper file has all known variant from dbSNP and from other projects as well.

You can either map by localising the genetic variants using tabix or by a table scan (file join) approach. The file join is most efficient if you have millions of variants, or rather if your input fie is ~10-20M variants. In this case the common file is used for the join and where something can’t be mapped then a tabix query is tried again the full file. In many cases the common file is good enough but it might miss some variants.

Installation

This can be installed using Pypi or conda

To install using Pypi:

pip install variant-mapper

To install using conda:

conda install -c cfin -c conda-forge variant-mapper

Additional setup

In addition to installing you will need to download one or more mapping files (these are on my pCloud so please don’t hammer it).

• The common mapping file can be downloaded (~9G): mapping-v20220402

• The full mapping file (~60G), please contact me for a download link. There is nothing super secret about the mapping file, UCL does not offer any file downloading so I have no other way to distribute these.

Of course if you really want to you can follow the instructions to build your own but I would not recommend it. However, if you want to see how the mapping file is created then the instructions should give you a good idea. They also detail what populations are available in the mapping file.

What next?

There is a TLDR; which details how to use the command line programs.

Contents

Usage

• variant-mapper TLDR;
  • Install the package
  • Get the mapping files
  • Run on the command line
  • Run usung Python using the API
  • Using the Bash scripts
• Command-line endpoints
  • Python endpoints
  • BASH endpoints

Programmer reference

• variant_mapper API
  • variant_mapper package
• Example code
  • Using the Ensembl variant mapper API
  • Mapping using Tabix and VCF files
  • Summary
  • INDEL normalisation

Project admin

• Building the mapping files
  • Introduction
  • Version information
  • The populations in the mapping file
  • The mapping VCF file format
  • Download reference genomes
  • Installing helper bash scripts for building the mapping files
  • Mapping file data
  • ALFA
  • GNOMAD2 exome allele counts
  • GNOMAD3 allele counts
  • 1000 genomes allele counts
  • UKBB SNPstats files
  • Merging all the data sources
  • Running VEP
  • Splitting the mapping file into common/rare
  • The variant synonyms file
• Introduction to variant mapping
  • What are the data sources?
  • The variant mapping process
• Installing Ensembl VEP
  • Install requirements
  • Installing VEP
  • Downloading the CADD data
  • Running VEP
• Updating Ensembl VEP
• Contributing to the project

Indices and tables

• Index

• Module Index

• Search Page