HDDM Docker镜像文档

镜像概述

本镜像为HDDM（Hierarchical Drift Diffusion Modeling，贝叶斯分层漂移扩散模型）提供便捷的部署环境。HDDM是一个用于反应时数据分析的Python包，广泛应用于心理学、神经科学等领域。本镜像整合了HDDM及其依赖库，支持ArviZ可视化工具，并提供Jupyter Notebook交互环境，适配amd64（Intel）和arm64（Apple M1/M2）架构，简化用户的安装与配置流程。

标签说明

镜像提供多个标签版本，推荐使用latest标签。各标签信息如下：

• latest：与hddm:1.0.1相同，基于预印本Version 12提供教程。
• hddm:1.0.1：Python 3.8.8，HDDM 1.0.1最新版，包含amd64（Intel芯片，同hddm:1.0.1-amd64）和arm64（Apple M1/M2芯片，同hddm:1.0.1-arm64）两个版本，教程见预印本Version 12。
• hddm:1.0.1-amd64：适用于amd64架构（Intel芯片）的HDDM 1.0.1镜像。
• hddm:1.0.1-arm64：适用于arm64架构（Apple M1/M2芯片）的HDDM 1.0.1镜像。
• hddm:0.9.8RC/hddm:0.9.8：Python 3.8.8，HDDM 0.9.8版本（修复部分bug），包含amd64（同hddm:0.9.8RC-amd64）和arm64（同hddm:0.9.8RC-arm64）版本，教程见预印本Version 8。
• hddm:0.9.8RC-amd64：适用于amd64架构的HDDM 0.9.8RC镜像。
• hddm:0.9.8RC-arm64：适用于arm64架构的HDDM 0.9.8RC镜像。
• hddm:0.8.0：Python 3.8.8，HDDM 0.8.0，kabuki 0.6.4，支持amd64和arm64架构，用于复现基于该版本的已发表结果。
• hddm:0.8_tutorial：适用于amd64架构，包含HDDM 0.8、kabuki 0.6.4及HDDM与ArviZ桥接功能，对应预印本Version 6教程。
• hddm:0.8_tutorial_arm64：适用于arm64架构的hddm:0.8_tutorial版本。

引用说明

若在研究中使用本镜像，请引用以下文献：

Wiecki et al 2013: [***]

以及预印本：

Pan, W., Geng, H., Zhang, L., Fengler, A., Frank, M. J., Zhang, R.-Y., & Chuan-Peng, H. (2025). dockerHDDM: A User-Friendly Environment for Bayesian Hierarchical Drift-Diffusion Modeling. Advances in Methods and Practices in Psychological Science, 8(1), 25152459241298700. [***]

安装步骤

前提条件

首先安装Docker并测试，具体步骤参考Docker***文档：

• Ubuntu：Docker Engine安装指南
• Windows：Docker Desktop安装指南（Windows用户需安装WSL，按提示完成配置）

拉取镜像

安装Docker后，拉取最新版HDDM镜像：

bash
docker pull hcp4715/hddm

注意：Ubuntu用户可能需要sudo权限执行Docker命令；Windows用户需以管理员权限打开PowerShell/命令行。

使用方法

启动容器与Jupyter Notebook

拉取镜像后，通过以下命令启动容器并运行Jupyter Notebook：

Ubuntu示例

bash
docker run -it --rm --cpus=4 \
-v /home/用户名/dockerhddm:/home/jovyan/work \
-p 8888:8888 hcp4715/hddm jupyter notebook

Windows示例

bash
docker run -it --rm --cpus=4 -v /d/用户名/dockerhddm:/home/jovyan/work -p 8888:8888 hcp4715/hddm jupyter notebook

参数说明

• docker run：运行Docker镜像
• -it：保持标准输入打开
• --rm：容器退出后自动删除
• --cpus=4：指定容器使用的CPU核心数
• -v 本地路径:/home/jovyan/work：挂载本地文件夹到容器内（本地路径需替换为实际数据目录，如Ubuntu的/home/用户名/data或Windows的/d/用户名/data）
• -p 8888:8888：将容器的8888端口映射到主机，用于访问Jupyter Notebook
• hcp4715/hddm：镜像名称（可指定标签，如hcp4715/hddm:1.0.1-arm64）
• jupyter notebook：启动Jupyter Notebook服务

访问Jupyter Notebook

运行命令后，终端会输出类似以下内容：

To access the notebook, open this file in a browser:
    file:///home/jovyan/.local/share/jupyter/runtime/nbserver-6-open.html
Or copy and paste one of these URLs:
    [***]
 or [***]

复制包含127.0.0.1:8888（或Windows的localhost:8888）的URL到浏览器，即可访问Jupyter Notebook。容器内的work文件夹对应本地挂载目录，examples文件夹包含示例数据和教程 notebooks（如HDDM_official_tutorial_reproduced.ipynb）。

使用示例

运行以下命令可直接启动容器并查看内置示例：

bash
docker run -it --rm --cpus=4 -p 8888:8888 hcp4715/hddm jupyter notebook

访问Jupyter后，在examples文件夹中可找到示例数据集和教程notebook，用于测试HDDM功能。

潜在错误与解决方法

1. 权限拒绝：参考HDDM用户组讨论解决权限问题。
2. 端口8888被占用：修改端口映射，如-p 8787:8888，并将浏览器URL中的8888替换为8787。

镜像构建说明

本镜像基于jupyter/scipy-notebook的Dockerfile修改，添加了HDDM、ipyparallel等依赖，并配置了ipyparallel以支持Jupyter Notebook（暂不支持JupyterLab）。构建命令如下：

bash
docker build -t hcp4715/hddm:[标签] -f Dockerfile .

替换[标签]为自定义标签（如1.0.1-custom）。

致谢

• 感谢斯坦福大学Rui Yuan博士对Dockerfile的修改与优化。
• 感谢@madslupe提供的早期HDDM镜像基础。
• 感谢Wanke和zenkavi对HDDM 0.9.8版本的bug修复贡献。

问题反馈

使用中遇到问题，请通过以下渠道反馈：

• GitHub Issues
• GitHub Discussions