Background on the ukbb-assigner.R script.¶
The methodology section outlines the specific steps that were taken to generate the genetic similarity table. The ukbb-assigner.R script is a simple wrapper script used to assign individuals to groups based on genetic similarity to populations inferred using the UK Biobank (see Prive et al 2022 (a)). It uses code developed by Florian Prive through the bigsnpr package. Please cite Florian Prive's work if using this methodology in your own analyses.
We provide this script to enable researchers to reproduce results or apply this methodology to different cohorts. However, throughout migrations of our systems, it may be possible that the script does not directly function. In such cases, we expect you to make your own adjustments to the script as long as Florian Prive's work is cited.
Location¶
Path to script: /gel_data_resources/gel_diverse_data/ukbb-assigner/ukbb-assigner.R
Package requirements¶
The following R packages are required for this tool to work: - tidyverse - bigsnpr - optparse
Command line options¶
Usage: ukbb-assigner.R [options]
Options:
-v VCF, --vcf=VCF
Path to single or multi-sample VCF file (must be gzipped)
-p PLINK, --plink=PLINK
Path to single or multi-sample binary plink file prefix bed/bim/fam
-r REFERENCE, --reference=REFERENCE
Reference genome build (options: v37 or v38). default - v38.
-o OUTPUT, --output=OUTPUT
Output prefix. default - assignment
-t THRESHOLD, --threshold=THRESHOLD
Ancestry assignment threshold euclidean distance. default - 0.002.
-m, --mixture
Also output population-specific mixture fractions.
--tmpDir=TMPDIR
Path to temporary directory.
-h, --help
Show this help message and exit
Usage (Example)¶
Below we outline various examples that the script can be used for. In most cases we have example data available, except for GRCh37. The example data however is simply generated by filtering the public 1000-Genomes data for HQ sites, and may need to be converted into VCFs.
Binary Plink Files (Default)¶
This method works directly on binary PLINK files (bed/bim/fam), and so running on these files is preferable if they are available.
VCF Files¶
The file will perform auto-conversion of VCFs on the fly - converting the file to PLINK format if it can.
Be aware of ascertainment bias!
We do not recommend running this tool on single-sample VCFs or PLINK files that only include variable sites. Only including sites that are variable in a single (or few) individuals leads to ascertainment bias which will lead to poor performance. Please provide genotypes at variable and non-variable sites.
Change confidence threshold¶
Individuals within VCF/PLINK files are assigned to a population by calculating the squared distance of projected genotypes from the PC centre of each respective population, converting this to an approximate FST, identifying the smallest such distance (most likely assignment), and then applying a confidence threshold for assignment (default FST < 0.002). Individuals whose lowest approximate FST to any PC centre is above the threshold value are instead unassigned - as may be the case with admixed samples.
If you want to generate the most likely assignments, use a confidence threshold of 1.
If you want to be less stringent with your assignments - you can increase the FST threshold value (e.g. to 0.005).
Output mixture fractions¶
Methods that release convex mixture fractions such as ADMIXTURE (projection mode) can be approximated rapidly using PC projection with this tool. To output mixture fractions (summing to 1) as well as assignments and FST:
Reference build 37¶
If your samples are aligned to build GRCh37/hg19 of the reference genome, you can use the code below. However, note that we do not have example data available for this.