Skip to contents

Make alpha hull from points

Source: R/jam-points-to-ahull.R
make_point_hull.Rd

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", "ahull", "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 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 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 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.

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().

Details

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

See also

Other jam utility functions: ashape(), avg_angles(), avg_colors_by_list(), bulk_cnet_adjustments(), call_fn_ellipsis_deprecated(), cell_fun_bivariate(), collapse_mem_clusters(), colorRamp2D(), deconcat_df2(), display_colorRamp2D(), enrichList2geneHitList(), filter_mem_genes(), filter_mem_sets(), find_colname(), find_enrich_colnames(), 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)

plot(x4, col="red", pch=20, cex=3,
   main="hull_method='ahull'")
phxy <- make_point_hull(x=xy, expand=0.05, do_plot=TRUE,
   hull_method="ahull",
   label="ahull",
   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")

#> ##  (13:44:58) 17Oct2025:   make_point_hull(): label.y.nudge:0 
#> ##  (13:44:58) 17Oct2025:   make_point_hull(): calculated alpha: 10 
#> ##  (13:44:58) 17Oct2025:   make_point_hull(): Iterating alpha values up to 100 times. 
#> ##  (13:44:58) 17Oct2025:   make_point_hull(): Iterated 1 times, 126 mxys points.