make_point_hull: Make alpha hull from points

In jmw86069/jamenrich: Analysis and Visualization of Multiple Gene Set Enrichments

Make alpha hull from points

Description

Make alpha hull from points

Usage

make_point_hull(
  x,
  expand = 0.1,
  buffer = NULL,
  alpha = NULL,
  seed = 123,
  col = "#FF000033",
  border = "#FF0000FF",
  lwd = 2,
  lty = 1,
  max_iterations = 100,
  do_plot = FALSE,
  add = FALSE,
  hull_method = c("default", "alphahull", "igraph", "sf", "chull"),
  smooth = TRUE,
  shape = 1/2,
  label = NULL,
  label.cex = 1,
  label.x.nudge = 0,
  label.y.nudge = 0,
  label_preset = NULL,
  label_adj_preset = label_preset,
  verbose = FALSE,
  ...
)

Arguments

x	numeric matrix with 2 columns that contains the coordinate of each point.
expand	numeric value indicating the buffer width around each point, scaled based upon the total range of coordinates, used only when buffer is not supplied.
buffer	numeric value indicating the absolute buffer width around each point. This value is used if provided, otherwise expand is used to derive a value for buffer.
alpha	numeric value passed to alphahull::ashape() when hull_method is "alphahull". This value determines the level of detail of the resulting hull.
seed	numeric seed used with set.seed() to define reproducible behavior.
lwd, lty	line width and line type parameters, respectively.
max_iterations	integer number of attempts to call alphahull::ashape() with varying values of alpha. Each iteration checks to confirm the resulting polygon includes all input points.
do_plot	logical indicating whether to plot the polygon output.
add	logical used when do_plot=TRUE to indicate whether the hull should be drawn onto an existing plot device, or whether to open a new plot prior to drawing the hull.
hull_method	character string indicating the hull method to use: "default" - will use "alphahull" if the alphahull R package is available. "alphahull" - use alphahull::ashape() which is the preferred method, in fact the only available option that will allow a concave shape in the output. "igraph" - calls hidden function igraph:::convex_hull() as used when drawing mark.groups around grouped nodes. "sf" - calls sf::st_convex_hull(), with same effective output as "igraph". "chull" - calls grDevices::chull(), again with same effective output as "igraph", but with benefit of not incurring additional R package dependencies.
smooth	logical indicating whether to smooth the final polygon using graphics::xspline().
label_preset	character (default NULL) indicating the side to place a label, when label is provided. Recognized values: ⁠"bottom", "top", "left", "right"⁠. When NULL it detects the offset from the plot center.
label_adj_preset	character (default label_preset) indicating the label adjustment relative to the position of the label. In most cases it should equal label_preset.
verbose	logical indicating whether to print verbose output.
...	additional arguments are ignored.
color, border	character colors used when do_plot=TRUE to draw the resulting hull polygon.

Details

This function makes an alpha hull around points, calling alphahull::ashape() then piecing together the somewhat random set of outer edges into a coherent polygon.

Value

numeric matrix with polygon coordinates, where each polygon is separated by one row that contains NA values. This output is sufficient for vectorized plotting in base R graphics using graphics::polygon().

See Also

Other jam utility functions: avg_angles(), avg_colors_by_list(), call_fn_ellipsis_deprecated(), cell_fun_bivariate(), collapse_mem_clusters(), colorRamp2D(), deconcat_df2(), display_colorRamp2D(), enrichList2geneHitList(), filter_mem_genes(), filter_mem_sets(), find_colname(), get_hull_data(), get_igraph_layout(), gsubs_remove(), handle_igraph_param_list(), isColorBlank(), make_legend_bivariate(), mem_find_overlap(), order_colors(), rank_mem_clusters(), rotate_coordinates(), subgraph_jam(), subset_mem(), summarize_node_spacing(), xyAngle()

Examples

set.seed(12)
n <- 22
xy <- cbind(x=sample(seq_len(n), size=n, replace=TRUE),
   y=sample(seq_len(n), size=n, replace=TRUE));
xy <- rbind(xy, xy[1,,drop=FALSE])
x4 <- sf::st_multipoint(xy)

if (jamba::check_pkg_installed("alphahull")) {
   plot(x4, col="red", pch=20, cex=3,
      main="hull_method='alphahull'")
   phxy <- make_point_hull(x=xy, expand=0.05, do_plot=TRUE,
      hull_method="alphahull",
      label="alphahull",
      add=TRUE, xpd=TRUE)
}

plot(x4, col="red", pch=20, cex=3,
   main="hull_method='chull'")
phxy2 <- make_point_hull(x=xy, expand=0.05, do_plot=TRUE,
   add=TRUE, verbose=TRUE, xpd=TRUE, hull_method="chull")

plot(x4, col="red", pch=20, cex=3,
   main="hull_method='igraph'")
phxy2 <- make_point_hull(x=xy, expand=0.05, do_plot=TRUE,
   add=TRUE, verbose=TRUE, xpd=TRUE, hull_method="igraph")

plot(x4, col="red", pch=20, cex=3,
   main="hull_method='sf'")
phxy2 <- make_point_hull(x=xy, expand=0.05, do_plot=TRUE,
   add=TRUE, verbose=TRUE, xpd=TRUE, hull_method="sf")

jmw86069/jamenrich documentation built on Nov. 6, 2024, 7:07 p.m.