Merge branch 'v0.2.2_development' into 58-error-at-least-80-of-man-pa…

…ges-documenting-exported-objects-must-have-runnable-examples

DESCRIPTION

@@ -9,7 +9,8 @@ Authors@R: c(
     person("Elana", "Fertig", role = "ctb", email = "[email protected]", comment = c(ORCID = "0000-0003-3204-342X")),
     person("Jennifer", "Elisseeff", role = "ctb", email = "[email protected]", comment = c(ORCID = "0000-0002-5066-1996"))
     )
-Description: Domino2 is a package developed to analyze cell signaling through ligand - receptor - transcription factor networks in scRNAseq data. It takes as input information transcriptomic data, requiring counts, z-scored counts, and cluster labels, as well as information on transcription factor activation (such as from SCENIC) and a database of ligand and receptor pairings (such as from cellphoneDB). This package creates an object storing ligand - receptor - transcription factor linkages by cluster and provides several methods for exploring, summarizing, and visualizing the analysis.
+Description: 
+    Domino2 is a package developed to analyze cell signaling through ligand - receptor - transcription factor networks in scRNAseq data. It takes as input information transcriptomic data, requiring counts, z-scored counts, and cluster labels, as well as information on transcription factor activation (such as from SCENIC) and a database of ligand and receptor pairings (such as from cellphoneDB). This package creates an object storing ligand - receptor - transcription factor linkages by cluster and provides several methods for exploring, summarizing, and visualizing the analysis.
 BugReports: https://github.com/FertigLab/domino_development/issues
 Depends:
     R(>= 3.6.2),

NAMESPACE

@@ -10,6 +10,16 @@ export(count_linkage)
 export(create_domino)
 export(create_regulon_list_scenic)
 export(create_rl_map_cellphonedb)
+export(dom_clusters)
+export(dom_correlations)
+export(dom_counts)
+export(dom_database)
+export(dom_de)
+export(dom_info)
+export(dom_linkages)
+export(dom_signaling)
+export(dom_tf_activation)
+export(dom_zscores)
 export(feat_heatmap)
 export(gene_network)
 export(incoming_signaling_heatmap)

R/import_fxns.R

@@ -44,7 +44,7 @@ create_rl_map_cellphonedb <- function(genes, proteins, interactions, complexes =
   if(alternate_convert & is.null(alternate_convert_table)) {
       stop("If using alternate conversion table (not recommended), a table must be provided")
   }
-  
+
   # Read in files if needed:
   if (is(genes, "character")) {
     genes <- read.csv(genes, stringsAsFactors = FALSE)
@@ -328,12 +328,12 @@ create_domino <- function(rl_map, features, ser = NULL, counts = NULL, z_scores
   }
   # Read in lr db info
   if (verbose) {
-    print("Reading in and processing signaling database")
+    message("Reading in and processing signaling database")
   }
   if ("database_name" %in% colnames(rl_map)) {
     dom@db_info <- rl_map
     if (verbose) {
-      print(paste0("Database provided from source: ", unique(rl_map[["database_name"]])))
+      message(paste0("Database provided from source: ", unique(rl_map[["database_name"]])))
     }
   } else {
     dom@db_info <- rl_map
@@ -400,7 +400,7 @@ create_domino <- function(rl_map, features, ser = NULL, counts = NULL, z_scores
   dom@misc[["rl_map"]] <- rl_reading
   # Get z-score and cluster info
   if (verbose) {
-    print("Getting z_scores, clusters, and counts")
+    message("Getting z_scores, clusters, and counts")
   }
   if (!is.null(ser)) {
     z_scores <- ser@assays$RNA@scale.data

R/utils.R

@@ -1 +1,163 @@
-#'
+#' Access database
+#' 
+#' A function to pull database information from a domino object
+#' 
+#' @param dom A domino object that has been created
+#' @param name_only A boolean for whether to return only the name of the database used 
+#'                  or the entire database that is stored. Default TRUE.
+#' @return  A vector of unique databases used in building the domino object OR 
+#'          a data frame that includes the database information used in the domino object creation
+#' @export
+
+dom_database <- function(dom, name_only = TRUE) {
+    db = slot(dom, "db_info")
+    if (name_only) {
+        return(unique(db$database_name))
+    } else {
+        return(db)
+    }
+}
+
+#' Access z-scores
+#' 
+#' A function to pull z-scored expression from a domino object
+#' 
+#' @param dom A domino object that has been created with [create_domino()]
+#' @return  A matrix containing the z-scored gene expression values for each gene (row) by cell (column)
+#' @export
+
+dom_zscores <- function(dom) {
+    slot(dom, "z_scores")
+}
+
+#' Access counts
+#' 
+#' A function to pull gene expression from a domino object
+#' 
+#' @param dom A domino object that has been created with [create_domino()]
+#' @return  A matrix containing the gene expression values for each gene (row) by cell (column)
+#' @export
+dom_counts <- function(dom) {
+    as.matrix(slot(dom, "counts"))
+}
+
+#' Access clusters
+#' 
+#' A function to pull cluster information from a domino object
+#' 
+#' @param dom A domino object that has been created with [create_domino()]
+#' @param labels A boolean for whether to return the cluster labels for each cell or the clusters used for inferring communication
+#' @return  A vector containing either the names of the clusters used OR factors of the cluster label for each individual cell
+#' @export
+
+dom_clusters <- function(dom, labels = FALSE) {
+    clust = slot(dom, "clusters")
+    if (labels) {
+        return(clust)
+    } else {
+        return(levels(clust))
+    }
+}
+
+#' Access transcription factor activation
+#' 
+#' A function to pull transcription factor activation scores from a domino object
+#' 
+#' @param dom A domino object that has been created with [create_domino()]
+#' @return  A matrix containing the transcription factor activation scores for each feature (row) by cell (column)
+#' @export
+dom_tf_activation <- function(dom) {
+    slot(dom, "features")
+}
+
+#' Access correlations
+#' 
+#' A function to pull receptor-transcription factor correlations from a domino object
+#' 
+#' @param dom A domino object that has been created with [create_domino()]
+#' @return  A matrix containing the correlation values for each receptor (row) by transcription factor (column)
+#' @export
+dom_correlations <- function(dom) {
+    slot(dom, "cor")
+}
+
+#' Access linkages
+#' 
+#' A function to pull linkages from a domino object
+#' 
+#' @param dom A domino object that has been created with [create_domino()]
+#' @param link_type One value (out of "complexes", "receptor-ligand", 
+#'                  "tf-target", "tf-receptor", "receptor", "incoming-ligand") used
+#'                  to select the desired type of linkage
+#' @param by_cluster A boolean to indicate whether the linkages should be returned overall or by cluster
+#' @return  A list containing linkages between some combination of receptors, ligands, transcription factors, and clusters
+#' @export
+dom_linkages <- function(dom, link_type = c("complexes", "receptor-ligand",
+                "tf-target", "tf-receptor", "receptor", "incoming-ligand"), by_cluster = FALSE) {
+    links = slot(dom, "linkages")
+    if (by_cluster) {
+        if (link_type == "tf-receptor") {
+            return(links$clust_tf)
+        } else if(link_type == "receptor") {
+            return(links$clust_rec) 
+        } else if(link_type == "incoming-ligand") {
+            return(links$clust_incoming_lig)
+        } else {
+            stop("This linkage type is not available")
+        }
+    } else {
+        if (link_type == "complexes") {
+            return(links$complexes)
+        } else if (link_type == "receptor-ligand") {
+            return(links$rec_lig)
+        } else if (link_type == "tf_targets") {
+            return(links$tf_targets)
+        } else if (link_type == "tf_receptor") {
+            return(links$tf_rec)
+        } else {
+            stop("This linkage type is not available.")
+        }
+    }
+}
+
+#' Access signaling
+#' 
+#' A function to pull signaling matrices from a domino object
+#' 
+#' @param dom A domino object that has been created with [create_domino()]
+#' @param cluster Either NULL to indicate global signaling or a specific cluster for which a
+#' @return  A data.frame containing the signaling score through each ligand (row) by each cluster (column) OR
+#'          a data.frame containing the global summed signaling scores between receptors (rows) and ligands (columns) of each cluster
+#' @export
+dom_signaling <- function(dom, cluster = NULL) {
+    if(is.null(cluster)) {
+        as.data.frame(slot(dom, "signaling"))
+    } else {
+        as.data.frame(slot(dom, "cl_signaling_matrices")[cluster])
+    }
+}
+
+#' Access differential expression
+#' 
+#' A function to pull differential expression p values from a domino object
+#' 
+#' @param dom A domino object that has been created with [create_domino()]
+#' @return  A matrix containing the p values for differential expression of transcription factors (rows) in each cluster (columns)
+#' @export
+dom_de <- function(dom) {
+    slot(dom, "clust_de")
+}
+
+#' Access build information
+#' 
+#' A function to pull the parameters used when running [build_domino()] from a domino object
+#' 
+#' @param dom A domino object that has been created with [create_domino()]
+#' @return  A list containing booleans for whether the object has been created and build, and a list of the
+#'          build parameters that were used in [build_domino()] to infer the signaling network
+#' @export
+dom_info <- function(dom) {
+    info = slot(dom, "misc")
+    return(list("create" = info$create, "build"= info$build, 
+        "build_variables"= info$build_vars))
+}

_pkgdown.yml

@@ -59,6 +59,19 @@ reference:
   - plot_differential_linkages
 - title: "Helper Functions"
   desc: "Convenience functions for working with Domino2 objects"
+- subtitle: "Access functions"
+  contents:
+  - dom_clusters
+  - dom_correlations
+  - dom_counts
+  - dom_database
+  - dom_de
+  - dom_info
+  - dom_linkages
+  - dom_signaling
+  - dom_tf_activation
+  - dom_zscores
+- subtitle: "Misc. utility functions"
   contents:
   - add_rl_column
   - collate_network_items