# The FEAST User’s Guide

# Installation and help

## Install FEAST

To install this package, start R (version > “4.0”) and enter:

    if(!requireNamespace("BiocManager", quietly = TRUE))
        install.packages("BiocManager")
    BiocManager::install("FEAST")

## Help for FEAST

If you have any FEAST-related questions, please post to the GitHub Issue section of FEAST at https://github.com/suke18/FEAST/issues, which will be helpful for the construction of FEAST.

# Introduction

## Background

Cell clustering is one of the most important and commonly performed tasks in single-cell RNA sequencing (scRNA-seq) data analysis. An important step in cell clustering is to select a subset of genes (referred to as “features”), whose expression patterns will then be used for downstream clustering. A good set of features should include the ones that distinguish different cell types, and the quality of such set could have significant impact on the clustering accuracy. All existing scRNA-seq clustering tools include a feature selection step relying on some simple unsupervised feature selection methods, mostly based on the statistical moments of gene-wise expression distributions. In this work, we develop a feature selection algorithm named FEAture SelecTion (FEAST), which provides more representative features.

## Citation

- For consensus clustering, cite Strehl and Ghosh (2002).
- For using (FEAST) feature selection procedure, Su et al. (2021)

## Quick start

We use `Yan` dataset(Yan et al. 2013) for the demonstration. This `Yan` dataset includes 6 cell types about human preimplantation embryos and embryonic stem cells. The users can run the FEAST or FEAST_fast function to obtain the gene rankings (from the most significant to the least significant genes) of These featured genes are deemed to better contribute to the clustering accuracy. Here, we demonstrate that some of the top 9 selected genes are very informative (or known as marker genes e.g., CYYR1 ).

    library(FEAST)
    data(Yan)
    k = length(unique(trueclass))
    Y = process_Y(Y, thre = 2)
    # The core function.
    ixs = FEAST(Y, k=k)
    # look at the features
    Ynorm = Norm_Y(Y)
    par(mfrow = c(3,3))
    for (i in 1:9){
      tmp_ix = ixs[i]
      tmp_gene = rownames(Ynorm)[tmp_ix]
      boxplot(as.numeric(Ynorm[tmp_ix, ])~trueclass, main = tmp_gene, xlab="", ylab="", las=2)
    }

# Using FEAST for scRNA-seq clustering analysis

FEAST requires a count expression matrix with rows representing the genes and columns representing the cells. To preprocess the count matrix, FEAST filters out the genes depending on the dropout rates (sometimes known as zero-expression rates). Alternatively, the users can input the normalized matrix (usually log transformed of relative abundance expression matrix (scaled by average sequencing depth)). Here, we use one template `Yan` (Yan et al. 2013) dataset. It is important to note that FEAST requires the number of clusters (k) as an input, which can be obtained by the prior knowledge of the cell types.

## Load the data

The `Yan` dataset is loaded with two objects including the count expression matrix (Y) and corresponding cell type information (trueclass). Other sample datasets can be downloaded at https://drive.google.com/drive/u/0/folders/1SRT7mrX7ziJoSjuFLLkK8kjnUsJrabVM. If the users want to use one Deng dataset(Deng et al. 2014), the users can load the data and access the phenotype information by using `colData(Deng)` function, and the count expression matrix by using `assay(Deng,"counts")` function from the SummarizedExperiment Bioconductor package.

    data(Yan)
    dim(Y)
    #> [1] 19304   124
    table(trueclass)
    #> trueclass
    #>  2-cell  4-cell  8-cell    hESC    Late Morulae  Oocyte  Zygote
    #>       6      12      20      34      30      16       3       3

## Consensus clustering

To preprocess the count expression matrix (`Y`), FEAST filters out the genes based on the dropout rate (sometimes known as zero-expression rate). This consensus clustering step will output the initial clustering labels based on a modified CSPA algorithm. It will find the cells that tightly clustered together and possibly filter out the cells that are less correlated to the initial clustering centers.

    Y = process_Y(Y, thre = 2) # preprocess the data if needed
    con_res = Consensus(Y, k=k)

## Calculate the gene-level significance

After the consensus clustering step, FEAST will generate the initial clustering labels with confidence. Based on the initial clustering outcomes, FEAST further infers the gene-level significance by using F-statistics followed by the ranking of the full list of genes.

    F_res = cal_F2(Y, con_res$cluster)
    ixs = order(F_res$F_scores, decreasing = TRUE) # order the features

## Clustering and validation

After ranking the genes by F-statistics, FEAST curates a series of top number of features (genes). Then, FEAST input these top (by default `top = 500, 1000, 2000`) features into some established clustering algorithm such as SC3 (Kiselev et al. 2017), which is regarded as the most accurate scRNA-seq clustering algorithm (Duò et al. 2018). It is worth noting that one needs to confirm the k to be the same for every iteration.

After the clustering steps, with the case of unknown cell types, FEAST evaluates the quality of the feature set by computing the average distance between each cell and the clustering centers, which is the same as the MSE. It is noting that FEAST uses all the features (genes) for distance calculation for the purpose of fair comparisons. The clustering centers are obtained by using previous clustering step.

It is noted that FEAST is not limited to SC3 clustering. It also shows superior performance on other clustering methods such as TSCAN. The code for running SC3 and TSCAN are embedded in FEAST package, which can be access by SC3_Clust and TSCAN_Clust.

    ## clustering step
    tops = c(500, 1000, 2000)
    cluster_res = NULL
    for (top in tops){
        tmp_ixs = ixs[1:top]
        tmp_markers = rownames(Y)[tmp_ixs]
        tmp_res = TSCAN_Clust(Y, k = k, input_markers = tmp_markers)
        #tmp_res = SC3_Clust(Y, k = k, input_markers = tmp_markers)
        cluster_res[[toString(top)]] = tmp_res
    }
    ## validation step
    Ynorm = Norm_Y(Y)
    mse_res = NULL
    for (top in names(cluster_res)){
        tmp_res = cluster_res[[top]]
        tmp_cluster = tmp_res$cluster
        tmp_mse = cal_MSE(Ynorm = Ynorm, cluster = tmp_cluster)
        mse_res = c(mse_res, tmp_mse)
    }
    names(mse_res) = names(cluster_res)

## Compare to the real cell type labels

### Benchmark with the original SC3

After the validation step, the feature set associated with the smallest MSE value will be recommended for the further analysis. Here, we demonstrate that an improved clustering accuracy by specifying the optimal feature set. The benchmark comparison is the original setting of established clustering algorithm (e.g. SC3).

    original = TSCAN_Clust(Y, k=k)
    id = which.min(mse_res)
    eval_Cluster(original$cluster, trueclass)
    eval_Cluster(cluster_res[[id]]$cluster, trueclass)

### Show the clustering improvement by using figures

As demonstrated in the figure below, the first panel includes the PCA illustration of the cell types. The second panel shows the clustering result by the original SC3, in which some cells (inside the gray circle) are mixed. The third panel shows the improved clustering outcomes by inputing the optimized feature set into SC3. This is an example for the `Deng` dataset.

# Quick use step-by-step

The users can run the `Consensus` function and then run the `Select_Model_short_SC3` function; however, `Consensus` step could take a while especially for the large dataset (sample size is greater than 2000).

    data(Yan)
    Y = process_Y(Y, thre = 2) # preprocess the data if needed
    con_res = Consensus(Y, k=k)
    mod_res = Select_Model_short_TSCAN(Y, cluster = con_res$cluster, top = c(200, 500, 1000, 2000))
    # mod_res = Select_Model_short_SC3(Y, cluster = con_res$cluster, top = c(200, 500, 1000, 2000))
    # to visualize the result, one needs to load ggpubr library.
    library(ggpubr)
    PP = Visual_Rslt(model_cv_res = mod_res, trueclass = trueclass)
    #> Warning in .f(y = .l[[1L]][[i]], data = .l[[2L]][[i]], x = .l[[3L]][[i]], : The
    #> 'size' parameter for lines is deprecated in ggplot2 3.4.0+. Please use
    #> 'linewidth' instead to avoid this warning in future versions.
    print(PP$ggobj) # show the visualization plot.

The result figure shows that the MSE validation process is concordant with the clustering accuracy trend. It demonstrated that using top 1000 featured genes can result in the highest clustering accuracy with improvement than the original setting.

# Quick use by the wrapper function

To quickly obtain the ranking orders of the features, the users can directly apply `FEAST` function, which works perfectly fun on small dataset. For the large dataset, the users can consider change the dimention reduction method to irlba by specifying `dim_reduce="irlba"`. Moreover, the users can resort to `FEAST_fast` function for fast calculation on the large datasets. For extreme large dataset (sample size >5000), it will split the dataset equally into chucks and apply FEAST algorithm in parallel on individual splitted datasets. In this case, the users need to specify two parameters `split = TRUE`, and `batch_size = 1000` corresponding to the splitted size.

    ixs = FEAST(Y, k=k)
    #ixs = FEAST_fast(Y, k=k)
    #ixs = FEAST_fast(Y, k=k, split=TRUE, batch_size = 1000)

# Session Info

    sessionInfo()
    #> R version 4.6.0 (2026-04-24)
    #> Platform: x86_64-pc-linux-gnu
    #> Running under: Ubuntu 24.04.4 LTS
    #>
    #> Matrix products: default
    #> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    #> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
    #>
    #> locale:
    #>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    #>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
    #>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    #>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    #>  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    #> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    #>
    #> time zone: Etc/UTC
    #> tzcode source: system (glibc)
    #>
    #> attached base packages:
    #> [1] stats4    stats     graphics  grDevices utils     datasets  methods
    #> [8] base
    #>
    #> other attached packages:
    #>  [1] ggpubr_0.6.3                ggplot2_4.0.3
    #>  [3] FEAST_1.20.0                SummarizedExperiment_1.42.0
    #>  [5] Biobase_2.72.0              GenomicRanges_1.64.0
    #>  [7] Seqinfo_1.2.0               IRanges_2.46.0
    #>  [9] S4Vectors_0.50.0            BiocGenerics_0.58.0
    #> [11] generics_0.1.4              MatrixGenerics_1.24.0
    #> [13] matrixStats_1.5.0           BiocParallel_1.46.0
    #> [15] mclust_6.1.2                BiocStyle_2.40.0
    #>
    #> loaded via a namespace (and not attached):
    #>   [1] bitops_1.0-9                rlang_1.2.0
    #>   [3] magrittr_2.0.5              otel_0.2.0
    #>   [5] e1071_1.7-17                compiler_4.6.0
    #>   [7] mgcv_1.9-4                  vctrs_0.7.3
    #>   [9] combinat_0.0-8              pkgconfig_2.0.3
    #>  [11] fastmap_1.2.0               backports_1.5.1
    #>  [13] XVector_0.52.0              labeling_0.4.3
    #>  [15] caTools_1.18.3              promises_1.5.0
    #>  [17] rmarkdown_2.31              TSCAN_1.50.0
    #>  [19] purrr_1.2.2                 xfun_0.57
    #>  [21] WriteXLS_6.8.0              cachem_1.1.0
    #>  [23] jsonlite_2.0.0              later_1.4.8
    #>  [25] DelayedArray_0.38.0         broom_1.0.12
    #>  [27] irlba_2.3.7                 parallel_4.6.0
    #>  [29] cluster_2.1.8.2             R6_2.6.1
    #>  [31] bslib_0.10.0                RColorBrewer_1.1-3
    #>  [33] car_3.1-5                   rrcov_1.7-7
    #>  [35] jquerylib_0.1.4             Rcpp_1.1.1-1.1
    #>  [37] iterators_1.0.14            knitr_1.51
    #>  [39] httpuv_1.6.17               Matrix_1.7-5
    #>  [41] splines_4.6.0               igraph_2.3.0
    #>  [43] tidyselect_1.2.1            abind_1.4-8
    #>  [45] yaml_2.3.12                 doParallel_1.0.17
    #>  [47] gplots_3.3.0                codetools_0.2-20
    #>  [49] doRNG_1.8.6.3               lattice_0.22-9
    #>  [51] tibble_3.3.1                plyr_1.8.9
    #>  [53] withr_3.0.2                 shiny_1.13.0
    #>  [55] S7_0.2.2                    ROCR_1.0-12
    #>  [57] evaluate_1.0.5              proxy_0.4-29
    #>  [59] TrajectoryUtils_1.20.0      pillar_1.11.1
    #>  [61] BiocManager_1.30.27         carData_3.0-6
    #>  [63] rngtools_1.5.2              SC3_1.40.0
    #>  [65] KernSmooth_2.23-26          foreach_1.5.2
    #>  [67] pcaPP_2.0-5                 scales_1.4.0
    #>  [69] fastICA_1.2-7               gtools_3.9.5
    #>  [71] xtable_1.8-8                class_7.3-23
    #>  [73] glue_1.8.1                  pheatmap_1.0.13
    #>  [75] maketools_1.3.2             tools_4.6.0
    #>  [77] robustbase_0.99-7           sys_3.4.3
    #>  [79] ggsignif_0.6.4              buildtools_1.0.0
    #>  [81] mvtnorm_1.3-7               cowplot_1.2.0
    #>  [83] grid_4.6.0                  tidyr_1.3.2
    #>  [85] SingleCellExperiment_1.34.0 nlme_3.1-169
    #>  [87] Formula_1.2-5               cli_3.6.6
    #>  [89] S4Arrays_1.12.0             dplyr_1.2.1
    #>  [91] gtable_0.3.6                DEoptimR_1.1-4
    #>  [93] ggsci_5.0.0                 rstatix_0.7.3
    #>  [95] sass_0.4.10                 digest_0.6.39
    #>  [97] SparseArray_1.12.0          farver_2.1.2
    #>  [99] htmltools_0.5.9             lifecycle_1.0.5
    #> [101] mime_0.13

# Reference

Deng, Qiaolin, Daniel Ramsköld, Björn Reinius, and Rickard Sandberg. 2014. “Single-Cell RNA-Seq Reveals Dynamic, Random Monoallelic Gene Expression in Mammalian Cells.” Science 343 (6167): 193–96.
Duò, Angelo, Mark D Robinson, and Charlotte Soneson. 2018. “A Systematic Performance Evaluation of Clustering Methods for Single-Cell RNA-Seq Data.” F1000Research 7.
Kiselev, Vladimir Yu, Kristina Kirschner, Michael T Schaub, et al. 2017. “SC3: Consensus Clustering of Single-Cell RNA-Seq Data.” Nature Methods 14 (5): 483–86.
Strehl, Alexander, and Joydeep Ghosh. 2002. “Cluster Ensembles—a Knowledge Reuse Framework for Combining Multiple Partitions.” Journal of Machine Learning Research 3 (Dec): 583–617.
Su, Kenong, Tianwei Yu, and Hao Wu. 2021. “Accurate Feature Selection Improves Single-Cell RNA-Seq Cell Clustering.” Briefings in Bioinformatics.
Yan, Liying, Mingyu Yang, Hongshan Guo, et al. 2013. “Single-Cell RNA-Seq Profiling of Human Preimplantation Embryos and Embryonic Stem Cells.” Nature Structural & Molecular Biology 20 (9): 1131.