Package {wowi}

Title: Detect Spatial Clusters of High Rates of Acute Malnutrition
Version: 1.0.3
Description: Utilities for detecting statistically significant spatial clusters of high acute malnutrition rates using a Bernoulli spatial scan statistic, implemented via the 'SaTScan' software https://www.satscan.org/.
License: GPL (≥ 3)
Encoding: UTF-8
LazyData: true
Language: en-GB
URL: https://github.com/tiwowi/wowi, https://tiwowi.github.io/wowi/
BugReports: https://github.com/tiwowi/wowi/issues
Imports: dplyr (≥ 1.1.4), rlang (≥ 1.1.6), rsatscan (≥ 1.0.9), mwana (≥ 0.2.5), withr (≥ 3.0.2), stringr (≥ 1.5.1), tibble (≥ 3.3.0), shiny (≥ 1.11.1), shinycssloaders (≥ 1.1.0), bslib (≥ 0.9.0), openxlsx (≥ 4.2.8.1), DT (≥ 0.34.0), htmltools (≥ 0.5.8.1)
Suggests: covr (≥ 3.6.4), knitr (≥ 1.50), rmarkdown (≥ 2.30), quarto (≥ 1.4.4), shinytest2 (≥ 0.4.1), spelling (≥ 2.3.1), testthat (≥ 3.0.0)
Config/testthat/edition: 3
Depends: R (≥ 4.1.0)
VignetteBuilder: quarto
BuildVignettes: true
Config/roxygen2/version: 8.1.0
NeedsCompilation: no
Packaged: 2026-09-17 14:51:42 UTC; tomaszaba
Author: Tomás Zaba ORCID iD [aut, cre, cph]
Maintainer: Tomás Zaba <tomas.zaba@outlook.com>
Repository: CRAN
Date/Publication: 2026-09-28 08:10:02 UTC

wowi: Detect Spatial Clusters of High Rates of Acute Malnutrition

Description

logo

Utilities for detecting statistically significant spatial clusters of high acute malnutrition rates using a Bernoulli spatial scan statistic, implemented via the 'SaTScan' software https://www.satscan.org/.

Author(s)

Maintainer: Tomás Zaba tomas.zaba@outlook.com (ORCID) [copyright holder]

Authors:

See Also

Useful links:

Sample data set of district-level SMART surveys with geographical coordinates

Description

anthro is a SMART survey-generated data conducted in nine districts in Uganda.

Usage

anthro

Format

A tibble of 2,934 rows and 17 columns.

Variable Description
district Location in which the survey was undertaken
cluster Primary sampling unit
sex Sex; "1" = boys, "2" = girls
age Calculated age in months with two decimal places
weight Weight in kilograms
height Height in centimetres
oedema Oedema; "n" = no oedema, "y" = with oedema
muac Mid upper-arm circumference in millimetres
y Geographical coordinates: Latitude
x Geographical coordinates: Longitude
precision Estimated spatial accuracy of the recorded GPS coordinates, in meters.

Source

anonymous

Examples

anthro

Helper function to locate app directory

Description

Helper function to locate app directory

Usage

get_app_dir(package = "wowi")

Run Scan

Description

Run Scan

Usage

mod_call_satscan(
  .data,
  filename,
  directory,
  sslocation,
  ssbatchfilename,
  satscan_version,
  scan_for,
  latitude,
  longitude,
  gam_based,
  area,
  vals,
  output
)

Display input variables dynamically, according to UI for screening

Description

Display input variables dynamically, according to UI for screening

Usage

mod_display_input_variables(
  .data,
  analysis_scope = c("single", "multiple"),
  ns
)

Module server for data upload

Description

Module server for data upload

Usage

module_server_run_spatial_scan(id, .data)

Arguments

id

Module ID

Module server for data upload

Description

Module server for data upload

Usage

module_server_upload(id)

Arguments

id

Module ID

Module server for data upload

Description

Module server for data upload

Usage

module_server_wrangle_data(id, data)

Arguments

id

Module ID

Module UI for data upload

Description

Module UI for data upload

Usage

module_ui_run_spatial_scan(id)

Arguments

id

Module ID

Module UI for data upload

Description

Module UI for data upload

Usage

module_ui_upload(id)

Arguments

id

Module ID

Module UI for data upload

Description

Module UI for data upload

Usage

module_ui_wrangle_data(id)

Arguments

id

Module ID

Extract results from SaTScan-text-based output

Description

Extract results from SaTScan-text-based output

Usage

parse_clusters(file)

Arguments

file

SaTScan-text-based output result given as "main" to be parsed

Configure SaTScan for Bernoulli purely spatial scan

Description

Define the analysis parameters required by SaTScan's GUI to conduct a Bernoulli-based purely spatial scan to detect either clusters of high rates of acute malnutrition or both high and low rates.

User input is limited to specifying the analysis area filename, the destination directory for the parameters file, the SaTScan version in use, and the type of clusters to be detected. All other parameters are pre-defined by this function.

Usage

ww_configure_satscan(
  filename = character(),
  params_dir = character(),
  satscan_version = character(),
  .scan_for = c("high-rates", "high-low-rates")
)

Arguments

filename

A quoted string identifying the analysis area.

params_dir

A quoted string of the folder or directory in which the parameters file (produced by this function) should be saved. This can be the same directory as that specified in ww_wrangle_data().

satscan_version

A quoted string indicating the version of SaTScan installed on the user's computer. Internally, this value is checked against the latest available version. If it is older, a warning is issued with a link to SaTScan’s website. Although the analysis is not interrupted, it is recommended to use the latest version.

.scan_for

A quoted string indicating the type of clusters to scan for. To scan for clusters of high rates only, set .scan_for = "high-rates". To scan for both high and low rates, set .scan_for = "high-low-rates".

Details

For more information on Bernoulli purely spatial scans, refer to the SaTScan technical documentation available at: https://www.satscan.org/techdoc.html.

Value

A SaTScan parameters file with the extension .prm.

References

Kulldorff, M. (2022) SaTScan user guide for version 10.1. Available at: https://www.satscan.org/.

Examples

## Given a temporary directory ----
tmp <- withr::local_tempdir()
directory <- file.path(tmp, "input-files")

## Wrangle data with `{mwana}` ----
x <- anthro |>
  dplyr::rename(longitude = y, latitude = x) |>
  mwana::mw_wrangle_wfhz(
    sex = sex,
    .recode_sex = TRUE,
    weight = weight,
    height = height
  ) |>
  mwana::define_wasting(
    zscores = wfhz,
    .by = "zscores",
    oedema = oedema
  )

## Apply the function ----
ww_wrangle_data(
  .data = x,
  filename = "Locality",
  dir = directory,
  .gam_based = "wfhz",
  latitude = latitude,
  longitude = longitude
)

library(rsatscan) # important to make `{wowi}` access `{rsatscan}`-specific eviroment

#### Configure SaTScan ----
do.call(
  what = ww_configure_satscan,
  args = list(
    filename = "Locality",
    params_dir = directory,
    satscan_version = "10.3.2",
    .scan_for = "high-low-rates"
  )
)

## Show file's content ----
file.show(file.path(tmp, "input-files/Locality.prm"))

Initialise built-in Shiny application

Description

Initialise built-in Shiny application

Usage

ww_run_app(package = "wowi")

Arguments

package

package name ("wowi").

Value

Called for its side effect of launching the wowi Shiny application in the user's default web browser. Returns NULL invisibly when the app session ends.

Examples

if(interactive()) ww_run_app()

Run SaTScan for Bernoulli purely spatial scan to detect statistically significant clusters of acute malnutrition

Description

Detect statistically significant spatial clusters of acute malnutrition rates, including high-only or high-and-low clusters. ww_run_satscan() is a wrapper function that interacts with the SaTScan GUI via the {rsatscan} package. It internally calls both ww_wrangle_data() and ww_configure_satscan(), allowing users to skip these two steps in the workflow and instead call ww_run_satscan() directly.

Usage

ww_run_satscan(
  .data,
  filename = NULL,
  dir = character(),
  params_dir = dir,
  sslocation = character(),
  ssbatchfilename = character(),
  satscan_version,
  .by_area = FALSE,
  .scan_for = c("high-rates", "high-low-rates"),
  .gam_based = c("wfhz", "muac", "combined"),
  latitude,
  longitude,
  area = NULL,
  cleanup = TRUE,
  verbose = FALSE
)

Arguments

.data

A data frame object that has been wrangled using ⁠mwana::mw_wrangle_*()⁠ functions.

filename

Optional. Used only in single-area analysis. Used to identify the analysis area. The string should be quoted.

dir

A quoted string of the folder or directory in which the files should be saved.

params_dir

A quoted string of the folder or directory in which the parameters file (produced by this function) should be saved. Defaults to the same value as dir.

sslocation

A quoted string indicating the path to the SaTScan GUI installation. This varies depending on the operating system (OS). For macOS, it is typically "/Applications/SaTScan.app/Contents/app"; for Windows, "C:/Program Files/SaTScan".

ssbatchfilename

A quoted string specifying the SaTScan batch file name. For macOS, use "satscan"; for Windows, use "SaTScanBatch64".

satscan_version

A quoted string indicating the version of SaTScan installed on the user's computer. See ww_configure_satscan() for details.

.by_area

Logical. If TRUE, area-wise scan is done. Defaults to FALSE.

.scan_for

A quoted string indicating the type of clusters to scan for. To scan for clusters of high rates only, set .scan_for = "high-rates". To scan for both high and low rates, set .scan_for = "high-low-rates".

.gam_based

A quoted string indicating the criterion used to define acute malnutrition. This is used to identify the right vector where flagged values are identified, and for which should be excluded from the analysis. Defaults to wfhz.

latitude

Geographical coordinates. An unquoted string for the variable containing the x-axis, also known as latitude (east-west direction). The variable must be named "latitude".

longitude

Geographical coordinates. An unquoted string for the variable containing the y-axis, also know as longitude (north-south direction). The variable must be named "longitude".

area

An unquoted string for the variable containing the analysis areas for iteration.

cleanup

Logical. If TRUE, deletes all SaTScan output files from the directory after the function runs.

verbose

Logical. If TRUE, displays the SaTScan results in the R console as if run in batch mode. This is especially useful if the scan takes a long time.

Details

The geographical coordinates must be provided as latitude and longitude values. If the input data uses different variable names, they must be renamed accordingly; otherwise, the analysis will be aborted. Latitude corresponds to the X-axis (east-west direction), and longitude the to X-axis (north-south direction).

Value

A set of SaTScan output files, saved in the specified directory. The full file names depend on the filename argument:

Examples


## Wrangle data with `{mwana}` ----
x <- anthro |>
  dplyr::rename(longitude = y, latitude = x) |>
  mwana::mw_wrangle_wfhz(
    sex = sex,
    .recode_sex = TRUE,
    weight = weight,
    height = height
  ) |>
  mwana::define_wasting(
    zscores = wfhz,
    .by = "zscores",
    oedema = oedema
  )

#' ## Given a temporary directory ----
tmp <- withr::local_tempdir()
directory <- file.path(tmp, "input-files")

## Run satscan ----
library(rsatscan) # important to make `{wowi}` access `{rsatscan}`-specific eviroment

if (file.exists("/Applications/SaTScan.app/Contents/app/satscan")) {
  results <- ww_run_satscan(
    .data = x,
    filename = "Locality",
    dir = directory,
    sslocation = "/Applications/SaTScan.app/Contents/app",
    ssbatchfilename = "satscan",
    satscan_version = "10.3.2",
    .scan_for = "high-low-rates",
    .gam_based = "wfhz",
    latitude = latitude,
    longitude = longitude,
    .by_area = FALSE,
    area = NULL,
    verbose = FALSE,
    cleanup = FALSE
  )
}

Prepare SaTScan-required input data files for Bernoulli spatial scan analysis and save them in a user-defined working directory

Description

SaTScan's Bernoulli-based spatial scan requires the input data to be split into cases, controls, and geographical coordinates files, then saved in a format readable by the software, and placed in a directory it can access.

ww_wrangle_data() is a convenient function designed for this task. It assumes that the input anthropometric data has been pre-processed using {mwana} data wrangling functions.

Usage

ww_wrangle_data(
  .data,
  latitude,
  longitude,
  filename = character(),
  dir = character(),
  .gam_based = c("wfhz", "muac", "combined")
)

Arguments

.data

A data frame object that has been wrangled using ⁠mwana::mw_wrangle_*()⁠ functions.

latitude

Geographical coordinates. An unquoted string for the variable containing the Y-axis, also known as latitude (north-south direction). The variable must be named "latitude".

longitude

Geographical coordinates. An unquoted string for the variable containing the X-axis, also know as longitude (east-west direction). The variable must be named "latitude".

filename

A quoted string identifying the analysis area.

dir

A quoted string of the folder or directory in which the files should be saved.

.gam_based

A quoted string indicating the criterion used to define acute malnutrition. This is used to identify the right vector where flagged values are identified, and for which should be excluded from the analysis. Defaults to wfhz.

Value

Three files are created and saved in the user-defined directory as specified in the dir argument: a .cas file for cases, a .ctl for controls, and a .geo file for geographical coordinates. The full filenames will incorporate the use-defined filename string.

The .cas and .ctl files will each have two columns: the first containing survey cluster or enumeration area IDs, and the second containing only 1s, representing either cases or controls, respectively. The length of the .cas file depends on the number of positive acute malnutrition cases (gam == 1), and the .ctl file on the number of negative cases (gam == 0).

The .geo file will have three columns: cluster or enumeration area IDs, latitude, and longitude.

Examples


## Given a temporary directory ----
tmp <- withr::local_tempdir()
directory <- file.path(tmp, "input-files")

## Wrangle data with `{mwana}` ----
x <- anthro |>
  dplyr::rename(longitude = y, latitude = x) |>
  mwana::mw_wrangle_wfhz(
    sex = sex,
    .recode_sex = TRUE,
    weight = weight,
    height = height
  ) |>
  mwana::define_wasting(
    zscores = wfhz,
    .by = "zscores",
    oedema = oedema
  )

## Apply the function ----
ww_wrangle_data(
  .data = x,
  filename = "Locality",
  dir = directory,
  .gam_based = "wfhz",
  latitude = latitude,
  longitude = longitude
)

## Show created files ----
list.files(file.path(tmp, "input-files"))

## Display each files' content ----
file.show(file.path(tmp, "input-files/Locality.cas"))
file.show(file.path(tmp, "input-files/Locality.ctl"))
file.show(file.path(tmp, "input-files/Locality.geo"))