optimalSplitConnMat {ConnMatTools} R Documentation

## Iteratively, optimally split a connectivity matrix

### Description

Algorithm for iteratively determining subpopulations of highly-connected sites. Uses an iterative method described in Jacobi et al. (2012)

### Usage

```optimalSplitConnMat(
conn.mat,
normalize.cols = TRUE,
make.symmetric = "mean",
remove.diagonal = FALSE,
cycles = 2,
betas = betasVectorDefault(ifelse(normalize.cols, dim(conn.mat),
prod(dim(conn.mat))/sum(conn.mat)), steps),
steps = 10,
...
)
```

### Arguments

 `conn.mat` A square connectivity matrix. `normalize.cols` A boolean indicating if columns of conn.mat should be normalized by the sum of all elements in the column. Defaults to TRUE. `make.symmetric` A string indicating how to force conn.mat to be symmetric. "mean" (the default) will replace C_ij by (C_ij + C_ji)/2. "max" will replace C_ij by the maximum of C_ij and C_ji. `remove.diagonal` A boolean indicating if the diagonal elements of conn.mat should be removed before determining the subpopulations. Defaults to FALSE. `cycles` Number of times to pass over values in betas. `betas` Vector of beta values to try. If not given, will default to `betasVectorDefault(dim(conn.mat),steps)`. `steps` Number of beta values to produce using betasVectorDefault. Ignored if betas argument is explicitly given. `...` further arguments to be passed to `splitConnMat`

### Value

A list with the following elements:

 `betas` Vector of all beta values tested `num.subpops` Vector of number of subpopulations found for each value of beta `qualities` Vector of the quality statistic for each subpopulation division `subpops` A matrix with dimensions dim(conn.mat) X length(betas) indicating which subpopulation each site belongs to `best.splits` A list indicating for each number of subpopulations, which column of subpops contains the division with the lowest quality statistic. E.g., `best.splits[["4"]]\$index` contains the column index of the optimal division of the connectivity matrix into 4 subpopulations.

### Note

In Jacobi et al. (2012) paper, the connectivity matrix is oriented so that C_ij is dispersal from i to j, whereas in this R package, the connectivity matrix is oriented so that C_ij is dispersal from j to i. This choice of orientation is arbitrary, but one must always be consistent. From j to i is more common in population dynamics because it works well with matrix multiplication (e.g., `settlers = conn.mat %*% eggs`).

### Author(s)

David M. Kaplan dmkaplan2000@gmail.com

### References

Jacobi, M. N., Andre, C., Doos, K., and Jonsson, P. R. 2012. Identification of subpopulations from connectivity matrices. Ecography, 35: 1004-1016.

See also `splitConnMat`, `recSplitConnMat`, `mergeSubpops`, `qualitySubpops`

### Examples

```library(ConnMatTools)
data(chile.loco)

num <- prod(dim(chile.loco)) / sum(chile.loco)
betas <- betasVectorDefault(n=num,steps=4)
chile.loco.split <- optimalSplitConnMat(chile.loco,normalize.cols=FALSE,
betas=betas)

# Extra 3rd division
print(paste("Examining split with",names(chile.loco.split\$best.splits),
"subpopulations."))
pops <- subpopsVectorToList(chile.loco.split\$subpops[,chile.loco.split\$best.splits[]\$index])

reduce.loco <- reducedConnMat(pops,chile.loco)

sr <- selfRecruitment(reduce.loco)
lr <- localRetention(reduce.loco)
rlr <- relativeLocalRetention(reduce.loco)
```

[Package ConnMatTools version 0.3.5 Index]