optimalSplitConnMat: Iteratively, optimally split a connectivity matrix

In dmkaplan2000/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

optimalSplitConnMat(
  conn.mat,
  normalize.cols = TRUE,
  make.symmetric = "mean",
  remove.diagonal = FALSE,
  cycles = 2,
  betas = betasVectorDefault(ifelse(normalize.cols, dim(conn.mat)[2],
    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)[2],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)[2] 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 [e-mail]

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

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)[1],
            "subpopulations."))
pops <- subpopsVectorToList(chile.loco.split$subpops[,chile.loco.split$best.splits[[1]]$index])

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

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

dmkaplan2000/ConnMatTools documentation built on Feb. 8, 2020, 4:41 p.m.