Pycortex Guide

Pycortex Guide

Purpose

Encodes domain knowledge for using pycortex — a Python library for visualizing fMRI and volumetric neuroimaging data on cortical surfaces. Covers data creation, 2D flatmap rendering, interactive 3D WebGL viewers, volume-to-surface mapping, subject database management, FreeSurfer/fMRIPrep integration, and surface geometry analysis.

When to Use This Skill

Activate when the user:

• Wants to visualize fMRI data on cortical surfaces
• Mentions pycortex, import cortex, flatmaps, or cortical surface visualization
• Needs to create Volume, Vertex, or Dataset objects for brain data
• Wants to generate 2D flatmaps or 3D interactive brain viewers
• Needs to import FreeSurfer or fMRIPrep subjects into pycortex
• Works with volume-to-surface mapping or cortical ROIs
• Needs to align functional data to anatomical surfaces
• Wants to compute surface properties (curvature, thickness, geodesic distance)

Reference Files

Installation

bashCopy code
pip install -U setuptools wheel numpy cython
pip install -U pycortex
# With headless rendering support:
pip install -U 'pycortex[headless]'

Requirements: Python 3.10+, Linux/macOS only. Key dependencies: numpy, scipy, matplotlib, nibabel, h5py, tornado, shapely, lxml.

Overview Pipeline

Copy code
1. Import subject (FreeSurfer/fMRIPrep)  →  stored in cortex.db
2. Create data objects (Volume/Vertex)    →  wrap arrays with metadata
3. Visualize (quickflat / webgl / export) →  2D flatmaps or 3D viewers
4. Analyze surfaces (curvature, ROIs)     →  surface geometry tools

Quick Start

pythonCopy code
import cortex

# Create a random volume for demo subject "S1" with transform "fullhead"
vol = cortex.Volume.random("S1", "fullhead")

# 2D flatmap
fig = cortex.quickshow(vol, with_curvature=True, with_rois=True)
fig.savefig("flatmap.png")

# Interactive 3D viewer
cortex.webshow(vol)

# Create volume from your own data (3D numpy array)
import numpy as np
data = np.random.randn(31, 100, 100)  # must match transform shape
vol = cortex.Volume(data, "S1", "fullhead", cmap="RdBu_r", vmin=-2, vmax=2)
cortex.quickshow(vol)

# Save/load datasets
ds = cortex.Dataset(my_map=vol)
ds.save("results.hdf")
ds_loaded = cortex.load("results.hdf")

Key Data Types

Key Visualization Functions

Common Pitfalls

1. Volume data shape must match the transform dimensions in the database. Use cortex.db.get_xfm(subject, xfmname) to check expected shape.
2. Subject and transform names must exist in cortex.db before creating Volume objects. Import from FreeSurfer first.
3. cortex.quickshow is an alias for cortex.quickflat.make_figure — they are the same function.
4. Vertex data length must match total vertex count (left + right hemisphere). Single-hemisphere data is auto-padded with zeros.
5. vmin/vmax default to 1st/99th percentile of data. Always set explicitly for consistent colorbars across subjects.
6. WebGL viewer (webshow) starts a Tornado server — it blocks in scripts. Use in IPython/Jupyter or set autoclose=True.
7. The pycortex filestore path is set in cortex.options.config. Check with cortex.database.default_filestore.
8. For headless rendering (no display), install with pip install 'pycortex[headless]' and use cortex.export.save_3d_views(..., headless=True).
9. cortex.db is a singleton — all operations share the same database instance.
10. When saving datasets with pack=True, subject geometry and transforms are embedded in the HDF5 file for portability.