draw_all_admix {bnpsd}R Documentation

Simulate random allele frequencies and genotypes from the BN-PSD admixture model


This function returns simulated ancestral, intermediate, and individual-specific allele frequencies and genotypes given the admixture structure, as determined by the admixture proportions and the vector or tree of intermediate subpopulation FST values. The function is a wrapper around draw_p_anc(), draw_p_subpops()/draw_p_subpops_tree(), make_p_ind_admix(), and draw_genotypes_admix() with additional features such as requiring polymorphic loci. Importantly, by default fixed loci (where all individuals were homozygous for the same allele) are re-drawn from the start (starting from the ancestral allele frequencies) so no fixed loci are in the output and no biases are introduced by re-drawing genotypes conditional on any of the previous allele frequencies (ancestral, intermediate, or individual-specific). Below m_loci (also m) is the number of loci, n is the number of individuals, and k is the number of intermediate subpopulations.


  inbr_subpops = NULL,
  tree_subpops = NULL,
  want_genotypes = TRUE,
  want_p_ind = FALSE,
  want_p_subpops = FALSE,
  want_p_anc = TRUE,
  verbose = FALSE,
  require_polymorphic_loci = TRUE,
  maf_min = 0,
  beta = NA,
  p_anc = NULL,
  p_anc_distr = NULL



The n-by-k matrix of admixture proportions.


The length-k vector (or scalar) of intermediate subpopulation FST values. Either this or tree_subpops must be provided (but not both).


The number of loci to draw.


The coancestry tree relating the k intermediate subpopulations. Must be a phylo object from the ape package (see ape::read.tree()). Either this or inbr_subpops must be provided (but not both).


If TRUE (default), includes the matrix of random genotypes in the return list.


If TRUE (NOT default), includes the matrix of individual-specific allele frequencies in the return list. Note that by default p_ind is not constructed in full at all, instead a fast low-memory algorithm constructs it in parts as needed only; beware that setting want_p_ind = TRUE increases memory usage in comparison.


If TRUE (NOT default), includes the matrix of random intermediate subpopulation allele frequencies in the return list.


If TRUE (default), includes the vector of random ancestral allele frequencies in the return list.


If TRUE, prints messages for every stage in the algorithm.


If TRUE (default), returned genotype matrix will not include any fixed loci (loci that happened to be fixed are drawn again, starting from their ancestral allele frequencies, and checked iteratively until no fixed loci remain, so that the final number of polymorphic loci is exactly m_loci).


The minimum minor allele frequency (default zero), to extend the working definition of "fixed" above to include rare variants. This helps simulate a frequency-based locus ascertainment bias. Loci with minor allele frequencies less than or equal to this value are treated as fixed (passed to fixed_loci()). This parameter has no effect if require_polymorphic_loci is FALSE.


Shape parameter for a symmetric Beta for ancestral allele frequencies p_anc. If NA (default), p_anc is uniform with range in [0.01, 0.5]. Otherwise, p_anc has a symmetric Beta distribution with range in [0, 1]. Has no effect if either p_anc or p_anc_distr options are non-NULL.


If provided, it is used as the ancestral allele frequencies (instead of drawing random ones). Must either be a scalar or a length-m_loci vector. If scalar and want_p_anc = TRUE, then the returned p_anc is the scalar value repeated m_loci times (it is always a vector). If a locus was fixed and has to be redrawn, the ancestral allele frequency in p_anc is retained and only downstream allele frequencies and genotypes are redrawn (contrast to p_anc_distr below).


If provided, ancestral allele frequencies are drawn with replacement from this vector (which may have any length) or function, instead of from draw_p_anc(). If a function, must accept a single parameter specifying the number of loci to draw. If a locus was fixed and has to be redrawn, the ancestral allele frequency is redrawn from the distribution (contrast to p_anc above).


As a precaution, function stops if both the column names of admix_proportions and the names in inbr_subpops or tree_subpops exist and disagree, which might be because these two data are not aligned or there is some other inconsistency.


A named list with the following items (which may be missing depending on options):


# dimensions
# number of loci
m_loci <- 10
# number of individuals
n_ind <- 5
# number of intermediate subpops
k_subpops <- 2

# define population structure
# FST values for k = 2 subpopulations
inbr_subpops <- c(0.1, 0.3)
# admixture proportions from 1D geography
admix_proportions <- admix_prop_1d_linear(n_ind, k_subpops, sigma = 1)

# draw all random allele freqs and genotypes
out <- draw_all_admix(admix_proportions, inbr_subpops, m_loci)

# return value is a list with these items:

# genotypes
X <- out$X

# ancestral AFs
p_anc <- out$p_anc

# # these are excluded by default, but would be included if ...
# # ... `want_p_subpops == TRUE`
# # intermediate subpopulation AFs
# p_subpops <- out$p_subpops
# # ... `want_p_ind == TRUE`
# # individual-specific AFs
# p_ind <- out$p_ind

[Package bnpsd version 1.3.13 Index]