简介：本资源是Isherwood、Clifford、Schira、Roberts与Spehar于2021年发表视觉研究论文的配套MATLAB代码，面向从事时空视觉感知、分形几何与心理物理学实验的研究生、科研人员及计算神经科学方向的开发者，用于复现论文中的时空斜率计算与三维分形刺激生成流程。压缩包共4个文件，包含3个m脚本与1个md说明文档，整体约9KB，体积轻量便于快速部署；其中脚本分别承担时间斜率、空间斜率计算以及三维分形刺激构建等核心功能，md文件则提供使用说明与依赖提示。目前已有119人学习下载，适合作为视觉实验数据分析与刺激生成的参考模板。读者可借助该代码理解论文方法的具体实现，掌握时空斜率拟合与分形刺激参数化的编程思路，并在此基础上迁移到自身实验任务中，减少从零搭建分析流程的成本。
1. 时空数据怎么存才不翻车：从一份视觉研究代码说起
做视觉与认知实验的同行，大概率都遇到过同一个尴尬：实验跑完了，数据也采了，可等到要复现某张图、某个统计结果时，发现原始刺激、被试反应、时间戳散落在三四个文件夹里，命名规则还各不相同。pp-spatiotemp 这个存储库，解决的正是这类问题——它把一项关于空间与时间知觉的视觉研究（Isherwood 等，2021）所用的代码整理成一套可复用的分析流程。核心场景很明确：你手头有一批带时间维度的视觉刺激与行为数据，想稳定地做预处理、指标计算和可视化，而不是每次重写脚本。适合谁？做心理物理、视觉认知、EEG/fMRI 行为侧分析的实验员和研究生，以及需要把实验代码交付给合作者的工程师。它不炫技，但把「时空数据怎么组织、怎么算、怎么画」这条链路讲得比较实。
2. 先搞懂时空数据在视觉实验里的组织逻辑
2.1 为什么空间与时间要放在同一张表里
视觉实验的数据天然是二维以上的：每个试次（trial）有空间位置（刺激出现在视野的哪个方位、偏心距多少），也有时间属性（呈现时长、SOA、反应时）。很多人的第一版代码会把空间参数写进一个 config，把时间序列另存一个 csv，结果做交互分析时两边对不上号。pp-spatiotemp 的思路是：以试次为最小单元，把空间字段和时间字段并到同一张主表，时间序列信号（如果有）用外键关联。这样做的好处是任何一次筛选、分组、聚合都只操作一张表，不会出现「空间条件筛完忘了同步时间条件」的玄学 bug。
常见做法是定义一个 schema，字段分三类：标识类（subject_id、trial_id、block）、空间类（eccentricity、angle、hemifield）、时间类（duration_ms、soa_ms、rt_ms）。我一般会强制要求所有时间字段带_ms后缀，所有角度字段带_deg，单位写进字段名，省得三个月后自己都忘了是弧度还是角度。
2.2 目录结构决定你能不能复现
一个能交付的视觉分析项目，目录不该是「新建文件夹 (3)」。参考这类研究的通用组织方式，可以这样分层：
project/ data/ raw/ # 原始导出，只读，永不修改 interim/ # 清洗中间态，可重建 processed/ # 分析就绪数据 src/ io.py # 读写与 schema 校验 preprocess.py # 清洗、试次剔除 metrics.py # 指标计算 plots.py # 可视化 configs/ exp.yaml # 实验参数 outputs/ figures/ tables/关键原则只有一条：raw只读。任何清洗都写到interim或processed，这样一旦发现剔除规则写错，删掉中间产物重跑即可，原始数据永远有后悔药。很多人翻车就翻在直接对 raw 做 in-place 修改，出了问题连对照都没有。
2.3 用配置驱动而不是硬编码
实验参数（呈现时长、偏心距列表、被试数）如果写死在脚本里，换个数据集就得改代码。用一份 YAML 配置把参数抽出来，脚本只读配置：
# configs/exp.yaml experiment: name: "spatiotemp_demo" durations_ms: [50, 100, 200, 400] eccentricities_deg: [2.0, 4.0, 8.0] soa_ms: [0, 100, 300] preprocess: rt_min_ms: 150 # 反应时下限，低于此视为抢答 rt_max_ms: 2000 # 反应时上限，高于此视为走神 exclude_missing: true参数说明：rt_min_ms和rt_max_ms是试次剔除的硬边界，视觉实验里低于 150ms 的反应基本是预判，高于 2000ms 多半是注意力漂移。这两个值不是拍脑袋，要结合你的任务难度调，但一定要显式写进配置，而不是散落在 if 语句里。
3. 把原始数据跑成可用指标的最小流程
3.1 读取与 schema 校验
第一步不是急着算指标，而是确认读进来的表符合预期。字段缺失、单位错乱、被试 ID 混入空格，这些问题越早暴露越好。
# src/io.py import pandas as pd REQUIRED_COLS = { "subject_id": "object", "trial_id": "int64", "eccentricity_deg": "float64", "duration_ms": "float64", "soa_ms": "float64", "rt_ms": "float64", "correct": "bool", } def load_trials(path: str) -> pd.DataFrame: df = pd.read_csv(path) # 字段存在性检查 missing = set(REQUIRED_COLS) - set(df.columns) if missing: raise ValueError(f"缺少字段: {missing}") # 类型与单位校验 for col, dtype in REQUIRED_COLS.items(): df[col] = df[col].astype(dtype) # 角度范围合理性检查 if df["eccentricity_deg"].lt(0).any(): raise ValueError("偏心距出现负值，检查单位或符号约定") return df逻辑说明：REQUIRED_COLS同时承担字段清单和类型契约两个职责，缺字段直接抛错而不是默默继续。参数上，eccentricity_deg用浮点是因为偏心距常有小数；correct用布尔而非 0/1，是为了后续聚合时语义清晰。这一步多花五分钟，能省掉后面几小时的「为什么分组结果对不上」。
3.2 试次剔除与清洗
清洗的核心是「有依据地删」，而不是「看着不顺眼就删」。视觉实验里常见的剔除规则：反应时越界、缺失反应、以及基于被试整体正确率的离群剔除。
# src/preprocess.py import pandas as pd def clean_trials(df: pd.DataFrame, cfg: dict) -> pd.DataFrame: n0 = len(df) # 1) 反应时越界 rt_ok = df["rt_ms"].between(cfg["rt_min_ms"], cfg["rt_max_ms"]) # 2) 缺失反应 if cfg["exclude_missing"]: rt_ok &= df["rt_ms"].notna() df = df[rt_ok].copy() # 3) 被试级正确率离群（低于均值2个标准差） acc = df.groupby("subject_id")["correct"].mean() keep = acc[acc >= acc.mean() - 2 * acc.std()].index df = df[df["subject_id"].isin(keep)] print(f"剔除试次: {n0 - len(df)} / {n0}") return df逻辑说明：三步剔除顺序不能乱——先做试次级过滤，再做被试级过滤，否则被试正确率会被未清洗的脏试次污染。参数rt_min_ms/rt_max_ms来自配置，2 * std是常用的离群阈值，样本量小的时候可以放宽到 2.5。打印剔除数量是血泪经验：不打印，你永远不知道某次改动是不是把一半数据误删了。
3.3 计算时空交互指标
研究空间与时间知觉，核心指标往往是「不同偏心距下，反应时随 SOA 变化的曲线」。这类指标要按条件聚合，而不是笼统求平均。
# src/metrics.py import pandas as pd def spatiotemp_metrics(df: pd.DataFrame) -> pd.DataFrame: # 只保留正确试次计算反应时 correct = df[df["correct"]] out = ( correct .groupby(["subject_id", "eccentricity_deg", "soa_ms"]) .agg( rt_mean=("rt_ms", "mean"), rt_std=("rt_ms", "std"), n_trials=("rt_ms", "size"), ) .reset_index() ) # 试次数过少的格子标记出来，避免噪声结论 out["reliable"] = out["n_trials"] >= 8 return out逻辑说明：分组键是subject_id + eccentricity_deg + soa_ms，正好对应空间与时间两个维度。n_trials >= 8这个阈值是经验值，格子内试次太少时均值极不稳定，标成reliable=False后续画图可以淡化处理。参数上，rt_std保留是为了画误差棒，别只存均值。
3.4 可视化：把交互效应画出来
# src/plots.py import matplotlib.pyplot as plt import seaborn as sns def plot_rt_by_soa(metrics: pd.DataFrame, out_path: str): sns.set_theme(style="whitegrid") g = sns.FacetGrid( metrics, col="eccentricity_deg", hue="subject_id", col_wrap=3, height=3 ) g.map(sns.lineplot, "soa_ms", "rt_mean", marker="o", alpha=0.6) g.set_axis_labels("SOA (ms)", "反应时 (ms)") g.savefig(out_path, dpi=150, bbox_inches="tight")逻辑说明：用FacetGrid按偏心距分面，每个被试一条线，能直观看出交互趋势是否在个体间一致。alpha=0.6是为了被试线重叠时不糊成一片。dpi=150兼顾清晰度和文件体积，投稿级图可以提到 300。
4. 避坑与排查：那些让结果对不上的细节
4.1 现象：分组均值算出来和手算差一点
原因：groupby默认会丢弃含 NaN 的行，而你可能在别处用fillna(0)补过缺失反应时，导致 0 被当成有效值参与均值。解决：清洗阶段就明确缺失处理策略，要么剔除要么显式标记，绝不用 0 填充反应时。检查方法是在聚合前打印df["rt_ms"].isna().sum()。
4.2 现象：不同被试的偏心距条件数不一致
原因：原始数据里某些被试没跑全条件，或者条件名有空格/大小写差异（"2.0"vs"2.0 "）。解决：读取后统一做str.strip()和类型转换，再用pivot_table检查条件覆盖矩阵，缺格子的被试要么补跑要么在分析里显式排除。
4.3 现象：图里曲线抖动剧烈，结论不可信
原因：格子内试次太少，或者把错误试次也算进了反应时。解决：确认reliable标记，错误试次单独统计正确率而非混入反应时。视觉实验里错误试次的反应时分布和正确试次往往不同，混在一起是典型的黑匣子操作。
4.4 现象：换台机器跑结果就变了
原因：随机种子没固定，或者依赖库版本不一致导致浮点聚合顺序不同。解决：在配置里固定random_seed，用requirements.txt锁版本，聚合前对数据按subject_id, trial_id排序，保证顺序确定。
4.5 现象：原始数据被改过，无法回溯
原因：直接对raw目录做了写操作。解决：把raw设为只读权限，所有清洗输出到interim。这是最不该犯但最常犯的错，一旦原始数据被覆盖，连后悔药都没得吃。
5. 进阶：把一次性脚本变成可复用的分析管线
走到这里，你已经能把一份时空视觉数据跑通。但真正拉开差距的，是让这套流程可复用、可验证。我一般会做三件事。
第一，写一个端到端入口脚本，把load → clean → metrics → plot串起来，参数全部从配置读：
# run_pipeline.py import yaml from src.io import load_trials from src.preprocess import clean_trials from src.metrics import spatiotemp_metrics from src.plots import plot_rt_by_soa def main(cfg_path: str): with open(cfg_path) as f: cfg = yaml.safe_load(f)["preprocess"] df = load_trials("data/raw/trials.csv") df = clean_trials(df, cfg) metrics = spatiotemp_metrics(df) metrics.to_csv("outputs/tables/metrics.csv", index=False) plot_rt_by_soa(metrics, "outputs/figures/rt_by_soa.png") if __name__ == "__main__": main("configs/exp.yaml")这样换数据集只需改配置和输入路径，逻辑一行不动。
第二，加一层轻量验证。对关键指标做断言，比如「清洗后试次数不应少于原始的 60%」「每个被试至少覆盖 3 个 SOA 条件」。断言失败就中断，比事后看图发现异常要早得多。
第三，把中间产物版本化。metrics.csv每次生成带时间戳或哈希，配合一份简短的变更记录，说明这次改了什么规则、影响了哪些条件。合作者拿到手能对上号，而不是收到一堆metrics_final_v2.csv。
| 阶段 | 输入 | 输出 | 关键校验 |
|---|---|---|---|
| 读取 | raw/trials.csv | DataFrame | 字段齐全、单位正确 |
| 清洗 | 原始表 + 配置 | interim 表 | 剔除比例合理 |
| 指标 | 清洗后表 | metrics.csv | 格子试次充足 |
| 可视化 | metrics.csv | figures | 个体趋势一致 |
最后说个我自己的习惯：任何一次分析，先跑通一个被试、一个条件，确认数字对得上手算，再放开全量。急着跑全量然后对着异常结果排查，往往比先小后大慢得多。这套时空数据的组织与计算思路，迁移到别的视觉或行为实验也基本成立，希望帮到你。
本文还有配套的精品资源，点击获取
