@brainpilot/skills 0.0.6 → 0.0.8

package/skills/06_fMRI_Neuroimaging/ucla-cnp-skill/scripts/extract_ucla_cnp_phenotype.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Extract and merge UCLA CNP phenotype data.
+
+Reads UCLA CNP phenotype files (diagnosis, cognitive battery, behavioral)
+and produces a merged phenotype table aligned with imaging subject list.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+COLUMN_MAP = {
+    "subject_id": ["subject", "Subject", "participant_id", "SubID"],
+    "age": ["age", "Age"],
+    "sex": ["sex", "Sex", "Gender"],
+    "race": ["race", "Race"],
+    "ethnicity": ["ethnicity", "Ethnicity"],
+    "handedness": ["handedness", "Handedness"],
+    "diagnosis": ["diagnosis", "Diagnosis", "Group", "DX"],
+    "diagnosis_detail": ["diagnosis_detail", "Diagnosis_Detail"],
+    # Cognitive battery
+    "digit_span_fwd": ["DigitSpan_Forward", "digit_span_fwd"],
+    "digit_span_bwd": ["DigitSpan_Backward", "digit_span_bwd"],
+    "trail_a": ["TrailA", "trail_a"],
+    "trail_b": ["TrailB", "trail_b"],
+    "cpt_dprime": ["CPT_dprime", "cpt_dprime"],
+    "lns": ["LNS", "lns"],
+    # Task performance
+    "stopsignal_srt": ["StopSignal_SRT", "stopsignal_srt"],
+    "stopsignal_ssrt": ["StopSignal_SSRT", "stopsignal_ssrt"],
+    "spatialwm_accuracy": ["SpatialWM_Acc", "spatialwm_accuracy"],
+    "facememory_accuracy": ["FaceMem_Acc", "facememory_accuracy"],
+    # Clinical
+    "bdi": ["BDI", "bdi"],
+    "bai": ["BAI", "bai"],
+    "panss_positive": ["PANSS_Pos", "panss_positive"],
+    "panss_negative": ["PANSS_Neg", "panss_negative"],
+    "panss_general": ["PANSS_Gen", "panss_general"],
+    "ymrs": ["YMRS", "ymrs"],
+}
+
+
+def load_csv(path: Path) -> List[Dict[str, str]]:
+    delimiter = "\t" if path.suffix == ".tsv" else ","
+    with open(path, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f, delimiter=delimiter)
+        return list(reader)
+
+
+def find_column(row: Dict[str, str], candidates: List[str]) -> Optional[str]:
+    for col in candidates:
+        if col in row:
+            return col
+    return None
+
+
+def extract_phenotype(
+    phenotype_files: List[Path],
+    imaging_ids: Optional[List[str]] = None,
+    columns: Optional[List[str]] = None,
+) -> List[Dict[str, str]]:
+    all_data = []
+    for fpath in phenotype_files:
+        rows = load_csv(fpath)
+        all_data.extend(rows)
+
+    if not all_data:
+        return []
+
+    target_columns = columns if columns else list(COLUMN_MAP.keys())
+    merged = {}
+
+    for row in all_data:
+        subj_col = find_column(row, COLUMN_MAP["subject_id"])
+        if subj_col is None:
+            continue
+        subj_id = row[subj_col].strip()
+        if not subj_id:
+            continue
+
+        if subj_id not in merged:
+            merged[subj_id] = {"subject_id": subj_id}
+
+        for target_col in target_columns:
+            if target_col == "subject_id":
+                continue
+            if target_col in merged[subj_id] and merged[subj_id][target_col]:
+                continue
+            candidates = COLUMN_MAP.get(target_col, [target_col])
+            src_col = find_column(row, candidates)
+            if src_col and row.get(src_col, "").strip():
+                merged[subj_id][target_col] = row[src_col].strip()
+
+    result = list(merged.values())
+    if imaging_ids:
+        imaging_set = set(imaging_ids)
+        result = [r for r in result if r["subject_id"] in imaging_set]
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Extract UCLA CNP phenotype data.")
+    parser.add_argument("--phenotype-files", required=True, nargs="+")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--imaging-ids")
+    parser.add_argument("--columns")
+    args = parser.parse_args()
+
+    phenotype_files = [Path(f).resolve() for f in args.phenotype_files]
+    for f in phenotype_files:
+        if not f.exists():
+            print(f"File not found: {f}", file=sys.stderr)
+            return 1
+
+    imaging_ids = None
+    if args.imaging_ids:
+        id_file = Path(args.imaging_ids).resolve()
+        if id_file.exists():
+            imaging_ids = [l.strip() for l in id_file.read_text().splitlines() if l.strip()]
+
+    columns = None
+    if args.columns:
+        columns = [c.strip() for c in args.columns.split(",")]
+
+    merged = extract_phenotype(phenotype_files, imaging_ids, columns)
+    if not merged:
+        print("[ERROR] No phenotype data extracted.", file=sys.stderr)
+        return 1
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    fieldnames = list(merged[0].keys())
+    with open(output_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(merged)
+
+    diag_groups = set(r.get("diagnosis", "") for r in merged if r.get("diagnosis"))
+    print(f"Phenotype: {len(merged)} subjects, {len(fieldnames)} columns, {len(diag_groups)} groups -> {output_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/ucla-cnp-skill/scripts/ucla_cnp_qc_summary.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Generate per-subject QC summaries for UCLA CNP processing.
+
+Multi-disorder: tracks diagnostic group and applies appropriate QC criteria.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+
+def load_confounds(confounds_path: Path) -> Dict[str, float]:
+    metrics = {"fd_mean": float("nan"), "fd_max": float("nan")}
+    try:
+        import pandas as pd
+        df = pd.read_csv(confounds_path, sep="\t")
+        if "framewise_displacement" in df.columns:
+            fd = df["framewise_displacement"].dropna()
+            metrics["fd_mean"] = float(fd.mean())
+            metrics["fd_max"] = float(fd.max())
+    except Exception:
+        pass
+    return metrics
+
+
+def check_exclusion(metrics: Dict[str, float], fd_threshold: float = 0.3) -> List[str]:
+    reasons = []
+    if not (metrics["fd_mean"] != metrics["fd_mean"]):
+        if metrics["fd_mean"] > fd_threshold:
+            reasons.append(f"FD mean {metrics['fd_mean']:.3f} > {fd_threshold}")
+    return reasons
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate QC summaries for UCLA CNP processing.")
+    parser.add_argument("--fmriprep-dir", help="Path to fMRIPrep output directory")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--exclude-output")
+    parser.add_argument("--fd-threshold", type=float, default=0.3)
+    parser.add_argument("--diagnosis-file", help="CSV with subject diagnosis info")
+    args = parser.parse_args()
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    diagnosis_map = {}
+    if args.diagnosis_file:
+        diag_path = Path(args.diagnosis_file).resolve()
+        if diag_path.exists():
+            with open(diag_path, "r", encoding="utf-8") as f:
+                reader = csv.DictReader(f)
+                for row in reader:
+                    subj = row.get("subject_id") or row.get("Subject", "")
+                    diag = row.get("diagnosis") or row.get("Diagnosis") or row.get("Group", "")
+                    if subj and diag:
+                        diagnosis_map[subj] = diag
+
+    subjects = set()
+    if args.fmriprep_dir:
+        fmriprep_dir = Path(args.fmriprep_dir).resolve()
+        if fmriprep_dir.exists():
+            for d in fmriprep_dir.glob("sub-*"):
+                if d.is_dir():
+                    subjects.add(d.name)
+
+    if not subjects:
+        print("[WARN] No subjects found.", file=sys.stderr)
+        return 1
+
+    results = []
+    excluded = []
+    for subj in sorted(subjects):
+        metrics = {"subject_id": subj}
+        if diagnosis_map:
+            metrics["diagnosis"] = diagnosis_map.get(subj, "unknown")
+
+        if args.fmriprep_dir:
+            confounds_files = list(Path(args.fmriprep_dir).glob(f"{subj}/func/*_desc-confounds_timeseries.tsv"))
+            if confounds_files:
+                metrics.update(load_confounds(confounds_files[0]))
+
+        exclusion_reasons = check_exclusion(metrics, args.fd_threshold)
+        metrics["excluded"] = len(exclusion_reasons) > 0
+        metrics["exclusion_reasons"] = "; ".join(exclusion_reasons)
+
+        results.append(metrics)
+        if exclusion_reasons:
+            excluded.append({"subject_id": subj, "reasons": "; ".join(exclusion_reasons)})
+
+    if results:
+        fieldnames = list(results[0].keys())
+        with open(output_path, "w", newline="", encoding="utf-8") as f:
+            writer = csv.DictWriter(f, fieldnames=fieldnames)
+            writer.writeheader()
+            writer.writerows(results)
+        print(f"QC: {len(results)} subjects, {len(excluded)} excluded -> {output_path}")
+
+    if args.exclude_output and excluded:
+        exclude_path = Path(args.exclude_output).resolve()
+        exclude_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(exclude_path, "w", newline="", encoding="utf-8") as f:
+            writer = csv.DictWriter(f, fieldnames=["subject_id", "reasons"])
+            writer.writeheader()
+            writer.writerows(excluded)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/ucla-cnp-skill/scripts/validate_ucla_cnp.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Validate UCLA CNP BIDS structure and generate compliance report.
+
+Checks directory structure, modality completeness, and task paradigm presence.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+EXPECTED_TASKS = ["stopsignal", "spatialwm", "facememory", "barts", "taskswitch"]
+
+
+def validate_subject(subject_dir: Path) -> Dict[str, any]:
+    report = {
+        "subject": subject_dir.name,
+        "anat_complete": False,
+        "task_fMRI_present": False,
+        "dwi_present": False,
+        "n_task_runs": 0,
+        "tasks_found": [],
+        "missing_files": [],
+        "warnings": [],
+    }
+
+    anat_dir = subject_dir / "anat"
+    if anat_dir.exists():
+        t1w_files = list(anat_dir.glob("*_T1w.nii.gz"))
+        report["anat_complete"] = len(t1w_files) > 0
+        if not t1w_files:
+            report["missing_files"].append("anat/*_T1w.nii.gz")
+    else:
+        report["missing_files"].append("anat/")
+
+    func_dir = subject_dir / "func"
+    if func_dir.exists():
+        bold_files = list(func_dir.glob("*_bold.nii.gz"))
+        report["n_task_runs"] = len(bold_files)
+
+        tasks_found = set()
+        for f in bold_files:
+            name = f.name
+            for task in EXPECTED_TASKS:
+                if f"task-{task}" in name:
+                    tasks_found.add(task)
+        report["tasks_found"] = sorted(tasks_found)
+        report["task_fMRI_present"] = len(tasks_found) > 0
+    else:
+        report["missing_files"].append("func/")
+
+    dwi_dir = subject_dir / "dwi"
+    if dwi_dir.exists():
+        dwi_files = list(dwi_dir.glob("*_dwi.nii.gz"))
+        report["dwi_present"] = len(dwi_files) > 0
+    else:
+        report["warnings"].append("No dwi directory")
+
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate UCLA CNP BIDS structure.")
+    parser.add_argument("--input", required=True)
+    parser.add_argument("--output", required=True)
+    args = parser.parse_args()
+
+    input_dir = Path(args.input).resolve()
+    if not input_dir.exists():
+        print(f"Input directory not found: {input_dir}", file=sys.stderr)
+        return 1
+
+    subjects = sorted([d for d in input_dir.glob("sub-*") if d.is_dir()])
+    print(f"Found {len(subjects)} subjects in {input_dir}")
+
+    if not subjects:
+        print("[ERROR] No subjects found.", file=sys.stderr)
+        return 1
+
+    results = []
+    for sub_dir in subjects:
+        report = validate_subject(sub_dir)
+        results.append(report)
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    fieldnames = [
+        "subject", "anat_complete", "task_fMRI_present", "dwi_present",
+        "n_task_runs", "tasks_found", "missing_files", "warnings",
+    ]
+    with open(output_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        for r in results:
+            r["tasks_found"] = "; ".join(r["tasks_found"])
+            r["missing_files"] = "; ".join(r["missing_files"])
+            r["warnings"] = "; ".join(r["warnings"])
+            writer.writerow(r)
+
+    print(f"\nValidation Summary:")
+    print(f"  Total subjects: {len(results)}")
+    print(f"  With T1w: {sum(1 for r in results if r['anat_complete'])}")
+    print(f"  With task-fMRI: {sum(1 for r in results if r['task_fMRI_present'])}")
+    print(f"  With dMRI: {sum(1 for r in results if r['dwi_present'])}")
+    print(f"  Avg task runs: {sum(r['n_task_runs'] for r in results) / max(len(results), 1):.1f}")
+    print(f"  Output: {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/ukb-skill/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: ukb-skill
+description: "Use this skill whenever the user wants to analyze already available UK Biobank data for brain-related research, including neurological outcomes, cognitive phenotypes, brain MRI derived phenotypes, survival analysis, subgroup analysis, propensity score analysis, mediation analysis, sensitivity analysis, machine learning, visualization, or manuscript-ready summaries. This skill only covers post-extraction analysis and explicitly excludes RAP access and data download guidance."
+license: MIT License (NeuroClaw custom skill – freely modifiable within the project)
+layer: subagent
+skill_type: dataset
+dependencies:
+  - nilearn-tool
+  - fsl-tool
+  - claw-shell
+---
+# UKB Skill (Dataset Layer)
+
+## Overview
+
+`ukb-skill` is the NeuroClaw **analysis-layer** skill for **brain-focused UK Biobank downstream research**.
+
+This skill is designed for users who already have local UK Biobank tables, derived phenotype tables, or neuroimaging-derived feature matrices and want to run downstream statistical or machine learning analyses.
+
+It follows the NeuroClaw hierarchical design principles:
+- This skill describes **WHAT needs to be analyzed** and **which existing skill should handle each part**.
+- It contains **no RAP download workflow** and **no cloud export instructions**.
+- It contains **no direct implementation code** and **no direct shell commands**.
+- All concrete execution should be delegated through `claw-shell` and related downstream skills.
+
+**Core workflow (never bypassed):**
+1. Confirm that the user already has accessible UK Biobank-derived local data.
+2. Identify the research target: neurological endpoint, cognitive phenotype, brain MRI phenotype, or predictive modeling task.
+3. Identify the analysis type: regression, survival analysis, subgroup analysis, propensity score analysis, mediation analysis, sensitivity analysis, machine learning, visualization, or manuscript support.
+4. Check the minimum required columns, files, and assumptions.
+5. Generate a **numbered execution plan** with outputs, delegated skills, and risks.
+6. Present the plan and wait for explicit user confirmation ("YES" / "execute" / "proceed").
+7. On confirmation, delegate all execution through `claw-shell` and the target skills.
+
+**Research use only.**
+
+---
+
+## Scope Boundaries
+
+### Included
+- Brain-related UK Biobank disease endpoint analysis using existing tables
+- Cognitive and brain-health phenotype modeling
+- Brain MRI derived phenotype association analysis
+- Survival / logistic / linear modeling on UK Biobank-derived tables
+- Sensitivity analysis, subgroup analysis, propensity score analysis, and mediation analysis
+- Machine learning on brain-related tabular or derived neuroimaging features
+- Visualization and manuscript-ready result summarization
+
+### Excluded
+- UK Biobank RAP access setup
+- UK Biobank application, governance, or approval procedures
+- Downloading demographics, proteomics, metabolomics, or raw UKB exports
+- Cloud-side field selection or export helper workflows
+- Low-level data download scripts
+
+If the user asks how to obtain or download UK Biobank data, state that this skill only supports post-extraction analysis after the data has already been exported or derived.
+
+---
+
+## Benchmark-Facing Default Mainline
+
+For benchmark-style prompts, choose the narrowest valid UK Biobank brain-analysis route first and do not widen the response into unrelated epidemiology branches.
+
+- If the task is incident neurological disease modeling:
+   - Default to `analysis-ready table -> survival endpoint check -> Cox regression -> sensitivity analysis if requested -> result summary`.
+   - Do not expand into unrelated imaging preprocessing or data download steps.
+- If the task is cross-sectional cognition or brain-phenotype association analysis:
+   - Default to `feature table -> covariate check -> linear/logistic regression -> ranked outputs -> visualization if requested`.
+   - Do not expand into unrelated survival analysis unless the prompt explicitly asks for incident-event modeling.
+- If the task is predictive modeling on brain-related UKB features:
+   - Default to `clean feature matrix -> train/validation split -> model fitting -> metrics -> interpretation`.
+   - Delegate predictive modeling to `run_models` when appropriate.
+- If required columns or files are missing:
+   - State `Missing required input` explicitly.
+   - Do not invent UKB field names, event dates, or covariates.
+- Do not introduce RAP, cloud export, or downloader guidance in benchmark mode.
+
+When multiple valid analysis routes exist, prefer one explicit mainline plus a short note about blocked optional branches.
+
+**Research use only.**
+
+---
+
+## Quick Reference (Common UKB Brain Tasks → Delegation Map)
+
+| Task | What needs to be done (high level) | Delegate to which skill | Expected outputs |
+|---|---|---|---|
+| Phenotype extraction | Extract and preprocess UKB variables with field ID mapping | `scripts/extract_ukb_phenotype.py` | Preprocessed phenotype CSV |
+| Case extraction | Extract brain-related disease cases by ICD-10/ICD-9 codes | `scripts/extract_ukb_cases.py` | Case/control CSV with prevalence stats |
+| Survival dataset | Build survival dataset with prevalent/incident separation | `scripts/build_ukb_survival.py` | Survival CSV (time, status) |
+| QC summary | Generate per-subject QC with imaging availability | `scripts/ukb_qc_summary.py` | QC summary + exclusion list |
+| Neurological survival analysis | Validate incident-event table, define endpoint, run Cox regression, summarize hazard ratios | `claw-shell` | model summaries, hazard ratio tables, survival outputs |
+| Cognitive phenotype association | Regress cognition or brain-health phenotype on exposure or imaging features | `claw-shell` | beta/OR tables, cleaned regression outputs |
+| Brain MRI phenotype association | Analyze ROI volumes, cortical thickness, WMH burden, diffusion or connectivity summaries | `claw-shell` | ranked effect tables, feature association summaries |
+| Predictive modeling on UKB brain features | Fit classification or regression models and interpret them | `run_models` | metrics, predictions, SHAP summaries, model comparisons |
+| Subgroup analysis | Test heterogeneity by sex, age band, APOE, vascular risk, or other subgroup | `claw-shell` | subgroup effect tables, interaction summaries |
+| Propensity score analysis | Estimate propensity scores, run matching or weighting, assess balance | `claw-shell` | matched/weighted dataset summaries, balance outputs |
+| Mediation analysis | Test whether a biomarker or imaging phenotype mediates a brain-related outcome | `claw-shell` | direct/indirect effect summaries, mediation tables |
+| Sensitivity analysis | Exclude early events or rows with missing covariates, then rerun the same model | `claw-shell` | sensitivity tables, robustness comparison summaries |
+| Brain-result visualization | Turn ranked brain-region or connectome outputs into figures | `brain-visualization` | PNG figures, ranked region tables, connectome plots |
+| Manuscript-ready methods/results | Convert the finished analysis into text for reports or papers | `paper-writing` | draft methods, results text, figure legends |
+
+---
+
+## Recommended Strategy (Decision Logic)
+
+- If the goal is **incident neurological disease analysis** such as dementia, stroke, or Parkinson's disease:
+   - Prefer the survival-analysis route.
+   - Confirm prevalent vs incident definition, censoring rule, and time/status columns before modeling.
+   - Best for: longitudinal UKB outcome studies.
+
+- If the goal is **cross-sectional cognition or brain-health association analysis**:
+   - Prefer linear or logistic regression on a cleaned participant-level table.
+   - Best for: baseline phenotype studies, association screens, cognition analyses.
+
+- If the goal is **brain MRI phenotype association analysis** using ROI tables, cortical thickness, WMH burden, diffusion summaries, or connectome summaries:
+   - Prefer a feature-table association route.
+   - Best for: imaging-derived phenotype studies and region-wise effect ranking.
+
+- If the goal is **predictive modeling** on UKB brain-related features:
+   - Prefer `run_models` for model fitting, model comparison, and interpretation.
+   - Best for: disease risk prediction, cognitive outcome prediction, multimodal tabular modeling.
+
+- If the goal is **effect heterogeneity or causal approximation**:
+   - Prefer subgroup, propensity score, or mediation workflows.
+   - Best for: mechanistic analyses, treatment/exposure comparison, robustness studies.
+
+- If the goal is **publication-ready figures or writing**:
+   - Prefer `brain-visualization` for figures and `paper-writing` for text output.
+   - Best for: reporting, paper drafting, slide-ready summaries.
+
+---
+
+## Minimal Input Requirements
+
+### For Survival Analysis
+- participant ID column
+- survival time or baseline and event/censoring dates
+- event indicator/status column
+- clearly defined neurological or brain-related outcome
+- covariates
+
+### For Cross-Sectional Regression
+- participant ID column
+- exposure or predictor columns
+- target phenotype column
+- covariates
+
+### For Brain Feature Modeling
+- participant ID column
+- ROI / IDP / derived feature columns
+- target phenotype or outcome
+- optional scanner, site, or confound columns
+
+If the required inputs are not present, return a concrete missing-input list instead of inventing fields.
+
+---
+
+## Brain-Relevant UKB Targets
+
+This skill is intentionally restricted to brain-related UK Biobank content. Typical targets include:
+- neurodegenerative outcomes: dementia, Alzheimer's disease, Parkinson's disease
+- cerebrovascular outcomes: stroke and vascular brain-health outcomes
+- cognition: memory, reaction time, executive function, fluid intelligence, cognitive decline
+- psychiatric or brain-health outcomes when explicitly tied to brain-focused analysis
+- imaging-derived brain phenotypes: cortical thickness, regional volume, subcortical volume, WMH burden, diffusion metrics, functional connectivity summaries
+
+If the request is mainly non-brain UK Biobank epidemiology, this skill should state that it is out of scope.
+
+---
+
+## When to Call This Skill
+
+- Any request involving UK Biobank brain-related downstream analysis on already available local data.
+- Any request involving dementia, stroke, cognition, brain MRI phenotypes, WMH burden, or brain-feature prediction in UKB.
+- Any request asking for subgroup analysis, propensity score analysis, mediation analysis, or sensitivity analysis in a brain-focused UKB setting.
+
+Do not call this skill for RAP export, field download, or raw neuroimaging preprocessing from DICOM/NIfTI.
+
+---
+
+## Complementary / Related Skills
+
+- `run_models`            -> predictive modeling and interpretation on derived UKB brain features
+- `brain-visualization`   -> convert effect tables or connectome outputs into figures
+- `paper-writing`         -> manuscript-ready methods/results writing
+- `method-design`         -> analysis design refinement for neurological UKB studies
+- `academic-research-hub` -> literature-backed design support and research grounding
+- `smri-skill`            -> raw structural MRI preprocessing before UKB-level tabular analysis
+- `fmri-skill`            -> raw functional MRI preprocessing before UKB-level tabular analysis
+- `wmh-segmentation`      -> WMH extraction before UKB-level association or prediction analysis
+- `claw-shell`            -> all concrete execution
+
+---
+
+## Important Notes & Limitations
+
+- This skill assumes that the user already has legal access to UK Biobank data and has already exported or derived the needed local analysis files.
+- This skill does not define fixed UKB field IDs because field selection differs across studies and exports.
+- This skill should not guess disease definitions, date columns, or censoring rules when they are not provided.
+- Sensitivity analysis should be framed as filtered-data reruns of the same main model, not as unrelated new pipelines.
+- If multiple candidate outcomes or feature tables exist, the skill should first ask which one is primary before execution.
+- This skill is intended for research workflows and not for clinical decision-making.
+
+---
+
+## Default Response Pattern
+
+When this skill is triggered, the response should:
+1. Restate the exact UK Biobank brain-related analysis goal.
+2. State that the skill assumes local data is already available and does not cover downloading.
+3. List the minimum required columns or files.
+4. Provide a numbered execution plan.
+5. State which NeuroClaw skills will be delegated to.
+6. Wait for confirmation before execution.
+
+---
+
+## Companion Scripts
+
+Adapted from [UKBAnalytica_v2](https://github.com/Hinna0818/UKBAnalytica_v2) (Nan He, Southern Medical University).
+
+### `scripts/extract_ukb_phenotype.py`
+
+Extract and preprocess UKB phenotype data with automatic field ID mapping.
+
+```bash
+python skills/ukb-skill/scripts/extract_ukb_phenotype.py \
+  --input ukb_raw.csv --output phenotype.csv
+
+python skills/ukb-skill/scripts/extract_ukb_phenotype.py \
+  --input ukb_raw.csv --variables sex,age,bmi,smoking,townsend --output covariates.csv
+
+python skills/ukb-skill/scripts/extract_ukb_phenotype.py --list-variables
+```
+
+Features:
+- 50+ predefined UKB field ID mappings (demographics, lifestyle, biomarkers, brain IDPs, cognition)
+- Automatic preprocessing: invalid code removal, variable-specific recoding
+- Custom variable mapping via JSON
+- Lists all available variables with `--list-variables`
+
+### `scripts/extract_ukb_cases.py`
+
+Extract brain-related disease cases using ICD-10/ICD-9 codes.
+
+```bash
+python skills/ukb-skill/scripts/extract_ukb_cases.py \
+  --input ukb_raw.csv --disease dementia --output dementia_cases.csv
+
+python skills/ukb-skill/scripts/extract_ukb_cases.py \
+  --input ukb_raw.csv --custom-icd G20 --output custom_cases.csv
+
+python skills/ukb-skill/scripts/extract_ukb_cases.py --list-diseases
+```
+
+Features:
+- 15 predefined brain-related disease definitions (dementia, Alzheimer's, stroke, Parkinson's, MS, epilepsy, depression, anxiety, schizophrenia, bipolar, brain tumour, TBI)
+- Multi-source ascertainment: ICD-10, ICD-9, Death register
+- Custom ICD-10 pattern support
+- Prevalence statistics per disease
+
+### `scripts/build_ukb_survival.py`
+
+Build survival analysis datasets with prevalent/incident case separation.
+
+```bash
+python skills/ukb-skill/scripts/build_ukb_survival.py \
+  --input ukb_raw.csv --disease dementia --output survival.csv
+
+python skills/ukb-skill/scripts/build_ukb_survival.py \
+  --input ukb_raw.csv --disease stroke --censor-date 2023-10-31 --output stroke_survival.csv
+```
+
+Features:
+- Follow-up time calculation (years from baseline)
+- Prevalent vs incident case separation
+- Censoring at death or administrative censor date
+- Compatible with Cox regression in downstream analysis
+
+### `scripts/ukb_qc_summary.py`
+
+Generate per-subject QC summaries for brain-related UKB data.
+
+```bash
+python skills/ukb-skill/scripts/ukb_qc_summary.py \
+  --input ukb_raw.csv --output qc_summary.csv
+
+python skills/ukb-skill/scripts/ukb_qc_summary.py \
+  --input ukb_raw.csv --imaging-check --age-min 45 --age-max 80 --output qc_imaging.csv
+```
+
+Features:
+- Covariate completeness check
+- Brain imaging availability (T1w, FLAIR, dMRI, rs-fMRI IDPs)
+- Age range filtering
+- Per-subject QC pass/fail flag
+
+---
+
+## Reference
+
+Companion scripts adapted from [UKBAnalytica_v2](https://github.com/Hinna0818/UKBAnalytica_v2) by Nan He (Southern Medical University). SKILL.md analysis design narrowed to brain-focused UK Biobank research.
+
+Custom NeuroClaw skill.
+
+Created At: 2026-04-20 15:47 HKT
+Last Updated At: 2026-05-06 15:12 HKT
+Author: chengwang96