Added compute_label option

Author: drisso

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: mbkmeans
 Type: Package
 Title: Mini-batch K-means Clustering for Single-Cell RNA-seq
-Version: 1.3.1
+Version: 1.3.2
 Authors@R:
     c(person("Yuwei", "Ni", role = c("aut", "cph"),
              email = "yuweini45@gmail.com"),
@@ -38,7 +38,7 @@ Suggests:
 License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 6.1.1
+RoxygenNote: 7.0.2
 LinkingTo: 
     Rcpp, 
     RcppArmadillo (>= 0.7.2),

R/RcppExports.R

@@ -73,8 +73,10 @@ compute_wcss <- function(clusters, cent, data) {
 #'  number between 0.0 and 1.0.
 #'@param initializer the method of initialization. One of \emph{kmeans++} and
 #'  \emph{random}. See details for more information.
+#'@param compute_labels logical indicating whether to compute the final cluster
+#'  labels.
 #'@param calc_wcss logical indicating whether the within-cluster sum of squares
-#'  should be computed and returned.
+#'  should be computed and returned (ignored if `compute_labels = FALSE`).
 #'@param early_stop_iter continue that many iterations after calculation of the
 #'  best within-cluster-sum-of-squared-error.
 #'@param verbose logical indicating whether progress is printed on screen.
@@ -87,12 +89,14 @@ compute_wcss <- function(clusters, cent, data) {
 #'
 #'centroids: the final centroids;
 #'
-#'WCSS_per_cluster: within-cluster sum of squares;
+#'WCSS_per_cluster (optional): the final per-cluster WCSS.
 #'
 #'best_initialization: which initialization value led to the best WCSS
 #'solution;
 #'
-#'iters_per_initialization: number of iterations per each initialization.
+#'iters_per_initialization: number of iterations per each initialization;
+#'
+#'Clusters (optional): the final cluster labels.
 #'
 #'@details This function performs k-means clustering using mini batches. It was
 #'inspired by the implementation in https://github.com/mlampros/ClusterR.
@@ -121,7 +125,7 @@ compute_wcss <- function(clusters, cent, data) {
 #'mini_batch(data, 2, 10, 10)
 #'
 #' @export
-mini_batch <- function(data, clusters, batch_size, max_iters, num_init = 1L, init_fraction = 1.0, initializer = "kmeans++", calc_wcss = FALSE, early_stop_iter = 10L, verbose = FALSE, CENTROIDS = NULL, tol = 1e-4) {
-    .Call(`_mbkmeans_mini_batch`, data, clusters, batch_size, max_iters, num_init, init_fraction, initializer, calc_wcss, early_stop_iter, verbose, CENTROIDS, tol)
+mini_batch <- function(data, clusters, batch_size, max_iters, num_init = 1L, init_fraction = 1.0, initializer = "kmeans++", compute_labels = TRUE, calc_wcss = FALSE, early_stop_iter = 10L, verbose = FALSE, CENTROIDS = NULL, tol = 1e-4) {
+    .Call(`_mbkmeans_mini_batch`, data, clusters, batch_size, max_iters, num_init, init_fraction, initializer, compute_labels, calc_wcss, early_stop_iter, verbose, CENTROIDS, tol)
 }
 

R/kmeans.R

@@ -122,8 +122,10 @@ setMethod(
 #'  \emph{random}. See details for more information
 #'@param early_stop_iter continue that many iterations after calculation of the
 #'  best within-cluster-sum-of-squared-error
-#'@param calc_wcss either TRUE or FALSE, indicating whether the result of WCSS
-#'  is shown. FALSE is default
+#'@param compute_labels logcical indicating whether to compute the final cluster
+#'  labels.
+#'@param calc_wcss logical indicating whether the per-cluster WCSS
+#'  is computed. Ignored if `compute_labels = FALSE`.
 #'@param verbose either TRUE or FALSE, indicating whether progress is printed
 #'  during clustering
 #'@param CENTROIDS a matrix of initial cluster centroids. The rows of the
@@ -156,7 +158,7 @@ setMethod(
                                             ceiling(ncol(x)*.05), ncol(x)),
                         max_iters =100, num_init = 1,
                         init_fraction = ifelse(ncol(x)>100, .25, 1),
-                        initializer = "kmeans++",
+                        initializer = "kmeans++", compute_labels = TRUE,
                         calc_wcss = FALSE, early_stop_iter = 10,
                         verbose = FALSE,
                         CENTROIDS = NULL, tol = 1e-4)
@@ -171,7 +173,9 @@ setMethod(
                             batch_size = batch_size, max_iters = max_iters,
                             num_init = num_init,
                             init_fraction = init_fraction,
-                            initializer = initializer, calc_wcss = calc_wcss,
+                            initializer = initializer, 
+                            compute_labels = compute_labels,
+                            calc_wcss = calc_wcss,
                             early_stop_iter = early_stop_iter,
                             verbose = verbose,
                             CENTROIDS = CENTROIDS, tol = tol)

inst/NEWS

@@ -1,3 +1,9 @@
+Version 1.3.2 (2020-02-04)
+=====================================
+
+- Added option `compute_labels=TRUE` to optionally avoid computing labels and 
+  return only the centroids.
+
 Version 0.99.0 (2019-03-08)
 =====================================
 

man/mbkmeans.Rd

@@ -32,8 +32,8 @@ BEGIN_RCPP
 END_RCPP
 }
 // mini_batch
-Rcpp::List mini_batch(SEXP data, int clusters, int batch_size, int max_iters, int num_init, double init_fraction, std::string initializer, bool calc_wcss, int early_stop_iter, bool verbose, Rcpp::Nullable<Rcpp::NumericMatrix> CENTROIDS, double tol);
-RcppExport SEXP _mbkmeans_mini_batch(SEXP dataSEXP, SEXP clustersSEXP, SEXP batch_sizeSEXP, SEXP max_itersSEXP, SEXP num_initSEXP, SEXP init_fractionSEXP, SEXP initializerSEXP, SEXP calc_wcssSEXP, SEXP early_stop_iterSEXP, SEXP verboseSEXP, SEXP CENTROIDSSEXP, SEXP tolSEXP) {
+Rcpp::List mini_batch(SEXP data, int clusters, int batch_size, int max_iters, int num_init, double init_fraction, std::string initializer, bool compute_labels, bool calc_wcss, int early_stop_iter, bool verbose, Rcpp::Nullable<Rcpp::NumericMatrix> CENTROIDS, double tol);
+RcppExport SEXP _mbkmeans_mini_batch(SEXP dataSEXP, SEXP clustersSEXP, SEXP batch_sizeSEXP, SEXP max_itersSEXP, SEXP num_initSEXP, SEXP init_fractionSEXP, SEXP initializerSEXP, SEXP compute_labelsSEXP, SEXP calc_wcssSEXP, SEXP early_stop_iterSEXP, SEXP verboseSEXP, SEXP CENTROIDSSEXP, SEXP tolSEXP) {
 BEGIN_RCPP
     Rcpp::RObject rcpp_result_gen;
     Rcpp::RNGScope rcpp_rngScope_gen;
@@ -44,20 +44,21 @@ BEGIN_RCPP
     Rcpp::traits::input_parameter< int >::type num_init(num_initSEXP);
     Rcpp::traits::input_parameter< double >::type init_fraction(init_fractionSEXP);
     Rcpp::traits::input_parameter< std::string >::type initializer(initializerSEXP);
+    Rcpp::traits::input_parameter< bool >::type compute_labels(compute_labelsSEXP);
     Rcpp::traits::input_parameter< bool >::type calc_wcss(calc_wcssSEXP);
     Rcpp::traits::input_parameter< int >::type early_stop_iter(early_stop_iterSEXP);
     Rcpp::traits::input_parameter< bool >::type verbose(verboseSEXP);
     Rcpp::traits::input_parameter< Rcpp::Nullable<Rcpp::NumericMatrix> >::type CENTROIDS(CENTROIDSSEXP);
     Rcpp::traits::input_parameter< double >::type tol(tolSEXP);
-    rcpp_result_gen = Rcpp::wrap(mini_batch(data, clusters, batch_size, max_iters, num_init, init_fraction, initializer, calc_wcss, early_stop_iter, verbose, CENTROIDS, tol));
+    rcpp_result_gen = Rcpp::wrap(mini_batch(data, clusters, batch_size, max_iters, num_init, init_fraction, initializer, compute_labels, calc_wcss, early_stop_iter, verbose, CENTROIDS, tol));
     return rcpp_result_gen;
 END_RCPP
 }
 
 static const R_CallMethodDef CallEntries[] = {
     {"_mbkmeans_predict_mini_batch", (DL_FUNC) &_mbkmeans_predict_mini_batch, 2},
     {"_mbkmeans_compute_wcss", (DL_FUNC) &_mbkmeans_compute_wcss, 3},
-    {"_mbkmeans_mini_batch", (DL_FUNC) &_mbkmeans_mini_batch, 12},
+    {"_mbkmeans_mini_batch", (DL_FUNC) &_mbkmeans_mini_batch, 13},
     {NULL, NULL, 0}
 };
 

man/mini_batch.Rd

@@ -338,8 +338,10 @@ Rcpp::NumericVector compute_wcss(Rcpp::NumericVector clusters, Rcpp::NumericMatr
 //'  number between 0.0 and 1.0.
 //'@param initializer the method of initialization. One of \emph{kmeans++} and
 //'  \emph{random}. See details for more information.
+//'@param compute_labels logical indicating whether to compute the final cluster
+//'  labels.
 //'@param calc_wcss logical indicating whether the within-cluster sum of squares
-//'  should be computed and returned.
+//'  should be computed and returned (ignored if `compute_labels = FALSE`).
 //'@param early_stop_iter continue that many iterations after calculation of the
 //'  best within-cluster-sum-of-squared-error.
 //'@param verbose logical indicating whether progress is printed on screen.
@@ -352,12 +354,14 @@ Rcpp::NumericVector compute_wcss(Rcpp::NumericVector clusters, Rcpp::NumericMatr
 //'
 //'centroids: the final centroids;
 //'
-//'WCSS_per_cluster: within-cluster sum of squares;
+//'WCSS_per_cluster (optional): the final per-cluster WCSS.
 //'
 //'best_initialization: which initialization value led to the best WCSS
 //'solution;
 //'
-//'iters_per_initialization: number of iterations per each initialization.
+//'iters_per_initialization: number of iterations per each initialization;
+//'
+//'Clusters (optional): the final cluster labels.
 //'
 //'@details This function performs k-means clustering using mini batches. It was
 //'inspired by the implementation in https://github.com/mlampros/ClusterR.
@@ -390,6 +394,7 @@ Rcpp::NumericVector compute_wcss(Rcpp::NumericVector clusters, Rcpp::NumericMatr
 Rcpp::List mini_batch(SEXP data, int clusters, int batch_size, int max_iters,
                     int num_init = 1, double init_fraction = 1.0,
                     std::string initializer = "kmeans++",
+                    bool compute_labels = true,
                     bool calc_wcss = false, int early_stop_iter = 10,
                     bool verbose = false,
                     Rcpp::Nullable<Rcpp::NumericMatrix> CENTROIDS = R_NilValue,
@@ -655,14 +660,19 @@ Rcpp::List mini_batch(SEXP data, int clusters, int batch_size, int max_iters,
 
   }
 
-
-  Rcpp::NumericVector clusterfinal = predict_mini_batch(data, Rcpp::wrap(centers_out));
+  Rcpp::NumericVector clusterfinal;
   Rcpp::NumericVector wcss_final;
+  
+  if(compute_labels) {
 
-  if(calc_wcss){
-      wcss_final = compute_wcss(clusterfinal,Rcpp::wrap(centers_out),data);
+    clusterfinal = predict_mini_batch(data, Rcpp::wrap(centers_out));
+    if(calc_wcss){
+        wcss_final = compute_wcss(clusterfinal, Rcpp::wrap(centers_out), data);
+    }
+    
   }
 
+
       return Rcpp::List::create(Rcpp::Named("centroids") = centers_out,
                                 Rcpp::Named("WCSS_per_cluster") = wcss_final,
                                 Rcpp::Named("best_initialization") = end_init,