ipcaps: Perform unsupervised clustering to capture population...
In kridsadakorn/ipcaps.bioc: Iterative Pruning to Capture Population Structure

Description Usage Arguments Details Value References Examples

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 ipcaps 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).

ipcaps(
  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,
  seed = NA
)

`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: http://zzz.bwh.harvard.edu/plink/data.shtml.
`rdata`	In case of re-analysis, it is convenient to run ipcaps using the file rawdata.RData generated by ipcaps. This file contains a matrix of SNPs (raw.data) and a vector of labels (label).
`files`	If the data type is 'snp', ipcaps supports SNPs encoded as 0, 1 and 2 (dosage encoding). If the data type is 'linear', the data must be numeric and text and words are not allowed in the input files. Rows represent SNPs or features and columns represent individuals or 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 ipcaps) related subject, for example, geographic location or disease phenotype. These labels (one at a time) are used in displaying the clustering outcome of ipcaps. 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 ipcaps clustering results.
`out`	To set an absolute path for ipcaps 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), and 'hclust' (R: Hierarchical Clustering). 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.
`seed`	To specify a seed number for the function mixmod in the package Rmixmod. Default = NA, which means that a seed number is automatically chose.

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.

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 ipcaps. 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.

Bodenhofer, U., Palme, J., Melkonian, C., and Kothmeier, A. (2016). apcluster : Affinity Propagation Clustering. Available at: https://CRAN.R-project.org/package=apcluster (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: https://stat.ethz.ch/R-manual/R-devel/library/cluster/html/clara.html (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: https://www.R-project.org/.

R: Hierarchical Clustering Available at: https://stat.ethz.ch/R-manual/R-devel/library/stats/html/hclust.html (Accessed March 7, 2017).

R: Partitioning Around Medoids (PAM) Object Available at: https://stat.ethz.ch/R-manual/R-devel/library/cluster/html/pam.object.html (Accessed March 7, 2017).

Wang, M. C. and D. (2016). MeanShift: Clustering via the Mean Shift Algorithm. Available at: https://CRAN.R-project.org/package=MeanShift (Accessed March 7, 2017).

#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 = 'IPCAPS.BIOC')
LABEL.file <- system.file('extdata',
                          'ipcaps_example_individuals.txt.gz',
                          package = 'IPCAPS.BIOC')

my.cluster1 <- ipcaps(bed = BED.file,
                     label.file = LABEL.file,
                     lab.col = 2,
                     out = tempdir(),
                     max.thread = 1,
                     seed = 1234)

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

# 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 = 'IPCAPS.BIOC')

LABEL.file <- system.file('extdata',
                          'ipcaps_example_individuals.txt.gz',
                          package = 'IPCAPS.BIOC')

my.cluster2 <- ipcaps(files = c(text.file),
                      label.file = LABEL.file,
                      lab.col = 2,
                      out=tempdir(),
                      max.thread = 1,
                      seed = 1234)

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

# Use an R Data file as input
# Use the example file embedded in the package

rdata.file <- system.file('extdata',
                          'ipcaps_example.RData',
                          package = 'IPCAPS.BIOC')

my.cluster3 <- ipcaps(rdata = rdata.file,
                      out = tempdir(),
                      max.thread = 1,
                      seed = 1234)

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