# optimalSplitConnMat: Iteratively, optimally split a connectivity matrix In ConnMatTools: Tools for Working with Connectivity Data

## Description

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

## Usage

 ``` 1 2 3 4 5 6 7 8 9 10 11``` ```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`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18``` ```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) ```