diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 03e2c6ba..6231d5ea 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -22,7 +22,7 @@ jobs: permissions: contents: write steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - uses: r-lib/actions/setup-pandoc@v2 @@ -41,7 +41,7 @@ jobs: - name: Deploy to GitHub pages 🚀 if: github.event_name != 'pull_request' - uses: JamesIves/github-pages-deploy-action@v4.4.1 + uses: JamesIves/github-pages-deploy-action@v4.5.0 with: clean: false branch: gh-pages diff --git a/DESCRIPTION b/DESCRIPTION index 372e879b..74f3dd61 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -11,7 +11,7 @@ Authors@R: c( person("Jennifer", "Elisseeff", role = "ctb", email = "jhe@jhu.edu", comment = c(ORCID = "0000-0002-5066-1996")) ) Description: - dominoSignal 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. + dominoSignal 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/dominoSignal/issues Depends: R(>= 4.2.0), diff --git a/NAMESPACE b/NAMESPACE index 5b41425e..8a15d501 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -32,6 +32,8 @@ export(summarize_linkages) export(test_differential_linkages) exportClasses(domino) exportClasses(linkage_summary) +exportMethods(print) +exportMethods(show) import(ComplexHeatmap) import(biomaRt) import(circlize) diff --git a/NEWS.md b/NEWS.md index ad565e86..bceed691 100644 --- a/NEWS.md +++ b/NEWS.md @@ -6,9 +6,9 @@ ## Bioconductor Standards -- Update to Vignettes presenting application of the DominoSignal pipeline on data formatted as a SingleCellExperiment object +- Update to vignettes presenting application of the DominoSignal pipeline on data formatted as a SingleCellExperiment object - Implemented caching of example data by BiocCache to meet package size limits -- Removal of depreciated scripts for running SCENIC. Tutorials for running SCENIC are still present in vignettes +- Removal of deprecated scripts for running SCENIC. Tutorials for running SCENIC are still present in vignettes - Corrected BiocCheck notes pertaining to coding practices including paste in conditional statements, functions with dontrun examples, usage of seq_len or seq_along in place of seq, and usage of vapply in place of sapply @@ -24,17 +24,17 @@ - Plotting function for differential linkages ## Package structure -- Adjustments made to meet BioConductor standards +- Adjustments made to meet Bioconductor standards # dominoSignal v0.2.1 ## Updates to domino object construction -- Uniform formats for inputs of receptor-ligand interaction databases, transcription factor activity features, and regulon gene lists for operability with alternative databases and transcription factor activation inference methods +- Uniform formats for inputs of receptor - ligand interaction databases, transcription factor activity features, and regulon gene lists for operability with alternative databases and transcription factor activation inference methods - Helper functions for reformatting pySCENIC outputs and CellPhoneDB database files to domino-readable uniform formats - Assessment of transcription factor linkage with receptors that function as a heteromeric complex based on correlation between transcription factor activity and all receptor component genes - Assessment of complex ligand expression as the mean of component gene expression for plotting functions - Minimum threshold for the percentage of cells in a cluster expressing a receptor gene for the receptor to be called active within the cluster -- Additional linkage slots for active receptors in each cluster, transcription factor-receptor linkages for each cluster, and incoming ligands for active receptors on each cluster +- Additional linkage slots for active receptors in each cluster, transcription factor - receptor linkages for each cluster, and incoming ligands for active receptors on each cluster ## Plotting functions - Chord plot of ligand expression targeting a specified receptor where chord widths correspond to the quantity of ligand expression by each cell cluster @@ -43,7 +43,7 @@ ## Bugfixes - Added host option for gene ortholog conversions using `{biomaRt}` for access to maintained mirrors -- Transcription factor-target linkages are now properly stored so that receptors in a transcription factor's regulon are excluded from linkage +- Transcription factor - target linkages are now properly stored so that receptors in a transcription factor's regulon are excluded from linkage - Ligand nodes sizes in gene networks correspond to quantity of ligand expression - `create_domino()` can be run without providing a regulon list - References to the host GitHub repository have been updated to [Elisseeff-Lab](https://github.com/Elisseeff-Lab/domino) diff --git a/R/class_definitions.R b/R/class_definitions.R index 3693abbd..13137525 100644 --- a/R/class_definitions.R +++ b/R/class_definitions.R @@ -2,18 +2,18 @@ #' @importClassesFrom Matrix dgCMatrix #' NULL -#' The domino Class +#' The domino class #' #' The domino class contains all information necessary to calculate receptor-ligand #' signaling. It contains z-scored expression, cell cluster labels, feature values, #' and a referenced receptor-ligand database formatted as a receptor-ligand map. #' Calculated intermediate values are also stored. #' -#' @slot db_info List of data sets from lr database. +#' @slot db_info List of data sets from ligand - receptor database #' @slot counts Raw count gene expression data #' @slot z_scores Matrix of z-scored expression data with cells as columns #' @slot clusters Named factor with cluster identity of each cell -#' @slot features Matrix of features to correlate receptor-ligand expression with. Cells are columns and features are rows. +#' @slot features Matrix of features (TFs) to correlate receptor - ligand expression with. Cells are columns and features are rows. #' @slot cor Correlation matrix of receptor expression to features. #' @slot linkages List of lists containing info linking cluster->tf->rec->lig #' @slot clust_de Data frame containing differential expression results for features by cluster. @@ -23,7 +23,7 @@ NULL #' @name domino-class #' @rdname domino-class #' @exportClass domino -#' @return an instance of class `domino ` +#' @return An instance of class `domino ` #' domino <- methods::setClass( Class = "domino", @@ -74,9 +74,9 @@ linkage_summary <- setClass( #' #' Prints a summary of a domino object #' -#' @param x Domino object -#' @return a printed description of the number of cell clusters in the object -#' @keywords internal +#' @param x A domino object +#' @return A printed description of the number of cells and clusters in the domino object +#' @export #' @examples #' print(dominoSignal:::pbmc_dom_built_tiny) #' @@ -84,12 +84,12 @@ setMethod("print", "domino", function(x, ...) { if (x@misc$build) { message( "A domino object of ", length(x@clusters), " cells - Contains signaling between", - length(levels(x@clusters)), "clusters - Built with a maximum of", as.integer(x@misc$build_vars["max_tf_per_clust"]), - "TFs per cluster - and a maximum of", as.integer(x@misc$build_vars["max_rec_per_tf"]), - "receptors per TF\n" + Contains signaling between ", + length(levels(x@clusters)), " clusters + Built with a maximum of ", x@misc$build_vars["max_tf_per_clust"], + " TFs per cluster + and a maximum of ", x@misc$build_vars["max_rec_per_tf"], + " receptors per TF\n" ) } else { message(c("A domino object of ", length(x@clusters), " cells\n", "A signaling network has not been built\n"), @@ -101,9 +101,9 @@ setMethod("print", "domino", function(x, ...) { #' #' Shows content overview of domino object #' -#' @param object Domino object -#' @return a printed description of the number of cells in a domino object and its build status -#' @keywords internal +#' @param object A domino object +#' @return A printed description of cell numbers and clusters in the object +#' @export #' @examples #' dominoSignal:::pbmc_dom_built_tiny #' diff --git a/R/convenience_fxns.R b/R/convenience_fxns.R index fa75c837..dc0c8b85 100644 --- a/R/convenience_fxns.R +++ b/R/convenience_fxns.R @@ -5,17 +5,11 @@ NULL #' Renames clusters in a domino object #' -#' This function reads in a receptor ligand signaling database, cell level -#' features of some kind (ie. output from pySCENIC), z-scored single cell data, -#' and cluster id for single cell data, calculates a correlation matrix between -#' receptors and other features (this is transcription factor module scores if -#' using pySCENIC), and finds features enriched by cluster. It will return a -#' domino object prepared for [build_domino()], which will calculate a signaling -#' network. +#' This function renames the clusters used to build a domino object #' -#' @param dom Domino object to rename clusters in -#' @param clust_conv Named vector of conversions from old to new clusters. Values are taken as new clusters IDs and names as old cluster IDs. -#' @param warning Logical. If TRUE, will warn if a cluster is not found in the conversion table. Default is FALSE. +#' @param dom a domino object to rename clusters in +#' @param clust_conv named vector of conversions from old to new clusters. Values are taken as new clusters IDs and names as old cluster IDs. +#' @param warning logical. If TRUE, will warn if a cluster is not found in the conversion table. Default is FALSE. #' @return A domino object with clusters renamed in all applicable slots. #' @export #' @examples @@ -73,17 +67,17 @@ rename_clusters <- function(dom, clust_conv, warning = FALSE) { } -#' Convert Genes Using Table +#' Convert genes using a table #' -#' Takes a vector of gene inputs and a conversion table and returns a +#' Takes a vector of gene inputs and a conversion table and returns a #' converted gene table #' -#' @param genes The genes to convert. -#' @param from Gene symbol type of the input (ENSG, ENSMUSG, HGNC, MGI) -#' @param to Desired gene symbol type for the output (HGNC, MGI) -#' @param conversion_table A data.frame with column names corresponding to gene symbol types (mm.ens, hs.ens, mgi, hgnc) +#' @param genes the genes to convert +#' @param from gene symbol type of the input (ENSG, ENSMUSG, HGNC, MGI) +#' @param to desired gene symbol type for the output (HGNC, MGI) +#' @param conversion_table a data frame with column names corresponding to gene symbol types (mm.ens, hs.ens, mgi, hgnc) #' and rows corresponding to the gene symbols themselves -#' @return Data frame of genes with original and corresponding converted symbols +#' @return A data frame of genes with original and corresponding converted symbols #' @keywords internal #' table_convert_genes <- function(genes, from, to, conversion_table) { diff --git a/R/differential_fxns.R b/R/differential_fxns.R index aaafb35c..70e2bde2 100644 --- a/R/differential_fxns.R +++ b/R/differential_fxns.R @@ -4,12 +4,12 @@ NULL #' Summarize linkages from multiple domino objects #' -#' Creates a linkage_summary object storing the linkages learned in different domino objects as nested lists to facilitate comparisons of networks learned by domino across subject covariates. +#' Creates a [linkage_summary()] object storing the linkages learned in different domino objects as nested lists to facilitate comparisons of networks learned by domino across subject covariates. #' -#' @param domino_results list of domino result with one domino object per subject. Names from the list must match subject_names. -#' @param subject_meta dataframe that includes the subject features by which the objects could be grouped. The first column should must be subject names +#' @param domino_results list of domino result with one domino object per subject. Names from the list must match subject_names +#' @param subject_meta data frame that includes the subject features by which the objects could be grouped. The first column should must be subject names #' @param subject_names vector of subject names in domino_results. If NULL, defaults to first column of subject_meta. -#' @return A linkage summary class object consisting of nested lists of the active transcription factors, active receptors, and incoming ligands for each cluster across multiple domino results. +#' @return A linkage summary class object consisting of nested lists of the active transcription factors, active receptors, and incoming ligands for each cluster across multiple domino results #' @export #' @examples #' dom_ls <- dominoSignal:::dom_ls_tiny @@ -99,12 +99,12 @@ summarize_linkages <- function(domino_results, subject_meta, subject_names = NUL #' #' Count occurrences of linkages across multiple domino results from a linkage summary #' -#' @param linkage_summary a linkage_summary object +#' @param linkage_summary a [linkage_summary()] object #' @param cluster the name of the cell cluster being compared across multiple domino results -#' @param group.by the name of the column in linkage_summary\@subject_meta by which to group subjects for counting. If NULL, only total counts of linkages for linkages in the cluster across all subjects is given. -#' @param linkage a stored linkage from the domino object. Can compare ('tfs', 'rec', 'incoming_lig', 'tfs_rec', 'rec_lig') +#' @param group.by the name of the column in `linkage_summary@subject_meta` by which to group subjects for counting. If NULL, only total counts of linkages for linkages in the cluster across all subjects is given. +#' @param linkage a stored linkage from the domino object. Can compare any of 'tfs', 'rec', 'incoming_lig', 'tfs_rec', or 'rec_lig' #' @param subject_names a vector of subject_names from the linkage_summary to be compared. If NULL, all subject_names in the linkage summary are included in counting. -#' @return a data frame with columns for the unique linkage features and the counts of how many times the linkage occured across the compared domino results. If group.by is used, counts of the linkages are also provided as columns named by the unique values of the group.by variable. +#' @return A data frame with columns for the unique linkage features and the counts of how many times the linkage occured across the compared domino results. If group.by is used, counts of the linkages are also provided as columns named by the unique values of the group.by variable. #' @export #' @examples #' count_linkage( @@ -145,16 +145,16 @@ count_linkage <- function(linkage_summary, cluster, group.by = NULL, linkage = " #' #' Statistical test for differential linkages across multiple domino results #' -#' @param linkage_summary a linkage_summary object +#' @param linkage_summary a [linkage_summary()] object #' @param cluster the name of the cell cluster being compared across multiple domino results -#' @param group.by the name of the column in linkage_summary\@subject_meta by which to group subjects for counting. -#' @param linkage a stored linkage from the domino object. Can compare ('tfs', 'rec', 'incoming_lig', 'tfs_rec', 'rec_lig') +#' @param group.by the name of the column in `linkage_summary@subject_meta` by which to group subjects for counting. +#' @param linkage a stored linkage from the domino object. Can compare any of 'tfs', 'rec', 'incoming_lig', 'tfs_rec', or 'rec_lig' #' @param subject_names a vector of subject_names from the linkage_summary to be compared. If NULL, all subject_names in the linkage summary are included in counting. #' @param test_name the statistical test used for comparison. #' \itemize{ #' \item{'fishers.exact'} : Fisher's exact test for the dependence of the proportion of subjects with an active linkage in the cluster on which group the subject belongs to in the group.by variable. Provides an odds ratio, p-value, and a Benjamini-Hochberg FDR-adjusted p-value (p.adj) for each linkage tested. #' } -#' @return a data frame of results from the test of the differential linkages. Rows correspond to each linkage tested. Columns correspond to: +#' @return A data frame of results from the test of the differential linkages. Rows correspond to each linkage tested. Columns correspond to: #' \itemize{ #' \item{'cluster'} : the name of the cell cluster being compared #' \item{'linkage'} : the type of linkage being compared diff --git a/R/import_fxns.R b/R/import_fxns.R index bf357c24..5ac636d4 100644 --- a/R/import_fxns.R +++ b/R/import_fxns.R @@ -6,14 +6,14 @@ #' NULL -#' Create a receptor-ligand map from a cellphonedb signaling database +#' Create a receptor - ligand map from a CellPhoneDB signaling database #' #' Generates a data frame of ligand-receptor interactions from a CellPhoneDB database annotating the genes encoding the interacting ligands and receptors to be queried in transcriptomic data. #' -#' @param genes dataframe or file path to table of gene names in uniprot, hgnc_symbol, or ensembl format in cellphonedb database format -#' @param proteins dataframe or file path to table of protein features in cellphonedb format -#' @param interactions dataframe or file path to table of protein-protein interactions in cellphonedb format -#' @param complexes optional: dataframe or file path to table of protein complexes in cellphonedb format +#' @param genes data frame or file path to table of gene names in uniprot, hgnc_symbol, or ensembl format in CellPhoneDB database format +#' @param proteins data frame or file path to table of protein features in CellPhoneDB format +#' @param interactions data frame or file path to table of protein-protein interactions in CellPhoneDB format +#' @param complexes optional: data frame or file path to table of protein complexes in CellPhoneDB format #' @param database_name name of the database being used, stored in output #' @param gene_conv a tuple of (from, to) or (source, target) if gene conversion to orthologs is desired; options are ENSMUSG, ENSG, MGI, or HGNC #' @param gene_conv_host host for conversion; default ensembl, could also use mirrors if desired @@ -238,7 +238,7 @@ create_rl_map_cellphonedb <- function( #' #' Generates a list of transcription factors and the genes targeted by the transcription factor as part of their regulon inferred by pySCENIC #' -#' @param regulons Dataframe or file path to the table of the output of the grn (gene regulatory network) function from pySCENIC +#' @param regulons Data frame or file path to the table of the output of the ctx function from pySCENIC #' @return A list where names are transcription factors and the stored values are character vectors of genes in the inferred regulons #' @export create_regulon_list_scenic #' @examples @@ -574,9 +574,9 @@ create_domino <- function( #' #' @param genes Vector of genes to convert. #' @param from Format of gene input (ENSMUSG, ENSG, MGI, or HGNC) -#' @param to Format of gene output (MGI, or HGNC) +#' @param to Format of gene output (MGI or HGNC) #' @param host Host to connect to. Defaults to https://www.ensembl.org following the useMart default, but can be changed to archived hosts if useMart fails to connect. -#' @return A data frame with input genes as col 1 and output as col 2 +#' @return A data frame with input genes as column 1 and converted genes as column 2 #' @keywords internal #' convert_genes <- function( @@ -662,7 +662,7 @@ add_rl_column <- function(map, map_ref, conv, new_name) { new_map <- data.frame(new_map, stringsAsFactors = FALSE) } -#' Calculate mean ligand expression as a data.frame for plotting in circos plot +#' Calculate mean ligand expression as a data frame for plotting in circos plot #' #' Creates a data frame of mean ligand expression for use in plotting a circos #' plot of ligand expression and saving tables of mean expression. diff --git a/R/plot_fxns.R b/R/plot_fxns.R index cc0e2257..71537248 100644 --- a/R/plot_fxns.R +++ b/R/plot_fxns.R @@ -10,23 +10,24 @@ NULL #' Create a network heatmap #' #' Creates a heatmap of the signaling network. Alternatively, the network -#' matrix can be accessed directly in the signaling slot of a domino object. +#' matrix can be accessed directly in the signaling slot of a domino object using +#' the [dom_signaling()] function. #' -#' @param dom Domino object with network built ([build_domino()]) -#' @param clusts Vector of clusters to be included. If NULL then all clusters are used. -#' @param min_thresh Minimum signaling threshold for plotting. Defaults to -Inf for no threshold. -#' @param max_thresh Maximum signaling threshold for plotting. Defaults to Inf for no threshold. -#' @param scale How to scale the values (after thresholding). Options are 'none', 'sqrt' for square root, or 'log' for log10. -#' @param normalize Options to normalize the matrix. Normalization is done after thresholding and scaling. Accepted inputs are 'none' for no normalization, 'rec_norm' to normalize to the maximum value with each receptor cluster, or 'lig_norm' to normalize to the maximum value within each ligand cluster -#' @param ... Other parameters to pass to [ComplexHeatmap::Heatmap()] -#' @return a Heatmap rendered to the active graphics device +#' @param dom domino object with network built ([build_domino()]) +#' @param clusts vector of clusters to be included. If NULL then all clusters are used. +#' @param min_thresh minimum signaling threshold for plotting. Defaults to -Inf for no threshold. +#' @param max_thresh maximum signaling threshold for plotting. Defaults to Inf for no threshold. +#' @param scale how to scale the values (after thresholding). Options are 'none', 'sqrt' for square root, or 'log' for log10. +#' @param normalize options to normalize the matrix. Normalization is done after thresholding and scaling. Accepted inputs are 'none' for no normalization, 'rec_norm' to normalize to the maximum value with each receptor cluster, or 'lig_norm' to normalize to the maximum value within each ligand cluster +#' @param ... other parameters to pass to [ComplexHeatmap::Heatmap()] +#' @return A heatmap rendered to the active graphics device #' @export signaling_heatmap #' @examples -#' #basic usage +#' # basic usage #' signaling_heatmap(dominoSignal:::pbmc_dom_built_tiny) -#' #scale +#' # scale #' signaling_heatmap(dominoSignal:::pbmc_dom_built_tiny, scale = "sqrt") -#' #normalize +#' # normalize #' signaling_heatmap(dominoSignal:::pbmc_dom_built_tiny, normalize = "rec_norm") #' signaling_heatmap <- function( @@ -172,27 +173,27 @@ incoming_signaling_heatmap <- function( #' #' Creates a network diagram of signaling between clusters. Nodes are clusters #' and directed edges indicate signaling from one cluster to another. Edges are -#' colored based on the color scheme of the ligand expressing cluster. +#' colored based on the color scheme of the ligand expressing cluster #' -#' @param dom Domino object with network built ([build_domino()]) -#' @param cols Named vector indicating the colors for clusters. Values are colors and names must match clusters in the domino object. If left as NULL then ggplot colors are generated for the clusters. -#' @param edge_weight Weight for determining thickness of edges on plot. Signaling values are multiplied by this value. -#' @param clusts Vector of clusters to be included in the network plot. -#' @param showOutgoingSignalingClusts Vector of clusters to plot the outgoing signaling from -#' @param showIncomingSignalingClusts Vector of clusters to plot the incoming signaling on -#' @param min_thresh Minimum signaling threshold. Values lower than the threshold will be set to the threshold. Defaults to -Inf for no threshold. -#' @param max_thresh Maximum signaling threshold for plotting. Values higher than the threshold will be set to the threshold. Defaults to Inf for no threshold. -#' @param normalize Options to normalize the signaling matrix. Accepted inputs are 'none' for no normalization, 'rec_norm' to normalize to the maximum value with each receptor cluster, or 'lig_norm' to normalize to the maximum value within each ligand cluster -#' @param scale How to scale the values (after thresholding). Options are 'none', 'sqrt' for square root, 'log' for log10, or 'sq' for square. -#' @param layout Type of layout to use. Options are 'random', 'sphere', 'circle', 'fr' for Fruchterman-Reingold force directed layout, and 'kk' for Kamada Kawai for directed layout. -#' @param scale_by How to size vertices. Options are 'lig_sig' for summed outgoing signaling, 'rec_sig' for summed incoming signaling, and 'none'. In the former two cases the values are scaled with asinh after summing all incoming or outgoing signaling. -#' @param vert_scale Integer used to scale size of vertices with our without variable scaling from size_verts_by. -#' @param plot_title Text for the plot's title. -#' @param ... Other parameters to be passed to plot when used with an igraph object. -#' @return an igraph rendered to the active graphics device +#' @param dom a domino object with network built ([build_domino()]) +#' @param cols named vector indicating the colors for clusters. Values are colors and names must match clusters in the domino object. If left as NULL then ggplot colors are generated for the clusters +#' @param edge_weight weight for determining thickness of edges on plot. Signaling values are multiplied by this value +#' @param clusts vector of clusters to be included in the network plot +#' @param showOutgoingSignalingClusts vector of clusters to plot the outgoing signaling from +#' @param showIncomingSignalingClusts vector of clusters to plot the incoming signaling on +#' @param min_thresh minimum signaling threshold. Values lower than the threshold will be set to the threshold. Defaults to -Inf for no threshold +#' @param max_thresh maximum signaling threshold for plotting. Values higher than the threshold will be set to the threshold. Defaults to Inf for no threshold +#' @param normalize options to normalize the signaling matrix. Accepted inputs are 'none' for no normalization, 'rec_norm' to normalize to the maximum value with each receptor cluster, or 'lig_norm' to normalize to the maximum value within each ligand cluster +#' @param scale how to scale the values (after thresholding). Options are 'none', 'sqrt' for square root, 'log' for log10, or 'sq' for square +#' @param layout type of layout to use. Options are 'random', 'sphere', 'circle', 'fr' for Fruchterman-Reingold force directed layout, and 'kk' for Kamada Kawai for directed layout +#' @param scale_by how to size vertices. Options are 'lig_sig' for summed outgoing signaling, 'rec_sig' for summed incoming signaling, and 'none'. In the former two cases the values are scaled with asinh after summing all incoming or outgoing signaling +#' @param vert_scale integer used to scale size of vertices with our without variable scaling from size_verts_by. +#' @param plot_title text for the plot's title. +#' @param ... other parameters to be passed to plot when used with an igraph object. +#' @return An igraph plot rendered to the active graphics device #' @export signaling_network #' @examples -#' #basic usage +#' # basic usage #' signaling_network(dominoSignal:::pbmc_dom_built_tiny) #' # scaling, thresholds, layouts, selecting clusters #' signaling_network( @@ -337,11 +338,11 @@ signaling_network <- function( #' @param cols Named vector of colors for individual genes. Genes not included in this vector will be colored according to class_cols. #' @param lig_scale FALSE or a numeric value to scale the size of ligand vertices based on z-scored expression in the data set. #' @param layout Type of layout to use. Options are 'grid', 'random', 'sphere', 'circle', 'fr' for Fruchterman-Reingold force directed layout, and 'kk' for Kamada Kawai for directed layout. -#' @param ... Other parameters to pass to plot() with an [igraph] object. See [igraph] manual for options. -#' @return an igraph rendered to the active graphics device +#' @param ... Other parameters to pass to plot() with an [igraph](https://r.igraph.org/) object. See [igraph](https://r.igraph.org/) manual for options. +#' @return An igraph plot rendered to the active graphics device #' @export gene_network #' @examples -#' #basic usage +#' # basic usage #' gene_network( #' dominoSignal:::pbmc_dom_built_tiny, clust = "CD8_T_cell", #' OutgoingSignalingClust = "CD14_monocyte") @@ -486,8 +487,7 @@ gene_network <- function(dom, clust = NULL, OutgoingSignalingClust = NULL, #' Create a heatmap of features organized by cluster #' -#' Creates a heatmap of feature expression (typically transcription factor -#' activation scores) by cells organized by cluster. +#' Creates a heatmap of transcription factor activation scores by cells grouped by cluster. #' #' @param dom Domino object with network built ([build_domino()]) #' @param bool Boolean indicating whether the heatmap should be continuous or boolean. If boolean then bool_thresh will be used to determine how to define activity as positive or negative. @@ -495,17 +495,17 @@ gene_network <- function(dom, clust = NULL, OutgoingSignalingClust = NULL, #' @param title Either a string to use as the title or a boolean describing whether to include a title. In order to pass the 'main' parameter to [ComplexHeatmap::Heatmap()] you must set title to FALSE. #' @param norm Boolean indicating whether or not to normalize the transcrption factors to their max value. #' @param feats Either a vector of features to include in the heatmap or 'all' for all features. If left NULL then the features selected for the signaling network will be shown. -#' @param ann_cols Boolean indicating whether to include cell cluster as a column annotation. Colors can be defined with cols. If FALSE then custom annotations can be passed to NMF. +#' @param ann_cols Boolean indicating whether to include cell cluster as a column annotation. Colors can be defined with cols. If FALSE then custom annotations can be passed to [ComplexHeatmap::Heatmap()]. #' @param cols Named vector of colors to annotate cells by cluster color. Values are taken as colors and names as cluster. If left as NULL then default ggplot colors will be generated. #' @param min_thresh Minimum threshold for color scaling if not a boolean heatmap #' @param max_thresh Maximum threshold for color scaling if not a boolean heatmap #' @param ... Other parameters to pass to [ComplexHeatmap::Heatmap()] . Note that to use the 'main' parameter of [ComplexHeatmap::Heatmap()] you must set title = FALSE and to use 'annCol' or 'annColors' ann_cols must be FALSE. -#' @return a Heatmap rendered to the active graphics device +#' @return A heatmap rendered to the active graphics device #' @export feat_heatmap #' @examples -#' #basic usage +#' # basic usage #' feat_heatmap(dominoSignal:::pbmc_dom_built_tiny) -#' #using thresholds +#' # using thresholds #' feat_heatmap( #' dominoSignal:::pbmc_dom_built_tiny, min_thresh = 0.1, #' max_thresh = 0.6, norm = TRUE, bool = FALSE) @@ -624,14 +624,14 @@ feat_heatmap <- function( #' @param recs Either a vector of receptors to include in the heatmap or 'all' for all receptors. If left NULL then the receptors selected in the signaling network connected to the features plotted will be shown. #' @param mark_connections Boolean indicating whether to add an 'x' in cells where there is a connected receptor or TF. Default FALSE. #' @param ... Other parameters to pass to [ComplexHeatmap::Heatmap()] . Note that to use the 'main' parameter of [ComplexHeatmap::Heatmap()] you must set title = FALSE and to use 'annCol' or 'annColors' ann_cols must be FALSE. -#' @return a Heatmap rendered to the active graphics device +#' @return A heatmap rendered to the active graphics device #' @export cor_heatmap #' @examples -#' #basic usage +#' # basic usage #' cor_heatmap(dominoSignal:::pbmc_dom_built_tiny, title = "PBMC R-TF Correlations") -#' #show correlations above a specific value +#' # show correlations above a specific value #' cor_heatmap(dominoSignal:::pbmc_dom_built_tiny, bool = TRUE, bool_thresh = 0.25) -#' #identify combinations that are connected +#' # identify combinations that are connected #' cor_heatmap(dominoSignal:::pbmc_dom_built_tiny, bool = FALSE, mark_connections = TRUE) #' cor_heatmap <- function( @@ -711,16 +711,16 @@ cor_heatmap <- function( } } -#' Create a correlation plot between transcription factor activation score and receptor +#' Create a correlation plot between TF and receptor #' -#' Create a correlation plot between transcription factor activation score and receptor +#' Create a correlation plot between transcription factor activation score and receptor expression #' #' @param dom Domino object with network built ([build_domino()]) -#' @param tf Target TF module for plotting with receptor -#' @param rec Target receptor for plotting with TF -#' @param remove_rec_dropout Whether to remove cells with zero expression for plot. This should match the same setting as in build_domino. -#' @param ... Other parameters to pass to ggscatter. -#' @return a ggplot object +#' @param tf Target TF for plottting AUC score +#' @param rec Target receptor for plotting expression +#' @param remove_rec_dropout Whether to remove cells with zero expression for plot. This should match the same setting as in [build_domino()]. +#' @param ... Other parameters to pass to [ggpubr::ggscatter()]. +#' @return A ggplot scatter plot rendered in the active graphics device #' @export cor_scatter #' @examples #' cor_scatter(dominoSignal:::pbmc_dom_built_tiny, "FLI1","CXCR3") @@ -749,7 +749,7 @@ cor_scatter <- function(dom, tf, rec, remove_rec_dropout = TRUE, ...) { #' @param ligand_expression_threshold Minimum mean expression value of a ligand by a cell type for a chord to be rendered between the cell type and the receptor #' @param cell_idents Vector of cell types from cluster assignments in the domino object to be included in the plot. #' @param cell_colors Named vector of color names or hex codes where names correspond to the plotted cell types and the color values -#' @return renders a circos plot to the active graphics device +#' @return Renders a circos plot to the active graphics device #' @export circos_ligand_receptor #' @examples #' #basic usage @@ -882,12 +882,12 @@ circos_ligand_receptor <- function( #' #' Plot differential linkages among domino results ranked by a comparative statistic #' -#' @param differential_linkages a data.frame output from the test_differential_linkages function +#' @param differential_linkages a data frame output from the [test_differential_linkages()] function #' @param test_statistic column name of differential_linkages where the test statistic used for ranking linkages is stored (ex. 'p.value') #' @param stat_range a two value vector of the minimum and maximum values of test_statistic for plotting linkage features #' @param stat_ranking 'ascending' (lowest value of test statisic is colored red and plotted at the top) or 'descending' (highest value of test statistic is colored red and plotted at the top). #' @param group_palette a named vector of colors to use for each group being compared -#' @return a Heatmap-class object of features ranked by test_statistic annotated with the proportion of subjects that showed active linkage of the features. +#' @return A heatmap-class object of features ranked by test_statistic annotated with the proportion of subjects that showed active linkage of the features. #' @export #' @examples #' plot_differential_linkages( @@ -975,7 +975,7 @@ plot_differential_linkages <- function( #' Normalizes a matrix to its max value by row or column #' #' @param mat Matrix to be normalized -#' @param dir Direction to normalize the matrix c('row', 'col') +#' @param dir Direction to normalize the matrix (either "row" for row or "col" for column) #' @return A normalized matrix in the direction specified. #' @keywords internal #' diff --git a/R/processing_fxns.R b/R/processing_fxns.R index c68532bb..0ecfc9c0 100644 --- a/R/processing_fxns.R +++ b/R/processing_fxns.R @@ -4,11 +4,11 @@ #' preprocessed from create_domino and returns a domino object prepared for #' plotting with the various plotting functions in this package. #' -#' @param dom Domino object from create_domino. +#' @param dom Domino object from [create_domino()]. #' @param max_tf_per_clust Maximum number of transcription factors called active in a cluster. #' @param min_tf_pval Minimum p-value from differential feature score test to call a transcription factor active in a cluster. #' @param max_rec_per_tf Maximum number of receptors to link to each transcription factor. -#' @param rec_tf_cor_threshold Minimum pearson correlation used to consider a receptor linked with a transcription factor. Increasing this will decrease the number of receptors linked to each transcription factor. +#' @param rec_tf_cor_threshold Minimum Spearman correlation used to consider a receptor linked with a transcription factor. Increasing this will decrease the number of receptors linked to each transcription factor. #' @param min_rec_percentage Minimum percentage of cells in cluster expressing a receptor for the receptor to be linked to trancription factors in that cluster. #' @return A domino object with a signaling network built #' @export diff --git a/R/utils.R b/R/utils.R index 1fdc88a5..ca1c0cba 100644 --- a/R/utils.R +++ b/R/utils.R @@ -2,8 +2,8 @@ #' #' 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 +#' @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 @@ -25,7 +25,7 @@ dom_database <- function(dom, name_only = TRUE) { #' #' A function to pull z-scored expression from a domino object #' -#' @param dom A domino object that has been created with [create_domino()] +#' @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 #' @examples @@ -39,7 +39,7 @@ dom_zscores <- function(dom) { #' #' A function to pull gene expression from a domino object #' -#' @param dom A domino object that has been created with [create_domino()] +#' @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 #' @examples @@ -53,8 +53,8 @@ dom_counts <- function(dom) { #' #' 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 +#' @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 #' @examples @@ -74,8 +74,8 @@ dom_clusters <- function(dom, labels = FALSE) { #' #' 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) +#' @param dom a domino object that has been created with [create_domino()] +#' @return A matrix containing the transcription factor activation scores for each TF (row) by cell (column) #' @export #' @examples #' tf_activation <- dom_tf_activation(dominoSignal:::pbmc_dom_built_tiny) @@ -88,8 +88,8 @@ dom_tf_activation <- function(dom) { #' #' A function to pull receptor-transcription factor correlations from a domino object #' -#' @param dom A domino object that has been created with [create_domino()] -#' @param type Either "rl" or "complex", to select between the receptor-ligand or complex correlation matrix +#' @param dom a domino object that has been created with [create_domino()] +#' @param type either "rl" or "complex", to select between the receptor-ligand or complex correlation matrix #' @return A matrix containing the correlation values for each receptor (row) by transcription factor (column) #' @export #' @examples @@ -111,11 +111,11 @@ dom_correlations <- function(dom, type = "rl") { #' #' 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", +#' @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 +#' @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 #' @examples @@ -156,10 +156,10 @@ dom_linkages <- function(dom, link_type = c( #' #' 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 +#' @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 signaling matrix is desired +#' @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 #' @examples #' monocyte_signaling <- dom_signaling(dominoSignal:::pbmc_dom_built_tiny, cluster = "CD14_monocyte") @@ -174,10 +174,10 @@ dom_signaling <- function(dom, cluster = NULL) { #' Access differential expression #' -#' A function to pull differential expression p values from a domino object +#' 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) +#' @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 #' @examples #' de_mat <- dom_de(dominoSignal:::pbmc_dom_built_tiny) @@ -190,8 +190,8 @@ dom_de <- function(dom) { #' #' 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 +#' @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 built and a list of the #' build parameters that were used in [build_domino()] to infer the signaling network #' @export #' @examples @@ -212,9 +212,9 @@ dom_info <- function(dom) { #' comparing signaling networks across two separate conditions. In order to run #' this [build_domino()] must be run on the object previously. #' -#' @param dom Domino object containing a signaling network (i.e. [build_domino()] was run) -#' @param return String indicating where to collate "features", "receptors", or "ligands". If "all" then a list of all three will be returned. -#' @param clusters Vector indicating clusters to collate network items from. If left as NULL then all clusters will be included. +#' @param dom a domino object containing a signaling network (i.e. [build_domino()] was run) +#' @param return string indicating whether to collate "features", "receptors", or "ligands". If "all" then a list of all three will be returned. +#' @param clusters vector indicating clusters to collate network items from. If left as NULL then all clusters will be included. #' @return A vector containing all features, receptors, or ligands in the data set or a list containing all three. #' @export #' @examples @@ -261,18 +261,18 @@ dom_network_items <- function(dom, clusters = NULL, return = NULL) { #' Check input arguments #' -#' Accepts an object and rules for checking, stops if rules not met. +#' Accepts an object and rules to check against; stops if requirements are not met #' -#' @param arg The argument to check -#' @param allow_class Vector of allowed classes -#' @param allow_len Vector of allowed lengths +#' @param arg the argument to check +#' @param allow_class vector of allowed classes +#' @param allow_len vector of allowed lengths #' @param allow_range range of minimum and maximum values i.e. c(1, 5) -#' @param allow_values Vector of allowed values -#' @param need_vars Vector of required variables -#' @param need_colnames Logical for whether colnames are required -#' @param need_rownames Logical for whether rownames are required -#' @param need_names Logical for whether names are required -#' @return logical +#' @param allow_values vector of allowed values +#' @param need_vars vector of required variables +#' @param need_colnames vogical for whether colnames are required +#' @param need_rownames logical for whether rownames are required +#' @param need_names logical for whether names are required +#' @return Logical indicating whether the argument meets the requirements #' @keywords internal #' check_arg <- function(arg, allow_class = NULL, allow_len = NULL, @@ -336,10 +336,10 @@ check_arg <- function(arg, allow_class = NULL, allow_len = NULL, } -#' Read in data if an object looks like path to it. +#' Read in data if an object looks like path to it #' -#' @param obj Object to read if not already object -#' @return obj Object itself in case its not a character +#' @param obj object to read if not already object +#' @return Object itself or data read in from path #' @keywords internal read_if_char <- function(obj) { if (is(obj, "character")) { @@ -351,8 +351,8 @@ read_if_char <- function(obj) { #' Change cases of True/False syntax from Python to TRUE/FALSE R syntax #' -#' @param obj Object that will be converted -#' @return obj The converted object +#' @param obj object that will be converted +#' @return The converted object #' @keywords internal conv_py_bools <- function(obj) { for (x in colnames(obj)) { diff --git a/README.md b/README.md index 61e64e5b..684583e9 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ remotes::install_github('FertigLab/dominoSignal') Here is an overview of how dominoSignal might be used in analysis of a single cell RNA sequencing data set: 1. Transcription factor activation scores are calculated (we recommend using [pySCENIC](https://pyscenic.readthedocs.io/en/latest/), but other methods can be used as well) -2. A ligand-receptor database is used to map linkages between ligands and receptors (we recommend using [CellphoneDB](https://www.cellphonedb.org/), but other methods can be used as well). +2. A ligand-receptor database is used to map linkages between ligands and receptors (we recommend using [CellPhoneDB](https://www.cellphonedb.org/), but other methods can be used as well). 3. A domino object is created using counts, z-scored counts, clustering information, and the data from steps 1 and 2. 4. Parameters such as the maximum number of transcription factors and receptors or the minimum correlation threshold (among others) are used to make a cell communication network 5. Communication networks can be extracted from within the domino object or visualized using a variety of plotting functions diff --git a/_pkgdown.yml b/_pkgdown.yml index a37dbaa6..423e7b90 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -32,6 +32,8 @@ reference: and produced in dominoSignal analysis contents: - domino-class + - print,domino-method + - show,domino-method - linkage_summary - title: "Analysis Functions" desc: > @@ -95,7 +97,7 @@ navbar: menu: - text: SCENIC for TF Scoring href: vignettes/articles/tf_scenic_vignette.html - - text: Using CellphoneDB + - text: Using CellPhoneDB href: vignettes/articles/cellphonedb_vignette.html - text: Domino Object Structure href: vignettes/domino_object_vignette.html @@ -127,6 +129,8 @@ news: one_page: true cran_dates: false releases: + - text: "dominoSignal v0.99.2" + href: https://github.com/FertigLab/dominoSignal/releases/tag/v0.99.2-alpha - text: "dominoSignal v0.2.1" href: https://github.com/FertigLab/dominoSignal/releases/tag/v0.2.1-alpha - text: "dominoSignal v0.2.2" diff --git a/docs/404.html b/docs/404.html index 18c6168b..89f18289 100644 --- a/docs/404.html +++ b/docs/404.html @@ -33,7 +33,7 @@ dominoSignal - 0.99.1 + 0.99.2