@brainpilot/skills 0.0.6 → 0.0.8

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

@@ -0,0 +1,122 @@
+---
+name: dictlearning
+description: "Use this model doc whenever the user wants to perform resting-state network decomposition using DictLearning. This is a non-deep-learning unsupervised route focused on sparse component extraction, network map discovery, and subject-level time series from resting-state fMRI."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: base
+skill_type: model
+dependencies:
+  - fmri-skill
+  - nilearn-tool
+  - run_models
+---
+# DictLearning Model Doc
+
+## Overview
+DictLearning is a classical non-deep-learning method for resting-state network decomposition.
+
+- Model family: non-deep-learning unsupervised decomposition method
+- Typical objectives:
+  - identify sparse resting-state networks from preprocessed fMRI
+  - extract dictionary component maps and subject-level time series
+  - derive interpretable network summaries for downstream connectivity or clustering
+- Primary input: preprocessed resting-state fMRI, optional mask, optional group subject list
+- Primary output: dictionary component maps, subject time series, optional connectomes or reports
+
+In NeuroClaw, this document is model-level guidance for DictLearning-based resting-state decomposition workflows rather than phenotype prediction.
+
+Upstream preparation should usually be delegated to:
+- `fmri-skill` for rs-fMRI preprocessing, nuisance regression, filtering, and standard-space alignment
+- `nilearn-tool` for concrete DictLearning fitting and component export
+
+**Research use only.**
+
+---
+
+## Quick Start
+
+### 1) Prepare resting-state inputs
+Expected inputs:
+- preprocessed resting-state BOLD images
+- optional confounds TSV files
+- optional brain mask
+- optional subject list or cohort manifest
+
+If these are not ready, delegate to `fmri-skill` first.
+
+### 2) DictLearning route
+Representative operations:
+- load preprocessed resting-state images
+- fit sparse dictionary learning for network decomposition
+- export dictionary component maps and subject time series
+- optionally use outputs for connectome or clustering analysis
+
+Example execution route:
+```bash
+# delegated through claw-shell after preprocessing is confirmed
+python skills/nilearn-tool/scripts/rest_dictlearning_reference.py \
+  --input-list path/to/rest_bold_list.txt \
+  --mask path/to/group_mask.nii.gz \
+  --n-components 20 \
+  --output-dir run_models_output/dictlearning
+```
+
+---
+
+## Input / Output Contract
+
+### Required inputs
+- preprocessed resting-state fMRI in subject space or standard space
+- subject list or image list
+
+### Optional inputs
+- confounds table(s)
+- mask image
+- repetition time (`TR`)
+- decomposition parameters such as number of components
+- group/covariate table for downstream statistical analysis
+
+### Produced outputs
+- 4D component map image
+- subject-level component time series
+- component report figures and summary tables
+- optional component correlation matrix / connectome
+
+---
+
+## Recommended Delegation
+
+- resting-state preprocessing and denoising -> `fmri-skill`
+- concrete implementation of DictLearning -> `nilearn-tool`
+- shell execution and logging -> `claw-shell`
+
+No execution before explicit plan confirmation.
+
+---
+
+## When to Use DictLearning
+
+- The user wants resting-state network decomposition rather than task activation analysis.
+- The goal is to identify sparse intrinsic connectivity networks from rs-fMRI.
+- The user wants subject-level component time series for downstream connectivity or clustering.
+- Sparse and interpretable network components are preferred.
+- A lightweight classical unsupervised method is preferred over deep learning.
+
+---
+
+## Limitations and Notes
+
+- Results are sensitive to preprocessing quality, head motion, filtering, and masking choices.
+- The number of components strongly influences decomposition granularity.
+- DictLearning is unsupervised and does not directly provide statistical group inference.
+- Downstream comparisons across groups usually require additional statistical analysis after decomposition.
+
+---
+
+## Reference
+
+- Varoquaux G et al. Dictionary learning for resting-state fMRI atlas extraction.
+- Nilearn decomposition documentation: https://nilearn.github.io/stable/connectivity/resting_state_networks.html
+
+Created At: 2026-04-14 00:31 HKT
+Last Updated At: 2026-04-14 00:45 HKT
+Author: chengwang96

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

@@ -0,0 +1,121 @@
+---
+name: filtering
+description: "Use this model doc whenever the user wants to perform neuroimaging signal denoising with classical temporal filtering methods. This is a non-deep-learning preprocessing route focused on temporal cleaning, frequency selection, and preparation of cleaner time series for 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
+---
+# Filtering Model Doc
+
+## Overview
+Filtering is a classical non-deep-learning method for neuroimaging signal denoising.
+
+- Model family: non-deep-learning preprocessing and denoising method
+- Typical objectives:
+  - remove unwanted frequency content from BOLD time series
+  - retain frequency bands relevant to resting-state or task analysis
+  - prepare cleaner voxel-wise or ROI-wise time series for downstream connectivity, decoding, or statistical analysis
+- Primary input: preprocessed fMRI time series, optional confounds, optional mask, TR
+- Primary output: denoised BOLD image, cleaned ROI time series, optional QC summaries
+
+In NeuroClaw, this document is model-level guidance for temporal filtering 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 filtering and cleaned image export
+
+**Research use only.**
+
+---
+
+## Quick Start
+
+### 1) Prepare denoising inputs
+Expected inputs:
+- preprocessed BOLD image
+- repetition time (`TR`)
+- optional confounds TSV
+- optional brain mask
+- optional requested frequency band
+
+If images are not preprocessed yet, delegate to `fmri-skill` first.
+
+### 2) Filtering route
+Representative operations:
+- load preprocessed BOLD time series
+- apply temporal high-pass / low-pass or band-pass filtering
+- optionally combine filtering with standardization or confound regression
+- export denoised image and cleaned summaries
+
+Example execution route:
+```bash
+# delegated through claw-shell after preprocessing is confirmed
+python skills/nilearn-tool/scripts/preprocess_bold_reference.py \
+  --bold path/to/sub-001_rest_preproc_bold.nii.gz \
+  --tr 2.0 \
+  --high-pass 0.01 \
+  --low-pass 0.08 \
+  --output run_models_output/filtering/sub-001_rest_filtered_bold.nii.gz
+```
+
+---
+
+## Input / Output Contract
+
+### Required inputs
+- preprocessed BOLD image or extracted time series
+- TR for temporal filtering
+
+### Optional inputs
+- confounds table
+- mask image
+- high-pass / low-pass frequency settings
+- standardization or smoothing options
+
+### Produced outputs
+- denoised BOLD image
+- cleaned ROI or voxel time series
+- optional QC summary of filtering settings
+
+---
+
+## Recommended Delegation
+
+- modality-level denoising plan -> `fmri-skill`
+- concrete implementation of filtering -> `nilearn-tool`
+- shell execution and logging -> `claw-shell`
+
+No execution before explicit plan confirmation.
+
+---
+
+## When to Use Filtering
+
+- The user wants signal cleaning rather than statistical modeling or prediction.
+- The goal is to remove unwanted frequency content 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 band-pass filtering, high-pass filtering, or low-pass filtering.
+
+---
+
+## Limitations and Notes
+
+- Filtering choices depend strongly on TR, study design, and whether the data are resting-state or task-fMRI.
+- Over-aggressive filtering can remove meaningful task-related or physiological signals.
+- Temporal cleaning parameters should be reported because they directly affect downstream analyses.
+
+---
+
+## Reference
+
+- Lindquist MA. The statistical analysis of fMRI data.
+- 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

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

@@ -0,0 +1,153 @@
+---
+name: glm
+description: "Use this model doc whenever the user wants to run a classical General Linear Model (GLM) for task-evoked fMRI activation analysis. This is a non-deep-learning model route focused on design matrices, first-level/second-level statistics, and statistical maps."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: base
+skill_type: model
+dependencies:
+  - fmri-skill
+  - nilearn-tool
+  - run_models
+---
+# GLM Model Doc
+
+## Overview
+GLM refers to the classical General Linear Model used for task-based fMRI activation analysis.
+
+- Model family: non-deep-learning statistical model
+- Typical objectives:
+  - first-level GLM for subject/session-level task activation analysis
+  - second-level GLM for group-level inference across subjects
+- Primary input: preprocessed task fMRI, events, TR, optional confounds, optional brain mask
+- Primary output: first-level contrast maps, second-level z maps, thresholded activation maps, region-level summaries
+
+In NeuroClaw, this document is model-level guidance for statistical activation workflows rather than phenotype prediction.
+
+Upstream preparation should usually be delegated to:
+- `fmri-skill` for task-fMRI preprocessing and confounds preparation
+- `nilearn-tool` for concrete GLM fitting, design matrix construction, and statistical map generation
+
+**Research use only.**
+
+---
+
+## Quick Start
+
+### 1) Prepare task-fMRI inputs
+Expected inputs:
+- preprocessed task BOLD image
+- events TSV/CSV with onset, duration, trial type
+- repetition time (`TR`)
+- optional confounds TSV
+- optional mask image
+
+These should be prepared before model fitting. If not ready, delegate to `fmri-skill` first.
+
+### 2) Typical first-level GLM flow
+Representative operations:
+- build design matrix from events and confounds
+- fit first-level GLM per subject/session
+- compute named contrasts such as `task > baseline`
+- export z maps / effect size maps
+
+Example execution route:
+```bash
+# delegated through claw-shell after preprocessing is confirmed
+python skills/nilearn-tool/scripts/task_glm_reference.py \
+  --bold path/to/sub-001_task-preproc_bold.nii.gz \
+  --events path/to/sub-001_task-events.tsv \
+  --confounds path/to/sub-001_confounds.tsv \
+  --tr 2.0 \
+  --contrast "task-baseline" \
+  --output-dir run_models_output/glm/sub-001
+```
+
+### 3) Second-level GLM (group-level inference)
+When multiple subjects are available, use second-level GLM for group-level inference.
+
+Representative operations:
+- collect subject-level contrast maps from first-level GLM
+- build a group design matrix (for one-sample, two-sample, or covariate models)
+- fit a second-level model across subjects
+- export group z maps, thresholded figures, and statistical summaries
+
+Typical use cases:
+- one-sample group activation inference
+- between-group comparison
+- covariate-adjusted group analysis (for example age / sex / site)
+
+Example execution route:
+```bash
+# delegated through claw-shell after subject-level contrasts are prepared
+python skills/nilearn-tool/scripts/second_level_glm_reference.py \
+  --contrast-maps path/to/contrast_map_list.txt \
+  --design-matrix path/to/group_design_matrix.csv \
+  --contrast group_mean \
+  --output-dir run_models_output/glm/group_level
+```
+
+---
+
+## Input / Output Contract
+
+### Required inputs
+- preprocessed task fMRI in subject space or standard space
+- events table with onset / duration / condition labels
+- TR
+
+### Optional inputs
+- confounds table
+- mask image
+- subject-level metadata for group models
+- first-level contrast maps for second-level GLM
+- group design matrix for second-level GLM
+
+### Produced outputs
+- design matrix figure or CSV snapshot
+- first-level beta / contrast / z maps
+- thresholded maps and glass-brain figures
+- second-level group z maps and statistical summaries
+
+---
+
+## Recommended Delegation
+
+- preprocessing and task-fMRI preparation -> `fmri-skill`
+- concrete implementation of design matrices and GLM fitting -> `nilearn-tool`
+- shell execution and logging -> `claw-shell`
+
+Recommended route split:
+- first-level GLM -> subject/session-level task activation analysis
+- second-level GLM -> group-level inference on first-level contrast maps
+
+No execution before explicit plan confirmation.
+
+---
+
+## When to Use GLM Instead of Deep Learning
+
+- The user wants classical task activation analysis rather than phenotype prediction.
+- The goal is statistical inference on task conditions or contrasts.
+- The user wants group-level inference across subjects rather than individual-level prediction.
+- Sample size is limited and interpretability of condition effects is more important than representation learning.
+- The required output is a contrast map, z map, or cluster-level inference report.
+
+---
+
+## Limitations and Notes
+
+- GLM is primarily for task-fMRI, not resting-state phenotype modeling.
+- Results are sensitive to event timing quality, motion confounds, and preprocessing decisions.
+- Group-level inference requires consistent first-level contrast definitions across subjects.
+- Second-level GLM requires aligned subject-level maps and a valid group design matrix.
+
+---
+
+## Reference
+
+- Friston KJ et al. Statistical Parametric Mapping foundations for task-fMRI analysis.
+- Nilearn GLM documentation: https://nilearn.github.io/stable/glm/index.html
+
+Created At: 2026-04-14 00:28 HKT
+Last Updated At: 2026-04-14 00:28 HKT
+Author: chengwang96

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

@@ -0,0 +1,121 @@
+---
+name: hierarchical
+description: "Use this model doc whenever the user wants to perform brain parcellation using Hierarchical clustering. This is a non-deep-learning unsupervised route focused on multi-scale parcel discovery, voxel or vertex grouping, and atlas-like region generation from neuroimaging features."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: base
+skill_type: model
+dependencies:
+  - fmri-skill
+  - smri-skill
+  - nilearn-tool
+  - run_models
+---
+# Hierarchical Model Doc
+
+## Overview
+Hierarchical clustering is a classical non-deep-learning method for data-driven brain parcellation.
+
+- Model family: non-deep-learning unsupervised clustering method
+- Typical objectives:
+  - partition voxels, vertices, or ROI features into data-driven brain parcels
+  - build subject-level or group-level parcellations from functional or structural similarity
+  - export parcel labels and merge summaries across scales
+- Primary input: preprocessed neuroimaging features, optional mask, optional similarity or connectivity representation
+- Primary output: parcel label map, cluster summaries, optional dendrogram outputs
+
+In NeuroClaw, this document is model-level guidance for Hierarchical-clustering-based brain parcellation workflows rather than supervised prediction.
+
+Upstream preparation should usually be delegated to:
+- `fmri-skill` for rs-fMRI or task-fMRI feature preparation when parcellation is function-driven
+- `smri-skill` for structural feature preparation when parcellation is anatomy-driven
+- `nilearn-tool` for concrete masking, feature matrix preparation, and hierarchical parcel export
+
+**Research use only.**
+
+---
+
+## Quick Start
+
+### 1) Prepare parcellation inputs
+Expected inputs:
+- preprocessed feature matrix or image list
+- optional brain mask
+- optional subject list or cohort manifest
+- target parcel number or clustering granularity
+
+If these are not ready, delegate preprocessing to `fmri-skill` or `smri-skill` first.
+
+### 2) Hierarchical route
+Representative operations:
+- prepare aligned feature representation
+- compute similarity or distance structure across spatial units
+- fit agglomerative / Ward-style hierarchical clustering
+- export parcel labels and optional dendrogram or merge summaries
+
+Example execution route:
+```bash
+# delegated through claw-shell after features are prepared
+python skills/nilearn-tool/scripts/hierarchical_parcellation_reference.py \
+  --input-list path/to/image_list.txt \
+  --mask path/to/group_mask.nii.gz \
+  --n-clusters 200 \
+  --output-dir run_models_output/hierarchical
+```
+
+---
+
+## Input / Output Contract
+
+### Required inputs
+- feature matrix or aligned neuroimaging image list
+- requested clustering target such as parcel count
+
+### Optional inputs
+- mask image
+- connectivity or similarity matrix
+- spatial adjacency constraints
+- subject grouping or cohort definition
+- linkage parameters
+
+### Produced outputs
+- parcel label image or table
+- cluster size summary
+- optional hierarchical merge information or dendrogram summary
+
+---
+
+## Recommended Delegation
+
+- imaging preprocessing and feature preparation -> `fmri-skill` and/or `smri-skill`
+- concrete implementation of Hierarchical clustering -> `nilearn-tool`
+- shell execution and logging -> `claw-shell`
+
+No execution before explicit plan confirmation.
+
+---
+
+## When to Use Hierarchical Clustering
+
+- The user wants data-driven brain region partitioning rather than using a predefined atlas.
+- The goal is to derive parcel labels for downstream connectivity, decoding, or visualization.
+- A classical unsupervised clustering baseline is preferred over deep learning.
+- The user wants multi-scale organization or merge structure.
+
+---
+
+## Limitations and Notes
+
+- Clustering quality depends strongly on preprocessing, feature definition, and spatial normalization.
+- Hierarchical clustering can be computationally expensive for large voxel spaces.
+- Data-driven parcellations may vary across cohorts and may not align directly with standard atlases.
+
+---
+
+## Reference
+
+- Bellec P et al. Multi-level bootstrap analysis of stable clusters in resting-state fMRI.
+- Nilearn regions and parcellations documentation: https://nilearn.github.io/stable/connectivity/region_extraction.html
+
+Created At: 2026-04-14 00:37 HKT
+Last Updated At: 2026-04-14 00:45 HKT
+Author: chengwang96

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

@@ -0,0 +1,122 @@
+---
+name: ica
+description: "Use this model doc whenever the user wants to perform resting-state network decomposition using ICA. This is a non-deep-learning unsupervised route focused on extracting intrinsic connectivity networks, component maps, and subject-level time series from resting-state fMRI."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: base
+skill_type: model
+dependencies:
+  - fmri-skill
+  - nilearn-tool
+  - run_models
+---
+# ICA Model Doc
+
+## Overview
+ICA is a classical non-deep-learning method for resting-state network decomposition.
+
+- Model family: non-deep-learning unsupervised decomposition method
+- Typical objectives:
+  - identify intrinsic connectivity networks from resting-state fMRI
+  - extract spatial component maps and subject-level time series
+  - derive component-level connectivity or subject summaries for downstream analysis
+- Primary input: preprocessed resting-state fMRI, optional mask, optional group subject list
+- Primary output: component maps, subject time series, component loadings, optional connectomes or reports
+
+In NeuroClaw, this document is model-level guidance for ICA-based resting-state decomposition workflows rather than phenotype prediction.
+
+Upstream preparation should usually be delegated to:
+- `fmri-skill` for rs-fMRI preprocessing, nuisance regression, filtering, and standard-space alignment
+- `nilearn-tool` for concrete ICA fitting and component export
+
+**Research use only.**
+
+---
+
+## Quick Start
+
+### 1) Prepare resting-state inputs
+Expected inputs:
+- preprocessed resting-state BOLD images
+- optional confounds TSV files
+- optional brain mask
+- optional subject list or cohort manifest
+
+If these are not ready, delegate to `fmri-skill` first.
+
+### 2) ICA route
+Representative operations:
+- load subject-level or group-level rs-fMRI images
+- fit ICA to estimate intrinsic connectivity components
+- export component spatial maps and subject time series
+- optionally compute component-level correlations
+
+Example execution route:
+```bash
+# delegated through claw-shell after preprocessing is confirmed
+python skills/nilearn-tool/scripts/rest_ica_reference.py \
+  --input-list path/to/rest_bold_list.txt \
+  --mask path/to/group_mask.nii.gz \
+  --n-components 20 \
+  --output-dir run_models_output/ica
+```
+
+---
+
+## Input / Output Contract
+
+### Required inputs
+- preprocessed resting-state fMRI in subject space or standard space
+- subject list or image list
+
+### Optional inputs
+- confounds table(s)
+- mask image
+- repetition time (`TR`)
+- decomposition parameters such as number of components
+- group/covariate table for downstream statistical analysis
+
+### Produced outputs
+- 4D component map image
+- subject-level component time series
+- component report figures and summary tables
+- optional component correlation matrix / connectome
+
+---
+
+## Recommended Delegation
+
+- resting-state preprocessing and denoising -> `fmri-skill`
+- concrete implementation of ICA -> `nilearn-tool`
+- shell execution and logging -> `claw-shell`
+
+No execution before explicit plan confirmation.
+
+---
+
+## When to Use ICA
+
+- The user wants resting-state network decomposition rather than task activation analysis.
+- The goal is to identify intrinsic connectivity networks from rs-fMRI.
+- The user wants subject-level component time series for downstream connectivity or clustering.
+- Interpretability of spatial networks is more important than supervised phenotype prediction.
+- A lightweight classical unsupervised method is preferred over deep learning.
+
+---
+
+## Limitations and Notes
+
+- Results are sensitive to preprocessing quality, head motion, filtering, and masking choices.
+- The number of components strongly influences decomposition granularity.
+- ICA is unsupervised and does not directly provide statistical group inference.
+- Downstream comparisons across groups usually require additional statistical analysis after decomposition.
+
+---
+
+## Reference
+
+- Beckmann CF, Smith SM. Probabilistic independent component analysis for functional magnetic resonance imaging.
+- Nilearn decomposition documentation: https://nilearn.github.io/stable/connectivity/resting_state_networks.html
+
+Created At: 2026-04-14 00:31 HKT
+Last Updated At: 2026-04-14 00:45 HKT
+Author: chengwang96