bnpsd (version 1.1.1)

admix_prop_1d_linear: Construct admixture proportion matrix for 1D geography

Description

Assumes \(k\) intermediate subpopulations placed along a line at locations \(1:k\) spread by random walks, then \(n\) individuals sampled equally spaced in \([a,b]\) (default \([0.5, k+0.5]\)) draw their admixture proportions relative to the Normal density that models the random walks of each of these intermediate subpopulations. The spread of the random walks (the \(\sigma\) of the Normal densities) is set to sigma if not missing, otherwise \(\sigma\) is found numerically to give the desired bias coefficient bias_coeff, the coancestry matrix of the intermediate subpopulations coanc_subpops (up to a scalar factor), and the final \(F_{ST}\) of the admixed individuals (see details below).

Usage

admix_prop_1d_linear(n_ind, k_subpops, sigma = NA,
  coord_ind_first = 0.5, coord_ind_last = k_subpops + 0.5, bias_coeff,
  coanc_subpops, fst)

Arguments

n_ind

Number of individuals.

k_subpops

Number of intermediate subpopulations.

sigma

Spread of intermediate subpopulations (standard deviation of normal densities). The edge cases sigma = 0 and sigma = Inf are handled appropriately!

coord_ind_first

Location of first individual.

coord_ind_last

Location of last individual.

OPTIONS FOR BIAS COEFFICIENT VERSION

bias_coeff

The desired bias coefficient, which specifies \(\sigma\) indirectly. Required if sigma is missing.

coanc_subpops

The \(k \times k\) coancestry matrix of the intermediate subpopulations, or equivalent vector or scalar forms (which model independent subpopulations), up to a scaling factor (which cancels out in calculations) Required if sigma is missing.

fst

The desired final \(F_{ST}\) of the admixed individuals. Required if sigma is missing.

Value

If sigma was provided, the \(n \times k\) admixture proportion matrix. If sigma is missing, a named list is returned containing admix_proportions, the rescaled coanc_subpops, and the sigma that together give the desired \(bias_coeff\) and final \(F_{ST}\) of the admixed individuals.

Details

When sigma is missing, the function determines its value using the desired bias_coeff, coanc_subpops up to a scalar factor, and fst. Uniform weights for the final generalized \(F_{ST}\) are assumed. The scale of coanc_subpops is irrelevant because it cancels out in bias_coeff; after sigma is found, coanc_subpops is rescaled to give the desired final \(F_{ST}\). However, the function stops with a fatal error if the rescaled coanc_subpops takes on any values greater than 1, which are not allowed since coanc_subpops are IBD probabilities.

Examples

# NOT RUN {
# admixture matrix for 1000 individuals drawing alleles from 10 subpops
# and a spread of 2 standard deviations along the 1D geography
admix_proportions <- admix_prop_1d_linear(n_ind = 1000, k_subpops = 10, sigma = 2)

# as sigma approaches zero, admix_proportions approaches the independent subpopulations matrix
admix_prop_1d_linear(n_ind = 10, k_subpops = 2, sigma = 0)

# a similar model but with a bias coefficient of exactly 1/2
k_subpops <- 10
# FST vector for intermediate independent subpops, up to a factor (will be rescaled below)
coanc_subpops <- 1 : k_subpops
obj <- admix_prop_1d_linear(
    n_ind = 1000,
    k_subpops = k_subpops,
    bias_coeff = 0.5,
    coanc_subpops = coanc_subpops,
    fst = 0.1 # desired final FST of admixed individuals
)

# in this case return value is a named list with three items:
# admixture proportions
admix_proportions <- obj$admix_proportions

# rescaled coancestry data (matrix or vector) for intermediate subpops
coanc_subpops <- obj$coanc_subpops

# and the sigma that gives the desired bias_coeff and final FST
sigma <- obj$sigma

# }