@brainpilot/skills 0.0.6 → 0.0.8

package/skills/13_Visualization/brain-visualization/scripts/connectome_reference.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import nibabel as nib
+import numpy as np
+from nilearn import plotting
+
+
+def load_connectivity_matrix(matrix_path: Path) -> np.ndarray:
+    if matrix_path.suffix.lower() == ".npy":
+        matrix = np.load(matrix_path)
+    else:
+        matrix = np.loadtxt(matrix_path, delimiter=",")
+
+    if matrix.ndim != 2 or matrix.shape[0] != matrix.shape[1]:
+        raise ValueError("Connectivity matrix must be square.")
+
+    matrix = (matrix + matrix.T) / 2.0
+    np.fill_diagonal(matrix, 0)
+    return matrix
+
+
+def keep_strongest_connections(matrix: np.ndarray, top_k: int) -> np.ndarray:
+    if top_k <= 0:
+        return matrix
+
+    upper_indices = np.triu_indices_from(matrix, k=1)
+    weights = matrix[upper_indices]
+    positive = weights[weights > 0]
+    if len(positive) == 0 or top_k >= len(positive):
+        return matrix
+
+    threshold = np.partition(positive, -top_k)[-top_k]
+    filtered = matrix.copy()
+    filtered[filtered < threshold] = 0
+    return filtered
+
+
+def plot_connectome_reference(
+    atlas_path: Path,
+    template_path: Path,
+    matrix_path: Path,
+    output_path: Path,
+    top_k: int,
+    node_size: int,
+    brain_opacity: float,
+) -> None:
+    atlas_img = nib.load(str(atlas_path))
+    coords = plotting.find_parcellation_cut_coords(atlas_img)
+
+    matrix = load_connectivity_matrix(matrix_path)
+    matrix = keep_strongest_connections(matrix, top_k)
+
+    colors = ["#1f77b4", "#ff7f0e", "#2ca02c", "#d62728"]
+    node_colors = [colors[index % len(colors)] for index in range(len(coords))]
+
+    fig, ax = plt.subplots(figsize=(12, 10), facecolor="white")
+    plotting.plot_glass_brain(
+        str(template_path),
+        display_mode="ortho",
+        axes=ax,
+        alpha=brain_opacity,
+    )
+    plotting.plot_connectome(
+        matrix,
+        coords,
+        node_color=node_colors,
+        node_size=node_size,
+        axes=ax,
+        colorbar=True,
+        edge_threshold=None,
+        edge_vmin=-1,
+        edge_vmax=1,
+    )
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    plt.savefig(output_path, dpi=300, bbox_inches="tight")
+    plt.close(fig)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference script for 3D brain connectome plotting.")
+    parser.add_argument("--atlas", type=Path, required=True, help="Atlas NIfTI used to derive parcel coordinates.")
+    parser.add_argument("--template", type=Path, required=True, help="Template T1 image for background display.")
+    parser.add_argument("--matrix", type=Path, required=True, help="Connectivity matrix in .npy or .csv format.")
+    parser.add_argument("--output", type=Path, required=True, help="Output PNG path.")
+    parser.add_argument("--top-k", type=int, default=8, help="Number of strongest positive connections to keep.")
+    parser.add_argument("--node-size", type=int, default=100, help="Node marker size.")
+    parser.add_argument("--brain-opacity", type=float, default=0.18, help="Background template opacity.")
+    args = parser.parse_args()
+
+    plot_connectome_reference(
+        atlas_path=args.atlas,
+        template_path=args.template,
+        matrix_path=args.matrix,
+        output_path=args.output,
+        top_k=args.top_k,
+        node_size=args.node_size,
+        brain_opacity=args.brain_opacity,
+    )
+    print(f"Saved connectome figure to: {args.output}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/13_Visualization/brain-visualization/scripts/freesurfer_ply_reference.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel.freesurfer as fs
+import numpy as np
+
+
+def export_colored_ply(surf_path: Path, annot_path: Path, output_path: Path) -> None:
+    coords, faces = fs.read_geometry(str(surf_path))
+    labels, color_table, _ = fs.read_annot(str(annot_path))
+
+    vertex_colors = np.zeros((len(coords), 3), dtype=np.uint8)
+    for index, label in enumerate(labels):
+        if 0 <= label < len(color_table):
+            vertex_colors[index] = color_table[label, :3]
+        else:
+            vertex_colors[index] = [128, 128, 128]
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with output_path.open("w", encoding="utf-8") as handle:
+        handle.write("ply\n")
+        handle.write("format ascii 1.0\n")
+        handle.write(f"element vertex {len(coords)}\n")
+        handle.write("property float x\n")
+        handle.write("property float y\n")
+        handle.write("property float z\n")
+        handle.write("property uchar red\n")
+        handle.write("property uchar green\n")
+        handle.write("property uchar blue\n")
+        handle.write(f"element face {len(faces)}\n")
+        handle.write("property list uchar int vertex_indices\n")
+        handle.write("end_header\n")
+
+        for vertex, color in zip(coords, vertex_colors):
+            handle.write(f"{vertex[0]:.6f} {vertex[1]:.6f} {vertex[2]:.6f} {color[0]} {color[1]} {color[2]}\n")
+        for face in faces:
+            handle.write(f"3 {face[0]} {face[1]} {face[2]}\n")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference script for exporting FreeSurfer surfaces to colored PLY.")
+    parser.add_argument("--surf", type=Path, required=True, help="FreeSurfer surface file such as lh.pial or rh.pial.")
+    parser.add_argument("--annot", type=Path, required=True, help="FreeSurfer annotation file such as lh.aparc.annot.")
+    parser.add_argument("--output", type=Path, required=True, help="Output PLY path.")
+    args = parser.parse_args()
+
+    export_colored_ply(args.surf, args.annot, args.output)
+    print(f"Saved colored PLY to: {args.output}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/13_Visualization/brain-visualization/scripts/zalff_summary_reference.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+import pandas as pd
+from nilearn import image
+from nilearn.maskers import NiftiLabelsMasker
+
+
+def load_labels(label_path: Path) -> list[str]:
+    with label_path.open("r", encoding="utf-8", errors="ignore") as handle:
+        return [line.strip() for line in handle if line.strip()]
+
+
+def get_roi_center(atlas_data: np.ndarray, affine: np.ndarray, roi_id: int) -> list[float]:
+    coords = np.argwhere(atlas_data == roi_id)
+    if len(coords) == 0:
+        return [0.0, 0.0, 0.0]
+    center = np.median(coords, axis=0)
+    xyz = nib.affines.apply_affine(affine, center)
+    return np.round(xyz, 2).tolist()
+
+
+def summarize_zalff(
+    bold_path: Path,
+    atlas_path: Path,
+    label_path: Path,
+    mask_path: Path,
+    output_dir: Path,
+    tr: float,
+    top_n: int,
+) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    bold_img = nib.load(str(bold_path))
+    mni_img = image.resample_to_img(
+        bold_img,
+        str(mask_path),
+        interpolation="linear",
+        force_resample=True,
+    )
+
+    cleaned = image.clean_img(
+        mni_img,
+        detrend=True,
+        standardize=False,
+        low_pass=0.1,
+        high_pass=0.01,
+        t_r=tr,
+        mask_img=str(mask_path),
+    )
+
+    alff = image.math_img("np.std(img, axis=3)", img=cleaned)
+    mask_data = nib.load(str(mask_path)).get_fdata() > 0.5
+    alff_values = alff.get_fdata()[mask_data]
+    mu = float(np.mean(alff_values))
+    sigma = float(np.std(alff_values))
+    if sigma == 0:
+        raise ValueError("zALFF normalization failed because the standard deviation is zero.")
+
+    zalff = image.math_img(f"(img - {mu}) / {sigma}", img=alff)
+
+    labels = load_labels(label_path)
+    masker = NiftiLabelsMasker(labels_img=str(atlas_path), standardize=False)
+    roi_values = masker.fit_transform(zalff)[0]
+
+    summary = pd.DataFrame(
+        {
+            "Region_ID": range(1, len(roi_values) + 1),
+            "Region_Name": labels[: len(roi_values)],
+            "zALFF": roi_values,
+        }
+    ).sort_values(by="zALFF", ascending=False, ignore_index=True)
+
+    atlas_img = nib.load(str(atlas_path))
+    atlas_data = atlas_img.get_fdata()
+    affine = atlas_img.affine
+    coordinates = [get_roi_center(atlas_data, affine, int(region_id)) for region_id in summary["Region_ID"]]
+    summary[["MNI_X", "MNI_Y", "MNI_Z"]] = pd.DataFrame(coordinates, index=summary.index)
+
+    top_table = summary.head(top_n)
+    top_table.to_csv(output_dir / "TOP_active_regions.csv", index=False)
+    top_table[["Region_Name", "MNI_X", "MNI_Y", "MNI_Z", "zALFF"]].to_csv(
+        output_dir / "top_coordinates.csv", index=False
+    )
+    summary.to_csv(output_dir / "all_brain_regions_activity.csv", index=False)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference script for atlas-based zALFF regional summaries.")
+    parser.add_argument("--bold", type=Path, required=True, help="Input 4D BOLD NIfTI image.")
+    parser.add_argument("--atlas", type=Path, required=True, help="Atlas NIfTI for parcel summaries.")
+    parser.add_argument("--labels", type=Path, required=True, help="Atlas label text file.")
+    parser.add_argument("--mask", type=Path, required=True, help="MNI or analysis mask used for resampling and cleanup.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for CSV outputs.")
+    parser.add_argument("--tr", type=float, default=1.0, help="Repetition time in seconds.")
+    parser.add_argument("--top-n", type=int, default=10, help="Number of top regions to export.")
+    args = parser.parse_args()
+
+    summarize_zalff(
+        bold_path=args.bold,
+        atlas_path=args.atlas,
+        label_path=args.labels,
+        mask_path=args.mask,
+        output_dir=args.output_dir,
+        tr=args.tr,
+        top_n=args.top_n,
+    )
+    print(f"Saved zALFF summaries to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/13_Visualization/ethoclaw-paper-figure-layout/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: ethoclaw-paper-figure-layout
+description: "Auto-layout folders of result images into a paper-like PDF (LaTeX) with captions derived from filenames and optional heatmap+colorbar grouping. Use when the user says: use images in this folder to help with layout/generate paper figures/arrange figures into PDF by folder grouping; or when there are many PNG/JPG figures that need consistent captions and pagination."
+---
+
+# Paper Figure Layout
+
+Auto-generate a Nature-Communications-ish **compact multi-panel figure PDF** from a directory of images.
+
+## What it does
+
+### Default (recommended): compact multi-panel
+
+- **Compact, figure-like layout** (not one-page-per-image)
+- **Subpanel letters** `a, b, c…` aligned in reading order
+- **Figure title above panels** (`Fig. X | Title`)
+- **Per-panel descriptions below** ("a …; b …; c …")
+- **Sensible defaults**: if the user doesn’t specify, pick **1 representative image per type**
+  - "type" = (nested) subfolder under the input root, e.g. `heatmap_velocity/`, `radar/group_means/`
+
+### Legacy: foldered dump
+
+- **Groups by subfolder**: each subfolder becomes a section.
+- **Captions from filenames**: underscores/dashes become spaces.
+- **Stable pagination**: uses one-column LaTeX blocks (no fragile two-column floats).
+
+## Quick start
+
+### Compact multi-panel (default)
+
+```bash
+python3 scripts/layout_results_foldered.py \
+  --input "/path/to/2_results" \
+  --output "/path/to/out.pdf" \
+  --title "Results"
+```
+
+Defaults (can override):
+- `--mode compact`
+- `--max-per-type 1`
+- `--cols 2`
+- `--panels-per-figure 6`
+
+Default representative logic:
+- `--max-per-type 1` means: keep **1 representative per inferred subtype**, not just 1 file for the whole folder.
+- Example: if a folder contains `x-Axis`, `y-Axis`, `z-Axis`, the default compact layout should keep all 3 because they are three subtypes of the same figure family.
+
+Useful override:
+- `--max-per-type 0` → include **all images** from each type/folder instead of representative selection.
+
+Special handling:
+- If a folder contains `colorBar` / `color_bar` plus heatmaps, the layout bundles them into one panel:
+  - up to 3 heatmaps + 1 shared colorbar side-by-side
+  - the colorbar is rendered narrow instead of occupying a full panel by itself
+
+### Legacy foldered
+
+```bash
+python3 scripts/layout_results_foldered.py \
+  --input "/path/to/2_results" \
+  --output "/path/to/out.pdf" \
+  --title "Results" \
+  --mode foldered
+```
+
+## Outputs
+
+- A single PDF at `--output`.
+
+## Notes
+
+- The TypeTex LaTeX compiler environment often defaults to `xelatex` via latexmk, but `xelatex` may be missing.
+  The script supplies a `.latexmkrc` that forces `pdflatex`.
+
+## Resources
+
+- `scripts/layout_results_foldered.py` — the generator.
+- `assets/naturecomm_figures.tex` — the Nature-Communications-ish preamble used by the generator.

package/skills/13_Visualization/ethoclaw-paper-figure-layout/assets/naturecomm_figures.tex

@@ -0,0 +1,74 @@
+% naturecomm_figures.tex
+% A Nature Communications–style 2-column LaTeX template tuned for figure-heavy docs.
+% Reference PDF: /home/max/Downloads/demo.pdf (Nature Communications | (2021)12:2784 | doi:10.1038/s41467-021-22970-y)
+%
+% NOTE: The TypeTex LaTeX compiler in this environment does NOT have xelatex.
+% Keep this template pdfLaTeX-compatible (no fontspec).
+%
+% Traits emulated:
+% - 2-column layout, ~6mm column gap
+% - Grey running header line with journal/doi/url and page number
+% - Figures centered, captions below, small caption text, ragged-right
+% - Supports single-column figures and wide figures (figure*)
+
+\documentclass[9pt,twocolumn]{article}
+
+% demo.pdf page size is 210 x 276 mm (A4 width, shorter height)
+\usepackage[
+  paperwidth=210mm,
+  paperheight=276mm,
+  top=16mm,bottom=16mm,left=16.5mm,right=16.5mm
+]{geometry}
+
+\setlength{\columnsep}{6mm}
+
+\usepackage{graphicx}
+\usepackage{xcolor}
+\usepackage{caption}
+\usepackage{subcaption}
+\usepackage{fancyhdr}
+\usepackage{hyperref}
+
+% --- Running header ---
+\pagestyle{fancy}
+\fancyhf{}
+\renewcommand{\headrulewidth}{0.3pt}
+\renewcommand{\headrule}{\hbox to\headwidth{\color{black!25}\leaders\hrule height \headrulewidth\hfill}}
+
+% Customize these per document
+\newcommand{\NCJournal}{NATURE COMMUNICATIONS}
+\newcommand{\NCYear}{2021}
+\newcommand{\NCVol}{12}
+\newcommand{\NCArticle}{2784}
+\newcommand{\NCDOI}{https://doi.org/10.1038/s41467-021-22970-y}
+\newcommand{\NCURL}{www.nature.com/naturecommunications}
+
+\lhead{\color{black!55}\fontsize{8}{9}\selectfont
+\NCJournal\ | (\NCYear)\NCVol:\NCArticle\ | \href{\NCDOI}{\NCDOI}\ | \NCURL}
+\rhead{\color{black!55}\fontsize{8}{9}\selectfont \thepage}
+
+% --- Figure caption style ("Fig. 1" bold) ---
+\renewcommand{\figurename}{Fig.}
+\captionsetup[figure]{
+  font=small,
+  labelfont=bf,
+  labelsep=space,
+  justification=raggedright,
+  singlelinecheck=false,
+  skip=2mm
+}
+
+% Float spacing (tune to taste)
+\setlength{\textfloatsep}{6mm}
+\setlength{\intextsep}{6mm}
+\setlength{\floatsep}{5mm}
+\setlength{\dbltextfloatsep}{6mm}
+\setlength{\dblfloatsep}{5mm}
+\usepackage{titlesec}
+\titlespacing*{\section}{0pt}{1.0ex}{0.8ex}
+\titlespacing*{\subsection}{0pt}{0.8ex}{0.6ex}
+
+% ---- Document starts here ----
+% \begin{document}
+% ...
+% \end{document}