# Simulates emigration between populations

`gl.sim.emigration.Rd`

A function that allows to exchange individuals of populations within a genlight object (=simulate emigration between populations).

## Arguments

- x
A genlight or list of genlight objects [required].

- perc.mig
Percentage of individuals that migrate (emigrates = nInd times perc.mig) [default NULL].

- emi.m
Probabilistic emigration matrix (emigrate from=column to=row) [default NULL]

- emi.table
If presented emi.m matrix is ignored. Deterministic emigration as specified in the matrix (a square matrix of dimension of the number of populations). e.g. an entry in the 'emi.table[2,1]<- 5' means that five individuals emigrate from population 1 to population 2 (from=columns and to=row) [default NULL].

## Value

A list or a single [depends on the input] genlight object, where emigration between population has happened

## Details

There are two ways to specify emigration. If an emi.table is provided (a square matrix of dimension of the populations that specifies the emigration from column x to row y), then emigration is deterministic in terms of numbers of individuals as specified in the table. If perc.mig and emi.m are provided, then emigration is probabilistic. The number of emigrants is determined by the population size times the perc.mig and then the population where to migrate to is taken from the relative probability in the columns of the emi.m table.

Be aware if the diagonal is non zero then migration can occur into the same patch. So most often you want to set the diagonal of the emi.m matrix to zero. Which individuals is moved is random, but the order is in the order of populations. It is possible that an individual moves twice within an emigration call(as there is no check, so an individual moved from population 1 to 2 can move again from population 2 to 3).

## Author

Custodian: Bernd Gruber (Post to https://groups.google.com/d/forum/dartr)

## Examples

```
x <- possums.gl
#one individual moves from every population to
#every other population
emi.tab <- matrix(1, nrow=nPop(x), ncol=nPop(x))
diag(emi.tab)<- 0
np <- gl.sim.emigration(x, emi.table=emi.tab)
np
#> /// GENLIGHT OBJECT /////////
#>
#> // 300 genotypes, 200 binary SNPs, size: 508.5 Kb
#> 0 (0 %) missing data
#>
#> // Basic content
#> @gen: list of 300 SNPbin
#>
#> // Optional content
#> @ind.names: 300 individual labels
#> @loc.names: 200 locus labels
#> @pop: population of each individual (group size range: 30-30)
#> @other: a list containing: elements without names
#>
```