ipcaps2: Perform unsupervised clustering to capture population...

In kridsadakorn/ipcaps2: Iterative Pruning to Capture Population Structure version 2

Perform unsupervised clustering to capture population structure based on iterative pruning

Description

This version supports ordinal data which can be applied directly to SNP data to identify fine-scale population structure. It was built on the iterative pruning Principal Component Analysis (ipPCA) algorithm (Intarapanich et al., 2009; Limpiti et al., 2011). The IPCAPS2 involves an iterative process using multiple splits based on multivariate Gaussian mixture modeling of principal components and Clustering EM estimation (Lebret et al., 2015). In each iteration, rough clusters and outliers are also identified using our own method called rubikclust (R package KRIS).

Usage

ipcaps2(
  bed = NA,
  rdata = NA,
  files = NA,
  label.file = NA,
  lab.col = 1,
  out,
  plot.as.pdf = FALSE,
  method = "mix",
  missing = NA,
  covariate = NA,
  cov.col.first = NA,
  cov.col.last = NA,
  threshold = 0.18,
  min.fst = 8e-04,
  min.in.group = 20,
  no.plot = FALSE,
  data.type = "snp",
  silence = FALSE,
  max.thread = 0,
  no.rep = 5,
  cutoff.confident = 0.5
)

Arguments

bed	A PLINK binary format consists of 3 files; bed, bim, and fam. To generate these files from PLINK, use option –make-bed. See more details at: harvard.edu.
rdata	In case of re-analysis, it is convenient to run IPCAPS2 using the file rawdata.RData generated by IPCAPS2. This file contains a matrix of SNPs (raw.data) and a vector of labels (label).
files	IPCAPS2 supports SNPs encoded as 0, 1 and 2 (dosage encoding). Rows represent SNPs and columns represent subjects. Each column needs to be separated by a space or a tab. A big text file should be divided into smaller files to load faster. For instance, to input 3 files, use as: files=c( 'input1.txt', 'input2.txt', 'input3.txt').
label.file	An additional useful information (called "labels" in IPCAPS2) related subject, for example, geographic location or disease phenotype. These labels (one at a time) are used in displaying the clustering outcome of IPCAPS2. A label file must contain at least one column. However, it may contain more than one column in which case each column need to be separated by a space or a tab.
lab.col	The label in the label file to be used in the tree-like display of IPCAPS2 clustering results.
out	To set an absolute path for IPCAPS2 output. If the specified output directory already exists, result files are saved in sub-directories cluster_out, cluster_out1, cluster_out2, etc.
plot.as.pdf	To export plots as PDF. When omitted, plots are saved as PNG.
method	The internal clustering method. It can be set to "mix" (rubikclust & mixmod), "mixmod" (Lebret et al., 2015), "clara" (R: Clustering Large Applications), "pam" (R: Partitioning Around Medoids (PAM) Object), "meanshift" (Wang, 2016), "apcluster" (Bodenhofer et al., 2016), "hclust" (R: Hierarchical Clustering), kmeans (Hartigan et al., 1979), and dbscan (Ester et al. 1996). Default = "mix".
missing	Symbol used for missing genotypes. Default = NA.
covariate	A file of covariates; one covariate per column. SNPs can be adjusted for these covariates via regression modeling and residual computation.
cov.col.first	Refer to a covariate file, the first covariate to be considered as confounding variable.
cov.col.last	Refer to a covariate file, the last covariate to be considered as confounding variable. All the variables in between the cov.col.first and cov.col.last will be considered in the adjustment process.
threshold	Cutoff value for EigenFit. Possible values range from 0.03 to 0.18. The smaller, the potentially finer the substructure can be. Default = 0.18.
min.fst	Minimum Fst between a pair of subgroups. Default = 0.0008.
min.in.group	Minimum number of individuals to constitute a cluster or subgroup. Default = 20.
no.plot	No plot is generated if this option is TRUE. This option is useful when the system does not support X Windows in the unix based system. Default = FALSE.
data.type	To specify which type of input data between 'snp' and 'linear'. Default = 'snp'.
silence	To enable or disable silence mode. If silence mode is enabled, the fuction is processed without printing any message on the screen, and it is slightly faster. Default = TRUE.
max.thread	To specify a number of threads in order to run an analysis in parallel. If max.thread is specified more than the maximum number of CPU cores, then the maximum number of CPU cores are used instead. If max.thread is specified as floating point number, it will be rounded up using the function round(). Default = 0, which the maximum number of CPU cores are used.
no.rep	To specify a number of time to replicate the internal clustering. Default = 5,
cutoff.confident	To specify a cutoff for confident values. Default = 0.5.

Details

The computational time depends on the number of individuals. Consequentially, if large data sets are analyzed, it may be necessary first to split data into smaller files, and then load into computer memory (with parameter 'files'). Internally, the split files are merged to construct a com-prehensive matrix.

Value

Returns the list object containing 2 internal objects; output.dir as class character and cluster as class data.frame. The object output.dir stores a result directory. The object cluster contains 4 columns, group, node, label, and row.number. The column group contains the assigned groups from IPCAPS2. The column node contains node numbers in a tree as illustrated in the HTML result files. The column label contains the given labels that is set to the parameter label. The column row.number contains indices to an input data, which is matched to row numbers of input matrix. All clustering result files are saved in one directory (as specified by out) containing assigned groups, hierarchical trees of group membership, PC plots, and binary data for further analysis.

• $snp is a SNP matrix from BED file.

• $snp.info is a data.frame of SNP information from BIM file.

• $ind.info is a data.frame of individual information from FAM file.

If function return NULL, it means the input files are not in proper format.

References

Bodenhofer, U., Palme, J., Melkonian, C., and Kothmeier, A. (2016). apcluster : Affinity Propagation Clustering. Available at CRAN (Accessed March 7, 2017).

Intarapanich, A., Shaw, P. J., Assawamakin, A., Wangkumhang, P., Ngamphiw, C. , Chaichoompu, K., et al. (2009). Iterative pruning PCA improves resolution of highly structured populations. BMC Bioinformatics 10, 382. doi:10.1186/ 1471-2105-10-382.

Lebret, R., Iovleff, S., Langrognet, F., Biernacki, C., Celeux, G., and Govaert, G. (2015). Rmixmod: TheRPackage of the Model-Based Unsupervised, Supervised, and Semi-Supervised ClassificationMixmodLibrary. J. Stat. Softw. 67. doi:10.18637/jss.v067.i06.

Limpiti, T., Intarapanich, A., Assawamakin, A., Shaw, P. J., Wangkumhang, P., Piriyapongsa, J., et al. (2011). Study of large and highly stratified population datasets by combining iterative pruning principal component analysis and structure. BMC Bioinformatics 12, 255. doi:10.1186/1471-2105-12- 255.

Maechler, M., Rousseeuw, P., Struyf, A., Hubert, M., and Hornik, K. (2017). cluster: Cluster Analysis Basics and Extensions.

R: Clustering Large Applications Available at: ethz.ch (Accessed March 7, 2017).

R Core Team (2017). R: A Language and Environment for Statistical Computing. Vienna, Austria: R Foundation for Statistical Computing Available at: r-project.org.

R: Hierarchical Clustering Available at: ethz.ch (Accessed March 7, 2017).

R: Partitioning Around Medoids (PAM) Object Available at: ethz.ch (Accessed March 7, 2017).

Wang, M. C. and D. (2016). MeanShift: Clustering via the Mean Shift Algorithm. Available at: CRAN (Accessed March 7, 2017).

Examples

#Use the BED format as input
#Importantly, bed file, bim file, and fam file are required
#Use the example files embedded in the package

BED.file <- system.file("extdata", "ipcaps_example.bed", package = "IPCAPS2")
LABEL.file <- system.file("extdata", "ipcaps_example_individuals.txt.gz",
                          package = "IPCAPS2")
my.cluster1 <- ipcaps2(bed = BED.file, label.file = LABEL.file, lab.col = 2,
out = tempdir(),silence = TRUE , no.rep = 1)

table(my.cluster1$cluster$label, my.cluster1$cluster$group)

# Alternatively, use a text file as input
# Use the example files embedded in the package

#text.file <- system.file("extdata", "ipcaps_example_rowVar_colInd.txt.gz",
#                          package="IPCAPS2")
#LABEL.file <- system.file("extdata", "ipcaps_example_individuals.txt.gz",
#                           package="IPCAPS2")

#my.cluster2 <- ipcaps2(files = c(text.file), label.file = LABEL.file, lab.col = 2,
#                       out=tempdir(), ,silence=TRUE, no.rep=1)
#table(my.cluster2$cluster$label, my.cluster2$cluster$group)

# The other alternative way, use an R Data file as input
# Use the example file embedded in the package

#rdata.file <- system.file("extdata", "ipcaps_example.rda", package = "IPCAPS2")

#my.cluster3 <- ipcaps2(rdata = rdata.file, out = tempdir(), silence=TRUE, no.rep=1)
#table(my.cluster3$cluster$label, my.cluster3$cluster$group)

kridsadakorn/ipcaps2 documentation built on June 11, 2022, 8:35 p.m.