Haplotype based scans for selection
C C++ TeX Other
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
example
include
lib
manual
releases
src
.gitignore
INSTALL
LICENSE.md
MBE-2014-Szpiech-selscan-appnote.pdf
README

README

selscan -- a program to calculate EHH-based scans for positive selection in 
	genomes

Copyright (C) 2014  Zachary A Szpiech

selscan currently implements EHH, iHS, XP-EHH, nSL, and iHH12 and requires phased data. 
It should be run separately for each chromosome and population (or population 
pair for XP-EHH).  selscan is 'dumb' with respect ancestral/derived coding and
simply expects haplotype data to be coded 0/1.  Unstandardized iHS scores are 
thus reported as ln(iHH1/iHH0) based on the coding you have provided.

Citations:

ZA Szpiech and RD Hernandez (2014) selscan: an efficient multi-threaded program 
	to calculate EHH-based scans for positive selection. Molecular Biology and Evolution, 
	31: 2824-2827.
R Torres, et al. (2017) Human demographic history has amplified the effects of
	background selection across the genome. bioRxiv, doi: https://doi.org/10.1101/181859.
N Garud, et al. (2015) Recent selective sweeps in North American Drosophila
	melanogaster show signatures of soft sweeps. PLoS Genetics, 11: 1–32.
A Ferrer-Admetlla, et al. (2014) On detecting incomplete soft or hard selective sweeps
	using haplotype structure. Molecular Biology and Evolution, 31: 1275-1291.
PC Sabeti, et al. (2007) Genome-wide detection and characterization of positive 
	selection in human populations. Nature, 449: 913–918.
BF Voight, et al. (2006) A map of recent positive selection in the human 
	genome. PLoS Biology, 4: e72.
PC Sabeti, et al. (2002) Detecting recent positive selection in the human 
	genome from haplotype structure. Nature, 419: 832–837.

18SEPT2017 - norm v1.2.1a, selcan v1.2.0a iHH12 output files have a header line, XPEHH header line has an extra column name, fixed norm bugs relating to normalization of ihh12 files.

25AUG2017 - norm v1.2.1 released to fix a crash when --nsl flag is used.

18JUL2017 - Support for iHH12 calculations. norm has --ihh12 and --nsl flags.

09JAN2017 - Fixed buggy --crit-percent flag in norm binary.

05SEPT2016 - Fixed misleading error messages when --trunc-ok used.

12FEB2016 - v 1.1.0b - The flag --skip-low-freq is now on by default and no longer has any function.  selscan now filters low frequency variants by default.  A new flag --keep-low-freq is available if you would like to include low frequency variants when building haplotypes (low frequency variants will still be skipped over as core loci), using this option may reduce the power of iHS scans.

28OCT2015 - Updates to norm so that it can handle output from selscan when --ihs-detail is used.

18JUNE2015 - v1.1.0a - When calculating nSL, a mapfile is no longer required for VCF.  Physical distances will be read directly from VCF.  A mapfile specifying physical distances is stille required for .hap files when calculating nSL.  selscan now appropriately reports an error if this is not provided.

15JUNE2015 - Release of 1.1.0. tomkinsc adds the --ihs-detail parameter which, when provided as an adjunct to --ihs, will cause selscan to write out four additional columns to the output file of iHS calculations (in order): derived_ihh_left, derived_ihh_right, ancestral_ihh_left, and ancestral_ihh_right.

An example file row follows, with header added for clarity.

locus           phys-pos        1_freq          ihh_1           ihh_0           ihs             derived_ihh_left     derived_ihh_right    ancestral_ihh_left      ancestral_ihh_right

16133705        16133705        0.873626        0.0961264       0.105545        -0.0934761      0.0505176             0.0456087           0.0539295               0.0516158

From these values we can calculate iHS, but it is preserved in the output for convenience. Having left and right integral information may assist certain machine learning models that gain information from iHH asymmetry. 

selscan can now calculate the nSL statistic described in A Ferrer-Admetlla, et al. (2014) MBE, 31: 1275-1291.  Also introduced a check on map distance ordering.  Three new command line options.

--nsl <bool>: Set this flag to calculate nSL.
	Default: false

--max-extend-nsl <int>: The maximum distance an nSL haplotype is allowed to extend from the core.
	Set <= 0 for no restriction.
	Default: 100

--ihs-detail <bool> : Set this flag to write out left and right iHH scores for '1' and '0' in addition to iHS.

06MAY2015 - Release of 1.0.5. Added basic VCF support.  selscan can now read .vcf and .vcf.gz files but without tabix support.  A mapfile is required when using VCF.  Two new command line options.

13MAY2015 - norm v1.0.5 is released.  norm will now normalize ihs or xpehh scores.  Two new command line options.

--ihs <bool>: Do iHS normalization.

--xpehh <bool>: Do XP-EHH normalization.

Exactly one of these must be specified when running norm (e.g. ./norm --ihs --files *.ihs.out or ./norm --xpehh --files *.xpehh.out).

--vcf <string>: A VCF file containing haplotype data.
	A map file must be specified with --map.

--vcf-ref <string>: A VCF file containing haplotype and map data.
	Variants should be coded 0/1. This is the 'reference'
	population for XP-EHH calculations and should contain the same number
	of loci as the query population. Ignored otherwise.

07JAN2015 - norm bug fix and --skip-low-freq works for single EHH queries.

12NOV2014 - The program norm has been updated to allow for user defined critical values.  Two new command line options.

--crit-percent <double>: Set the critical value such that a SNP with iHS in the most extreme CRIT_PERCENT tails (two-tailed) is marked as an extreme SNP.
	Not used by default.

--crit-val <double>: Set the critical value such that a SNP with |iHS| > CRIT_VAL is marked as an extreme SNP.  Default as in Voight et al.
	Default: 2.00

17OCT2014 - Release of 1.0.4. A pairwise sequence difference module has been introduced.  This module isn't multithreaded at the moment, but still runs quite fast.  Calculating pi in 100bp windows with 198 haplotypes with 707,980 variants on human chr22 finishes in 77s on the test machine.  Using 100kb windows, it finishes in 34s.  Two new command line options.

--pi <bool>: Set this flag to calculate mean pairwise sequence difference in a sliding window.
	Default: false

--pi-win <int>: Sliding window size in bp for calculating pi.
	Default: 100

15SEP2014 - Release of 1.0.3.  **A critical bug in the XP-EHH module was introduced in version 1.0.2 and had been fixed in 1.0.3.  Do not use 1.0.2 for calculating XP-EHH scores.**  Thanks to David McWilliams for finding this error.  1.0.3 also introduces support for gzipped input files.  You may pass hap.gz, map.gz. and tped.gz files interchangably with unzipped files using the same command line arguments.  A new command line option is available.

--trunc-ok <bool>: If an EHH decay reaches the end of a sequence before reaching the cutoff,
	integrate the curve anyway (iHS and XPEHH only).
	Normal function is to disregard the score for that core.
	Default: false

17JUN2014 - Release of 1.0.2.  General speed improvements have been made, especially with threading.  New support for TPED formatted data and new command line options are available.

--skip-low-freq <bool>: Do not include low frequency variants in the construction of haplotypes (iHS only).
	Default: false

--max-extend: The maximum distance an EHH decay curve is allowed to extend from the core.
	Set <= 0 for no restriction.
	Default: 1000000

--tped <string>: A TPED file containing haplotype and map data.
	Variants should be coded 0/1
	Default: __hapfile1

--tped-ref <string>: A TPED file containing haplotype and map data.
	Variants should be coded 0/1. This is the 'reference'
	population for XP-EHH calculations and should contain the same number
	of loci as the query population. Ignored otherwise.
	Default: __hapfile2

10APR2014 - Release of 1.0.1.  Minor bug fixes. XP-EHH output header is now separated by tabs instead of spaces.  Removed references to missing data (which is not accepted), and introduced error checking in the event of non-0/1 data being provided.

26MAR2014 - Initial release of selscan 1.0.0.

USAGE:

**Data must be phased and have no missing genotypes.**

To calculate EHH:

./selscan --ehh <locusID> --hap <haps> --map <mapfile> --out <outfile>

To calculate iHS:

./selscan --ihs --hap <haps> --map <mapfile> --out <outfile>

To calculate nSL:

./selscan --nsl --hap <haps> --map <mapfile> --out <outfile>

To calculate iHH12:

./selscan --ihh12 --hap <haps> --map <mapfile> --out <outfile>

To calculate XP-EHH:

./selscan --xpehh --hap <pop1 haps> --ref <pop2 haps> --map <mapfile> --out <outfile>

----------Command Line Arguments----------

--alt <bool>: Set this flag to calculate homozygosity based on the sum of the
	squared haplotype frequencies in the observed data instead of using
	binomial coefficients.
	Default: false

--cutoff <double>: The EHH decay cutoff.
	Default: 0.05

--ehh <string>: Calculate EHH of the '1' and '0' haplotypes at the specified
	locus. Output: <physical dist> <genetic dist> <'1' EHH> <'0' EHH>
	Default: __NO_LOCUS__

--ehh-win <int>: When calculating EHH, this is the length of the window in bp
	in each direction from the query locus.
	Default: 100000

--gap-scale <int>: Gap scale parameter in bp. If a gap is encountered between
	two snps > GAP_SCALE and < MAX_GAP, then the genetic distance is
	scaled by GAP_SCALE/GAP.
	Default: 20000

--hap <string>: A hapfile with one row per haplotype, and one column per
	variant. Variants should be coded 0/1
	Default: __hapfile1

--help <bool>: Prints this help dialog.
	Default: false

--ihh12 <bool>: Set this flag to calculate iHH12.
	Default: false

--ihs <bool>: Set this flag to calculate iHS.
	Default: false

--ihs-detail <bool>: Set this flag to write out left and right iHH scores for '1' and '0' in addition to iHS.
	Default: false

--keep-low-freq <bool>: Include low frequency variants in the construction of your haplotypes.
	Default: false

--maf <double>: If a site has a MAF below this value, the program will not use
	it as a core snp.
	Default: 0.05

--map <string>: A mapfile with one row per variant site.
	Formatted <chr#> <locusID> <genetic pos> <physical pos>.
	Default: __mapfile

--max-extend <int>: The maximum distance an EHH decay curve is allowed to extend from the core.
	Set <= 0 for no restriction.
	Default: 1000000

--max-extend-nsl <int>: The maximum distance an nSL haplotype is allowed to extend from the core.
	Set <= 0 for no restriction.
	Default: 100

--max-gap <int>: Maximum allowed gap in bp between two snps.
	Default: 200000

--nsl <bool>: Set this flag to calculate nSL.
	Default: false

--out <string>: The basename for all output files.
	Default: outfile

--pi <bool>: Set this flag to calculate mean pairwise sequence difference in a sliding window.
	Default: false

--pi-win <int>: Sliding window size in bp for calculating pi.
	Default: 100

--ref <string>: A hapfile with one row per haplotype, and one column per
	variant. Variants should be coded 0/1. This is the 'reference'
	population for XP-EHH calculations.  Ignored otherwise.
	Default: __hapfile2

--skip-low-freq <bool>: **This flag is now on by default. If you want to include low frequency variants
in the construction of your haplotypes please use the --keep-low-freq flag.
	Default: false

--threads <int>: The number of threads to spawn during the calculation.
	Partitions loci across threads.
	Default: 1

--tped <string>: A TPED file containing haplotype and map data.
	Variants should be coded 0/1
	Default: __hapfile1

--tped-ref <string>: A TPED file containing haplotype and map data.
	Variants should be coded 0/1. This is the 'reference'
	population for XP-EHH calculations and should contain the same number
	of loci as the query population. Ignored otherwise.
	Default: __hapfile2

--trunc-ok <bool>: If an EHH decay reaches the end of a sequence before reaching the cutoff,
	integrate the curve anyway (iHS and XPEHH only).
	Normal function is to disregard the score for that core.
	Default: false

--vcf <string>: A VCF file containing haplotype data.
	A map file must be specified with --map.
	Default: __hapfile1

--vcf-ref <string>: A VCF file containing haplotype and map data.
	Variants should be coded 0/1. This is the 'reference'
	population for XP-EHH calculations and should contain the same number
	of loci as the query population. Ignored otherwise.
	Default: __hapfile2

--xpehh <bool>: Set this flag to calculate XP-EHH.
	Default: false


################################################################################
################################################################################

norm v1.2.1a -- a program for downstream analysis of selscan output
Source code and binaries can be found at
	<https://www.github.com/szpiech/selscan>

Citations:

selscan: ZA Szpiech and RD Hernandez (2014) MBE, 31: 2824-2827.
iHH12: R Torres, et al. (2017) bioRxiv, doi: https://doi.org/10.1101/181859.
       N Garud, et al. (2015) PLoS Genetics, 11: 1–32.
nSL: A Ferrer-Admetlla, et al. (2014) MBE, 31: 1275-1291.
xpehh: PC Sabeti, et al. (2007) Nature, 449: 913–918.
iHS: BF Voight, et al. (2006) PLoS Biology, 4: e72.

To normalize selscan output across frequency bins:

./norm [--ihs|--xpehh|--nsl|--ihh12] --files <file1.*.out> ... <fileN.*.out>

To normalize selscan output and analyze non-overlapping windows of fixed bp for 
extreme scores:

./norm [--ihs|--xpehh|--nsl|--ihh12] --files <file1.*.out> ... <fileN.*.out> --bp-win

----------Command Line Arguments----------

--bins <int>: The number of frequency bins in [0,1] for score normalization.
	Default: 100

--bp-win <bool>: If set, will use windows of a constant bp size with varying
	number of SNPs.
	Default: false

--crit-percent <double>: Set the critical value such that a SNP with iHS in the most extreme CRIT_PERCENT tails (two-tailed) is marked as an extreme SNP.
	Not used by default.
	Default: -1.00

--crit-val <double>: Set the critical value such that a SNP with |iHS| > CRIT_VAL is marked as an extreme SNP.  Default as in Voight et al.
	Default: 2.00

--files <string1> ... <stringN>: A list of files delimited by whitespace for
	joint normalization.
	Expected format for iHS or nSL files (no header):
	<locus name> <physical pos> <freq> <ihh1/sL1> <ihh2/sL2> <ihs/nsl>
	Expected format for XP-EHH files (one line header):
	<locus name> <physical pos> <genetic pos> <freq1> <ihh1> <freq2> <ihh2> <xpehh>
	Expected format for iHH12 files (one line header):
	<locus name> <physical pos> <freq1> <ihh12>
	Default: infile

--first <bool>: Output only the first file's normalization.
	Default: false

--help <bool>: Prints this help dialog.
	Default: false

--ihh12 <bool>: Do ihh12 normalization.
	Default: false

--ihs <bool>: Do iHS normalization.
	Default: false

--log <string>: The log file name.
	Default: logfile

--min-snps <int>: Only consider a bp window if it has at least this many SNPs.
	Default: 10

--nsl <bool>: Do nSL normalization.
	Default: false

--qbins <int>: Outlying windows are binned by number of sites within each
	window.  This is the number of quantile bins to use.
	Default: 20

--winsize <int>: The non-overlapping window size for calculating the percentage
	of extreme SNPs.
	Default: 100000

--xpehh <bool>: Do XP-EHH normalization.
	Default: false