hcp4715/hddm repository overview

⁠A HDDM docker image

There a few different images, see hcp4715/hddm/tags.

⁠Report issues

If you encountered any issues in using this docker image, please feel free to report it here⁠ or discuss it with others here⁠.

⁠How to cite us

If you used one of these docker images in your research, please cite Wiecki et al. (2013) and our paper:

⁠Tags

Below is the information about different tags of the docker images. We recommend you use the latest tag.

latest: same as hddm:1.0.1, see Version 12 of our AMPPS paper⁠ for tutorial.

hddm:1.0.1: Python 3.8.8, the latest version of HDDM 1.0.1⁠, this tag include two images, one for machines with amd64 (intel) chips (same as hddm:1.0.1-amd64), one for machines with arm64 chips (m1/m2/apple, same as hddm:1.0.1-arm64). See our AMPPS paper⁠ for the tutorial.

hddm:1.0.1-amd64: the HDDM 1.0.1 image for machines with amd64 (intel) chips;

hddm:1.0.1-arm64: the HDDM 1.0.1 image for machines with arm64 (m1/m2/apple) chips;

hddm:0.9.8RC or hddm:0.9.8: Python 3.8.8, HDDM 0.9.8, fixed a few bugs (credit to Wanke and zenkavi⁠), this tag include two images, one for machines with amd64 (intel) chips (same as hddm:0.9.8RC-amd64 or hddm:0.9.8-amd64), one for machines with arm64 chips (m1/m2/apple, same as hddm:0.9.8RC-arm64 or hddm:0.9.8-arm64). See Version 8 of our preprint⁠ for tutorial.

hddm:0.9.8RC-amd64: the HDDM 0.9.8RC image for machines with amd64 (intel) chips;

hddm:0.9.8RC-arm64: the HDDM 0.9.8RC image for machines with arm64 (m1/m2/apple) chips;

hddm:0.8.0: Python 3.8.8, HDDM 0.8.0, and kabuki 0.6.4. This version also has both amd64 and arm64 version. This version works with arviz too. We keep this version for reproducing published results from this version.

hddm:0.8_tutorial: Python 3.8.8, HDDM 0.8, kabuki 0.6.4, and with functions bridging HDDM model results and arviz. For machines with amd64 (intel) chips. We keep this version because it is the image for the Version 6 of the preprint⁠;

hddm:0.8_tutorial_arm64: Python 3.8.8, HDDM 0.8, kabuki 0.6.4, and with functions bridging HDDM model results and arviz. For machines with arm64 (m1/m2/apple) chips. We keep this version because it is the image for the Version 6 of the preprint⁠.

⁠What is HDDM?

HDDM is a python package for hierarchical drift diffusion modelling, see here⁠ for more.

⁠How to use this docker image

⁠Installation

First, install docker and test it. Please check docker website.

⁠Ubuntu

Please read this post on docker's website⁠ for installing docker for Linux (Ubuntu included).

Then, pull the latest HDDM from docker hub:

docker pull hcp4715/hddm

Note: you may need sudo permission to run the command docker.

⁠Windows

Please read this post⁠ for installing docker on Windows. During the installation of docker, you might be instructed to install/update your window subsystem linux (WSL), please follow the instruction to finish the installation of docker.

Then, open window power shell with administrator privileges, and pull the latest docker image from docker hub:

docker pull hcp4715/hddm

⁠Start a container and code in Jupyter notebook

After pulling it from docker hub, you can then run jupyter notebook in the container (e.g., in terminal of Linux/MacOS or PowerShell/Command Line of Windows, for windows users, PowerShell/Command Line should be opened with administrator privileges):

⁠Example code for Ubuntu:

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

⁠Example code for windows:

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

⁠Explanations of the example code

docker run ---- Run a docker image in a container

-it ---- Keep STDIN open even if not attached

--rm ---- Automatically remove the container when it exits

--cpus=5 ---- Number of cores will be used by docker

-v ---- Mount a folder to the container

/home/hcp4715/dockerhddm ---- The directory of a local folder where I stored my data [For Linux/MacOS]. If you are using windows, and you hope to analyze data stored in the folder hcp4715/dockerhddm in drive D, you can use /d/hcp4715/dockerhddm, this is the directory of a local folder under drive D. It appears as D:\hcp4715\dockerhddm in windows system.

/home/jovyan/work ---- The directory inside the docker image (the mounting point of the local folder in the docker image). Note that the docker container itself likes a mini virtual linux system, so the file system inside it is Linux style.

-p ---- Publish a container’s port(s) to the host

hcp4715/hddm ---- The docker image to run. You can also be more specific, using hcp4715/hddm:latest, where the latest after : is the tag of the current docker image.

jupyter notebook ---- Open juypter notebook when start running the container.

After running the code above, bash will has output like this:

....
....
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:
    http://174196acc395:8888/?token=75f1a7a8ffcbb55f0c2802433a9a5d57ac00868e05089c09
 or http://127.0.0.1:8888/?token=75f1a7a8ffcbb55f0c2802433a9a5d57ac00868e05089c09

Copy the full url (http://127.0.0.1:8888/?token=⁠.......) to a browser (firefox or chrome) and it will show a web page, this is the interface of jupyter notebook! Note, in Windows system, it might be localhost instead of 127.0.0.1 in the url.

Under the Files tab, there should be three folders: work and examples. The work folder is the local folder mounted in docker container. The examples folder was the one built in docker image, this folder includes one dataset and one jupyter notebooks, you can test functions of HDDM by running this jupyter notebook.

Enter work folder, you can start your analysis with HDDM.

⁠Using examples

The examples folder also includes two other jupyter notebooks, HDDM_official_tutorial_reproduced.ipynb reproduces the tutorial code, using the HDDM in this docker image.

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

⁠Potential errors

1. Permission denied. If you still encounter this error, please see this post⁠ about the permission problem.

2. The port 8888 was occupied. You may use other ports by these two steps: (1) replace the -p 8888:888 with -p 8787:8888 in docker run ..., AND (2), change 8888 to 8787 after pasting the url generated by docker run ....

⁠How this docker image was built

The docker image is to build it from Dockerfile. This Dockerfile is modified by Dr. Rui Yuan @ Stanford, based on the Dockerfile of jupyter/scipy-notebook⁠. We installed additional packages for HDDM and ipyparallel, and configured the ipyparallel so that we can run it in jupyter noebook (doesn't work for jupyterlab yet). See Dockerfile for the details

Code for building the docker image (don't forget the . in the end):

docker build -t hcp4715/hddm:[tag] -f Dockerfile .

• replace [tag] with a tag you prefer.

⁠Acknowledgement

Thank @madslupe⁠ for his previous HDDM image, which laid the base for the current version.

Thank Dr Rui Yuan⁠ for his help in creating the Dockerfile.