Tools, Classes, and Methods for Interfacing with SaTScan Stand-Alone Software

SaTScan(TM) ( http://www.satscan.org) is software for finding regions in Time, Space, or Time-Space that have excess risk, based on scan statistics, and uses Monte Carlo hypothesis testing to generate P-values for these regions. The rsatscan package provides functions for writing R data frames in SaTScan-readable formats, for setting SaTScan parameters, for running SaTScan in the OS, and for reading the files that SaTScan creates.


rsatscan is a set of tools that function as wrappers for SaTScan, a stand-alone engine for Spatial and Temporal Scan statistics. It has no functions useful outside this context. In order to use the package, you probably need a fairly sophisticated understanding of what SaTScan does.

Included functions useful for most users include

  • write.???()
  • ss.options()
  • satscan()

The write.???() functions take data from data.frame objects and write them to the OS in SaTScan-readable formats.

The ss.options() function is used to set the parameters the SaTScan engine will use. It functions similarly to options() and par() in that there is a set of default parameter settings, and the user can change any or all of them, and reset the options as needed, or recover the defaults. Key parameters include the names of the input data files and the type of analysis and model to be used.

The satscan() function calls into the operating system to run SaTScan. An object is returned with all the output files that SaTScan made. By default, this is all possible outputs, but this can be controlled by changing the default parameter settings.

Three data sets distributed with SaTScan are also included with the package. An example of using the package, replicated from the vignettes, follows. See the vignette for additional explanatory text.

Begin by resetting the paremeter file:

library("rsatscan")
invisible(ss.options(reset=TRUE))

Then, change the parameters. The parameters used in the SaTScan manual are replicated:

ss.options(list(CaseFile="NYCfever.cas", PrecisionCaseTimes=3))
ss.options(c("StartDate=2001/11/1","EndDate=2001/11/24"))
ss.options(list(CoordinatesFile="NYCfever.geo", AnalysisType=4, ModelType=2, TimeAggregationUnits=3))
ss.options(list(UseDistanceFromCenterOption="y", MaxSpatialSizeInDistanceFromCenter=3, NonCompactnessPenalty=0))
ss.options(list(MaxTemporalSizeInterpretation=1, MaxTemporalSize=7))
ss.options(list(ProspectiveStartDate="2001/11/24", ReportGiniClusters="n", LogRunToHistoryFile="n"))

Then, write the parameter file, the case file, and the geometry file to the OS. These case and geometry files are included in the package and distributed with SaTScan.

td = tempdir()
write.ss.prm(td,"NYCfever")
write.cas(NYCfevercas,td,"NYCfever")
write.geo(NYCfevergeo,td,"NYCfever")

Then run SaTScan.

NYCfever = satscan(td,"NYCfever")

The rsatscan package provides a summary method for satscan objects.

summary(NYCfever)
#> Prospective Space-Time analysis 
#> scanning for clusters with high rates 
#> using the Space-Time Permutation model. 
#>  
#> Study period.......................: 2001/11/1 to 2001/11/24 
#> Number of locations................: 192 
#> Total number of cases..............: 194 
#> _______________________________________________________________________________________________ 
#>  
#> 
#> There were 3 clusters identified.
#> There were 0 clusters with p < .05.

SaTScan is available for free from satscan.org.

News

Version 0.3.9200 (3-17-2015)

  • satscan() sslocation option now robust to path names with spaces, such as "C:/Program Files (x86)/satscan". Thanks to Richard Wen for help identifying the problem and pointing the way to a solution.
  • Minor changes to vignettes

Version 0.3.9122 (2-5-2015)

  • Changes to vignettes, following discussions with CRAN maintainers

Version 0.3.9110 (1-22-2015)

  • satscan() "cleanup" parameter (TRUE by default) removes the SaTScan output files from the OS

Version 0.3.9102 (1-21-2015)

  • satscan() robust to presence or absence of trailing "/" for parameter file and SaTScan batch file location.

Version 0.3.9000 (1-18-2015)

  • satscan() to run SaTScan
  • ss.options() to set parameters
  • write.ss.prm() to write parameter file
  • write.??? to write data for SaTScan
  • This version tested on: ** Windows 7 with SaTScan 9.2, R 3.1.2, R 3.2 (devel) ** Windows 7 with SaTScan 9.3.1, R 3.0.2, R 3.0.3 ** Ubuntu 14.04.1 with SaTScan 9.3.1, R 3.1.2

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("rsatscan")

0.3.9200 by Ken Kleinman, 4 years ago


http://www.satscan.org


Browse source code at https://github.com/cran/rsatscan


Authors: Ken Kleinman [aut, cre]


Documentation:   PDF Manual  


Task views: Handling and Analyzing Spatio-Temporal Data


GPL-3 license


Imports utils, foreign

Suggests knitr, rgdal, sp


See at CRAN