Creates Hull plots to visualize clusters and groups in scatter plots using ggforce. Hull plots draw polygonal boundaries around data points grouped by categorical variables, making it easy to identify customer segments, group membership, and data clusters. Based on the geom_mark_hull() function from ggforce package.
Usage
hullplot(
data,
x_var = NULL,
y_var = NULL,
group_var = NULL,
color_var = NULL,
size_var = NULL,
hull_concavity = 2,
hull_alpha = 0.3,
show_labels = TRUE,
point_size = 2,
point_alpha = 0.7,
color_palette = "default",
plot_theme = "minimal",
plot_title = "Hull Plot - Group Visualization",
x_label = "",
y_label = "",
hull_expand = 0.05,
show_statistics = FALSE,
outlier_detection = FALSE,
confidence_ellipses = FALSE,
show_summary = FALSE,
show_assumptions = FALSE
)Arguments
- data
The data as a data frame.
- x_var
Continuous variable for the X-axis of the scatter plot.
- y_var
Continuous variable for the Y-axis of the scatter plot.
- group_var
Categorical variable that defines the groups for hull boundaries. Each group will have its own hull polygon.
- color_var
Optional variable for coloring points. If not specified, uses the grouping variable.
- size_var
Optional continuous variable for sizing points based on values.
- hull_concavity
Controls the concavity of hull polygons. Lower values follow the point cloud more closely; higher values approach the convex hull. The permitted range is 0-2 and the default of 2 matches ggforce; a true convex hull needs a much larger value than this range allows. Ignored when V8/concaveman are unavailable.
- hull_alpha
Transparency level for hull polygons. 0 = completely transparent, 1 = opaque.
- show_labels
If TRUE, displays group labels inside hull regions.
- point_size
Size of scatter plot points. Ignored when a Size Variable is selected, because point size is then mapped to that variable's values.
- point_alpha
Transparency level for scatter plot points.
- color_palette
Color palette for hulls and points.
- plot_theme
Overall visual theme for the plot.
- plot_title
Custom title for the hull plot.
- x_label
Custom label for X-axis. If empty, uses variable name.
- y_label
Custom label for Y-axis. If empty, uses variable name.
- hull_expand
Padding added around each hull, as a fraction of the plot area (0 = hull touches the outermost points, 1 = the whole panel). Ignored when V8/concaveman are unavailable and convex hulls are drawn.
- show_statistics
If TRUE, displays summary statistics for each group in the output.
- outlier_detection
If TRUE, reports the number of potential outliers in each group using the 1.5 x IQR rule applied separately to the X and Y variables. Groups with fewer than 5 observations are reported as too small rather than given a count. Outliers are counted, not marked on the plot.
- confidence_ellipses
If TRUE, adds confidence ellipses in addition to hull polygons.
- show_summary
If TRUE, displays a plain-language summary of the results with copy-ready text.
- show_assumptions
If TRUE, displays data requirements, assumptions, and usage guidelines.