@brainpilot/skills 0.0.6

package/skills/06_fMRI_Neuroimaging/pycortex-guide/references/dataset-types.md

@@ -0,0 +1,208 @@
+# Dataset Types Reference
+
+## Table of Contents
+1. [Volume](#volume)
+2. [Vertex](#vertex)
+3. [VolumeRGB / VertexRGB](#volumergb--vertexrgb)
+4. [Volume2D / Vertex2D](#volume2d--vertex2d)
+5. [Dataset](#dataset)
+6. [Colors Utility](#colors-utility)
+
+## Volume
+
+Wraps 3D/4D volumetric data with subject, transform, and colormap metadata.
+
+```python
+cortex.Volume(data, subject, xfmname, mask=None, cmap=None, vmin=None, vmax=None, description="", **kwargs)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `data` | ndarray or str | 3D `(z,y,x)`, 4D `(t,z,y,x)`, 1D masked `(v,)`, 2D masked `(t,v)`, or NIfTI path |
+| `subject` | str | Subject name in `cortex.db` |
+| `xfmname` | str | Transform name in database |
+| `mask` | ndarray, optional | Binary 3D mask; auto-detected if data is 1D/2D |
+| `cmap` | str | Matplotlib colormap name |
+| `vmin/vmax` | float | Color scale bounds (default: 1st/99th percentile) |
+
+Key properties and methods:
+- `vol.volume` — returns unmasked 3D/4D array
+- `vol.linear` — True if data is masked (1D/2D)
+- `vol.movie` — True if data has time dimension
+- `vol.shape` — 3D volume shape
+- `vol.map(projection="nearest")` — convert to Vertex via surface mapping
+- `vol.save(filename)` — save to HDF5
+- `vol.save_nii(filename)` — save as NIfTI
+- `Volume.random(subject, xfmname)` — class method for random test data
+- `Volume.empty(subject, xfmname, value=0)` — class method for constant volume
+
+```python
+# From numpy array
+vol = cortex.Volume(np.random.randn(31, 100, 100), "S1", "fullhead",
+                    cmap="hot", vmin=0, vmax=3)
+
+# From NIfTI file
+vol = cortex.Volume("func.nii.gz", "S1", "fullhead")
+
+# Masked data (1D)
+mask = cortex.db.get_mask("S1", "fullhead", "thick")
+masked_data = np.random.randn(mask.sum())
+vol = cortex.Volume(masked_data, "S1", "fullhead", mask=mask)
+
+# 4D movie data
+movie_vol = cortex.Volume(np.random.randn(100, 31, 100, 100), "S1", "fullhead")
+```
+
+## Vertex
+
+Wraps surface vertex data (one value per vertex).
+
+```python
+cortex.Vertex(data, subject, cmap=None, vmin=None, vmax=None, description="", **kwargs)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `data` | ndarray | 1D `(v,)` or 2D `(t,v)` for movie |
+| `subject` | str | Subject name in `cortex.db` |
+
+Key properties and methods:
+- `vx.vertices` — data with time dim added if needed
+- `vx.left` / `vx.right` — hemisphere-specific data
+- `vx.llen` / `vx.rlen` — vertex counts per hemisphere
+- `vx.hem` — "left", "right", or "both"
+- `vx.volume(xfmname, projection="nearest")` — map back to volume (approximate)
+- `vx.map(target_subj, surface_type="fiducial")` — project to another subject
+- `vx.blend_curvature(alpha)` — blend with curvature, returns VertexRGB
+- `Vertex.random(subject)` — random test data
+- `Vertex.empty(subject, value=0)` — constant vertex data
+
+```python
+# Full brain (both hemispheres)
+n_verts = cortex.db.get_surf("S1", "fiducial", "both", merge=True, nudge=False)[0].shape[0]
+vx = cortex.Vertex(np.random.randn(n_verts), "S1", cmap="RdBu_r", vmin=-3, vmax=3)
+
+# Single hemisphere (auto-padded)
+left_pts, _ = cortex.db.get_surf("S1", "fiducial", "left")
+vx_left = cortex.Vertex(np.random.randn(left_pts.shape[0]), "S1")
+```
+
+## VolumeRGB / VertexRGB
+
+Direct RGB(A) color specification per voxel or vertex.
+
+```python
+cortex.VolumeRGB(red, green, blue, subject=None, xfmname=None, alpha=None,
+                 description="", channel1color=(255,0,0), channel2color=(0,255,0),
+                 channel3color=(0,0,255), vmin=None, vmax=None, autorange="individual")
+
+cortex.VertexRGB(red, green, blue, subject=None, alpha=None, ...)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `red/green/blue` | ndarray or Volume/Vertex | Data channels |
+| `alpha` | ndarray or Volume/Vertex, optional | Transparency channel |
+| `channel1/2/3color` | tuple(int,int,int) | RGB color for each channel |
+| `vmin/vmax` | float or tuple(3) | Per-channel or shared bounds |
+| `autorange` | str | "individual" or "shared" percentile ranging |
+
+```python
+# Three-channel RGB volume
+r = cortex.Volume(data_r, "S1", "fullhead")
+g = cortex.Volume(data_g, "S1", "fullhead")
+b = cortex.Volume(data_b, "S1", "fullhead")
+rgb = cortex.VolumeRGB(r, g, b)
+
+# With alpha transparency
+alpha = cortex.Volume(significance_map, "S1", "fullhead")
+rgb = cortex.VolumeRGB(r, g, b, alpha=alpha)
+
+# Custom channel colors
+rgb = cortex.VolumeRGB(ch1, ch2, ch3, subject="S1", xfmname="fullhead",
+                       channel1color=(255, 100, 0),
+                       channel2color=(0, 200, 100),
+                       channel3color=(100, 0, 255))
+```
+
+## Volume2D / Vertex2D
+
+Two data dimensions visualized with a 2D colormap.
+
+```python
+cortex.Volume2D(dim1, dim2, subject=None, xfmname=None, cmap=None,
+                vmin=None, vmax=None, vmin2=None, vmax2=None)
+
+cortex.Vertex2D(dim1, dim2, subject=None, cmap=None,
+                vmin=None, vmax=None, vmin2=None, vmax2=None)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `dim1/dim2` | ndarray or Volume/Vertex | Two data dimensions |
+| `vmin/vmax` | float | Bounds for dim1 |
+| `vmin2/vmax2` | float | Bounds for dim2 |
+| `cmap` | str | 2D colormap name |
+
+```python
+# Activation + significance
+activation = cortex.Volume(beta_map, "S1", "fullhead")
+significance = cortex.Volume(-np.log10(pval_map), "S1", "fullhead")
+vol2d = cortex.Volume2D(activation, significance,
+                        vmin=-5, vmax=5, vmin2=0, vmax2=5)
+cortex.quickshow(vol2d)
+```
+
+## Dataset
+
+Container for multiple named Dataview objects. Used for multi-map viewers.
+
+```python
+cortex.Dataset(**named_dataviews)
+```
+
+```python
+ds = cortex.Dataset(
+    activation=cortex.Volume(act_data, "S1", "fullhead", cmap="hot"),
+    contrast=cortex.Volume(con_data, "S1", "fullhead", cmap="RdBu_r"),
+    surface=cortex.Vertex(surf_data, "S1", cmap="viridis")
+)
+
+# Save and load
+ds.save("experiment.hdf")
+ds = cortex.load("experiment.hdf")  # alias for Dataset.from_file
+
+# Save portable (includes subject geometry)
+ds.save("portable.hdf", pack=True)
+
+# Access views
+ds["activation"]  # or ds.activation
+for name, view in ds:
+    print(name)
+
+# Append more views
+ds.append(new_map=cortex.Volume(...))
+```
+
+## Colors Utility
+
+Predefined colors for RGB visualizations:
+
+```python
+from cortex.dataset import Colors
+Colors.RoseRed     # (237, 35, 96)
+Colors.LimeGreen   # (141, 198, 63)
+Colors.SkyBlue     # (0, 176, 218)
+Colors.DodgerBlue  # (30, 144, 255)
+Colors.Red         # (255, 0, 0)
+Colors.Green       # (0, 255, 0)
+Colors.Blue        # (0, 0, 255)
+```
+
+Numpy-style arithmetic works on all data types:
+```python
+vol_sum = vol1 + vol2
+vol_diff = vol1 - vol2
+vol_scaled = vol1 * 2.0
+vol_abs = abs(vol1)
+```

package/skills/06_fMRI_Neuroimaging/pycortex-guide/references/freesurfer-fmriprep.md

@@ -0,0 +1,162 @@
+# FreeSurfer & fMRIPrep Integration Reference
+
+## Table of Contents
+1. [Import from FreeSurfer](#import-from-freesurfer)
+2. [FreeSurfer Utilities](#freesurfer-utilities)
+3. [Import from fMRIPrep](#import-from-fmriprep)
+
+## Import from FreeSurfer
+
+### import_subj
+
+Import a FreeSurfer-processed subject into the pycortex database.
+
+```python
+cortex.freesurfer.import_subj(freesurfer_subject, pycortex_subject=None, freesurfer_subject_dir=None, whitematter_surf='smoothwm')
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `freesurfer_subject` | str | required | FreeSurfer subject name |
+| `pycortex_subject` | str | None | Pycortex subject name (defaults to freesurfer_subject) |
+| `freesurfer_subject_dir` | str | None | FreeSurfer SUBJECTS_DIR (defaults to env var) |
+| `whitematter_surf` | str | 'smoothwm' | White matter surface to import |
+
+```python
+# Basic import
+cortex.freesurfer.import_subj("fsaverage")
+
+# Import with different pycortex name
+cortex.freesurfer.import_subj("sub-01", pycortex_subject="S1",
+    freesurfer_subject_dir="/path/to/freesurfer/subjects")
+```
+
+### import_flat
+
+Import flattened cortical surfaces from FreeSurfer.
+
+```python
+cortex.freesurfer.import_flat(freesurfer_subject, patch, hemis=['lh', 'rh'],
+    pycortex_subject=None, flat_type='freesurfer',
+    freesurfer_subject_dir=None)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `freesurfer_subject` | str | required | FreeSurfer subject name |
+| `patch` | str | required | Patch name (e.g., "full" for full hemisphere) |
+| `hemis` | list | ['lh','rh'] | Hemispheres to import |
+| `flat_type` | str | 'freesurfer' | Flattening method used |
+
+```python
+cortex.freesurfer.import_flat("sub-01", "full", pycortex_subject="S1")
+```
+
+## FreeSurfer Utilities
+
+### Surface Operations
+
+```python
+# Parse FreeSurfer surface file
+pts, polys = cortex.freesurfer.parse_surf("/path/to/lh.pial")
+
+# Write FreeSurfer surface
+cortex.freesurfer.write_surf("output_surf", pts, polys)
+
+# Get surface with type
+pts, polys = cortex.freesurfer.get_surf("sub-01", "lh", "pial")
+
+# Get curvature data
+curv = cortex.freesurfer.get_curv("sub-01", "lh", type="wm")
+
+# Parse curvature file
+curv_data = cortex.freesurfer.parse_curv("/path/to/lh.curv")
+```
+
+### Surface-to-Surface Projection
+
+```python
+# Project data between subjects via FreeSurfer sphere
+projected = cortex.freesurfer.mri_surf2surf(
+    data, source_subj="sub-01", target_subj="fsaverage",
+    hemi="lh")
+
+# Get projection matrix (for repeated use)
+matrix = cortex.freesurfer.get_mri_surf2surf_matrix(
+    source_subj="sub-01", hemi="lh",
+    surface_type="sphere.reg", target_subj="fsaverage")
+projected = matrix.dot(data)
+```
+
+### FreeSurfer Processing
+
+```python
+# Run autorecon
+cortex.freesurfer.autorecon("sub-01", type="all", parallel=True)
+
+# Flatten cortical surface
+cortex.freesurfer.flatten("sub-01", "lh", patch="full")
+
+# Create fiducial (mid-cortical) surface
+cortex.freesurfer.make_fiducial("sub-01")
+
+# Get ROI labels
+label_verts = cortex.freesurfer.get_label("S1", "V1", fs_subject="sub-01")
+```
+
+### File Path Helpers
+
+```python
+# Get FreeSurfer file paths
+paths = cortex.freesurfer.get_paths("sub-01", "lh", type="surf")
+# type options: "patch", "surf", "curv", "slim"
+```
+
+## Import from fMRIPrep
+
+### import_subj
+
+Import an fMRIPrep-processed subject into pycortex.
+
+```python
+cortex.fmriprep.import_subj(subject, source_dir, session=None,
+    dataset=None, sname=None, old_fmriprep=False)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `subject` | str | required | BIDS subject ID (e.g., "01") |
+| `source_dir` | str | required | Path to fMRIPrep output directory |
+| `session` | str | None | BIDS session ID |
+| `dataset` | str | None | BIDS dataset name |
+| `sname` | str | None | Pycortex subject name (default: auto-generated) |
+| `old_fmriprep` | bool | False | Use old fMRIPrep directory structure |
+
+```python
+# Import from fMRIPrep output
+cortex.fmriprep.import_subj(
+    subject="01",
+    source_dir="/path/to/fmriprep/output",
+    session="01",
+    sname="S1"
+)
+
+# After import, subject is available in cortex.db
+vol = cortex.Volume(data, "S1", "my_transform")
+```
+
+### Typical Workflow
+
+```python
+# 1. Run fMRIPrep on your BIDS dataset (outside pycortex)
+# 2. Import the subject
+cortex.fmriprep.import_subj("01", "/data/derivatives/fmriprep")
+
+# 3. Create alignment transform
+cortex.align.automatic("sub-01", "task_bold",
+    reference="/data/derivatives/fmriprep/sub-01/func/sub-01_task-rest_bold.nii.gz")
+
+# 4. Visualize
+vol = cortex.Volume("beta_map.nii.gz", "sub-01", "task_bold")
+cortex.quickshow(vol)
+```

package/skills/06_fMRI_Neuroimaging/pycortex-guide/references/mapping-transforms.md

@@ -0,0 +1,181 @@
+# Mapping & Transforms Reference
+
+## Table of Contents
+1. [Volume-to-Surface Mapping](#volume-to-surface-mapping)
+2. [Mapper Types](#mapper-types)
+3. [Transform Class](#transform-class)
+4. [Alignment](#alignment)
+
+## Volume-to-Surface Mapping
+
+### get_mapper
+
+```python
+cortex.mapper.get_mapper(subject, xfmname, type='nearest', recache=False, **kwargs)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `subject` | str | required | Subject name |
+| `xfmname` | str | required | Transform name |
+| `type` | str | 'nearest' | Mapper type (see table below) |
+| `recache` | bool | False | Force recomputation |
+
+Returns a Mapper object that can project data between volume and surface space.
+
+```python
+mapper = cortex.mapper.get_mapper("S1", "fullhead", type="trilinear")
+
+# Volume → Surface
+vertex_data = mapper(volume_data)
+
+# Surface → Volume (inverse)
+volume_data = mapper.backwards(vertex_data)
+
+# Access mask
+mask = mapper.mask
+left_mask, right_mask = mapper.hemimasks
+```
+
+### High-Level Convenience
+
+```python
+# Volume.map() method
+vol = cortex.Volume(data, "S1", "fullhead")
+vx = vol.map("nearest")  # returns Vertex
+
+# Direct function
+from cortex.mapper import vol2surf
+vertex_data = vol2surf(data, "S1", "fullhead", target_surface="native")
+```
+
+### nanproject
+
+```python
+from cortex.mapper import nanproject
+vertex_data = nanproject(volume_data_with_nans, mapper, reweigh=True)
+```
+
+Handles NaN values during projection by reweighting non-NaN contributions.
+
+## Mapper Types
+
+| Type | Class | Description |
+|------|-------|-------------|
+| `'nearest'` | PointNN | Nearest-neighbor point sampling |
+| `'trilinear'` | PointTrilin | Trilinear interpolation at surface points |
+| `'gaussian'` | PointGauss | Gaussian kernel sampling |
+| `'lanczos'` | PointLanczos | Lanczos interpolation |
+| `'const_nearest'` | ConstPatchNN | Constant-depth patch, nearest neighbor |
+| `'const_trilinear'` | ConstPatchTrilin | Constant-depth patch, trilinear |
+| `'const_lanczos'` | ConstPatchLanczos | Constant-depth patch, Lanczos |
+| `'line_nearest'` | LineNN | Line sampling (WM→pial), nearest |
+| `'line_trilinear'` | LineTrilin | Line sampling (WM→pial), trilinear |
+| `'line_lanczos'` | LineLanczos | Line sampling (WM→pial), Lanczos |
+
+Point mappers sample at a single cortical depth. Line mappers average across the cortical ribbon (white matter to pial surface). Patch mappers sample a local neighborhood.
+
+Recommended defaults:
+- Quick visualization: `'nearest'`
+- Publication quality: `'line_nearest'` or `'trilinear'`
+- Smoothest results: `'lanczos'`
+
+## Transform Class
+
+```python
+from cortex.xfm import Transform
+```
+
+### Creating Transforms
+
+```python
+# From 4x4 matrix + reference NIfTI
+xfm = Transform(np.eye(4), "reference.nii.gz")
+
+# From FSL FLIRT output
+xfm = Transform.from_fsl("flirt_matrix.mat", "func.nii.gz", "anat.nii.gz")
+
+# From FreeSurfer bbregister
+xfm = Transform.from_freesurfer("register.dat", "func.nii.gz", "S1")
+```
+
+### Using Transforms
+
+```python
+# Apply to points
+transformed_pts = xfm(pts)  # pts shape (N, 3)
+
+# Inverse
+inv_xfm = xfm.inv
+
+# Compose transforms
+combined = xfm1 * xfm2
+
+# Save to database
+xfm.save("S1", "my_transform", xfmtype="magnet")
+
+# Convert to FSL format
+xfm.to_fsl("anat.nii.gz", direction='func>anat')
+
+# Convert to FreeSurfer format
+xfm.to_freesurfer("register.dat", "S1")
+```
+
+### Transform Types
+
+| Type | Description |
+|------|-------------|
+| `"magnet"` | Scanner magnet coordinates → anatomical |
+| `"coord"` | Coordinate transform (default) |
+| `"raw"` | Raw affine matrix |
+
+## Alignment
+
+Functions for aligning functional volumes to cortical surfaces.
+
+### Manual Alignment (FreeSurfer FreeView)
+
+```python
+cortex.align.manual(subject, xfmname, output_name="register.lta",
+    wm_color="yellow", pial_color="blue", wm_surface='white',
+    noclean=False, reference=None, inspect_only=False)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `subject` | str | required | Subject name |
+| `xfmname` | str | required | Transform name to save |
+| `output_name` | str | "register.lta" | Output registration filename |
+| `wm_color` | str | "yellow" | White matter surface color in FreeView |
+| `pial_color` | str | "blue" | Pial surface color in FreeView |
+| `wm_surface` | str | "white" | White matter surface type |
+| `reference` | str | None | Path to functional volume |
+| `inspect_only` | bool | False | View alignment without editing |
+
+Opens FreeView GUI for interactive alignment. Saves result to database.
+
+### Automatic Alignment
+
+```python
+# Using FreeSurfer bbregister
+cortex.align.automatic(subject, xfmname, reference, init="coreg",
+    epi_mask=False, intermediate=None, reference_contrast="t2", noclean=False)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `subject` | str | required | Subject name |
+| `xfmname` | str | required | Name to save transform as |
+| `reference` | str | required | Path to functional volume |
+| `init` | str | "coreg" | Initialization: "coreg", "fsl", "header", "spm" |
+| `epi_mask` | bool | False | Use EPI mask during registration |
+| `reference_contrast` | str | "t2" | Reference image contrast type: "t1" or "t2" |
+| `noclean` | bool | False | Keep temporary files after alignment |
+
+```python
+# Using FSL FLIRT BBR
+cortex.align.automatic_fsl(subject, xfmname, reference="func.nii.gz")
+
+# Fine-tune existing alignment
+cortex.align.autotweak(subject, xfmname)
+```