@brainpilot/skills 0.0.6 → 0.0.8

package/skills/06_fMRI_Neuroimaging/nilearn-tool/scripts/preprocess_bold_reference.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+from nilearn.datasets import load_mni152_template
+from nilearn.image import resample_to_img, smooth_img
+from scipy.signal import butter, filtfilt
+
+
+def drop_dummies(image: nib.spatialimages.SpatialImage, n_dummies: int) -> nib.Nifti1Image:
+    data = image.get_fdata()[..., n_dummies:]
+    return nib.Nifti1Image(data, image.affine, image.header)
+
+
+def bandpass_filter(image: nib.spatialimages.SpatialImage, tr: float, high_pass: float, low_pass: float) -> nib.Nifti1Image:
+    data = image.get_fdata()
+    n_timepoints = data.shape[3]
+    nyquist = 0.5 / tr
+    b_coef, a_coef = butter(2, [high_pass / nyquist, low_pass / nyquist], btype="band")
+
+    flat = data.reshape(-1, n_timepoints)
+    mask = np.std(flat, axis=1) > 0
+    result = flat.copy()
+    result[mask] = filtfilt(b_coef, a_coef, flat[mask], axis=1)
+    return nib.Nifti1Image(result.reshape(data.shape), image.affine, image.header)
+
+
+def preprocess_bold(
+    bold_path: Path,
+    output_path: Path,
+    tr: float,
+    fwhm: float,
+    high_pass: float,
+    low_pass: float,
+    n_dummies: int,
+) -> None:
+    image = nib.load(str(bold_path))
+    processed = drop_dummies(image, n_dummies=n_dummies)
+    processed = smooth_img(processed, fwhm=fwhm)
+    processed = bandpass_filter(processed, tr=tr, high_pass=high_pass, low_pass=low_pass)
+
+    template = load_mni152_template(resolution=2)
+    processed = resample_to_img(processed, template, interpolation="linear")
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    nib.save(processed, str(output_path))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference Nilearn preprocessing snippet for resting-state BOLD.")
+    parser.add_argument("--bold", type=Path, required=True, help="Input 4D BOLD NIfTI.")
+    parser.add_argument("--output", type=Path, required=True, help="Output preprocessed BOLD NIfTI.")
+    parser.add_argument("--tr", type=float, default=1.0, help="Repetition time in seconds.")
+    parser.add_argument("--fwhm", type=float, default=6.0, help="Smoothing kernel FWHM in mm.")
+    parser.add_argument("--high-pass", type=float, default=0.01, help="High-pass frequency in Hz.")
+    parser.add_argument("--low-pass", type=float, default=0.10, help="Low-pass frequency in Hz.")
+    parser.add_argument("--n-dummies", type=int, default=5, help="Number of initial dummy scans to drop.")
+    args = parser.parse_args()
+
+    preprocess_bold(
+        bold_path=args.bold,
+        output_path=args.output,
+        tr=args.tr,
+        fwhm=args.fwhm,
+        high_pass=args.high_pass,
+        low_pass=args.low_pass,
+        n_dummies=args.n_dummies,
+    )
+    print(f"Saved preprocessed BOLD to: {args.output}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/06_fMRI_Neuroimaging/nilearn-tool/scripts/rest_dictlearning_reference.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import pandas as pd
+from nilearn.decomposition import DictLearning
+
+
+def load_image_list(list_path: Path) -> list[str]:
+    with list_path.open("r", encoding="utf-8") as handle:
+        return [line.strip() for line in handle if line.strip()]
+
+
+def run_dictlearning(input_list: Path, output_dir: Path, n_components: int, mask_path: Path | None = None) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    images = load_image_list(input_list)
+
+    model = DictLearning(
+        n_components=n_components,
+        mask=mask_path,
+        random_state=0,
+        memory="nilearn_cache",
+        memory_level=1,
+    )
+    model.fit(images)
+
+    nib.save(model.components_img_, str(output_dir / "components.nii.gz"))
+
+    frames = []
+    for index, image_path in enumerate(images):
+        series = model.transform(image_path)
+        frame = pd.DataFrame(series)
+        frame.insert(0, "subject_index", index)
+        frame.to_csv(output_dir / f"subject_{index:03d}_timeseries.csv", index=False)
+        frames.append(frame)
+
+    if frames:
+        pd.concat(frames, ignore_index=True).to_csv(output_dir / "all_subject_timeseries.csv", index=False)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference Nilearn snippet for resting-state DictLearning.")
+    parser.add_argument("--input-list", type=Path, required=True, help="Text file listing preprocessed resting-state BOLD images.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for DictLearning outputs.")
+    parser.add_argument("--n-components", type=int, default=20, help="Number of dictionary components.")
+    parser.add_argument("--mask", type=Path, default=None, help="Optional mask image.")
+    args = parser.parse_args()
+
+    run_dictlearning(args.input_list, args.output_dir, args.n_components, args.mask)
+    print(f"Saved DictLearning outputs to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/06_fMRI_Neuroimaging/nilearn-tool/scripts/rest_ica_reference.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+import pandas as pd
+from nilearn.decomposition import CanICA
+
+
+def load_image_list(list_path: Path) -> list[str]:
+    with list_path.open("r", encoding="utf-8") as handle:
+        return [line.strip() for line in handle if line.strip()]
+
+
+def run_ica(input_list: Path, output_dir: Path, n_components: int, mask_path: Path | None = None) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    images = load_image_list(input_list)
+
+    model = CanICA(
+        n_components=n_components,
+        mask=mask_path,
+        threshold=3.0,
+        random_state=0,
+        memory="nilearn_cache",
+        memory_level=1,
+    )
+    model.fit(images)
+
+    nib.save(model.components_img_, str(output_dir / "components.nii.gz"))
+    pd.DataFrame({"component": np.arange(1, n_components + 1)}).to_csv(output_dir / "components_index.csv", index=False)
+
+    time_series_frames = []
+    for index, image_path in enumerate(images):
+        series = model.transform(image_path)
+        frame = pd.DataFrame(series)
+        frame.insert(0, "subject_index", index)
+        frame.to_csv(output_dir / f"subject_{index:03d}_timeseries.csv", index=False)
+        time_series_frames.append(frame)
+
+    if time_series_frames:
+        pd.concat(time_series_frames, ignore_index=True).to_csv(output_dir / "all_subject_timeseries.csv", index=False)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference Nilearn snippet for resting-state ICA.")
+    parser.add_argument("--input-list", type=Path, required=True, help="Text file listing preprocessed resting-state BOLD images.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for ICA outputs.")
+    parser.add_argument("--n-components", type=int, default=20, help="Number of ICA components.")
+    parser.add_argument("--mask", type=Path, default=None, help="Optional mask image.")
+    args = parser.parse_args()
+
+    run_ica(args.input_list, args.output_dir, args.n_components, args.mask)
+    print(f"Saved ICA outputs to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/06_fMRI_Neuroimaging/nilearn-tool/scripts/second_level_glm_reference.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import pandas as pd
+from nilearn.glm.second_level import SecondLevelModel
+
+
+def load_contrast_maps(list_path: Path) -> list[str]:
+    with list_path.open("r", encoding="utf-8") as handle:
+        return [line.strip() for line in handle if line.strip()]
+
+
+def run_second_level_glm(
+    contrast_maps_path: Path,
+    design_matrix_path: Path,
+    output_dir: Path,
+    contrast_name: str,
+    mask_path: Path | None = None,
+) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    contrast_maps = load_contrast_maps(contrast_maps_path)
+    design_matrix = pd.read_csv(design_matrix_path)
+
+    model = SecondLevelModel(mask_img=str(mask_path) if mask_path is not None else None)
+    model = model.fit(contrast_maps, design_matrix=design_matrix)
+    z_map = model.compute_contrast(contrast_name, output_type="z_score")
+    effect_map = model.compute_contrast(contrast_name, output_type="effect_size")
+
+    nib.save(z_map, str(output_dir / "second_level_z_map.nii.gz"))
+    nib.save(effect_map, str(output_dir / "second_level_effect_map.nii.gz"))
+    design_matrix.to_csv(output_dir / "design_matrix.csv", index=False)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference Nilearn snippet for second-level GLM.")
+    parser.add_argument("--contrast-maps", type=Path, required=True, help="Text file listing subject-level contrast maps.")
+    parser.add_argument("--design-matrix", type=Path, required=True, help="CSV design matrix for group model.")
+    parser.add_argument("--contrast", type=str, required=True, help="Column or contrast expression for group inference.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for second-level outputs.")
+    parser.add_argument("--mask", type=Path, default=None, help="Optional mask image.")
+    args = parser.parse_args()
+
+    run_second_level_glm(
+        contrast_maps_path=args.contrast_maps,
+        design_matrix_path=args.design_matrix,
+        output_dir=args.output_dir,
+        contrast_name=args.contrast,
+        mask_path=args.mask,
+    )
+    print(f"Saved second-level GLM outputs to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/06_fMRI_Neuroimaging/nilearn-tool/scripts/spacenet_classifier_reference.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+import pandas as pd
+from nilearn.decoding import SpaceNetClassifier
+
+
+def load_image_list(list_path: Path) -> list[str]:
+    with list_path.open("r", encoding="utf-8") as handle:
+        return [line.strip() for line in handle if line.strip()]
+
+
+def run_spacenet(
+    input_list: Path,
+    labels_path: Path,
+    output_dir: Path,
+    target: str,
+    mask_path: Path | None = None,
+) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    images = load_image_list(input_list)
+    labels = pd.read_csv(labels_path)
+    y = labels[target].to_numpy()
+
+    model = SpaceNetClassifier(mask=mask_path, penalty="tv-l1", standardize=True, cv=3, n_jobs=1)
+    model.fit(images, y)
+
+    predictions = model.predict(images)
+    pd.DataFrame({"y_true": y, "y_pred": predictions}).to_csv(output_dir / "predictions.csv", index=False)
+
+    coef_img = model.coef_img_
+    if isinstance(coef_img, (list, tuple)):
+        coef_img = coef_img[0]
+    nib.save(coef_img, str(output_dir / "coef_map.nii.gz"))
+
+    decision = model.decision_function(images)
+    pd.DataFrame({"decision_score": np.ravel(decision)}).to_csv(output_dir / "decision_scores.csv", index=False)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference Nilearn snippet for SpaceNet disease classification.")
+    parser.add_argument("--input-list", type=Path, required=True, help="Text file listing aligned subject images.")
+    parser.add_argument("--labels", type=Path, required=True, help="CSV label table.")
+    parser.add_argument("--target", type=str, required=True, help="Target column in label table.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for classifier outputs.")
+    parser.add_argument("--mask", type=Path, default=None, help="Optional mask image.")
+    args = parser.parse_args()
+
+    run_spacenet(args.input_list, args.labels, args.output_dir, args.target, args.mask)
+    print(f"Saved SpaceNet outputs to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/06_fMRI_Neuroimaging/nilearn-tool/scripts/svm_classifier_reference.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import pandas as pd
+from sklearn.metrics import accuracy_score, roc_auc_score
+from sklearn.model_selection import StratifiedKFold, cross_val_predict
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+from sklearn.svm import SVC
+
+
+def run_svm(features_path: Path, labels_path: Path, output_dir: Path, target: str, cv: int) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    features = pd.read_csv(features_path)
+    labels = pd.read_csv(labels_path)
+    y = labels[target]
+
+    if "subject_id" in labels.columns and "subject_id" in features.columns:
+        merged = features.merge(labels[["subject_id", target]], on="subject_id", how="inner")
+        y = merged[target]
+        x = merged.drop(columns=[target])
+        if "subject_id" in x.columns:
+            x = x.drop(columns=["subject_id"])
+    else:
+        x = features
+
+    pipeline = Pipeline([
+        ("scaler", StandardScaler()),
+        ("svm", SVC(kernel="linear", probability=True, random_state=0)),
+    ])
+    splitter = StratifiedKFold(n_splits=cv, shuffle=True, random_state=0)
+    predicted = cross_val_predict(pipeline, x, y, cv=splitter, method="predict")
+    probabilities = cross_val_predict(pipeline, x, y, cv=splitter, method="predict_proba")
+
+    metrics = {"accuracy": accuracy_score(y, predicted)}
+    if probabilities.shape[1] == 2:
+        metrics["auc"] = roc_auc_score(y, probabilities[:, 1])
+
+    pd.DataFrame({"y_true": y, "y_pred": predicted}).to_csv(output_dir / "predictions.csv", index=False)
+    pd.DataFrame([metrics]).to_csv(output_dir / "metrics.csv", index=False)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference Nilearn/scikit-learn snippet for SVM disease classification.")
+    parser.add_argument("--features", type=Path, required=True, help="CSV feature table.")
+    parser.add_argument("--labels", type=Path, required=True, help="CSV label table.")
+    parser.add_argument("--target", type=str, required=True, help="Target column in label table.")
+    parser.add_argument("--cv", type=int, default=5, help="Number of CV folds.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for classifier outputs.")
+    args = parser.parse_args()
+
+    run_svm(args.features, args.labels, args.output_dir, args.target, args.cv)
+    print(f"Saved SVM outputs to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/06_fMRI_Neuroimaging/nilearn-tool/scripts/task_glm_reference.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import pandas as pd
+from nilearn.glm.first_level import FirstLevelModel
+from nilearn.plotting import plot_design_matrix
+
+
+def run_task_glm(
+    bold_path: Path,
+    events_path: Path,
+    output_dir: Path,
+    tr: float,
+    contrast: str,
+    confounds_path: Path | None = None,
+    mask_path: Path | None = None,
+) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    events = pd.read_csv(events_path, sep=None, engine="python")
+    confounds = pd.read_csv(confounds_path, sep=None, engine="python") if confounds_path is not None else None
+
+    model = FirstLevelModel(t_r=tr, mask_img=str(mask_path) if mask_path is not None else None)
+    model = model.fit(str(bold_path), events=events, confounds=confounds)
+
+    design_matrix = model.design_matrices_[0]
+    design_matrix.to_csv(output_dir / "design_matrix.csv", index=False)
+    plot_design_matrix(design_matrix).figure.savefig(output_dir / "design_matrix.png", dpi=150, bbox_inches="tight")
+
+    z_map = model.compute_contrast(contrast, output_type="z_score")
+    effect_map = model.compute_contrast(contrast, output_type="effect_size")
+    nib.save(z_map, str(output_dir / "z_map.nii.gz"))
+    nib.save(effect_map, str(output_dir / "effect_map.nii.gz"))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference Nilearn snippet for first-level task GLM.")
+    parser.add_argument("--bold", type=Path, required=True, help="Input preprocessed task BOLD NIfTI.")
+    parser.add_argument("--events", type=Path, required=True, help="Events TSV/CSV with onset, duration, and trial_type.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for GLM outputs.")
+    parser.add_argument("--tr", type=float, required=True, help="Repetition time in seconds.")
+    parser.add_argument("--contrast", type=str, required=True, help="Named contrast expression.")
+    parser.add_argument("--confounds", type=Path, default=None, help="Optional confounds TSV/CSV.")
+    parser.add_argument("--mask", type=Path, default=None, help="Optional mask image.")
+    args = parser.parse_args()
+
+    run_task_glm(
+        bold_path=args.bold,
+        events_path=args.events,
+        output_dir=args.output_dir,
+        tr=args.tr,
+        contrast=args.contrast,
+        confounds_path=args.confounds,
+        mask_path=args.mask,
+    )
+    print(f"Saved first-level GLM outputs to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/06_fMRI_Neuroimaging/nilearn-tool/scripts/zalff_summary_reference.py

@@ -0,0 +1,109 @@
+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 export_zalff_summary(
+    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]
+    mean_value = float(np.mean(alff_values))
+    std_value = float(np.std(alff_values))
+    if std_value == 0:
+        raise ValueError("zALFF normalization failed because the standard deviation is zero.")
+
+    zalff = image.math_img(f"(img - {mean_value}) / {std_value}", 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)
+
+    summary.head(top_n).to_csv(output_dir / "TOP_active_regions.csv", index=False)
+    summary.head(top_n)[["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 Nilearn snippet for zALFF regional summaries.")
+    parser.add_argument("--bold", type=Path, required=True, help="Input 4D BOLD NIfTI.")
+    parser.add_argument("--atlas", type=Path, required=True, help="Atlas NIfTI for regional summaries.")
+    parser.add_argument("--labels", type=Path, required=True, help="Atlas label text file.")
+    parser.add_argument("--mask", type=Path, required=True, help="Mask image for resampling and cleaning.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for summary 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()
+
+    export_zalff_summary(
+        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()