Package 'wowi'

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

---

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:

• filename.txt: A plain-text summary of the results.

• filename.clustermap.html: An interactive HTML map showing detected clusters, with red bubbles for high-rate clusters and blue for low-rate clusters.

• Shapefiles: A collection of spatial files suitable for use in GIS software.

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"))

---