Dissolve groups in a SPATA2 object

This function dissolves specified groups in a SPATA2 object by merging them into the closest neighboring groups based on the pairwise distances between observations.

dissolveGroups(object, grouping, groups_dissolve, grouping_new = NULL)

Arguments

object

An object of class SPATA2 or, in case of S4 generics, objects of classes for which a method has been defined.

grouping

Character value. The grouping variable of interest. Use getGroupingOptions() to obtain all valid input options.

groups_dissolve

A character vector specifying the names of the groups to be dissolved.

grouping_new

A character string specifying the name for the new grouping variable. If NULL, the original grouping variable will be updated. Default is NULL!

Value

The updated input object, containing the added, removed or computed results.

Details

This function performs the following steps:

  1. Retrieves the metadata data frame from the SPATA2 object.

  2. Checks if the specified grouping and groups to dissolve exist in the object.

  3. Computes the pairwise distances between all observations.

  4. Identifies the closest neighboring groups for the observations in the groups to be dissolved.

  5. Updates the grouping variable with the new group assignments.

  6. If grouping_new is provided, a new grouping variable is created; otherwise, the original grouping variable is updated.

Examples


library(SPATA2)
library(ggplot2)
library(patchwork)

object <- loadExampleObject("UKF313T")

# add example grouping
# this is a random grouping variable solely created for demonstrating the
# purpose of dissolveGroups()! It is not of any analytical value!
object <- addFeatures(object, feature_df = example_data$dissolve_groups)

# note the many spots of class 'unnamed' surrounded by actual groups
plot_before <-
 plotSurface(object, color_by = "histo_bad", pt_clrp = "uc", clrp_adjust = c("unnamed" = "black"))

# show plot
plot_before

# dissolve the group "unnamed"
object <-
 dissolveGroups(
   object = object,
   grouping = "histo_bad",
    groups_dissolve = "unnamed",
    grouping_new = "histo_better"
    )

# spots of group 'unnamed' have been dissolved into their respective neighbor group
# use alpha (transparency) to highlight spots that used to of group "unnamed"
plot_afterwards <-
 plotSurface(object, color_by = "histo_better", pt_clrp = "uc", alpha_by = "histo_alpha") +
 scale_alpha_identity()

# show plots
plot_before + plot_afterwards