add more roxygen to the functions

Author: rcannood

DESCRIPTION

@@ -82,3 +82,4 @@ Collate:
     'plot_strip.R'
     'plot_topology.R'
     'theme_clean.R'
+Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -1,6 +1,5 @@
 # Generated by roxygen2: do not edit by hand
 
-export(add_milestone_coloring)
 export(empty_plot)
 export(get_milestone_palette_names)
 export(linearise_cells)

R/add_cell_coloring.R

@@ -1,16 +1,44 @@
 #' Add colouring to a set of cells.
 #'
+#' The cells can be coloured by a grouping (clustering), according to a feature
+#'   (gene expression), closest milestone, or pseudotime from the root of the trajectory.
+#'
 #' @param cell_positions The positions of the cells, represented by a tibble.
 #'   Must contain column `cell_id` (character) and may contain columns `from`,
 #'   `to`, `pseudotime`, depending on the value of `color_cells`.
-#' @param color_cells How to color the cells
-#' @param trajectory The trajectory
-#' @param grouping The grouping of the cells
-#' @param groups Tibble containing information of the cell groups
-#' @param feature_oi feature to plot expression
-#' @param expression_source Source of the feature expression, defaults to `expression`
-#' @param pseudotime The pseudotime
-#' @param milestone_percentages The milestone percentages
+#' @param color_cells How to color the cells.
+#'   * `"auto"`: Try to figure out how to color cells depending on whether
+#'     one of the `grouping`, `feature_io`, `milestones` or `pseudotime` parameters are defined.
+#'   * `"none"`: Cells are not coloured.
+#'   * `"grouping"`: Cells are coloured according to a grouping (e.g. clustering).
+#'     Either the `grouping` parameter or `trajectory$grouping` must be a named character vector.
+#'   * `"feature"`: Cells are coloured according to the values of a given feature (e.g. gene expression).
+#'     Either the `expression_source` parameter or `get_expression(trajectory)` must be a matrix.
+#'     Parameter `feature_oi` must also be defined.
+#'   * `"milestone"` (recommended): Cells are coloured according their position in the trajectory. The positioning of the
+#'     cells are determined by parameter `milestone_percentages` or else by `trajectory$milestone_percentages`. The colours
+#'     of the milestones can be determined automatically or can be specified by passing a tibble containing character columns
+#'     `milestone_id` and `color` (See `add_milestone_coloring()` for help in constructing this object).
+#'   * `"pseudotime"`: Cells are coloured according to the pseudotime value from the root.
+#'
+#' @param trajectory A dynwrap trajectory.
+#' @param grouping A grouping of the cells (e.g. clustering) as a named character vector.
+#' @param groups A tibble containing character columns `group_id` and `color`. If `NULL`, this object is inferred from the `grouping` itself.
+#' @param feature_oi The name of a feature to use for colouring the cells.
+#' @param expression_source Source of the feature expression, defaults to `get_expression(trajectory)`.
+#' @param pseudotime The pseudotime from the root of the trajectory to the cells as a named numeric vector.
+#' @param milestone_percentages The milestone percentages.
+#'
+#' @returns
+#' A named list with following objects:
+#'  * cell_positions: The `trajectory$progressions` object with a `color` column added.
+#'  * color_scale: A ggplot colour scale to add to the downstream ggplot.
+#'  * fill_scale: A ggplot fill scale to add to the downstream ggplot.
+#'  * color_cells: The input `color_cells` value, except `"auto"` will have been replaced depending
+#'    on which other parameters were passed.
+#'
+# @examples
+# add_cell_coloring(example_bifurcating$progressions)
 #'
 #' @inheritParams add_milestone_coloring
 #'

R/add_density_coloring.R

@@ -1,13 +1,22 @@
 #' Color cells using a background density
 #'
-#' @param cell_positions The positions of the cells in 2D
-#' @param color_density How to color density, can be "none", "grouping", or "feature"
-#' @param padding The padding in the edges to the plot, relative to the size of the plot
-#' @param nbins Number of bins for calculating the density
-#' @param bw Bandwidth, relative to the size of the plot
-#' @param density_cutoff Cutoff for density, the lower the larger the areas
-#' @param density_cutoff_label Cutoff for density for labelling, the lower the further way from cells
+#' @param cell_positions The positions of the cells in 2D. Must be a tibble with character column `cell_id` and numeric columns `comp_1` and `comp_2`.
+#' @param color_density How to color density, can be "none", "grouping", or "feature".
+#' @param padding The padding in the edges to the plot, relative to the size of the plot.
+#' @param nbins Number of bins for calculating the density.
+#' @param bw Bandwidth, relative to the size of the plot.
+#' @param density_cutoff Cutoff for density, the lower the larger the areas.
+#' @param density_cutoff_label Cutoff for density for labeling, the lower the further way from cells.
 #' @inheritParams add_cell_coloring
+#'
+#' @returns A named list with objects:
+#' * polygon: A layer to add to the ggplot.
+#' * scale: A scale to add to the ggplot.
+#'
+# @examples
+# pca <- prcomp(example_bifurcating$expression, rank. = 2)$x
+# cell_positions <- pca %>% as.matrix %>% as.data.frame %>% magrittr::set_colnames(c("comp_1", "comp_2")) %>% rownames_to_column("cell_id")
+# add_density_coloring(cell_positions, "feature", trajectory = example_bifurcating, feature_oi = "B1_TF1")
 add_density_coloring <- function(
   cell_positions,
   color_density = c("none", "grouping", "feature"),
@@ -26,7 +35,9 @@ add_density_coloring <- function(
 
   if (color_density == "none") return(list())
 
-  if (any(!c("comp_1", "comp_2", "cell_id") %in% colnames(cell_positions))) {stop("Invalid cell positions")}
+  if (any(!c("comp_1", "comp_2", "cell_id") %in% colnames(cell_positions))) {
+    stop("Invalid value for cell_positions. See documentation for more details.")
+  }
 
   xlims <- c(min(cell_positions$comp_1), max(cell_positions$comp_1))
   ylims <- c(min(cell_positions$comp_2), max(cell_positions$comp_2))

R/add_milestone_coloring.R

@@ -17,19 +17,17 @@
 #'
 #' @include milestone_palette.R
 #'
-#' @export
-#'
-#' @examples
-#' milestones <- data.frame(
-#'   milestone_id = c("A", "B", "C")
-#' )
-#' add_milestone_coloring(milestones)
-#'
-#' milestones <- data.frame(
-#'   milestone_id = c("A", "B", "C"),
-#'   color = c("#111111", "#222222", "#333333")
-#' )
-#' add_milestone_coloring(milestones)
+# @examples
+# milestones <- data.frame(
+#   milestone_id = c("A", "B", "C")
+# )
+# add_milestone_coloring(milestones)
+#
+# milestones <- data.frame(
+#   milestone_id = c("A", "B", "C"),
+#   color = c("#111111", "#222222", "#333333")
+# )
+# add_milestone_coloring(milestones)
 add_milestone_coloring <- function(
   milestones = NULL,
   color_milestones = c("auto", "given", get_milestone_palette_names())

R/milestone_palette.R

@@ -32,7 +32,7 @@ milestone_palette_list <- list(
   }
 )
 
-#' @param name The name of the palette. Must be one of \code{"cubeHelix"}, \code{"Set3"}, or \code{"rainbow"}.
+#' @param name The name of the palette. Must be one of `"cubeHelix"`, `"Set3"`, or `"rainbow"`.
 #' @param n The number of colours to be in the palette.
 #'
 #' @rdname get_milestone_palette_names

R/project_waypoints.R

@@ -1,10 +1,21 @@
 #' Project the waypoints
 #'
 #' @inheritParams add_cell_coloring
-#' @param waypoints The waypoints to use for projecting, as generated by [dynwrap::select_waypoints()]
-#' @param trajectory_projection_sd The standard deviation of the gaussian kernel
-#' @param color_trajectory How to color the trajectory, can be "nearest" for coloring to nearest cell, or "none"
-#' @param edge_positions The positions of the edges
+#' @param cell_positions The positions of the cells in 2D. Must be a tibble with character column `cell_id` and numeric columns `comp_1` and `comp_2`.
+#' @param waypoints The waypoints to use for projecting. Can by generated using [dynwrap::select_waypoints()].
+#' @param trajectory_projection_sd The standard deviation of the gaussian kernel.
+#' @param color_trajectory How to color the trajectory, can be "nearest" for coloring to nearest cell, or "none".
+#' @param edge_positions The positions of the edges.
+#'
+#' @returns
+#' A named list containing items:
+#' * segments: A tibble containing columns `comp_1` (numeric), `comp_2` (numeric), `waypoint_id` (character), `milestone_id` (character), `from` (character), `to` (character)
+#'   `percentage` (numeric), `group` (factor), and `arrow` (logical).
+#'
+# @examples
+# pca <- prcomp(example_bifurcating$expression, rank. = 2)$x
+# cell_positions <- pca %>% as.matrix %>% as.data.frame %>% magrittr::set_colnames(c("comp_1", "comp_2")) %>% rownames_to_column("cell_id")
+# project_waypoints_coloured(example_bifurcating, cell_positions)
 project_waypoints_coloured <- function(
   trajectory,
   cell_positions,