HDDM (by JAE-YOUNG SON)

Introduction

HDDM is a Python package that makes it extremely easy to perform Drift Diffusion Model analyses using hierarchical Bayesian parameter estimation. As Python packages go, it is fairly well-documented, and has an active user forum where you can ask questions and get answers (often from the software developers themselves) within 48 hours.

This guide is not written to be comprehensive, nor will it teach you the fundamentals of DDM or use of HDDM. Instead, this guide goes over some of the finer points of HDDM that would probably take you a long time to figure out on your own, especially if you're a newcomer to DDM, Python, or Bayesian stats.

Sample HDDM scripts

Click here to see sample scripts for HDDM.

I want to learn more about DDM and/or HDDM

Good for you! Here are some resources that will get you started:

• What is the Drift Diffusion Model?
  • Voss, Rothermund, & Ross, 2004
  • Ratcliff & McKoon, 2008
• How does HDDM work?
  • Wiecki, Sofer, & Frank, 2013
• Can the DDM be used to study social decision-making?
  • Hutcherson, Bushong, & Rangel, 2015
  • Germar et al., 2016
  • Huber, Klucharev, & Rieskamp, 2014

How to install HDDM

Step 1: Install Anaconda

Anaconda is an open-data package manager that contains many Python packages useful for scientific computing. Here's how to install it on your personal computer:

1. Download the command-line version of Anaconda for Python 3
2. Open up an instance of Terminal and type cd Downloads to change directory into the Downloads folder (presuming this is where the shell script was saved)
3. Now copy/paste whatever command Anaconda's website tells you to (something like bash Anaconda3-VersionNumber.sh)
4. Say yes to everything and wait until it finishes installing. It will give you a notification when it is done, so even if it looks like it's not doing anything, just be patient
5. Open up a new Terminal window and close the old one

Step 2: Set up Anaconda to accommodate the installation of HDDM

Unfortunately, some of the packages that HDDM relies on are not yet compatible with Python 3.6. To proceed, you have two options:

1. Downgrade your default Python installation to 3.5 (less preferable)
   1. Type conda install python=3.5
2. Create a virtual environment that uses Python 3.5 (preferable if you use Python for other reasons, and therefore need to use the latest versions of Python)
   1. Type conda create -n VirtualEnvironmentName python=3.5 anaconda (the name of your virtual environment can be anything; the Anaconda developers like py35, which is reasonable)
   2. If you do this, you will need to call your virtual environment every time you start a new Python session by typing source activate VirtualEnvironmentName

Step 3: Install HDDM

1. Type source activate VirtualEnvironmentName to enter into your virtual environment
2. Type conda install -c pymc hddm
3. All done! Yes, it's really that easy.

How to use HDDM

Getting started

HDDM's documentation includes an excellent tutorial, which you should treat as a textbook.

Use my sample scripts as a template!

Troubleshooting

There are miscellaneous coding quirks with HDDM, Jupyter, and Oscar that can make you want to throw your computer out the window, especially because these quirks are not particularly well-documented. I have done all the hard work for you figuring out how to fix/work around these quirks... don't reinvent the wheel! Reference my sample scripts to see how to bypass some common problems.

Note that HDDM is utterly inflexible about what you name your key variable columns:

• Your subject identifiers column should always be named subj_idx
• Your RTs column should always be named rt
• Your response/choice column should always be named response
• On the other hand, HDDM is very flexible about what you name your other IVs

Running HDDM through Jupyter

What is Jupyter, and when should I use it?

Jupyter is a Python package that allows you to create "notebooks" containing Python code. It is automatically installed when you install Anaconda. The real benefit of using Jupyter is that you can write modular code (it's literally compartmentalized into separate cells), which makes it extremely easy to play around with code. Therefore, Jupyter is great for when you need to immediately see the output of experimental code.

Note that Jupyter is less good for when you need to run computationally-intensive analyses that you've already bug-tested. In these situations, you should use CCV's Oscar to run batch scripts instead.

I'm sold. How do I use Jupyter?

Type jupyter notebook into your Terminal. A new tab will open in your default web browser, from which you can navigate through your computer's folders and create new notebooks wherever you please. If your web browser does not open a new tab automatically, copy the link from your Terminal and paste it into your browser. Don't close Terminal unless you want to close Jupyter!

Running HDDM through CCV's Oscar

What is Oscar, and when should I use it?

Oscar is the name of Brown's computing cluster, maintained through the Center for Computation and Visualization (CCV). You should use Oscar when you have a thoroughly-vetted analysis script that would take your personal/work computer a long time to process (e.g. MCMC sampling ≥ 2000).

How do I set up an Oscar account?

Click here for instructions on how to create an Oscar account. By default, you have free access to an "exploratory" account as an individual. However, our lab has access to a "condo" account through the Brown Institute for Brain Science (BIBS), which means that you will have priority access to truly mind-boggling computing power once you are associated with our group.

How do I log into Oscar?

Open up Terminal, then type ssh YourUsername@ssh.ccv.brown.edu. Type in your password, and you'll be logged into a login node.

What the hell's a login node? Wait, how is Oscar even structured?

Genuinely good question. Okay, imagine walking into a mansion. That mansion is the entirety of Oscar. You get to rent rooms inside this mansion: from the shared resources, you're given "private" computing resources to do whatever you want, and you can specify how much computing power you need.

On the other hand, the front door and foyer of this mansion are like a login node: everyone shares it. What you do in the privacy of your own room is your own business, but it would be very inconsiderate if you were to start doing a weird interpretive dance in the middle of a common space, as you'd be taking up a lot of unnecessary space from everyone else for no good reason. In the same way, you should NEVER run scripts straight from the login node. Why? Because login nodes are shared by everyone, and because login nodes aren't very computationally powerful anyways. It's self-defeating and it pisses people off. What should you do instead? Most likely, you'll want to run an interactive session or a batch job.

How do I install Anaconda and HDDM in my CCV folder?

First, you'll need to get the installer on the CCV server. To do this, download Anaconda for Linux (64-bit, x86). Upload that shell script you just downloaded to your Oscar data folder (/gpfs/data/groupname/username). If you don't know how to do this, reference "Moving files around on Oscar" below.

Presuming that you're already logged into your CCV account, start an interactive session. Recommended parameters are interact -n 16 -t 01:00:00 -m 16g

Finally, run whatever command Anaconda's website tells you to (something like bash Anaconda3-VersionNumber-Linux-x86_64.sh).

Next, follow the instructions in the "How to install HDDM" section of this page WITH THE FOLLOWING ADDENDUMS:

1. When Anaconda asks you for an installation location, DO NOT press enter to install into the default location! Instead, tell Anaconda that you want the installation to take place inside (/users/YourUsername/data/YourUsername/anaconda3).
2. When downgrading to Python 3.5, create an Anaconda virtual environment. It's best practice, and it actually ends up being the easiest way to call the correct version of Python from CCV.
3. At the end of the installation process, Anaconda will ask you something to this effect: Do you wish the installer to prepend the Anaconda install location to PATH in your /home/name/.bashrc ? [yes|no]. Say yes!

How do I move files around on Oscar?

There are ways to do this using Terminal text commands, but I personally like using a GUI. Honestly, if you need to ask, you'd probably prefer using a GUI also.

Download the FileZilla client and install it. Open up the "Site Manager" window, and create a new site. Name it "CCV" or something to that effect. For "host", copy/paste ssh.ccv.brown.edu. Select the SFTP protocol. Select the Normal login type, then type in your username and password into the appropriate fields. Finally, click connect to connect with the CCV server.

By default, you will be taken to your "home" directory. You should never use it. Instead, store all of your data in your data directory, preferably such that each HDDM project is stored in its own subdirectory.

How do I ask Oscar to run batch scripts?

Read this guide from CCV to get a Gestalt sense for what to do. Don't worry if you don't understand everything they say. Download my sample scripts to see how batch scripts should be written.

This guide was written by Jae-Young Son and was last updated July 11th, 2017