Web-based vSampler supports five types of files as input, including rsID, VCF, VCF-like, Coord-Only, Coord-Allele.

1. Population (default: EUR) : Sampling variants based on one of the 1000 genome phase3 super populations {EUR, EAS, AFR, AMR, SAS} genotype data.
2. Minor Allele Frequency Deviation (default: +/- 0.05) : Maximum allowable deviations for minor allele frequency.

1. DTCT Deviation (default: null) : Maximum allowable deviations for distance to closest transcription start site.
2. Gene Density Deviation (default: null) : Maximum allowable deviations for gene density. Users can choose LD thresholds using r² > {0.1, 0.2, ..., 0.9} or Physical Distance thresholds from 100kb to 1000kb.
3. Number of Variants in LD Deviation (default: null) : Maximum allowable deviations for the number of buddy variants in LD at various r² thresholds in r² > {0.1, 0.2, ..., 0.9}.
4. GC Content Deviation (default: null) : Maximum allowable deviations for the GC Content around the variant using window size {100bp, 200bp,...,500bp}.
5. Match Epigenomic Marks (default: null) : Whether to sample control variants with the same annotation of cell type-specific epigenomic mark.
6. Match eQTL Significance (default: null) : Whether to sample control variants with the same GTEx v8 eQTL significance (significant/not significant). Select 1 of 54 tissue.
7. Match Coding/Noncoding Region (default: null) : Whether to sample control variants falling in the same region (coding/noncoding).

1. Sample Across Chromosome (default: false) : Indicator of sampling across chromosomes or not. Note: this option might increase the runtime by 2-4 times.
2. Exclude Input SNPs (default: true) : Indicator to exclude input variants from matched variants or not.
3. Match Variant Type (default: true) : Whether to sample control variants with the same variant type (SNP/INDEL).
4. Sampling Number (default: 1) : The number of controls for each query variant.
5. Annotation Number (default: 1) : When `Sampling number` is large, the control variants and its annotation information will make the output file extemely large. Thus it's necessary to output the annotation information of only a subset of control variants. This number is defined by `Annotation number`.
6. Random Seed (default: NA). : Set random seed to ensure reproducibility.

shows all configuration of the submitted job

Results of vSampler will be displayed in tabular form, which can be easily sorted and filtered.

1. Basic job information including job name, submission time and job id.
2. Show unannotated query or Show insufficient match records to the table.
3. Results, background of query records are colored in aquamarine, and the first column of this table is the label followed by sampling ratio in parentheses. Sufficient records are marked with green √
4. Display configurations, users can define number of records to display, and filter the data use Filter Setting

Reports the density distribution of MAF, DTCT, Gene Density, LD variants number, GC content.

Java Runtime Environment (JRE) version 8.0 or above is required for vSampler. It can be downloaded from the Java web site. Installing the JRE is very easy in Windows OS and Mac OS X. In Linux, you have more work to do. Details of the installation can be found see the http://www.java.com/en/download/help/linux_install.xml.

This steps guides you from downloading the vSampler program.

1. The latest version of vSampler can be downloaded from https://github.com/mulinlab/vSampler/releases.
2. Extract the ZIP archive, you should find file called VariantSampler-x.y.z.jar which can be used for run vSampler.
3. You should also download indexed genotype reference panels from https://1drv.ms/f/s!Aurnn0fjCLv3glA_EoGK_N-daIwo?e=rKm9bh

vSampler sample variants based on 1000G phase 3 genotype data of 3 super populations including EUR, AFR, EAS, AMR, SAS.

To test that you can run vSampler tools, run the following command in your terminal application, providing either the full path to the VariantSampler-x.y.z.jar file:

java -jar -Xms1g -Xmx4g VariantSampler-x.y.z.jar

You should see a complete list of all the tools in the vSampler toolkit.

USAGE: java -jar /path/to/VariantSampler-x.y.z.jar <program name> [-h]

Available Programs:
--------------------------------------------------------------------------------------
Database:                                        Database build related.
    BuildDatabase                                Build Database
    BuildIndex                                   Build Index

--------------------------------------------------------------------------------------
Sampler:                                         Sampler related.
    Sampler                                      Sampler

The arguments -Xmx4g and -Xms1g set the initial and maximum Java heap sizes for vSampler as 1G and 4G respectively. Specifying a larger maximum heap size can speed up the analysis. A higher setting like -Xmx8g or even -Xmx20g is required when there is a large number of variants, say 5 million. The number, however, should be less than the size of physical memory of a machine.

• Local vSampler requires query file and indexed genotype reference panels as inputs.
• Local vSampler supports five types of query file, including VCF, VCF-like, Coord-Only, Coord-Allele, TAB.

java -jar -Xmx4g -Xms1g VariantSampler-x.y.z.jar Sampler -Q:vcf data/example.vcf -D data/EUR.gz
java -jar -Xmx4g -Xms1g VariantSampler-x.y.z.jar Sampler -Q:vcfLike data/example.vcflike.tsv -D data/EUR.gz
java -jar -Xmx4g -Xms1g VariantSampler-x.y.z.jar Sampler -Q:coordOnly data/example.coordOnly.tsv -D data/EUR.gz
java -jar -Xmx4g -Xms1g VariantSampler-x.y.z.jar Sampler -Q:coordAllele data/example.coordAllele.tsv -D data/EUR.gz
java -jar -Xmx4g -Xms1g VariantSampler-x.y.z.jar Sampler -Q:tab,c=2,b=3,e=4,0=true data/example.tab.tsv -D data/EUR.gz

vSampler will generate a zip containing the following four files:

1. anno.out.txt - This file contains the annotations of query and controls. Example Data.
2. sampler.config.txt - This file contains the configuration of the job, (i.e. the parameters used when running vSampler). Example Data
3. sampler.out.txt - This file reports the sampling outputs. Example Data
4. input.exclude.txt - vSampler only contains all variants that locates on autosomes with MAF > 0.01 based on 1000 genome phase 3 project genotype data, query variants out of this scope will be exclude. Example Data

Program to sampling dataset, the following options are relevant to Sampler

Genotype call sets of EUR, EAS, AFR, AMR and SAS super populations from 1000 Genomes Project phase 3

• URL: ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/release/20130502/;
• Release date: 05/02/2013;
• Sample size: EUR: 495, EAS: 497, AFR: 645

First split multi-allelic variants into multiple bi-allelic variants and then left-aligned and normalized reference and alternative alleles of all variants. Duplicate variants that map to the same position with identical reference and alternative alleles were removed.

The number of variants in the annotation database was too large to be feasible for the sampling process. Kept only variants with MAF > 0.01 of the annotation database to construct the sampling database.

Number of variants in vSampler database (GRCh37/hg19)

Number of variants in vSampler database (GRCh38/hg38)

• MAF: variants’ MAF of EUR, EAS, AFR, AMR and SAS population were computed based on allele frequency information from 1000 Genomes Project phase 3 release as described in database construction section.
• Distance to closest transcription start site(DTCT): all 5’ transcription start sites were defined according to GENCODE v32 and then we calculated variants’ distance to the closest 5’ transcription start sites.
• Gene density: gene density refers to number of genes overlapping with variant loci. Genes were extracted from GENCODE v32, and variant loci were defined by LD thresholds (r² > {0.1, 0.2, …, 0.9}) or physical distance (window size of 100, 200, ..., 1000 kb).
• Number of variants in LD: number of variants in LD were calculated using LD thresholds (r² > {0.1, 0.2, …, 0.9}).
• GC content: GC content of variants were computed with various window sizes (100bp, 200bp,...,500bp) based on 5 base GC content file hg19.gc5Base.txt.gz from UCSC Genome Browser (http://hgdownload.cse.ucsc.edu/goldenPath/hg19/gc5Base/hg19.gc5Base.txt.gz).
• Cell type specific epigenomic marks: annotation of cell type-specific epigenomic marks is binary indicator of whether variants fall within selected cell type-specific epigenomic marks. The cell type specific epigenomic marks included DNase I hypersensitive sites (DHSs) and histone modifications H3K4me1, H3K4me3, H3K36me3, H3K27me3, H3K9me3 downloaded from Roadmap Epigenomics Project (https://egg2.wustl.edu/roadmap/web_portal/).
• eQTL: annotation of eQTL significance is binary indicator of whether variants are significant eQTL variants. Significant eQTL variants data of 49 tissues/cell types were downloaded from GTEx project v8 (https://storage.googleapis.com/gtex_analysis_v8/single_tissue_qtl_data/GTEx_Analysis_v8_eQTL.tar). Significance of eQTL variants were determined based on permutation by GTEx project.
• Coding/noncoding region: We first identified variant effects using Jannovar, and then variants effects were classified as coding or non-coding.