├── .gitignore ├── data ├── NMcas.rda ├── NMgeo.rda ├── NMpop.rda ├── NYCfevercas.rda ├── NYCfevergeo.rda ├── NHumbersidecas.rda ├── NHumbersidectl.rda └── NHumbersidegeo.rda ├── R ├── stringfunctions.R ├── methods.R ├── rsatscan.R ├── DataDoc.R ├── readfiles.R ├── satscan.R ├── params.R ├── write.R └── zzz.R ├── NAMESPACE ├── rsatscan.Rproj ├── .gitattributes ├── man ├── charlistopts.Rd ├── NHumbersidecas.Rd ├── NHumbersidectl.Rd ├── NYCfevergeo.Rd ├── NMpop.Rd ├── NHumbersidegeo.Rd ├── print.satscan.Rd ├── NMgeo.Rd ├── NMcas.Rd ├── NYCfevercas.Rd ├── summary.satscan.Rd ├── read.rr.Rd ├── read.col.Rd ├── read.gis.Rd ├── read.llr.Rd ├── read.sci.Rd ├── read.satscanmain.Rd ├── subin.Rd ├── write.adj.Rd ├── write.max.Rd ├── write.met.Rd ├── write.cas.Rd ├── write.grd.Rd ├── write.ctl.Rd ├── write.geo.Rd ├── write.nbr.Rd ├── write.pop.Rd ├── write.ha.Rd ├── ss.options.extra.Rd ├── write.ss.prm.Rd ├── rsatscan.Rd ├── ss.options.Rd └── satscan.Rd ├── DESCRIPTION ├── NEWS ├── README.Rmd ├── README.md └── vignettes ├── simulation.Rmd └── rsatscan.Rmd /.gitignore: -------------------------------------------------------------------------------- 1 | .Rproj.user 2 | .Rhistory 3 | .RData 4 | .Ruserdata 5 | -------------------------------------------------------------------------------- /data/NMcas.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Kenkleinman/rsatscan/HEAD/data/NMcas.rda -------------------------------------------------------------------------------- /data/NMgeo.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Kenkleinman/rsatscan/HEAD/data/NMgeo.rda -------------------------------------------------------------------------------- /data/NMpop.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Kenkleinman/rsatscan/HEAD/data/NMpop.rda -------------------------------------------------------------------------------- /data/NYCfevercas.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Kenkleinman/rsatscan/HEAD/data/NYCfevercas.rda -------------------------------------------------------------------------------- /data/NYCfevergeo.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Kenkleinman/rsatscan/HEAD/data/NYCfevergeo.rda -------------------------------------------------------------------------------- /data/NHumbersidecas.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Kenkleinman/rsatscan/HEAD/data/NHumbersidecas.rda -------------------------------------------------------------------------------- /data/NHumbersidectl.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Kenkleinman/rsatscan/HEAD/data/NHumbersidectl.rda -------------------------------------------------------------------------------- /data/NHumbersidegeo.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Kenkleinman/rsatscan/HEAD/data/NHumbersidegeo.rda -------------------------------------------------------------------------------- /R/stringfunctions.R: -------------------------------------------------------------------------------- 1 | stripslash = function (string) { 2 | laststr = tail(unlist(strsplit(string,"")),1) 3 | return( ifelse(laststr == "/", substr(string, 1, nchar(string)-1) , string)) 4 | } 5 | 6 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2 (4.1.0): do not edit by hand 2 | 3 | S3method(print,satscan) 4 | S3method(summary,satscan) 5 | export(satscan) 6 | export(ss.options) 7 | export(write.adj) 8 | export(write.cas) 9 | export(write.ctl) 10 | export(write.geo) 11 | export(write.grd) 12 | export(write.ha) 13 | export(write.max) 14 | export(write.met) 15 | export(write.nbr) 16 | export(write.pop) 17 | export(write.ss.prm) 18 | -------------------------------------------------------------------------------- /rsatscan.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: Default 4 | SaveWorkspace: Default 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: knitr 13 | LaTeX: pdfLaTeX 14 | 15 | BuildType: Package 16 | PackageUseDevtools: Yes 17 | PackageInstallArgs: --no-multiarch --with-keep.source 18 | PackageRoxygenize: rd,collate,namespace 19 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Auto detect text files and perform LF normalization 2 | * text=auto 3 | 4 | # Custom for Visual Studio 5 | *.cs diff=csharp 6 | 7 | # Standard to msysgit 8 | *.doc diff=astextplain 9 | *.DOC diff=astextplain 10 | *.docx diff=astextplain 11 | *.DOCX diff=astextplain 12 | *.dot diff=astextplain 13 | *.DOT diff=astextplain 14 | *.pdf diff=astextplain 15 | *.PDF diff=astextplain 16 | *.rtf diff=astextplain 17 | *.RTF diff=astextplain 18 | -------------------------------------------------------------------------------- /man/charlistopts.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/params.R 3 | \name{charlistopts} 4 | \alias{charlistopts} 5 | \title{Change list version of paramaters into char vector} 6 | \usage{ 7 | charlistopts(x) 8 | } 9 | \arguments{ 10 | \item{x}{A list.} 11 | } 12 | \value{ 13 | A character vector 14 | 15 | Not expected to be used directly. 16 | } 17 | \description{ 18 | Turns a list of options into a charvar of options 19 | } 20 | \details{ 21 | The resulting charvar has values such as "name=value" where "name" was the named item 22 | of the list. 23 | } 24 | 25 | -------------------------------------------------------------------------------- /man/NHumbersidecas.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/DataDoc.R 3 | \name{NHumbersidecas} 4 | \alias{NHumbersidecas} 5 | \title{North Humberside leukemian and lymphoma example-- cases} 6 | \format{A data frame with 191 observations and 2 variables} 7 | \source{ 8 | Distributed with SaTScan software: \url{http://www.satscan.org} 9 | } 10 | \description{ 11 | A data set from North Humberside. The variables are as follows: 12 | } 13 | \details{ 14 | \itemize{ 15 | \item locationid: Postal code ID 16 | \item numcases: The number of cases observed 17 | } 18 | } 19 | 20 | -------------------------------------------------------------------------------- /man/NHumbersidectl.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/DataDoc.R 3 | \name{NHumbersidectl} 4 | \alias{NHumbersidectl} 5 | \title{North Humberside leukemian and lymphoma example-- controls} 6 | \format{A data frame with 191 observations and 2 variables} 7 | \source{ 8 | Distributed with SaTScan software: \url{http://www.satscan.org} 9 | } 10 | \description{ 11 | A data set from North Humberside. The variables are as follows: 12 | } 13 | \details{ 14 | \itemize{ 15 | \item locationid: Postal code ID 16 | \item numcontrols: The number of controls observed 17 | } 18 | } 19 | 20 | -------------------------------------------------------------------------------- /man/NYCfevergeo.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/DataDoc.R 3 | \name{NYCfevergeo} 4 | \alias{NYCfevergeo} 5 | \title{New York City Fever example-- geography} 6 | \format{A data frame with 192 observations and 3 variables} 7 | \source{ 8 | Distributed with SaTScan software: \url{http://www.satscan.org} 9 | } 10 | \description{ 11 | A data set from New York City. The variables are as follows: 12 | } 13 | \details{ 14 | \itemize{ 15 | \item zip: The US Postal Service ZIP code 16 | \item lat: Decimal latitude north 17 | \item long: Decimal longitude 18 | } 19 | } 20 | 21 | -------------------------------------------------------------------------------- /man/NMpop.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/DataDoc.R 3 | \name{NMpop} 4 | \alias{NMpop} 5 | \title{New Mexico Brain Cancer example-- population} 6 | \format{A data frame with 3456 observations and 5 variables} 7 | \source{ 8 | Distributed with SaTScan software: \url{http://www.satscan.org} 9 | } 10 | \description{ 11 | A data set from New Mexico. The variables are as follows: 12 | } 13 | \details{ 14 | \itemize{ 15 | \item county: County name 16 | \item year: year 17 | \item year: population 18 | \item agegroup: Age group 19 | \item sex: Sex 20 | } 21 | } 22 | 23 | -------------------------------------------------------------------------------- /man/NHumbersidegeo.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/DataDoc.R 3 | \name{NHumbersidegeo} 4 | \alias{NHumbersidegeo} 5 | \title{North Humberside leukemian and lymphoma example-- geography} 6 | \format{A data frame with 191 observations and 3 variables} 7 | \source{ 8 | Distributed with SaTScan software: \url{http://www.satscan.org} 9 | } 10 | \description{ 11 | A data set from North Humberside. The variables are as follows: 12 | } 13 | \details{ 14 | \itemize{ 15 | \item locationid: Postal code ID 16 | \item x-coordinate: x-coordinate 17 | \item y-coordinate: y-coordinate 18 | } 19 | } 20 | 21 | -------------------------------------------------------------------------------- /man/print.satscan.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/methods.R 3 | \name{print.satscan} 4 | \alias{print.satscan} 5 | \title{Methods for satscan-class objects} 6 | \usage{ 7 | \method{print}{satscan}(x, ...) 8 | } 9 | \arguments{ 10 | \item{x}{is a satscan object} 11 | 12 | \item{...}{vestigial, for compatability with the default summary method} 13 | } 14 | \value{ 15 | x, invisibly. Side effect is to display ss$main, the SaTScan text report 16 | } 17 | \description{ 18 | These functions define the default methods for satscan-class objects, which 19 | are the result objects from a call to satscan() 20 | } 21 | 22 | -------------------------------------------------------------------------------- /man/NMgeo.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/DataDoc.R 3 | \name{NMgeo} 4 | \alias{NMgeo} 5 | \title{New Mexico Brain Cancer example-- geography} 6 | \format{A data frame with 194 observations and 3 variables} 7 | \source{ 8 | Distributed with SaTScan software: \url{http://www.satscan.org} 9 | } 10 | \description{ 11 | A data set from New Mexico. The variables are as follows: 12 | } 13 | \details{ 14 | \itemize{ 15 | \item county: The US Postal Service ZIP code 16 | \item cases: The number of cases observed 17 | \item long: The date on which the cases were observed in that ZIP code 18 | } 19 | } 20 | 21 | -------------------------------------------------------------------------------- /man/NMcas.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/DataDoc.R 3 | \name{NMcas} 4 | \alias{NMcas} 5 | \title{New Mexico Brain Cancer example-- cases} 6 | \format{A data frame with 1175 observations and 5 variables} 7 | \source{ 8 | Distributed with SaTScan software: \url{http://www.satscan.org} 9 | } 10 | \description{ 11 | A data set from New Mexico. The variables are as follows: 12 | } 13 | \details{ 14 | \itemize{ 15 | \item county: County name 16 | \item cases: Number of cases 17 | \item year: Year of case 18 | \item agegroup: Age group of case 19 | \item sex: Sex of case 20 | } 21 | } 22 | 23 | -------------------------------------------------------------------------------- /man/NYCfevercas.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/DataDoc.R 3 | \name{NYCfevercas} 4 | \alias{NYCfevercas} 5 | \title{New York City Fever example-- cases} 6 | \format{A data frame with 194 observations and 3 variables} 7 | \source{ 8 | Distributed with SaTScan software: \url{http://www.satscan.org} 9 | } 10 | \description{ 11 | A data set from New York City. The variables are as follows: 12 | } 13 | \details{ 14 | \itemize{ 15 | \item zip: The US Postal Service ZIP code 16 | \item cases: The number of cases observed 17 | \item long: The date on which the cases were observed in that ZIP code 18 | } 19 | } 20 | 21 | -------------------------------------------------------------------------------- /man/summary.satscan.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/methods.R 3 | \name{summary.satscan} 4 | \alias{summary.satscan} 5 | \title{Methods for satscan-class objects} 6 | \usage{ 7 | \method{summary}{satscan}(object, ...) 8 | } 9 | \arguments{ 10 | \item{object}{is a satscan object} 11 | 12 | \item{...}{vestigial, for compatability with the default summary method} 13 | } 14 | \value{ 15 | object, invisibly. Side effect is to display minimal facts contained in ss 16 | } 17 | \description{ 18 | These functions define the default methods for satscan-class objects, which 19 | are the result objects from a call to satscan() 20 | } 21 | 22 | -------------------------------------------------------------------------------- /man/read.rr.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/readfiles.R 3 | \name{read.rr} 4 | \alias{read.rr} 5 | \title{Read SaTScan output files} 6 | \usage{ 7 | read.rr(location, file) 8 | } 9 | \arguments{ 10 | \item{location}{A directory location, including the trailing "/"} 11 | 12 | \item{file}{A file name, without the extension.} 13 | } 14 | \value{ 15 | A data frame. 16 | } 17 | \description{ 18 | Reads a SaTScan output .dbf file. 19 | } 20 | \details{ 21 | This is expected to be a purely internal function. 22 | It's called by \code{satscan()} with the location and file nmae provided 23 | to that function. Since it's nothing more than \code{foreign::read.dbf()}, it's 24 | probably nor necessary to even have it as a function. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/read.col.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/readfiles.R 3 | \name{read.col} 4 | \alias{read.col} 5 | \title{Read SaTScan output files} 6 | \usage{ 7 | read.col(location, file) 8 | } 9 | \arguments{ 10 | \item{location}{A directory location, including the trailing "/"} 11 | 12 | \item{file}{A file name, without the extension.} 13 | } 14 | \value{ 15 | A data frame. 16 | } 17 | \description{ 18 | Reads a SaTScan output .dbf file. 19 | } 20 | \details{ 21 | This is expected to be a purely internal function. 22 | It's called by \code{satscan()} with the location and file nmae provided 23 | to that function. Since it's nothing more than \code{foreign::read.dbf()}, it's 24 | probably nor necessary to even have it as a function. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/read.gis.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/readfiles.R 3 | \name{read.gis} 4 | \alias{read.gis} 5 | \title{Read SaTScan output files} 6 | \usage{ 7 | read.gis(location, file) 8 | } 9 | \arguments{ 10 | \item{location}{A directory location, including the trailing "/"} 11 | 12 | \item{file}{A file name, without the extension.} 13 | } 14 | \value{ 15 | A data frame. 16 | } 17 | \description{ 18 | Reads a SaTScan output .dbf file. 19 | } 20 | \details{ 21 | This is expected to be a purely internal function. 22 | It's called by \code{satscan()} with the location and file nmae provided 23 | to that function. Since it's nothing more than \code{foreign::read.dbf()}, it's 24 | probably nor necessary to even have it as a function. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/read.llr.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/readfiles.R 3 | \name{read.llr} 4 | \alias{read.llr} 5 | \title{Read SaTScan output files} 6 | \usage{ 7 | read.llr(location, file) 8 | } 9 | \arguments{ 10 | \item{location}{A directory location, including the trailing "/"} 11 | 12 | \item{file}{A file name, without the extension.} 13 | } 14 | \value{ 15 | A data frame. 16 | } 17 | \description{ 18 | Reads a SaTScan output .dbf file. 19 | } 20 | \details{ 21 | This is expected to be a purely internal function. 22 | It's called by \code{satscan()} with the location and file nmae provided 23 | to that function. Since it's nothing more than \code{foreign::read.dbf()}, it's 24 | probably nor necessary to even have it as a function. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/read.sci.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/readfiles.R 3 | \name{read.sci} 4 | \alias{read.sci} 5 | \title{Read SaTScan output files} 6 | \usage{ 7 | read.sci(location, file) 8 | } 9 | \arguments{ 10 | \item{location}{A directory location, including the trailing "/"} 11 | 12 | \item{file}{A file name, without the extension.} 13 | } 14 | \value{ 15 | A data frame. 16 | } 17 | \description{ 18 | Reads a SaTScan output .dbf file. 19 | } 20 | \details{ 21 | This is expected to be a purely internal function. 22 | It's called by \code{satscan()} with the location and file nmae provided 23 | to that function. Since it's nothing more than \code{foreign::read.dbf()}, it's 24 | probably nor necessary to even have it as a function. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/read.satscanmain.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/readfiles.R 3 | \name{read.satscanmain} 4 | \alias{read.satscanmain} 5 | \title{Read SaTScan output files} 6 | \usage{ 7 | read.satscanmain(location, file) 8 | } 9 | \arguments{ 10 | \item{location}{A directory location, including the trailing "/"} 11 | 12 | \item{file}{A file name, without the extension.} 13 | } 14 | \value{ 15 | A data frame. 16 | } 17 | \description{ 18 | Reads a SaTScan output .dbf file. 19 | } 20 | \details{ 21 | This is expected to be a purely internal function. 22 | It's called by \code{satscan()} with the location and file nmae provided 23 | to that function. Since it's nothing more than \code{readLines()}, it's 24 | probably nor necessary to even have it as a function. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/subin.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/params.R 3 | \name{subin} 4 | \alias{subin} 5 | \title{Substitute new values into the input object} 6 | \usage{ 7 | subin(x, ssparams) 8 | } 9 | \arguments{ 10 | \item{x}{A character vector of the form "name=value"} 11 | 12 | \item{ssparams}{A character vector with arbitrary lines, 13 | currently imagined to be .ss.params} 14 | } 15 | \value{ 16 | The modified ssparams. 17 | } 18 | \description{ 19 | Replaces existing values found in one object with new values 20 | } 21 | \details{ 22 | For each line of x, the function: 1) finds the "name" and the "value" 23 | 2) checks to see whether the "name" exists in ssparams; if not, prints a warning 24 | but if so, replaces the existing line of ssparams with that line of x. 25 | 26 | Not expected to be used directly. 27 | } 28 | 29 | -------------------------------------------------------------------------------- /man/write.adj.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/write.R 3 | \name{write.adj} 4 | \alias{write.adj} 5 | \title{Write a SaTScan adj file} 6 | \usage{ 7 | write.adj(x, location, filename, userownames = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{Your data frame.} 11 | 12 | \item{location}{Directory location where the file should be written} 13 | 14 | \item{filename}{Name for the output file in the OS; .adj will be added.} 15 | 16 | \item{userownames}{If TRUE, will write the row names into the file.} 17 | } 18 | \description{ 19 | Write a SaTScan adj file 20 | } 21 | \details{ 22 | Writes the input data frame to the OS, using the .adj extension. Contents of the data 23 | frame should be only what you want SaTScan to see. 24 | This is a simple function that calls write.table, since SaTScan just needs ASCII files. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/write.max.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/write.R 3 | \name{write.max} 4 | \alias{write.max} 5 | \title{Write a SaTScan max file} 6 | \usage{ 7 | write.max(x, location, filename, userownames = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{Your data frame.} 11 | 12 | \item{location}{Directory location where the file should be written} 13 | 14 | \item{filename}{Name for the output file in the OS; .max will be added.} 15 | 16 | \item{userownames}{If TRUE, will write the row names into the file.} 17 | } 18 | \description{ 19 | Write a SaTScan max file 20 | } 21 | \details{ 22 | Writes the input data frame to the OS, using the .max extension. Contents of the data 23 | frame should be only what you want SaTScan to see. 24 | This is a simple function that calls write.table, since SaTScan just needs ASCII files. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/write.met.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/write.R 3 | \name{write.met} 4 | \alias{write.met} 5 | \title{Write a SaTScan met file} 6 | \usage{ 7 | write.met(x, location, filename, userownames = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{Your data frame.} 11 | 12 | \item{location}{Directory location where the file should be written} 13 | 14 | \item{filename}{Name for the output file in the OS; .met will be added.} 15 | 16 | \item{userownames}{If TRUE, will write the row names into the file.} 17 | } 18 | \description{ 19 | Write a SaTScan met file 20 | } 21 | \details{ 22 | Writes the input data frame to the OS, using the .met extension. Contents of the data 23 | frame should be only what you want SaTScan to see. 24 | This is a simple function that calls write.table, since SaTScan just needs ASCII files. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/write.cas.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/write.R 3 | \name{write.cas} 4 | \alias{write.cas} 5 | \title{Write a SaTScan cas (case) file} 6 | \usage{ 7 | write.cas(x, location, filename, userownames = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{Your data frame.} 11 | 12 | \item{location}{Directory location where the file should be written} 13 | 14 | \item{filename}{Name for the output file in the OS; .cas will be added.} 15 | 16 | \item{userownames}{If TRUE, will write the row names into the file.} 17 | } 18 | \description{ 19 | Write a SaTScan cas (case) file 20 | } 21 | \details{ 22 | Writes the input data frame to the OS, using the .cas extension. Contents of the data 23 | frame should be only what you want SaTScan to see. 24 | This is a simple function that calls write.table, since SaTScan just needs ASCII files. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/write.grd.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/write.R 3 | \name{write.grd} 4 | \alias{write.grd} 5 | \title{Write a SaTScan grd (grid) file} 6 | \usage{ 7 | write.grd(x, location, filename, userownames = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{Your data frame.} 11 | 12 | \item{location}{Directory location where the file should be written} 13 | 14 | \item{filename}{Name for the output file in the OS; .grd will be added.} 15 | 16 | \item{userownames}{If TRUE, will write the row names into the file.} 17 | } 18 | \description{ 19 | Write a SaTScan grd (grid) file 20 | } 21 | \details{ 22 | Writes the input data frame to the OS, using the .grd extension. Contents of the data 23 | frame should be only what you want SaTScan to see. 24 | This is a simple function that calls write.table, since SaTScan just needs ASCII files. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/write.ctl.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/write.R 3 | \name{write.ctl} 4 | \alias{write.ctl} 5 | \title{Write a SaTScan ctl (control) file} 6 | \usage{ 7 | write.ctl(x, location, filename, userownames = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{Your data frame.} 11 | 12 | \item{location}{Directory location where the file should be written} 13 | 14 | \item{filename}{Name for the output file in the OS; .ctl will be added.} 15 | 16 | \item{userownames}{If TRUE, will write the row names into the file.} 17 | } 18 | \description{ 19 | Write a SaTScan ctl (control) file 20 | } 21 | \details{ 22 | Writes the input data frame to the OS, using the .geo extension. Contents of the data 23 | frame should be only what you want SaTScan to see. 24 | This is a simple function that calls write.table, since SaTScan just needs ASCII files. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/write.geo.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/write.R 3 | \name{write.geo} 4 | \alias{write.geo} 5 | \title{Write a SaTScan geo file} 6 | \usage{ 7 | write.geo(x, location, filename, userownames = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{Your data frame.} 11 | 12 | \item{location}{Directory location where the file should be written} 13 | 14 | \item{filename}{Name for the output file in the OS; .geo extension will be added.} 15 | 16 | \item{userownames}{If TRUE, will write the row names into the file.} 17 | } 18 | \description{ 19 | Write a SaTScan geo file 20 | } 21 | \details{ 22 | Writes the input data frame to a file in the OS, using the .geo extension. Contents of the data 23 | frame should be only what you want SaTScan to see. 24 | This is a simple function that calls write.table, since SaTScan just needs ASCII files. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/write.nbr.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/write.R 3 | \name{write.nbr} 4 | \alias{write.nbr} 5 | \title{Write a SaTScan nbr (neighbor) file} 6 | \usage{ 7 | write.nbr(x, location, filename, userownames = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{Your data frame.} 11 | 12 | \item{location}{Directory location where the file should be written} 13 | 14 | \item{filename}{Name for the output file in the OS; .nbr will be added.} 15 | 16 | \item{userownames}{If TRUE, will write the row names into the file.} 17 | } 18 | \description{ 19 | Write a SaTScan nbr (neighbor) file 20 | } 21 | \details{ 22 | Writes the input data frame to the OS, using the .nbr extension. Contents of the data 23 | frame should be only what you want SaTScan to see. 24 | This is a simple function that calls write.table, since SaTScan just needs ASCII files. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/write.pop.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/write.R 3 | \name{write.pop} 4 | \alias{write.pop} 5 | \title{Write a SaTScan pop (population) file} 6 | \usage{ 7 | write.pop(x, location, filename, userownames = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{Your data frame.} 11 | 12 | \item{location}{Directory location where the file should be written} 13 | 14 | \item{filename}{Name for the output file in the OS; .pop will be added.} 15 | 16 | \item{userownames}{If TRUE, will write the row names into the file.} 17 | } 18 | \description{ 19 | Write a SaTScan pop (population) file 20 | } 21 | \details{ 22 | Writes the input data frame to the OS, using the .pop extension. Contents of the data 23 | frame should be only what you want SaTScan to see. 24 | This is a simple function that calls write.table, since SaTScan just needs ASCII files. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/write.ha.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/write.R 3 | \name{write.ha} 4 | \alias{write.ha} 5 | \title{Write a SaTScan ha (alternative hypothesis) file} 6 | \usage{ 7 | write.ha(x, location, filename, userownames = FALSE) 8 | } 9 | \arguments{ 10 | \item{x}{Your data frame.} 11 | 12 | \item{location}{Directory location where the file should be written} 13 | 14 | \item{filename}{Name for the output file in the OS; .ha will be added.} 15 | 16 | \item{userownames}{If TRUE, will write the row names into the file.} 17 | } 18 | \description{ 19 | Write a SaTScan ha (alternatove hypothesis) file 20 | } 21 | \details{ 22 | Writes the input data frame to the OS, using the .ha extension. Contents of the data 23 | frame should be only what you want SaTScan to see. 24 | This is a simple function that calls write.table, since SaTScan just needs ASCII files. 25 | } 26 | 27 | -------------------------------------------------------------------------------- /man/ss.options.extra.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/params.R 3 | \name{ss.options.extra} 4 | \alias{ss.options.extra} 5 | \title{Add lines to the current SaTScan parameter list} 6 | \usage{ 7 | ss.options.extra(invals = NULL) 8 | } 9 | \arguments{ 10 | \item{invals}{A character vector, which will be added to the end of the 11 | current paramter list.} 12 | } 13 | \value{ 14 | Nothing. 15 | } 16 | \description{ 17 | Allows you to add arbitrary lines to the current set 18 | of SaTScan parameters 19 | } 20 | \details{ 21 | For certain SaTScan models or inputs (multiple data sets, 22 | Polygon), 23 | SaTScan allows a variable number of parameters; these 24 | parameters are not used/allowed for other models or inputs. 25 | This function allows the user to add 26 | arbitray lines to the current list of 27 | parameters. In addition to the options mentioned, it could also be 28 | used to add comments to the parameter file. 29 | } 30 | 31 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: rsatscan 2 | Title: Tools, Classes, and Methods for Interfacing with SaTScan Stand-Alone 3 | Software 4 | Description: SaTScan(TM) (http://www.satscan.org) is software for finding regions in 5 | Time, Space, or Time-Space that have excess risk, based on scan statistics, and 6 | uses Monte Carlo hypothesis testing to generate P-values for these regions. The 7 | rsatscan package provides functions for writing R data frames in 8 | SaTScan-readable formats, for setting SaTScan parameters, for running SaTScan in 9 | the OS, and for reading the files that SaTScan creates. 10 | Version: 0.3.9200 11 | Date: 2015-03-17 12 | URL: http://www.satscan.org 13 | Authors@R: person("Ken", "Kleinman", email= "ken.kleinman@gmail.com", role=c("aut", "cre")) 14 | Maintainer: Ken Kleinman 15 | Depends: 16 | R (>= 3.0.2) 17 | Imports: 18 | utils, 19 | foreign 20 | Suggests: 21 | knitr, 22 | rgdal (>= 0.9.1), 23 | sp (>= 1.0-9) 24 | VignetteBuilder: knitr 25 | License: GPL-3 26 | LazyData: true -------------------------------------------------------------------------------- /R/methods.R: -------------------------------------------------------------------------------- 1 | #' Methods for satscan-class objects 2 | #' 3 | #' These functions define the default methods for satscan-class objects, which 4 | #' are the result objects from a call to satscan() 5 | #' 6 | #' @param x is a satscan object 7 | #' @param ... vestigial, for compatability with the default summary method 8 | #' 9 | #' @return x, invisibly. Side effect is to display ss$main, the SaTScan text report 10 | #' 11 | #' @export 12 | 13 | print.satscan = function(x, ...) { 14 | stopifnot(class(x)=="satscan") 15 | cat(x$main,fill=1) 16 | invisible(x) 17 | } 18 | 19 | 20 | #' Methods for satscan-class objects 21 | #' 22 | #' These functions define the default methods for satscan-class objects, which 23 | #' are the result objects from a call to satscan() 24 | #' 25 | #' @param object is a satscan object 26 | #' @param ... vestigial, for compatability with the default summary method 27 | #' 28 | #' @return object, invisibly. Side effect is to display minimal facts contained in ss 29 | #' 30 | #' @export 31 | 32 | 33 | summary.satscan = function(object, ...) { 34 | stopifnot(class(object)=="satscan") 35 | cat(object$main[c(9:11, 15:20,22)], fill=1) 36 | cat(paste0("There were ", dim(object$col)[1], " clusters identified."), fill=1) 37 | cat(paste0("There were ", sum(object$col$P_VALUE < .05), " clusters with p < .05.")) 38 | invisible(object) 39 | } 40 | 41 | 42 | 43 | -------------------------------------------------------------------------------- /man/write.ss.prm.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/params.R 3 | \name{write.ss.prm} 4 | \alias{write.ss.prm} 5 | \title{Write the SaTScan parameter file} 6 | \usage{ 7 | write.ss.prm(location, filename, matchout = TRUE) 8 | } 9 | \arguments{ 10 | \item{location}{A directory location, excluding the trailing "/".} 11 | 12 | \item{filename}{The name of the file to be written to the OS; 13 | The extension ".prm" will be appended.} 14 | 15 | \item{matchout}{If false, the ResultsFile parameter will not 16 | be touched; note that this will likely result in undesirable 17 | performance from calls to \code{satcan()} using the parameter file. 18 | If true, the ResultsFile is reset to share the filename given here.} 19 | } 20 | \value{ 21 | Nothing. (Invisibly.) Side effect is to write a file 22 | in the OS. 23 | } 24 | \description{ 25 | Writes the current set of SaTScan parameters to a 26 | specified location in the OS. 27 | } 28 | \details{ 29 | The current SaTScan options can be reset or modified 30 | \code{ss.options()} and/or \code{ss.options.extra()}. Once 31 | they are set as desired, they can be written to the OS 32 | using this function. 33 | } 34 | \examples{ 35 | \dontrun{ 36 | ## Would write the current ss.options() to c:/temp/NYCfever.prm 37 | write.ss.prm("c:/tmp","NYCfever") 38 | } 39 | } 40 | \seealso{ 41 | \code{\link{ss.options}}, \code{\link{ss.options.extra}} 42 | } 43 | 44 | -------------------------------------------------------------------------------- /NEWS: -------------------------------------------------------------------------------- 1 | Version 0.3.9200 (3-17-2015) 2 | ----------------------------------------------------------- 3 | 4 | * 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. 5 | * Minor changes to vignettes 6 | 7 | 8 | 9 | Version 0.3.9122 (2-5-2015) 10 | ----------------------------------------------------------- 11 | 12 | * Changes to vignettes, following discussions with CRAN maintainers 13 | 14 | 15 | Version 0.3.9110 (1-22-2015) 16 | ----------------------------------------------------------- 17 | 18 | * satscan() "cleanup" parameter (TRUE by default) removes the SaTScan output files from the OS 19 | 20 | 21 | Version 0.3.9102 (1-21-2015) 22 | ----------------------------------------------------------- 23 | 24 | * satscan() robust to presence or absence of trailing "/" for parameter file and SaTScan batch file location. 25 | 26 | 27 | 28 | Version 0.3.9000 (1-18-2015) 29 | ----------------------------------------------------------- 30 | 31 | * satscan() to run SaTScan 32 | * ss.options() to set parameters 33 | * write.ss.prm() to write parameter file 34 | * write.??? to write data for SaTScan 35 | * This version tested on: 36 | ** Windows 7 with SaTScan 9.2, R 3.1.2, R 3.2 (devel) 37 | ** Windows 7 with SaTScan 9.3.1, R 3.0.2, R 3.0.3 38 | ** Ubuntu 14.04.1 with SaTScan 9.3.1, R 3.1.2 39 | 40 | 41 | 42 | -------------------------------------------------------------------------------- /R/rsatscan.R: -------------------------------------------------------------------------------- 1 | #' R functions, a class, and methods for working with SaTScan stand-alone software. 2 | #' 3 | #' rsatscan provides a suite of functions that allows you to easily write SaTScan parameter 4 | #' files in the OS, run SaTScan in the OS, and read the output files that SaTScan generates. 5 | #' 6 | #' The parameter files are constructed in R using the \code{ss.options} function and written 7 | #' to the OS using the \code{write.ss.prm} function. SaTScan is run using the \code{satscan} 8 | #' function. The \code{satscan} function returns a \code{satscan-class} object that has a 9 | #' slot for every possible file that SaTScan makes, plus one for the parameter file you used 10 | #' to generate the output. 11 | #' 12 | #' The package also includes \code{write.???} functions which will write case, control, 13 | #' geography, population, etc., files in the format expected by SaTScan, if you happen to have 14 | #' them (or make them) in R and want to write them into the OS for SaTScan to use. 15 | #' 16 | #' There are \code{summary} and \code{print} methods for \code{satscan-class} 17 | #' objects. There are also \code{plot} methods in the \code{sp} package, which 18 | #' can be used if the \code{rgdal} package and \code{sp} packages are 19 | #' installed and SaTScan generated a shapefile. 20 | #' 21 | #' Currently the package works with SaTScan >= 9.2 and has been tested on Windows 7 and 22 | #' Ubuntu 14.04.1. Please contact the author if you find success or trouble on other OSes. 23 | #' 24 | #' @docType package 25 | #' @name rsatscan 26 | NULL -------------------------------------------------------------------------------- /man/rsatscan.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/rsatscan.R 3 | \docType{package} 4 | \name{rsatscan} 5 | \alias{rsatscan} 6 | \alias{rsatscan-package} 7 | \title{R functions, a class, and methods for working with SaTScan stand-alone software.} 8 | \description{ 9 | rsatscan provides a suite of functions that allows you to easily write SaTScan parameter 10 | files in the OS, run SaTScan in the OS, and read the output files that SaTScan generates. 11 | } 12 | \details{ 13 | The parameter files are constructed in R using the \code{ss.options} function and written 14 | to the OS using the \code{write.ss.prm} function. SaTScan is run using the \code{satscan} 15 | function. The \code{satscan} function returns a \code{satscan-class} object that has a 16 | slot for every possible file that SaTScan makes, plus one for the parameter file you used 17 | to generate the output. 18 | 19 | The package also includes \code{write.???} functions which will write case, control, 20 | geography, population, etc., files in the format expected by SaTScan, if you happen to have 21 | them (or make them) in R and want to write them into the OS for SaTScan to use. 22 | 23 | There are \code{summary} and \code{print} methods for \code{satscan-class} 24 | objects. There are also \code{plot} methods in the \code{sp} package, which 25 | can be used if the \code{rgdal} package and \code{sp} packages are 26 | installed and SaTScan generated a shapefile. 27 | 28 | Currently the package works with SaTScan >= 9.2 and has been tested on Windows 7 and 29 | Ubuntu 14.04.1. Please contact the author if you find success or trouble on other OSes. 30 | } 31 | 32 | -------------------------------------------------------------------------------- /man/ss.options.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/params.R 3 | \name{ss.options} 4 | \alias{ss.options} 5 | \title{Set or reset parameters to be used by SaTScan} 6 | \usage{ 7 | ss.options(invals = NULL, reset = FALSE) 8 | } 9 | \arguments{ 10 | \item{invals}{A list with entries of the form name=value, where value should be 11 | in quotes unless it is a number. Alternatively, may be a character vector whose 12 | entries are of the form "name=value". The "name" in either case should be a 13 | valid SaTScan parameter name; unrecognized names will generate a warning and will 14 | do nothing.} 15 | 16 | \item{reset}{If TRUE, will restore the default parameter values described in 17 | the "Details" section.} 18 | } 19 | \value{ 20 | If \code{invals == NULL}, returns the current parameter set, 21 | as altered by previous 22 | calls to \code{ss.options()} since the last call with \code{reset=TRUE}. Otherwise 23 | returns modified parameter set invisibly. The side effect, if \code{invals != NULL}, is to 24 | set the current values of the parameters per the value of \code{invals} 25 | and \code{reset}. 26 | } 27 | \description{ 28 | Set or reset parameters to be used by SaTScan 29 | } 30 | \details{ 31 | \code{ss.options()} is intended to function like \code{par()} or 32 | \code{options()}. There is a default set of parameter settings that resembles 33 | the one used by SaTScan, except that it produces all possible output files and 34 | makes them as .dbf files instead of text. 35 | } 36 | \examples{ 37 | \dontrun{ 38 | head(ss.options(),3) 39 | ss.options(list(CaseFile="NYCfever.cas")) 40 | head(ss.options(),3) 41 | 42 | # reset; shows whole parameter file without invisible() 43 | invisible(ss.options(reset=TRUE)) 44 | head(ss.options(),3) 45 | } 46 | } 47 | 48 | -------------------------------------------------------------------------------- /man/satscan.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/satscan.R 3 | \name{satscan} 4 | \alias{satscan} 5 | \title{Run SaTScan in the OS} 6 | \usage{ 7 | satscan(prmlocation, prmfilename, sslocation = "c:/progra~2/satscan", 8 | ssbatchfilename = "SaTScanBatch", cleanup = TRUE, verbose = FALSE) 9 | } 10 | \arguments{ 11 | \item{prmlocation}{A string containing the 12 | directory location where the paramter file is located.} 13 | 14 | \item{prmfilename}{A string containg the name of the parameter file, without the extension, i.e., no ".prm".} 15 | 16 | \item{sslocation}{A string containing the directory location where satscanbatch.exe (Windows) 17 | is located. The default value is a common location in Windows 7.} 18 | 19 | \item{ssbatchfilename}{Name of the file containing the SaTScan executable. This is likely to be 20 | either SaTScanBatch or SaTScanBatch64. Omit the file extension.} 21 | 22 | \item{cleanup}{If true, deletes any SaTScan output files from the OS.} 23 | 24 | \item{verbose}{If true, will display the results in the R console as if running SaTScan in batch. This may be especially 25 | useful if you expect SaTScan to take a long time to run.} 26 | } 27 | \value{ 28 | A satscan-class object, which is a list of 8 items, not all of which are always made, depending on SaTScan options and whether the program call was successful or not: 29 | \describe{ 30 | \item{main}{A character vector containing the main text output from SaTScan. This is 31 | probably identical to the material displayed when verbose=True} 32 | \item{col}{A data frame with the basic cluster information dataset SaTScan makes.} 33 | \item{rr}{A data frame with the risk ratio dataset SaTScan makes.} 34 | \item{gis}{A data frame with the geographic information dataset SaTScan makes.} 35 | \item{llr}{A data frame with the log likelihood ratios dataset SaTScan makes.} 36 | \item{sci}{A data frame with the other cluster information dataset SaTScan makes.} 37 | \item{shapeclust}{A list object, of class SpatialPolygonsDataFrame, defined by the \code{sp} 38 | package. It contains the ESRI shapefile(s) SaTScan makes. This is made only if the \code{rgdal} 39 | package is available.} 40 | \item{prm}{A character vector containing the contents of the parameter file you told SaTScan 41 | to use.} 42 | } 43 | If an item is not made by SaTScan, it will be NA. 44 | } 45 | \description{ 46 | Calls out into the OS to run SaTScan, with the parameter file specified 47 | } 48 | \details{ 49 | The parameter file may have been made by the \code{\link{ss.options}} function or not. 50 | If not, or if the \code{matchout = FALSE} parameter was set in \code{ss.options}, then the 51 | return object will include the main text output from SaTScan only you manually set the 52 | \code{ResultsFile} SaTScan parameter to have the same name as the parameter file. 53 | } 54 | \examples{ 55 | \dontrun{ 56 | ## Please see vignette("rsatscan"); example() code doesn't make sense since 57 | ## all examples rely on calls to SaTScan in the OS. 58 | } 59 | } 60 | \seealso{ 61 | \code{\link{ss.options}}, \code{\link{write.ss.prm}} 62 | } 63 | 64 | -------------------------------------------------------------------------------- /README.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | output: 3 | md_document: 4 | variant: markdown_github 5 | --- 6 | 7 | 8 | 9 | ```{r, echo = FALSE} 10 | knitr::opts_chunk$set( 11 | collapse = TRUE, 12 | comment = "#>", 13 | fig.path = "README-" 14 | ) 15 | ``` 16 | 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. 17 | 18 | Included functions useful for most users include 19 | 20 | * write.???() 21 | * ss.options() 22 | * satscan() 23 | 24 | The write.???() functions take data from data.frame objects and write them to the OS in SaTScan-readable formats. 25 | 26 | 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. 27 | 28 | 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. 29 | 30 | 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. 31 | 32 | Begin by resetting the paremeter file: 33 | ```{r} 34 | library("rsatscan") 35 | invisible(ss.options(reset=TRUE)) 36 | ``` 37 | 38 | Then, change the parameters. The parameters used in the SaTScan manual are replicated: 39 | ```{r} 40 | ss.options(list(CaseFile="NYCfever.cas", PrecisionCaseTimes=3)) 41 | ss.options(c("StartDate=2001/11/1","EndDate=2001/11/24")) 42 | ss.options(list(CoordinatesFile="NYCfever.geo", AnalysisType=4, ModelType=2, TimeAggregationUnits=3)) 43 | ss.options(list(UseDistanceFromCenterOption="y", MaxSpatialSizeInDistanceFromCenter=3, NonCompactnessPenalty=0)) 44 | ss.options(list(MaxTemporalSizeInterpretation=1, MaxTemporalSize=7)) 45 | ss.options(list(ProspectiveStartDate="2001/11/24", ReportGiniClusters="n", LogRunToHistoryFile="n")) 46 | ``` 47 | 48 | Then, write the parameter file, the case file, and the geometry file to the OS. 49 | ```{r} 50 | td = tempdir() 51 | 52 | write.ss.prm(td,"NYCfever") 53 | write.cas(NYCfevercas,td,"NYCfever") 54 | write.geo(NYCfevergeo,td,"NYCfever") 55 | ``` 56 | 57 | Then run SaTScan. 58 | ```{r} 59 | # This step omitted in compliance with CRAN policies 60 | # Please install SaTScan and run the vignette with this and following code uncommented 61 | # SaTScan can be downloaded from www.satscan.org, free of charge 62 | 63 | # NYCfever = satscan(td,"NYCfever", sslocation="C:/Program Files (x86)/SaTScan") 64 | ``` 65 | 66 | The `rsatscan` package provides a `summary` method for `satscan` objects. 67 | ```{r} 68 | # summary(NYCfever) 69 | ``` 70 | 71 | SaTScan is available for free from www.satscan.org. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | 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. 3 | 4 | Included functions useful for most users include 5 | 6 | - write.???() 7 | - ss.options() 8 | - satscan() 9 | 10 | The write.???() functions take data from data.frame objects and write them to the OS in SaTScan-readable formats. 11 | 12 | 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. 13 | 14 | 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. 15 | 16 | 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. 17 | 18 | Begin by resetting the paremeter file: 19 | 20 | ``` r 21 | library("rsatscan") 22 | #> RSaTScan only does anything useful if you have SaTScan-- see http://www.satscan.org/ for free access. 23 | invisible(ss.options(reset=TRUE)) 24 | ``` 25 | 26 | Then, change the parameters. The parameters used in the SaTScan manual are replicated: 27 | 28 | ``` r 29 | ss.options(list(CaseFile="NYCfever.cas", PrecisionCaseTimes=3)) 30 | ss.options(c("StartDate=2001/11/1","EndDate=2001/11/24")) 31 | ss.options(list(CoordinatesFile="NYCfever.geo", AnalysisType=4, ModelType=2, TimeAggregationUnits=3)) 32 | ss.options(list(UseDistanceFromCenterOption="y", MaxSpatialSizeInDistanceFromCenter=3, NonCompactnessPenalty=0)) 33 | ss.options(list(MaxTemporalSizeInterpretation=1, MaxTemporalSize=7)) 34 | ss.options(list(ProspectiveStartDate="2001/11/24", ReportGiniClusters="n", LogRunToHistoryFile="n")) 35 | ``` 36 | 37 | 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. 38 | 39 | ``` r 40 | td = tempdir() 41 | write.ss.prm(td,"NYCfever") 42 | write.cas(NYCfevercas,td,"NYCfever") 43 | write.geo(NYCfevergeo,td,"NYCfever") 44 | ``` 45 | 46 | Then run SaTScan. 47 | 48 | ``` r 49 | NYCfever = satscan(td,"NYCfever") 50 | ``` 51 | 52 | The `rsatscan` package provides a `summary` method for `satscan` objects. 53 | 54 | ``` 55 | summary(NYCfever) 56 | #> Prospective Space-Time analysis 57 | #> scanning for clusters with high rates 58 | #> using the Space-Time Permutation model. 59 | #> 60 | #> Study period.......................: 2001/11/1 to 2001/11/24 61 | #> Number of locations................: 192 62 | #> Total number of cases..............: 194 63 | #> _______________________________________________________________________________________________ 64 | #> 65 | #> 66 | #> There were 3 clusters identified. 67 | #> There were 0 clusters with p < .05. 68 | ``` 69 | 70 | SaTScan is available for free from satscan.org. 71 | -------------------------------------------------------------------------------- /R/DataDoc.R: -------------------------------------------------------------------------------- 1 | #' New York City Fever example-- geography 2 | #' 3 | #' A data set from New York City. The variables are as follows: 4 | #' 5 | #' \itemize{ 6 | #' \item zip: The US Postal Service ZIP code 7 | #' \item lat: Decimal latitude north 8 | #' \item long: Decimal longitude 9 | #' } 10 | #' 11 | #' @format A data frame with 192 observations and 3 variables 12 | #' @source Distributed with SaTScan software: \url{http://www.satscan.org} 13 | #' @name NYCfevergeo 14 | NULL 15 | 16 | #' New York City Fever example-- cases 17 | #' 18 | #' A data set from New York City. The variables are as follows: 19 | #' 20 | #' \itemize{ 21 | #' \item zip: The US Postal Service ZIP code 22 | #' \item cases: The number of cases observed 23 | #' \item long: The date on which the cases were observed in that ZIP code 24 | #' } 25 | #' 26 | #' @format A data frame with 194 observations and 3 variables 27 | #' @source Distributed with SaTScan software: \url{http://www.satscan.org} 28 | #' @name NYCfevercas 29 | NULL 30 | 31 | #' New Mexico Brain Cancer example-- cases 32 | #' 33 | #' A data set from New Mexico. The variables are as follows: 34 | #' 35 | #' \itemize{ 36 | #' \item county: County name 37 | #' \item cases: Number of cases 38 | #' \item year: Year of case 39 | #' \item agegroup: Age group of case 40 | #' \item sex: Sex of case 41 | #' } 42 | #' 43 | #' @format A data frame with 1175 observations and 5 variables 44 | #' @source Distributed with SaTScan software: \url{http://www.satscan.org} 45 | #' @name NMcas 46 | NULL 47 | 48 | #' New Mexico Brain Cancer example-- population 49 | #' 50 | #' A data set from New Mexico. The variables are as follows: 51 | #' 52 | #' \itemize{ 53 | #' \item county: County name 54 | #' \item year: year 55 | #' \item year: population 56 | #' \item agegroup: Age group 57 | #' \item sex: Sex 58 | #' } 59 | #' 60 | #' @format A data frame with 3456 observations and 5 variables 61 | #' @source Distributed with SaTScan software: \url{http://www.satscan.org} 62 | #' @name NMpop 63 | NULL 64 | 65 | #' New Mexico Brain Cancer example-- geography 66 | #' 67 | #' A data set from New Mexico. The variables are as follows: 68 | #' 69 | #' \itemize{ 70 | #' \item county: The US Postal Service ZIP code 71 | #' \item cases: The number of cases observed 72 | #' \item long: The date on which the cases were observed in that ZIP code 73 | #' } 74 | #' 75 | #' @format A data frame with 194 observations and 3 variables 76 | #' @source Distributed with SaTScan software: \url{http://www.satscan.org} 77 | #' @name NMgeo 78 | NULL 79 | 80 | #' North Humberside leukemian and lymphoma example-- geography 81 | #' 82 | #' A data set from North Humberside. The variables are as follows: 83 | #' 84 | #' \itemize{ 85 | #' \item locationid: Postal code ID 86 | #' \item x-coordinate: x-coordinate 87 | #' \item y-coordinate: y-coordinate 88 | #' } 89 | #' 90 | #' @format A data frame with 191 observations and 3 variables 91 | #' @source Distributed with SaTScan software: \url{http://www.satscan.org} 92 | #' @name NHumbersidegeo 93 | NULL 94 | 95 | #' North Humberside leukemian and lymphoma example-- cases 96 | #' 97 | #' A data set from North Humberside. The variables are as follows: 98 | #' 99 | #' \itemize{ 100 | #' \item locationid: Postal code ID 101 | ##' \item numcases: The number of cases observed 102 | #' } 103 | #' 104 | #' @format A data frame with 191 observations and 2 variables 105 | #' @source Distributed with SaTScan software: \url{http://www.satscan.org} 106 | #' @name NHumbersidecas 107 | NULL 108 | 109 | 110 | #' North Humberside leukemian and lymphoma example-- controls 111 | #' 112 | #' A data set from North Humberside. The variables are as follows: 113 | #' 114 | #' \itemize{ 115 | #' \item locationid: Postal code ID 116 | ##' \item numcontrols: The number of controls observed 117 | #' } 118 | #' 119 | #' @format A data frame with 191 observations and 2 variables 120 | #' @source Distributed with SaTScan software: \url{http://www.satscan.org} 121 | #' @name NHumbersidectl 122 | NULL 123 | -------------------------------------------------------------------------------- /R/readfiles.R: -------------------------------------------------------------------------------- 1 | require(foreign) 2 | #' @title Read SaTScan output files 3 | #' 4 | #' @description 5 | #' Reads a SaTScan output .dbf file. 6 | #' 7 | #' @details 8 | #' This is expected to be a purely internal function. 9 | #' It's called by \code{satscan()} with the location and file nmae provided 10 | #' to that function. Since it's nothing more than \code{foreign::read.dbf()}, it's 11 | #' probably nor necessary to even have it as a function. 12 | #' 13 | #' @param location A directory location, including the trailing "/" 14 | #' @param file A file name, without the extension. 15 | #' 16 | #' @return A data frame. 17 | read.col = function(location,file) foreign::read.dbf(paste0(location,file,".col.dbf")) 18 | 19 | 20 | #' @title Read SaTScan output files 21 | #' 22 | #' @description 23 | #' Reads a SaTScan output .dbf file. 24 | #' 25 | #' @details 26 | #' This is expected to be a purely internal function. 27 | #' It's called by \code{satscan()} with the location and file nmae provided 28 | #' to that function. Since it's nothing more than \code{foreign::read.dbf()}, it's 29 | #' probably nor necessary to even have it as a function. 30 | #' 31 | #' @param location A directory location, including the trailing "/" 32 | #' @param file A file name, without the extension. 33 | #' 34 | #' @return A data frame. 35 | read.rr = function(location,file) foreign::read.dbf(paste0(location,file,".rr.dbf")) 36 | 37 | #' @title Read SaTScan output files 38 | #' 39 | #' @description 40 | #' Reads a SaTScan output .dbf file. 41 | #' 42 | #' @details 43 | #' This is expected to be a purely internal function. 44 | #' It's called by \code{satscan()} with the location and file nmae provided 45 | #' to that function. Since it's nothing more than \code{foreign::read.dbf()}, it's 46 | #' probably nor necessary to even have it as a function. 47 | #' 48 | #' @param location A directory location, including the trailing "/" 49 | #' @param file A file name, without the extension. 50 | #' 51 | #' @return A data frame. 52 | read.gis = function(location,file) foreign::read.dbf(paste0(location,file,".gis.dbf")) 53 | 54 | #' @title Read SaTScan output files 55 | #' 56 | #' @description 57 | #' Reads a SaTScan output .dbf file. 58 | #' 59 | #' @details 60 | #' This is expected to be a purely internal function. 61 | #' It's called by \code{satscan()} with the location and file nmae provided 62 | #' to that function. Since it's nothing more than \code{foreign::read.dbf()}, it's 63 | #' probably nor necessary to even have it as a function. 64 | #' 65 | #' @param location A directory location, including the trailing "/" 66 | #' @param file A file name, without the extension. 67 | #' 68 | #' @return A data frame. 69 | read.llr = function(location,file) foreign::read.dbf(paste0(location,file,".llr.dbf")) 70 | 71 | #' @title Read SaTScan output files 72 | #' 73 | #' @description 74 | #' Reads a SaTScan output .dbf file. 75 | #' 76 | #' @details 77 | #' This is expected to be a purely internal function. 78 | #' It's called by \code{satscan()} with the location and file nmae provided 79 | #' to that function. Since it's nothing more than \code{foreign::read.dbf()}, it's 80 | #' probably nor necessary to even have it as a function. 81 | #' 82 | #' @param location A directory location, including the trailing "/" 83 | #' @param file A file name, without the extension. 84 | #' 85 | #' @return A data frame. 86 | read.sci = function(location,file) foreign::read.dbf(paste0(location,file,".sci.dbf")) 87 | 88 | #' @title Read SaTScan output files 89 | #' 90 | #' @description 91 | #' Reads a SaTScan output .dbf file. 92 | #' 93 | #' @details 94 | #' This is expected to be a purely internal function. 95 | #' It's called by \code{satscan()} with the location and file nmae provided 96 | #' to that function. Since it's nothing more than \code{readLines()}, it's 97 | #' probably nor necessary to even have it as a function. 98 | #' 99 | #' @param location A directory location, including the trailing "/" 100 | #' @param file A file name, without the extension. 101 | #' 102 | #' @return A data frame. 103 | read.satscanmain = function(location,file) suppressWarnings( 104 | readLines(paste0(location,file,".txt"))) 105 | 106 | # need to get these to read dates correctly. Currently reading as factors -------------------------------------------------------------------------------- /vignettes/simulation.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Simulation experiments with SaTScan and rsatscan" 3 | author: "Ken Kleinman" 4 | date: "`r Sys.Date()`" 5 | output: rmarkdown::html_vignette 6 | vignette: > 7 | %\VignetteIndexEntry{Simulation} 8 | %\VignetteEngine{knitr::rmarkdown} 9 | \usepackage[utf8]{inputenc} 10 | --- 11 | 12 | 13 | In this vignette, I use the space-time permutation scan to show how the rsatscan package can be used to simplify the process of making data in R, running SaTScan on the generated data, and collecting the results, presumably leading to quicker and easier accumulation of results. 14 | 15 | I begin by making data on a 10*10 grid of locations, over 30 days. Each day, each location has a 0.1 probability of having a single case. 16 | ```{r} 17 | set.seed(42) 18 | mygeo = expand.grid(1:10,1:10) 19 | daysbase = 30 20 | locid = rep(1:100, times=daysbase) 21 | basecas = rbinom(3000, 1, .1) 22 | day = rep(1:30, each = 100) 23 | mycas = data.frame(locid,basecas, day) 24 | ``` 25 | 26 | Here's what the geo and case files look like. I'm using generic time, for convenience. 27 | ```{r} 28 | head(mygeo) 29 | head(mycas) 30 | ``` 31 | 32 | Now I can write the data into the OS; the row names in the mygeo data.frame object are the location IDs for SaTSCan, so I'm using the `userownames` option to use, rather than ignore, the row names from R in the geography file; in the case file, there is an explicit column with the same information included. 33 | ```{r} 34 | library("rsatscan") 35 | td = tempdir() 36 | write.geo(mygeo, location = td, file = "mygeo", userownames=TRUE) 37 | write.cas(mycas, location = td, file = "mycas") 38 | ``` 39 | 40 | Now I'm ready to build the parameter file. This is adapted pretty closely from the `NYCfever` example in the `rsatscan` vignette. 41 | ```{r} 42 | invisible(ss.options(reset=TRUE)) 43 | ss.options(list(CaseFile="mycas.cas", PrecisionCaseTimes=4)) 44 | ss.options(list(StartDate="1", CoordinatesType=0, TimeAggregationUnits=4)) 45 | ss.options(list(EndDate="30", CoordinatesFile="mygeo.geo", AnalysisType=4, ModelType=2)) 46 | ss.options(list(UseDistanceFromCenterOption="y", MaxSpatialSizeInDistanceFromCenter=3)) 47 | ss.options(list(NonCompactnessPenalty=0, MaxTemporalSizeInterpretation=1, MaxTemporalSize=7)) 48 | ss.options(list(ProspectiveStartDate="30", ReportGiniClusters="n", LogRunToHistoryFile="n")) 49 | ``` 50 | 51 | Then I write the parameter file into the OS and run SaTScan using it. I'll peek in the summary cluster table to see what we got. 52 | ```{r} 53 | write.ss.prm(td, "mybase") 54 | # This step omitted in compliance with CRAN policies 55 | # Please install SaTScan and run the vignette with this and following code uncommented 56 | # SaTScan can be downloaded from www.satscan.org, free of charge 57 | # you will also find there fully compiled versions of this vignette with results 58 | 59 | # mybase = satscan(td, "mybase") 60 | # mybase$col[3:10] 61 | ``` 62 | As one would hope, there's no evidence of a meaningful cluster. 63 | 64 | 65 | Now, let's add a day just like the others. I'll stick it onto the end of the previous data, then write out a new case file. 66 | ```{r} 67 | newday = data.frame(locid = 1:100, basecas = rbinom(100,1,.1), day = 31) 68 | newcas = rbind(mycas,newday) 69 | write.cas(newcas, location = td, file = "mycas") 70 | ``` 71 | 72 | I don't need to re-assign any parameter values that don't change between runs. In this case, since I used the same name for the data file, I only need to change the end date of the surveillance period. 73 | ```{r} 74 | ss.options(list(EndDate="31")) 75 | write.ss.prm(td, "day1") 76 | 77 | # day1 = satscan(td, "day1") 78 | # day1$col[3:10] 79 | ``` 80 | Again, no clusters, as we would expect. 81 | 82 | But now let's make a cluster appear. I create an additional time unit as before, but then select a location to get a heap of extra cases. Glue the new day to the end of the old case file, write it to the OS, change the end date, and re-run SaTScan. 83 | ```{r} 84 | newday = data.frame(locid = 1:100, basecas = rbinom(100,1,.1), day = 32) 85 | newday$basecas[20] =5 86 | newcas = rbind(mycas,newday) 87 | 88 | write.cas(newcas, location = td, file = "mycas") 89 | 90 | ss.options(list(EndDate="32")) 91 | write.ss.prm(td, "day2") 92 | 93 | # day2 = satscan(td,"day2") 94 | # day2$col[3:10] 95 | ``` 96 | This demonstrates that I did detect what I inserted. I can also extract the wordier section of the report about this cluster. 97 | 98 | ```{r} 99 | # summary(day2) 100 | # cat(day2$main[20:31],fill=1) 101 | ``` 102 | 103 | ```{r, echo=FALSE, include=FALSE } 104 | #clean up! 105 | file.remove(paste0(td,"/day1.prm")) 106 | file.remove(paste0(td,"/day2.prm")) 107 | file.remove(paste0(td,"/mybase.prm")) 108 | file.remove(paste0(td,"/mycas.cas")) 109 | file.remove(paste0(td,"/mygeo.geo")) 110 | ``` 111 | 112 | 113 | -------------------------------------------------------------------------------- /R/satscan.R: -------------------------------------------------------------------------------- 1 | #' @title Run SaTScan in the OS 2 | #' 3 | #' @description Calls out into the OS to run SaTScan, with the parameter file specified 4 | #' 5 | #' @param prmlocation A string containing the 6 | #' directory location where the paramter file is located. 7 | #' @param prmfilename A string containg the name of the parameter file, without the extension, i.e., no ".prm". 8 | #' @param sslocation A string containing the directory location where satscanbatch.exe (Windows) 9 | #' is located. The default value is a common location in Windows 7. 10 | #' @param ssbatchfilename Name of the file containing the SaTScan executable. This is likely to be 11 | #' either SaTScanBatch or SaTScanBatch64. Omit the file extension. 12 | #' @param cleanup If true, deletes any SaTScan output files from the OS. 13 | #' @param verbose If true, will display the results in the R console as if running SaTScan in batch. This may be especially 14 | #' useful if you expect SaTScan to take a long time to run. 15 | #' 16 | #' @details The parameter file may have been made by the \code{\link{ss.options}} function or not. 17 | #' If not, or if the \code{matchout = FALSE} parameter was set in \code{ss.options}, then the 18 | #' return object will include the main text output from SaTScan only you manually set the 19 | #' \code{ResultsFile} SaTScan parameter to have the same name as the parameter file. 20 | #' 21 | #' @return A satscan-class object, which is a list of 8 items, not all of which are always made, depending on SaTScan options and whether the program call was successful or not: 22 | #' \describe{ 23 | #' \item{main}{A character vector containing the main text output from SaTScan. This is 24 | #' probably identical to the material displayed when verbose=True} 25 | #' \item{col}{A data frame with the basic cluster information dataset SaTScan makes.} 26 | #' \item{rr}{A data frame with the risk ratio dataset SaTScan makes.} 27 | #' \item{gis}{A data frame with the geographic information dataset SaTScan makes.} 28 | #' \item{llr}{A data frame with the log likelihood ratios dataset SaTScan makes.} 29 | #' \item{sci}{A data frame with the other cluster information dataset SaTScan makes.} 30 | #' \item{shapeclust}{A list object, of class SpatialPolygonsDataFrame, defined by the \code{sp} 31 | #' package. It contains the ESRI shapefile(s) SaTScan makes. This is made only if the \code{rgdal} 32 | #' package is available.} 33 | #' \item{prm}{A character vector containing the contents of the parameter file you told SaTScan 34 | #' to use.} 35 | #' } 36 | #' If an item is not made by SaTScan, it will be NA. 37 | #' 38 | #' @examples 39 | #' 40 | #' \dontrun{ 41 | #' ## Please see vignette("rsatscan"); example() code doesn't make sense since 42 | #' ## all examples rely on calls to SaTScan in the OS. 43 | #' } 44 | #' 45 | #' 46 | #' @seealso \code{\link{ss.options}}, \code{\link{write.ss.prm}} 47 | #' 48 | #' @export 49 | 50 | satscan = function( 51 | prmlocation, prmfilename, sslocation = "c:/progra~2/satscan", 52 | ssbatchfilename = "SaTScanBatch", cleanup = TRUE, verbose=FALSE) { 53 | 54 | 55 | ssfile = paste0(stripslash(sslocation), "/", ssbatchfilename) 56 | if (Sys.which(ssfile) =="") 57 | stop("SaTScan is not there or is not runnable") 58 | prmloc = paste0(stripslash(prmlocation),"/") 59 | infile = paste0(prmloc, prmfilename,".prm") 60 | if (!file.exists(infile)) stop("I can't find that parameter file") 61 | system(paste(shQuote(ssfile), infile), show.output.on.console=verbose) 62 | prm = suppressWarnings(readLines(infile)) 63 | mainfile = if (file.exists(paste0(prmloc,prmfilename,".txt"))) 64 | read.satscanmain(prmloc,prmfilename) else NA 65 | colfile = if (file.exists(paste0(prmloc,prmfilename,".col.dbf"))) 66 | read.col(prmloc,prmfilename) else NA 67 | rrfile = if (file.exists(paste0(prmloc,prmfilename,".rr.dbf"))) 68 | read.rr(prmloc,prmfilename) else NA 69 | gisfile = if (file.exists(paste0(prmloc,prmfilename,".gis.dbf"))) 70 | read.gis(prmloc,prmfilename) else NA 71 | llrfile = if (file.exists(paste0(prmloc,prmfilename,".llr.dbf"))) 72 | read.llr(prmloc,prmfilename) else NA 73 | scifile = if (file.exists(paste0(prmloc,prmfilename,".sci.dbf"))) 74 | read.sci(prmloc,prmfilename) else NA 75 | if (verbose) cat("\n \n Any following message is from readOGR() in the rdgal package \n") 76 | shpfile = if (file.exists(paste0(prmloc,prmfilename,".col.shp"))) { 77 | if (requireNamespace("rgdal", quietly = TRUE)) { 78 | rgdal::readOGR(dsn=stripslash(prmloc), layer=paste0(prmfilename,".col"), 79 | verbose=verbose) 80 | } else cat("\n \n rgdal package not installed, so shapefile can't be imported") 81 | } else NA 82 | if (cleanup) { 83 | suppressWarnings(file.remove(paste0(prmloc,prmfilename,".txt"))) 84 | suppressWarnings(file.remove(paste0(prmloc,prmfilename,".col.dbf"))) 85 | suppressWarnings(file.remove(paste0(prmloc,prmfilename,".rr.dbf"))) 86 | suppressWarnings(file.remove(paste0(prmloc,prmfilename,".gis.dbf"))) 87 | suppressWarnings(file.remove(paste0(prmloc,prmfilename,".llr.dbf"))) 88 | suppressWarnings(file.remove(paste0(prmloc,prmfilename,".sci.dbf"))) 89 | suppressWarnings(file.remove(paste0(prmloc,prmfilename,".col.shp"))) 90 | suppressWarnings(file.remove(paste0(prmloc,prmfilename,".col.shx"))) 91 | } 92 | return(structure(list(main=mainfile, col=colfile, rr = rrfile, gis=gisfile, llr=llrfile, 93 | sci=scifile, shapeclust=shpfile, prm=prm), class="satscan")) 94 | } 95 | 96 | 97 | 98 | 99 | -------------------------------------------------------------------------------- /R/params.R: -------------------------------------------------------------------------------- 1 | utils::globalVariables("ssenv") 2 | #' @title Substitute new values into the input object 3 | #' 4 | #' @description 5 | #' Replaces existing values found in one object with new values 6 | #' 7 | #' @param x A character vector of the form "name=value" 8 | #' @param ssparams A character vector with arbitrary lines, 9 | #' currently imagined to be .ss.params 10 | #' 11 | #' @details 12 | #' For each line of x, the function: 1) finds the "name" and the "value" 13 | #' 2) checks to see whether the "name" exists in ssparams; if not, prints a warning 14 | #' but if so, replaces the existing line of ssparams with that line of x. 15 | #' 16 | #' Not expected to be used directly. 17 | #' 18 | #' @return The modified ssparams. 19 | subin = function (x,ssparams) { 20 | for (i in 1:length(x)) { 21 | inprm = substr(x[i],1,regexpr("=",x[i])) 22 | indef = substr(x[i],regexpr("=",x[i])+1, nchar(x[i])) 23 | if (length(which(substr(ssparams,1,regexpr("=",ssparams)) == inprm)) == 0) 24 | warning('Trouble! There is no parameter "', substr(inprm,1,regexpr("=",inprm)-1), 25 | '"', call.=FALSE) 26 | else {ssparams[which(substr(ssparams,1,regexpr("=",ssparams)) == inprm)]=paste0(inprm,indef)} 27 | } 28 | return(ssparams) 29 | } 30 | 31 | # test whether this works appropriately when there is no = in a an input line 32 | # test whether it works if "name = value", as well as "name=value". 33 | # most likely I should re-do to extract the = from inorm and remove trailing blanks 34 | 35 | 36 | #' @title Change list version of paramaters into char vector 37 | #' 38 | #' @description 39 | #' Turns a list of options into a charvar of options 40 | #' 41 | #' @details 42 | #' The resulting charvar has values such as "name=value" where "name" was the named item 43 | #' of the list. 44 | #' 45 | #' @return 46 | #' A character vector 47 | #' 48 | #' Not expected to be used directly. 49 | #' 50 | #' @param x A list. 51 | #' 52 | charlistopts = function (x) { 53 | paste0(names(x),"=",unlist(x)) 54 | } 55 | 56 | #Huge ups to http://digitheadslabnotebook.blogspot.com/2011/06/environments-in-r.html 57 | #which helped me get the scoping to play out correctly. 58 | #ss.options will: 1) return the current values of .ss.params, if no invals 59 | # 2) Reset the values of .ss.params, if reset==TRUE 60 | # 3) change the values of the listed parameters, if a) invals = 61 | # c("param=value","param=value") or list(param="value") 62 | #' @title Set or reset parameters to be used by SaTScan 63 | #' 64 | #' @description Set or reset parameters to be used by SaTScan 65 | #' 66 | #' @details \code{ss.options()} is intended to function like \code{par()} or 67 | #' \code{options()}. There is a default set of parameter settings that resembles 68 | #' the one used by SaTScan, except that it produces all possible output files and 69 | #' makes them as .dbf files instead of text. 70 | #' 71 | #' @param invals A list with entries of the form name=value, where value should be 72 | #' in quotes unless it is a number. Alternatively, may be a character vector whose 73 | #' entries are of the form "name=value". The "name" in either case should be a 74 | #' valid SaTScan parameter name; unrecognized names will generate a warning and will 75 | #' do nothing. 76 | #' @param reset If TRUE, will restore the default parameter values described in 77 | #' the "Details" section. 78 | #' @return If \code{invals == NULL}, returns the current parameter set, 79 | #' as altered by previous 80 | #' calls to \code{ss.options()} since the last call with \code{reset=TRUE}. Otherwise 81 | #' returns modified parameter set invisibly. The side effect, if \code{invals != NULL}, is to 82 | #' set the current values of the parameters per the value of \code{invals} 83 | #' and \code{reset}. 84 | #' 85 | #' @export 86 | #' 87 | #' @examples 88 | #' \dontrun{ 89 | #' head(ss.options(),3) 90 | #' ss.options(list(CaseFile="NYCfever.cas")) 91 | #' head(ss.options(),3) 92 | #' 93 | #' # reset; shows whole parameter file without invisible() 94 | #' invisible(ss.options(reset=TRUE)) 95 | #' head(ss.options(),3) 96 | #' } 97 | #' 98 | ss.options = function (invals=NULL, reset=FALSE) { 99 | inparms = ssenv$.ss.params 100 | if (reset == TRUE) ssenv$.ss.params = ssenv$.ss.params.defaults 101 | if (is.null(invals)) {return(ssenv$.ss.params)} 102 | else { 103 | if (class(invals) == "list") invals = charlistopts(invals) 104 | ssenv$.ss.params = subin(invals, inparms) 105 | invisible(ssenv$.ss.params) 106 | } 107 | } 108 | # review the help text for logic-- matches function?? 109 | 110 | #I need to think about how this will work when called by another function. 111 | 112 | # Do I need to re-think this? There is 113 | # a [Multiple Data Sets] line already... 114 | 115 | #' @title Add lines to the current SaTScan parameter list 116 | #' 117 | #' @description Allows you to add arbitrary lines to the current set 118 | #' of SaTScan parameters 119 | #' 120 | #' @details For certain SaTScan models or inputs (multiple data sets, 121 | #' Polygon), 122 | #' SaTScan allows a variable number of parameters; these 123 | #' parameters are not used/allowed for other models or inputs. 124 | #' This function allows the user to add 125 | #' arbitray lines to the current list of 126 | #' parameters. In addition to the options mentioned, it could also be 127 | #' used to add comments to the parameter file. 128 | #' 129 | #' @param invals A character vector, which will be added to the end of the 130 | #' current paramter list. 131 | #' 132 | #' @return Nothing. 133 | #' 134 | #' @export 135 | #' 136 | ss.options.extra = function(invals=NULL) { 137 | if (is.null(invals)) stop("This function doesn't do anything when there is no input") 138 | if (class(invals) != "character") stop("Please input a character vector") 139 | else { 140 | ssenv$.ss.params = c(ssenv$.ss.params, invals) 141 | invisible() 142 | } 143 | } 144 | # for help page: examples of [Polygon] and Multiple Data Sets 145 | 146 | 147 | 148 | 149 | 150 | 151 | # Functions to write out the param file 152 | # Probably a really bad idea to make matchout = FALSE-- only useful to write file 153 | # from R but examine output manually 154 | #' @title Write the SaTScan parameter file 155 | #' 156 | #' @description Writes the current set of SaTScan parameters to a 157 | #' specified location in the OS. 158 | #' 159 | #' @details The current SaTScan options can be reset or modified 160 | #' \code{ss.options()} and/or \code{ss.options.extra()}. Once 161 | #' they are set as desired, they can be written to the OS 162 | #' using this function. 163 | #' 164 | #' @param location A directory location, excluding the trailing "/". 165 | #' @param filename The name of the file to be written to the OS; 166 | #' The extension ".prm" will be appended. 167 | #' @param matchout If false, the ResultsFile parameter will not 168 | #' be touched; note that this will likely result in undesirable 169 | #' performance from calls to \code{satcan()} using the parameter file. 170 | #' If true, the ResultsFile is reset to share the filename given here. 171 | #' 172 | #' @return Nothing. (Invisibly.) Side effect is to write a file 173 | #' in the OS. 174 | #' 175 | #' 176 | #' @examples 177 | #' \dontrun{ 178 | #' ## Would write the current ss.options() to c:/temp/NYCfever.prm 179 | #' write.ss.prm("c:/tmp","NYCfever") 180 | #' } 181 | #' 182 | #' 183 | #' 184 | #' @export 185 | #' @seealso \code{\link{ss.options}}, \code{\link{ss.options.extra}} 186 | #' 187 | # 188 | # I should change this to detect and deal with the trailing /. 189 | # change docs to cross-link. 190 | 191 | write.ss.prm = function(location, filename, matchout = TRUE) { 192 | if (matchout) ss.options(list(ResultsFile=paste0(filename,".txt"))) 193 | fileconn<-file(paste0(location,"/",filename,".prm")) 194 | writeLines(ssenv$.ss.params, fileconn) 195 | close(fileconn) 196 | invisible() 197 | } 198 | 199 | 200 | 201 | #Testing 202 | #ss.options(c("CaseFile=blue","ControlFile=red")) 203 | #ss.options("CaseFile=orange") 204 | #head(.ss.params) 205 | #check = ss.options(reset=TRUE) 206 | #head(check) 207 | 208 | 209 | 210 | 211 | 212 | 213 | -------------------------------------------------------------------------------- /vignettes/rsatscan.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "rsatscan" 3 | author: "Ken Kleinman" 4 | date: "`r Sys.Date()`" 5 | output: rmarkdown::html_vignette 6 | vignette: > 7 | %\VignetteIndexEntry{rsatscan} 8 | %\VignetteEngine{knitr::rmarkdown} 9 | \usepackage[utf8]{inputenc} 10 | --- 11 | 12 | SaTScan is a powerful stand-alone software program that runs spation-temporal scan statistics. It is carefully optimized and contains many tricks to reduce the computational burden of the approach, which is doubly computationaly intensive. First, scanning itself can be costly, particularly in spatio-temporal settings. However, even more difficult, testing involves resampling (Monte Carlo hypothesis testing). While SaTScan is not open source, it is distributed free of charge. 13 | 14 | However, use of SaTScan can be cumbersome. There are two means of access: a GUI, and a batch file. The GUI allows complete control, but precludes automated or repeated operation. The batch file allows this, but may be difficult to integrate into other analyses. The `rsatscan` package contains a set of functions and defines a class and methods to make it easy to work with SaTScan from R. This should allow easy automation and integration. 15 | 16 | The functions in the package can be grouped into three sets: 17 | SaTScan parameter functions that set parameters for SaTScan or write them in a file to the OS; write functions that write R data frames to the OS in SaTScan-readable formats; and the `satscan()` function, which calls out into the OS, runs SaTScan, and returns a `satscan` class object. Successful use of the package requires a fairly precise understanding of the SaTScan parameter file, for which users are referred to the SaTScan manual. 18 | 19 | ```{r} 20 | library("rsatscan") 21 | ``` 22 | 23 | Basic usage of the package will: 24 | 25 | 1. use the `ss.options()` function to set SaTScan parameters; these are saved in R 26 | 2. use the `write.ss.prm()` function to write the SaTScan parameter file 27 | 3. use the `satscan()` function to run SaTScan 28 | 4. use `summary()` on the `satscan` object and proceed to analyze the results from SaTScan in R. 29 | 30 | # Space-Time Permutation example: NYC fever data 31 | 32 | The New York City fever data, which are distributed with SaTScan, are also included with the package. 33 | ```{r} 34 | head(NYCfevercas) 35 | head(NYCfevergeo) 36 | ``` 37 | 38 | For good style, an analysis would begin by resetting the paremeter file: 39 | ```{r} 40 | invisible(ss.options(reset=TRUE)) 41 | ``` 42 | 43 | Then, one would change parameters as desired. This can be done in as many or few steps as you like; the previous state of the parameter set is retained, as in `par()` or `options()`. Here, the parameters used in the example from the SaTScan manual are replicated: 44 | ```{r} 45 | ss.options(list(CaseFile="NYCfever.cas", PrecisionCaseTimes=3)) 46 | ss.options(c("StartDate=2001/11/1","EndDate=2001/11/24")) 47 | ss.options(list(CoordinatesFile="NYCfever.geo", AnalysisType=4, ModelType=2, TimeAggregationUnits=3)) 48 | ss.options(list(UseDistanceFromCenterOption="y", MaxSpatialSizeInDistanceFromCenter=3, NonCompactnessPenalty=0)) 49 | ss.options(list(MaxTemporalSizeInterpretation=1, MaxTemporalSize=7)) 50 | ss.options(list(ProspectiveStartDate="2001/11/24", ReportGiniClusters="n", LogRunToHistoryFile="n")) 51 | ``` 52 | Note that the second call to `ss.options()` uses the character vector format, while the others use the list format; either works. 53 | 54 | It might be reasonable at this point to check what the parameter file looks like: 55 | ```{r} 56 | head(ss.options(),3) 57 | ``` 58 | 59 | Then, we write the parameter file, the case file, and the geometry file to some writeable location in the OS, using the functions in package. These ensure that SaTScan-readable formats are used. 60 | ```{r} 61 | td = tempdir() 62 | write.ss.prm(td, "NYCfever") 63 | write.cas(NYCfevercas, td, "NYCfever") 64 | write.geo(NYCfevergeo, td, "NYCfever") 65 | ``` 66 | The `write.???` functions append the appropriate file extensions to the files they save into the OS. 67 | 68 | Then we're ready to run SaTScan. The location of the SaTScan executable may well differ on you r disk, particularly if you do not use Windows. In a later release of the package, it may be possible to detect the location the executable 69 | ```{r} 70 | # This step omitted in compliance with CRAN policies 71 | # Please install SaTScan and run the vignette with this and following code uncommented 72 | # SaTScan can be downloaded from www.satscan.org, free of charge 73 | # you will also find there fully compiled versions of this vignette with results 74 | 75 | ## NYCfever = satscan(td, "NYCfever", sslocation="C:/Program Files (x86)/SaTScan") 76 | ``` 77 | 78 | The `rsatscan` package provides a `summary` method for `satscan` objects. 79 | ```{r} 80 | ## summary(NYCfever) 81 | ``` 82 | 83 | The `satscan` object has a slot for each possible output file that SaTScan creates, and contains whatever output files your call happened to generate. 84 | 85 | ```{r} 86 | ## summary.default(NYCfever) 87 | ``` 88 | 89 | If SaTScan generated a shapefile, `satscan()` reads it, by way of the `rgdal` function `readOGR()`, if it's available, into a class defined in the `sp` package. You can use the plot methods defined in the `sp` package to plot it, or use one of the many packages that builds on the `sp` package for further processing. 90 | 91 | ```{r} 92 | ## sp::plot(NYCfever$shapeclust) 93 | ``` 94 | 95 | It might be interesting to examine the scan statistics from the Monte Carlo steps. 96 | ```{r, fig.keep="all", fig.show="hold"} 97 | ## hist(unlist(NYCfever$llr), main="Monte Carlo") 98 | 99 | # Let's draw a line for the clusters in the observed data 100 | ## abline(v=NYCfever$col[,c("TEST_STAT")], col = "red") 101 | ``` 102 | 103 | This shows why none of the observed clusters had small p=values. 104 | 105 | ```{r, echo=FALSE, include=FALSE } 106 | #clean up! 107 | file.remove(paste0(td,"/NYCfever.prm")) 108 | file.remove(paste0(td,"/NYCfever.cas")) 109 | file.remove(paste0(td,"/NYCfever.geo")) 110 | ``` 111 | 112 | 113 | 114 | # Poisson spatio-temporal example: New Mexico brain tumor data 115 | 116 | This is another data set included with `SaTScan`. It differs from the NYC fever examle in that denominators are available; these are porvided in a population file. The analysis uses the Poisson model rather than the Spatio-temporal permutation. 117 | 118 | ```{r} 119 | write.cas(NMcas, td,"NM") 120 | write.geo(NMgeo, td,"NM") 121 | write.pop(NMpop, td,"NM") 122 | ``` 123 | 124 | Again, replicating the examples from the SaTScan user guide, we set up and then write the parameter file, then run SaTScan. 125 | ```{r} 126 | invisible(ss.options(reset=TRUE)) 127 | ss.options(list(CaseFile="NM.cas",StartDate="1973/1/1",EndDate="1991/12/31", 128 | PopulationFile="NM.pop", 129 | CoordinatesFile="NM.geo", CoordinatesType=0, AnalysisType=3)) 130 | ss.options(c("NonCompactnessPenalty=0", "ReportGiniClusters=n", "LogRunToHistoryFile=n")) 131 | 132 | write.ss.prm(td,"testnm") 133 | ## testnm = satscan(td,"testnm", sslocation="C:/Program Files (x86)/SaTScan") 134 | ``` 135 | Note that the parameter file need not have the same name as the case and other input files, which also need not share a name, though it may be helpful in keeping things organized. 136 | ```{r} 137 | ## summary(testnm) 138 | ``` 139 | 140 | One of the elements of a `satscan` class object is the parameter set which was used to call SaTScan. This may be useful, later. 141 | 142 | ```{r} 143 | ## head(testnm$prm,10) 144 | ``` 145 | 146 | ```{r, echo=FALSE, include=FALSE } 147 | #clean up! 148 | file.remove(paste0(td,"/testnm.prm")) 149 | file.remove(paste0(td,"/NM.pop")) 150 | file.remove(paste0(td,"/NM.cas")) 151 | file.remove(paste0(td,"/NM.geo")) 152 | ``` 153 | 154 | # Bernoulli purely spatial example: North Humberside leukemia and lymphoma 155 | 156 | A third data set included with `SaTScan` is also included with the package. This one has cases and controls, and uses the Bernoulli model. We replicate the parameters from the `SaTScan` manual again. 157 | 158 | ```{r} 159 | write.cas(NHumbersidecas, td, "NHumberside") 160 | write.ctl(NHumbersidectl, td, "NHumberside") 161 | write.geo(NHumbersidegeo, td, "NHumberside") 162 | 163 | invisible(ss.options(reset=TRUE)) 164 | ss.options(list(CaseFile="NHumberside.cas", ControlFile="NHumberside.ctl")) 165 | ss.options(list(PrecisionCaseTimes=0, StartDate="2001/11/1", EndDate="2001/11/24")) 166 | ss.options(list(CoordinatesFile="NHumberside.geo", CoordinatesType=0, ModelType=1)) 167 | ss.options(list(TimeAggregationUnits = 3, NonCompactnessPenalty=0)) 168 | ss.options(list(ReportGiniClusters="n", LogRunToHistoryFile="n")) 169 | 170 | write.ss.prm(td, "NHumberside") 171 | ## NHumberside = satscan(td, "NHumberside", sslocation="C:/Program Files (x86)/SaTScan") 172 | 173 | ## summary(NHumberside) 174 | ``` 175 | 176 | ```{r, echo=FALSE, include=FALSE } 177 | #clean up! 178 | file.remove(paste0(td,"/NHumberside.cas")) 179 | file.remove(paste0(td,"/NHumberside.ctl")) 180 | file.remove(paste0(td,"/NHumberside.geo")) 181 | file.remove(paste0(td,"/NHumberside.prm")) 182 | ``` -------------------------------------------------------------------------------- /R/write.R: -------------------------------------------------------------------------------- 1 | #' @title Write a SaTScan geo file 2 | #' @description Write a SaTScan geo file 3 | #' @details Writes the input data frame to a file in the OS, using the .geo extension. Contents of the data 4 | #' frame should be only what you want SaTScan to see. 5 | #' This is a simple function that calls write.table, since SaTScan just needs ASCII files. 6 | #' @param x Your data frame. 7 | #' @param location Directory location where the file should be written 8 | #' @param filename Name for the output file in the OS; .geo extension will be added. 9 | #' @param userownames If TRUE, will write the row names into the file. 10 | #' @export 11 | write.geo = function(x, location, filename, userownames = FALSE){ 12 | if (class(x) != "data.frame") stop("Need a data frame") 13 | if (dim(x)[2] < 2) stop("Need a data frame with 2 or more columns") 14 | utils::write.table(x, quote=F, file = paste0(location,"/",filename,".geo"), 15 | row.names=userownames, col.names=FALSE) 16 | } 17 | # check to see if data.frame is really needed 18 | 19 | 20 | #' @title Write a SaTScan cas (case) file 21 | #' @description Write a SaTScan cas (case) file 22 | #' @details Writes the input data frame to the OS, using the .cas extension. Contents of the data 23 | #' frame should be only what you want SaTScan to see. 24 | #' This is a simple function that calls write.table, since SaTScan just needs ASCII files. 25 | #' @param x Your data frame. 26 | #' @param location Directory location where the file should be written 27 | #' @param filename Name for the output file in the OS; .cas will be added. 28 | #' @param userownames If TRUE, will write the row names into the file. 29 | #' @export 30 | write.cas = function(x, location, filename, userownames = FALSE){ 31 | if (class(x) != "data.frame") stop("Need a data frame") 32 | if (dim(x)[2] < 2) stop("Need a data frame with 2 or more columns") 33 | utils::write.table(x, quote=F, file = paste0(location,"/",filename,".cas"), 34 | row.names=userownames, col.names=FALSE) 35 | } 36 | 37 | 38 | #' @title Write a SaTScan ctl (control) file 39 | #' @description Write a SaTScan ctl (control) file 40 | #' @details Writes the input data frame to the OS, using the .geo extension. Contents of the data 41 | #' frame should be only what you want SaTScan to see. 42 | #' This is a simple function that calls write.table, since SaTScan just needs ASCII files. 43 | #' @param x Your data frame. 44 | #' @param location Directory location where the file should be written 45 | #' @param filename Name for the output file in the OS; .ctl will be added. 46 | #' @param userownames If TRUE, will write the row names into the file. 47 | #' @export 48 | 49 | write.ctl = function(x, location, filename, userownames = FALSE){ 50 | if (class(x) != "data.frame") stop("Need a data frame") 51 | if (dim(x)[2] > 3) stop("Need a data frame with 3 or fewer columns") 52 | utils::write.table(x, quote=F, file = paste0(location,"/",filename,".ctl"), 53 | row.names=userownames, col.names=FALSE) 54 | } 55 | 56 | 57 | #' @title Write a SaTScan nbr (neighbor) file 58 | #' @description Write a SaTScan nbr (neighbor) file 59 | #' @details Writes the input data frame to the OS, using the .nbr extension. Contents of the data 60 | #' frame should be only what you want SaTScan to see. 61 | #' This is a simple function that calls write.table, since SaTScan just needs ASCII files. 62 | #' @param x Your data frame. 63 | #' @param location Directory location where the file should be written 64 | #' @param filename Name for the output file in the OS; .nbr will be added. 65 | #' @param userownames If TRUE, will write the row names into the file. 66 | #' @export 67 | write.nbr = function(x, location, filename, userownames = FALSE){ 68 | if (class(x) != "data.frame") stop("Need a data frame") 69 | utils::write.table(x, quote=F, file = paste0(location,"/",filename,".nbr"), 70 | row.names=userownames, col.names=FALSE) 71 | } 72 | # This one needs a test, since rows likely have different n of adjacent centroids 73 | 74 | #' @title Write a SaTScan met file 75 | #' @description Write a SaTScan met file 76 | #' @details Writes the input data frame to the OS, using the .met extension. Contents of the data 77 | #' frame should be only what you want SaTScan to see. 78 | #' This is a simple function that calls write.table, since SaTScan just needs ASCII files. 79 | #' @param x Your data frame. 80 | #' @param location Directory location where the file should be written 81 | #' @param filename Name for the output file in the OS; .met will be added. 82 | #' @param userownames If TRUE, will write the row names into the file. 83 | #' @export 84 | write.met = function(x, location, filename, userownames = FALSE){ 85 | if (class(x) != "data.frame") stop("Need a data frame") 86 | utils::write.table(x, quote=F, file = paste0(location,"/",filename,".met"), 87 | row.names=userownames, col.names=FALSE) 88 | } 89 | 90 | #' @title Write a SaTScan max file 91 | #' @description Write a SaTScan max file 92 | #' @details Writes the input data frame to the OS, using the .max extension. Contents of the data 93 | #' frame should be only what you want SaTScan to see. 94 | #' This is a simple function that calls write.table, since SaTScan just needs ASCII files. 95 | #' @param x Your data frame. 96 | #' @param location Directory location where the file should be written 97 | #' @param filename Name for the output file in the OS; .max will be added. 98 | #' @param userownames If TRUE, will write the row names into the file. 99 | #' @export 100 | write.max = function(x, location, filename, userownames = FALSE){ 101 | if (class(x) != "data.frame") stop("Need a data frame") 102 | utils::write.table(x, quote=F, file = paste0(location,"/",filename,".max"), 103 | row.names=userownames, col.names=FALSE) 104 | } 105 | # This one needs a test, since rows likely have different n of adjacent centroids 106 | 107 | #' @title Write a SaTScan adj file 108 | #' @description Write a SaTScan adj file 109 | #' @details Writes the input data frame to the OS, using the .adj extension. Contents of the data 110 | #' frame should be only what you want SaTScan to see. 111 | #' This is a simple function that calls write.table, since SaTScan just needs ASCII files. 112 | #' @param x Your data frame. 113 | #' @param location Directory location where the file should be written 114 | #' @param filename Name for the output file in the OS; .adj will be added. 115 | #' @param userownames If TRUE, will write the row names into the file. 116 | #' @export 117 | write.adj = function(x, location, filename, userownames = FALSE){ 118 | if (class(x) != "data.frame") stop("Need a data frame") 119 | utils::write.table(x, quote=F, file = paste0(location,"/",filename,".adj"), 120 | row.names=userownames, col.names=FALSE) 121 | } 122 | 123 | #' @title Write a SaTScan ha (alternative hypothesis) file 124 | #' @description Write a SaTScan ha (alternatove hypothesis) file 125 | #' @details Writes the input data frame to the OS, using the .ha extension. Contents of the data 126 | #' frame should be only what you want SaTScan to see. 127 | #' This is a simple function that calls write.table, since SaTScan just needs ASCII files. 128 | #' @param x Your data frame. 129 | #' @param location Directory location where the file should be written 130 | #' @param filename Name for the output file in the OS; .ha will be added. 131 | #' @param userownames If TRUE, will write the row names into the file. 132 | #' @export 133 | write.ha = function(x, location, filename, userownames = FALSE){ 134 | if (class(x) != "data.frame") stop("Need a data frame") 135 | utils::write.table(x, quote=F, file = paste0(location,"/",filename,".ha"), 136 | row.names=userownames, col.names=FALSE) 137 | } 138 | 139 | #' @title Write a SaTScan pop (population) file 140 | #' @description Write a SaTScan pop (population) file 141 | #' @details Writes the input data frame to the OS, using the .pop extension. Contents of the data 142 | #' frame should be only what you want SaTScan to see. 143 | #' This is a simple function that calls write.table, since SaTScan just needs ASCII files. 144 | #' @param x Your data frame. 145 | #' @param location Directory location where the file should be written 146 | #' @param filename Name for the output file in the OS; .pop will be added. 147 | #' @param userownames If TRUE, will write the row names into the file. 148 | #' @export 149 | write.pop = function(x, location, filename, userownames = FALSE){ 150 | if (class(x) != "data.frame") stop("Need a data frame") 151 | utils::write.table(x, quote=F, file = paste0(location,"/",filename,".pop"), 152 | row.names=userownames, col.names=FALSE) 153 | } 154 | 155 | #' @title Write a SaTScan grd (grid) file 156 | #' @description Write a SaTScan grd (grid) file 157 | #' @details Writes the input data frame to the OS, using the .grd extension. Contents of the data 158 | #' frame should be only what you want SaTScan to see. 159 | #' This is a simple function that calls write.table, since SaTScan just needs ASCII files. 160 | #' @param x Your data frame. 161 | #' @param location Directory location where the file should be written 162 | #' @param filename Name for the output file in the OS; .grd will be added. 163 | #' @param userownames If TRUE, will write the row names into the file. 164 | #' @export 165 | write.grd = function(x, location, filename, userownames = FALSE){ 166 | if (class(x) != "data.frame") stop("Need a data frame") 167 | utils::write.table(x, quote=F, file = paste0(location,"/",filename,".grd"), 168 | row.names=userownames, col.names=FALSE) 169 | } 170 | 171 | 172 | 173 | -------------------------------------------------------------------------------- /R/zzz.R: -------------------------------------------------------------------------------- 1 | .onAttach <- function(libname, pkgname) { 2 | packageStartupMessage("rsatscan only does anything useful if you have SaTScan") 3 | packageStartupMessage("See http://www.satscan.org/ for free access") 4 | 5 | #These resemble defaults in satscan, but save all the dbase files 6 | 7 | ssenv <<- new.env(parent=emptyenv()) 8 | x = c("[Input]",";case data filename","CaseFile=",";control data filename","ControlFile=",";time precision (0=None, 1=Year, 2=Month, 3=Day, 4=Generic)","PrecisionCaseTimes=1",";study period start date (YYYY/MM/DD)","StartDate=2000/1/1",";study period end date (YYYY/MM/DD)","EndDate=2000/12/31",";population data filename","PopulationFile=",";coordinate data filename","CoordinatesFile=",";use grid file? (y/n)","UseGridFile=n",";grid data filename","GridFile=",";coordinate type (0=Cartesian, 1=latitude/longitude)","CoordinatesType=1","","[Analysis]",";analysis type (1=Purely Spatial, 2=Purely Temporal, 3=Retrospective Space-Time, 4=Prospective Space-Time, 5=Spatial Variation in Temporal Trends, 6=Prospective Purely Temporal)","AnalysisType=1",";model type (0=Discrete Poisson, 1=Bernoulli, 2=Space-Time Permutation, 3=Ordinal, 4=Exponential, 5=Normal, 6=Continuous Poisson, 7=Multinomial)","ModelType=0", 9 | ";scan areas (1=High Rates(Poison,Bernoulli,STP); High Values(Ordinal,Normal); Short Survival(Exponential), 2=Low Rates(Poison,Bernoulli,STP); Low Values(Ordinal,Normal); Long Survival(Exponential), 3=Both Areas)","ScanAreas=1",";time aggregation units (0=None, 1=Year, 2=Month, 3=Day, 4=Generic)","TimeAggregationUnits=1",";time aggregation length (Positive Integer)","TimeAggregationLength=1","","[Output]",";analysis results output filename","ResultsFile=",";output Google Earth KML file (y/n)","OutputGoogleEarthKML=n",";output shapefiles (y/n)","OutputShapefiles=y",";output cluster information in ASCII format? (y/n)","MostLikelyClusterEachCentroidASCII=n",";output cluster information in dBase format? (y/n)","MostLikelyClusterEachCentroidDBase=y",";output cluster case information in ASCII format? (y/n)","MostLikelyClusterCaseInfoEachCentroidASCII=n",";output cluster case information in dBase format? (y/n)", 10 | "MostLikelyClusterCaseInfoEachCentroidDBase=y",";output location information in ASCII format? (y/n)","CensusAreasReportedClustersASCII=n",";output location information in dBase format? (y/n)","CensusAreasReportedClustersDBase=y",";output relative risks in ASCII format? (y/n)","IncludeRelativeRisksCensusAreasASCII=n",";output relative risks in dBase format? (y/n)","IncludeRelativeRisksCensusAreasDBase=y",";output simulated log likelihoods ratios in ASCII format? (y/n)","SaveSimLLRsASCII=n",";output simulated log likelihoods ratios in dBase format? (y/n)","SaveSimLLRsDBase=y","","[Multiple Data Sets]","; multiple data sets purpose type (0=Multivariate, 1=Adjustment)","MultipleDataSetsPurposeType=0","","[Data Checking]",";study period data check (0=Strict Bounds, 1=Relaxed Bounds)","StudyPeriodCheckType=0",";geographical coordinates data check (0=Strict Coordinates, 1=Relaxed Coordinates)", 11 | "GeographicalCoordinatesCheckType=0","","[Spatial Neighbors]",";use neighbors file (y/n)","UseNeighborsFile=n",";neighbors file","NeighborsFilename=",";use meta locations file (y/n)","UseMetaLocationsFile=n",";meta locations file","MetaLocationsFilename=",";multiple coordinates type (0=OnePerLocation, 1=AtLeastOneLocation, 2=AllLocations)","MultipleCoordinatesType=0","","[Spatial Window]",";maximum spatial size in population at risk (<=50%)","MaxSpatialSizeInPopulationAtRisk=50",";restrict maximum spatial size - max circle file? (y/n)","UseMaxCirclePopulationFileOption=n",";maximum spatial size in max circle population file (<=50%)","MaxSpatialSizeInMaxCirclePopulationFile=50",";maximum circle size filename","MaxCirclePopulationFile=",";restrict maximum spatial size - distance? (y/n)","UseDistanceFromCenterOption=n",";maximum spatial size in distance from center (positive integer)", 12 | "MaxSpatialSizeInDistanceFromCenter=1",";include purely temporal clusters? (y/n)","IncludePurelyTemporal=n",";window shape (0=Circular, 1=Elliptic)","SpatialWindowShapeType=0",";elliptic non-compactness penalty (0=NoPenalty, 1=MediumPenalty, 2=StrongPenalty)","NonCompactnessPenalty=1",";isotonic scan (0=Standard, 1=Monotone)","IsotonicScan=0","","[Temporal Window]",";how max temporal size should be interpretted (0=Percentage, 1=Time)","MaxTemporalSizeInterpretation=0",";maximum temporal cluster size (<=90%)","MaxTemporalSize=50",";include purely spatial clusters? (y/n)","IncludePurelySpatial=n",";temporal clusters evaluated (0=All, 1=Alive, 2=Flexible Window)","IncludeClusters=0",";flexible temporal window start range (YYYY/MM/DD,YYYY/MM/DD)","IntervalStartRange=2000/1/1,2000/12/31",";flexible temporal window end range (YYYY/MM/DD,YYYY/MM/DD)","IntervalEndRange=2000/1/1,2000/12/31","", 13 | "[Space and Time Adjustments]",";time trend adjustment type (0=None, 1=Nonparametric, 2=LogLinearPercentage, 3=CalculatedLogLinearPercentage, 4=TimeStratifiedRandomization, 5=CalculatedQuadraticPercentage)","TimeTrendAdjustmentType=0",";time trend adjustment percentage (>-100)","TimeTrendPercentage=0",";time trend type - SVTT only (Linear=0, Quadratic=1)","TimeTrendType=0",";adjust for weekly trends, nonparametric","AdjustForWeeklyTrends=n",";spatial adjustments type (0=No Spatial Adjustment, 1=Spatially Stratified Randomization)","SpatialAdjustmentType=0",";use adjustments by known relative risks file? (y/n)","UseAdjustmentsByRRFile=n",";adjustments by known relative risks file name (with HA Randomization=1)","AdjustmentsByKnownRelativeRisksFilename=","","[Inference]",";p-value reporting type (Default p-value=0, Standard Monte Carlo=1, Early Termination=2, Gumbel p-value=3) ", 14 | "PValueReportType=0",";early termination threshold","EarlyTerminationThreshold=50",";report Gumbel p-values (y/n)","ReportGumbel=n",";Monte Carlo replications (0, 9, 999, n999)","MonteCarloReps=999",";adjust for earlier analyses(prospective analyses only)? (y/n)","AdjustForEarlierAnalyses=n",";prospective surveillance start date (YYYY/MM/DD)","ProspectiveStartDate=2000/12/31",";perform iterative scans? (y/n)","IterativeScan=n",";maximum iterations for iterative scan (0-32000)","IterativeScanMaxIterations=10",";max p-value for iterative scan before cutoff (0.000-1.000)","IterativeScanMaxPValue=0.05","","[Power Evaluation]",";perform power evaluation - Poisson only (y/n)","PerformPowerEvaluation=n",";power evaluation method (0=Analysis And Power Evaluation Together, 1=Only Power Evaluation With Case File, 2=Only Power Evaluation With Defined Total Cases)","PowerEvaluationsMethod=0", 15 | ";total cases in power evaluation","PowerEvaluationTotalCases=600",";critical value type (0=Monte Carlo, 1=Gumbel, 2=User Specified Values)","CriticalValueType=0",";power evaluation critical value .05 (> 0)","CriticalValue05=0",";power evaluation critical value .001 (> 0)","CriticalValue01=0",";power evaluation critical value .001 (> 0)","CriticalValue001=0",";power estimation type (0=Monte Carlo, 1=Gumbel)","PowerEstimationType=0",";number of replications in power step","NumberPowerReplications=1000",";power evaluation alternative hypothesis filename","AlternativeHypothesisFilename=",";power evaluation simulation method for power step (0=Null Randomization, 1=N/A, 2=File Import)","PowerEvaluationsSimulationMethod=0",";power evaluation simulation data source filename","PowerEvaluationsSimulationSourceFilename=",";report power evaluation randomization data from power step (y/n)", 16 | "ReportPowerEvaluationSimulationData=n",";power evaluation simulation data output filename","PowerEvaluationsSimulationOutputFilename=","","[Spatial Output]",";automatically launch Google Earth - gui only (y/n)","LaunchKMLViewer=y",";create compressed KMZ file instead of KML file (y/n)","CompressKMLtoKMZ=n",";whether to include cluster locations kml output (y/n)","IncludeClusterLocationsKML=y",";threshold for generating separate kml files for cluster locations (positive integer)","ThresholdLocationsSeparateKML=1000",";report hierarchical clusters (y/n)","ReportHierarchicalClusters=y",";criteria for reporting secondary clusters(0=NoGeoOverlap, 1=NoCentersInOther, 2=NoCentersInMostLikely, 3=NoCentersInLessLikely, 4=NoPairsCentersEachOther, 5=NoRestrictions)","CriteriaForReportingSecondaryClusters=0",";report gini clusters (y/n)","ReportGiniClusters=y",";gini index cluster reporting type (0=optimal index only, 1=all values)", 17 | "GiniIndexClusterReportingType=0",";spatial window maxima stops (comma separated decimal values[<=50%] )","SpatialMaxima=1,2,3,4,5,6,8,10,12,15,20,25,30,40,50",";max p-value for clusters used in calculation of index based coefficients (0.000-1.000)","GiniIndexClustersPValueCutOff=0.05",";report gini index coefficents to results file (y/n)","ReportGiniIndexCoefficents=n",";restrict reported clusters to maximum geographical cluster size? (y/n)","UseReportOnlySmallerClusters=n",";maximum reported spatial size in population at risk (<=50%)","MaxSpatialSizeInPopulationAtRisk_Reported=50",";restrict maximum reported spatial size - max circle file? (y/n)","UseMaxCirclePopulationFileOption_Reported=n",";maximum reported spatial size in max circle population file (<=50%)","MaxSizeInMaxCirclePopulationFile_Reported=50",";restrict maximum reported spatial size - distance? (y/n)","UseDistanceFromCenterOption_Reported=n", 18 | ";maximum reported spatial size in distance from center (positive integer)","MaxSpatialSizeInDistanceFromCenter_Reported=1","","[Temporal Output]",";output temporal graph HTML file (y/n)","OutputTemporalGraphHTML=n","","[Other Output]",";report critical values for .01 and .05? (y/n)","CriticalValue=n",";report cluster rank (y/n)","ReportClusterRank=n",";print ascii headers in output files (y/n)","PrintAsciiColumnHeaders=n","","[Elliptic Scan]",";elliptic shapes - one value for each ellipse (comma separated decimal values)","EllipseShapes=1.5,2,3,4,5",";elliptic angles - one value for each ellipse (comma separated integer values)","EllipseAngles=4,6,9,12,15","","[Power Simulations]",";simulation methods (0=Null Randomization, 1=N/A, 2=File Import)","SimulatedDataMethodType=0",";simulation data input file name (with File Import=2)","SimulatedDataInputFilename=", 19 | ";print simulation data to file? (y/n)","PrintSimulatedDataToFile=n",";simulation data output filename","SimulatedDataOutputFilename=","","[Run Options]",";number of parallel processes to execute (0=All Processors, x=At Most X Processors)","NumberParallelProcesses=0",";suppressing warnings? (y/n)","SuppressWarnings=n",";log analysis run to history file? (y/n)","LogRunToHistoryFile=y",";analysis execution method (0=Automatic, 1=Successively, 2=Centrically)","ExecutionType=0","","[System]",";system setting - do not modify","Version=9.2.0","") 20 | 21 | ssenv$.ss.params.defaults = x 22 | ssenv$.ss.params = x 23 | 24 | } 25 | --------------------------------------------------------------------------------