compute.fstats: Estimate the F-statistics (F2, F3, F3star, F4, Dstat) and within and across population diversity

Description

Estimate the F-statistics (F2, F3, F3star, F4, Dstat) and within and across population diversity

Usage

compute.fstats(
  x,
  nsnp.per.bjack.block = 0,
  computeDstat = FALSE,
  computeF3 = TRUE,
  computeF4 = TRUE,
  output.pairwise.fst = TRUE,
  output.pairwise.div = TRUE,
  computeQmat = TRUE,
  return.F2.blockjackknife.samples = FALSE,
  return.F4.blockjackknife.samples = FALSE,
  verbose = TRUE
)

Value

An object of class fstats (see help(fstats) for details)

Arguments

x: A pooldata object containing Pool-Seq information or a countdata object containing allele count information
nsnp.per.bjack.block: Number of consecutive SNPs within a block for block-jackknife (default=0, i.e., no block-jackknife sampling)
computeDstat: If TRUE compute Dstatistics (i.e. scaled F4). This may add some non negligible computation time if the number of population is large (n>15)
computeF3: If TRUE (default) compute all F3 and all F3star (i.e. scaled F3).
computeF4: If TRUE (default) compute all F4.
output.pairwise.fst: If TRUE (default), output the npopxnpop matrix of pairwise-population Fst estimates (corresponding to the "Identity" method implemented in compute.pairwiseFST) in the pairwise.fst slot of the fstats output object (see help(fstats) for details) that may be visualized with e.g. heatmap function or used with a clustering function (e.g., hclust).
output.pairwise.div: If TRUE (default), output the npopxnpop matrix of pairwise-population divergence (1-Q2) estimates in the pairwise.div slot of the fstats output object (see help(fstats) for details) that may be visualized with e.g. heatmap function or used with a clustering function (e.g., hclust).
computeQmat: If TRUE, compute the error covariance matrix between all F3 and F2 statistics (needed for admixture graph construction). This matrix may be very large if the number of pops is large. It is recommended to estimate it on a reduced sample of pops.
return.F2.blockjackknife.samples: If TRUE (and nsnp.per.bjack.block>0) return an array of dimension (npopxnpopxnblocks) in an admixtools2 compatible format
return.F4.blockjackknife.samples: Deprecated options (since v. 2.2.0)
verbose: If TRUE extra information is printed on the terminal

Details

The function estimates for the n populations (or pools) represented in the input object x:

The F2 statistics for all the \(n(n-1)/2\) pairs of populations (or pools) and their scaled version (equivalent, but faster, than Fst estimated with compute.pairwiseFST when method="Identity")
If n>2, The F3 statistics for all the \(npools(npools-1)(npools-2)/2\) possible triplets of populations (or pools) and their scaled version (named F3star after Patterson et al., 2012)
If n>3, The F4 statistics and the D-statistics (a scaled version of the F4) for all the \(npools(npools-1)(npools-2)*(npools-3)/8\) possible quadruplets of populations
The estimated within population heterozygosities (=1-Q1)
The estimated divergence for each pair of populations (=1-Q2)

Examples

Run this code

 make.example.files(writing.dir=tempdir())
 pooldata=popsync2pooldata(sync.file=paste0(tempdir(),"/ex.sync.gz"),poolsizes=rep(50,15))
 res.fstats=compute.fstats(pooldata)