@brainpilot/skills 0.0.6 → 0.0.7

package/skills/06_fMRI_Neuroimaging/ukb-skill/scripts/extract_ukb_phenotype.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""Extract and preprocess UK Biobank phenotype data for brain-related analysis.
+
+Adapted from UKBAnalytica_v2 variable_preprocess.R (Nan He, Southern Medical University).
+Provides field ID mapping, automatic preprocessing, and covariate table generation.
+
+Usage:
+    python extract_ukb_phenotype.py --input ukb_raw.csv --output phenotype.csv
+    python extract_ukb_phenotype.py --input ukb_raw.csv --variables sex,age,bmi,smoking --output covariates.csv
+    python extract_ukb_phenotype.py --input ukb_raw.csv --custom-mapping mapping.json --output custom.csv
+"""
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import pandas as pd
+
+# UKB field ID -> column name mapping (adapted from UKBAnalytica_v2)
+VARIABLE_MAPPING = {
+    # Demographics
+    "sex": {"field_id": 31, "ukb_col": "p31", "description": "Sex (0=Female, 1=Male)"},
+    "age": {"field_id": 21022, "ukb_col": "p21022", "description": "Age at recruitment"},
+    "ethnicity": {"field_id": 21000, "ukb_col": "p21000_i0", "description": "Ethnic background"},
+    "birth_year": {"field_id": 34, "ukb_col": "p34", "description": "Year of birth"},
+    "assessment_centre": {"field_id": 54, "ukb_col": "p54_i0", "description": "UK Biobank assessment centre"},
+    "baseline_date": {"field_id": 53, "ukb_col": "p53_i0", "description": "Date of baseline assessment"},
+
+    # Anthropometrics
+    "bmi": {"field_id": 21001, "ukb_col": "p21001_i0", "description": "BMI (kg/m^2)"},
+    "height": {"field_id": 50, "ukb_col": "p50_i0", "description": "Standing height (cm)"},
+    "weight": {"field_id": 21002, "ukb_col": "p21002_i0", "description": "Weight (kg)"},
+    "waist": {"field_id": 48, "ukb_col": "p48_i0", "description": "Waist circumference (cm)"},
+
+    # Lifestyle
+    "smoking": {"field_id": 20116, "ukb_col": "p20116_i0", "description": "Smoking status (0=Never, 1=Previous, 2=Current)"},
+    "drinking": {"field_id": 20117, "ukb_col": "p20117_i0", "description": "Alcohol drinker status"},
+    "sleep_duration": {"field_id": 1160, "ukb_col": "p1160_i0", "description": "Sleep duration (hours/day)"},
+    "physical_activity": {"field_id": 22032, "ukb_col": "p22032_i0", "description": "Physical activity level"},
+
+    # Socioeconomic
+    "education": {"field_id": 6138, "ukb_col": "p6138_i0", "description": "Qualifications"},
+    "income": {"field_id": 738, "ukb_col": "p738_i0", "description": "Average total household income"},
+    "townsend": {"field_id": 189, "ukb_col": "p189", "description": "Townsend deprivation index"},
+
+    # Blood Pressure
+    "sbp_auto": {"field_id": 4080, "ukb_col": "p4080_i0_a0", "description": "SBP automated reading"},
+    "dbp_auto": {"field_id": 4079, "ukb_col": "p4079_i0_a0", "description": "DBP automated reading"},
+
+    # Biomarkers
+    "triglycerides": {"field_id": 30870, "ukb_col": "p30870_i0", "description": "Triglycerides (mmol/L)"},
+    "ldl": {"field_id": 30780, "ukb_col": "p30780_i0", "description": "LDL cholesterol (mmol/L)"},
+    "hdl": {"field_id": 30760, "ukb_col": "p30760_i0", "description": "HDL cholesterol (mmol/L)"},
+    "hba1c": {"field_id": 30750, "ukb_col": "p30750_i0", "description": "HbA1c (mmol/mol)"},
+    "glucose": {"field_id": 30740, "ukb_col": "p30740_i0", "description": "Glucose (mmol/L)"},
+    "crp": {"field_id": 30710, "ukb_col": "p30710_i0", "description": "C-reactive protein"},
+
+    # Brain imaging (IDPs)
+    "brain_volume": {"field_id": 25000, "ukb_col": "p25000_i0", "description": "Total brain volume (GM+WM)"},
+    "gm_volume": {"field_id": 25001, "ukb_col": "p25001_i0", "description": "Grey matter volume"},
+    "wm_volume": {"field_id": 25002, "ukb_col": "p25002_i0", "description": "White matter volume"},
+    "hippocampus_volume": {"field_id": 25003, "ukb_col": "p25003_i0", "description": "Hippocampal volume"},
+    "wmh_volume": {"field_id": 25004, "ukb_col": "p25004_i0", "description": "White matter hyperintensity volume"},
+    "ventricular_volume": {"field_id": 25005, "ukb_col": "p25005_i0", "description": "Ventricular volume"},
+
+    # Cognition
+    "fluid_intelligence": {"field_id": 20016, "ukb_col": "p20016_i0", "description": "Fluid intelligence score"},
+    "reaction_time": {"field_id": 20023, "ukb_col": "p20023_i0", "description": "Mean reaction time"},
+    "memory_pairs": {"field_id": 399, "ukb_col": "p399_i0", "description": "Numeric memory (max digits)"},
+    "trail_making_a": {"field_id": 20156, "ukb_col": "p20156_i0", "description": "Trail making test A"},
+    "trail_making_b": {"field_id": 20157, "ukb_col": "p20157_i0", "description": "Trail making test B"},
+
+    # APOE genotype
+    "apoe": {"field_id": 22616, "ukb_col": "p22616", "description": "APOE genotype"},
+
+    # Death
+    "death_date": {"field_id": 40000, "ukb_col": "p40000_i0", "description": "Date of death"},
+    "death_cause": {"field_id": 40001, "ukb_col": "p40001_i0", "description": "Primary cause of death (ICD-10)"},
+
+    # Hospital inpatient
+    "icd10_primary": {"field_id": 41202, "ukb_col": "p41202", "description": "ICD-10 primary diagnoses"},
+    "icd10_date": {"field_id": 41280, "ukb_col": "p41280", "description": "ICD-10 diagnosis dates"},
+}
+
+# UKB invalid codes (treated as missing)
+INVALID_CODES = [-1, -3, -9]
+
+
+def preprocess_variable(series: pd.Series, var_name: str, invalid_codes: List[int]) -> pd.Series:
+    """Apply variable-specific preprocessing."""
+    s = series.copy()
+
+    # Replace invalid codes with NaN
+    if s.dtype in ("int64", "float64"):
+        for code in invalid_codes:
+            s = s.replace(code, pd.NA)
+
+    # Variable-specific transformations
+    if var_name == "ethnicity":
+        # Recode: White=0, non-White=1
+        s = s.apply(lambda x: 0 if x == 1 else (1 if pd.notna(x) and x > 0 else pd.NA))
+
+    elif var_name == "education":
+        # Recode: College/University degree -> High; A levels/GCSEs -> Medium; None -> Low
+        def edu_recode(x):
+            if pd.isna(x):
+                return pd.NA
+            x = int(x)
+            if x in [1, 2, 3, 4]:  # College/University
+                return 3
+            elif x in [5, 6]:  # A levels, O levels/GCSEs
+                return 2
+            elif x in [7]:  # CSEs
+                return 1
+            else:
+                return 1
+        s = s.apply(edu_recode)
+
+    elif var_name == "smoking":
+        # 0=Never, 1=Previous, 2=Current
+        s = s.apply(lambda x: x if x in [0, 1, 2] else pd.NA)
+
+    return s
+
+
+def load_custom_mapping(path: Path) -> Dict:
+    """Load custom variable mapping from JSON file."""
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def extract_phenotype(
+    input_path: Path,
+    variables: Optional[List[str]] = None,
+    custom_mapping: Optional[Dict] = None,
+    drop_missing: bool = False,
+) -> pd.DataFrame:
+    """Extract and preprocess UKB phenotype data."""
+    df = pd.read_csv(input_path, low_memory=False)
+    print(f"Loaded {len(df)} rows, {len(df.columns)} columns")
+
+    # Merge mappings
+    mapping = dict(VARIABLE_MAPPING)
+    if custom_mapping:
+        mapping.update(custom_mapping)
+
+    # Default variables: demographics + key covariates
+    if variables is None:
+        variables = ["sex", "age", "ethnicity", "bmi", "smoking", "education", "townsend"]
+
+    # Validate
+    invalid = [v for v in variables if v not in mapping]
+    if invalid:
+        print(f"[WARN] Unknown variables: {invalid}")
+        variables = [v for v in variables if v in mapping]
+
+    # Process each variable
+    result = pd.DataFrame()
+    result["eid"] = df["eid"]
+
+    processed = []
+    for var in variables:
+        var_info = mapping[var]
+        ukb_col = var_info["ukb_col"]
+
+        # Try exact column match, then prefix match
+        if ukb_col in df.columns:
+            col = ukb_col
+        else:
+            candidates = [c for c in df.columns if c.startswith(ukb_col)]
+            col = candidates[0] if candidates else None
+
+        if col is None:
+            print(f"[WARN] Column '{ukb_col}' not found for variable '{var}', skipping")
+            continue
+
+        result[var] = preprocess_variable(df[col], var, INVALID_CODES)
+        processed.append(var)
+
+    print(f"Processed {len(processed)} variables: {processed}")
+
+    if drop_missing:
+        before = len(result)
+        result = result.dropna(subset=processed)
+        print(f"Dropped {before - len(result)} rows with missing values")
+
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Extract UKB phenotype data.")
+    parser.add_argument("--input", required=True, help="Path to UKB raw CSV")
+    parser.add_argument("--output", required=True, help="Output path for phenotype CSV")
+    parser.add_argument("--variables", help="Comma-separated variable names (default: core covariates)")
+    parser.add_argument("--custom-mapping", help="JSON file with custom variable mappings")
+    parser.add_argument("--drop-missing", action="store_true", help="Drop rows with missing values")
+    parser.add_argument("--list-variables", action="store_true", help="List available variables and exit")
+    args = parser.parse_args()
+
+    if args.list_variables:
+        print("Available variables:")
+        for name, info in VARIABLE_MAPPING.items():
+            print(f"  {name}: {info['description']} (field {info['field_id']}, col {info['ukb_col']})")
+        return 0
+
+    input_path = Path(args.input).resolve()
+    if not input_path.exists():
+        print(f"Input file not found: {input_path}", file=sys.stderr)
+        return 1
+
+    variables = None
+    if args.variables:
+        variables = [v.strip() for v in args.variables.split(",")]
+
+    custom_mapping = None
+    if args.custom_mapping:
+        custom_mapping = load_custom_mapping(Path(args.custom_mapping).resolve())
+
+    result = extract_phenotype(input_path, variables, custom_mapping, args.drop_missing)
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    result.to_csv(output_path, index=False)
+    print(f"Saved {len(result)} rows, {len(result.columns)} columns -> {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/ukb-skill/scripts/ukb_qc_summary.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Generate QC summaries for UK Biobank brain-related data.
+
+Tracks data completeness, imaging availability, and exclusion criteria.
+
+Usage:
+    python ukb_qc_summary.py --input ukb_raw.csv --output qc_summary.csv
+    python ukb_qc_summary.py --input ukb_raw.csv --imaging-check --output qc_imaging.csv
+"""
+import argparse
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+import pandas as pd
+
+
+def check_completeness(df: pd.DataFrame, required_cols: List[str]) -> Dict:
+    """Check data completeness for required columns."""
+    stats = {}
+    for col in required_cols:
+        if col in df.columns:
+            n_missing = df[col].isna().sum()
+            stats[col] = {
+                "n_present": len(df) - n_missing,
+                "n_missing": n_missing,
+                "pct_complete": (len(df) - n_missing) / len(df) * 100,
+            }
+        else:
+            stats[col] = {"n_present": 0, "n_missing": len(df), "pct_complete": 0}
+    return stats
+
+
+def check_imaging_availability(df: pd.DataFrame) -> Dict:
+    """Check brain imaging data availability."""
+    imaging_checks = {
+        "T1w": ["p25000_i0", "p25001_i0", "p25002_i0"],  # Brain volume IDPs
+        "T2_FLAIR": ["p25004_i0"],  # WMH volume
+        "dMRI": ["p25008_i0", "p25009_i0"],  # DTI IDPs
+        "rsfMRI": ["p25010_i0", "p25011_i0"],  # fMRI IDPs
+    }
+
+    results = {}
+    for modality, cols in imaging_checks.items():
+        available = [c for c in cols if c in df.columns]
+        if available:
+            # Has data if at least one imaging column is non-null
+            has_data = df[available].notna().any(axis=1).sum()
+            results[modality] = {"n_available": has_data, "pct": has_data / len(df) * 100}
+        else:
+            results[modality] = {"n_available": 0, "pct": 0}
+
+    return results
+
+
+def generate_qc(
+    df: pd.DataFrame,
+    required_cols: List[str] = None,
+    imaging_check: bool = False,
+    age_range: tuple = None,
+) -> pd.DataFrame:
+    """Generate per-subject QC summary."""
+    if required_cols is None:
+        required_cols = ["p31", "p21022", "p21001_i0"]  # sex, age, bmi
+
+    result = pd.DataFrame({"eid": df["eid"]})
+
+    # Age filtering
+    if age_range and "p21022" in df.columns:
+        age = df["p21022"]
+        result["in_age_range"] = ((age >= age_range[0]) & (age <= age_range[1])).astype(int)
+    else:
+        result["in_age_range"] = 1
+
+    # Missing data count
+    available_required = [c for c in required_cols if c in df.columns]
+    if available_required:
+        result["n_missing_covariates"] = df[available_required].isna().sum(axis=1)
+        result["complete_covariates"] = (result["n_missing_covariates"] == 0).astype(int)
+    else:
+        result["n_missing_covariates"] = 0
+        result["complete_covariates"] = 1
+
+    # Imaging availability
+    if imaging_check:
+        imaging_cols = {
+            "has_brain_volume": ["p25000_i0"],
+            "has_gm_volume": ["p25001_i0"],
+            "has_wm_volume": ["p25002_i0"],
+            "has_hippocampus": ["p25003_i0"],
+            "has_wmh": ["p25004_i0"],
+        }
+        for name, cols in imaging_cols.items():
+            available = [c for c in cols if c in df.columns]
+            if available:
+                result[name] = df[available].notna().any(axis=1).astype(int)
+            else:
+                result[name] = 0
+
+    # Overall QC pass
+    qc_pass = (result["complete_covariates"] == 1) & (result["in_age_range"] == 1)
+    result["qc_pass"] = qc_pass.astype(int)
+
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate UKB QC summary.")
+    parser.add_argument("--input", required=True, help="Path to UKB raw CSV")
+    parser.add_argument("--output", required=True, help="Output path for QC summary CSV")
+    parser.add_argument("--imaging-check", action="store_true", help="Include imaging availability check")
+    parser.add_argument("--age-min", type=float, default=None, help="Minimum age filter")
+    parser.add_argument("--age-max", type=float, default=None, help="Maximum age filter")
+    parser.add_argument("--required-cols", help="Comma-separated required column names")
+    args = parser.parse_args()
+
+    input_path = Path(args.input).resolve()
+    if not input_path.exists():
+        print(f"Input file not found: {input_path}", file=sys.stderr)
+        return 1
+
+    df = pd.read_csv(input_path, low_memory=False)
+    print(f"Loaded {len(df)} subjects")
+
+    required_cols = None
+    if args.required_cols:
+        required_cols = [c.strip() for c in args.required_cols.split(",")]
+
+    age_range = None
+    if args.age_min is not None and args.age_max is not None:
+        age_range = (args.age_min, args.age_max)
+
+    result = generate_qc(df, required_cols, args.imaging_check, age_range)
+
+    # Summary
+    n_total = len(result)
+    n_pass = result["qc_pass"].sum()
+    print(f"\nQC Summary:")
+    print(f"  Total subjects: {n_total}")
+    print(f"  QC pass: {n_pass} ({n_pass/n_total*100:.1f}%)")
+    print(f"  QC fail: {n_total - n_pass} ({(n_total-n_pass)/n_total*100:.1f}%)")
+
+    if args.imaging_check:
+        for col in ["has_brain_volume", "has_gm_volume", "has_wm_volume", "has_hippocampus", "has_wmh"]:
+            if col in result.columns:
+                n = result[col].sum()
+                print(f"  {col}: {n} ({n/n_total*100:.1f}%)")
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    result.to_csv(output_path, index=False)
+    print(f"Saved -> {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/wmh-segmentation/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: wmh-segmentation
+description: "Use this skill whenever the user wants to perform automated white matter hyperintensity (WMH) segmentation on structural MRI data using the MARS-WMH nnU-Net model. Requires one FLAIR and one T1w NIfTI image (no contrast). Triggers include: 'wmh', 'white matter hyperintensities', 'WMH segmentation', 'MARS-WMH', 'wmh-nnunet', 'segment FLAIR T1', 'white matter lesions', 'vascular WMH', 'mars wmh', or any request to run nnU-Net WMH segmentation on FLAIR+T1w pair."
+license: MIT License (NeuroClaw custom skill – freely modifiable within the project)
+layer: base
+skill_type: tool
+dependencies:
+  - claw-shell
+---
+# WMH Segmentation (MARS-WMH nnU-Net)
+
+## Overview
+MARS-WMH is the state-of-the-art, clinically-validated deep-learning tool (nnU-Net architecture) for segmenting brain white matter hyperintensities of presumed vascular origin. It takes a FLAIR image (recommended 1 mm isotropic) and a co-registered or registrable T1w image (1 mm isotropic, no contrast) and outputs a precise WMH segmentation mask in NIfTI format (returned in the original input resolution).
+
+This skill serves as the **NeuroClaw interface-layer wrapper** for the official MARS-WMH Docker container (`ghcr.io/miac-research/wmh-nnunet:latest`) and strictly follows the hierarchical design:
+
+1. Check whether Docker (with NVIDIA Container Toolkit) is installed (`docker --version` + `nvidia-smi` via `claw-shell`).
+2. If `nvidia-smi` fails → immediately print the exact NVIDIA Container Toolkit installation commands and instruct the user to run them manually before retry.
+3. If paths not provided → interactively ask the user for FLAIR and T1w full paths and confirm they exist on disk.
+4. If paths provided → verify file existence and readability.
+5. Prepare clean working directory, copy inputs, generate exact Docker pull/tag + run commands.
+6. Generate a numbered execution plan.
+7. Present the plan, estimated runtime (~5–15 min on GPU), requirements and risks → wait for explicit user confirmation (“YES” / “execute” / “proceed”).
+8. On confirmation → delegate **all** shell execution to `claw-shell`.
+9. Report completion, exact output mask location, and next steps.
+
+**Key design principle (2026 update)**: All Docker execution is routed through `claw-shell`.
+
+## Quick Reference (Common Use Cases)
+
+| Task                              | Recommended approach                                      |
+|-----------------------------------|-----------------------------------------------------------|
+| Standard WMH segmentation         | Default Docker run (nnU-Net, GPU)                         |
+| Already co-registered images      | Add `--skipRegistration` flag                             |
+| CPU-only fallback                 | Remove `--gpus all` (slow)                                |
+
+## Installation Check & Setup
+Installation of Docker is delegated to `dependency-planner`.
+
+GPU check performed before every run:
+
+- If `nvidia-smi` fails, prompt user to run:
+
+```bash
+curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
+  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
+curl -fsSL https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
+  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#' | \
+  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list > /dev/null
+sudo apt-get update
+sudo apt-get install -y nvidia-container-toolkit
+sudo nvidia-ctk runtime configure --runtime=docker
+sudo systemctl restart docker
+```
+
+**Prerequisites**:
+- `dependency-planner`
+- `claw-shell`
+- NVIDIA GPU + drivers
+- ≥8 GB VRAM
+
+## NeuroClaw recommended wrapper script
+```bash
+# WMH Segmentation Shell Commands (execute via claw-shell)
+
+# 0. GPU check
+nvidia-smi >/dev/null 2>&1 || {
+  echo "GPU not detected. Run the following commands to install NVIDIA Container Toolkit:"
+  cat << 'EOF'
+curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
+  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
+curl -fsSL https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
+  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#' | \
+  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list > /dev/null
+sudo apt-get update
+sudo apt-get install -y nvidia-container-toolkit
+sudo nvidia-ctk runtime configure --runtime=docker
+sudo systemctl restart docker
+EOF
+  exit 1
+}
+
+# 1. Pull & tag
+docker pull ghcr.io/miac-research/wmh-nnunet:latest
+docker tag ghcr.io/miac-research/wmh-nnunet:latest mars-wmh-nnunet:latest
+
+# 2. Prepare workspace (replace paths with user-provided FLAIR/T1w)
+FLAIR="/path/to/FLAIR.nii.gz"
+T1="/path/to/T1w.nii.gz"
+OUTPUT_DIR="wmh_output"
+mkdir -p "$OUTPUT_DIR"
+cp "$FLAIR" "$OUTPUT_DIR/FLAIR.nii.gz"
+cp "$T1" "$OUTPUT_DIR/T1w.nii.gz"
+
+# 3. Fix Docker data directory permission issues (common on Ubuntu)
+chmod -R 777 "$OUTPUT_DIR"
+
+# 4. Run inference
+docker run --rm --gpus all \
+  -v "$(pwd)/$OUTPUT_DIR:/data" \
+  mars-wmh-nnunet:latest \
+  --flair /data/FLAIR.nii.gz \
+  --t1 /data/T1w.nii.gz
+
+# 5. Show output mask
+ls -lh "$OUTPUT_DIR"/*.nii*
+echo "WMH segmentation mask saved in $OUTPUT_DIR"
+```
+
+## Important Notes & Limitations
+- Docker data directory permission issues are automatically fixed with `chmod -R 777` on the output directory.
+- If `docker run` fails with permission denied → run `newgrp docker` first, then retry.
+- First run pulls image (~several GB); subsequent runs are fast.
+- Input must be NIfTI; use `dcm2nii` if starting from DICOM.
+- Output mask appears in `$OUTPUT_DIR` (exact filename shown by final `ls`).
+
+## When to Call This Skill
+- User provides FLAIR + T1w and wants WMH segmentation.
+- Any mention of MARS-WMH, nnU-Net WMH, white matter lesions segmentation.
+
+## Complementary / Related Skills
+- `dcm2nii`              → convert DICOM to NIfTI input
+- `dependency-planner`   → install Docker and NVIDIA Container Toolkit
+- `claw-shell`           → safe Docker execution
+
+## Reference
+Official repo: https://github.com/miac-research/MARS-WMH  
+Docker image: `ghcr.io/miac-research/wmh-nnunet:latest`  
+Custom NeuroClaw skill.
+
+Created At: 2026-03-23  
+Last Updated At: 2026-03-26 00:29 HKT  
+Author: chengwang96

package/skills/07_Computational_Modeling/detrending/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: detrending
+description: "Use this model doc whenever the user wants to perform neuroimaging signal denoising with classical detrending methods. This is a non-deep-learning preprocessing route focused on removing low-frequency drift and linear trends from time series before downstream analysis."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: base
+skill_type: model
+dependencies:
+  - fmri-skill
+  - nilearn-tool
+  - run_models
+---
+# Detrending Model Doc
+
+## Overview
+Detrending is a classical non-deep-learning method for neuroimaging signal denoising.
+
+- Model family: non-deep-learning preprocessing and denoising method
+- Typical objectives:
+  - remove low-frequency drift and temporal trends
+  - stabilize time series before connectivity, decoding, or statistical analysis
+  - prepare cleaner voxel-wise or ROI-wise time series for downstream workflows
+- Primary input: preprocessed fMRI time series, optional confounds, optional mask, TR
+- Primary output: cleaned BOLD image, cleaned ROI time series, optional QC summaries
+
+In NeuroClaw, this document is model-level guidance for detrending workflows rather than predictive modeling.
+
+Upstream preparation should usually be delegated to:
+- `fmri-skill` for modality-level denoising planning and validated preprocessing sequences
+- `nilearn-tool` for concrete detrending and cleaned time series export
+
+**Research use only.**
+
+---
+
+## Quick Start
+
+### 1) Prepare denoising inputs
+Expected inputs:
+- preprocessed BOLD image
+- repetition time (`TR`)
+- optional confounds TSV
+- optional brain mask
+
+If images are not preprocessed yet, delegate to `fmri-skill` first.
+
+### 2) Detrending route
+Representative operations:
+- load preprocessed image or extracted ROI time series
+- remove constant and linear temporal trends
+- optionally combine detrending with confound regression or standardization
+- export cleaned image or time series table
+
+Example execution route:
+```bash
+# delegated through claw-shell after preprocessing is confirmed
+python skills/nilearn-tool/scripts/denoise_timeseries_reference.py \
+  --bold path/to/sub-001_rest_preproc_bold.nii.gz \
+  --confounds path/to/sub-001_confounds.tsv \
+  --tr 2.0 \
+  --detrend \
+  --output-dir run_models_output/detrending
+```
+
+---
+
+## Input / Output Contract
+
+### Required inputs
+- preprocessed BOLD image or extracted time series
+- TR when combined with temporal cleaning workflow metadata
+
+### Optional inputs
+- confounds table
+- mask image
+- standardization options
+
+### Produced outputs
+- cleaned BOLD image or cleaned time series
+- optional QC summary of detrending settings
+
+---
+
+## Recommended Delegation
+
+- modality-level denoising plan -> `fmri-skill`
+- concrete implementation of detrending -> `nilearn-tool`
+- shell execution and logging -> `claw-shell`
+
+No execution before explicit plan confirmation.
+
+---
+
+## When to Use Detrending
+
+- The user wants signal cleaning rather than statistical modeling or prediction.
+- The goal is to remove drift before connectivity or decoding.
+- The workflow needs standardized temporal preprocessing before ROI extraction.
+- A classical transparent denoising baseline is preferred over learned denoising methods.
+- The user explicitly asks for detrending or drift removal.
+
+---
+
+## Limitations and Notes
+
+- Detrending alone does not remove motion or physiological confounds unless combined with regression.
+- Detrending choices should be reported because they directly affect downstream analyses.
+- Aggressive cleaning sequences can alter downstream effect estimates if applied without task awareness.
+
+---
+
+## Reference
+
+- Ciric R et al. Benchmarking of participant-level confound regression strategies for the control of motion artifact in studies of functional connectivity.
+- Nilearn signal cleaning documentation: https://nilearn.github.io/stable/modules/generated/nilearn.image.clean_img.html
+
+Created At: 2026-04-14 00:40 HKT
+Last Updated At: 2026-04-14 00:45 HKT
+Author: chengwang96