SaTScan安装配置完整指南：Java环境、参数文件与避坑实践

简介：SaTScan 中文说明书面向公共卫生、流行病学与空间统计方向的研究者及学生，帮助解决空间、时间及时空扫描统计软件上手难、英文文档阅读门槛高的问题。资源包内含1个doc文档，约485KB，系统梳理了SaTScan的核心用途与操作要点，涵盖地理疾病监测、疾病集群检测、随机分布检验及前瞻性实时监测等场景。文档详细介绍了离散与连续扫描统计的差异，以及泊松模型、伯努利模型、时空置换模型、多项式模型、序模型、指数模型和空间变化时间趋势模型等方法的适用条件，并配有新墨西哥脑肿瘤、亨伯赛德儿童白血病、纽约发热急诊及马里兰教育水平等示例数据集说明，便于读者对照理解数据格式与参数设置。目前已有2805人学习下载，适合需要快速掌握SaTScan建模流程、开展疾病聚集性分析的研究人员参考。

1. 装 SaTScan 前，先把版本和运行环境理清楚

SaTScan 这个软件，做疾病监测、空间聚类分析的人早晚会碰到。它是个自由软件，专门分析空间、时间、时空数据，用扫描统计的方法检测疾病集群有没有统计学意义。听起来挺学术，但装起来其实不复杂——真正让人翻车的是版本选错、Java 环境没配对、数据文件格式对不上。我见过太多人下载完双击图标，弹个报错就卡住了，然后开始怀疑人生。

这篇笔记面向的是准备在自己机器上把 SaTScan 跑起来的开发者，不管你是做地理疾病监测、公共卫生研究，还是拿它分析考古、生态、犯罪学里的空间聚类问题。我会把下载、安装、配置、测试数据跑通、常见报错处理这一整条链路拆开讲，每一步都落到具体操作。装完之后，你至少能用它自带的示例数据集跑出一份完整结果，知道每个参数文件是干什么的。

2. 下载与安装：从官网拿到能跑的安装包

2.1 确认系统要求和 Java 依赖

SaTScan 是 Java 写的，所以不管你用 Windows、macOS 还是 Linux，机器上必须有 Java 运行时环境。官方推荐 Java 8 或更高版本，我一般会装 Java 11 或 Java 17 的 LTS 版本，稳定、兼容性好。检查 Java 是否已安装，打开终端或命令行：

java -version

如果输出类似openjdk version "17.0.x"就说明有了。如果提示command not found，那就得先装 Java。Windows 用户去 Oracle 或 Adoptium 下载 JDK 安装包，macOS 用 Homebrew 一行搞定：

brew install openjdk@17

Linux 上用包管理器，比如 Ubuntu：

sudo apt update sudo apt install openjdk-17-jdk

装完再跑一次java -version确认。这里有个坑：有些机器上装了多个 Java 版本，java命令指向的还是旧版，SaTScan 启动时可能报UnsupportedClassVersionError。解决办法是检查JAVA_HOME环境变量，确保指向你刚装的那个版本。

2.2 从官网下载 SaTScan 安装包

SaTScan 的官方下载地址是http://www.satscan.org。打开页面后找 Download 链接，选择对应你操作系统的版本。Windows 用户下载.exe安装程序，macOS 和 Linux 用户下载.zip或.tar.gz压缩包。下载之前建议先看一眼官网的更新日志，确认你拿的是最新稳定版。我一般不会追最新 beta 版，生产环境用稳定版更稳妥。

下载完成后，Windows 直接双击.exe，跟着安装向导一步步走，选安装路径时注意别放在中文目录下——这是血泪经验，SaTScan 对中文路径的支持时好时坏，放在C:\SaTScan这种纯英文路径下最省心。macOS 和 Linux 用户解压压缩包到你想放的目录：

tar -xzf satscan.tar.gz -C /opt/satscan

解压后目录里会有可执行文件、示例数据集和文档。Linux 下可能需要给可执行文件加权限：

chmod +x /opt/satscan/satscan

2.3 安装后的目录结构说明

装完之后别急着打开，先看一眼目录结构，后面配置参数文件的时候心里有数。典型的 SaTScan 安装目录包含这几类东西：

示例数据集里比较常用的几个：新墨西哥州脑肿瘤发病率数据（泊松模型，时空扫描）、儿童白血病数据（伯努利模型，纯空间扫描）、纽约市发热病例数据（时空置换模型）。这些数据集是验证安装是否成功的最好材料，后面会具体讲怎么跑。

3. 配置参数文件：搞懂 .cas、.pop、.geo、.ctl 四件套

3.1 参数文件类型和格式要求

SaTScan 运行一次分析，通常需要准备几个输入文件，具体要哪些取决于你用哪个统计模型。最常见的组合是：

• .cas 文件：病例数据，记录每个病例的位置、时间等信息
• .pop 文件：人口数据，用于泊松模型，提供每个位置的背景人口数
• .geo 文件：地理坐标文件，记录每个位置的经纬度或直角坐标
• .ctl 文件：控制文件，用于伯努利模型，记录对照数据

这些文件都是纯文本格式，用空格或制表符分隔列。格式要求比较严格，列的顺序和含义必须和参数设置里指定的对应。比如泊松模型的 .cas 文件，典型格式是：

<位置ID> <病例数> <时间>

而 .pop 文件的格式是：

<位置ID> <年份> <人口数>

. geo 文件则是：

<位置ID> <X坐标> <Y坐标>

我一般会先用文本编辑器打开示例数据集里的文件，对照着看几行，搞清楚每一列代表什么，然后再改自己的数据。直接上手写容易因为列错位导致读取出错。

3.2 在图形界面里加载参数文件

SaTScan 有图形界面，打开后点击 “Open Saved Session”，选择一个参数文件（通常是 .prm 后缀），软件会自动加载对应的输入文件路径和分析设置。以新墨西哥州脑肿瘤数据为例，加载nm.prm后，界面里会显示：

• 病例文件：nm.cas
• 人口文件：nm.pop
• 坐标文件：nm.geo
• 研究期间：1973 至 1991 年
• 聚类数量：32 个县
• 时间精度：年
• 坐标类型：直角坐标
• 变量：年龄组（1 到 18）、性别（1 男 2 女）

这些参数在界面里都可以手动改。如果你要跑自己的数据，最省事的做法是复制一份示例参数文件，改掉文件路径和参数值，另存为新的 .prm 文件。

3.3 命令行方式运行分析

图形界面适合调试，但如果你要批量跑多个数据集，或者把 SaTScan 集成到自动化流程里，命令行方式更高效。基本用法：

satscan /path/to/your_parameters.prm

运行后 SaTScan 会在参数文件指定的输出目录里生成结果文件，包括聚类列表、统计显著性、日志文件等。命令行模式下没有图形界面弹窗，所有信息都写到日志里，所以跑完之后一定要检查日志文件确认没有报错。

提示：命令行运行时，参数文件里的路径最好用绝对路径，相对路径在不同工作目录下容易找不到文件。

4. 避坑与排查：装 SaTScan 最容易踩的五个坑

4.1 启动报错 “Could not find or load main class”

现象：双击图标或命令行运行，弹窗提示找不到主类，程序直接退出。

原因：Java 环境变量没配好，或者JAVA_HOME指向了一个不存在的路径。有时候是装了多个 Java 版本，PATH 里排在前面的那个版本太旧。

解决：先跑java -version确认当前生效的 Java 版本。如果版本低于 8，重新装一个 Java 11 或 17。然后检查JAVA_HOME：

echo $JAVA_HOME

Windows 下用echo %JAVA_HOME%。如果为空或指向错误路径，手动设置成正确的 JDK 目录。改完重启终端再试。

4.2 加载参数文件后提示 “File not found”

现象：打开 .prm 文件后，软件提示某个 .cas 或 .pop 文件找不到。

原因：参数文件里记录的是相对路径，而你打开参数文件时的工作目录和当初保存时不一样。或者你把数据文件挪了位置，但没更新参数文件里的路径。

解决：用文本编辑器打开 .prm 文件，找到文件路径那一行，改成绝对路径。比如把nm.cas改成/opt/satscan/sample/nm.cas。改完保存，重新加载。

4.3 数据格式错误导致读取失败

现象：软件能打开参数文件，但一运行就报错，提示某一行数据格式不对，或者读取到的记录数为零。

原因：.cas、.pop、.geo 文件里的列分隔符不统一，或者列的顺序和参数设置里指定的不一致。常见的是从 Excel 导出时带了多余的制表符或空格，或者文件编码不是 UTF-8。

解决：用文本编辑器打开数据文件，确认每一行的列数和分隔符一致。建议用空格分隔，不要混用制表符。如果是从 Excel 导出的，先另存为 CSV，再用脚本转成空格分隔的纯文本。检查文件编码：

file -i yourdata.cas

如果不是utf-8，用iconv转一下：

iconv -f gbk -t utf-8 yourdata.cas > yourdata_utf8.cas

4.4 中文路径导致程序异常

现象：程序能启动，但加载数据或输出结果时莫名其妙报错，日志里出现乱码。

原因：SaTScan 对中文路径和中文文件名的支持不完善，尤其是在 Windows 上。Java 的文件读取在某些编码环境下会把中文路径解析错。

解决：把 SaTScan 安装目录、数据文件目录、输出目录全部改成纯英文路径。文件名也不要用中文。这是最省事的办法，别跟编码较劲。

4.5 内存不足导致分析中断

现象：跑大规模数据时，程序跑到一半卡住，或者报OutOfMemoryError。

原因：SaTScan 默认的 JVM 堆内存可能不够用，尤其是病例数多、扫描窗口大的时候。

解决：找到 SaTScan 的启动脚本（Windows 下是.bat文件，Linux/macOS 下是 shell 脚本），修改 JVM 内存参数。比如把-Xmx调到 4G：

java -Xmx4g -jar satscan.jar

具体改哪个文件取决于你的安装方式，Windows 安装版一般在安装目录下有个satscan.l4j.ini之类的配置文件，里面可以加-Xmx4g。改完保存，重启软件。

5. 装完怎么验证：用示例数据集跑通一次完整分析

装完 SaTScan、配好 Java 环境之后，别急着拿自己的数据跑。先用官方示例数据集验证一遍，确认整条链路没问题。我一般会选新墨西哥州脑肿瘤数据，因为它覆盖了泊松模型、时空扫描、空间变化时间趋势这几个核心功能，跑通了说明安装基本没问题。

打开 SaTScan，点击 “Open Saved Session”，找到示例数据集目录下的nm.prm文件。加载后检查一下界面里的参数：病例文件nm.cas、人口文件nm.pop、坐标文件nm.geo，研究期间 1973 到 1991 年，聚类数量 32 个县，时间精度为年，坐标类型为直角坐标。这些应该都是自动填好的。确认无误后点击运行按钮，等待分析完成。

分析结束后，SaTScan 会弹出一个结果窗口，显示检测到的聚类列表。每个聚类包含位置、时间范围、病例数、期望病例数、相对风险、对数似然比和 P 值。如果 P 值小于 0.05，说明这个聚类在统计学上显著。你还可以点击 “Export” 把结果导出为 CSV 或文本文件，方便后续处理。

除了看结果窗口，还要检查输出目录里的日志文件。日志里会记录分析过程中的详细信息，包括读取了多少条病例记录、多少个人口记录、扫描窗口的设置、迭代次数等。如果日志里有WARNING或ERROR字样，根据提示排查。常见的是数据里有缺失值或者坐标超出研究区域范围。

跑完新墨西哥州数据后，可以再试一个伯努利模型的例子，比如儿童白血病数据nhumberside.prm。这个数据集是纯空间扫描，需要 .cas、.ctl 和 .geo 三个文件。加载后运行，看看能不能正常出结果。如果两个例子都能跑通，说明你的 SaTScan 安装和配置都没问题，可以开始导入自己的数据了。

从那以后我每次装完 SaTScan，都会先拿示例数据集跑一遍，确认 Java 版本、文件路径、数据格式都没问题，再动自己的数据。这个习惯帮我省了很多来回折腾的时间。希望帮到你。

本文还有配套的精品资源，点击获取