Display UMAP of Community Membership with text overlays

Usage

make_network_umap(
  membership_matrix,
  community_memb_cut_main = 0.7,
  community_n_main = 20,
  community_memb_cut_secondary = 0.8,
  community_n_secondary = 5,
  gene_memb_cut_main = 0.75,
  gene_memb_cut_secondary = 0.65,
  community_labels = NULL,
  umap_specs = umap::umap.defaults
)

Arguments

membership_matrix: a community membership (kME) matrix with genes as rows and communities as columns. Often community_membership or full_community_membership output from icwgcna()
community_memb_cut_main: main cutoff of a membership score threshold for filtering out communities to include in the plot. Any communities with less than community_n_main number of genes greater than community_memb_cut_main are filtered out.
community_n_main: the number of genes that must have membership scores great than community_memb_cut_main in order for a community to be kept in the plot.
community_memb_cut_secondary: cutoff of a membership score threshold for filtering genes to include in the plot. Any communities with less than community_n_secondary number of genes greater than community_memb_cut_secondary are filtered out.
community_n_secondary: the number of genes that must have membership scores great than community_memb_cut_secondary in order for a community to be kept in the plot.
gene_memb_cut_main: main cutoff of a membership score threshold for filtering genes to include in the plot. Any genes with an absolute membership score greater than gene_memb_cut_main in any community is included
gene_memb_cut_secondary: secondary cutoff of a membership score threshold for filtering genes to include in the plot. Any genes with an absolute membership score greater than gene_memb_cut_main in more than 1 community is included
community_labels: a data.frame with the text to display over gene communities. Expects first column to match column names of membership_matrix and second column to contain text of labels associated with each community
umap_specs: configuration for UMAP (default is umap::umap.defaults). To use custom specs copy umap::umap.defaults and make specific changes (see Examples)

Value

Returns a list with the following items:

umap_w_annotation - a UMAP plot of genes with labeled clusters overlaid
umap_w_legend - a UMAP plot of genes with a legend and no overlaid labels
layout - the UMAP layout to enable customized user plotting

Filtering

In order to facilitate viewing, communities and genes are filtered prior to plotting. Gene filtering is performed after community filtering.

For inclusion either the main or secondary parameters can be satisfied. For example, using the defaults here a community must have either 20 genes over 0.7 kME or 5 genes over 0.8 kME to be included. After community filtering, gene filtering is performed. Again using the defaults here, a gene must have at least one community over 0.75 kME or two communities over 0.65 kME to be included.

Setting community_memb_cut_main and gene_memb_cut_main to 0 will force all communities and genes to be included in the UMAP

Output

Both umap_w_annotation and umap_w_legend outputs are ggplot objects, so plot details can easily be added or modified (i.e. umap_results$umap_w_legend + theme_classic()).

Examples

if (FALSE) { # \dontrun{
library("UCSCXenaTools")
luad <- getTCGAdata(
  project = "LUAD", mRNASeq = TRUE, mRNASeqType = "normalized",
  clinical = FALSE, download = TRUE
)
ex <- as.matrix(data.table::fread(luad$destfiles), rownames = 1)
results <- icwgcna(ex)

umap_results <- make_network_umap(results$community_membership)
umap_results$umap_w_annotation
umap_results$umap_w_legend + theme(legend.position = 'top')

# can adjust umap specifications
custom_umap_specs <- umap::umap.defaults
custom_umap_specs$n_neighbors <- 20

umap_results <- make_network_umap(results$community_membership,
                                  umap_specs = custom_umap_specs)
} # }