diff --git a/DESCRIPTION b/DESCRIPTION index 4b163f4f..a3914f08 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: miaViz Title: Microbiome Analysis Plotting and Visualization -Version: 1.13.6 +Version: 1.13.7 Authors@R: c(person(given = "Tuomas", family = "Borman", role = c("aut", "cre"), email = "tuomas.v.borman@utu.fi", diff --git a/NEWS b/NEWS index 55bc6a9a..125ba21c 100644 --- a/NEWS +++ b/NEWS @@ -31,3 +31,4 @@ Changes in version 1.13.x + add plotNMDS to miaViz (plotNMDS deprecated in mia) + Added getNeatOrder function + plotAbundance: enable plotting without agglomeration ++ Change parameter naming convention from parameter_name to parameter.name diff --git a/R/plotAbundance.R b/R/plotAbundance.R index 66eb0288..5c0b27cd 100644 --- a/R/plotAbundance.R +++ b/R/plotAbundance.R @@ -7,7 +7,7 @@ #' #' Subsetting to rows of interested and ordering of those is expected to be done #' outside of this functions, e.g. \code{x[1:2,]}. This will plot data of all -#' features present. +#' col.var present. #' #' @param x a #' \code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}} @@ -24,47 +24,54 @@ #' (Please use \code{assay.type} instead. At some point \code{assay_name} #' will be disabled.) #' -#' @param features a single \code{character} value defining a column from +#' @param col.var a single \code{character} value defining a column from #' \code{colData} to be plotted below the abundance plot. #' Continuous numeric values will be plotted as point, whereas factors and -#' character will be plotted as colour-code bar. (default: \code{features = +#' character will be plotted as colour-code bar. (default: \code{col.var = #' NULL}) #' -#' @param order_rank_by How to order abundance value: By name (\dQuote{name}) +#' @param features Deprecated. Use \code{col.var} instead. +#' +#' @param order.row.by How to order abundance value: By name (\dQuote{name}) #' for sorting the taxonomic labels alphabetically, by abundance (\dQuote{abund}) to #' sort by abundance values or by a reverse order of abundance values (\dQuote{revabund}). -#' +#' +#' @param order_rank_by Deprecated. Use \code{order.row.by} instead. #' -#' @param order_sample_by A single character value from the chosen rank of abundance +#' @param order.col.by A single character value from the chosen rank of abundance #' data or from \code{colData} to select values to order the abundance -#' plot by. (default: \code{order_sample_by = NULL}) +#' plot by. (default: \code{order.col.by = NULL}) +#' +#' @param order_sample_by Deprecated. Use \code{order.col.by} instead. #' -#' @param decreasing TRUE or FALSE: If the \code{order_sample_by} is defined and the +#' @param decreasing TRUE or FALSE: If the \code{order.col.by} is defined and the #' values are numeric, should the values used to order in decreasing or #' increasing fashion? (default: \code{decreasing = FALSE}) #' #' @param layout Either \dQuote{bar} or \dQuote{point}. #' -#' @param one_facet Should the plot be returned in on facet or split into +#' @param one.facet Should the plot be returned in on facet or split into #' different facet, one facet per different value detect in \code{rank}. If -#' \code{features} or \code{order_sample_by} is not \code{NULL}, this setting will +#' \code{col.var} or \code{order.col.by} is not \code{NULL}, this setting will #' be disregarded. +#' +#' @param one_facet Deprecated. Use \code{one.facet} instead. #' -#' @param ncol,scales if \code{one_facet = FALSE}, \code{ncol} defines many +#' @param ncol,scales if \code{one.facet = FALSE}, \code{ncol} defines many #' columns should be for plotting the different facets and \code{scales} is #' used to define the behavior of the scales of each facet. Both values are #' passed onto \code{\link[ggplot2:facet_wrap]{facet_wrap}}. #' #' @param ... additional parameters for plotting. #' \itemize{ -#' \item{use_relative}{ \code{TRUE} or \code{FALSE}: Should the relative values -#' be calculated? (default: \code{use_relative = FALSE} } +#' \item{as.relative}{ \code{TRUE} or \code{FALSE}: Should the relative values +#' be calculated? (default: \code{as.relative = FALSE} } #' } #' See \code{\link{mia-plot-args}} for more details i.e. call \code{help("mia-plot-args")} #' #' @return #' a \code{\link[ggplot2:ggplot]{ggplot}} object or list of two -#' \code{\link[ggplot2:ggplot]{ggplot}} objects, if `features` are added to +#' \code{\link[ggplot2:ggplot]{ggplot}} objects, if `col.var` are added to #' the plot. #' #' @name plotAbundance @@ -73,15 +80,14 @@ #' data(GlobalPatterns, package="mia") #' tse <- GlobalPatterns #' -#' # Apply relative transform -#' tse <- transformAssay(tse, method = "relabundance") -#' #' ## If rank is set to NULL (default), agglomeration is not done. However, note #' ## that there is maximum number of rows that can be plotted. That is why #' ## we take sample from the data. #' set.seed(26348) #' sample <- sample(rownames(tse), 20) #' tse_sub <- tse[sample, ] +#' # Apply relative transformation +#' tse_sub <- transformAssay(tse_sub, method = "relabundance") #' plotAbundance(tse_sub, assay.type = "relabundance") #' #' ## Plotting counts using the first taxonomic rank as default @@ -92,19 +98,21 @@ #' ## Using "Phylum" as rank. Apply relative transformation to "counts" assay. #' plotAbundance( #' tse, assay.type="counts", rank = "Phylum", add_legend = FALSE, -#' use_relative = TRUE) +#' as.relative = TRUE) #' +#' # Apply relative transform +#' tse <- transformAssay(tse, method = "relabundance") #' #' ## A feature from colData or taxon from chosen rank can be used for ordering #' ## samples. #' plotAbundance(tse, assay.type="relabundance", rank = "Phylum", -#' order_sample_by = "Bacteroidetes") +#' order.col.by = "Bacteroidetes") #' -#' ## Features from colData can be plotted together with abundance plot. +#' ## col.var from colData can be plotted together with abundance plot. #' # Returned object is a list that includes two plot; other visualizes -#' ## abundance other features. +#' ## abundance other col.var. #' plot <- plotAbundance(tse, assay.type = "relabundance", rank = "Phylum", -#' features = "SampleType") +#' col.var = "SampleType") #' \donttest{ #' # These two plots can be combined with wrap_plots function from patchwork #' # package @@ -115,8 +123,8 @@ #' ## Same plot as above but showing sample IDs as labels for the x axis on the #' ## top plot #' plot[[1]] <- plotAbundance(tse, assay.type = "relabundance", rank = "Phylum", -#' features = "SampleType", add_legend = FALSE, -#' add_x_text = TRUE)[[1]] + +#' col.var = "SampleType", add.legend = FALSE, +#' add.x.text = TRUE)[[1]] + #' theme(axis.text.x = element_text(angle = 90)) #' \donttest{ #' wrap_plots(plot, ncol = 1, heights = c(0.8,0.2)) @@ -137,7 +145,7 @@ #' #' # Compositional barplot #' plotAbundance(tse, assay.type="relabundance", rank = "Phylum", -#' order_rank_by="abund", order_sample_by = "Bacteroidetes") +#' order.row.by="abund", order.col.by = "Bacteroidetes") NULL #' @rdname plotAbundance @@ -163,11 +171,15 @@ setGeneric("plotAbundance", signature = c("x"), setMethod("plotAbundance", signature = c("SummarizedExperiment"), function(x, rank = NULL, + col.var = features, features = NULL, + order.row.by = order_rank_by, order_rank_by = c("name","abund","revabund"), + order.col.by = order_sample_by, order_sample_by = NULL, decreasing = TRUE, layout = c("bar","point"), + one.facet = one_facet, one_facet = TRUE, ncol = 2, scales = "fixed", @@ -187,34 +199,34 @@ setMethod("plotAbundance", signature = c("SummarizedExperiment"), } .check_for_taxonomic_data_order(x) layout <- match.arg(layout, c("bar","point")) - order_rank_by <- match.arg(order_rank_by, c("name","abund","revabund")) - .check_abund_plot_args(one_facet = one_facet, + order.row.by <- match.arg(order.row.by, c("name","abund","revabund")) + .check_abund_plot_args(one_facet = one.facet, ncol = ncol) - if( !is.null(features) ){ - features <- match.arg(features, colnames(colData(x))) + if( !is.null(col.var) ){ + col.var <- match.arg(col.var, colnames(colData(x))) } ########################### INPUT CHECK END ########################### # Get the abundance data to be plotted. Agglomerate and apply relative # transformation if specified. abund_data <- .get_abundance_data( - x, rank, assay.type, order_rank_by, ...) + x, rank, assay.type, order.row.by, ...) # If rank was NULL, then the data was not agglomerated. The rank is # still used in coloring (passed to colour_by parameter in # .abund_plotter), which is why we adjust the value of it to apply # coloring in (NULL means that coloring is not applied). rank <- ifelse(is.null(rank), "Feature", rank) # Order columns - order_sample_by <- .norm_order_sample_by( - order_sample_by, unique(abund_data$colour_by), x) + order_col_by <- .norm_order_sample_by( + order.col.by, unique(abund_data$colour_by), x) # Get additional column metadata to be plotted features_data <- NULL - if(!is.null(features) || !is.null(order_sample_by)){ - features_data <- .get_features_data(features, order_sample_by, x) + if(!is.null(col.var) || !is.null(order_col_by)){ + features_data <- .get_features_data(col.var, order_col_by, x) } # Order the whole data to follow user specified ordering if(!is.null(order_sample_by)){ order_out <- .order_abund_feature_data( - abund_data, features_data, order_sample_by, decreasing) + abund_data, features_data, order_col_by, decreasing) abund_data <- order_out$abund_data features_data <- order_out$features_data } @@ -225,14 +237,13 @@ setMethod("plotAbundance", signature = c("SummarizedExperiment"), ...) # Create the column metadata plot and create a list from plots if(!is.null(features_data)){ - plot_feature_out <- .features_plotter(features_data, - order_sample_by, - ...) + plot_feature_out <- .features_plotter( + features_data, order.col.by, ...) plot_out <- c(list(abundance = plot_out), plot_feature_out) } else { # Whether to split the main plot to multiple facets. This is # disabled if user wants to plot also column metadata. - if (!one_facet) { + if (!one.facet) { plot_out <- plot_out + facet_wrap(~colour_by, ncol = ncol, scales = scales) } @@ -243,11 +254,11 @@ setMethod("plotAbundance", signature = c("SummarizedExperiment"), # If features is specified, then only abundance and features plots # are returned as a list. If it is not, then only abundance plot is # returned. - if( !is.null(features) ){ + if( !is.null(col.var) ){ plot_out <- list( - abundance = plot_out[["abundance"]], plot_out[[features]]) + abundance = plot_out[["abundance"]], plot_out[[col.var]]) # Assigns the names back - names(plot_out) <- c("abundance", features) + names(plot_out) <- c("abundance", col.var) } else{ plot_out <- plot_out[["abundance"]] } @@ -258,10 +269,11 @@ setMethod("plotAbundance", signature = c("SummarizedExperiment"), #' @importFrom dplyr group_by summarize rename .get_abundance_data <- function( - x, rank, assay.type, order_rank_by = "name", use_relative = FALSE, ...){ + x, rank, assay.type, order_rank_by = "name", as.relative = use_relative, + use_relative = FALSE, ...){ # Input check - if(!.is_a_bool(use_relative)){ - stop("'use_relative' must be TRUE or FALSE.", + if(!.is_a_bool(as.relative)){ + stop("'as.relative' must be TRUE or FALSE.", call. = FALSE) } # @@ -282,7 +294,7 @@ setMethod("plotAbundance", signature = c("SummarizedExperiment"), } # If user wants to calculate relative abundances, apply relative transform # and use relative assay instead of the original assay in plotting. - if( use_relative ){ + if( as.relative ){ temp_name <- "temporary_relative_abundance" x <- transformAssay( x, assay.type = assay.type, method = "relabundance", @@ -337,7 +349,7 @@ setMethod("plotAbundance", signature = c("SummarizedExperiment"), return(order_sample_by) } # Chec that the parameter is string - msg <- paste0("'order_sample_by' must be a single non-empty character value, ", + msg <- paste0("'order.col.by' must be a single non-empty character value, ", "either present in the abundance data as group variable or ", "in the column data of 'x'. (The abundance data takes ", "precedence)") @@ -453,7 +465,7 @@ setMethod("plotAbundance", signature = c("SummarizedExperiment"), #' scale_y_continuous .abund_plotter <- function(object, xlab = "Samples", - ylab = paste0(ifelse(use_relative, "Rel. ", ""),"Abundance"), + ylab = paste0(ifelse(as.relative, "Rel. ", ""),"Abundance"), colour_by = NULL, layout = "bar", flipped = FALSE, @@ -463,6 +475,7 @@ setMethod("plotAbundance", signature = c("SummarizedExperiment"), bar_alpha = 0.65, point_alpha = 1, point_size = 2, + as.relative = use_relative, use_relative = FALSE, ... ){ diff --git a/R/plotAbundanceDensity.R b/R/plotAbundanceDensity.R index 581ff00f..9bc4acf0 100644 --- a/R/plotAbundanceDensity.R +++ b/R/plotAbundanceDensity.R @@ -2,7 +2,7 @@ #' #' This function plots abundance of the most abundant taxa. #' -#' @param object a +#' @param x a #' \code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}} #' object. #' @@ -20,26 +20,34 @@ #' will be disabled.) #' #' @param n a positive integer specifying the number of the most abundant taxa -#' to show. (default: \code{n = min(nrow(object), 25L)}) +#' to show. (default: \code{n = min(nrow(x), 25L)}) #' -#' @param colour_by a single character value defining a column from +#' @param colour.by a single character value defining a column from #' \code{colData}, that is used to color plot. Must be a value of -#' \code{colData()} function. (default: \code{colour_by = NULL}) +#' \code{colData()} function. (default: \code{colour.by = NULL}) +#' +#' @param colour_by Deprecated. Use \code{colour.by} instead. #' -#' @param shape_by a single character value defining a column from +#' @param shape.by a single character value defining a column from #' \code{colData}, that is used to group observations to different point shape -#' groups. Must be a value of \code{colData()} function. \code{shape_by} is -#' disabled when \code{layout = "density"}. (default: \code{shape_by = NULL}) +#' groups. Must be a value of \code{colData()} function. \code{shape.by} is +#' disabled when \code{layout = "density"}. (default: \code{shape.by = NULL}) +#' +#' @param shape_by Deprecated. Use \code{shape.by} instead. #' -#' @param size_by a single character value defining a column from +#' @param size.by a single character value defining a column from #' \code{colData}, that is used to group observations to different point size -#' groups. Must be a value of \code{colData()} function. \code{size_by} is -#' disabled when \code{layout = "density"}. (default: \code{size_by = NULL}) +#' groups. Must be a value of \code{colData()} function. \code{size.by} is +#' disabled when \code{layout = "density"}. (default: \code{size.by = NULL}) +#' +#' @param size_by Deprecated. Use \code{size.by} instead. #' -#' @param order_descending \code{TRUE}, \code{FALSE} or\code{NA}: Should the -#' results be ordered in a descending order? If \code{NA} is given the order -#' as found in \code{object} for the \code{n} most abundant taxa is used. -#' (default: \code{order_descending = TRUE}) +#' @param decreasing \code{Boolean} indicating whether the results should be ordered +#' in a descending order or not. If \code{NA} is given the order +#' as found in \code{x} for the \code{n} most abundant taxa is used. +#' (Default: \code{TRUE}) +#' +#' @param order_descending Deprecated. Use \code{order.descending} instead. #' #' @param ... additional parameters for plotting. #' \itemize{ @@ -101,7 +109,7 @@ #' # "nationality" information is used to color the points. X-axis is log-scaled. #' plotAbundanceDensity( #' tse, layout = "jitter", assay.type = "relabundance", n = 10, -#' colour_by = "Geographical_location") + +#' colour.by = "Geographical_location") + #' scale_x_log10() #' #' # Plots the relative abundance of 10 most abundant taxa as a density plot. @@ -121,75 +129,78 @@ #' # and adjusted for point size #' plotAbundanceDensity( #' tse, layout = "point", assay.type = "relabundance", n = 10, -#' shape_by = "Geographical_location", size_by = "Age", point_size=1) +#' shape.by = "Geographical_location", size.by = "Age", point_size=1) #' -#' # Ordering via order_descending +#' # Ordering via decreasing #' plotAbundanceDensity( -#' tse, assay.type = "relabundance", order_descending = FALSE) +#' tse, assay.type = "relabundance", decreasing = FALSE) #' -#' # for custom ordering set order_descending = NA and order the input object +#' # for custom ordering set decreasing = NA and order the input object #' # to your wishes #' plotAbundanceDensity( -#' tse, assay.type = "relabundance", order_descending = NA) +#' tse, assay.type = "relabundance", decreasing = NA) #' NULL #' @rdname plotAbundanceDensity #' @export -setGeneric("plotAbundanceDensity", signature = c("object"), - function(object, ...) +setGeneric("plotAbundanceDensity", signature = c("x"), + function(x, ...) standardGeneric("plotAbundanceDensity")) #' @rdname plotAbundanceDensity #' @export -setMethod("plotAbundanceDensity", signature = c(object = "SummarizedExperiment"), - function(object, +setMethod("plotAbundanceDensity", signature = c(x = "SummarizedExperiment"), + function(x, layout = c("jitter", "density", "point"), assay.type = assay_name, assay_name = "counts", - n = min(nrow(object), 25L), - colour_by = NULL, - shape_by = NULL, - size_by = NULL, + n = min(nrow(x), 25L), colour.by = colour_by, + colour_by = NULL, + shape.by = shape_by, + shape_by = NULL, + size.by = size_by, + size_by = NULL, + decreasing = order_descending, order_descending = TRUE, ...){ ############################# Input Check ############################## # Check layout layout <- match.arg(layout, c("jitter", "density", "point")) # Checks assay.type - .check_assay_present(assay.type, object) + .check_assay_present(assay.type, x) # Checks n if( !(length(n)==1 && is.numeric(n) && n%%1==0 && n>0) ){ stop("'n' must be a positive integer.", call. = FALSE) } - # Checks colour_by - if( !is.null(colour_by) && !.is_a_string(colour_by)){ - stop("'colour_by' must be a single character value.", + # Checks colour.by + if( !is.null(colour.by) && !.is_a_string(colour.by)){ + stop("'colour.by' must be a single character value.", call. = FALSE) } - # Checks shape_by - if( !is.null(shape_by) && !.is_a_string(shape_by)){ - stop("'shape_by' must be a single character value.", + # Checks shape.by + if( !is.null(shape.by) && !.is_a_string(shape.by)){ + stop("'shape.by' must be a single character value.", call. = FALSE) } - # Checks size_by - if( !is.null(size_by) && !.is_a_string(size_by)){ - stop("'size_by' must be a single character value.", + # Checks shape.by + if( !is.null(shape.by) && !.is_a_string(shape.by)){ + stop("'shape.by' must be a single character value.", call. = FALSE) } - # Checks order_descending - if( !is.na(order_descending) && !.is_a_bool(order_descending)){ - stop("'order_descending' must be TRUE, FALSE or NA.", + # Checks decreasing + if( !is.na(decreasing) && !.is_a_bool(decreasing)){ + stop("'decreasing' must be TRUE, FALSE or NA.", call. = FALSE) } ########################### Input Check end ############################ # Gets data that will be plotted. Gets a list - density_data_list <- .incorporate_density_data(object = object, + density_data_list <- .incorporate_density_data(object = x, assay.type = assay.type, n = n, - colour_by = colour_by, - shape_by = shape_by, - size_by = size_by, - order_descending = order_descending) + colour_by = colour.by, + shape_by = shape.by, + size_by = size.by, + order_descending = decreasing) # Extracts the density data and aesthetic from the list density_data <- density_data_list$density_data colour_by <- density_data_list$colour_by diff --git a/R/plotCCA.R b/R/plotCCA.R index 87ee047b..3ecd31c4 100644 --- a/R/plotCCA.R +++ b/R/plotCCA.R @@ -4,7 +4,7 @@ #' output of \code{\link[mia:runCCA]{CCA and RDA}} functions, two common methods #' for supervised ordination of microbiome data. #' -#' @param object a +#' @param x a #' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-constructor]{TreeSummarizedExperiment}} #' or a matrix of weights. The latter is returned as output from \code{\link[mia:runCCA]{getRDA}}. #' @@ -112,26 +112,26 @@ #' #' # Create RDA plot coloured by variable #' plotRDA(tse, "RDA", -#' colour_by = "ClinicalStatus") +#' colour.by = "ClinicalStatus") #' #' # Create RDA plot with empty ellipses #' plotRDA(tse, "RDA", -#' colour_by = "ClinicalStatus", +#' colour.by = "ClinicalStatus", #' add.ellipse = "colour") #' #' # Create RDA plot with text encased in labels #' plotRDA(tse, "RDA", -#' colour_by = "ClinicalStatus", +#' colour.by = "ClinicalStatus", #' vec.text = FALSE) #' #' # Create RDA plot without repelling text #' plotRDA(tse, "RDA", -#' colour_by = "ClinicalStatus", +#' colour.by = "ClinicalStatus", #' repel.labels = FALSE) #' #' # Create RDA plot without vectors #' plotRDA(tse, "RDA", -#' colour_by = "ClinicalStatus", +#' colour.by = "ClinicalStatus", #' add.vectors = FALSE) #' #' # Calculate RDA as a separate object @@ -148,40 +148,40 @@ NULL #' @rdname plotCCA #' @aliases plotRDA #' @export -setGeneric("plotCCA", signature = c("object"), - function(object, ...) standardGeneric("plotCCA")) +setGeneric("plotCCA", signature = c("x"), + function(x, ...) standardGeneric("plotCCA")) #' @rdname plotCCA #' @aliases plotRDA #' @export -setMethod("plotCCA", signature = c(object = "SingleCellExperiment"), - function(object, dimred, ...){ +setMethod("plotCCA", signature = c(x = "SingleCellExperiment"), + function(x, dimred, ...){ # Reproduce plotRDA function - return(plotRDA(object, dimred, ...)) + return(plotRDA(x, dimred, ...)) } ) #' @rdname plotCCA #' @aliases plotRDA #' @export -setMethod("plotCCA", signature = c(object = "matrix"), - function(object, ...){ +setMethod("plotCCA", signature = c(x = "matrix"), + function(x, ...){ # Reproduce plotRDA function - return(plotRDA(object, ...)) + return(plotRDA(x, ...)) } ) #' @rdname plotCCA #' @aliases plotCCA #' @export -setGeneric("plotRDA", signature = c("object"), - function(object, ...) standardGeneric("plotRDA")) +setGeneric("plotRDA", signature = c("x"), + function(x, ...) standardGeneric("plotRDA")) #' @rdname plotCCA #' @aliases plotCCA #' @export -setMethod("plotRDA", signature = c(object = "SingleCellExperiment"), - function(object, dimred, +setMethod("plotRDA", signature = c(x = "SingleCellExperiment"), + function(x, dimred, add.ellipse = TRUE, ellipse.alpha = 0.2, ellipse.linewidth = 0.1, ellipse.linetype = 1, confidence.level = 0.95, vec.size = 0.5, vec.color = vec.colour, vec.colour = "black", vec.linetype = 1, arrow.size = 0.25, label.color = label.colour, label.colour = "black", label.size = 4, @@ -255,7 +255,7 @@ setMethod("plotRDA", signature = c(object = "SingleCellExperiment"), ###################### Input check end #################### # Get data for plotting plot_data <- .incorporate_rda_vis( - object, dimred, sep.group = sep.group, repl.underscore = repl.underscore, + x, dimred, sep.group = sep.group, repl.underscore = repl.underscore, add.significance = add.significance, add.expl.var = add.expl.var, add.ellipse = add.ellipse, add.vectors = add.vectors, ... ) @@ -275,12 +275,12 @@ setMethod("plotRDA", signature = c(object = "SingleCellExperiment"), #' @rdname plotCCA #' @aliases plotCCA #' @export -setMethod("plotRDA", signature = c(object = "matrix"), - function(object, ...){ +setMethod("plotRDA", signature = c(x = "matrix"), + function(x, ...){ # Construct TreeSE from rda/cca object - object <- .rda2tse(object) + x <- .rda2tse(x) # Run plotRDA method for TreeSE - return(plotRDA(object, "RDA", ...)) + return(plotRDA(x, "RDA", ...)) } ) @@ -301,9 +301,12 @@ setMethod("plotRDA", signature = c(object = "matrix"), #' @importFrom scater plotReducedDim retrieveCellInfo #' @importFrom SingleCellExperiment reducedDim reducedDimNames .incorporate_rda_vis <- function( - tse, dimred, ncomponents = 2, colour_by = color_by, color_by = NULL, + tse, dimred, ncomponents = 2, + colour_by = color_by, color_by = colour.by, + colour.by = color.by, color.by = NULL, add.significance = TRUE, add.expl.var = TRUE, add.ellipse = TRUE, - add.vectors = TRUE, vec.lab = NULL, expl_var = NULL, + add.vectors = TRUE, vec.lab = NULL, + expl.var = expl_var, expl_var = NULL, sep.group = "\U2012", repl.underscore = " ", ...){ # Check dimred diff --git a/R/plotGraph.R b/R/plotGraph.R index 60267f6b..55cb727c 100644 --- a/R/plotGraph.R +++ b/R/plotGraph.R @@ -14,7 +14,7 @@ #' \code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}} #' the key for subsetting the \code{metadata(x)} to a graph object. #' -#' @param show_label \code{logical} (scalar), \code{integer} or \code{character} +#' @param show.label \code{logical} (scalar), \code{integer} or \code{character} #' vector. If a \code{logical} scalar is given, should tip labels be plotted #' or if a logical vector is provided, which labels should be shown? If an #' \code{integer} or \code{character} vector is provided, it will be converted @@ -23,49 +23,69 @@ #' match values of a \code{label} or \code{name} column in the node data. In #' case of a \code{character} vector only values corresponding to actual #' labels will be plotted and if no labels are provided no labels will be -#' shown. (default: \code{show_label = FALSE}) +#' shown. (default: \code{show.label = FALSE}) +#' +#' @param show_label Deprecated. Use \code{show.label} instead. #' -#' @param add_legend logical scalar. Should legends be plotted? -#' (default: \code{add_legend = TRUE}) +#' @param add.legend logical scalar. Should legends be plotted? +#' (default: \code{add.legend = TRUE}) +#' +#' @param add_legend Deprecated. Use \code{add.legend} instead. #' #' @param layout layout for the plotted graph. See #' \code{\link[ggraph:ggraph]{ggraph}} for details. (default: #' \code{layout = "kk"}) #' -#' @param edge_type type of edge plotted on the graph. See +#' @param edge.type type of edge plotted on the graph. See #' \code{\link[ggraph:geom_edge_fan]{geom_edge_fan}} for details and other #' available geoms. (default: -#' \code{edge_type = "fan"}) +#' \code{edge.type = "fan"}) +#' +#' @param edge_type Deprecated. Use \code{edge.type} instead. #' -#' @param edge_colour_by Specification of a edge metadata field to use for +#' @param edge.colour.by Specification of a edge metadata field to use for #' setting colours of the edges. #' -#' @param edge_width_by Specification of a edge metadata field to use for +#' @param edge_colour_by Deprecated. Use \code{edge.colour.by} instead. +#' +#' @param edge.width.by Specification of a edge metadata field to use for #' setting width of the edges. +#' +#' @param edge_width_by Deprecated. Use \code{edge.width.by} instead. #' -#' @param colour_by Specification of a column metadata field or a feature to +#' @param colour.by Specification of a column metadata field or a feature to #' colour graph nodes by, see the by argument in #' \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible #' values. #' -#' @param shape_by Specification of a column metadata field or a feature to +#' @param colour_by Deprecated. Use \code{colour.by} instead. +#' +#' @param shape.by Specification of a column metadata field or a feature to #' shape graph nodes by, see the by argument in #' \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible #' values. #' -#' @param size_by Specification of a column metadata field or a feature to +#' @param shape_by Deprecated. Use \code{shape.by} instead. +#' +#' @param size.by Specification of a column metadata field or a feature to #' size graph nodes by, see the by argument in #' \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible #' values. #' -#' @param by_exprs_values A string or integer scalar specifying which assay to +#' @param size_by Deprecated. Use \code{size.by} instead. +#' +#' @param assay.type A string or integer scalar specifying which assay to #' obtain expression values from, for use in point aesthetics - see the #' \code{exprs_values} argument in #' \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}}. +#' +#' @param by_exprs_values Deprecated. Use \code{assay.type} instead. #' -#' @param other_fields Additional fields to include in the node information +#' @param other.fields Additional fields to include in the node information #' without plotting them. #' +#' @param other_fields Deprecated. Use \code{other.fields} instead. +#' #' @param ... additional arguments for plotting. See #' \code{\link{mia-plot-args}} for more details i.e. call \code{help("mia-plot-args")} #' @@ -96,57 +116,57 @@ #' # plot a graph independently #' plotColGraph(col_graph, #' genus, -#' colour_by = "SampleType", -#' edge_colour_by = "weight", -#' edge_width_by = "weight", -#' show_label = TRUE) +#' colour.by = "SampleType", +#' edge.colour.by = "weight", +#' edge.width.by = "weight", +#' show.label = TRUE) #' #' # plot the graph stored in the object #' plotColGraph(genus, #' name = "col_graph", -#' colour_by = "SampleType", -#' edge_colour_by = "weight", -#' edge_width_by = "weight") +#' colour.by = "SampleType", +#' edge.colour.by = "weight", +#' edge.width.by = "weight") #' #' #' # plot a graph independently #' plotRowGraph(row_graph, #' genus, -#' colour_by = "Kingdom", -#' edge_colour_by = "weight", -#' edge_width_by = "weight") +#' colour.by = "Kingdom", +#' edge.colour.by = "weight", +#' edge.width.by = "weight") #' #' # plot the graph stored in the object #' plotRowGraph(genus, #' name = "row_graph", -#' colour_by = "Phylum", -#' edge_colour_by = "weight", -#' edge_width_by = "weight") +#' colour.by = "Phylum", +#' edge.colour.by = "weight", +#' edge.width.by = "weight") #' #' #' # plot a graph independently #' plotRowGraph(row_graph_order, #' order, -#' colour_by = "Kingdom", -#' edge_colour_by = "weight", -#' edge_width_by = "weight") +#' colour.by = "Kingdom", +#' edge.colour.by = "weight", +#' edge.width.by = "weight") #' #' # plot the graph stored in the object and include some labels #' plotRowGraph(order, #' name = "row_graph", -#' colour_by = "Phylum", -#' edge_colour_by = "weight", -#' edge_width_by = "weight", -#' show_label = c("Sulfolobales","Spirochaetales", +#' colour.by = "Phylum", +#' edge.colour.by = "weight", +#' edge.width.by = "weight", +#' show.label = c("Sulfolobales","Spirochaetales", #' "Verrucomicrobiales")) #' #' # labels can also be included via selecting specific rownames of x/y #' plotRowGraph(order, #' name = "row_graph", -#' colour_by = "Phylum", -#' edge_colour_by = "weight", -#' edge_width_by = "weight", -#' show_label = c(1,10,50)) +#' colour.by = "Phylum", +#' edge.colour.by = "weight", +#' edge.width.by = "weight", +#' show.label = c(1,10,50)) #' #' # labels can also be included via a logical vector, which has the same length #' # as nodes are present @@ -154,10 +174,10 @@ #' label_select[c(1,10,50)] <- TRUE #' plotRowGraph(order, #' name = "row_graph", -#' colour_by = "Phylum", -#' edge_colour_by = "weight", -#' edge_width_by = "weight", -#' show_label = label_select) +#' colour.by = "Phylum", +#' edge.colour.by = "weight", +#' edge.width.by = "weight", +#' show.label = label_select) #' } NULL @@ -199,30 +219,40 @@ setGeneric("plotRowGraph", signature = c("x","y"), setMethod("plotColGraph", signature = c(x = "ANY",y = "SummarizedExperiment"), function(x, y, + show.label = show_label, show_label = FALSE, + add.legend = add_legend, add_legend = TRUE, layout = "kk", + edge.type = edge_type, edge_type = c("fan","link","arc","parallel"), + edge.colour.by = edge_colour_by, edge_colour_by = NULL, + edge.width.by = edge_width_by, edge_width_by = NULL, + colour.by = colour_by, colour_by = NULL, + shape.by = shape_by, shape_by = NULL, + size.by = size_by, size_by = NULL, + assay.type = by_exprs_values, by_exprs_values = "counts", + other.fields = other_fields, other_fields = list(), ...){ .plot_row_column_graph(x = x, y = y, - show_label = show_label, - add_legend = add_legend, + show_label = show.label, + add_legend = add.legend, layout = layout, - edge_type = edge_type, - edge_colour_by = edge_colour_by, - edge_width_by = edge_width_by, - colour_by = colour_by, - shape_by = shape_by, - size_by = size_by, - by_exprs_values = by_exprs_values, - other_fields = other_fields, + edge_type = edge.type, + edge_colour_by = edge.colour.by, + edge_width_by = edge.width.by, + colour_by = colour.by, + shape_by = shape.by, + size_by = size.by, + by_exprs_values = assay.type, + other_fields = other.fields, type = "column", ...) } @@ -248,30 +278,39 @@ setMethod("plotColGraph", setMethod("plotRowGraph", signature = c(x = "ANY",y = "SummarizedExperiment"), function(x, y, + show.label = show_label, show_label = FALSE, + add.legend = add_legend, add_legend = TRUE, layout = "kk", + edge.type = edge_type, edge_type = c("fan","link","arc","parallel"), + edge.colour.by = edge_colour_by, edge_colour_by = NULL, + edge.width.by = edge_width_by, edge_width_by = NULL, + colour.by = colour_by, colour_by = NULL, + shape.by = shape_by, shape_by = NULL, - size_by = NULL, + size.by = NULL, + assay.type = by_exprs_values, by_exprs_values = "counts", + other.fields = other_fields, other_fields = list(), ...){ .plot_row_column_graph(x = x, y = y, - show_label = show_label, - add_legend = add_legend, + show_label = show.label, + add_legend = add.legend, layout = layout, - edge_type = edge_type, - edge_colour_by = edge_colour_by, - edge_width_by = edge_width_by, - colour_by = colour_by, - shape_by = shape_by, - size_by = size_by, - by_exprs_values = by_exprs_values, - other_fields = other_fields, + edge_type = edge.type, + edge_colour_by = edge.colour.by, + edge_width_by = edge.width.by, + colour_by = colour.by, + shape_by = shape.by, + size_by = size.by, + by_exprs_values = assay.type, + other_fields = other.fields, type = "row", ...) } diff --git a/R/plotPrevalence.R b/R/plotPrevalence.R index 48bf9c34..cb73f634 100644 --- a/R/plotPrevalence.R +++ b/R/plotPrevalence.R @@ -12,7 +12,7 @@ #' #' @param rank,... additional arguments #' \itemize{ -#' \item{use_relative}{ \code{TRUE} or \code{FALSE}: Should the relative values +#' \item{as.relative}{ \code{TRUE} or \code{FALSE}: Should the relative values #' be calculated? (Default: \code{FALSE}) } #' #' \item{ndetection}{ \code{Integer scalar}. Determines the number of breaks @@ -39,42 +39,56 @@ #' (Please use \code{assay.type} instead. At some point \code{assay_name} #' will be disabled.) #' -#' @param colour_by Specification of a feature to colour points by, see the +#' @param colour.by Specification of a feature to colour points by, see the #' \code{by} argument in #' \code{\link[scater:retrieveFeatureInfo]{?retrieveFeatureInfo}} for #' possible values. Only used with \code{layout = "point"}. -#' @param shape_by Specification of a feature to shape points by, see the +#' +#' @param colour_by Deprecated. Use \code{colour.by} instead. +#' +#' @param shape.by Specification of a feature to shape points by, see the #' \code{by} argument in #' \code{\link[scater:retrieveFeatureInfo]{?retrieveFeatureInfo}} for #' possible values. Only used with \code{layout = "point"}. -#' @param size_by Specification of a feature to size points by, see the +#' +#' @param shape_by Deprecated. Use \code{shape.by} instead. +#' +#' @param size.by Specification of a feature to size points by, see the #' \code{by} argument in #' \code{\link[scater:retrieveFeatureInfo]{?retrieveFeatureInfo}} for #' possible values. Only used with \code{layout = "point"}. #' -#' @param facet_by Taxonomic rank to facet the plot by. +#' @param size_by Deprecated. Use \code{size.by} instead. +#' +#' @param facet.by Taxonomic rank to facet the plot by. #' Value must be of \code{taxonomyRanks(x)} #' Argument can only be used in function plotPrevalentAbundance. #' -#' @param label a \code{logical}, \code{character} or \code{integer} vector +#' @param facet_by Deprecated. Use \code{facet.by} instead. +#' +#' @param show.label a \code{logical}, \code{character} or \code{integer} vector #' for selecting labels from the rownames of \code{x}. If \code{rank} is not -#' \code{NULL} the rownames might change. (default: \code{label = NULL}) +#' \code{NULL} the rownames might change. (default: \code{show.label = NULL}) +#' +#' @param label Deprecated. Use \code{show.label} instead. #' #' @param detection Detection thresholds for absence/presence. Either an #' absolutes value compared directly to the values of \code{x} or a relative -#' value between 0 and 1, if \code{as_relative = TRUE}. +#' value between 0 and 1, if \code{as.relative = TRUE}. #' #' @param detections Deprecated. Use \code{detection} instead. #' #' @param prevalence Prevalence thresholds (in 0 to 1). The #' required prevalence is strictly greater by default. To include the -#' limit, set \code{include_lowest} to \code{TRUE}. +#' limit, set \code{include.lowest} to \code{TRUE}. #' #' @param prevalences Deprecated. Use \code{prevalence} instead. #' -#' @param min_prevalence a single numeric value to apply as a threshold for +#' @param min.prevalence a single numeric value to apply as a threshold for #' plotting. The threshold is applied per row and column. #' (default: \code{min_prevalence = 0}) +#' +#' @param min_prevalence Deprecated. Use \code{min.prevalence} instead. #' #' @param BPPARAM A #' \code{\link[BiocParallel:BiocParallelParam-class]{BiocParallelParam}} @@ -121,14 +135,14 @@ #' # point layout for plotRowPrevalence can be used to visualize by additional #' # information #' plotPrevalentAbundance( -#' GlobalPatterns, rank = "Family", colour_by = "Phylum") + +#' GlobalPatterns, rank = "Family", colour.by = "Phylum") + #' scale_x_log10() #' #' # When using function plotPrevalentAbundace, it is possible to create facets -#' # with 'facet_by'. +#' # with 'facet.by'. #' plotPrevalentAbundance( #' GlobalPatterns, rank = "Family", -#' colour_by = "Phylum", facet_by = "Kingdom") + +#' colour.by = "Phylum", facet.by = "Kingdom") + #' scale_x_log10() NULL @@ -174,9 +188,9 @@ setMethod("plotPrevalence", signature = c(x = "SummarizedExperiment"), p <- .prevalence_plotter(plot_data, layout = "line", ylab = "N", - colour_by = "Prevalence [%]", - size_by = NULL, - shape_by = NULL, + colour.by = "Prevalence [%]", + size.by = NULL, + shape.by = NULL, ...) return(p) } @@ -192,7 +206,8 @@ setMethod("plotPrevalence", signature = c(x = "SummarizedExperiment"), #' @importFrom SummarizedExperiment assay .get_prevalence_plot_data <- function( x, assay.type, detections, prevalences, - BPPARAM = BiocParallel::SerialParam(), as_relative = FALSE, ...){ + BPPARAM = BiocParallel::SerialParam(), as.relative = as_relative, + as_relative = FALSE, ...){ # Input check if(!.is_a_bool(as_relative)){ stop("'as_relative' must be TRUE or FALSE.", call. = FALSE) @@ -249,18 +264,23 @@ setMethod("plotPrevalentAbundance", signature = c(x = "SummarizedExperiment"), x, rank = NULL, assay.type = assay_name, assay_name = "counts", - colour_by = NULL, + colour.by = colour_by, colour_by = NULL, + size.by = size_by, size_by = NULL, + shape.by = shape_by, shape_by = NULL, + show.label = label, label = NULL, + facet.by = facet_by, facet_by = NULL, ...){ # input check .check_assay_present(assay.type, x) - # Check facet_by. It is FALSE by default, but user can specify it, but + + # Check facet.by It is FALSE by default, but user can specify it, but # the value must be in taxonomyRanks. - if(!(is.null(facet_by) || facet_by %in% taxonomyRanks(x))){ - stop("'facet_by' must be in taxonomyRanks.", call. = FALSE) + if(!(is.null(facet.by) || facet.by %in% taxonomyRanks(x))){ + stop("'facet.by' must be in taxonomyRanks.", call. = FALSE) } # # Agglomerate data if specified @@ -268,7 +288,7 @@ setMethod("plotPrevalentAbundance", signature = c(x = "SummarizedExperiment"), x <- agglomerateByRank(x, rank = rank, ...) } # Check that labels are correct (or get rownames as labels if NULL) - label <- .norm_label(label, x) + label <- .norm_label(show.label, x) # Get prevalence data plot_data <- .get_prevalence_plot_point_data( x, assay.type, label = label, ...) @@ -276,11 +296,11 @@ setMethod("plotPrevalentAbundance", signature = c(x = "SummarizedExperiment"), vis_out <- .incorporate_prevalence_vis( plot_data, se = x, - colour_by = colour_by, - size_by = size_by, - shape_by = shape_by, + colour_by = colour.by, + size_by = size.by, + shape_by = shape.by, label = label, - facet_by = facet_by) + facet_by = facet.by) plot_data <- vis_out$df colour_by <- vis_out$colour_by size_by <- vis_out$size_by @@ -296,9 +316,9 @@ setMethod("plotPrevalentAbundance", signature = c(x = "SummarizedExperiment"), size_by = size_by, shape_by = shape_by, ...) - # If facet_by is not NULL, user has specified it. Adds the facets to + # If facet.by is not NULL, user has specified it. Adds the facets to # the plot. - if(!is.null(facet_by)){ + if(!is.null(facet.by)){ plot <- plot + # Create facets facet_wrap(vars(!!sym("facet_by"))) @@ -404,6 +424,7 @@ setMethod("plotRowPrevalence", signature = c(x = "SummarizedExperiment"), rank = NULL, assay.type = assay_name, assay_name = "counts", detection = detections, detections = c(0.01, 0.1, 1, 2, 5, 10, 20), + min.prevalence = min_prevalence, min_prevalence = 0, BPPARAM = BiocParallel::SerialParam(), ...){ @@ -412,8 +433,9 @@ setMethod("plotRowPrevalence", signature = c(x = "SummarizedExperiment"), stop("'detection' must be numeric values.", call. = FALSE) } .check_assay_present(assay.type, x) - if(length(min_prevalence) != 1 || !.is_numeric_string(min_prevalence)){ - stop("'min_prevalence' must be single numeric values.", + + if(length(min.prevalence) != 1 || !.is_numeric_string(min.prevalence)){ + stop("'min.prevalence' must be single numeric values.", call. = FALSE) } # @@ -423,7 +445,7 @@ setMethod("plotRowPrevalence", signature = c(x = "SummarizedExperiment"), } # Get prevalence data plot_data <- .get_prevalence_plot_matrix( - x, assay.type, detection, min_prevalence, BPPARAM, ...) + x, assay.type, detection, min.prevalence, BPPARAM, ...) plot_data$colour_by <- plot_data$colour_by * 100 ylab <- ifelse(is.null(rank), "Features", rank) colour_by <- "Prevalence [%]" @@ -452,7 +474,8 @@ setMethod("plotRowPrevalence", signature = c(x = "SummarizedExperiment"), #' @importFrom DelayedArray rowSums .get_prevalence_plot_matrix <- function( x, assay.type, detections, min_prevalence, - BPPARAM = BiocParallel::SerialParam(), as_relative = FALSE, + BPPARAM = BiocParallel::SerialParam(), as.relative = as_relative, + as_relative = FALSE, ndetection = 20, ...){ # Input check if(!.is_a_bool(as_relative)){ @@ -535,7 +558,7 @@ setMethod("plotRowPrevalence", signature = c(x = "SummarizedExperiment"), #' theme_classic .prevalence_plotter <- function(plot_data, layout = c("line","point","heatmap"), - xlab = paste0(ifelse(as_relative, "Rel. ", ""),"Abundance"), + xlab = paste0(ifelse(as.relative, "Rel. ", ""),"Abundance"), ylab = NULL, colour_by = NULL, size_by = NULL, @@ -547,6 +570,7 @@ setMethod("plotRowPrevalence", signature = c(x = "SummarizedExperiment"), line_alpha = 1, line_type = NULL, line_size = 1, + as.relative = as_relative, as_relative = FALSE, ...){ # Start plotting diff --git a/R/plotSeries.R b/R/plotSeries.R index 46cdfac3..c5be71d3 100644 --- a/R/plotSeries.R +++ b/R/plotSeries.R @@ -27,17 +27,23 @@ #' to agglomerate the data. Must be a value of \code{taxonomicRanks()} #' function. #' -#' @param colour_by a single character value defining a taxonomic rank, that is used to +#' @param colour.by a single character value defining a taxonomic rank, that is used to #' color plot. Must be a value of \code{taxonomicRanks()} function. +#' +#' @param colour_by Deprecated. Use \code{colour.by} instead. #' -#' @param linetype_by a single character value defining a taxonomic rank, that +#' @param linetype.by a single character value defining a taxonomic rank, that #' is used to divide taxa to different line types. Must be a value of #' \code{taxonomicRanks()} function. +#' +#' @param linetype_by Deprecated. Use \code{linetype.by} instead. #' -#' @param size_by a single character value defining a taxonomic rank, that is +#' @param size.by a single character value defining a taxonomic rank, that is #' used to divide taxa to different line size types. Must be a value of #' \code{taxonomicRanks()} function. #' +#' @param size_by Deprecated. Use \code{size.by} instead. +#' #' @param ... additional parameters for plotting. See #' \code{\link{mia-plot-args}} for more details i.e. call \code{help("mia-plot-args")} #' @@ -64,7 +70,7 @@ #' plotSeries(object, #' x = "DAY_ORDER", #' y = getTop(object, 2), -#' colour_by = "Family") +#' colour.by = "Family") #' #' # Counts relative abundances #' object <- transformAssay(object, method = "relabundance") @@ -75,16 +81,16 @@ #' # Plots relative abundances of phylums #' plotSeries(object[taxa,], #' x = "DAY_ORDER", -#' colour_by = "Family", -#' linetype_by = "Phylum", +#' colour.by = "Family", +#' linetype.by = "Phylum", #' assay.type = "relabundance") #' -#' # In addition to 'colour_by' and 'linetype_by', 'size_by' can also be used to group taxa. +#' # In addition to 'colour.by' and 'linetype.by', 'size.by' can also be used to group taxa. #' plotSeries(object, #' x = "DAY_ORDER", #' y = getTop(object, 5), -#' colour_by = "Family", -#' size_by = "Phylum", +#' colour.by = "Family", +#' size.by = "Phylum", #' assay.type = "counts") #' } NULL @@ -96,8 +102,11 @@ setGeneric("plotSeries", signature = c("object"), x, y = NULL, rank = NULL, + colour.by = colour_by, colour_by = NULL, + size.by = size_by, size_by = NULL, + linetype.by = linetype_by, linetype_by = NULL, assay.type = assay_name, assay_name = "counts", ...) @@ -112,8 +121,11 @@ setMethod("plotSeries", signature = c(object = "SummarizedExperiment"), x, y = NULL, rank = NULL, + colour.by = colour_by, colour_by = NULL, + size.by = size_by, size_by = NULL, + linetype.by = linetype_by, linetype_by = NULL, assay.type = assay_name, assay_name = "counts", ...){ @@ -157,9 +169,9 @@ setMethod("plotSeries", signature = c(object = "SummarizedExperiment"), # Fetches sample and features data as a list. vis_out <- .incorporate_series_vis(object, x, - colour_by, - linetype_by, - size_by) + colour.by, + linetype.by, + size.by) series_data <- vis_out$series_data feature_data <- vis_out$feature_data x <- vis_out$x diff --git a/R/plotTree.R b/R/plotTree.R index 573b5675..9b61c683 100644 --- a/R/plotTree.R +++ b/R/plotTree.R @@ -5,25 +5,33 @@ #' \code{colData} information can be taken for enriching the tree plots with #' additional information. #' -#' @param object a +#' @param x a #' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}} -#' object. +#' x. #' -#' @param tree_name a single \code{character} value specifying a rowTree/colTree from -#' \code{object}. (By default: \code{tree_name = "phylo"}) +#' @param tree.name a single \code{character} value specifying a rowTree/colTree from +#' \code{x}. (By default: \code{tree.name = "phylo"}) +#' +#' @param tree_name Deprecated. Use \code{tree.name} instead. #' -#' @param relabel_tree logical scalar, Should the tip labels be relabeled using -#' the output of \code{getTaxonomyLabels(object, with_rank = TRUE)}? -#' (default: \code{relabel_tree = FALSE}) +#' @param relabel.tree logical scalar, Should the tip labels be relabeled using +#' the output of \code{getTaxonomyLabels(x, with_rank = TRUE)}? +#' (default: \code{relabel.tree = FALSE}) +#' +#' @param relabel_tree Deprecated. Use \code{relavel.tree} instead. #' -#' @param order_tree logical scalar, Should the tree be ordered based on +#' @param order.tree logical scalar, Should the tree be ordered based on #' alphabetic order of taxonomic levels? -#' (default: \code{order_tree = FALSE}) +#' (default: \code{order.tree = FALSE}) +#' +#' @param order_tree Deprecated. Use \code{order.tree} instead. #' -#' @param remove_levels logical scalar, Should taxonomic level information -#' be removed from labels? (default: \code{relabel_tree = FALSE}) +#' @param levels.rm logical scalar, Should taxonomic level information +#' be removed from labels? (default: \code{levels.rm = FALSE}) #' -#' @param show_label,show_highlights,show_highlight_label,abbr_label +#' @param remove_levels Deprecated. Use \code{levels.rm} instead. +#' +#' @param show.label,show.highlights,show.highlight.label,abbr.label #' \code{logical} (scalar), \code{integer} or \code{character} vector. If a #' \code{logical} scalar is given, should tip labels be plotted or if a #' logical vector is provided, which labels should be shown? If an @@ -35,63 +43,90 @@ #' plotted and if no labels are provided no labels will be shown. (default: #' \code{FALSE}) #' -#' @param add_legend logical scalar. Should legends be plotted? -#' (default: \code{add_legend = TRUE}) +#' @param show_label,show_highlights,show_highlight_label,abbr_label Deprecated. +#' Use \code{show.label, show.highlights, show.highlight.label, abbr_label} instead. +#' +#' @param add.legend logical scalar. Should legends be plotted? +#' (default: \code{add.legend = TRUE}) +#' +#' @param add_legend Deprecated. Use \code{add.legend} instead. #' #' @param layout layout for the plotted tree. See #' \code{\link[ggtree:ggtree]{ggtree}} for details. #' -#' @param edge_colour_by Specification of a column metadata field or a feature +#' @param edge.colour.by Specification of a column metadata field or a feature #' to colour tree edges by, see the by argument in #' \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible #' values. #' -#' @param edge_size_by Specification of a column metadata field or a feature +#' @param edge_colour_by Deprecated. Use \code{edge.colour.by} instead. +#' +#' @param edge.size.by Specification of a column metadata field or a feature #' to size tree edges by, see the by argument in #' \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible #' values. #' -#' @param tip_colour_by Specification of a column metadata field or a feature to +#' @param edge_size_by Deprecated. Use \code{edge.size.by} instead. +#' +#' @param tip.colour.by Specification of a column metadata field or a feature to #' colour tree tips by, see the by argument in #' \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible #' values. #' -#' @param tip_shape_by Specification of a column metadata field or a feature to +#' @param tip_colour_by Deprecated. Use \code{tip.colour.by} instead. +#' +#' @param tip.shape.by Specification of a column metadata field or a feature to #' shape tree tips by, see the by argument in #' \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible #' values. #' -#' @param tip_size_by Specification of a column metadata field or a feature to +#' @param tip_shape_by Deprecated. Use \code{tip.shape.by} isntead. +#' +#' @param tip.size.by Specification of a column metadata field or a feature to #' size tree tips by, see the by argument in #' \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible #' values. #' -#' @param node_colour_by Specification of a column metadata field or a feature to -#' colour tree nodes by. Must be a field from \code{other_fields}. +#' @param tip_size_by Deprecated. Use \code{tip.size.by} instead. +#' +#' @param node.colour.by Specification of a column metadata field or a feature to +#' colour tree nodes by. Must be a field from \code{other.fields}. +#' +#' @param node_colour_by Deprecated. Use \code{node.colour.by} instead. #' -#' @param node_shape_by Specification of a column metadata field or a feature to -#' shape tree nodes by. Must be a field from \code{other_fields}. +#' @param node.shape.by Specification of a column metadata field or a feature to +#' shape tree nodes by. Must be a field from \code{other.fields}. #' -#' @param node_size_by Specification of a column metadata field or a feature to -#' size tree nodes by. Must be a field from \code{other_fields}. +#' @param node_shape_by Deprecated. Use \code{node.shape.by} instead. #' -#' @param colour_highlights_by Should the highlights be colour differently? -#' If \code{show_highlights = TRUE}, \code{colour_highlights} will be set to +#' @param node.size.by Specification of a column metadata field or a feature to +#' size tree nodes by. Must be a field from \code{other.fields}. +#' +#' @param node_size_by Deprecated. Use \code{node.size.by} instead. +#' +#' @param colour.highlights.by Should the highlights be colour differently? +#' If \code{show.highlights = TRUE}, \code{colour_highlights} will be set to #' \code{TRUE} as default. (default: \code{colour_highlights = FALSE}) #' -#' @param by_exprs_values A string or integer scalar specifying which assay to +#' @param colour_highlights_by Deprecated. Use \code{colour.highlights.by} isntead. +#' +#' @param assay.type A string or integer scalar specifying which assay to #' obtain expression values from, for use in point aesthetics - see the #' \code{exprs_values} argument in #' \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}}. #' -#' @param other_fields Additional fields to include in the node information +#' @param by_exprs_values Deprecated. Use \code{assay.type} instead. +#' +#' @param other.fields Additional fields to include in the node information #' without plotting them. #' +#' @param other_fields Deprecated. Use \code{other.fields} instead. +#' #' @param ... additional arguments for plotting. See #' \code{\link{mia-plot-args}} for more details i.e. call \code{help("mia-plot-args")} #' #' @details -#' If \code{show_label} or \code{show_highlight_label} have the same length +#' If \code{show.label} or \code{show.highlight.label} have the same length #' as the number of nodes, the vector will be used to relabel the nodes. #' #' @return a \code{\link{ggtree}} plot @@ -119,31 +154,31 @@ #' # #' x <- altExp(GlobalPatterns,"Genus") #' plotRowTree(x[rownames(x) %in% top_genus,], -#' tip_colour_by = "log_mean", -#' tip_size_by = "detected") +#' tip.colour.by = "log_mean", +#' tip.size.by = "detected") #' #' # plot with tip labels #' plotRowTree(x[rownames(x) %in% top_genus,], -#' tip_colour_by = "log_mean", -#' tip_size_by = "detected", -#' show_label = TRUE) +#' tip.colour.by = "log_mean", +#' tip.size.by = "detected", +#' show.label = TRUE) #' # plot with selected labels #' labels <- c("Genus:Providencia", "Genus:Morganella", "0.961.60") #' plotRowTree(x[rownames(x) %in% top_genus,], -#' tip_colour_by = "log_mean", -#' tip_size_by = "detected", -#' show_label = labels, +#' tip.colour.by = "log_mean", +#' tip.size.by = "detected", +#' show.label = labels, #' layout="rectangular") #' #' # plot with labeled edges #' plotRowTree(x[rownames(x) %in% top_genus,], -#' edge_colour_by = "Phylum", -#' tip_colour_by = "log_mean") +#' edge.colour.by = "Phylum", +#' tip.colour.by = "log_mean") #' # if edges are sized, colours might disappear depending on plotting device #' plotRowTree(x[rownames(x) %in% top_genus,], -#' edge_colour_by = "Phylum", -#' edge_size_by = "detected", -#' tip_colour_by = "log_mean") +#' edge.colour.by = "Phylum", +#' edge.size.by = "detected", +#' tip.colour.by = "log_mean") #' #' # aggregating data over the taxonomic levels for plotting a taxonomic tree #' # please note that the original tree of GlobalPatterns is dropped by @@ -167,159 +202,200 @@ #' highlights <- c("Phylum:Firmicutes","Phylum:Bacteroidetes", #' "Family:Pseudomonadaceae","Order:Bifidobacteriales") #' plotRowTree(x[rowData(x)$Phylum %in% top_phyla,], -#' tip_colour_by = "log_mean", -#' node_colour_by = "log_mean", -#' show_highlights = highlights, -#' show_highlight_label = highlights, -#' colour_highlights_by = "Phylum") +#' tip.colour.by = "log_mean", +#' node.colour.by = "log_mean", +#' show.highlights = highlights, +#' show.highlight.label = highlights, +#' colour.highlights.by = "Phylum") #' #' plotRowTree(x[rowData(x)$Phylum %in% top_phyla,], -#' edge_colour_by = "Phylum", -#' edge_size_by = "detected", -#' tip_colour_by = "log_mean", -#' node_colour_by = "log_mean") +#' edge.colour.by = "Phylum", +#' edge.size.by = "detected", +#' tip.colour.by = "log_mean", +#' node.colour.by = "log_mean") NULL #' @rdname plotTree -setGeneric("plotRowTree", signature = c("object"), - function(object, ...) +setGeneric("plotRowTree", signature = c("x"), + function(x, ...) standardGeneric("plotRowTree")) #' @rdname plotTree -setGeneric("plotColTree", signature = c("object"), - function(object, ...) +setGeneric("plotColTree", signature = c("x"), + function(x, ...) standardGeneric("plotColTree")) #' @rdname plotTree #' @export -setMethod("plotColTree", signature = c(object = "TreeSummarizedExperiment"), - function(object, - tree_name = "phylo", - relabel_tree = FALSE, - order_tree = FALSE, - remove_levels = FALSE, - show_label = FALSE, - show_highlights = FALSE, - show_highlight_label = FALSE, - abbr_label = FALSE, - add_legend = TRUE, - layout = "circular", - edge_colour_by = NULL, - edge_size_by = NULL, - tip_colour_by = NULL, - tip_shape_by = NULL, - tip_size_by = NULL, - node_colour_by = NULL, - node_shape_by = NULL, - node_size_by = NULL, - colour_highlights_by = NULL, - by_exprs_values = "counts", - other_fields = list(), - ...){ - .plot_row_column_tree(object, - tree_name = tree_name, - relabel_tree = relabel_tree, - order_tree = order_tree, - remove_levels = remove_levels, - show_label = show_label, - show_highlights = show_highlights, - show_highlight_label = show_highlight_label, - abbr_label = abbr_label, - add_legend = add_legend, - layout = layout, - edge_colour_by = edge_colour_by, - edge_size_by = edge_size_by, - tip_colour_by = tip_colour_by, - tip_shape_by = tip_shape_by, - tip_size_by = tip_size_by, - node_colour_by = node_colour_by, - node_shape_by = node_shape_by, - node_size_by = node_size_by, - colour_highlights_by = colour_highlights_by, - by_exprs_values = by_exprs_values, - other_fields = other_fields, - type = "column", - ...) +setMethod("plotColTree", signature = c(x = "TreeSummarizedExperiment"), + function(x, + tree.name = tree_name, + tree_name = "phylo", + relabel.tree = relabel_tree, + relabel_tree = FALSE, + order.tree = order_tree, + order_tree = FALSE, + levels.rm = remove_levels, + remove_levels = FALSE, + show.label = show_label, + show_label = FALSE, + show.highlights = show_highlights, + show_highlights = FALSE, + show.highlight.label = show_highlight_label, + show_highlight_label = FALSE, + abbr.label = abbr_label, + abbr_label = FALSE, + add.legend = add_legend, + add_legend = TRUE, + layout = "circular", + edge.colour.by = edge.colour.by, + edge_colour_by = NULL, + edge.size.by = edge_size_by, + edge_size_by = NULL, + tip.colour.by = tip_colour_by, + tip_colour_by = NULL, + tip.shape.by = tip_shape_by, + tip_shape_by = NULL, + tip.size.by = tip_size_by, + tip_size_by = NULL, + node.colour.by = node_colour_by, + node_colour_by = NULL, + node.shape.by = node_shape_by, + node_shape_by = NULL, + node.size.by = node_size_by, + node_size_by = NULL, + colour.highlights.by = colour_highlights_by, + colour_highlights_by = NULL, + assay.type = by_exprs_values, + by_exprs_values = "counts", + other.fields = other_fields, + other_fields = list(), + ...){ + .plot_row_column_tree(x, + tree_name = tree.name, + relabel_tree = relabel.tree, + order_tree = order.tree, + remove_levels = levels.rm, + show_label = show.label, + show_highlights = show.highlights, + show_highlight_label = show.highlight.label, + abbr_label = abbr.label, + add_legend = add.legend, + layout = layout, + edge_colour_by = edge.colour.by, + edge_size_by = edge.size.by, + tip_colour_by = tip.colour.by, + tip_shape_by = tip.shape.by, + tip_size_by = tip.size.by, + node_colour_by = node.colour.by, + node_shape_by = node.shape.by, + node_size_by = node.size.by, + colour_highlights_by = colour.highlights.by, + by_exprs_values = assay.type, + other_fields = other.fields, + type = "column", + ...) } ) #' @rdname plotTree #' @export -setMethod("plotRowTree", signature = c(object = "TreeSummarizedExperiment"), - function(object, - tree_name = "phylo", - relabel_tree = FALSE, - order_tree = FALSE, - remove_levels = FALSE, - show_label = FALSE, - show_highlights = FALSE, - show_highlight_label = FALSE, - abbr_label = FALSE, - add_legend = TRUE, - layout = "circular", - edge_colour_by = NULL, - edge_size_by = NULL, - tip_colour_by = NULL, - tip_shape_by = NULL, - tip_size_by = NULL, - node_colour_by = NULL, - node_shape_by = NULL, - node_size_by = NULL, - colour_highlights_by = NULL, - by_exprs_values = "counts", - other_fields = list(), - ...){ - .plot_row_column_tree(object, - tree_name = tree_name, - relabel_tree = relabel_tree, - order_tree = order_tree, - remove_levels = remove_levels, - show_label = show_label, - show_highlights = show_highlights, - show_highlight_label = show_highlight_label, - abbr_label = abbr_label, - add_legend = add_legend, - layout = layout, - edge_colour_by = edge_colour_by, - edge_size_by = edge_size_by, - tip_colour_by = tip_colour_by, - tip_shape_by = tip_shape_by, - tip_size_by = tip_size_by, - node_colour_by = node_colour_by, - node_shape_by = node_shape_by, - node_size_by = node_size_by, - colour_highlights_by = colour_highlights_by, - by_exprs_values = by_exprs_values, - other_fields = other_fields, - type = "row", - ...) +setMethod("plotRowTree", signature = c(x = "TreeSummarizedExperiment"), + function(x, + tree.name = tree_name, + tree_name = "phylo", + relabel.tree = relabel_tree, + relabel_tree = FALSE, + order.tree = order_tree, + order_tree = FALSE, + levels.rm = remove_levels, + remove_levels = FALSE, + show.label = show_label, + show_label = FALSE, + show.highlights = show_highlights, + show_highlights = FALSE, + show.highlight.label = show_highlight_label, + show_highlight_label = FALSE, + abbr.label = abbr_label, + abbr_label = FALSE, + add.legend = add_legend, + add_legend = TRUE, + layout = "circular", + edge.colour.by = edge_colour_by, + edge_colour_by = NULL, + edge.size.by = edge_size_by, + edge_size_by = NULL, + tip.colour.by = tip_colour_by, + tip_colour_by = NULL, + tip.shape.by = tip_shape_by, + tip_shape_by = NULL, + tip.size.by = tip_size_by, + tip_size_by = NULL, + node.colour.by = node_colour_by, + node_colour_by = NULL, + node.shape.by = node_shape_by, + node_shape_by = NULL, + node.size.by = node_size_by, + node_size_by = NULL, + colour.highlights.by = colour_highlights_by, + colour_highlights_by = NULL, + assay.type = by_exprs_values, + by_exprs_values = "counts", + other.fields = other_fields, + other_fields = list(), + ...){ + # + .plot_row_column_tree(x, + tree_name = tree.name, + relabel_tree = relabel.tree, + order_tree = order.tree, + remove_levels = levels.rm, + show_label = show.label, + show_highlights = show.highlights, + show_highlight_label = show.highlight.label, + abbr_label = abbr.label, + add_legend = add.legend, + layout = layout, + edge_colour_by = edge.colour.by, + edge_size_by = edge.size.by, + tip_colour_by = tip.colour.by, + tip_shape_by = tip.shape.by, + tip_size_by = tip.size.by, + node_colour_by = node.colour.by, + node_shape_by = node.shape.by, + node_size_by = node.size.by, + colour_highlights_by = colour.highlights.by, + by_exprs_values = assay.type, + other_fields = other.fields, + type = "row", + ...) } ) .check_tree_plot_switches <- function(layout, - relabel_tree, - remove_levels, - order_tree, - show_label, - show_highlights, - show_highlight_label, - abbr_label, - add_legend){ + relabel_tree, + remove_levels, + order_tree, + show_label, + show_highlights, + show_highlight_label, + abbr_label, + add_legend){ if(!.is_a_string(layout)){ stop("'layout' must be a single character value.", call. = FALSE) } if(!.is_a_bool(relabel_tree)){ - stop("'relabel_tree' must be either TRUE or FALSE.", call. = FALSE) + stop("'relabel.tree' must be either TRUE or FALSE.", call. = FALSE) } if(!.is_a_bool(remove_levels)){ - stop("'remove_levels' must be either TRUE or FALSE.", call. = FALSE) + stop("'level.rm' must be either TRUE or FALSE.", call. = FALSE) } if(!.is_a_bool(order_tree)){ - stop("'order_tree' must be either TRUE or FALSE.", call. = FALSE) + stop("'order.tree' must be either TRUE or FALSE.", call. = FALSE) } if(!.is_a_bool(show_label)){ if( (!is.logical(show_label) && !is.character(show_label) && !is.numeric(show_label)) || is.null(show_label)){ - stop("'show_label' must be either TRUE or FALSE or logical, ", + stop("'show.label' must be either TRUE or FALSE or logical, ", "integer or character ", "vector. Character alues should match the label of the tree.", call. = FALSE) @@ -329,7 +405,7 @@ setMethod("plotRowTree", signature = c(object = "TreeSummarizedExperiment"), if( (!is.logical(show_highlights) && !is.character(show_highlights) && !is.numeric(show_highlights)) || is.null(show_highlights)){ - stop("'show_label' must be either TRUE or FALSE or logical, ", + stop("'show.label' must be either TRUE or FALSE or logical, ", "integer or character ", "vector. Character alues should match the label of the tree.", call. = FALSE) @@ -339,7 +415,7 @@ setMethod("plotRowTree", signature = c(object = "TreeSummarizedExperiment"), if( (!is.logical(show_highlight_label) && !is.character(show_highlight_label) && !is.numeric(show_highlight_label)) || is.null(show_highlight_label)){ - stop("'show_highlight_label' must be either TRUE or FALSE or logical, ", + stop("'show.highlight.label' must be either TRUE or FALSE or logical, ", "integer or character ", "vector. Character alues should match the label of the tree.", call. = FALSE) @@ -349,63 +425,63 @@ setMethod("plotRowTree", signature = c(object = "TreeSummarizedExperiment"), if( (!is.logical(abbr_label) && !is.character(abbr_label) && !is.numeric(abbr_label)) || is.null(abbr_label)){ - stop("'abbr_label' must be either TRUE or FALSE or logical, ", + stop("'abbr.label' must be either TRUE or FALSE or logical, ", "integer or character ", "vector. Character alues should match the label of the tree.", call. = FALSE) } } if(!.is_a_bool(add_legend)){ - stop("'add_legend' must be either TRUE or FALSE.", call. = FALSE) + stop("'add.legend' must be either TRUE or FALSE.", call. = FALSE) } } .plot_row_column_tree <- function(object, - tree_name = "phylo", - relabel_tree = FALSE, - order_tree = FALSE, - remove_levels = FALSE, - show_label = FALSE, - show_highlights = FALSE, - show_highlight_label = FALSE, - abbr_label = FALSE, - add_legend = TRUE, - layout = "circular", - edge_colour_by = NULL, - edge_size_by = NULL, - tip_colour_by = NULL, - tip_shape_by = NULL, - tip_size_by = NULL, - node_colour_by = NULL, - node_shape_by = NULL, - node_size_by = NULL, - colour_highlights_by = NULL, - by_exprs_values = "counts", - other_fields = list(), - type = c("row","column"), - ...){ + tree_name = "phylo", + relabel_tree = FALSE, + order_tree = FALSE, + remove_levels = FALSE, + show_label = FALSE, + show_highlights = FALSE, + show_highlight_label = FALSE, + abbr_label = FALSE, + add_legend = TRUE, + layout = "circular", + edge_colour_by = NULL, + edge_size_by = NULL, + tip_colour_by = NULL, + tip_shape_by = NULL, + tip_size_by = NULL, + node_colour_by = NULL, + node_shape_by = NULL, + node_size_by = NULL, + colour_highlights_by = NULL, + by_exprs_values = "counts", + other_fields = list(), + type = c("row","column"), + ...){ type <- match.arg(type) # input check # Check tree_name if( !.is_a_string(tree_name) ){ - stop("'tree_name' must be a single character value specifying a colTree.", + stop("'tree.name' must be a single character value specifying a colTree.", call. = FALSE) } FUN <- switch(type, row = "rowTree", column = "colTree") if(is.null(do.call(FUN,list(x = object, whichTree = tree_name)))){ - stop(FUN,"(object, tree_name) is empty.", call. = FALSE) + stop(FUN,"(object, tree.name) is empty.", call. = FALSE) } .check_tree_plot_switches(layout = layout, - relabel_tree = relabel_tree, - remove_levels = remove_levels, - order_tree = order_tree, - show_label = show_label, - show_highlights = show_highlights, - show_highlight_label = show_highlight_label, - abbr_label = abbr_label, - add_legend = add_legend) + relabel_tree = relabel_tree, + remove_levels = remove_levels, + order_tree = order_tree, + show_label = show_label, + show_highlights = show_highlights, + show_highlight_label = show_highlight_label, + abbr_label = abbr_label, + add_legend = add_legend) # tree_out <- .get_object_and_trimmed_tree( object, @@ -633,7 +709,7 @@ setMethod("plotRowTree", signature = c(object = "TreeSummarizedExperiment"), mutate(node_label = show_label) show_label <- TRUE } else if(!("node_label" %in% colnames(tree_data))){ - warning("If 'show_label' is a character with length != ", + warning("If 'show.label' is a character with length != ", "number of nodes in the graph or a logical/integer ", "vector, a 'label' ", "column must exist in the tree data.", @@ -644,7 +720,7 @@ setMethod("plotRowTree", signature = c(object = "TreeSummarizedExperiment"), if(any(show_label != as.integer(show_label)) || min(show_label) < 1 || max(show_label) > nrow(tree_data)){ - stop("If 'show_label' is numeric, values have to be whole ", + stop("If 'show.label' is numeric, values have to be whole ", "numbers and must be between 1 and the number of nodes ", "in the graph", call. = FALSE) @@ -657,7 +733,7 @@ setMethod("plotRowTree", signature = c(object = "TreeSummarizedExperiment"), } if(is.logical(show_label) && length(show_label) != nrow(tree_data)){ - stop("If 'show_label' is logical, it must have the length as ", + stop("If 'show.label' is logical, it must have the length as ", "nodes are in the graph.", call. = FALSE) } @@ -694,7 +770,7 @@ setMethod("plotRowTree", signature = c(object = "TreeSummarizedExperiment"), if(any(show_highlights != as.integer(show_highlights)) || min(show_highlights) < 1 || max(show_highlights) > nrow(tree_data)){ - stop("If 'show_highlights' is numeric, values have to be whole ", + stop("If 'show.highlights' is numeric, values have to be whole ", "numbers and must be between 1 and the number of nodes ", "in the graph", call. = FALSE) @@ -707,7 +783,7 @@ setMethod("plotRowTree", signature = c(object = "TreeSummarizedExperiment"), } if(is.logical(show_highlights) && length(show_highlights) != nrow(tree_data)){ - stop("If 'show_highlights' is logical, it must have the length as ", + stop("If 'show.highlights' is logical, it must have the length as ", "nodes are in the graph.", call. = FALSE) } @@ -750,7 +826,7 @@ setMethod("plotRowTree", signature = c(object = "TreeSummarizedExperiment"), mutate(highlight_label = show_highlight_label) show_highlight_label <- TRUE } else if(!("highlight_label" %in% colnames(tree_data))){ - warning("If 'show_highlight_label' is a character with length != ", + warning("If 'show.highlight.label' is a character with length != ", "number of nodes in the graph or a logical/integer ", "vector, a 'label' column must exist in the tree data.", call. = FALSE) @@ -760,7 +836,7 @@ setMethod("plotRowTree", signature = c(object = "TreeSummarizedExperiment"), if(any(show_highlight_label != as.integer(show_highlight_label)) || min(show_highlight_label) < 1 || max(show_highlight_label) > nrow(tree_data)){ - stop("If 'show_highlight_label' is numeric, values have ", + stop("If 'show.highlight.label' is numeric, values have ", "to be whole numbers and must be between 1 and the ", "number of nodes in the graph", call. = FALSE) @@ -774,7 +850,7 @@ setMethod("plotRowTree", signature = c(object = "TreeSummarizedExperiment"), } if(is.logical(show_highlight_label) && length(show_highlight_label) != nrow(tree_data)){ - stop("If 'show_highlight_label' is logical, it must have the ", + stop("If 'show.highlight.label' is logical, it must have the ", "length as nodes are in the graph.", call. = FALSE) } diff --git a/R/treeData.R b/R/treeData.R index a267fb8d..18aa12fa 100644 --- a/R/treeData.R +++ b/R/treeData.R @@ -8,16 +8,20 @@ #' \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}} #' object. #' -#' @param other_fields,value a \code{data.frame} or coercible to one, with at least one type +#' @param other.fields,value a \code{data.frame} or coercible to one, with at least one type #' of id information. See details. +#' +#' @param other_fields Deprecated. Use \code{other.fields} instead. #' -#' @param tree_name a single \code{character} value specifying a rowTree/colTree from -#' \code{x}. (By default: \code{tree_name = "phylo"}) +#' @param tree.name a single \code{character} value specifying a rowTree/colTree from +#' \code{x}. (By default: \code{tree.name = "phylo"}) +#' +#' @param tree_name Deprecated. Use \code{tree.name} instead. #' #' @param ... additional arguments, currently not used. #' #' @details -#' To match information to nodes, the id information in \code{other_fields} are used. +#' To match information to nodes, the id information in \code{other.fields} are used. #' These can either be a column, named \sQuote{node} or \sQuote{label} #' (\sQuote{node} taking precedent), or rownames. If all rownames can be coerced #' to \code{integer}, they are considered as \sQuote{node} values, otherwise as @@ -55,22 +59,22 @@ setGeneric("colTreeData", signature = c("x"), #' @rdname treeData setGeneric("rowTreeData<-", signature = c("x"), - function(x, tree_name = "phylo", value) + function(x, tree.name = tree_name, tree_name = "phylo", value) standardGeneric("rowTreeData<-")) #' @rdname treeData setGeneric("colTreeData<-", signature = c("x"), - function(x, tree_name = "phylo", value) + function(x, tree.name = tree_name, tree_name = "phylo", value) standardGeneric("colTreeData<-")) #' @rdname treeData setGeneric("combineTreeData", signature = c("x"), - function(x, other_fields = list()) + function(x, other.fields = other_fields, other_fields = list()) standardGeneric("combineTreeData")) #' @rdname treeData setGeneric("combineTreeData", signature = c("x"), - function(x, other_fields = list()) + function(x, other.fields = other_fields, other_fields = list()) standardGeneric("combineTreeData")) #' @importFrom tidytree as_tibble @@ -84,16 +88,16 @@ setGeneric("combineTreeData", signature = c("x"), #' @importFrom dplyr last_col #' @export setMethod("colTreeData", signature = c(x = "TreeSummarizedExperiment"), - function(x, tree_name = "phylo"){ - # Check tree_name - if( !.is_a_string(tree_name) ){ - stop("'tree_name' must be a single character value specifying a colTree.", + function(x, tree.name = tree_name, tree_name = "phylo"){ + # Check tree.name + if( !.is_a_string(tree.name) ){ + stop("'tree.name' must be a single character value specifying a colTree.", call. = FALSE) } - if(is.null(colTree(x, tree_name))){ + if(is.null(colTree(x, tree.name))){ return(NULL) } - .get_tree_data(colTree(x, tree_name)) %>% + .get_tree_data(colTree(x, tree.name)) %>% select(c("node","label":last_col())) } ) @@ -101,16 +105,16 @@ setMethod("colTreeData", signature = c(x = "TreeSummarizedExperiment"), #' @importFrom dplyr last_col #' @export setMethod("rowTreeData", signature = c(x = "TreeSummarizedExperiment"), - function(x, tree_name = "phylo"){ - # Check tree_name - if( !.is_a_string(tree_name) ){ - stop("'tree_name' must be a single character value specifying a rowTree.", + function(x, tree.name = tree_name, tree_name = "phylo"){ + # Check tree.name + if( !.is_a_string(tree.name) ){ + stop("'tree.name' must be a single character value specifying a rowTree.", call. = FALSE) } - if(is.null(rowTree(x, tree_name))){ + if(is.null(rowTree(x, tree.name))){ return(NULL) } - .get_tree_data(rowTree(x, tree_name)) %>% + .get_tree_data(rowTree(x, tree.name)) %>% select(c("node","label":last_col())) } ) @@ -124,19 +128,19 @@ DEFAULT_TREE_DATA_COLS <- c("parent","node","branch.length","label") #' @rdname treeData #' @export setReplaceMethod("colTreeData", signature = c(x = "TreeSummarizedExperiment"), - function(x, tree_name = "phylo", value){ - # Check tree_name - if( !.is_a_string(tree_name) ){ - stop("'tree_name' must be a single character value specifying a colTree.", + function(x, tree.name = tree_name, tree_name = "phylo", value){ + # Check tree.name + if( !.is_a_string(tree.name) ){ + stop("'tree.name' must be a single character value specifying a colTree.", call. = FALSE) } - tree <- colTree(x, tree_name) + tree <- colTree(x, tree.name) # input check if(is.null(tree)){ - stop("'colTree(x, tree_name)' is NULL.", call. = FALSE) + stop("'colTree(x, tree.name)' is NULL.", call. = FALSE) } # this is just temporary solution since phylo does not support data - x@colTree[[tree_name]] <- tidytree::as.phylo(combineTreeData(tree, value)) + x@colTree[[tree.name]] <- tidytree::as.phylo(combineTreeData(tree, value)) return(x) } ) @@ -145,10 +149,10 @@ setReplaceMethod("colTreeData", signature = c(x = "TreeSummarizedExperiment"), #' @importFrom tidytree as.phylo #' @export setReplaceMethod("rowTreeData", signature = c(x = "TreeSummarizedExperiment"), - function(x, tree_name = "phylo", value){ - # Check tree_name - if( !.is_a_string(tree_name) ){ - stop("'tree_name' must be a single character value specifying a rowTree.", + function(x, tree.name = tree_name, tree_name = "phylo", value){ + # Check tree.name + if( !.is_a_string(tree.name) ){ + stop("'tree.name' must be a single character value specifying a rowTree.", call. = FALSE) } tree <- rowTree(x) @@ -157,7 +161,7 @@ setReplaceMethod("rowTreeData", signature = c(x = "TreeSummarizedExperiment"), stop("'rowTree(x)' is NULL.", call. = FALSE) } # this is just temporary solution since phylo does not support data - x@rowTree[[tree_name]] <- tidytree::as.phylo(combineTreeData(tree, value)) + x@rowTree[[tree.name]] <- tidytree::as.phylo(combineTreeData(tree, value)) return(x) } ) @@ -259,15 +263,17 @@ setReplaceMethod("rowTreeData", signature = c(x = "TreeSummarizedExperiment"), #' @rdname treeData #' @export setMethod("combineTreeData", signature = c(x = "phylo"), - function(x, other_fields = list()){ - .combine_tree_and_other_fields(x, other_fields) - } + function(x, other.fields = other_fields, + other_fields = list()){ + .combine_tree_and_other_fields(x, other.fields) + } ) #' @rdname treeData #' @export setMethod("combineTreeData", signature = c(x = "treedata"), - function(x, other_fields = list()){ - .combine_tree_and_other_fields(x, other_fields) - } + function(x, other.fields = other_fields, + other_fields = list()){ + .combine_tree_and_other_fields(x, other.fields) + } ) diff --git a/man/plotAbundance.Rd b/man/plotAbundance.Rd index fa3f3afe..13b34f66 100644 --- a/man/plotAbundance.Rd +++ b/man/plotAbundance.Rd @@ -10,11 +10,15 @@ plotAbundance(x, ...) \S4method{plotAbundance}{SummarizedExperiment}( x, rank = NULL, + col.var = features, features = NULL, + order.row.by = order_rank_by, order_rank_by = c("name", "abund", "revabund"), + order.col.by = order_sample_by, order_sample_by = NULL, decreasing = TRUE, layout = c("bar", "point"), + one.facet = one_facet, one_facet = TRUE, ncol = 2, scales = "fixed", @@ -30,40 +34,48 @@ object.} \item{...}{additional parameters for plotting. \itemize{ -\item{use_relative}{ \code{TRUE} or \code{FALSE}: Should the relative values -be calculated? (default: \code{use_relative = FALSE} } +\item{as.relative}{ \code{TRUE} or \code{FALSE}: Should the relative values +be calculated? (default: \code{as.relative = FALSE} } } See \code{\link{mia-plot-args}} for more details i.e. call \code{help("mia-plot-args")}} \item{rank}{a single \code{character} value defining the taxonomic rank to use. Must be a value of \code{taxonomyRanks(x)}.} -\item{features}{a single \code{character} value defining a column from +\item{col.var}{a single \code{character} value defining a column from \code{colData} to be plotted below the abundance plot. Continuous numeric values will be plotted as point, whereas factors and -character will be plotted as colour-code bar. (default: \code{features = +character will be plotted as colour-code bar. (default: \code{col.var = NULL})} -\item{order_rank_by}{How to order abundance value: By name (\dQuote{name}) +\item{features}{Deprecated. Use \code{col.var} instead.} + +\item{order.row.by}{How to order abundance value: By name (\dQuote{name}) for sorting the taxonomic labels alphabetically, by abundance (\dQuote{abund}) to sort by abundance values or by a reverse order of abundance values (\dQuote{revabund}).} -\item{order_sample_by}{A single character value from the chosen rank of abundance +\item{order_rank_by}{Deprecated. Use \code{order.row.by} instead.} + +\item{order.col.by}{A single character value from the chosen rank of abundance data or from \code{colData} to select values to order the abundance -plot by. (default: \code{order_sample_by = NULL})} +plot by. (default: \code{order.col.by = NULL})} -\item{decreasing}{TRUE or FALSE: If the \code{order_sample_by} is defined and the +\item{order_sample_by}{Deprecated. Use \code{order.col.by} instead.} + +\item{decreasing}{TRUE or FALSE: If the \code{order.col.by} is defined and the values are numeric, should the values used to order in decreasing or increasing fashion? (default: \code{decreasing = FALSE})} \item{layout}{Either \dQuote{bar} or \dQuote{point}.} -\item{one_facet}{Should the plot be returned in on facet or split into +\item{one.facet}{Should the plot be returned in on facet or split into different facet, one facet per different value detect in \code{rank}. If -\code{features} or \code{order_sample_by} is not \code{NULL}, this setting will +\code{col.var} or \code{order.col.by} is not \code{NULL}, this setting will be disregarded.} -\item{ncol, scales}{if \code{one_facet = FALSE}, \code{ncol} defines many +\item{one_facet}{Deprecated. Use \code{one.facet} instead.} + +\item{ncol, scales}{if \code{one.facet = FALSE}, \code{ncol} defines many columns should be for plotting the different facets and \code{scales} is used to define the behavior of the scales of each facet. Both values are passed onto \code{\link[ggplot2:facet_wrap]{facet_wrap}}.} @@ -78,7 +90,7 @@ will be disabled.)} } \value{ a \code{\link[ggplot2:ggplot]{ggplot}} object or list of two -\code{\link[ggplot2:ggplot]{ggplot}} objects, if \code{features} are added to +\code{\link[ggplot2:ggplot]{ggplot}} objects, if \code{col.var} are added to the plot. } \description{ @@ -90,7 +102,7 @@ If only \sQuote{counts} is present, the relative abundance is computed. \details{ Subsetting to rows of interested and ordering of those is expected to be done outside of this functions, e.g. \code{x[1:2,]}. This will plot data of all -features present. +col.var present. } \examples{ data(GlobalPatterns, package="mia") @@ -115,19 +127,19 @@ plotAbundance( ## Using "Phylum" as rank. Apply relative transformation to "counts" assay. plotAbundance( tse, assay.type="counts", rank = "Phylum", add_legend = FALSE, - use_relative = TRUE) + as.relative = TRUE) ## A feature from colData or taxon from chosen rank can be used for ordering ## samples. plotAbundance(tse, assay.type="relabundance", rank = "Phylum", - order_sample_by = "Bacteroidetes") + order.col.by = "Bacteroidetes") -## Features from colData can be plotted together with abundance plot. +## col.var from colData can be plotted together with abundance plot. # Returned object is a list that includes two plot; other visualizes -## abundance other features. +## abundance other col.var. plot <- plotAbundance(tse, assay.type = "relabundance", rank = "Phylum", - features = "SampleType") + col.var = "SampleType") \donttest{ # These two plots can be combined with wrap_plots function from patchwork # package @@ -138,8 +150,8 @@ wrap_plots(plot, ncol = 1) ## Same plot as above but showing sample IDs as labels for the x axis on the ## top plot plot[[1]] <- plotAbundance(tse, assay.type = "relabundance", rank = "Phylum", - features = "SampleType", add_legend = FALSE, - add_x_text = TRUE)[[1]] + + col.var = "SampleType", add.legend = FALSE, + add.x.text = TRUE)[[1]] + theme(axis.text.x = element_text(angle = 90)) \donttest{ wrap_plots(plot, ncol = 1, heights = c(0.8,0.2)) @@ -160,5 +172,5 @@ rowData(tse)$Phylum <- as.character(phylum_renamed) # Compositional barplot plotAbundance(tse, assay.type="relabundance", rank = "Phylum", - order_rank_by="abund", order_sample_by = "Bacteroidetes") + order.row.by="abund", order.col.by = "Bacteroidetes") } diff --git a/man/plotAbundanceDensity.Rd b/man/plotAbundanceDensity.Rd index e2ab64b6..b4c2f9d6 100644 --- a/man/plotAbundanceDensity.Rd +++ b/man/plotAbundanceDensity.Rd @@ -5,23 +5,27 @@ \alias{plotAbundanceDensity,SummarizedExperiment-method} \title{Plot abundance density} \usage{ -plotAbundanceDensity(object, ...) +plotAbundanceDensity(x, ...) \S4method{plotAbundanceDensity}{SummarizedExperiment}( - object, + x, layout = c("jitter", "density", "point"), assay.type = assay_name, assay_name = "counts", - n = min(nrow(object), 25L), + n = min(nrow(x), 25L), + colour.by = colour_by, colour_by = NULL, + shape.by = shape_by, shape_by = NULL, + size.by = size_by, size_by = NULL, + decreasing = order_descending, order_descending = TRUE, ... ) } \arguments{ -\item{object}{a +\item{x}{a \code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}} object.} @@ -69,26 +73,34 @@ assay to use for calculation. will be disabled.)} \item{n}{a positive integer specifying the number of the most abundant taxa -to show. (default: \code{n = min(nrow(object), 25L)})} +to show. (default: \code{n = min(nrow(x), 25L)})} -\item{colour_by}{a single character value defining a column from +\item{colour.by}{a single character value defining a column from \code{colData}, that is used to color plot. Must be a value of -\code{colData()} function. (default: \code{colour_by = NULL})} +\code{colData()} function. (default: \code{colour.by = NULL})} -\item{shape_by}{a single character value defining a column from +\item{colour_by}{Deprecated. Use \code{colour.by} instead.} + +\item{shape.by}{a single character value defining a column from \code{colData}, that is used to group observations to different point shape -groups. Must be a value of \code{colData()} function. \code{shape_by} is -disabled when \code{layout = "density"}. (default: \code{shape_by = NULL})} +groups. Must be a value of \code{colData()} function. \code{shape.by} is +disabled when \code{layout = "density"}. (default: \code{shape.by = NULL})} + +\item{shape_by}{Deprecated. Use \code{shape.by} instead.} -\item{size_by}{a single character value defining a column from +\item{size.by}{a single character value defining a column from \code{colData}, that is used to group observations to different point size -groups. Must be a value of \code{colData()} function. \code{size_by} is -disabled when \code{layout = "density"}. (default: \code{size_by = NULL})} +groups. Must be a value of \code{colData()} function. \code{size.by} is +disabled when \code{layout = "density"}. (default: \code{size.by = NULL})} + +\item{size_by}{Deprecated. Use \code{size.by} instead.} + +\item{decreasing}{\code{Boolean} indicating whether the results should be ordered +in a descending order or not. If \code{NA} is given the order +as found in \code{x} for the \code{n} most abundant taxa is used. +(Default: \code{TRUE})} -\item{order_descending}{\code{TRUE}, \code{FALSE} or\code{NA}: Should the -results be ordered in a descending order? If \code{NA} is given the order -as found in \code{object} for the \code{n} most abundant taxa is used. -(default: \code{order_descending = TRUE})} +\item{order_descending}{Deprecated. Use \code{order.descending} instead.} } \value{ A \code{ggplot2} object @@ -119,7 +131,7 @@ tse <- transformAssay(tse, method = "relabundance") # "nationality" information is used to color the points. X-axis is log-scaled. plotAbundanceDensity( tse, layout = "jitter", assay.type = "relabundance", n = 10, - colour_by = "Geographical_location") + + colour.by = "Geographical_location") + scale_x_log10() # Plots the relative abundance of 10 most abundant taxa as a density plot. @@ -139,16 +151,16 @@ plotAbundanceDensity( # and adjusted for point size plotAbundanceDensity( tse, layout = "point", assay.type = "relabundance", n = 10, - shape_by = "Geographical_location", size_by = "Age", point_size=1) + shape.by = "Geographical_location", size.by = "Age", point_size=1) -# Ordering via order_descending +# Ordering via decreasing plotAbundanceDensity( - tse, assay.type = "relabundance", order_descending = FALSE) + tse, assay.type = "relabundance", decreasing = FALSE) -# for custom ordering set order_descending = NA and order the input object +# for custom ordering set decreasing = NA and order the input object # to your wishes plotAbundanceDensity( - tse, assay.type = "relabundance", order_descending = NA) + tse, assay.type = "relabundance", decreasing = NA) } \author{ diff --git a/man/plotCCA.Rd b/man/plotCCA.Rd index 0b0dd151..6aa05818 100644 --- a/man/plotCCA.Rd +++ b/man/plotCCA.Rd @@ -9,16 +9,16 @@ \alias{plotRDA,matrix-method} \title{Plot RDA or CCA object} \usage{ -plotCCA(object, ...) +plotCCA(x, ...) -\S4method{plotCCA}{SingleCellExperiment}(object, dimred, ...) +\S4method{plotCCA}{SingleCellExperiment}(x, dimred, ...) -\S4method{plotCCA}{matrix}(object, ...) +\S4method{plotCCA}{matrix}(x, ...) -plotRDA(object, ...) +plotRDA(x, ...) \S4method{plotRDA}{SingleCellExperiment}( - object, + x, dimred, add.ellipse = TRUE, ellipse.alpha = 0.2, @@ -44,10 +44,10 @@ plotRDA(object, ...) ... ) -\S4method{plotRDA}{matrix}(object, ...) +\S4method{plotRDA}{matrix}(x, ...) } \arguments{ -\item{object}{a +\item{x}{a \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-constructor]{TreeSummarizedExperiment}} or a matrix of weights. The latter is returned as output from \code{\link[mia:runCCA]{getRDA}}.} @@ -158,26 +158,26 @@ tse <- addRDA(tse, # Create RDA plot coloured by variable plotRDA(tse, "RDA", - colour_by = "ClinicalStatus") + colour.by = "ClinicalStatus") # Create RDA plot with empty ellipses plotRDA(tse, "RDA", - colour_by = "ClinicalStatus", + colour.by = "ClinicalStatus", add.ellipse = "colour") # Create RDA plot with text encased in labels plotRDA(tse, "RDA", - colour_by = "ClinicalStatus", + colour.by = "ClinicalStatus", vec.text = FALSE) # Create RDA plot without repelling text plotRDA(tse, "RDA", - colour_by = "ClinicalStatus", + colour.by = "ClinicalStatus", repel.labels = FALSE) # Create RDA plot without vectors plotRDA(tse, "RDA", - colour_by = "ClinicalStatus", + colour.by = "ClinicalStatus", add.vectors = FALSE) # Calculate RDA as a separate object diff --git a/man/plotGraph.Rd b/man/plotGraph.Rd index 758955d6..997cdb9b 100644 --- a/man/plotGraph.Rd +++ b/man/plotGraph.Rd @@ -17,16 +17,26 @@ plotRowGraph(x, y, ...) \S4method{plotColGraph}{ANY,SummarizedExperiment}( x, y, + show.label = show_label, show_label = FALSE, + add.legend = add_legend, add_legend = TRUE, layout = "kk", + edge.type = edge_type, edge_type = c("fan", "link", "arc", "parallel"), + edge.colour.by = edge_colour_by, edge_colour_by = NULL, + edge.width.by = edge_width_by, edge_width_by = NULL, + colour.by = colour_by, colour_by = NULL, + shape.by = shape_by, shape_by = NULL, + size.by = size_by, size_by = NULL, + assay.type = by_exprs_values, by_exprs_values = "counts", + other.fields = other_fields, other_fields = list(), ... ) @@ -36,16 +46,25 @@ plotRowGraph(x, y, ...) \S4method{plotRowGraph}{ANY,SummarizedExperiment}( x, y, + show.label = show_label, show_label = FALSE, + add.legend = add_legend, add_legend = TRUE, layout = "kk", + edge.type = edge_type, edge_type = c("fan", "link", "arc", "parallel"), + edge.colour.by = edge_colour_by, edge_colour_by = NULL, + edge.width.by = edge_width_by, edge_width_by = NULL, + colour.by = colour_by, colour_by = NULL, + shape.by = shape_by, shape_by = NULL, - size_by = NULL, + size.by = NULL, + assay.type = by_exprs_values, by_exprs_values = "counts", + other.fields = other_fields, other_fields = list(), ... ) @@ -62,7 +81,7 @@ For the latter object a graph object must be stored in \code{metadata(x)$name}.} \item{...}{additional arguments for plotting. See \code{\link{mia-plot-args}} for more details i.e. call \code{help("mia-plot-args")}} -\item{show_label}{\code{logical} (scalar), \code{integer} or \code{character} +\item{show.label}{\code{logical} (scalar), \code{integer} or \code{character} vector. If a \code{logical} scalar is given, should tip labels be plotted or if a logical vector is provided, which labels should be shown? If an \code{integer} or \code{character} vector is provided, it will be converted @@ -71,49 +90,69 @@ and number of nodes, whereas the values of a \code{character} vector must match values of a \code{label} or \code{name} column in the node data. In case of a \code{character} vector only values corresponding to actual labels will be plotted and if no labels are provided no labels will be -shown. (default: \code{show_label = FALSE})} +shown. (default: \code{show.label = FALSE})} + +\item{show_label}{Deprecated. Use \code{show.label} instead.} + +\item{add.legend}{logical scalar. Should legends be plotted? +(default: \code{add.legend = TRUE})} -\item{add_legend}{logical scalar. Should legends be plotted? -(default: \code{add_legend = TRUE})} +\item{add_legend}{Deprecated. Use \code{add.legend} instead.} \item{layout}{layout for the plotted graph. See \code{\link[ggraph:ggraph]{ggraph}} for details. (default: \code{layout = "kk"})} -\item{edge_type}{type of edge plotted on the graph. See +\item{edge.type}{type of edge plotted on the graph. See \code{\link[ggraph:geom_edge_fan]{geom_edge_fan}} for details and other available geoms. (default: -\code{edge_type = "fan"})} +\code{edge.type = "fan"})} -\item{edge_colour_by}{Specification of a edge metadata field to use for +\item{edge_type}{Deprecated. Use \code{edge.type} instead.} + +\item{edge.colour.by}{Specification of a edge metadata field to use for setting colours of the edges.} -\item{edge_width_by}{Specification of a edge metadata field to use for +\item{edge_colour_by}{Deprecated. Use \code{edge.colour.by} instead.} + +\item{edge.width.by}{Specification of a edge metadata field to use for setting width of the edges.} -\item{colour_by}{Specification of a column metadata field or a feature to +\item{edge_width_by}{Deprecated. Use \code{edge.width.by} instead.} + +\item{colour.by}{Specification of a column metadata field or a feature to colour graph nodes by, see the by argument in \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible values.} -\item{shape_by}{Specification of a column metadata field or a feature to +\item{colour_by}{Deprecated. Use \code{colour.by} instead.} + +\item{shape.by}{Specification of a column metadata field or a feature to shape graph nodes by, see the by argument in \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible values.} -\item{size_by}{Specification of a column metadata field or a feature to +\item{shape_by}{Deprecated. Use \code{shape.by} instead.} + +\item{size.by}{Specification of a column metadata field or a feature to size graph nodes by, see the by argument in \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible values.} -\item{by_exprs_values}{A string or integer scalar specifying which assay to +\item{size_by}{Deprecated. Use \code{size.by} instead.} + +\item{assay.type}{A string or integer scalar specifying which assay to obtain expression values from, for use in point aesthetics - see the \code{exprs_values} argument in \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}}.} -\item{other_fields}{Additional fields to include in the node information +\item{by_exprs_values}{Deprecated. Use \code{assay.type} instead.} + +\item{other.fields}{Additional fields to include in the node information without plotting them.} +\item{other_fields}{Deprecated. Use \code{other.fields} instead.} + \item{name}{If \code{x} is a \code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}} the key for subsetting the \code{metadata(x)} to a graph object.} @@ -149,57 +188,57 @@ metadata(order)$row_graph <- row_graph_order # plot a graph independently plotColGraph(col_graph, genus, - colour_by = "SampleType", - edge_colour_by = "weight", - edge_width_by = "weight", - show_label = TRUE) + colour.by = "SampleType", + edge.colour.by = "weight", + edge.width.by = "weight", + show.label = TRUE) # plot the graph stored in the object plotColGraph(genus, name = "col_graph", - colour_by = "SampleType", - edge_colour_by = "weight", - edge_width_by = "weight") + colour.by = "SampleType", + edge.colour.by = "weight", + edge.width.by = "weight") # plot a graph independently plotRowGraph(row_graph, genus, - colour_by = "Kingdom", - edge_colour_by = "weight", - edge_width_by = "weight") + colour.by = "Kingdom", + edge.colour.by = "weight", + edge.width.by = "weight") # plot the graph stored in the object plotRowGraph(genus, name = "row_graph", - colour_by = "Phylum", - edge_colour_by = "weight", - edge_width_by = "weight") + colour.by = "Phylum", + edge.colour.by = "weight", + edge.width.by = "weight") # plot a graph independently plotRowGraph(row_graph_order, order, - colour_by = "Kingdom", - edge_colour_by = "weight", - edge_width_by = "weight") + colour.by = "Kingdom", + edge.colour.by = "weight", + edge.width.by = "weight") # plot the graph stored in the object and include some labels plotRowGraph(order, name = "row_graph", - colour_by = "Phylum", - edge_colour_by = "weight", - edge_width_by = "weight", - show_label = c("Sulfolobales","Spirochaetales", + colour.by = "Phylum", + edge.colour.by = "weight", + edge.width.by = "weight", + show.label = c("Sulfolobales","Spirochaetales", "Verrucomicrobiales")) # labels can also be included via selecting specific rownames of x/y plotRowGraph(order, name = "row_graph", - colour_by = "Phylum", - edge_colour_by = "weight", - edge_width_by = "weight", - show_label = c(1,10,50)) + colour.by = "Phylum", + edge.colour.by = "weight", + edge.width.by = "weight", + show.label = c(1,10,50)) # labels can also be included via a logical vector, which has the same length # as nodes are present @@ -207,9 +246,9 @@ label_select <- rep(FALSE,nrow(order)) label_select[c(1,10,50)] <- TRUE plotRowGraph(order, name = "row_graph", - colour_by = "Phylum", - edge_colour_by = "weight", - edge_width_by = "weight", - show_label = label_select) + colour.by = "Phylum", + edge.colour.by = "weight", + edge.width.by = "weight", + show.label = label_select) } } diff --git a/man/plotPrevalence.Rd b/man/plotPrevalence.Rd index 0366e52d..d24f62e3 100644 --- a/man/plotPrevalence.Rd +++ b/man/plotPrevalence.Rd @@ -35,10 +35,15 @@ plotPrevalentAbundance(x, ...) rank = NULL, assay.type = assay_name, assay_name = "counts", + colour.by = colour_by, colour_by = NULL, + size.by = size_by, size_by = NULL, + shape.by = shape_by, shape_by = NULL, + show.label = label, label = NULL, + facet.by = facet_by, facet_by = NULL, ... ) @@ -52,6 +57,7 @@ plotRowPrevalence(x, ...) assay_name = "counts", detection = detections, detections = c(0.01, 0.1, 1, 2, 5, 10, 20), + min.prevalence = min_prevalence, min_prevalence = 0, BPPARAM = BiocParallel::SerialParam(), ... @@ -72,13 +78,13 @@ object.} \item{detection}{Detection thresholds for absence/presence. Either an absolutes value compared directly to the values of \code{x} or a relative -value between 0 and 1, if \code{as_relative = TRUE}.} +value between 0 and 1, if \code{as.relative = TRUE}.} \item{detections}{Deprecated. Use \code{detection} instead.} \item{prevalence}{Prevalence thresholds (in 0 to 1). The required prevalence is strictly greater by default. To include the -limit, set \code{include_lowest} to \code{TRUE}.} +limit, set \code{include.lowest} to \code{TRUE}.} \item{prevalences}{Deprecated. Use \code{prevalence} instead.} @@ -92,7 +98,7 @@ will be disabled.)} \item{rank, ...}{additional arguments \itemize{ -\item{use_relative}{ \code{TRUE} or \code{FALSE}: Should the relative values +\item{as.relative}{ \code{TRUE} or \code{FALSE}: Should the relative values be calculated? (Default: \code{FALSE}) } \item{ndetection}{ \code{Integer scalar}. Determines the number of breaks @@ -114,32 +120,44 @@ calculated detection thresholds when \code{detection=NULL}. When \code{\link[BiocParallel:BiocParallelParam-class]{BiocParallelParam}} object specifying whether the UniFrac calculation should be parallelized.} -\item{colour_by}{Specification of a feature to colour points by, see the +\item{colour.by}{Specification of a feature to colour points by, see the \code{by} argument in \code{\link[scater:retrieveFeatureInfo]{?retrieveFeatureInfo}} for possible values. Only used with \code{layout = "point"}.} -\item{size_by}{Specification of a feature to size points by, see the +\item{colour_by}{Deprecated. Use \code{colour.by} instead.} + +\item{size.by}{Specification of a feature to size points by, see the \code{by} argument in \code{\link[scater:retrieveFeatureInfo]{?retrieveFeatureInfo}} for possible values. Only used with \code{layout = "point"}.} -\item{shape_by}{Specification of a feature to shape points by, see the +\item{size_by}{Deprecated. Use \code{size.by} instead.} + +\item{shape.by}{Specification of a feature to shape points by, see the \code{by} argument in \code{\link[scater:retrieveFeatureInfo]{?retrieveFeatureInfo}} for possible values. Only used with \code{layout = "point"}.} -\item{label}{a \code{logical}, \code{character} or \code{integer} vector +\item{shape_by}{Deprecated. Use \code{shape.by} instead.} + +\item{show.label}{a \code{logical}, \code{character} or \code{integer} vector for selecting labels from the rownames of \code{x}. If \code{rank} is not -\code{NULL} the rownames might change. (default: \code{label = NULL})} +\code{NULL} the rownames might change. (default: \code{show.label = NULL})} -\item{facet_by}{Taxonomic rank to facet the plot by. +\item{label}{Deprecated. Use \code{show.label} instead.} + +\item{facet.by}{Taxonomic rank to facet the plot by. Value must be of \code{taxonomyRanks(x)} Argument can only be used in function plotPrevalentAbundance.} -\item{min_prevalence}{a single numeric value to apply as a threshold for +\item{facet_by}{Deprecated. Use \code{facet.by} instead.} + +\item{min.prevalence}{a single numeric value to apply as a threshold for plotting. The threshold is applied per row and column. (default: \code{min_prevalence = 0})} + +\item{min_prevalence}{Deprecated. Use \code{min.prevalence} instead.} } \value{ A \code{ggplot2} object or \code{plotly} object, if more than one @@ -182,14 +200,14 @@ plotRowPrevalence( # point layout for plotRowPrevalence can be used to visualize by additional # information plotPrevalentAbundance( - GlobalPatterns, rank = "Family", colour_by = "Phylum") + + GlobalPatterns, rank = "Family", colour.by = "Phylum") + scale_x_log10() # When using function plotPrevalentAbundace, it is possible to create facets -# with 'facet_by'. +# with 'facet.by'. plotPrevalentAbundance( GlobalPatterns, rank = "Family", - colour_by = "Phylum", facet_by = "Kingdom") + + colour.by = "Phylum", facet.by = "Kingdom") + scale_x_log10() } \seealso{ diff --git a/man/plotSeries.Rd b/man/plotSeries.Rd index a6c4bd29..5d9296d6 100644 --- a/man/plotSeries.Rd +++ b/man/plotSeries.Rd @@ -10,8 +10,11 @@ plotSeries( x, y = NULL, rank = NULL, + colour.by = colour_by, colour_by = NULL, + size.by = size_by, size_by = NULL, + linetype.by = linetype_by, linetype_by = NULL, assay.type = assay_name, assay_name = "counts", @@ -23,8 +26,11 @@ plotSeries( x, y = NULL, rank = NULL, + colour.by = colour_by, colour_by = NULL, + size.by = size_by, size_by = NULL, + linetype.by = linetype_by, linetype_by = NULL, assay.type = assay_name, assay_name = "counts", @@ -48,17 +54,23 @@ This parameter specifies taxa whose abundances will be plotted.} to agglomerate the data. Must be a value of \code{taxonomicRanks()} function.} -\item{colour_by}{a single character value defining a taxonomic rank, that is used to +\item{colour.by}{a single character value defining a taxonomic rank, that is used to color plot. Must be a value of \code{taxonomicRanks()} function.} -\item{size_by}{a single character value defining a taxonomic rank, that is +\item{colour_by}{Deprecated. Use \code{colour.by} instead.} + +\item{size.by}{a single character value defining a taxonomic rank, that is used to divide taxa to different line size types. Must be a value of \code{taxonomicRanks()} function.} -\item{linetype_by}{a single character value defining a taxonomic rank, that +\item{size_by}{Deprecated. Use \code{size.by} instead.} + +\item{linetype.by}{a single character value defining a taxonomic rank, that is used to divide taxa to different line types. Must be a value of \code{taxonomicRanks()} function.} +\item{linetype_by}{Deprecated. Use \code{linetype.by} instead.} + \item{assay.type}{a single character value for selecting the \code{\link[SummarizedExperiment:SummarizedExperiment-class]{assay}} to be plotted. (default: \code{assay.type = "counts"})} @@ -93,7 +105,7 @@ object <- SilvermanAGutData plotSeries(object, x = "DAY_ORDER", y = getTop(object, 2), - colour_by = "Family") + colour.by = "Family") # Counts relative abundances object <- transformAssay(object, method = "relabundance") @@ -104,16 +116,16 @@ taxa <- c("seq_1", "seq_2", "seq_3", "seq_4", "seq_5") # Plots relative abundances of phylums plotSeries(object[taxa,], x = "DAY_ORDER", - colour_by = "Family", - linetype_by = "Phylum", + colour.by = "Family", + linetype.by = "Phylum", assay.type = "relabundance") -# In addition to 'colour_by' and 'linetype_by', 'size_by' can also be used to group taxa. +# In addition to 'colour.by' and 'linetype.by', 'size.by' can also be used to group taxa. plotSeries(object, x = "DAY_ORDER", y = getTop(object, 5), - colour_by = "Family", - size_by = "Phylum", + colour.by = "Family", + size.by = "Phylum", assay.type = "counts") } } diff --git a/man/plotTree.Rd b/man/plotTree.Rd index c76ad51f..7b184308 100644 --- a/man/plotTree.Rd +++ b/man/plotTree.Rd @@ -8,85 +8,133 @@ \alias{plotRowTree,TreeSummarizedExperiment-method} \title{Plotting tree information enriched with information} \usage{ -plotRowTree(object, ...) +plotRowTree(x, ...) -plotColTree(object, ...) +plotColTree(x, ...) \S4method{plotColTree}{TreeSummarizedExperiment}( - object, + x, + tree.name = tree_name, tree_name = "phylo", + relabel.tree = relabel_tree, relabel_tree = FALSE, + order.tree = order_tree, order_tree = FALSE, + levels.rm = remove_levels, remove_levels = FALSE, + show.label = show_label, show_label = FALSE, + show.highlights = show_highlights, show_highlights = FALSE, + show.highlight.label = show_highlight_label, show_highlight_label = FALSE, + abbr.label = abbr_label, abbr_label = FALSE, + add.legend = add_legend, add_legend = TRUE, layout = "circular", + edge.colour.by = edge.colour.by, edge_colour_by = NULL, + edge.size.by = edge_size_by, edge_size_by = NULL, + tip.colour.by = tip_colour_by, tip_colour_by = NULL, + tip.shape.by = tip_shape_by, tip_shape_by = NULL, + tip.size.by = tip_size_by, tip_size_by = NULL, + node.colour.by = node_colour_by, node_colour_by = NULL, + node.shape.by = node_shape_by, node_shape_by = NULL, + node.size.by = node_size_by, node_size_by = NULL, + colour.highlights.by = colour_highlights_by, colour_highlights_by = NULL, + assay.type = by_exprs_values, by_exprs_values = "counts", + other.fields = other_fields, other_fields = list(), ... ) \S4method{plotRowTree}{TreeSummarizedExperiment}( - object, + x, + tree.name = tree_name, tree_name = "phylo", + relabel.tree = relabel_tree, relabel_tree = FALSE, + order.tree = order_tree, order_tree = FALSE, + levels.rm = remove_levels, remove_levels = FALSE, + show.label = show_label, show_label = FALSE, + show.highlights = show_highlights, show_highlights = FALSE, + show.highlight.label = show_highlight_label, show_highlight_label = FALSE, + abbr.label = abbr_label, abbr_label = FALSE, + add.legend = add_legend, add_legend = TRUE, layout = "circular", + edge.colour.by = edge_colour_by, edge_colour_by = NULL, + edge.size.by = edge_size_by, edge_size_by = NULL, + tip.colour.by = tip_colour_by, tip_colour_by = NULL, + tip.shape.by = tip_shape_by, tip_shape_by = NULL, + tip.size.by = tip_size_by, tip_size_by = NULL, + node.colour.by = node_colour_by, node_colour_by = NULL, + node.shape.by = node_shape_by, node_shape_by = NULL, + node.size.by = node_size_by, node_size_by = NULL, + colour.highlights.by = colour_highlights_by, colour_highlights_by = NULL, + assay.type = by_exprs_values, by_exprs_values = "counts", + other.fields = other_fields, other_fields = list(), ... ) } \arguments{ -\item{object}{a +\item{x}{a \code{\link[TreeSummarizedExperiment:TreeSummarizedExperiment-class]{TreeSummarizedExperiment}} -object.} +x.} \item{...}{additional arguments for plotting. See \code{\link{mia-plot-args}} for more details i.e. call \code{help("mia-plot-args")}} -\item{tree_name}{a single \code{character} value specifying a rowTree/colTree from -\code{object}. (By default: \code{tree_name = "phylo"})} +\item{tree.name}{a single \code{character} value specifying a rowTree/colTree from +\code{x}. (By default: \code{tree.name = "phylo"})} -\item{relabel_tree}{logical scalar, Should the tip labels be relabeled using -the output of \code{getTaxonomyLabels(object, with_rank = TRUE)}? -(default: \code{relabel_tree = FALSE})} +\item{tree_name}{Deprecated. Use \code{tree.name} instead.} -\item{order_tree}{logical scalar, Should the tree be ordered based on +\item{relabel.tree}{logical scalar, Should the tip labels be relabeled using +the output of \code{getTaxonomyLabels(x, with_rank = TRUE)}? +(default: \code{relabel.tree = FALSE})} + +\item{relabel_tree}{Deprecated. Use \code{relavel.tree} instead.} + +\item{order.tree}{logical scalar, Should the tree be ordered based on alphabetic order of taxonomic levels? -(default: \code{order_tree = FALSE})} +(default: \code{order.tree = FALSE})} + +\item{order_tree}{Deprecated. Use \code{order.tree} instead.} -\item{remove_levels}{logical scalar, Should taxonomic level information -be removed from labels? (default: \code{relabel_tree = FALSE})} +\item{levels.rm}{logical scalar, Should taxonomic level information +be removed from labels? (default: \code{levels.rm = FALSE})} -\item{show_label, show_highlights, show_highlight_label, abbr_label}{\code{logical} (scalar), \code{integer} or \code{character} vector. If a +\item{remove_levels}{Deprecated. Use \code{levels.rm} instead.} + +\item{show.label, show.highlights, show.highlight.label, abbr.label}{\code{logical} (scalar), \code{integer} or \code{character} vector. If a \code{logical} scalar is given, should tip labels be plotted or if a logical vector is provided, which labels should be shown? If an \code{integer} or \code{character} vector is provided, it will be converted @@ -97,57 +145,84 @@ match values of the \code{label} column in the node data. In case of a plotted and if no labels are provided no labels will be shown. (default: \code{FALSE})} -\item{add_legend}{logical scalar. Should legends be plotted? -(default: \code{add_legend = TRUE})} +\item{show_label, show_highlights, show_highlight_label, abbr_label}{Deprecated. +Use \code{show.label, show.highlights, show.highlight.label, abbr_label} instead.} + +\item{add.legend}{logical scalar. Should legends be plotted? +(default: \code{add.legend = TRUE})} + +\item{add_legend}{Deprecated. Use \code{add.legend} instead.} \item{layout}{layout for the plotted tree. See \code{\link[ggtree:ggtree]{ggtree}} for details.} -\item{edge_colour_by}{Specification of a column metadata field or a feature +\item{edge.colour.by}{Specification of a column metadata field or a feature to colour tree edges by, see the by argument in \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible values.} -\item{edge_size_by}{Specification of a column metadata field or a feature +\item{edge_colour_by}{Deprecated. Use \code{edge.colour.by} instead.} + +\item{edge.size.by}{Specification of a column metadata field or a feature to size tree edges by, see the by argument in \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible values.} -\item{tip_colour_by}{Specification of a column metadata field or a feature to +\item{edge_size_by}{Deprecated. Use \code{edge.size.by} instead.} + +\item{tip.colour.by}{Specification of a column metadata field or a feature to colour tree tips by, see the by argument in \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible values.} -\item{tip_shape_by}{Specification of a column metadata field or a feature to +\item{tip_colour_by}{Deprecated. Use \code{tip.colour.by} instead.} + +\item{tip.shape.by}{Specification of a column metadata field or a feature to shape tree tips by, see the by argument in \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible values.} -\item{tip_size_by}{Specification of a column metadata field or a feature to +\item{tip_shape_by}{Deprecated. Use \code{tip.shape.by} isntead.} + +\item{tip.size.by}{Specification of a column metadata field or a feature to size tree tips by, see the by argument in \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}} for possible values.} -\item{node_colour_by}{Specification of a column metadata field or a feature to -colour tree nodes by. Must be a field from \code{other_fields}.} +\item{tip_size_by}{Deprecated. Use \code{tip.size.by} instead.} + +\item{node.colour.by}{Specification of a column metadata field or a feature to +colour tree nodes by. Must be a field from \code{other.fields}.} + +\item{node_colour_by}{Deprecated. Use \code{node.colour.by} instead.} + +\item{node.shape.by}{Specification of a column metadata field or a feature to +shape tree nodes by. Must be a field from \code{other.fields}.} -\item{node_shape_by}{Specification of a column metadata field or a feature to -shape tree nodes by. Must be a field from \code{other_fields}.} +\item{node_shape_by}{Deprecated. Use \code{node.shape.by} instead.} -\item{node_size_by}{Specification of a column metadata field or a feature to -size tree nodes by. Must be a field from \code{other_fields}.} +\item{node.size.by}{Specification of a column metadata field or a feature to +size tree nodes by. Must be a field from \code{other.fields}.} -\item{colour_highlights_by}{Should the highlights be colour differently? -If \code{show_highlights = TRUE}, \code{colour_highlights} will be set to +\item{node_size_by}{Deprecated. Use \code{node.size.by} instead.} + +\item{colour.highlights.by}{Should the highlights be colour differently? +If \code{show.highlights = TRUE}, \code{colour_highlights} will be set to \code{TRUE} as default. (default: \code{colour_highlights = FALSE})} -\item{by_exprs_values}{A string or integer scalar specifying which assay to +\item{colour_highlights_by}{Deprecated. Use \code{colour.highlights.by} isntead.} + +\item{assay.type}{A string or integer scalar specifying which assay to obtain expression values from, for use in point aesthetics - see the \code{exprs_values} argument in \code{\link[scater:retrieveCellInfo]{?retrieveCellInfo}}.} -\item{other_fields}{Additional fields to include in the node information +\item{by_exprs_values}{Deprecated. Use \code{assay.type} instead.} + +\item{other.fields}{Additional fields to include in the node information without plotting them.} + +\item{other_fields}{Deprecated. Use \code{other.fields} instead.} } \value{ a \code{\link{ggtree}} plot @@ -159,7 +234,7 @@ be plotted. From the \code{rowData}, the \code{assays} as well as the additional information. } \details{ -If \code{show_label} or \code{show_highlight_label} have the same length +If \code{show.label} or \code{show.highlight.label} have the same length as the number of nodes, the vector will be used to relabel the nodes. } \examples{ @@ -180,31 +255,31 @@ top_genus <- getTop(altExp(GlobalPatterns,"Genus"), # x <- altExp(GlobalPatterns,"Genus") plotRowTree(x[rownames(x) \%in\% top_genus,], - tip_colour_by = "log_mean", - tip_size_by = "detected") + tip.colour.by = "log_mean", + tip.size.by = "detected") # plot with tip labels plotRowTree(x[rownames(x) \%in\% top_genus,], - tip_colour_by = "log_mean", - tip_size_by = "detected", - show_label = TRUE) + tip.colour.by = "log_mean", + tip.size.by = "detected", + show.label = TRUE) # plot with selected labels labels <- c("Genus:Providencia", "Genus:Morganella", "0.961.60") plotRowTree(x[rownames(x) \%in\% top_genus,], - tip_colour_by = "log_mean", - tip_size_by = "detected", - show_label = labels, + tip.colour.by = "log_mean", + tip.size.by = "detected", + show.label = labels, layout="rectangular") # plot with labeled edges plotRowTree(x[rownames(x) \%in\% top_genus,], - edge_colour_by = "Phylum", - tip_colour_by = "log_mean") + edge.colour.by = "Phylum", + tip.colour.by = "log_mean") # if edges are sized, colours might disappear depending on plotting device plotRowTree(x[rownames(x) \%in\% top_genus,], - edge_colour_by = "Phylum", - edge_size_by = "detected", - tip_colour_by = "log_mean") + edge.colour.by = "Phylum", + edge.size.by = "detected", + tip.colour.by = "log_mean") # aggregating data over the taxonomic levels for plotting a taxonomic tree # please note that the original tree of GlobalPatterns is dropped by @@ -228,17 +303,17 @@ x <- addHierarchyTree(x) highlights <- c("Phylum:Firmicutes","Phylum:Bacteroidetes", "Family:Pseudomonadaceae","Order:Bifidobacteriales") plotRowTree(x[rowData(x)$Phylum \%in\% top_phyla,], - tip_colour_by = "log_mean", - node_colour_by = "log_mean", - show_highlights = highlights, - show_highlight_label = highlights, - colour_highlights_by = "Phylum") + tip.colour.by = "log_mean", + node.colour.by = "log_mean", + show.highlights = highlights, + show.highlight.label = highlights, + colour.highlights.by = "Phylum") plotRowTree(x[rowData(x)$Phylum \%in\% top_phyla,], - edge_colour_by = "Phylum", - edge_size_by = "detected", - tip_colour_by = "log_mean", - node_colour_by = "log_mean") + edge.colour.by = "Phylum", + edge.size.by = "detected", + tip.colour.by = "log_mean", + node.colour.by = "log_mean") } \seealso{ \code{\link[mia:agglomerate-methods]{agglomerateByRanks}} diff --git a/man/treeData.Rd b/man/treeData.Rd index 463bb44d..6c181c1c 100644 --- a/man/treeData.Rd +++ b/man/treeData.Rd @@ -19,25 +19,25 @@ rowTreeData(x, ...) colTreeData(x, ...) -rowTreeData(x, tree_name = "phylo") <- value +rowTreeData(x, tree.name = tree_name, tree_name = "phylo") <- value -colTreeData(x, tree_name = "phylo") <- value +colTreeData(x, tree.name = tree_name, tree_name = "phylo") <- value -combineTreeData(x, other_fields = list()) +combineTreeData(x, other.fields = other_fields, other_fields = list()) -combineTreeData(x, other_fields = list()) +combineTreeData(x, other.fields = other_fields, other_fields = list()) -\S4method{colTreeData}{TreeSummarizedExperiment}(x, tree_name = "phylo") +\S4method{colTreeData}{TreeSummarizedExperiment}(x, tree.name = tree_name, tree_name = "phylo") -\S4method{rowTreeData}{TreeSummarizedExperiment}(x, tree_name = "phylo") +\S4method{rowTreeData}{TreeSummarizedExperiment}(x, tree.name = tree_name, tree_name = "phylo") -\S4method{colTreeData}{TreeSummarizedExperiment}(x, tree_name = "phylo") <- value +\S4method{colTreeData}{TreeSummarizedExperiment}(x, tree.name = tree_name, tree_name = "phylo") <- value -\S4method{rowTreeData}{TreeSummarizedExperiment}(x, tree_name = "phylo") <- value +\S4method{rowTreeData}{TreeSummarizedExperiment}(x, tree.name = tree_name, tree_name = "phylo") <- value -\S4method{combineTreeData}{phylo}(x, other_fields = list()) +\S4method{combineTreeData}{phylo}(x, other.fields = other_fields, other_fields = list()) -\S4method{combineTreeData}{treedata}(x, other_fields = list()) +\S4method{combineTreeData}{treedata}(x, other.fields = other_fields, other_fields = list()) } \arguments{ \item{x}{a @@ -46,11 +46,15 @@ object.} \item{...}{additional arguments, currently not used.} -\item{tree_name}{a single \code{character} value specifying a rowTree/colTree from -\code{x}. (By default: \code{tree_name = "phylo"})} +\item{tree.name}{a single \code{character} value specifying a rowTree/colTree from +\code{x}. (By default: \code{tree.name = "phylo"})} -\item{other_fields, value}{a \code{data.frame} or coercible to one, with at least one type +\item{tree_name}{Deprecated. Use \code{tree.name} instead.} + +\item{other.fields, value}{a \code{data.frame} or coercible to one, with at least one type of id information. See details.} + +\item{other_fields}{Deprecated. Use \code{other.fields} instead.} } \value{ a \code{data.frame} for the accessor and the modified @@ -63,7 +67,7 @@ To facilitate the dressing of the tree data stored in a \code{colTreeData} can be used. } \details{ -To match information to nodes, the id information in \code{other_fields} are used. +To match information to nodes, the id information in \code{other.fields} are used. These can either be a column, named \sQuote{node} or \sQuote{label} (\sQuote{node} taking precedent), or rownames. If all rownames can be coerced to \code{integer}, they are considered as \sQuote{node} values, otherwise as diff --git a/tests/testthat/test-1treeData.R b/tests/testthat/test-1treeData.R index a15c3724..1e1ede65 100644 --- a/tests/testthat/test-1treeData.R +++ b/tests/testthat/test-1treeData.R @@ -15,7 +15,7 @@ test_that("tree data", { expect_equal(colnames(actual), c("parent","node","branch.length","label")) # .norm_other_fields expect_error(miaViz:::.norm_other_fields(), - 'argument "other_fields" is missing') + 'argument "other.fields" is missing') expect_error(miaViz:::.norm_other_fields(list(a=c(1,2), b=c(2,3,4)))) expect_null(miaViz:::.norm_other_fields(NULL)) expect_null(miaViz:::.norm_other_fields(data.frame())) @@ -27,7 +27,7 @@ test_that("tree data", { expect_equal(actual, miaViz:::.norm_other_fields(other_fields)) # .norm_id_col_of_other_fields expect_error(miaViz:::.norm_id_col_of_other_fields(), - 'argument "other_fields" is missing') + 'argument "other.fields" is missing') expect_error(miaViz:::.norm_id_col_of_other_fields(other_fields)) expect_warning(miaViz:::.norm_id_col_of_other_fields(other_fields, td), "Not all 'node' values found in tree data") @@ -38,7 +38,7 @@ test_that("tree data", { expect_null(miaViz:::.norm_id_col_of_other_fields(NULL)) # .combine_tree_data_and_other_fields expect_error(miaViz:::.combine_tree_data_and_other_fields(td), - 'argument "other_fields" is missing') + 'argument "other.fields" is missing') expect_equal(td, miaViz:::.combine_tree_data_and_other_fields(td, NULL)) actual <- miaViz:::.combine_tree_data_and_other_fields(td, other_fields) expect_equal(colnames(actual), @@ -49,16 +49,13 @@ test_that("tree data", { expect_equal(combineTreeData(rowTree(x)), tidytree::as.treedata(td)) expect_equal(combineTreeData(rowTree(x), other_fields), tidytree::as.treedata(actual)) - # Test situation when tree_name is wrong - expect_equal( colTreeData(x, tree_name = "phylo"), NULL ) - expect_equal( rowTreeData(x, tree_name = "phylo.1"), NULL ) - expect_error( colTreeData(x, tree_name = 1) ) - expect_error( rowTreeData(x, tree_name = TRUE) ) - expect_error( rowTreeData(x, tree_name = c("test", "test2")) ) + # Test situation when tree.name is wrong + expect_equal( colTreeData(x, tree.name = "phylo"), NULL ) + expect_equal( rowTreeData(x, tree.name = "phylo.1"), NULL ) + expect_error( colTreeData(x, tree.name = 1) ) + expect_error( rowTreeData(x, tree.name = TRUE) ) + expect_error( rowTreeData(x, tree.name = c("test", "test2")) ) td <- rowTreeData(x) rowTreeData(x, "test") <- td expect_equal(names(x@rowTree), c("phylo", "test")) - data(esophagus) - tse <- mia::mergeSEs(esophagus, GlobalPatterns) - expect_equal( rowTreeData(tse, "phylo"), rowTreeData(esophagus, "phylo") ) }) diff --git a/tests/testthat/test-2plotAbundance.R b/tests/testthat/test-2plotAbundance.R index 5dcc3136..9396ebee 100644 --- a/tests/testthat/test-2plotAbundance.R +++ b/tests/testthat/test-2plotAbundance.R @@ -24,15 +24,15 @@ test_that("plot abundance", { expect_equal(as.character(actual[1,1,drop=TRUE]),"ABY1_OD1") expect_equal(as.character(actual2[1,1,drop=TRUE]),"Proteobacteria") actual3 <- miaViz:::.get_abundance_data(x,"Phylum","counts", - order_rank_by = "abund", - use_relative = FALSE) + order.row.by = "abund", + as.relative = FALSE) expect_true(max(actual3$Y) > 1) # .norm_order_sample_by expect_true(is.null(miaViz:::.norm_order_sample_by(NULL))) expect_error(miaViz:::.norm_order_sample_by("meep"), 'argument "factors" is missing') expect_error(miaViz:::.norm_order_sample_by("meep","meep2",x), - "'order_sample_by' must be a single non-empty character value") + "'order.col.by' must be a single non-empty character value") expect_equal(miaViz:::.norm_order_sample_by("Primer","meep2",x),"Primer") # .get_feature_data expect_true(is.null(miaViz:::.get_feature_data())) @@ -70,8 +70,8 @@ test_that("plot abundance", { expect_s3_class(plot,"ggplot") expect_named(plot$data,c("colour_by","X","Y")) plot <- plotAbundance(x, assay.type="counts", rank = "Phylum", - features = "SampleType", - order_sample_by = "SampleType") + col.var = "SampleType", + order.col.by = "SampleType") expect_true(is.list(plot)) expect_s3_class(plot[[1]],"ggplot") }) diff --git a/tests/testthat/test-2plotGraph.R b/tests/testthat/test-2plotGraph.R index d2bc6462..c3f0c986 100644 --- a/tests/testthat/test-2plotGraph.R +++ b/tests/testthat/test-2plotGraph.R @@ -4,15 +4,15 @@ test_that("plot graph", { library(tidygraph) # .check_graph_plot_switches expect_error(miaViz:::.check_graph_plot_switches(), - 'argument "show_label" is missing') + 'argument "show.label" is missing') expect_error(miaViz:::.check_graph_plot_switches(TRUE), - 'argument "add_legend" is missing') + 'argument "add.legend" is missing') expect_error(miaViz:::.check_graph_plot_switches(TRUE, 1), "'add_legend' must be either TRUE or FALSE") expect_null(miaViz:::.check_graph_plot_switches(1, FALSE)) # .norm_layout_edge_type expect_error(miaViz:::.norm_layout_edge_type(), - 'argument "edge_type" is missing') + 'argument "edge.type" is missing') expect_error(miaViz:::.norm_layout_edge_type("meep","meep"), "'arg' should be one") # @@ -37,7 +37,7 @@ test_that("plot graph", { rep(FALSE, nrow(actual %>% activate("nodes") %>% as.data.frame()))) expect_error(miaViz:::.add_graph_node_labels(actual,show_label), - "If 'show_label' is logical") + "If 'show.label' is logical") show_label <- show_label[-length(show_label)] actual2 <- miaViz:::.add_graph_node_labels(actual,show_label) expect_named(actual2$df %>% activate("nodes") %>% as.data.frame(), @@ -53,17 +53,17 @@ test_that("plot graph", { genus <- agglomerateByRank(GlobalPatterns,"Genus",na.rm=TRUE) plot <- plotColGraph(col_graph, genus, - colour_by = "SampleType", - edge_colour_by = "weight", - edge_width_by = "weight", - show_label = TRUE) + colour.by = "SampleType", + edge.colour.by = "weight", + edge.width.by = "weight", + show.label = TRUE) expect_s3_class(plot,"ggplot") metadata(genus)$col_graph <- col_graph plot2 <- plotColGraph(genus, name = "col_graph", - colour_by = "SampleType", - edge_colour_by = "weight", - edge_width_by = "weight", - show_label = TRUE) + colour.by = "SampleType", + edge.colour.by = "weight", + edge.width.by = "weight", + show.label = TRUE) expect_true(all(plot$data == plot2$data)) }) diff --git a/tests/testthat/test-2plotPrevalence.R b/tests/testthat/test-2plotPrevalence.R index 26e59cb4..b77b3c41 100644 --- a/tests/testthat/test-2plotPrevalence.R +++ b/tests/testthat/test-2plotPrevalence.R @@ -11,7 +11,7 @@ test_that("plot prevalence", { # .get_prevalence_count expect_equal(miaViz:::.get_prevalence_count(1,2,mat),0) expect_equal( - miaViz:::.get_prevalence_count(1,1,mat, include_lowest = TRUE),49) + miaViz:::.get_prevalence_count(1,1,mat, include.lowest = TRUE),49) # .get_prevalence_plot_data actual <- miaViz:::.get_prevalence_plot_data(se,"counts", c(0.1,0.2), @@ -24,7 +24,7 @@ test_that("plot prevalence", { expect_s3_class(plot,"ggplot") expect_equal(dim(plot$data),c(70,3)) plot <- plotPrevalentAbundance(GlobalPatterns, rank = "Family", - colour_by = "Phylum") + colour.by = "Phylum") expect_s3_class(plot,"ggplot") expect_equal(dim(plot$data),c(341,4)) }) diff --git a/tests/testthat/test-2plotTree.R b/tests/testthat/test-2plotTree.R index a9687c1d..04f3563e 100644 --- a/tests/testthat/test-2plotTree.R +++ b/tests/testthat/test-2plotTree.R @@ -31,13 +31,13 @@ test_that("plot tree", { # expect_error(miaViz:::.check_tree_plot_switches("A","TRUE", TRUE,TRUE,TRUE, TRUE, TRUE,TRUE, TRUE), - "'relabel_tree' must be either TRUE or FALSE") + "'relabel.tree' must be either TRUE or FALSE") expect_error(miaViz:::.check_tree_plot_switches("A",TRUE, 2, TRUE,TRUE, TRUE, TRUE,TRUE, TRUE), - "'remove_levels' must be either TRUE or FALSE") + "'level.rm' must be either TRUE or FALSE") expect_error(miaViz:::.check_tree_plot_switches("A",TRUE, TRUE, 2, TRUE, TRUE, TRUE,TRUE, TRUE), - "'order_tree' must be either TRUE or FALSE") + "'order.tree' must be either TRUE or FALSE") expect_null(miaViz:::.check_tree_plot_switches("A",TRUE, TRUE, TRUE, 2, TRUE, TRUE,TRUE, TRUE)) # @@ -67,26 +67,26 @@ test_that("plot tree", { assay.type="counts") # plot <- expect_warning(plotRowTree(altExp(GlobalPatterns,"genus")[top_taxa,], - tip_colour_by = "log_mean", - tip_size_by = "detected")) + tip.colour.by = "log_mean", + tip.size.by = "detected")) expect_true(all(c("colour_by", "size_by") %in% colnames(plot$data))) # plot with tip labels plot <- expect_warning(plotRowTree(altExp(GlobalPatterns,"genus")[top_taxa,], - tip_colour_by = "log_mean", - show_label = TRUE)) + tip.colour.by = "log_mean", + show.label = TRUE)) expect_true(all(c("colour_by") %in% colnames(plot$data))) # plot with selected labels labels <- c("Genus:Providencia", "Genus:Morganella", "0.961.60") plot <- expect_warning(plotRowTree(altExp(GlobalPatterns,"genus")[top_taxa,], - tip_colour_by = "log_mean", - tip_size_by = "detected", - show_label = labels, + tip.colour.by = "log_mean", + tip.size.by = "detected", + show.label = labels, layout="rectangular")) expect_true(all(c("colour_by", "size_by") %in% colnames(plot$data))) - # Test that error occurs if tree_name is wrong - expect_error( plotRowTree(GlobalPatterns, tree_name = "test") ) - expect_error( plotRowTree(GlobalPatterns, tree_name = NULL) ) - expect_error( plotRowTree(GlobalPatterns, tree_name = c("test", "phylo")) ) - expect_error( plotColTree(GlobalPatterns, tree_name = 1) ) - expect_error( plotRowTree(GlobalPatterns, tree_name = TRUE) ) + # Test that error occurs if tree.name is wrong + expect_error( plotRowTree(GlobalPatterns, tree.name = "test") ) + expect_error( plotRowTree(GlobalPatterns, tree.name = NULL) ) + expect_error( plotRowTree(GlobalPatterns, tree.name = c("test", "phylo")) ) + expect_error( plotColTree(GlobalPatterns, tree.name = 1) ) + expect_error( plotRowTree(GlobalPatterns, tree.name = TRUE) ) })