简介：SaTScan 中文说明书是一份面向公共卫生、流行病学与空间统计方向学习者的中文文档，用于帮助读者理解这款自由软件在空间、时间及时空扫描统计中的核心用法。SaTScan 常用于地理疾病监测、疾病集群检测与统计显著性评估，也可迁移到考古、生态、犯罪学等领域的聚集性分析。资源包为 doc 格式，共 1 个文件，约 485KB，内容涵盖离散与连续扫描统计、泊松模型、伯努利模型、时空置换模型、多项式与序模型、指数模型及空间变化时间趋势模型等，并配有新墨西哥脑肿瘤、亨伯赛德儿童白血病、纽约发热急诊等示例数据集说明。已有 2805 人学习下载，适合需要快速掌握软件原理、模型选择与数据格式的读者作为中文参考手册使用。
1. SaTScan 中文说明书环境搭建：从下载到跑通第一个泊松模型
很多人第一次接触 SaTScan，以为它是个绿色小工具，双击 exe 就能用。我当初也这么想，结果在一台 Windows 机器上装完，打开示例会话直接报错，折腾了一下午才发现是数据文件路径里带了中文目录。SaTScan 是做空间、时间、时空扫描统计的自由软件，常用于地理疾病监测、检测空间或时空疾病集群、判断病例是否随机分布，也能拿来做考古、生态、犯罪学等领域的聚集性分析。它支持离散泊松、伯努利、时空置换、多项式、序模型、指数模型、正态模型和连续泊松等多种模型。装不好，连示例数据集都跑不起来，更别说用自己的数据出结果。这篇笔记按我实际部署的顺序，把版本选择、安装、参数文件配置、避坑和验证一次讲清，适合刚上手 SaTScan、卡在环境配置上的开发者。
2. 安装前先把版本和数据格式定下来：SaTScan 9.0 与三类输入文件
2.1 版本选择与运行环境确认
SaTScan 官方提供 Windows、Linux 和 macOS 版本，我一般优先选当前稳定版，比如 9.0 系列。版本差异主要体现在支持的模型和参数上，比如 v9.0 对时空置换模型和多项模型有更新，老版本打开新参数文件可能直接提示不兼容。运行环境方面，Windows 版对系统要求不高，但建议至少 4GB 内存，因为时空扫描在县、邮编级别数据上会做大量置换计算，内存不够会中途崩掉。Linux 版通常以压缩包形式发布，解压后直接运行可执行文件，不需要 root 权限，适合放在服务器上做定期监测。
安装前先确认三件事：操作系统位数、是否有写权限的目录、以及数据文件准备放在哪里。我习惯在用户目录下建一个satscan_work文件夹，把可执行文件、参数文件、案例文件、坐标文件全放进去，避免路径里出现空格和中文。这一步看着简单，但后面很多报错都跟路径有关。
2.2 三类输入文件的格式与作用
SaTScan 的输入文件分三类：案例文件（.cas）、人口文件（.pop）或控制文件（.ctl）、坐标文件（.geo）。案例文件记录每个观察的位置、时间、属性；人口文件用于离散泊松模型，提供每个位置的风险人口；控制文件用于伯努利模型，提供对照数量；坐标文件给出每个位置的经纬度或直角坐标。
以泊松模型为例，案例文件格式通常是：位置标识、病例数、时间、属性变量。人口文件格式：位置标识、年份、人口数、属性变量。坐标文件格式：位置标识、X 坐标、Y 坐标。这三个文件的位置标识必须完全一致，否则 SaTScan 会报“位置不匹配”。我一般先用文本编辑器打开检查一遍，确认没有多余空格和 BOM 头。
# 以 nm.cas 为例，查看前几行确认格式 head -5 nm.cas # 输出示例： # 1 3 1973 1 1 # 1 2 1974 1 1 # 2 1 1973 2 1上面每行代表一个位置在某一年的病例数，后面两列是年龄组和性别变量。如果列数对不上，导入时就会提示“列数不一致”。坐标文件同理，用head看一眼，确认 X、Y 是数值而不是字符串。
2.3 下载与安装步骤
从 SaTScan 官网下载对应平台的安装包。Windows 版是 exe，双击后按提示下一步即可，安装路径建议用默认的C:\Program Files\SaTScan，不要改到中文目录。Linux 版下载 tar.gz 包，解压到工作目录：
# 解压 Linux 版 SaTScan tar -zxvf satscan_linux_9.0.tar.gz -C ~/satscan_work cd ~/satscan_work/satscan # 赋予可执行权限 chmod +x satscan # 查看版本，确认能运行 ./satscan --version--version能输出版本号，说明可执行文件没问题。如果提示缺少库，常见做法是安装libgomp或libstdc++的兼容版本。macOS 版类似，解压后直接运行，但首次打开可能被系统拦截，需要在“安全性与隐私”里允许。
安装完成后，先别急着用自己的数据，用官方示例数据集跑一遍。示例数据在官网 datasets 页面可以下载，包含 nm.cas、nm.pop、nm.geo 等文件。把这些文件放到工作目录，打开 SaTScan，选择“打开保存的会话”，加载对应的参数文件（.prm）。如果示例能跑出结果，说明环境基本正常。
3. 配置参数文件：泊松模型与伯努利模型的参数怎么填
3.1 参数文件的结构与关键字段
SaTScan 的参数文件（.prm）是纯文本，记录分析类型、输入文件路径、模型选择、扫描窗口、蒙特卡洛置换次数等。我一般不用图形界面从头建，而是拿示例参数文件改，这样不容易漏字段。关键字段包括：
CaseFile：案例文件路径PopulationFile：人口文件路径（泊松模型）ControlFile：控制文件路径（伯努利模型）CoordinatesFile：坐标文件路径ModelType：模型类型，如DiscretePoisson、BernoulliScanType：扫描类型，Spatial、Temporal、SpaceTimeMaxSpatialSize：最大空间扫描窗口比例MaxTemporalSize：最大时间扫描窗口比例MonteCarloReps：置换次数，一般 999 或 9999
路径建议写绝对路径，或者相对于参数文件的相对路径。我遇到过因为路径里用了反斜杠导致 Linux 版读不到文件，改成正斜杠就好了。
# 示例参数文件片段：离散泊松模型，时空扫描 CaseFile=nm.cas PopulationFile=nm.pop CoordinatesFile=nm.geo ModelType=DiscretePoisson ScanType=SpaceTime MaxSpatialSize=50 MaxTemporalSize=50 MonteCarloReps=999MaxSpatialSize=50表示空间扫描窗口最多覆盖研究区域 50% 的风险人口，这个值太大会导致集群范围过宽，太小可能漏掉真实集群。我一般先用 50% 跑一遍，再根据结果调整。MonteCarloReps越大，P 值越稳定，但计算时间线性增长，调试阶段可以用 99 次先看能不能跑通。
3.2 伯努利模型与时空置换模型的参数差异
伯努利模型用控制文件代替人口文件，案例文件里每行代表一个病例或对照，用 0/1 区分。参数文件里把ModelType改成Bernoulli，并指定ControlFile。时空置换模型更简单，只需要案例文件和坐标文件，不需要人口或控制文件，ModelType设为SpaceTimePermutation。但要注意，时空置换模型对人口变化敏感，如果研究期间超过几年，背景人口增长会导致 P 值有偏，官方文档也提醒谨慎使用。
# 伯努利模型参数片段 CaseFile=nhumberside.cas ControlFile=nhumberside.ctl CoordinatesFile=nhumberside.geo ModelType=Bernoulli ScanType=Spatial伯努利模型里，案例文件每行是一个个体，控制文件每行是对照数。如果位置标识重复，SaTScan 会自动汇总。我一般先用小样本跑通，再换全量数据，避免一开始就卡在格式错误上。
3.3 运行分析与结果文件解读
参数文件配好后，命令行运行：
# Linux 下运行 SaTScan ./satscan -p nm.prmWindows 下可以在图形界面点“运行”，或者用命令行satscan.exe -p nm.prm。运行结束后会生成结果文件，通常包括.txt汇总、.llr似然比、.gis地理文件等。重点看.txt里的集群列表：每个集群的位置、时间范围、病例数、期望病例数、相对风险、对数似然比和 P 值。P 值小于 0.05 通常认为集群有统计学意义，但还要结合相对风险和实际背景判断。
我一般会检查结果里的“总病例数”和输入文件是否一致，如果不一致，说明有记录被跳过，常见原因是位置标识不匹配或时间格式错误。这一步是验证数据完整性的关键。
4. 避坑与排查：SaTScan 安装配置中最容易翻车的五个点
4.1 现象：打开示例会话报“无法读取文件”
原因：路径里包含中文、空格或特殊字符，或者文件编码不是 UTF-8。SaTScan 对路径比较敏感，尤其是 Windows 版，中文目录经常导致读取失败。
解决：把工作目录改成纯英文路径，比如D:\satscan_work，并确保所有输入文件用 UTF-8 无 BOM 编码保存。用 Notepad++ 或 VS Code 转换编码后重新加载。
4.2 现象：运行时报“位置标识不匹配”
原因：案例文件、人口文件、坐标文件里的位置标识不一致，比如一个用数字 1，另一个用字符串 “001”，或者有前后空格。
解决：用sort和diff对比三个文件的位置标识列：
# 提取位置标识并排序，对比差异 cut -d' ' -f1 nm.cas | sort > cas_ids.txt cut -d' ' -f1 nm.pop | sort > pop_ids.txt diff cas_ids.txt pop_ids.txt如果有差异，统一格式后再跑。我习惯在 Excel 里先清洗一遍，确保三列完全一致。
4.3 现象：蒙特卡洛置换跑了一半卡住或崩溃
原因：置换次数设得太大，或者数据量太大导致内存不足。时空扫描在县级别数据上做 9999 次置换，可能跑几个小时。
解决：调试阶段把MonteCarloReps降到 99 或 199，确认能跑通后再调大。如果内存不足，可以分区域跑，或者换 Linux 服务器。我一般会在参数文件里加NumProcessors利用多核，但老版本可能不支持。
4.4 现象：结果里 P 值全是 1 或没有集群
原因：扫描窗口设置不合理，比如MaxSpatialSize太小，或者时间范围设错。也可能是数据本身没有聚集性。
解决：先把MaxSpatialSize调到 50%，MaxTemporalSize调到 50%，用示例数据验证。如果示例能出结果，再换自己的数据。检查时间字段格式是否与参数文件里的StudyPeriod一致。
4.5 现象：Linux 版运行提示缺少共享库
原因：系统缺少libgomp、libstdc++等依赖，或者版本不兼容。
解决：用ldd satscan查看缺失的库，然后通过包管理器安装。常见做法是安装gcc和g++运行时库。如果没权限，可以下载静态编译版本，或者用容器跑。
5. 装完怎么验证跑通：用示例数据集做一次完整回归
验证 SaTScan 是否装好，最直接的办法是用官方示例数据集跑一遍完整流程，然后检查输出是否合理。我一般按下面几步走：
第一步，下载 nm 数据集（泊松模型，时空扫描），放到工作目录。第二步，用示例参数文件运行，命令行或图形界面都行。第三步，检查结果文件里的集群数量和 P 值分布。第四步，对比官方文档里给出的参考结果，确认没有大的偏差。
# 完整验证流程 cd ~/satscan_work ./satscan -p nm.prm # 查看结果摘要 head -30 nm.txt # 检查集群列表 grep -i "cluster" nm.txt | head -10如果结果里出现至少一个 P 值小于 0.05 的集群，且位置和时间范围与示例描述一致，说明环境、参数、数据格式都没问题。我还会用伯努利模型示例再跑一遍，确认不同模型都能正常加载。
提示：验证时不要用自己的数据直接跑，先用示例数据排除环境问题。示例数据跑不通，自己的数据更跑不通。
另外，我习惯在验证通过后，把参数文件、输入文件、结果文件打包备份，并记录版本号和运行命令。这样下次换机器部署时，直接解压就能复现。SaTScan 的版本差异主要体现在模型支持和参数字段上，跨版本迁移时，先用新版本打开旧参数文件，看是否有警告，再逐项调整。
从那以后我每次装 SaTScan，都强制先用示例数据集走一遍完整流程，确认输出文件里集群列表和 P 值都正常，才敢换自己的数据。这个习惯帮我省了很多来回排查的时间。希望帮到你。
本文还有配套的精品资源，点击获取
