@brainpilot/skills 0.0.6

package/skills/06_fMRI_Neuroimaging/neural-decoding-analysis/references/rsa-guide.md

@@ -0,0 +1,266 @@
+# RSA Analysis Guide: Step-by-Step Workflow
+
+This reference document supplements `SKILL.md` with a complete step-by-step workflow for representational similarity analysis (RSA), including RDM construction, model specification, noise ceiling computation, and visualization.
+
+## Step-by-Step RSA Workflow
+
+### Step 1: Estimate Condition-Specific Activity Patterns
+
+**For fMRI:**
+1. Run a general linear model (GLM) with one regressor per condition (beta-series or least-squares-separate approach)
+2. Each condition yields a beta-weight map across voxels in an ROI
+3. Use **least-squares-separate (LSS)** for single-trial estimates when computing trial-wise RDMs (Mumford et al., 2012)
+4. Use **least-squares-all (LSA)** when you have a small number of conditions with many trials each
+
+> **Domain judgment**: For single-trial estimation, LSS produces less biased estimates than LSA when trials are closely spaced in time, because including all regressors simultaneously leads to collinearity in the design matrix (Mumford et al., 2012).
+
+**For EEG/MEG:**
+1. Epoch data around stimulus onset; average trials within each condition
+2. Use the spatial pattern at a specific time point, or average over a time window
+3. For time-resolved RSA: compute RDM at each time point separately
+
+### Step 2: Extract Patterns for the ROI or Brain Region
+
+- **ROI approach**: Extract voxel/channel values for each condition from a predefined region
+- **Searchlight RSA**: Compute RDMs in a local sphere around each voxel (same radius considerations as decoding searchlight: **3-4 voxels** for fMRI; Kriegeskorte et al., 2006)
+- **Whole-brain RSA**: Use parcellation (e.g., Glasser atlas with 360 parcels) and compute one RDM per parcel
+
+### Step 3: Construct the Neural RDM
+
+#### Choosing a Distance Metric
+
+| Metric | Formula | Bias | Scale | Best For |
+|---|---|---|---|---|
+| **Correlation distance** | 1 - Pearson(pattern_a, pattern_b) | Positively biased by noise | 0 to 2 | Exploratory RSA; comparing pattern shape |
+| **Euclidean distance** | sqrt(sum((a - b)^2)) | Positively biased by noise | 0 to inf | When amplitude matters |
+| **Crossnobis (cross-validated Mahalanobis)** | Multiply pattern differences across independent data partitions, with multivariate noise normalization | **Unbiased** (expected value = 0 under null) | -inf to inf | **Inferential statistics; model comparison** |
+
+(Walther et al., 2016; Kriegeskorte & Diedrichsen, 2019)
+
+#### Computing the Crossnobis Distance
+
+The crossnobis estimator requires data from multiple independent partitions (e.g., fMRI runs):
+
+1. Estimate condition-specific patterns separately for each run
+2. Compute the residual covariance matrix from the GLM residuals (for noise normalization)
+3. For each pair of conditions (i, j):
+ - Compute the pattern difference (beta_i - beta_j) in each run
+ - Multiply the pattern differences from different runs (cross-validated: never multiply a run's data with itself)
+ - Apply multivariate noise normalization (whiten using the residual covariance)
+4. Average across all cross-validated run pairs
+
+> **Domain judgment**: The cross-validation step ensures the estimator is unbiased. Without it, noise in the patterns inflates all pairwise distances by a positive amount proportional to the noise variance divided by the number of voxels. This bias makes it impossible to test whether two conditions are truly distinguishable (Walther et al., 2016).
+
+#### Noise Normalization (Multivariate Whitening)
+
+- Estimate the noise covariance matrix Sigma from GLM residuals
+- Apply Sigma^(-1/2) to the pattern differences before computing distances
+- This weights informative voxels (low noise correlation) more heavily than noisy or correlated voxels
+- Improves reliability of RDMs substantially, especially for large ROIs (Walther et al., 2016)
+
+### Step 4: Construct Model RDMs
+
+Model RDMs encode your theoretical predictions about representational structure.
+
+#### Common Model RDM Types
+
+| Model Type | Construction | Example |
+|---|---|---|
+| **Categorical** | Binary: 0 for same category, 1 for different category | "Face vs. object" model: 0 within faces, 0 within objects, 1 between |
+| **Feature-based** | Continuous distances from computational features | DNN layer activations; Gabor filter responses; semantic embedding distances |
+| **Behavioral** | Distances derived from human similarity judgments | Multi-arrangement task (Kriegeskorte & Mur, 2012); pairwise similarity ratings |
+| **Hierarchical** | Graded distances reflecting taxonomic depth | 0 within species, 0.5 within class, 1 across kingdoms |
+| **Computational model** | Distances from the internal representations of a model | CNN layer RDMs; RNN hidden state RDMs; reinforcement learning value RDMs |
+
+#### Constructing Model RDMs from Theoretical Predictions
+
+1. **Define your stimulus set**: List all conditions (N conditions)
+2. **For each pair of conditions**: Assign a predicted dissimilarity value
+3. **Organize into an N x N symmetric matrix** with zeros on the diagonal
+4. **Vectorize the lower triangle**: Extract the N*(N-1)/2 unique pairwise distances
+
+> **Domain judgment**: Model RDMs should be constructed BEFORE looking at neural data. Constructing models post-hoc to match observed neural RDMs is circular (Kriegeskorte et al., 2009). Pre-register your model RDMs when possible.
+
+### Step 5: Compare Neural RDMs to Model RDMs
+
+#### Comparison Methods
+
+| Method | Use When | Formula | Source |
+|---|---|---|---|
+| **Spearman rank correlation** | Default; robust to outliers and nonlinear monotonic relationships | rho(vectorized_brain_RDM, vectorized_model_RDM) | Nili et al., 2014 |
+| **Pearson correlation** | When the linear relationship between model and brain distances is theoretically motivated | r(vectorized_brain_RDM, vectorized_model_RDM) | Kriegeskorte et al., 2008 |
+| **Kendall tau-a** | For RDMs with many tied values (e.g., binary categorical models) | tau_a(vectorized_brain_RDM, vectorized_model_RDM) | Nili et al., 2014 |
+| **Partial correlation** | When controlling for a confound model (e.g., low-level visual similarity) | partial_rho(brain, model_A \| model_B) | Kriegeskorte & Diedrichsen, 2019 |
+| **Weighted regression** | Fitting multiple models simultaneously; estimating relative contributions | beta = (X'X)^{-1} X'y on vectorized RDMs | Kriegeskorte & Diedrichsen, 2019 |
+
+#### Choosing Between Spearman and Pearson
+
+- **Spearman** (default): Does not assume linearity between model and brain distances; only assumes a monotonic relationship. More robust to the arbitrary scaling of model predictions (Nili et al., 2014)
+- **Pearson**: Appropriate when the model makes quantitative predictions about the magnitude of distances, not just their rank order
+
+### Step 6: Statistical Inference
+
+#### Permutation Test for Individual Model Significance
+
+1. Permute condition labels **of the neural data** (not the model) to generate null RDMs
+2. Recompute the correlation between each permuted neural RDM and the model RDM
+3. Repeat **10,000 times** (Nili et al., 2014)
+4. p-value = proportion of null correlations >= observed correlation
+
+> **Domain judgment**: You must permute the condition labels (rows and columns of the RDM simultaneously), NOT individual entries of the RDM. Permuting entries destroys the distance-matrix structure and produces an invalid null distribution (Nili et al., 2014).
+
+#### Noise Ceiling Computation
+
+The noise ceiling bounds the best possible model fit given between-subject variability.
+
+**Upper bound:**
+1. For each subject, compute the correlation between that subject's RDM and the group-average RDM (including that subject)
+2. Average across subjects
+
+**Lower bound (preferred -- cross-validated):**
+1. For each subject, compute the correlation between that subject's RDM and the group-average RDM **excluding** that subject
+2. Average across subjects
+
+(Nili et al., 2014)
+
+**Interpretation:**
+- A model whose fit falls within the noise ceiling explains as much representational variance as is possible given the noise in the data
+- A model below the lower bound leaves systematic, explainable variance unaccounted for
+- The gap between upper and lower bound reflects the degree of between-subject variability
+
+#### Comparing Two Models
+
+1. For each subject, compute the correlation of the brain RDM with Model A and with Model B
+2. Compute the difference (corr_A - corr_B) for each subject
+3. Test the group-level difference with a paired t-test or Wilcoxon signed-rank test
+4. Alternatively, use a bootstrap test: resample subjects and test whether the difference in model fit is consistently positive or negative (Nili et al., 2014)
+
+### Step 7: Visualize Results
+
+#### RDM Visualization
+
+- Display as a **color-coded matrix** (conditions x conditions) with an appropriate colormap (diverging for crossnobis, sequential for correlation distance)
+- Order conditions meaningfully: group by category, sort by a relevant feature dimension
+- Always include a **colorbar** with the distance metric labeled
+- For crossnobis RDMs: use a diverging colormap centered at zero (e.g., blue-white-red) to highlight that negative values are meaningful
+
+#### Multidimensional Scaling (MDS)
+
+- Apply classical (metric) MDS to the RDM to project conditions into a 2D or 3D space
+- Useful for visualizing cluster structure and gradients in the representation
+- Report the stress value or proportion of variance explained by the MDS solution
+- **Caution**: MDS is a visualization aid, not a statistical test. Do not draw inferential conclusions from MDS plots alone (Kriegeskorte et al., 2008)
+
+#### Model Comparison Bar Plots
+
+- Plot the correlation between each model RDM and the brain RDM (one bar per model)
+- Include error bars (SEM across subjects or bootstrap confidence intervals)
+- Overlay the noise ceiling as a shaded band
+- Mark significant models and significant model differences
+
+## Category-Level vs. Exemplar-Level RSA
+
+### Category-Level Analysis
+
+- Conditions represent categories (e.g., faces, houses, tools, animals)
+- Typically **4-20 categories** with multiple exemplars per category
+- RDM captures between-category representational distances
+- Appropriate for: testing categorical organization (e.g., animate vs. inanimate distinction)
+- **Limitation**: Cannot distinguish whether a region encodes the category boundary or continuous features that correlate with category membership
+
+### Exemplar-Level Analysis
+
+- Each condition is a unique stimulus (e.g., 96 individual object images)
+- RDM captures fine-grained representational geometry
+- Appropriate for: comparing neural representations to computational model layer representations (e.g., DNN layers)
+- **Requirement**: Many more conditions (typically **48-96+**); each shown multiple times
+- **Challenge**: Single-trial beta estimates are noisier; crossnobis estimator is essential to avoid bias (Walther et al., 2016)
+
+> **Domain judgment**: Category-level RSA with few categories (e.g., 4) has very few unique distances in the RDM (only 6 for 4 categories), making model comparisons statistically weak. Exemplar-level designs with many conditions provide much more statistical power for RSA because the number of unique distances grows as N*(N-1)/2 (Kriegeskorte et al., 2008).
+
+## Multi-Arrangement for Behavioral RDMs
+
+### The Method
+
+The multi-arrangement task (Kriegeskorte & Mur, 2012) efficiently measures perceived similarity among stimuli:
+
+1. Participants view all stimuli on a computer screen and arrange them by perceived similarity (drag-and-drop)
+2. Similar items are placed close together; dissimilar items far apart
+3. The procedure adaptively selects subsets of stimuli for additional arrangements to improve estimation
+4. Pairwise distances between stimulus positions are extracted and combined across arrangements
+
+### Practical Parameters
+
+- **Number of stimuli**: Works well with **12-96** stimuli (fewer than 12: too few distances; more than 96: too many items to arrange simultaneously)
+- **Number of arrangements**: Typically **10-30** per participant; the algorithm adaptively selects informative subsets
+- **Subset size per arrangement**: **6-12 stimuli** per arrangement screen (participant fatigue increases with larger subsets)
+- **Duration**: Approximately **20-60 minutes** depending on stimulus set size
+
+### When to Use Behavioral RDMs
+
+- To test whether neural representations predict perceived similarity
+- To bridge neural and behavioral levels of description (Kriegeskorte et al., 2008)
+- As a model RDM alongside computational models to test which better explains neural data
+
+## Using the RSA Toolbox (Python: rsatoolbox)
+
+### Basic Workflow
+
+```python
+import rsatoolbox
+import numpy as np
+
+# 1. Create dataset objects (one per subject/session)
+# data: n_conditions x n_channels/voxels
+# descriptors: condition labels
+dataset = rsatoolbox.data.Dataset(
+ measurements=beta_patterns, # conditions x voxels
+ obs_descriptors={'stimulus': condition_labels}
+)
+
+# 2. Compute RDM
+rdm = rsatoolbox.rdm.calc_rdm(
+ dataset,
+ method='crossnobis', # preferred for inference
+ descriptor='stimulus',
+ noise=noise_covariance # from GLM residuals
+)
+
+# 3. Define model RDMs
+model_rdm = rsatoolbox.rdm.RDMs(
+ dissimilarities=model_distances, # vectorized lower triangle
+ rdm_descriptors={'name': 'my_model'}
+)
+
+# 4. Compare
+result = rsatoolbox.rdm.compare(
+ rdm, model_rdm,
+ method='spearman' # or 'corr', 'kendall'
+)
+
+# 5. Noise ceiling
+ceiling = rsatoolbox.inference.eval_fixed(
+ model_rdm, subject_rdms,
+ method='spearman'
+)
+```
+
+### Key Function Parameters
+
+| Function | Key Parameter | Recommended Value | Rationale |
+|---|---|---|---|
+| `calc_rdm` | `method` | `'crossnobis'` | Unbiased estimator (Walther et al., 2016) |
+| `calc_rdm` | `noise` | GLM residual covariance | Multivariate noise normalization improves reliability |
+| `compare` | `method` | `'spearman'` | Robust to nonlinear monotonic transforms (Nili et al., 2014) |
+| `eval_fixed` | `method` | `'spearman'` | Consistent with comparison method |
+
+## References
+
+- Kriegeskorte, N., Goebel, R., & Bandettini, P. (2006). Information-based functional brain mapping. *PNAS*, 103(10), 3863-3868.
+- Kriegeskorte, N., Mur, M., & Bandettini, P. (2008). Representational similarity analysis. *Front. Syst. Neurosci.*, 2, 4.
+- Kriegeskorte, N., et al. (2009). Circular analysis in systems neuroscience. *Nat. Neurosci.*, 12(5), 535-540.
+- Kriegeskorte, N., & Mur, M. (2012). Inverse MDS: Inferring dissimilarity structure from multiple item arrangements. *Front. Psychol.*, 3, 245.
+- Kriegeskorte, N., & Diedrichsen, J. (2019). Peeling the onion of brain representations. *Annu. Rev. Neurosci.*, 42, 407-432.
+- Mumford, J. A., Turner, B. O., Ashby, F. G., & Poldrack, R. A. (2012). Deconvolving BOLD activation in event-related designs for multivoxel pattern classification analyses. *NeuroImage*, 59(3), 2636-2643.
+- Nili, H., et al. (2014). A toolbox for representational similarity analysis. *PLoS Comput. Biol.*, 10(4), e1003553.
+- Walther, A., et al. (2016). Reliability of dissimilarity measures for multi-voxel pattern analysis. *NeuroImage*, 137, 188-200.

package/skills/06_fMRI_Neuroimaging/pycortex-guide/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: "pycortex-guide"
+description: "Domain-validated guidance for cortical surface visualization and brain surface rendering of fMRI data using pycortex: data types (Volume, Vertex, Dataset), 2D cortical flatmaps, 3D WebGL brain viewers, volume-to-surface mapping, FreeSurfer/fMRIPrep integration, ROI management, and surface analysis. Use this skill whenever the user mentions pycortex, `import cortex`, cortical surfaces, brain flatmaps, WebGL brain viewers, cortical surface mapping, or wants to visualize neuroimaging data on the cortex, even if they don't explicitly name pycortex."
+version: "1.0.0"
+authors:
+  - "Claude (AI-assisted)"
+review_status: "ai-generated"
+---
+
+# 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
+
+| Topic | File | When to Read |
+|-------|------|--------------|
+| Data types | `references/dataset-types.md` | User creates Volume, Vertex, RGB, 2D, or Dataset objects |
+| Visualization | `references/visualization.md` | User wants flatmaps, WebGL viewers, exports, or screenshots |
+| Database & subjects | `references/database-subjects.md` | User manages subjects, surfaces, transforms, or masks |
+| Mapping & transforms | `references/mapping-transforms.md` | User maps volume↔surface, aligns data, or works with transforms |
+| FreeSurfer & fMRIPrep | `references/freesurfer-fmriprep.md` | User imports subjects from FreeSurfer or fMRIPrep |
+| Surface analysis | `references/surface-analysis.md` | User computes curvature, geodesic distance, ROIs, or distortion |
+| MNI & utilities | `references/mni-utils.md` | User transforms to/from MNI space or uses volume utilities |
+
+## Installation
+
+```bash
+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
+
+```
+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
+
+```python
+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
+
+| Class | Description | Key Args |
+|-------|-------------|----------|
+| `Volume` | Volumetric data (3D/4D) | `data, subject, xfmname, cmap, vmin, vmax` |
+| `Vertex` | Surface vertex data (1D/2D) | `data, subject, cmap, vmin, vmax` |
+| `VolumeRGB` | RGB per voxel | `red, green, blue, subject, xfmname, alpha` |
+| `VertexRGB` | RGB per vertex | `red, green, blue, subject, alpha` |
+| `Volume2D` | Two volumes, 2D colormap | `dim1, dim2, subject, xfmname, vmin, vmax, vmin2, vmax2` |
+| `Vertex2D` | Two vertex maps, 2D colormap | `dim1, dim2, subject, vmin, vmax, vmin2, vmax2` |
+| `Dataset` | Container for multiple views | `**named_dataviews` |
+
+## Key Visualization Functions
+
+| Function | Description |
+|----------|-------------|
+| `cortex.quickshow(data, ...)` | 2D flatmap → matplotlib Figure |
+| `cortex.quickflat.make_png(fname, data, ...)` | Save flatmap as PNG |
+| `cortex.quickflat.make_svg(fname, data, ...)` | Save flatmap as SVG |
+| `cortex.quickflat.make_gif(fname, volumes, ...)` | Animated GIF from volumes |
+| `cortex.webshow(data, ...)` | Interactive 3D WebGL viewer |
+| `cortex.webgl.make_static(path, data, ...)` | Static HTML 3D viewer |
+| `cortex.export.save_3d_views(vol, ...)` | Multi-angle PNG exports |
+| `cortex.export.plot_panels(vol, panels, ...)` | Multi-panel figure |
+
+## 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.

package/skills/06_fMRI_Neuroimaging/pycortex-guide/references/database-subjects.md

@@ -0,0 +1,179 @@
+# Database & Subjects Reference
+
+## Table of Contents
+1. [Database Singleton (cortex.db)](#database-singleton)
+2. [Subject Management](#subject-management)
+3. [Surfaces](#surfaces)
+4. [Transforms](#transforms)
+5. [Masks](#masks)
+6. [ROI Storage](#roi-storage)
+7. [Configuration](#configuration)
+
+## Database Singleton
+
+`cortex.db` is the singleton `Database` object providing access to all stored subjects, surfaces, transforms, and masks.
+
+```python
+import cortex
+
+# Check filestore location
+print(cortex.database.default_filestore)
+
+# List subjects
+print(dir(cortex.db))
+```
+
+### Database File Structure
+
+```
+filestore/
+└── {subject}/
+    ├── surfaces/
+    │   ├── {name}_{hemisphere}.npz    # Surface geometry files
+    │   └── ...
+    ├── transforms/
+    │   └── {xfmname}/
+    │       ├── matrices.xfm           # Affine transform
+    │       └── reference.nii.gz       # Reference volume
+    ├── rois.svg                       # ROI definitions
+    ├── overlays.svg                   # Overlay definitions
+    └── warning.txt                    # Optional subject notes
+```
+
+## Subject Management
+
+```python
+# Access subject database
+subj_db = cortex.db.get_paths("S1")
+# Returns dict with keys: 'surfs', 'xfms', 'anatomicals', etc.
+
+# SubjectDB provides attribute access
+subj = cortex.database.SubjectDB("S1")
+subj.transforms   # XfmDB object
+subj.surfaces     # SurfaceDB object
+```
+
+## Surfaces
+
+### get_surf
+
+```python
+cortex.db.get_surf(subject, type, hemisphere="both", merge=False, nudge=False)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `subject` | str | required | Subject name |
+| `type` | str | required | Surface type |
+| `hemisphere` | str | "both" | "left", "right", or "both" |
+| `merge` | bool | False | Merge hemispheres into single array |
+| `nudge` | bool | False | Nudge hemispheres apart for display |
+
+Surface types: `"fiducial"`, `"inflated"`, `"flat"`, `"pial"`, `"wm"`, `"pia"`
+
+Returns: `(pts, polys)` — vertices array `(N, 3)` and faces array `(F, 3)`.
+If `hemisphere="both"` and `merge=False`, returns `((left_pts, left_polys), (right_pts, right_polys))`.
+
+```python
+# Get both hemispheres merged
+pts, polys = cortex.db.get_surf("S1", "fiducial", merge=True)
+
+# Get left hemisphere only
+left_pts, left_polys = cortex.db.get_surf("S1", "fiducial", "left")
+
+# Get inflated surface
+pts, polys = cortex.db.get_surf("S1", "inflated", merge=True, nudge=True)
+```
+
+## Transforms
+
+### get_xfm
+
+```python
+cortex.db.get_xfm(subject, xfmname, xfmtype="coord")
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `xfmtype` | str | "coord" | Transform type: "coord", "magnet", "raw" |
+
+Returns a `Transform` object.
+
+```python
+xfm = cortex.db.get_xfm("S1", "fullhead")
+print(xfm.shape)  # Expected volume shape
+
+# Save a new transform
+xfm.save("S1", "my_new_xfm")
+```
+
+### save_xfm
+
+```python
+cortex.db.save_xfm(subject, name, xfm, xfmtype="coord", reference=None)
+```
+
+## Masks
+
+Masks define which voxels are included in analyses. Stored per subject/transform.
+
+### get_mask
+
+```python
+cortex.db.get_mask(subject, xfmname, type="thick")
+```
+
+| Type | Description |
+|------|-------------|
+| `"thick"` | Thick cortical ribbon mask (default) |
+| `"thin"` | Thin cortical ribbon mask |
+| `"nearest"` | Nearest-neighbor mask |
+
+Returns: 3D boolean array matching transform shape.
+
+```python
+mask = cortex.db.get_mask("S1", "fullhead", "thick")
+n_voxels = mask.sum()
+# Use mask with Volume
+masked_data = np.random.randn(n_voxels)
+vol = cortex.Volume(masked_data, "S1", "fullhead", mask=mask)
+```
+
+## ROI Storage
+
+ROIs are stored as SVG files in the subject directory.
+
+```python
+# Get ROI vertices
+roi_verts = cortex.db.get_overlay("S1")
+# Returns SVGOverlay object
+
+# Get specific ROI vertex indices
+from cortex.utils import get_roi_verts
+roi_dict = get_roi_verts("S1", roi="V1")  # dict: {"V1": array_of_vertex_indices}
+
+# Get all ROIs
+all_rois = get_roi_verts("S1")  # dict of all ROI names → vertex arrays
+
+# Get ROI masks for volume data
+from cortex.utils import get_roi_mask
+roi_masks = get_roi_mask("S1", "fullhead", roi="V1")
+```
+
+## Configuration
+
+```python
+import cortex
+
+# View current config
+print(cortex.options.config.get("basic", "filestore"))
+
+# Config file location
+print(cortex.options.usercfg)
+
+# Key config sections:
+# [basic] filestore = path to subject database
+# [webgl] colormaps = path to colormap files
+```
+
+Default config is at `cortex/defaults.cfg`. User overrides in `~/.config/pycortex/options.cfg`.