Skip to content

Registration Example Using Jupyter

Jump to bottom
Jared Tanner edited this page Feb 17, 2026 · 1 revision

PSY4930 Lab: Brain Image Registration (HiPerGator + JupyterLab)

Goal

Learn how we align an individual brain to a universal “average” brain (MNI space) so we can compare neuroimaging and neuropsychological data across people.

Phase 1 — Set up your HiPerGator workspace (OOD)

  1. Log in to ood.rc.ufl.edu.
  2. Open Clusters → HiPerGator Shell Access.
  3. Copy/paste the commands below one at a time (press Enter after each).

A) Create a shortcut to the class directory

ln -s /blue/psy4930 ~/psy4930

B) Install the PSY4930 Jupyter kernel (one-time setup)

/blue/psy4930/share/data/neurotools/envs/psy4930/bin/python -m ipykernel install --user --name psy4930 --display-name "PSY4930 Class Kernel"

C) Create your personal class folder and copy the notebook

This creates your folder (if needed) and copies the notebook you will run:

mkdir -p /blue/psy4930/$USER
cp /blue/psy4930/share/data/registration/class_image_registration_demo.ipynb /blue/psy4930/$USER/

Sanity check (optional):

ls -lh /blue/psy4930/$USER/class_image_registration_demo.ipynb

Phase 2 — Launch JupyterLab

  1. In ood.rc.ufl.edu, go to Interactive Apps → JupyterLab.
  2. Use these resources:
    • Cores: 2
    • Memory: 8 GB
    • Time: 3 hours
  3. Click Launch, then Connect to Jupyter.

Phase 3 — Open the notebook and select the correct kernel

  1. In JupyterLab’s left sidebar, open:
    • psy4930 → your GatorLink ID (your $USER folder)
  2. Open class_image_registration_demo.ipynb.
  3. CRITICAL: In the top-right kernel selector, choose:
    • PSY4930 Class Kernel

If you do not select the class kernel, cells may fail due to missing Python packages.

Phase 4 — Interactive lesson (instructor script)

1) The misaligned cat (baseline)

What to say:
“We start with my cat, Melody. She moved between two photos. Run Cell 1.”

What students should notice:

  • Red/green “ghosts” (halos) show raw misalignment error.
  • The goal is to reduce the halos until the images overlap.

2) The “rigid” fix (affine / linear registration)

What to say:
“Run Cell 2. This is affine registration—think sliding/rotating a printed photo to match the other.”

What students should notice:

  • Big movements are corrected (shift/rotate/scale) but this looks like the output of the first cell.
  • It cannot fully correct local differences (e.g., parts moving independently).

3) The “clay” warp (diffeomorphic / nonlinear registration)

What to say:
“Run Cell 3. Now we treat the image like clay. Diffeomorphic registration can warp local regions while keeping the overall mapping well-behaved.”

What students should notice:

  • Local alignment improves (halos reduce further).
  • The deformation grid/field shows where space was “pulled” and “pushed.”

4) Brain normalization (clinical standard: mapping to MNI152)

What to say:
“Now we apply the same idea to a human brain—mapping an individual to the MNI152 template (the ‘universal average’). This can take ~60 seconds because it’s doing many computations.”

What students should notice (typical progression):

  • Raw: strong red/green halos (misalignment).
  • Linear: brain is in roughly the right location/size, but internal anatomy is still blurry/misaligned.
  • Nonlinear (diffeomorphic): structures overlap much better; colors move toward yellow (red + green = yellow), indicating stronger agreement between images.

Troubleshooting (quick)

  • Kernel not found: Re-run Phase 1B, then refresh JupyterLab.
  • Permission/path issues: Confirm you opened the notebook from /blue/psy4930/$USER/ and not from a read-only shared folder.
  • Out of memory/time: Relaunch JupyterLab with the requested resources (or higher if instructed).

Clone this wiki locally