Move functions around

DESCRIPTION

@@ -76,20 +76,18 @@ Collate:
     'aux_output.R'
     'aux_save.R'
     'aux_visuals.R'
+    'package_imports.R'
+    'colorRamp2.R'
     'color_palettes.R'
     'dd.R'
     'gg_info_layers.R'
     'globals.R'
-    'package_imports.R'
     'plot_dendrogram.R'
     'plot_heatmap.R'
     'plot_scatter.R'
     'plot_violin.R'
     'spatialDE_visuals.R'
-    'vis_hvf.R'
-    'vis_pc.R'
     'vis_spatial.R'
     'vis_spatial_in_situ.R'
-    'vis_spatial_interaction.R'
     'viz_spatial_network.R'
     'zzz.R'

NAMESPACE

@@ -1,19 +1,9 @@
 # Generated by roxygen2: do not edit by hand
 
 export(FSV_show)
-export(cellProximityBarplot)
-export(cellProximityHeatmap)
-export(cellProximityNetwork)
-export(cellProximitySpatPlot)
-export(cellProximitySpatPlot2D)
-export(cellProximitySpatPlot3D)
-export(cellProximityVisPlot)
-export(create_calc_var_HVF_plot)
+export(addGiottoImageToSpatPlot)
+export(colorRamp2)
 export(create_cluster_dendrogram)
-export(create_cov_group_HVF_plot)
-export(create_cov_loess_HVF_plot)
-export(create_jackstrawplot)
-export(create_screeplot)
 export(dimCellPlot)
 export(dimCellPlot2D)
 export(dimFeatPlot2D)
@@ -24,25 +14,15 @@ export(dimPlot3D)
 export(expand_feature_info)
 export(getColors)
 export(getDistinctColors)
+export(get_continuous_colors)
 export(gg_simple_scatter)
-export(plotCCcomDotplot)
-export(plotCCcomHeatmap)
-export(plotCPF)
-export(plotCellProximityFeats)
-export(plotCombineCCcom)
-export(plotCombineCellCellCommunication)
-export(plotCombineICF)
-export(plotCombineInteractionChangedFeats)
+export(pal_names)
 export(plotHeatmap)
-export(plotICF)
-export(plotInteractionChangedFeats)
 export(plotMetaDataCellsHeatmap)
 export(plotMetaDataHeatmap)
 export(plotPCA)
 export(plotPCA_2D)
 export(plotPCA_3D)
-export(plotRankSpatvsExpr)
-export(plotRecovery)
 export(plotStatDelaunayNetwork)
 export(plotTSNE)
 export(plotTSNE_2D)
@@ -51,10 +31,23 @@ export(plotUMAP)
 export(plotUMAP_2D)
 export(plotUMAP_3D)
 export(plot_output_handler)
+export(set_default_color_continuous)
+export(set_default_color_continuous_CCcom_dotplot)
+export(set_default_color_continuous_CCcom_heatmap)
+export(set_default_color_continuous_cell)
+export(set_default_color_continuous_heatmap)
+export(set_default_color_continuous_poly)
+export(set_default_color_discrete)
+export(set_default_color_discrete_cell)
+export(set_default_color_discrete_feat)
+export(set_default_color_discrete_heatmap_clus)
+export(set_default_color_discrete_poly)
+export(set_default_cow_n_col)
 export(showClusterDendrogram)
 export(showClusterHeatmap)
 export(showColorInstructions)
 export(showSaveParameters)
+export(simple_palette_factory)
 export(spatCellPlot)
 export(spatCellPlot2D)
 export(spatDeconvPlot)
@@ -83,6 +76,7 @@ import(GiottoUtils)
 import(ggplot2)
 import(utils)
 importClassesFrom(data.table,data.table)
+importFrom(colorRamp2,colorRamp2)
 importFrom(data.table,dcast)
 importFrom(data.table,dcast.data.table)
 importFrom(methods,slot)

R/aux_defaults.R

@@ -4,8 +4,13 @@
 # default plot n cols ####
 #' @title Set default ncols in plotting grid
 #' @name set_default_cow_n_col
-#' @keywords internal
-#' @noRd
+#' @description
+#' Determine a default cow_n_col param value for cowplot based on the number of
+#' items to plot.
+#' @param cow_n_col number of columns for cowplot to use. A default number is
+#' calculated if `NULL` is passed.
+#' @param nr_plots number of plots to use with cowplot
+#' @export
 set_default_cow_n_col = function(cow_n_col = NULL,
                                  nr_plots) {
 
@@ -20,17 +25,59 @@ set_default_cow_n_col = function(cow_n_col = NULL,
 
 # default plotting fill color ####
 
+
+
+
+
+
+
+
+## discrete ####
+
+
 # -------------------------------------------------------------------------- #
-# internal function to provide a function that will generate 'n' hexadecimal
-# color codes for discrete colors
-# inputs are INTENDED to be provided via instructions and options
-#
 # FUNCTION input to 'color' are also permitted, but REQUIRE an 'n' param
 # for downstream functionality. 'giotto.color_discrete_pal' and
 # 'giotto.color_discrete_strategy' are additionally ignored
 # -------------------------------------------------------------------------- #
 
-# framework function. Wrap this for specific things that need defaults setting
+#' @name set_default_color_discrete
+#' @title Set a discrete coloring scheme
+#' @description
+#' Provides a palette function that will generate 'n' hexadecimal color codes for
+#' discrete colors. Sets a default coloring palette if `NULL` is passed to `colors`
+#' param.\cr\cr
+#'
+#' Supports colors setting at three levels:
+#'  - **global options** (general session setting with blanket color palette type effects)
+#'    - options('giotto.color_d_pal) - palette to use
+#'    - options('giotto.color_d_rev) - whether colors should be reversed
+#'    - options('giotto.color_d_strategy) - strategy to use when making colors continuous. See [get_continuous_colors()]
+#'  - **giotto instructions** (gobject specific and effects specific types of plots)
+#'    - run `showColorInstructions()` for details on options/params to set in the `giottoInstructions` object
+#'  - **function specific** (directly pass desired colors to plotting function)
+#' \cr\cr
+#'
+#' If a character vector of length 1 input is provided then it will be assumed
+#' that a known color palette is being requested from [pal_names()].\cr
+#' If a longer character input is provided then they will be expected to be
+#' a vector of colors to use. These values will be passed to [simple_palette_factory]
+#' which will generate a palette function that interpolates between the colors
+#' provided by default and has a `n` param for number of requested colors.\cr
+#' Custom function inputs to `colors` is also supported but these custom functions
+#' should have a `n` param for number of requested colors.
+#' @param colors accepts color inputs
+#' @param instrs `giottoInstructions` object (output of `instructions(gobject)`)
+#' @param \dots additional params to pass
+NULL
+
+
+
+
+#' @describeIn set_default_color_discrete Framework function. Direct use should be minimal.
+#' Wrap this for specific things (plots or types of features) that need defaults setting.
+#' @param instr_pal,instr_rev,instr_strategy used by upstream function to pass specific `giottoInstructions` params
+#' @export
 set_default_color_discrete = function(
     colors = NULL,
     instr_pal,
@@ -67,6 +114,9 @@ set_default_color_discrete = function(
   }
 }
 
+
+#' @rdname set_default_color_discrete
+#' @export
 set_default_color_discrete_cell = function(
     colors = NULL,
     instrs,
@@ -87,6 +137,8 @@ set_default_color_discrete_cell = function(
   )
 }
 
+#' @rdname set_default_color_discrete
+#' @export
 set_default_color_discrete_poly = function(
     colors = NULL,
     instrs,
@@ -107,6 +159,8 @@ set_default_color_discrete_poly = function(
   )
 }
 
+#' @rdname set_default_color_discrete
+#' @export
 set_default_color_discrete_feat = function(
     colors = NULL,
     instrs,
@@ -127,6 +181,8 @@ set_default_color_discrete_feat = function(
   )
 }
 
+#' @rdname set_default_color_discrete
+#' @export
 set_default_color_discrete_heatmap_clus = function(
     colors = NULL,
     instrs,
@@ -155,25 +211,47 @@ set_default_color_discrete_heatmap_clus = function(
 
 
 
+
+## continuous ####
+
+
 #' @name set_default_color_continuous
 #' @title Set a default color for continuous values
 #' @description
-#' Framework function. Should not be used directly. Specific wrapper functions
-#' should be used for each item that needs defaults setting.
-#' midpoint param only supplied when using color scale with 3 colors.\cr
-#' This function sets a default color continuous color gradient to use. It takes
+#' Generates a gradient color palette based on input to `colors` param. Sets a
+#' default gradient if `NULL` is passed.
+#' `midpoint` param only supplied when using color scale with 3 colors.\cr\cr
+#'
+#' Supports colors setting at four levels:
+#' - **type specific defaults** - defaults for a sepecific feature or type of
+#' plot can be passed through `type_default` param
+#' - **global options** (general session setting with blanket color palette type effects)
+#'    - options('giotto.color_c_pal) - palette to use. Default for 'divergent'
+#' data is blue, white, red, for sequential, it is 'viridis'
+#'    - options('giotto.color_c_rev) - whether colors should be reversed
+#' - **giotto instructions** (gobject specific and effects specific types of plots)
+#'    - run `showColorInstructions()` for details on options/params to set in the `giottoInstructions` object
+#' - **function specific** (directly pass desired colors to plotting function)
+#' \cr\cr
 #'
-#' @param colors character or NULL. 2 to n number of hex color codes or 1 single
+#' @param colors character or `NULL`. 2 to n number of hex color codes or 1 single
 #' name of a palette to use can be passed
-#' @param instr_pal instructions default: palette
-#' @param instr_rev instructions default: reverse palette
-#' @param midpoint midpoint value of color gradient
-#' @param style scale color scale around midpoint (divergent) or starting from
+#' @param instrs `giottoInstructions` object (output of `instructions(gobject)`)
+#' @param midpoint numeric. midpoint value of color gradient
+#' @param style scale color scale around `midpoint` (divergent) or starting from
 #' minimum value (sequential)
-#' @param type_default data type specific defaults
+#' @param type_default data type specific default to use
 #' @param type whether setting is for ggplot2 'fill' or 'color' type function
 #' @param \dots additional params to pass to respective ggplot fill_gradient functions
-#' @keywords internal
+NULL
+
+
+
+#' @describeIn set_default_color_continuous Framework function. Direct use should
+#' be minimal. Specific wrapper functions should be used for each item that needs
+#' defaults setting (plots or types of features).
+#' @param instr_pal,instr_rev used by upstream function to pass specific `giottoInstructions` params
+#' @export
 set_default_color_continuous <- function(
     colors = NULL, # used for function inputs
     instr_pal,
@@ -317,7 +395,8 @@ evaluate_color_gradient_sequential = function(colors,
 }
 
 
-
+#' @rdname set_default_color_continuous
+#' @export
 set_default_color_continuous_cell <- function(
     colors = NULL,
     instrs,
@@ -342,6 +421,8 @@ set_default_color_continuous_cell <- function(
   )
 }
 
+#' @rdname set_default_color_continuous
+#' @export
 set_default_color_continuous_poly <- function(
     colors = NULL,
     instrs,
@@ -365,7 +446,8 @@ set_default_color_continuous_poly <- function(
 }
 
 
-
+#' @rdname set_default_color_continuous
+#' @export
 set_default_color_continuous_heatmap = function(
     colors = NULL,
     instrs,
@@ -388,6 +470,8 @@ set_default_color_continuous_heatmap = function(
   )
 }
 
+#' @rdname set_default_color_continuous
+#' @export
 set_default_color_continuous_CCcom_heatmap = function(
     colors = NULL,
     instrs,
@@ -413,6 +497,8 @@ set_default_color_continuous_CCcom_heatmap = function(
   )
 }
 
+#' @rdname set_default_color_continuous
+#' @export
 set_default_color_continuous_CCcom_dotplot = function(
     colors = NULL,
     instrs,

R/colorRamp2.R

@@ -0,0 +1,6 @@
+#' @include package_imports.R
+
+# nocov start
+#' @export
+colorRamp2::colorRamp2
+# nocov end

R/color_palettes.R

@@ -310,11 +310,22 @@ get_rcarto_colors = function(n, pal, strategy) {
 
 # helpers ####
 
-#' @noRd
-#' @param col character vector. colors to interpolate
+#' @name get_continuous_colors
+#' @title Generate a continuous set of colors
+#' @description
+#' Based on a vector of colors provided to `col`, make these colors continuous
+#' (i.e. make it possible for an arbitrary `n` number of colors to be requested)
+#' then return those `n` colors.\cr
+#' `strategy` describes how to make these colors continuous:
+#' - **'interpolate'** interpolates provided colors using [grDevices::colorRampPalette()]
+#' - **'recycle'** - recycles the input color vector across the `n` requested.
+#' - **'cutoff'** - supply only a maximum of as many colors as exist within the
+#' originally supplied vector.
+#' @param col character vector. colors to make continuous
 #' @param n integer. number of colors to get
 #' @param strategy one of 'cutoff', 'recycle', or 'interpolate'.
 #' strategy to use when more colors are requested than exist
+#' @export
 get_continuous_colors = function(col, n, strategy) {
   strategy = g_match_arg(strategy, choices = c('interpolate', 'recycle', 'cutoff'))
 
@@ -326,16 +337,19 @@ get_continuous_colors = function(col, n, strategy) {
 }
 
 
-#' @noRd
-#' @param col character vector. Hexadecimal color codes
-#' @param rev whether to reverse order of vector
-#' @param strategy policy when insufficient colors are available
+
+#' @name simple_palette_factory
+#' @title Generate a simple palette function
 #' @seealso [set_default_color_discrete()]
 #' @description
 #' Simple palette function generator. Creates a function with param n that
 #' dictates how many colors to return from the provided vector of hexadecimal
 #' color values. Generated functions send warning if there are not enough colors
 #' to use and it needs to recycle values.
+#' @param col character vector. Hexadecimal color codes
+#' @param rev whether to reverse order of vector
+#' @param strategy policy when insufficient colors are available
+#' @export
 simple_palette_factory = function(col, rev = FALSE, strategy = 'interpolate') {
   checkmate::assert_character(col)
   checkmate::assert_logical(rev)
@@ -364,6 +378,14 @@ get_palette_factory = function(pal, rev = FALSE, strategy = 'interpolate') {
 
 # * palette names list ####
 
+#' @title Color palette names
+#' @name pal_names
+#' @description
+#' Known color palettes info provided as named list of character vectors.
+#' List names correspond to the name of the palette package. The character vectors
+#' list the palettes that are available within. These palettes can be passed to
+#' the default color setting functions
+#' @export
 pal_names = list(
   hcl = grDevices::hcl.pals(),
   base = c(