Package {multiflexscan}

Type: Package
Title: Information Criterion and Scan Statistic Approach for Detecting Multiple Disease Clusters
Version: 0.1.0
Author: Takahiro Otani ORCID iD [aut, cre], Kunihiko Takahashi [aut]
Maintainer: Takahiro Otani <t.otani@aichi-cc.jp>
Description: Detecting multiple disease clusters using the information criterion and scan statistic approach developed by Takahashi and Shimadzu (2020) <doi:10.1186/s12942-020-00228-y>.
License: GPL-3
URL: https://github.com/tkhrotn/multiflexscan
BugReports: https://github.com/tkhrotn/multiflexscan/issues
Depends: R (≥ 4.0.0)
Imports: doSNOW, foreach, igraph, parallel, rflexscan (≥ 1.2.0), utils
Suggests: sf, spdep
Encoding: UTF-8
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-07-17 01:30:29 UTC; otani
Repository: CRAN
Date/Publication: 2026-07-24 10:00:08 UTC

Detecting multiple spatial disease clusters using the information criterion and scan statistic approach

Description

This package provides functions for detecting multiple spatial disease clusters based on the information criterion and scan statistic approach by Takahashi and Shimadzu (2020), using the flexible spatial scan statistic (Tango and Takahashi, 2005) or Kulldorff's circular spatial scan statistic (1997) implemented in the rflexscan package (Otani and Takahashi, 2021).

Author(s)

Maintainer: Takahiro Otani t.otani@aichi-cc.jp (ORCID)

Authors:

References

See Also

Useful links:

Draw a choropleth map of multiflexscan clusters

Description

Draw a choropleth map that highlights clusters selected by the information criterion. The order of regions must match the input order used in multiflexscan().

Usage

choropleth(
  x,
  regions,
  selected = seq_len(x$nclust),
  col = grDevices::palette(),
  background = "grey95",
  border = "grey80",
  border.lwd = 0.25,
  ...
)

Arguments

x

A multiflexscan object.

regions

An sf object containing the region geometries.

selected

Integer vector specifying the clusters to highlight. By default, the clusters selected by the information criterion are highlighted.

col

Colors used for highlighted clusters.

background

Fill color for regions not in selected clusters.

border

Border color passed to the geometry plot.

border.lwd

Line width for polygon borders. A value smaller than the graphics default is used by default to reduce overlap in dense maps.

...

Additional arguments passed to the geometry plot.

Value

The regions object with an added cluster column (integer cluster membership, 0 for unclustered regions), invisibly.

Note

Requires the suggested sf package.

See Also

multiflexscan, plot.multiflexscan

Detect multiple spatial clusters using the flexible/circular scan statistic

Description

This function analyzes spatial count data using the flexible spatial scan statistic developed by Tango and Takahashi (2005) or Kulldorff's circular spatial scan statistic (1997), and detects multiple disease clusters by selecting the number of clusters with an information criterion.

Usage

multiflexscan(
  x,
  y,
  name,
  observed,
  expected,
  nb,
  clustertype = "HOT",
  clustersize = 15,
  clusterradius = .Machine$double.xmax,
  maxclusters = 10,
  stattype = "ORIGINAL",
  scanmethod = "FLEXIBLE",
  ralpha = 0.2,
  simcount = 999,
  verbose = FALSE,
  cores = max(1, parallel::detectCores() - 1),
  parallel_type = "PSOCK"
)

Arguments

x

A vector of X-coordinates.

y

A vector of Y-coordinates.

name

A vector of names of each area.

observed

A vector with the observed number of disease cases.

expected

A vector with the expected number of disease cases under the null hypothesis. This is used with the Poisson model.

nb

A neighbours list or an adjacency matrix. When a list is supplied, element nb[[i]] gives the indices of regions adjacent to region i. When a matrix is supplied, non-zero entries indicate adjacency (the diagonal is ignored in the stored result).

clustertype

Type of cluster to be scanned.

"HOT"

Hot-spot clusters with elevated risk.

"COLD"

Cold-spot clusters with reduced risk.

"BOTH"

Hot- and cold-spot clusters simultaneously.

clustersize

Maximum spatial cluster size S, i.e., the maximum number of regions included in a detected cluster.

clusterradius

Upper bound on the spatial radius of candidate scanning windows, in the same units as x and y. The default .Machine$double.xmax imposes no radius limit. Choose a value consistent with the projected coordinate system used for x and y.

maxclusters

The maximum number of clusters to be detected.

stattype

Statistic type to be used (case-insensitive).

"ORIGINAL"

the likelihood ratio statistic by Kulldorff and Nagarwalla (1995)

"RESTRICTED"

the restricted likelihood ratio statistic by Tango (2008), with a preset parameter ralpha for restriction

scanmethod

Scanning method to be used (case-insensitive).

"FLEXIBLE"

flexible scan statistic by Tango and Takahashi (2005)

"CIRCULAR"

circular scan statistic by Kulldorff (1997)

ralpha

Threshold parameter of the mid-p-value for the restricted likelihood ratio statistic.

simcount

The number of Monte Carlo replications to calculate a p-value for statistical test.

verbose

Print progress messages.

cores

The number of CPU cores used for Monte Carlo replications.

parallel_type

Type of parallel backend passed to parallel::makeCluster() when distributing Monte Carlo replications across worker processes (default "PSOCK").

Details

Centroid coordinates for each region should be specified by Cartesian coordinates using arguments x and y. We recommend transforming latitude and longitude onto an appropriate projected coordinate system before calling this function.

The function first obtains non-overlapping candidate clusters by calling rflexscan::runFleXScan(), then fits a sequence of Poisson generalized linear models with cluster indicators and the expected counts as offsets. The selected number of clusters is the value that maximizes the relative difference criterion (RDC). The global p-value is calculated by Monte Carlo simulation under the null hypothesis of no clustering.

The relative difference criterion for a model with K clusters is

\mathrm{RDC}_K = \frac{C_0 - C_K}{C_0},

where C_K is the information criterion of Takahashi and Shimadzu (2020). The selected number of clusters nclust is the value of K that maximizes RDC.

Monte Carlo p-values follow the rank-based convention used in rflexscan:

p = \frac{\mathrm{rank}}{M + 1},

where M is simcount. The overall p-value P compares the maximum RDC from the observed data with maxima from datasets simulated under the null Poisson model. Cluster-level p-values pval compare each candidate cluster's scan statistic stats with statistics from the simulated datasets.

Value

A list of class "multiflexscan" with the following components:

call

The matched call.

input

A list with coordinates (centroid matrix), case (data frame of observed and expected counts), and adj_mat (binary adjacency matrix with zero diagonal).

cluster

A list of candidate clusters returned by rflexscan::runFleXScan(), each extended with Monte Carlo rank and pval. Each element contains area (integer indices into the input regions), name, max_dist, n_case, expected, RR, stats, pval, and rank.

RDC

Numeric vector of relative difference criterion values for K = 0, 1, \ldots clusters.

neg2logLik, AIC, BIC, C

Numeric vectors of model-selection criteria for K = 0, 1, \ldots clusters.

nclust

Selected number of clusters (index K with maximum RDC).

P

Monte Carlo p-value for the overall clustering test.

rank

Rank of the observed maximum RDC among simulated maxima.

null_dist

Numeric vector of maximum RDC values from Monte Carlo replications.

setting

A list recording analysis settings such as simcount, maxclusters, clustersize, clusterradius, stattype, scanmethod, and clustertype.

References

Tango T. and Takahashi K. (2005). A flexibly shaped spatial scan statistic for detecting clusters, International Journal of Health Geographics 4:11.

Kulldorff M. and Nagarwalla N. (1995). Spatial disease clusters: Detection and Inference. Statistics in Medicine 14:799-810.

Kulldorff M. (1997). A spatial scan statistic. Communications in Statistics: Theory and Methods, 26:1481-1496.

Tango T. (2008). A spatial scan statistic with a restricted likelihood ratio. Japanese Journal of Biometrics 29(2):75-95.

Takahashi K. and Shimadzu H. (2020). Detecting multiple spatial disease clusters: information criterion and scan statistic approach. International Journal of Health Geographics 19:33. doi:10.1186/s12942-020-00228-y

Otani T. and Takahashi K. (2021). Flexible scan statistics for detecting spatial disease clusters: The rflexscan R package. Journal of Statistical Software 99:13. doi:10.18637/jss.v099.i13

See Also

rflexscan::rflexscan, summary.multiflexscan, plot.multiflexscan, choropleth

Examples

if (requireNamespace("spdep", quietly = TRUE)) {
  # load sample data (North Carolina SIDS data)
  library(spdep)
  data("nc.sids")

  # calculate the expected numbers of cases
  expected <- nc.sids$BIR74 * sum(nc.sids$SID74) / sum(nc.sids$BIR74)

  # small settings are used here to keep the example fast; increase
  # 'simcount', 'clustersize', and 'maxclusters' for practical analyses
  fit <- multiflexscan(
    x = nc.sids$x, y = nc.sids$y,
    observed = nc.sids$SID74,
    expected = expected,
    name = rownames(nc.sids),
    nb = ncCR85.nb,
    clustersize = 5,
    maxclusters = 3,
    simcount = 99,
    cores = 1
  )
  print(fit)
  summary(fit)
  plot(fit)
}

Plot method for the multiflexscan object. The neighborhood graph is drawn with igraph, following plot.rflexscan().

Description

Plot method for the multiflexscan object. The neighborhood graph is drawn with igraph, following plot.rflexscan().

Usage

## S3 method for class 'multiflexscan'
plot(
  x,
  rank = 1:x$nclust,
  pval = 1,
  vertexsize = max(x$input$coordinates[, 1]) - min(x$input$coordinates[, 1]),
  xlab = colnames(x$input$coordinates)[1],
  ylab = colnames(x$input$coordinates)[2],
  xlim = c(min(x$input$coordinates[, 1]), max(x$input$coordinates[, 1])),
  ylim = c(min(x$input$coordinates[, 2]), max(x$input$coordinates[, 2])),
  col = palette(),
  frame_color = "gray40",
  vertex_color = "white",
  ...
)

Arguments

x

A multiflexscan object.

rank

Integer vector specifying the clusters to highlight.

pval

Maximum cluster-level p-value for a candidate cluster to be highlighted.

vertexsize

Size of region centroids in the igraph plot.

xlab

Label of the x-axis.

ylab

Label of the y-axis.

xlim

Limits of the x-axis.

ylim

Limits of the y-axis.

col

Colors used for highlighted clusters.

frame_color

Color used for neighborhood edges and vertex frames not highlighted as clusters.

vertex_color

Color used for region centroids that are not highlighted as clusters.

...

Additional arguments passed to igraph::plot.igraph().

Value

The input object, invisibly.

See Also

multiflexscan, choropleth, rflexscan::plot.rflexscan

Print multiflexscan object

Description

Print method for multiflexscan objects.

Usage

## S3 method for class 'multiflexscan'
print(x, ...)

Arguments

x

A multiflexscan object to be printed.

...

Ignored.

Value

The input object, invisibly.

See Also

multiflexscan, summary.multiflexscan

Print summary of multiflexscan results

Description

Print summary of multiflexscan results to the terminal.

Usage

## S3 method for class 'summary.multiflexscan'
print(x, ...)

Arguments

x

A summary.multiflexscan object to be printed.

...

Ignored.

Value

The input object, invisibly.

See Also

multiflexscan, summary.multiflexscan

Summarizing multiflexscan results

Description

Summary method for multiflexscan objects.

Usage

## S3 method for class 'multiflexscan'
summary(object, ...)

Arguments

object

A multiflexscan object to be summarized.

...

Ignored.

Value

A list of class "summary.multiflexscan" with components call, total_areas, total_cases, cluster (data frame of per-cluster statistics), RDC, nclust, P, and setting.

See Also

multiflexscan, print.summary.multiflexscan