bnpsd (version 1.3.13)

admix_prop_1d_linear: Construct admixture proportion matrix for 1D geography

Description

Assumes k_subpops intermediate subpopulations placed along a line at locations 1 : k_subpops spread by random walks, then n_ind individuals equally spaced in [coord_ind_first,coord_ind_last] 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 standard deviation of the Normal densities) is sigma. If sigma is missing, it can be set indirectly by providing three variables: (1) the desired bias coefficient bias_coeff, (2) the coancestry matrix of the intermediate subpopulations coanc_subpops (up to a scalar factor), and (3) the final fst 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 = NA,
  coanc_subpops = NULL,
  fst = NA
)

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 (default 0.5).

coord_ind_last

Location of last individual (default k_subpops + 0.5).

OPTIONS FOR BIAS COEFFICIENT VERSION

bias_coeff

If sigma is NA, this bias coefficient is required.

coanc_subpops

If sigma is NA, this intermediate subpops coancestry is required. It can be provided as a k_subpops-by-k_subpops matrix, a length-k_subpops population inbreeding vector (for independent subpopulations, where between-subpop coancestries are zero) or scalar (if population inbreeding values are all equal and coancestries are zero). This coanc_subpops can be in the wrong scale (it cancels out in calculations), which is returned corrected, to result in the desired fst (next).

fst

If sigma is NA, this FST of the admixed individuals is required.

Value

If sigma was provided, returns the n_ind-by-k_subpops admixture proportion matrix (admix_proportions). If sigma is missing, returns a named list containing:

• admix_proportions: the n_ind-by-k_subpops admixture proportion matrix. If coanc_subpops had names, they are copied to the columns of this matrix.

• coanc_subpops: the input coanc_subpops rescaled.

• sigma: the fit value of the spread of intermediate subpopulations

• coanc_factor: multiplicative factor used to rescale coanc_subpops

Details

If sigma is NA, its value is determined from the desired bias_coeff, coanc_subpops up to a scalar factor, and fst. Uniform weights for the final generalized FST 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 FST. However, the function stops if any rescaled coanc_subpops values are greater than 1, which are not allowed since they are IBD probabilities.

Examples

# NOT RUN {
# admixture matrix for 1000 individuals drawing alleles from 10 subpops
# simple version: spread of 2 standard deviations along the 1D geography
# (just set sigma)
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)

# advanced version: a similar model but with a bias coefficient of exactly 1/2
# (must provide bias_coeff, coanc_subpops, and fst in lieu of sigma)
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

# }