## 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.

### 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.

### 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`

### Examples

```# admixture matrix for 1000 individuals drawing alleles from 10 subpops
# simple version: spread of 2 standard deviations along the 1D geography
# (just set sigma)

# 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
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: