find_clusters: Find clusters

In gsClusterDetect: Utilities for Geo-Spatial Cluster Detection and Significance Classification

Find clusters

Description

Function will return clusters, given a frame of case counts by location and date, a distance matrix, a spline lookup table, and other parameters

Usage

find_clusters(
  cases,
  distance_matrix,
  detect_date,
  spline_lookup = NULL,
  baseline_length = 90,
  max_test_window_days = 7,
  guard_band = 0,
  distance_limit = 15,
  baseline_adjustment = c("add_one", "add_one_global", "add_test", "none"),
  adj_constant = 1,
  min_clust_cases = 0,
  max_clust_cases = Inf,
  use_fast = TRUE,
  return_interim = FALSE
)

Arguments

cases	a frame of case counts by location and date
distance_matrix	a square distance matrix, named on both dimensions or a list of distance vectors, one for each location
detect_date	a date that indicates the end of the test window in which we are looking for clusters
spline_lookup	default NULL; either a spline lookup table, which is a data frame that has at least two columns: including "observed" and "spl_thresh", OR a string indicating to use one of the built in lookup tables: i.e. one of "001", "005", "01", "05". If NULL, the default table will be 01 (i.e. spline_01 dataset)
baseline_length	integer (default = 90) number of days in the baseline interval
max_test_window_days	integer (default = 7) number of days for the test window
guard_band	integer (default = 0) buffer days between baseline and test interval
distance_limit	numeric (default=15) maximum distance to consider cluster size. Note that the units of the value default (miles) should be the same unit as the values in the distance matrix
baseline_adjustment	one of four string options: "add_one" (default), "add_one_global", "add_test", or "none". All methods except for "none" will ensure that the log(obs/expected) is always defined (i.e. avoids expected =0). For the default, this will add 1 to the expected for any individual calculation if expected would otherwise be zero. "add_one_global", will add one to all baseline location case counts. For "add_test_interval", each location in the baseline is increased by the number of cases in that location during the test interval. If "none", no adjustment is made.
adj_constant	numeric (default=1.0); this is the constant to be added if baseline_adjustment == 'add_one' or baseline_adjustment == 'add_one'
min_clust_cases	(default = 0); minimum number of case within a returned cluster.
max_clust_cases	(default = Inf); maximum number of cases within a returned cluster.
use_fast	boolean (default = TRUE) - set to TRUE to use the fast version of the compress clusters function
return_interim	boolean (default = FALSE) - set to TRUE to return all interim objects of the find_clusters() function

Value

returns a list of two of two dataframes.

Examples

find_clusters(
  cases = example_count_data,
  distance_matrix = county_distance_matrix("OH")[["distance_matrix"]],
  detect_date = example_count_data[, max(date)],
  distance_limit = 50
)

gsClusterDetect documentation built on July 27, 2026, 5:09 p.m.