Add core ROI masks, visualization script, and model profiles

- Introduced core ROI masks (BA47, TP, aSTS, pSTS) for A1 evaluation.
- Added README for ROI masks detailing their purpose and usage.
- Created a new script `run_a1_visualize.py` for visualizing A1 fit outputs.
- Implemented model profiles in JSON format for current and future model configurations.
- Updated requirements.txt with necessary dependencies for the new visualization script.

.gitignore

@@ -0,0 +1,13 @@
+/derivatives
+data
+*.pdf
+*.pyc
+/visualizations
+/code/outputs
+*png
+*.npz
+check_missing_derivatives.py
+free_space.sh
+/outputs
+*.csv
+llms_brain_lateralization/

README.md

@@ -1,12 +1,162 @@
----
-title: Csai
-emoji: 🐢
-colorFrom: purple
-colorTo: pink
-sdk: gradio
-sdk_version: 6.13.0
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Plan: A1 SI Baseline with Dual Evaluation and Expanded Parcels
+
+Implement A1 as a frozen SI baseline with two required evaluation protocols: cross-run generalization and within-run blocked split. Keep both 7 language ROIs and expanded Harvard-Oxford symmetric parcels, and report results separately so speaker-shift robustness and same-condition fit are not conflated.
+
+**Steps**
+1. Phase 0: Paper-first gate before coding
+- Verify appendix details for ROI/parcellation and document any unresolved ambiguities.
+- Lock assumptions and scope before implementation starts.
+
+2. Phase 1: Data manifest and integrity QC
+- Build clean derivatives manifest with strict checks: folder and filename subject consistency, run whitelist 1-4, sidecar existence, unique subject-run keys.
+- Save reject log and accepted manifest.
+- Validate per-run TR and scan length from BIDS sidecars.
+
+3. Phase 2: Spatial harmonization and mask
+- Resample BOLD to one canonical analysis grid.
+- Build analysis mask and enforce left-right symmetry using hemisphere swap and mask intersection.
+- Emit affine and shape and voxel-count QC report.
+
+4. Phase 3: Target definition with two parcellation tracks
+- Track A: 7 language ROIs from sphere masks.
+- Track B: Harvard-Oxford cortical maxprob-thr0-2mm with symmetric split for expanded parcel analysis.
+- Resample labels with nearest-neighbor interpolation only.
+- Build left-right parcel pairing map and parcel voxel index map.
+
+5. Phase 4: Annotation harmonization
+- Build unified word-event table with run_id, condition, speaker_stream, word, onset_s, offset_s, duration_s, provenance.
+- Apply approved fixed run mapping and mixed-run fallback flags.
+- Validate monotonic and non-negative timing.
+
+6. Phase 5: Frozen SI feature extraction
+- Extract per-run, per-layer, per-word hidden-state features for approved models.
+- Cache token-to-word aggregated embeddings and extraction metadata.
+- No model fine-tuning in baseline phase.
+
+7. Phase 6: Temporal alignment and normalization
+- Convert word features to TR regressors with HRF convolution.
+- Apply per-run z-score to regressors and BOLD targets.
+- Enforce exact regressor-target TR length match after trimming policy.
+
+8. Phase 7: Dual evaluation implementation (both required)
+- Protocol A: cross-run split
+- Leave-one-run-out per subject to test speaker and condition transfer.
+- Nested alpha selection on training-only partitions.
+- Protocol B: within-run blocked split
+- Use contiguous temporal blocks inside each run for train and test, not random word sampling.
+- Add temporal gap buffer between train and test blocks to reduce HRF bleed leakage.
+- Tune alpha using training-only temporal partitions.
+- Compute metrics for both target sets in both protocols: 7 ROIs and expanded parcels.
+- Keep outputs clearly labeled by protocol to avoid mixing interpretations.
+
+9. Phase 8: Outputs and reporting
+- Save per-model, per-layer, per-subject, per-run, per-target, per-protocol tables.
+- Save left-right asymmetry summaries and significance tables for parcel and ROI levels.
+- Save protocol comparison report: cross-run versus within-run blocked.
+
+10. Phase 9: Optional extension after baseline
+- Add fine-tuning branch as a separate experiment only after frozen baseline is complete.
+- Compare against frozen baseline outputs using matched protocols.
+
+**Relevant files**
+- /home/mohith/ds005345/NeurIPS-2024-fmri-predictors-based-on-language-models-of-increasing-complexity-recover-brain-left-lateralization-Paper-Conference.pdf — paper and appendix reference gate.
+- /home/mohith/ds005345/llms_brain_lateralization/README.md — reference pipeline order and 7 ROI context.
+- /home/mohith/ds005345/llms_brain_lateralization/create_roi_masks.py — 7 language ROI coordinates and generation pattern.
+- /home/mohith/ds005345/llms_brain_lateralization/analyze_results.ipynb — expanded Harvard-Oxford symmetric atlas workflow and nearest-neighbor resampling pattern.
+- /home/mohith/ds005345/llms_brain_lateralization/extract_llm_activations.py — hidden-state extraction and token-to-word aggregation pattern.
+- /home/mohith/ds005345/llms_brain_lateralization/fit_individual_subject.py — run-wise HRF regressor build and ridge CV template.
+- /home/mohith/ds005345/llms_brain_lateralization/resample_fmri_data.py — canonical resampling pattern.
+- /home/mohith/ds005345/llms_brain_lateralization/compute_mask.py — symmetric mask computation.
+
+**Verification**
+1. Paper gate checks
+- Appendix ROI and parcel assumptions logged and aligned with implementation choices.
+
+2. Spatial checks
+- Atlas and BOLD match analysis affine and shape.
+- Label interpolation nearest-neighbor only.
+- Symmetric mask voxel counts and left-right balance logged.
+
+3. Feature checks
+- Hidden-state files complete for each run, model, and layer.
+- Token-to-word aggregation diagnostics saved.
+
+4. Modeling checks
+- Frozen baseline confirmed with no weight updates.
+- Protocol A and Protocol B each have independent train and validation and test metadata.
+- Within-run blocked split includes temporal buffer and zero overlap after buffering.
+
+5. Reporting checks
+- 7 ROI and expanded parcel outputs exist for both protocols.
+- Side-by-side protocol comparison produced for every model.
+
+**Decisions**
+- Baseline SI uses frozen inference plus ridge only.
+- Two evaluation protocols are both required in baseline: cross-run and within-run blocked.
+- Random word-level 500/100 split is excluded from primary SI evaluation due temporal leakage risk after HRF convolution.
+- Expanded ROI set uses Harvard-Oxford cortical maxprob-thr0-2mm with symmetric split.
+- Fine-tuning remains a separate post-baseline experiment branch.
+
+## Running On HF Jobs
+
+For this project, use HF Jobs rather than a Space. The A1 pipeline expects one root containing:
+
+- `project/`
+- `data/`
+- `derivatives/`
+
+The launcher in `project/hf_jobs.py` reconstructs that layout inside the HF container and then runs `project/code/run_a1_end_to_end.py` unchanged.
+
+### Required HF repos
+
+Create two HF Dataset repos:
+
+- one whose repo root mirrors the contents of local `data/`
+- one whose repo root mirrors the contents of local `derivatives/`
+
+Important:
+
+- upload the folder contents, not the parent folder name
+- the `data` repo should have files like `participants.tsv` and `sub-01/` at repo root
+- the `derivatives` repo should have `sub-01/`, `sub-02/`, ... at repo root
+
+### Preview The Job
+
+```bash
+cd /home/mohith/ds005345
+conda activate csai
+python project/hf_jobs.py \
+  --code-url https://huggingface.co/spaces/Mohith202/csai.git \
+  --data-repo Mohith202/ds005345-data \
+  --derivatives-repo Mohith202/ds005345-derivatives \
+  --results-repo Mohith202/ds005345-a1-results \
+  --secret-hf-token
+```
+
+This prints the generated job script and the `hf jobs run` command without launching it.
+
+### Launch The End-To-End Run
+
+```bash
+cd /home/mohith/ds005345
+conda activate csai
+python project/hf_jobs.py \
+  --code-url https://huggingface.co/spaces/Mohith202/csai.git \
+  --data-repo Mohith202/ds005345-data \
+  --derivatives-repo Mohith202/ds005345-derivatives \
+  --results-repo Mohith202/ds005345-a1-results \
+  --results-path hf_jobs/run_001 \
+  --flavor a10g-small \
+  --model-profile current \
+  --protocols B,C \
+  --secret-hf-token \
+  --launch
+```
+
+### Notes
+
+- `--secret-hf-token` is recommended when the dataset repos are private.
+- The job keeps the CUDA-enabled PyTorch already present in the container image and installs the rest of `project/requirements.txt` separately.
+- By default bootstrap artifacts go to `outputs/a1_bootstrap_hf` inside the cloned repo.
+- You can forward the normal end-to-end controls such as `--model-profile`, `--model-slug`, `--reuse-caches`, `--skip-bootstrap`, `--skip-fit`, and `--skip-visualize`.
+- You can forward the normal end-to-end controls such as `--model-profile`, `--model-slug`, `--protocols`, `--reuse-caches`, `--skip-bootstrap`, `--skip-fit`, and `--skip-visualize`.

code/a1_pipeline/__init__.py

@@ -0,0 +1,30 @@
+"""A1 frozen SI baseline bootstrap package."""
+
+from .alignment import build_and_cache_alignment_inputs
+from .annotations import build_harmonized_annotation_tables
+from .constants import DEFAULT_ALLOWED_RUNS, DEFAULT_MODEL_IDS
+from .features import extract_and_cache_run_level_features, slugify_model_id
+from .manifest import build_derivatives_manifest
+from .model_config import load_model_ids_from_config, list_model_profiles
+from .spatial import build_symmetric_analysis_mask
+from .splits import build_cross_run_folds, build_within_run_blocked_splits, summarize_split_counts
+from .targets import CORE_ROI_NAMES, evaluate_core_roi_preservation, load_core_roi_masks
+
+__all__ = [
+    "build_and_cache_alignment_inputs",
+    "build_harmonized_annotation_tables",
+    "DEFAULT_ALLOWED_RUNS",
+    "DEFAULT_MODEL_IDS",
+    "extract_and_cache_run_level_features",
+    "slugify_model_id",
+    "build_derivatives_manifest",
+    "load_model_ids_from_config",
+    "list_model_profiles",
+    "build_symmetric_analysis_mask",
+    "build_cross_run_folds",
+    "build_within_run_blocked_splits",
+    "summarize_split_counts",
+    "CORE_ROI_NAMES",
+    "load_core_roi_masks",
+    "evaluate_core_roi_preservation",
+]

code/a1_pipeline/alignment.py

@@ -0,0 +1,348 @@
+"""TR-level HRF regressor and z-score alignment utilities."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+import nibabel as nib
+import numpy as np
+import pandas as pd
+
+
+def _zscore_columns(values: np.ndarray, eps: float = 1e-8) -> np.ndarray:
+    mean = np.mean(values, axis=0, keepdims=True)
+    std = np.std(values, axis=0, keepdims=True)
+    std[std < eps] = 1.0
+    return ((values - mean) / std).astype(np.float32)
+
+
+def _trim_time_axis(values: np.ndarray, trim_start_tr: int, trim_end_tr: int) -> np.ndarray:
+    if trim_start_tr < 0 or trim_end_tr < 0:
+        raise ValueError("trim_start_tr and trim_end_tr must be non-negative")
+
+    start = int(trim_start_tr)
+    stop = values.shape[0] - int(trim_end_tr)
+
+    if start >= stop:
+        raise ValueError(
+            "Trimming removed all time points: "
+            f"n_tr={values.shape[0]}, trim_start={trim_start_tr}, trim_end={trim_end_tr}"
+        )
+
+    return values[start:stop]
+
+
+def _format_tr_for_filename(tr_seconds: float) -> str:
+    return f"{tr_seconds:.4f}".replace(".", "p")
+
+
+def _assert_same_grid(img: nib.Nifti1Image, reference_img: nib.Nifti1Image, atol: float = 1e-5) -> None:
+    if img.shape[:3] != reference_img.shape:
+        raise ValueError(
+            "Image shape mismatch against analysis mask grid: "
+            f"image={img.shape[:3]}, reference={reference_img.shape}"
+        )
+    if not np.allclose(img.affine, reference_img.affine, atol=atol):
+        raise ValueError("Image affine mismatch against analysis mask grid")
+
+
+def _extract_masked_bold_2d(
+    bold_path: Path,
+    analysis_mask_bool: np.ndarray,
+    analysis_mask_img: nib.Nifti1Image,
+) -> np.ndarray:
+    img = nib.load(str(bold_path))
+    if len(img.shape) != 4:
+        raise ValueError(f"Expected 4D BOLD image, got shape={img.shape} for {bold_path}")
+
+    _assert_same_grid(img=img, reference_img=analysis_mask_img)
+
+    data = np.asanyarray(img.dataobj)
+    # Convert from (x,y,z,t) to (t,voxels)
+    bold_2d = data[analysis_mask_bool, :].T.astype(np.float32)
+    return bold_2d
+
+
+def compute_hrf_regressor_matrix(
+    word_features: np.ndarray,
+    onsets_s: np.ndarray,
+    offsets_s: np.ndarray,
+    tr_seconds: float,
+    n_volumes: int,
+    hrf_model: str,
+) -> np.ndarray:
+    """Build TR-level HRF-convolved regressors from word-level features."""
+    from nilearn.glm.first_level import compute_regressor
+
+    if word_features.ndim != 2:
+        raise ValueError("word_features must be 2D: (n_words, hidden_dim)")
+
+    if onsets_s.shape[0] != word_features.shape[0] or offsets_s.shape[0] != word_features.shape[0]:
+        raise ValueError("onset/offset lengths must match n_words in word_features")
+
+    durations = offsets_s - onsets_s
+    frame_times = np.arange(n_volumes, dtype=np.float64) * float(tr_seconds) + 0.5 * float(tr_seconds)
+
+    regressors = np.zeros((int(n_volumes), int(word_features.shape[1])), dtype=np.float32)
+
+    for feature_index in range(word_features.shape[1]):
+        amplitudes = word_features[:, feature_index].astype(np.float64)
+        exp_condition = np.array([onsets_s, durations, amplitudes], dtype=np.float64)
+        signal, _ = compute_regressor(exp_condition, hrf_model, frame_times)
+        regressors[:, feature_index] = signal[:, 0].astype(np.float32)
+
+    return regressors
+
+
+@dataclass(frozen=True)
+class BoldAlignmentRecord:
+    """Summary for one subject-run BOLD alignment artifact."""
+
+    subject: str
+    run: int
+    tr_seconds: float
+    n_volumes_raw: int
+    n_tr_aligned: int
+    n_voxels: int
+    trim_start_tr: int
+    trim_end_tr: int
+    bold_z_path: str
+
+
+@dataclass(frozen=True)
+class RegressorAlignmentRecord:
+    """Summary for one model-run-layer regressor artifact."""
+
+    model_id: str
+    model_slug: str
+    run: int
+    tr_seconds: float
+    n_volumes_raw: int
+    n_tr_aligned: int
+    layer_idx: int
+    n_features: int
+    trim_start_tr: int
+    trim_end_tr: int
+    hrf_model: str
+    regressor_z_path: str
+
+
+def build_and_cache_alignment_inputs(
+    manifest_df: pd.DataFrame,
+    run_events_df: pd.DataFrame,
+    feature_summary_df: pd.DataFrame,
+    analysis_mask_path: Path,
+    output_dir: Path,
+    trim_start_tr: int,
+    trim_end_tr: int,
+    hrf_model: str,
+    overwrite: bool,
+    alignment_subjects: list[str] | None = None,
+) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, Any]]:
+    """Cache z-scored BOLD targets and HRF-convolved z-scored regressors."""
+    if manifest_df.empty:
+        raise ValueError("Manifest is empty; cannot build alignment inputs")
+    if run_events_df.empty:
+        raise ValueError("run_events_df is empty; cannot build regressors")
+    if feature_summary_df.empty:
+        raise ValueError("feature_summary_df is empty; feature extraction must run first")
+
+    required_manifest_columns = {"subject", "run", "tr_seconds", "n_volumes", "derivatives_bold_path"}
+    missing_manifest = required_manifest_columns.difference(manifest_df.columns)
+    if missing_manifest:
+        raise ValueError(f"manifest_df missing required columns: {sorted(missing_manifest)}")
+
+    required_feature_columns = {"model_id", "model_slug", "run", "features_npz_path"}
+    missing_feature = required_feature_columns.difference(feature_summary_df.columns)
+    if missing_feature:
+        raise ValueError(f"feature_summary_df missing required columns: {sorted(missing_feature)}")
+
+    analysis_mask_img = nib.load(str(analysis_mask_path))
+    analysis_mask_bool = analysis_mask_img.get_fdata() > 0.5
+
+    manifest_alignment_df = manifest_df
+    requested_subjects = [value for value in (alignment_subjects or []) if str(value).strip()]
+    if requested_subjects:
+        subject_set = {str(value) for value in requested_subjects}
+        manifest_alignment_df = manifest_df[manifest_df["subject"].isin(subject_set)].copy()
+        if manifest_alignment_df.empty:
+            raise ValueError(
+                "Alignment subject filter produced no rows. "
+                f"Requested subjects={sorted(subject_set)}"
+            )
+
+    output_dir = output_dir.resolve()
+    bold_output_dir = output_dir / "bold_z"
+    regressor_output_dir = output_dir / "regressors"
+    bold_output_dir.mkdir(parents=True, exist_ok=True)
+    regressor_output_dir.mkdir(parents=True, exist_ok=True)
+
+    bold_rows: list[BoldAlignmentRecord] = []
+
+    for row in manifest_alignment_df.itertuples(index=False):
+        subject = str(getattr(row, "subject"))
+        run = int(getattr(row, "run"))
+        tr_seconds = float(getattr(row, "tr_seconds"))
+        n_volumes = int(getattr(row, "n_volumes"))
+        bold_path = Path(str(getattr(row, "derivatives_bold_path")))
+
+        bold_z_path = bold_output_dir / f"{subject}_run-{run:02d}_bold_z.npy"
+        if bold_z_path.exists() and not overwrite:
+            aligned_bold = np.load(bold_z_path)
+        else:
+            bold_2d = _extract_masked_bold_2d(
+                bold_path=bold_path,
+                analysis_mask_bool=analysis_mask_bool,
+                analysis_mask_img=analysis_mask_img,
+            )
+
+            if bold_2d.shape[0] != n_volumes:
+                raise ValueError(
+                    f"BOLD volume mismatch for {subject} run {run}: "
+                    f"manifest={n_volumes}, loaded={bold_2d.shape[0]}"
+                )
+
+            aligned_bold = _trim_time_axis(
+                values=bold_2d,
+                trim_start_tr=trim_start_tr,
+                trim_end_tr=trim_end_tr,
+            )
+            aligned_bold = _zscore_columns(aligned_bold)
+            np.save(bold_z_path, aligned_bold)
+
+        bold_rows.append(
+            BoldAlignmentRecord(
+                subject=subject,
+                run=run,
+                tr_seconds=tr_seconds,
+                n_volumes_raw=n_volumes,
+                n_tr_aligned=int(aligned_bold.shape[0]),
+                n_voxels=int(aligned_bold.shape[1]),
+                trim_start_tr=int(trim_start_tr),
+                trim_end_tr=int(trim_end_tr),
+                bold_z_path=str(bold_z_path),
+            )
+        )
+
+    regressor_rows: list[RegressorAlignmentRecord] = []
+
+    # Compute run configuration keys from manifest; regressors depend on run + TR + n_volumes.
+    run_config_map: dict[int, list[tuple[float, int]]] = {}
+    for run, group_df in manifest_alignment_df.groupby("run"):
+        unique_pairs = sorted(
+            {(float(tr), int(n_vol)) for tr, n_vol in zip(group_df["tr_seconds"], group_df["n_volumes"])},
+            key=lambda pair: (pair[0], pair[1]),
+        )
+        run_config_map[int(run)] = unique_pairs
+
+    for feature_row in feature_summary_df.itertuples(index=False):
+        model_id = str(getattr(feature_row, "model_id"))
+        model_slug = str(getattr(feature_row, "model_slug"))
+        run = int(getattr(feature_row, "run"))
+        features_npz_path = Path(str(getattr(feature_row, "features_npz_path")))
+
+        if run not in run_config_map:
+            continue
+
+        run_events = run_events_df[run_events_df["run"] == run].sort_values("word_index")
+        onsets_s = run_events["onset_s"].to_numpy(dtype=np.float64)
+        offsets_s = run_events["offset_s"].to_numpy(dtype=np.float64)
+
+        feature_bundle = np.load(features_npz_path)
+        layer_keys = sorted(
+            [key for key in feature_bundle.files if key.startswith("layer_")],
+            key=lambda value: int(value.split("_")[1]),
+        )
+
+        for tr_seconds, n_volumes in run_config_map[run]:
+            tr_tag = _format_tr_for_filename(tr_seconds)
+
+            model_regressor_dir = regressor_output_dir / model_slug
+            model_regressor_dir.mkdir(parents=True, exist_ok=True)
+
+            for layer_key in layer_keys:
+                layer_idx = int(layer_key.split("_")[1])
+                layer_features = np.asarray(feature_bundle[layer_key], dtype=np.float32)
+
+                if layer_features.shape[0] != onsets_s.shape[0]:
+                    raise ValueError(
+                        f"Word count mismatch for model={model_id}, run={run}, layer={layer_idx}: "
+                        f"features={layer_features.shape[0]}, events={onsets_s.shape[0]}"
+                    )
+
+                regressor_z_path = (
+                    model_regressor_dir
+                    / f"run-{run:02d}_tr-{tr_tag}_nvol-{n_volumes}_layer-{layer_idx:03d}_regressor_z.npy"
+                )
+
+                if regressor_z_path.exists() and not overwrite:
+                    regressors_aligned = np.load(regressor_z_path)
+                else:
+                    regressors = compute_hrf_regressor_matrix(
+                        word_features=layer_features,
+                        onsets_s=onsets_s,
+                        offsets_s=offsets_s,
+                        tr_seconds=tr_seconds,
+                        n_volumes=n_volumes,
+                        hrf_model=hrf_model,
+                    )
+                    regressors_aligned = _trim_time_axis(
+                        values=regressors,
+                        trim_start_tr=trim_start_tr,
+                        trim_end_tr=trim_end_tr,
+                    )
+                    regressors_aligned = _zscore_columns(regressors_aligned)
+                    np.save(regressor_z_path, regressors_aligned)
+
+                regressor_rows.append(
+                    RegressorAlignmentRecord(
+                        model_id=model_id,
+                        model_slug=model_slug,
+                        run=run,
+                        tr_seconds=tr_seconds,
+                        n_volumes_raw=n_volumes,
+                        n_tr_aligned=int(regressors_aligned.shape[0]),
+                        layer_idx=layer_idx,
+                        n_features=int(regressors_aligned.shape[1]),
+                        trim_start_tr=int(trim_start_tr),
+                        trim_end_tr=int(trim_end_tr),
+                        hrf_model=hrf_model,
+                        regressor_z_path=str(regressor_z_path),
+                    )
+                )
+
+    bold_summary_df = pd.DataFrame([asdict(row) for row in bold_rows])
+    if not bold_summary_df.empty:
+        bold_summary_df = bold_summary_df.sort_values(["subject", "run"]).reset_index(drop=True)
+
+    regressor_summary_df = pd.DataFrame([asdict(row) for row in regressor_rows])
+    if not regressor_summary_df.empty:
+        regressor_summary_df = regressor_summary_df.sort_values(
+            ["model_slug", "run", "layer_idx", "tr_seconds", "n_volumes_raw"]
+        ).reset_index(drop=True)
+
+    alignment_qc: dict[str, Any] = {
+        "analysis_mask_path": str(analysis_mask_path),
+        "hrf_model": hrf_model,
+        "trim_start_tr": int(trim_start_tr),
+        "trim_end_tr": int(trim_end_tr),
+        "alignment_subjects": sorted({str(value) for value in manifest_alignment_df["subject"].tolist()}),
+        "n_bold_rows": int(len(bold_summary_df)),
+        "n_regressor_rows": int(len(regressor_summary_df)),
+    }
+
+    if not bold_summary_df.empty:
+        alignment_qc["bold_n_tr_min"] = int(bold_summary_df["n_tr_aligned"].min())
+        alignment_qc["bold_n_tr_max"] = int(bold_summary_df["n_tr_aligned"].max())
+        alignment_qc["bold_n_voxels_min"] = int(bold_summary_df["n_voxels"].min())
+        alignment_qc["bold_n_voxels_max"] = int(bold_summary_df["n_voxels"].max())
+
+    if not regressor_summary_df.empty:
+        alignment_qc["regressor_n_tr_min"] = int(regressor_summary_df["n_tr_aligned"].min())
+        alignment_qc["regressor_n_tr_max"] = int(regressor_summary_df["n_tr_aligned"].max())
+        alignment_qc["regressor_n_features_min"] = int(regressor_summary_df["n_features"].min())
+        alignment_qc["regressor_n_features_max"] = int(regressor_summary_df["n_features"].max())
+
+    return bold_summary_df, regressor_summary_df, alignment_qc

code/a1_pipeline/annotations.py

@@ -0,0 +1,258 @@
+"""Annotation harmonization for A1 baseline event tables."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from .constants import (
+    DEFAULT_MIXED_RUN_WORD_TABLE_FALLBACK_MAP,
+    DEFAULT_RUN_WORD_TABLE_MAP,
+)
+
+
+@dataclass(frozen=True)
+class AnnotationSourceResolution:
+    """Resolved source table for one run."""
+
+    run: int
+    source_word_table: str
+    annotation_used_mixed_fallback: bool
+    provenance: str
+
+
+REQUIRED_WORD_TABLE_COLUMNS: tuple[str, ...] = ("word", "onset", "offset")
+
+
+def _validate_required_columns(df: pd.DataFrame, table_name: str) -> None:
+    missing = [column for column in REQUIRED_WORD_TABLE_COLUMNS if column not in df.columns]
+    if missing:
+        raise ValueError(f"Annotation table {table_name} missing columns: {missing}")
+
+
+def _load_and_normalize_word_table(
+    annotation_dir: Path,
+    table_name: str,
+    time_scale_seconds: float,
+) -> pd.DataFrame:
+    table_path = annotation_dir / table_name
+    if not table_path.exists():
+        raise FileNotFoundError(f"Annotation table not found: {table_path}")
+
+    df = pd.read_csv(table_path)
+    _validate_required_columns(df, table_name=table_name)
+
+    out = df.copy()
+    out["word"] = out["word"].astype(str).fillna("").str.strip()
+    out = out[out["word"] != ""].reset_index(drop=True)
+
+    out["onset"] = pd.to_numeric(out["onset"], errors="coerce")
+    out["offset"] = pd.to_numeric(out["offset"], errors="coerce")
+
+    if out["onset"].isna().any() or out["offset"].isna().any():
+        raise ValueError(f"Annotation table {table_name} contains non-numeric onset/offset values")
+
+    out["onset_s"] = out["onset"].astype(float) * float(time_scale_seconds)
+    out["offset_s"] = out["offset"].astype(float) * float(time_scale_seconds)
+    out["duration_s"] = out["offset_s"] - out["onset_s"]
+    out["word_index"] = np.arange(len(out), dtype=np.int64)
+    out["source_word_table"] = table_name
+
+    return out[["word_index", "word", "onset_s", "offset_s", "duration_s", "source_word_table"]]
+
+
+def _validate_timing_table(df: pd.DataFrame, label: str) -> list[str]:
+    errors: list[str] = []
+
+    if (df["onset_s"] < 0).any():
+        errors.append(f"{label}: negative onset_s found")
+
+    if (df["offset_s"] < 0).any():
+        errors.append(f"{label}: negative offset_s found")
+
+    if (df["duration_s"] < 0).any():
+        errors.append(f"{label}: negative duration_s found")
+
+    if (df["offset_s"] < df["onset_s"]).any():
+        errors.append(f"{label}: offset_s earlier than onset_s")
+
+    onset_diff = df["onset_s"].diff().dropna()
+    if (onset_diff < 0).any():
+        errors.append(f"{label}: onset_s is not monotonic non-decreasing")
+
+    offset_diff = df["offset_s"].diff().dropna()
+    if (offset_diff < 0).any():
+        errors.append(f"{label}: offset_s is not monotonic non-decreasing")
+
+    return errors
+
+
+def _resolve_run_source(
+    run: int,
+    enable_mixed_fallback: bool,
+    run_word_table_map: dict[int, str | None],
+    mixed_fallback_map: dict[int, str],
+) -> AnnotationSourceResolution:
+    source_table = run_word_table_map.get(run)
+    if source_table is not None:
+        return AnnotationSourceResolution(
+            run=run,
+            source_word_table=source_table,
+            annotation_used_mixed_fallback=False,
+            provenance=f"fixed_run_source:{source_table}",
+        )
+
+    if enable_mixed_fallback and run in mixed_fallback_map:
+        fallback_table = mixed_fallback_map[run]
+        return AnnotationSourceResolution(
+            run=run,
+            source_word_table=fallback_table,
+            annotation_used_mixed_fallback=True,
+            provenance=f"mixed_run_fallback_source:{fallback_table}",
+        )
+
+    raise ValueError(
+        "No annotation source available for run "
+        f"{run}. Provide a direct run mapping or enable mixed fallback."
+    )
+
+
+def build_harmonized_annotation_tables(
+    manifest_df: pd.DataFrame,
+    annotation_dir: Path,
+    time_scale_seconds: float,
+    enable_mixed_fallback: bool,
+    run_word_table_map: dict[int, str | None] | None = None,
+    mixed_fallback_map: dict[int, str] | None = None,
+) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, Any]]:
+    """Build run-level templates and subject-run unified annotation tables."""
+    if manifest_df.empty:
+        raise ValueError("Manifest is empty; cannot harmonize annotations")
+
+    required_columns = {
+        "subject",
+        "run",
+        "condition_fixed",
+        "condition_effective",
+        "speaker_stream",
+        "used_mixed_fallback",
+    }
+    missing = required_columns.difference(manifest_df.columns)
+    if missing:
+        raise ValueError(f"Manifest missing required columns for annotation harmonization: {sorted(missing)}")
+
+    annotation_dir = annotation_dir.resolve()
+    run_word_table_map = run_word_table_map or DEFAULT_RUN_WORD_TABLE_MAP
+    mixed_fallback_map = mixed_fallback_map or DEFAULT_MIXED_RUN_WORD_TABLE_FALLBACK_MAP
+
+    source_cache: dict[str, pd.DataFrame] = {}
+    run_template_rows: list[pd.DataFrame] = []
+    source_resolutions: list[AnnotationSourceResolution] = []
+
+    runs = sorted({int(value) for value in manifest_df["run"].tolist()})
+
+    for run in runs:
+        resolution = _resolve_run_source(
+            run=run,
+            enable_mixed_fallback=enable_mixed_fallback,
+            run_word_table_map=run_word_table_map,
+            mixed_fallback_map=mixed_fallback_map,
+        )
+        source_resolutions.append(resolution)
+
+        if resolution.source_word_table not in source_cache:
+            source_cache[resolution.source_word_table] = _load_and_normalize_word_table(
+                annotation_dir=annotation_dir,
+                table_name=resolution.source_word_table,
+                time_scale_seconds=time_scale_seconds,
+            )
+
+        template_df = source_cache[resolution.source_word_table].copy()
+        template_df["run"] = int(run)
+        template_df["annotation_used_mixed_fallback"] = bool(resolution.annotation_used_mixed_fallback)
+        template_df["provenance"] = resolution.provenance
+
+        run_template_rows.append(template_df)
+
+    run_events_df = pd.concat(run_template_rows, ignore_index=True)
+
+    template_errors: list[str] = []
+    for run, run_df in run_events_df.groupby("run"):
+        template_errors.extend(_validate_timing_table(run_df, label=f"run_template_run{run}"))
+
+    if template_errors:
+        raise ValueError("Annotation template validation failed: " + "; ".join(template_errors))
+
+    merged_rows: list[pd.DataFrame] = []
+    for row in manifest_df.itertuples(index=False):
+        subject = str(getattr(row, "subject"))
+        run = int(getattr(row, "run"))
+
+        run_template = run_events_df[run_events_df["run"] == run].copy()
+        run_template["subject"] = subject
+        run_template["condition_fixed"] = str(getattr(row, "condition_fixed"))
+        run_template["condition_effective"] = str(getattr(row, "condition_effective"))
+        run_template["speaker_stream"] = str(getattr(row, "speaker_stream"))
+        run_template["used_mixed_fallback"] = bool(getattr(row, "used_mixed_fallback"))
+
+        merged_rows.append(run_template)
+
+    unified_df = pd.concat(merged_rows, ignore_index=True)
+    unified_df = unified_df[
+        [
+            "subject",
+            "run",
+            "word_index",
+            "word",
+            "onset_s",
+            "offset_s",
+            "duration_s",
+            "condition_fixed",
+            "condition_effective",
+            "speaker_stream",
+            "used_mixed_fallback",
+            "annotation_used_mixed_fallback",
+            "source_word_table",
+            "provenance",
+        ]
+    ]
+
+    unified_errors: list[str] = []
+    for (subject, run), group_df in unified_df.groupby(["subject", "run"]):
+        unified_errors.extend(_validate_timing_table(group_df, label=f"unified_{subject}_run{run}"))
+
+    if unified_errors:
+        raise ValueError("Unified annotation validation failed: " + "; ".join(unified_errors))
+
+    source_resolution_df = pd.DataFrame([asdict(value) for value in source_resolutions])
+    source_resolution_df = source_resolution_df.sort_values(["run"]).reset_index(drop=True)
+
+    run_word_counts = (
+        run_events_df.groupby("run")["word_index"].max().add(1).astype(int).to_dict()
+        if not run_events_df.empty
+        else {}
+    )
+
+    annotation_qc: dict[str, Any] = {
+        "annotation_dir": str(annotation_dir),
+        "time_scale_seconds": float(time_scale_seconds),
+        "enable_mixed_fallback": bool(enable_mixed_fallback),
+        "n_manifest_rows": int(len(manifest_df)),
+        "n_run_templates": int(run_events_df["run"].nunique()) if not run_events_df.empty else 0,
+        "n_unified_rows": int(len(unified_df)),
+        "run_word_counts": {str(run): int(count) for run, count in sorted(run_word_counts.items())},
+        "source_resolution": [asdict(value) for value in source_resolutions],
+    }
+
+    if not unified_df.empty:
+        annotation_qc["duration_s_min"] = float(unified_df["duration_s"].min())
+        annotation_qc["duration_s_max"] = float(unified_df["duration_s"].max())
+
+    run_events_df = run_events_df.sort_values(["run", "word_index"]).reset_index(drop=True)
+    unified_df = unified_df.sort_values(["subject", "run", "word_index"]).reset_index(drop=True)
+
+    return run_events_df, unified_df, source_resolution_df, annotation_qc

code/a1_pipeline/constants.py

@@ -0,0 +1,71 @@
+"""Constants and shared defaults for A1 SI baseline bootstrap."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+DEFAULT_ALLOWED_RUNS: tuple[int, ...] = (1, 2, 3, 4)
+DEFAULT_TIME_SCALE_SECONDS: float = 0.01
+DEFAULT_HRF_LAG_SECONDS: float = 5.0
+
+# Locked baseline models from project scope.
+DEFAULT_MODEL_IDS: tuple[str, ...] = (
+    "Qwen/Qwen3-0.6B",
+    "meta-llama/Llama-3.2-1B",
+    "GSAI-ML/LLaDA-8B-Instruct",
+)
+
+# Run-level word timing tables available in ds005345 annotations.
+DEFAULT_RUN_WORD_TABLE_MAP: dict[int, str | None] = {
+    1: "single_female_word_information.csv",
+    2: "single_male_word_information.csv",
+    3: None,
+    4: None,
+}
+
+# Fallback sources for mixed-condition runs when dedicated mixed word timings are absent.
+DEFAULT_MIXED_RUN_WORD_TABLE_FALLBACK_MAP: dict[int, str] = {
+    3: "single_female_word_information.csv",
+    4: "single_male_word_information.csv",
+}
+
+
+@dataclass(frozen=True)
+class RunCondition:
+    """Condition labels attached to each run in the baseline mapping."""
+
+    condition_fixed: str
+    speaker_stream: str
+    condition_fallback: str | None = None
+
+
+DEFAULT_RUN_CONDITION_MAP: dict[int, RunCondition] = {
+    1: RunCondition(condition_fixed="single_female", speaker_stream="female"),
+    2: RunCondition(condition_fixed="single_male", speaker_stream="male"),
+    3: RunCondition(
+        condition_fixed="mixed_female",
+        speaker_stream="mixed_female",
+        condition_fallback="mixed",
+    ),
+    4: RunCondition(
+        condition_fixed="mixed_male",
+        speaker_stream="mixed_male",
+        condition_fallback="mixed",
+    ),
+}
+
+
+def resolve_run_condition(run: int, enable_mixed_fallback: bool) -> tuple[str, str, str, bool]:
+    """Resolve fixed/effective condition labels for one run.
+
+    Returns:
+        (condition_fixed, condition_effective, speaker_stream, used_mixed_fallback)
+    """
+    if run not in DEFAULT_RUN_CONDITION_MAP:
+        raise KeyError(f"Run {run} is not present in condition map")
+
+    info = DEFAULT_RUN_CONDITION_MAP[run]
+    use_fallback = bool(enable_mixed_fallback and info.condition_fallback is not None)
+    condition_effective = info.condition_fallback if use_fallback else info.condition_fixed
+
+    return info.condition_fixed, condition_effective, info.speaker_stream, use_fallback

code/a1_pipeline/features.py

@@ -0,0 +1,651 @@
+"""Frozen feature extraction wrappers for A1 baseline models."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import json
+from pathlib import Path
+import re
+from typing import Any
+import warnings
+
+import numpy as np
+import pandas as pd
+
+
+def slugify_model_id(model_id: str) -> str:
+    cleaned = re.sub(r"[^a-zA-Z0-9._-]+", "_", model_id.strip())
+    return cleaned.strip("_") or "unknown_model"
+
+
+def _is_llada_model_id(model_id: str) -> bool:
+    return "llada" in model_id.lower()
+
+
+def _apply_llada_compat_patches(model_id: str, local_files_only: bool) -> None:
+    """Apply compatibility patches for LLaDA remote-code models."""
+    try:
+        import transformers.modeling_utils as modeling_utils
+
+        if not hasattr(modeling_utils.PreTrainedModel, "all_tied_weights_keys"):
+            modeling_utils.PreTrainedModel.all_tied_weights_keys = {}
+        elif not isinstance(modeling_utils.PreTrainedModel.all_tied_weights_keys, dict):
+            modeling_utils.PreTrainedModel.all_tied_weights_keys = {}
+    except Exception:
+        # Best effort; continue with standard load flow.
+        pass
+
+    try:
+        from transformers import AutoConfig
+        from transformers.dynamic_module_utils import get_class_from_dynamic_module
+
+        config = AutoConfig.from_pretrained(
+            model_id,
+            trust_remote_code=True,
+            local_files_only=local_files_only,
+        )
+        auto_map = getattr(config, "auto_map", None) or {}
+        class_ref = auto_map.get("AutoModelForCausalLM")
+        if not class_ref:
+            return
+
+        model_cls = get_class_from_dynamic_module(
+            class_ref,
+            model_id,
+            local_files_only=local_files_only,
+        )
+
+        original_tie = getattr(model_cls, "tie_weights", None)
+        if original_tie is None or getattr(original_tie, "_a1_llada_safe_wrapped", False):
+            return
+
+        def _safe_tie_weights(self: Any, *args: Any, **kwargs: Any) -> Any:
+            kwargs.pop("missing_keys", None)
+            kwargs.pop("recompute_mapping", None)
+            try:
+                return original_tie(self, *args, **kwargs)
+            except TypeError as exc:
+                if "unexpected keyword argument" in str(exc):
+                    return original_tie(self)
+                raise
+
+        _safe_tie_weights._a1_llada_safe_wrapped = True
+        setattr(model_cls, "tie_weights", _safe_tie_weights)
+    except Exception:
+        # Best effort; continue with standard load flow.
+        pass
+
+
+def _normalize_all_tied_weights_keys(model: Any) -> None:
+    """Normalize missing/incompatible all_tied_weights_keys on loaded models."""
+    try:
+        tied = getattr(model, "all_tied_weights_keys", None)
+        if tied is None:
+            model.all_tied_weights_keys = {}
+        elif callable(tied):
+            value = tied()
+            model.all_tied_weights_keys = value if isinstance(value, dict) else {}
+        elif not isinstance(tied, dict):
+            model.all_tied_weights_keys = {}
+    except Exception:
+        pass
+
+
+def _load_causal_lm(
+    model_id: str,
+    model_dtype: Any,
+    local_files_only: bool,
+) -> Any:
+    from transformers import AutoModelForCausalLM
+
+    is_llada = _is_llada_model_id(model_id)
+    if is_llada:
+        _apply_llada_compat_patches(model_id=model_id, local_files_only=local_files_only)
+
+    load_kwargs: dict[str, Any] = {
+        "output_hidden_states": True,
+        "dtype": model_dtype,
+        "local_files_only": local_files_only,
+    }
+    if is_llada:
+        load_kwargs["trust_remote_code"] = True
+
+    try:
+        model = AutoModelForCausalLM.from_pretrained(model_id, **load_kwargs)
+    except AttributeError as exc:
+        if not (is_llada and "all_tied_weights_keys" in str(exc)):
+            raise
+
+        _apply_llada_compat_patches(model_id=model_id, local_files_only=local_files_only)
+        try:
+            model = AutoModelForCausalLM.from_pretrained(
+                model_id,
+                low_cpu_mem_usage=False,
+                **load_kwargs,
+            )
+        except TypeError:
+            model = AutoModelForCausalLM.from_pretrained(model_id, **load_kwargs)
+
+    _normalize_all_tied_weights_keys(model)
+    if hasattr(model, "config") and not hasattr(model.config, "use_cache"):
+        try:
+            model.config.use_cache = False
+        except Exception:
+            pass
+
+    return model
+
+
+@dataclass(frozen=True)
+class FeatureExtractionRecord:
+    """Summary row for cached run-level feature extraction."""
+
+    model_id: str
+    model_slug: str
+    run: int
+    n_words: int
+    n_layers: int
+    hidden_dim: int
+    unmatched_words: int
+    max_words_per_chunk: int
+    dry_run: bool
+    device: str
+    features_npz_path: str
+    metadata_json_path: str
+
+
+def _parse_model_max_length(model: Any, tokenizer: Any) -> int:
+    candidate_values: list[int] = []
+
+    max_position_embeddings = getattr(getattr(model, "config", None), "max_position_embeddings", None)
+    if isinstance(max_position_embeddings, int) and max_position_embeddings > 0:
+        candidate_values.append(int(max_position_embeddings))
+
+    tokenizer_max = getattr(tokenizer, "model_max_length", None)
+    if isinstance(tokenizer_max, int) and 0 < tokenizer_max < 100000:
+        candidate_values.append(int(tokenizer_max))
+
+    if candidate_values:
+        return int(min(candidate_values))
+
+    return 4096
+
+
+def _build_text_and_word_spans(words: list[str]) -> tuple[str, list[tuple[int, int]]]:
+    safe_words = [str(word) for word in words]
+
+    spans: list[tuple[int, int]] = []
+    cursor = 0
+    chunks: list[str] = []
+
+    for idx, word in enumerate(safe_words):
+        start = cursor
+        end = start + len(word)
+        spans.append((start, end))
+        chunks.append(word)
+
+        cursor = end
+        if idx < len(safe_words) - 1:
+            chunks.append(" ")
+            cursor += 1
+
+    return "".join(chunks), spans
+
+
+def _map_tokens_to_words(
+    token_offsets: list[tuple[int, int]],
+    word_spans: list[tuple[int, int]],
+) -> tuple[list[list[int]], int]:
+    token_to_word: list[list[int]] = [[] for _ in range(len(word_spans))]
+
+    valid_token_centers: list[tuple[int, float]] = []
+
+    for token_index, (token_start, token_end) in enumerate(token_offsets):
+        if token_end <= token_start:
+            continue
+
+        valid_token_centers.append((token_index, (token_start + token_end) * 0.5))
+
+        for word_index, (word_start, word_end) in enumerate(word_spans):
+            overlaps = token_end > word_start and token_start < word_end
+            if overlaps:
+                token_to_word[word_index].append(token_index)
+                break
+
+    unmatched_words = 0
+    if valid_token_centers:
+        centers = np.array([center for _, center in valid_token_centers], dtype=np.float64)
+        indices = [idx for idx, _ in valid_token_centers]
+
+        for word_index, word_tokens in enumerate(token_to_word):
+            if word_tokens:
+                continue
+
+            unmatched_words += 1
+            word_start, word_end = word_spans[word_index]
+            word_center = (word_start + word_end) * 0.5
+            nearest_idx = int(np.argmin(np.abs(centers - word_center)))
+            token_to_word[word_index] = [indices[nearest_idx]]
+    else:
+        unmatched_words = len(token_to_word)
+
+    return token_to_word, unmatched_words
+
+
+def _extract_chunk_features(
+    words_chunk: list[str],
+    model: Any,
+    tokenizer: Any,
+    device: str,
+    selected_layers: list[int],
+) -> tuple[dict[int, np.ndarray], dict[str, Any]]:
+    import torch
+
+    if not getattr(tokenizer, "is_fast", False):
+        raise RuntimeError(
+            "Fast tokenizer with offset mapping is required for word-level aggregation."
+        )
+
+    text, word_spans = _build_text_and_word_spans(words_chunk)
+    max_length = _parse_model_max_length(model=model, tokenizer=tokenizer)
+
+    encoded = tokenizer(
+        text,
+        return_tensors="pt",
+        return_offsets_mapping=True,
+        truncation=True,
+        max_length=max_length,
+        add_special_tokens=True,
+        return_overflowing_tokens=True,
+    )
+
+    input_ids = encoded["input_ids"]
+    if input_ids.shape[0] != 1:
+        raise RuntimeError(
+            "Tokenizer overflow produced multiple windows. "
+            "Decrease --max-words-per-chunk."
+        )
+
+    offset_mapping = encoded.pop("offset_mapping")[0].cpu().numpy().tolist()
+
+    model_inputs: dict[str, Any] = {}
+    for key, value in encoded.items():
+        if key in {"overflow_to_sample_mapping", "num_truncated_tokens"}:
+            continue
+        model_inputs[key] = value.to(device)
+
+    with torch.no_grad():
+        try:
+            outputs = model(**model_inputs, output_hidden_states=True, use_cache=False)
+        except TypeError as exc:
+            if "unexpected keyword argument" not in str(exc) or "use_cache" not in str(exc):
+                raise
+            outputs = model(**model_inputs, output_hidden_states=True)
+
+    hidden_states = outputs.hidden_states
+    if hidden_states is None:
+        raise RuntimeError("Model did not return hidden states")
+
+    token_to_word, unmatched_words = _map_tokens_to_words(
+        token_offsets=[(int(start), int(end)) for start, end in offset_mapping],
+        word_spans=word_spans,
+    )
+
+    per_layer_features: dict[int, np.ndarray] = {}
+    hidden_dim = int(hidden_states[selected_layers[0]].shape[-1])
+
+    for layer_idx in selected_layers:
+        layer_tokens = hidden_states[layer_idx][0].detach().float().cpu().numpy()
+        layer_word = np.zeros((len(words_chunk), hidden_dim), dtype=np.float32)
+
+        for word_index, token_indices in enumerate(token_to_word):
+            valid = [idx for idx in token_indices if 0 <= idx < layer_tokens.shape[0]]
+            if not valid:
+                continue
+            layer_word[word_index] = np.mean(layer_tokens[valid], axis=0, dtype=np.float32)
+
+        per_layer_features[layer_idx] = layer_word
+
+    diagnostics = {
+        "n_words": int(len(words_chunk)),
+        "n_tokens": int(len(offset_mapping)),
+        "unmatched_words": int(unmatched_words),
+    }
+    return per_layer_features, diagnostics
+
+
+def _extract_real_features_for_run(
+    words: list[str],
+    model: Any,
+    tokenizer: Any,
+    device: str,
+    layer_indices: list[int] | None,
+    max_words_per_chunk: int,
+) -> tuple[dict[int, np.ndarray], dict[str, Any]]:
+    if max_words_per_chunk <= 0:
+        raise ValueError("max_words_per_chunk must be positive")
+
+    if not words:
+        raise ValueError("Cannot extract features from an empty word list")
+
+    n_all_layers = int(getattr(model.config, "num_hidden_layers", 0)) + 1
+    selected_layers = layer_indices if layer_indices is not None else list(range(n_all_layers))
+
+    for layer_idx in selected_layers:
+        if layer_idx < 0 or layer_idx >= n_all_layers:
+            raise ValueError(f"Layer index {layer_idx} out of range [0, {n_all_layers - 1}]")
+
+    chunk_outputs: dict[int, list[np.ndarray]] = {layer_idx: [] for layer_idx in selected_layers}
+    total_unmatched_words = 0
+    total_tokens = 0
+
+    start = 0
+    while start < len(words):
+        stop = min(start + max_words_per_chunk, len(words))
+        chunk_words = words[start:stop]
+
+        per_layer_chunk, chunk_diag = _extract_chunk_features(
+            words_chunk=chunk_words,
+            model=model,
+            tokenizer=tokenizer,
+            device=device,
+            selected_layers=selected_layers,
+        )
+
+        total_unmatched_words += int(chunk_diag["unmatched_words"])
+        total_tokens += int(chunk_diag["n_tokens"])
+
+        for layer_idx in selected_layers:
+            chunk_outputs[layer_idx].append(per_layer_chunk[layer_idx])
+
+        start = stop
+
+    outputs: dict[int, np.ndarray] = {
+        layer_idx: np.concatenate(chunks, axis=0).astype(np.float32)
+        for layer_idx, chunks in chunk_outputs.items()
+    }
+
+    hidden_dim = int(outputs[selected_layers[0]].shape[1])
+    diagnostics = {
+        "n_words": int(len(words)),
+        "n_layers": int(len(selected_layers)),
+        "hidden_dim": hidden_dim,
+        "unmatched_words": int(total_unmatched_words),
+        "n_tokens_total": int(total_tokens),
+        "selected_layers": selected_layers,
+    }
+    return outputs, diagnostics
+
+
+def _extract_dry_run_features_for_run(
+    words: list[str],
+    model_id: str,
+    run: int,
+    dry_run_n_layers: int,
+    dry_run_hidden_dim: int,
+) -> tuple[dict[int, np.ndarray], dict[str, Any]]:
+    if dry_run_n_layers <= 0:
+        raise ValueError("dry_run_n_layers must be positive")
+    if dry_run_hidden_dim <= 0:
+        raise ValueError("dry_run_hidden_dim must be positive")
+
+    n_words = len(words)
+    seed = abs(hash((model_id, int(run), n_words))) % (2**32)
+    rng = np.random.default_rng(seed)
+
+    outputs: dict[int, np.ndarray] = {}
+    for layer_idx in range(dry_run_n_layers):
+        features = rng.standard_normal(size=(n_words, dry_run_hidden_dim)).astype(np.float32)
+        outputs[layer_idx] = features
+
+    diagnostics = {
+        "n_words": int(n_words),
+        "n_layers": int(dry_run_n_layers),
+        "hidden_dim": int(dry_run_hidden_dim),
+        "unmatched_words": 0,
+        "n_tokens_total": int(n_words),
+        "selected_layers": list(range(dry_run_n_layers)),
+    }
+    return outputs, diagnostics
+
+
+def extract_and_cache_run_level_features(
+    run_events_df: pd.DataFrame,
+    model_ids: list[str],
+    output_dir: Path,
+    layer_indices: list[int] | None,
+    max_words_per_chunk: int,
+    dry_run: bool,
+    dry_run_n_layers: int,
+    dry_run_hidden_dim: int,
+    device: str,
+    local_files_only: bool,
+    overwrite: bool,
+) -> tuple[pd.DataFrame, dict[str, Any]]:
+    """Extract and cache run-level word features for each model."""
+    if run_events_df.empty:
+        raise ValueError("run_events_df is empty; cannot extract features")
+
+    required_columns = {"run", "word_index", "word", "onset_s", "offset_s"}
+    missing = required_columns.difference(run_events_df.columns)
+    if missing:
+        raise ValueError(f"run_events_df missing required columns: {sorted(missing)}")
+
+    output_dir = output_dir.resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    runs = sorted({int(run) for run in run_events_df["run"].tolist()})
+
+    summary_rows: list[FeatureExtractionRecord] = []
+
+    for model_id in model_ids:
+        model_slug = slugify_model_id(model_id)
+        model_output_dir = output_dir / model_slug
+        model_output_dir.mkdir(parents=True, exist_ok=True)
+
+        resolved_device = "dry-run"
+        model = None
+        tokenizer = None
+
+        if not dry_run:
+            import torch
+            from transformers import AutoTokenizer
+
+            is_llada = _is_llada_model_id(model_id)
+
+            if device == "auto":
+                resolved_device = "cuda" if torch.cuda.is_available() else "cpu"
+            else:
+                resolved_device = device
+
+            model_dtype = torch.float16 if resolved_device.startswith("cuda") else torch.float32
+
+            tokenizer = AutoTokenizer.from_pretrained(
+                model_id,
+                use_fast=True,
+                local_files_only=local_files_only,
+                trust_remote_code=is_llada,
+            )
+            if tokenizer.pad_token is None:
+                tokenizer.pad_token = tokenizer.eos_token
+
+            model = _load_causal_lm(
+                model_id,
+                model_dtype=model_dtype,
+                local_files_only=local_files_only,
+            )
+
+            try:
+                model.to(resolved_device)
+            except torch.OutOfMemoryError as exc:
+                if device != "auto" or not resolved_device.startswith("cuda"):
+                    raise RuntimeError(
+                        "CUDA out of memory while moving model to device. "
+                        "Retry with --feature-device cpu or reduce model size."
+                    ) from exc
+
+                warnings.warn(
+                    f"CUDA OOM while loading model {model_id}; falling back to CPU.",
+                    RuntimeWarning,
+                )
+
+                try:
+                    del model
+                    torch.cuda.empty_cache()
+                except Exception:
+                    pass
+
+                resolved_device = "cpu"
+                model_dtype = torch.float32
+                model = _load_causal_lm(
+                    model_id,
+                    model_dtype=model_dtype,
+                    local_files_only=local_files_only,
+                )
+                model.to(resolved_device)
+
+            model.eval()
+
+        for run in runs:
+            run_df = run_events_df[run_events_df["run"] == run].sort_values("word_index")
+            words = run_df["word"].astype(str).tolist()
+
+            npz_path = model_output_dir / f"run-{run:02d}_features.npz"
+            metadata_path = model_output_dir / f"run-{run:02d}_metadata.json"
+
+            if npz_path.exists() and metadata_path.exists() and not overwrite:
+                with metadata_path.open("r", encoding="utf-8") as handle:
+                    metadata = json.load(handle)
+
+                summary_rows.append(
+                    FeatureExtractionRecord(
+                        model_id=model_id,
+                        model_slug=model_slug,
+                        run=int(run),
+                        n_words=int(metadata["n_words"]),
+                        n_layers=int(metadata["n_layers"]),
+                        hidden_dim=int(metadata["hidden_dim"]),
+                        unmatched_words=int(metadata.get("unmatched_words", 0)),
+                        max_words_per_chunk=int(metadata.get("max_words_per_chunk", max_words_per_chunk)),
+                        dry_run=bool(metadata.get("dry_run", dry_run)),
+                        device=str(metadata.get("device", resolved_device)),
+                        features_npz_path=str(npz_path),
+                        metadata_json_path=str(metadata_path),
+                    )
+                )
+                continue
+
+            if dry_run:
+                feature_map, diagnostics = _extract_dry_run_features_for_run(
+                    words=words,
+                    model_id=model_id,
+                    run=int(run),
+                    dry_run_n_layers=dry_run_n_layers,
+                    dry_run_hidden_dim=dry_run_hidden_dim,
+                )
+            else:
+                assert model is not None
+                assert tokenizer is not None
+                try:
+                    feature_map, diagnostics = _extract_real_features_for_run(
+                        words=words,
+                        model=model,
+                        tokenizer=tokenizer,
+                        device=resolved_device,
+                        layer_indices=layer_indices,
+                        max_words_per_chunk=max_words_per_chunk,
+                    )
+                except torch.OutOfMemoryError as exc:
+                    if device != "auto" or not resolved_device.startswith("cuda"):
+                        raise RuntimeError(
+                            "CUDA out of memory during feature extraction. "
+                            "Retry with --feature-device cpu or reduce --max-words-per-chunk."
+                        ) from exc
+
+                    warnings.warn(
+                        (
+                            f"CUDA OOM during feature extraction for model {model_id}, run={run}; "
+                            "falling back to CPU and retrying."
+                        ),
+                        RuntimeWarning,
+                    )
+
+                    torch.cuda.empty_cache()
+                    resolved_device = "cpu"
+                    model.to(resolved_device)
+
+                    feature_map, diagnostics = _extract_real_features_for_run(
+                        words=words,
+                        model=model,
+                        tokenizer=tokenizer,
+                        device=resolved_device,
+                        layer_indices=layer_indices,
+                        max_words_per_chunk=max_words_per_chunk,
+                    )
+
+            np.savez(
+                npz_path,
+                **{f"layer_{layer_idx}": values for layer_idx, values in feature_map.items()},
+                onset_s=run_df["onset_s"].to_numpy(dtype=np.float32),
+                offset_s=run_df["offset_s"].to_numpy(dtype=np.float32),
+                word_index=run_df["word_index"].to_numpy(dtype=np.int64),
+            )
+
+            metadata = {
+                "model_id": model_id,
+                "model_slug": model_slug,
+                "run": int(run),
+                "n_words": int(diagnostics["n_words"]),
+                "n_layers": int(diagnostics["n_layers"]),
+                "hidden_dim": int(diagnostics["hidden_dim"]),
+                "unmatched_words": int(diagnostics["unmatched_words"]),
+                "n_tokens_total": int(diagnostics["n_tokens_total"]),
+                "selected_layers": [int(value) for value in diagnostics["selected_layers"]],
+                "max_words_per_chunk": int(max_words_per_chunk),
+                "dry_run": bool(dry_run),
+                "device": str(resolved_device),
+                "features_npz_path": str(npz_path),
+            }
+            with metadata_path.open("w", encoding="utf-8") as handle:
+                json.dump(metadata, handle, indent=2, sort_keys=True)
+
+            summary_rows.append(
+                FeatureExtractionRecord(
+                    model_id=model_id,
+                    model_slug=model_slug,
+                    run=int(run),
+                    n_words=int(diagnostics["n_words"]),
+                    n_layers=int(diagnostics["n_layers"]),
+                    hidden_dim=int(diagnostics["hidden_dim"]),
+                    unmatched_words=int(diagnostics["unmatched_words"]),
+                    max_words_per_chunk=int(max_words_per_chunk),
+                    dry_run=bool(dry_run),
+                    device=str(resolved_device),
+                    features_npz_path=str(npz_path),
+                    metadata_json_path=str(metadata_path),
+                )
+            )
+
+        if model is not None:
+            del model
+            del tokenizer
+
+    summary_df = pd.DataFrame([asdict(row) for row in summary_rows])
+    if not summary_df.empty:
+        summary_df = summary_df.sort_values(["model_slug", "run"]).reset_index(drop=True)
+
+    feature_qc: dict[str, Any] = {
+        "n_models": int(len({row.model_slug for row in summary_rows})),
+        "n_model_run_rows": int(len(summary_rows)),
+        "dry_run": bool(dry_run),
+        "max_words_per_chunk": int(max_words_per_chunk),
+    }
+
+    if not summary_df.empty:
+        feature_qc["n_layers_min"] = int(summary_df["n_layers"].min())
+        feature_qc["n_layers_max"] = int(summary_df["n_layers"].max())
+        feature_qc["hidden_dim_min"] = int(summary_df["hidden_dim"].min())
+        feature_qc["hidden_dim_max"] = int(summary_df["hidden_dim"].max())
+        feature_qc["unmatched_words_total"] = int(summary_df["unmatched_words"].sum())
+
+    return summary_df, feature_qc

code/a1_pipeline/io_utils.py

@@ -0,0 +1,17 @@
+"""Simple I/O helpers for A1 bootstrap artifacts."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def ensure_directory(path: Path) -> Path:
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def write_json(path: Path, payload: dict[str, Any]) -> None:
+    with path.open("w", encoding="utf-8") as handle:
+        json.dump(payload, handle, indent=2, sort_keys=True)

code/a1_pipeline/manifest.py

@@ -0,0 +1,331 @@
+"""Manifest creation and integrity checks for ds005345 derivatives."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import json
+from pathlib import Path
+import re
+from typing import Any, Iterable
+
+import nibabel as nib
+import pandas as pd
+
+from .constants import resolve_run_condition
+
+# Only multitalker preprocessed BOLD files are valid candidates for A1.
+MULTITALKER_BOLD_RE = re.compile(
+    r"^(sub-\d+)_task-multitalker_run-(\d+)_desc-preproc_bold\.nii\.gz$"
+)
+
+
+@dataclass(frozen=True)
+class ManifestRecord:
+    """Accepted subject-run record used by later pipeline phases."""
+
+    subject: str
+    run: int
+    condition_fixed: str
+    condition_effective: str
+    speaker_stream: str
+    used_mixed_fallback: bool
+    derivatives_bold_path: str
+    raw_bold_json_path: str
+    tr_seconds: float
+    n_volumes: int
+
+
+@dataclass(frozen=True)
+class RejectRecord:
+    """Rejected candidate with explicit reason for auditability."""
+
+    derivatives_bold_path: str
+    folder_subject: str
+    filename_subject: str
+    run: int | None
+    reason: str
+    details: str
+
+
+def _safe_read_json(path: Path) -> dict[str, Any] | None:
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            payload = json.load(handle)
+        if isinstance(payload, dict):
+            return payload
+        return None
+    except Exception:
+        return None
+
+
+def _extract_repetition_time_seconds(payload: dict[str, Any]) -> float | None:
+    # BIDS RepetitionTime is in seconds.
+    for key in ("RepetitionTime", "RepetitionTimeExcitation"):
+        value = payload.get(key)
+        if value is None:
+            continue
+        try:
+            tr = float(value)
+            if tr > 0:
+                return tr
+        except (TypeError, ValueError):
+            continue
+    return None
+
+
+def _read_n_volumes(path: Path, deep_integrity_check: bool) -> int | None:
+    try:
+        image = nib.load(str(path))
+        shape = image.shape
+        if len(shape) != 4:
+            return None
+        n_volumes = int(shape[3])
+
+        if n_volumes <= 0:
+            return None
+
+        if deep_integrity_check:
+            # Force-read the last volume to catch truncated gzip streams early.
+            import numpy as np
+
+            _ = np.asanyarray(image.dataobj[..., n_volumes - 1])
+
+        return n_volumes
+    except Exception:
+        return None
+
+
+def _iter_candidate_bold_files(derivatives_dir: Path) -> list[Path]:
+    paths: list[Path] = []
+    for subject_dir in sorted(derivatives_dir.glob("sub-*")):
+        func_dir = subject_dir / "func"
+        if not func_dir.exists():
+            continue
+        paths.extend(sorted(func_dir.glob("*_desc-preproc_bold.nii.gz")))
+    return paths
+
+
+def build_derivatives_manifest(
+    derivatives_dir: Path,
+    data_dir: Path,
+    allowed_runs: Iterable[int],
+    enable_mixed_fallback: bool,
+    excluded_subjects: Iterable[str] | None = None,
+    deep_nifti_integrity_check: bool = False,
+) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, Any]]:
+    """Build accepted/rejected manifests with strict anti-leakage checks.
+
+    Checks enforced:
+    - filename must match multitalker preproc BOLD pattern
+    - subject must not be in excluded_subjects
+    - folder subject must equal filename subject
+    - run must be in allowed run whitelist
+    - matching raw BIDS sidecar JSON must exist
+    - raw sidecar must include a valid TR
+    - NIfTI must be readable with valid 4D volume count
+    - each (subject, run) key must be unique
+    """
+    allowed_run_set = set(int(run) for run in allowed_runs)
+    excluded_subject_set = {str(subject).strip() for subject in (excluded_subjects or []) if str(subject).strip()}
+
+    accepted_rows: list[ManifestRecord] = []
+    rejected_rows: list[RejectRecord] = []
+    seen_subject_run_keys: set[tuple[str, int]] = set()
+
+    candidate_files = _iter_candidate_bold_files(derivatives_dir)
+
+    for bold_path in candidate_files:
+        folder_subject = bold_path.parents[1].name
+        filename_subject = ""
+        run_number: int | None = None
+
+        match = MULTITALKER_BOLD_RE.match(bold_path.name)
+        if match is None:
+            rejected_rows.append(
+                RejectRecord(
+                    derivatives_bold_path=str(bold_path),
+                    folder_subject=folder_subject,
+                    filename_subject="",
+                    run=None,
+                    reason="filename_pattern_mismatch",
+                    details="Not a multitalker run preproc BOLD filename",
+                )
+            )
+            continue
+
+        filename_subject = match.group(1)
+        run_number = int(match.group(2))
+
+        if folder_subject in excluded_subject_set or filename_subject in excluded_subject_set:
+            rejected_rows.append(
+                RejectRecord(
+                    derivatives_bold_path=str(bold_path),
+                    folder_subject=folder_subject,
+                    filename_subject=filename_subject,
+                    run=run_number,
+                    reason="excluded_subject",
+                    details=f"Excluded subjects={sorted(excluded_subject_set)}",
+                )
+            )
+            continue
+
+        if folder_subject != filename_subject:
+            rejected_rows.append(
+                RejectRecord(
+                    derivatives_bold_path=str(bold_path),
+                    folder_subject=folder_subject,
+                    filename_subject=filename_subject,
+                    run=run_number,
+                    reason="folder_filename_subject_mismatch",
+                    details="Folder subject does not match filename subject",
+                )
+            )
+            continue
+
+        if run_number not in allowed_run_set:
+            rejected_rows.append(
+                RejectRecord(
+                    derivatives_bold_path=str(bold_path),
+                    folder_subject=folder_subject,
+                    filename_subject=filename_subject,
+                    run=run_number,
+                    reason="run_not_in_whitelist",
+                    details=f"Allowed runs={sorted(allowed_run_set)}",
+                )
+            )
+            continue
+
+        subject_run_key = (filename_subject, run_number)
+        if subject_run_key in seen_subject_run_keys:
+            rejected_rows.append(
+                RejectRecord(
+                    derivatives_bold_path=str(bold_path),
+                    folder_subject=folder_subject,
+                    filename_subject=filename_subject,
+                    run=run_number,
+                    reason="duplicate_subject_run_key",
+                    details="Another derivatives file already accepted for this subject/run",
+                )
+            )
+            continue
+
+        raw_json_path = (
+            data_dir / filename_subject / "func" / f"{filename_subject}_task-multitalker_run-{run_number}_bold.json"
+        )
+        if not raw_json_path.exists():
+            rejected_rows.append(
+                RejectRecord(
+                    derivatives_bold_path=str(bold_path),
+                    folder_subject=folder_subject,
+                    filename_subject=filename_subject,
+                    run=run_number,
+                    reason="missing_raw_sidecar_json",
+                    details=str(raw_json_path),
+                )
+            )
+            continue
+
+        raw_json_payload = _safe_read_json(raw_json_path)
+        if raw_json_payload is None:
+            rejected_rows.append(
+                RejectRecord(
+                    derivatives_bold_path=str(bold_path),
+                    folder_subject=folder_subject,
+                    filename_subject=filename_subject,
+                    run=run_number,
+                    reason="unreadable_raw_sidecar_json",
+                    details=str(raw_json_path),
+                )
+            )
+            continue
+
+        tr_seconds = _extract_repetition_time_seconds(raw_json_payload)
+        if tr_seconds is None:
+            rejected_rows.append(
+                RejectRecord(
+                    derivatives_bold_path=str(bold_path),
+                    folder_subject=folder_subject,
+                    filename_subject=filename_subject,
+                    run=run_number,
+                    reason="missing_or_invalid_repetition_time",
+                    details=str(raw_json_path),
+                )
+            )
+            continue
+
+        n_volumes = _read_n_volumes(
+            path=bold_path,
+            deep_integrity_check=bool(deep_nifti_integrity_check),
+        )
+        if n_volumes is None:
+            rejected_rows.append(
+                RejectRecord(
+                    derivatives_bold_path=str(bold_path),
+                    folder_subject=folder_subject,
+                    filename_subject=filename_subject,
+                    run=run_number,
+                    reason="unreadable_or_invalid_nifti",
+                    details="Could not read 4D volume count",
+                )
+            )
+            continue
+
+        condition_fixed, condition_effective, speaker_stream, used_fallback = resolve_run_condition(
+            run=run_number,
+            enable_mixed_fallback=enable_mixed_fallback,
+        )
+
+        accepted_rows.append(
+            ManifestRecord(
+                subject=filename_subject,
+                run=run_number,
+                condition_fixed=condition_fixed,
+                condition_effective=condition_effective,
+                speaker_stream=speaker_stream,
+                used_mixed_fallback=used_fallback,
+                derivatives_bold_path=str(bold_path),
+                raw_bold_json_path=str(raw_json_path),
+                tr_seconds=float(tr_seconds),
+                n_volumes=int(n_volumes),
+            )
+        )
+        seen_subject_run_keys.add(subject_run_key)
+
+    manifest_df = pd.DataFrame([asdict(row) for row in accepted_rows])
+    reject_df = pd.DataFrame([asdict(row) for row in rejected_rows])
+
+    if not manifest_df.empty:
+        manifest_df = manifest_df.sort_values(["subject", "run"]).reset_index(drop=True)
+    if not reject_df.empty:
+        reject_df = reject_df.sort_values(["folder_subject", "reason", "derivatives_bold_path"]).reset_index(
+            drop=True
+        )
+
+    tr_values = manifest_df["tr_seconds"].tolist() if not manifest_df.empty else []
+    n_volumes_values = manifest_df["n_volumes"].tolist() if not manifest_df.empty else []
+    reject_counts = (
+        reject_df["reason"].value_counts().sort_index().to_dict() if not reject_df.empty else {}
+    )
+
+    qc_summary: dict[str, Any] = {
+        "n_candidates": len(candidate_files),
+        "n_accepted": int(len(manifest_df)),
+        "n_rejected": int(len(reject_df)),
+        "n_unique_subjects": int(manifest_df["subject"].nunique()) if not manifest_df.empty else 0,
+        "allowed_runs": sorted(int(run) for run in allowed_run_set),
+        "excluded_subjects": sorted(excluded_subject_set),
+        "deep_nifti_integrity_check": bool(deep_nifti_integrity_check),
+        "mixed_fallback_enabled": bool(enable_mixed_fallback),
+        "reject_counts": reject_counts,
+    }
+
+    if tr_values:
+        qc_summary["tr_seconds_unique"] = sorted({float(value) for value in tr_values})
+        qc_summary["tr_seconds_min"] = float(min(tr_values))
+        qc_summary["tr_seconds_max"] = float(max(tr_values))
+
+    if n_volumes_values:
+        qc_summary["n_volumes_min"] = int(min(n_volumes_values))
+        qc_summary["n_volumes_max"] = int(max(n_volumes_values))
+
+    return manifest_df, reject_df, qc_summary

code/a1_pipeline/model_config.py

@@ -0,0 +1,95 @@
+"""Model profile configuration utilities for A1 bootstrap."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def _unique_preserve_order(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    unique: list[str] = []
+
+    for raw in values:
+        value = str(raw).strip()
+        if not value or value in seen:
+            continue
+        seen.add(value)
+        unique.append(value)
+
+    return unique
+
+
+def list_model_profiles(config_path: Path) -> tuple[list[str], str | None]:
+    """List available profile names and active profile from JSON config."""
+    config_path = config_path.resolve()
+    if not config_path.exists():
+        raise FileNotFoundError(f"Model config not found: {config_path}")
+
+    with config_path.open("r", encoding="utf-8") as handle:
+        payload = json.load(handle)
+
+    profiles = payload.get("profiles")
+    if not isinstance(profiles, dict) or not profiles:
+        raise ValueError(f"Invalid model config (missing non-empty 'profiles'): {config_path}")
+
+    names = sorted(str(name) for name in profiles.keys())
+    active = payload.get("active_profile")
+    active_profile = str(active) if active is not None else None
+    return names, active_profile
+
+
+def load_model_ids_from_config(
+    config_path: Path,
+    profile: str | None,
+) -> tuple[list[str], dict[str, Any]]:
+    """Load model IDs from a profile inside the model config JSON."""
+    config_path = config_path.resolve()
+    if not config_path.exists():
+        raise FileNotFoundError(f"Model config not found: {config_path}")
+
+    with config_path.open("r", encoding="utf-8") as handle:
+        payload = json.load(handle)
+
+    profiles = payload.get("profiles")
+    if not isinstance(profiles, dict) or not profiles:
+        raise ValueError(f"Invalid model config (missing non-empty 'profiles'): {config_path}")
+
+    profile_name = profile or payload.get("active_profile")
+    if profile_name is None:
+        profile_name = sorted(profiles.keys())[0]
+
+    profile_name = str(profile_name)
+    if profile_name not in profiles:
+        available = ", ".join(sorted(str(key) for key in profiles.keys()))
+        raise ValueError(
+            f"Requested model profile '{profile_name}' not found in {config_path}. "
+            f"Available profiles: {available}"
+        )
+
+    profile_payload = profiles[profile_name]
+    if not isinstance(profile_payload, dict):
+        raise ValueError(
+            f"Invalid model profile payload for '{profile_name}' in {config_path}"
+        )
+
+    raw_model_ids = profile_payload.get("model_ids")
+    if not isinstance(raw_model_ids, list):
+        raise ValueError(
+            f"Model profile '{profile_name}' must contain a list field 'model_ids'"
+        )
+
+    model_ids = _unique_preserve_order([str(value) for value in raw_model_ids])
+    if not model_ids:
+        raise ValueError(
+            f"Model profile '{profile_name}' resolved to an empty model list"
+        )
+
+    selection_info = {
+        "source": "model_config",
+        "config_path": str(config_path),
+        "profile": profile_name,
+        "description": str(profile_payload.get("description", "")),
+    }
+    return model_ids, selection_info

code/a1_pipeline/participant_runs.py

@@ -0,0 +1,176 @@
+"""Participant-specific run-to-stimulus mapping helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+CANONICAL_RUN_LABEL_TO_INDEX: dict[str, int] = {
+    "single_f": 1,
+    "single_female": 1,
+    "single_m": 2,
+    "single_male": 2,
+    "mixed_f": 3,
+    "mixed_female": 3,
+    "mixed_m": 4,
+    "mixed_male": 4,
+}
+
+
+CANONICAL_RUN_INDEX_TO_LABEL: dict[int, str] = {
+    1: "single_female",
+    2: "single_male",
+    3: "mixed_female",
+    4: "mixed_male",
+}
+
+
+def parse_run_key(raw_key: Any) -> int:
+    if isinstance(raw_key, int):
+        run = int(raw_key)
+    else:
+        token = str(raw_key).strip().lower()
+        if token.startswith("run"):
+            token = token[3:]
+        token = token.lstrip("_-")
+        if not token.isdigit():
+            raise ValueError(f"Invalid run key in participant_run_info: {raw_key}")
+        run = int(token)
+
+    if run <= 0:
+        raise ValueError(f"Run key must be positive in participant_run_info: {raw_key}")
+
+    return run
+
+
+def normalize_run_label(raw_label: Any) -> str:
+    token = str(raw_label).strip().lower().replace("-", "_").replace(" ", "_")
+    return "_".join(part for part in token.split("_") if part)
+
+
+def resolve_canonical_run(raw_value: int | str) -> int:
+    if isinstance(raw_value, int):
+        canonical_run = int(raw_value)
+    else:
+        normalized_label = normalize_run_label(raw_value)
+        if normalized_label not in CANONICAL_RUN_LABEL_TO_INDEX:
+            raise ValueError(
+                f"Unsupported canonical run label: {raw_value}. "
+                f"Allowed labels: {sorted(CANONICAL_RUN_LABEL_TO_INDEX.keys())}"
+            )
+        canonical_run = int(CANONICAL_RUN_LABEL_TO_INDEX[normalized_label])
+
+    if canonical_run not in CANONICAL_RUN_INDEX_TO_LABEL:
+        raise ValueError(
+            f"Unsupported canonical run index: {canonical_run}. "
+            f"Allowed indices: {sorted(CANONICAL_RUN_INDEX_TO_LABEL.keys())}"
+        )
+
+    return canonical_run
+
+
+def canonical_run_to_label(canonical_run: int) -> str:
+    resolved = resolve_canonical_run(int(canonical_run))
+    return str(CANONICAL_RUN_INDEX_TO_LABEL[resolved])
+
+
+def load_participant_run_map(
+    participant_run_info_path: Path,
+    subjects: list[str],
+    runs: list[int] | None = None,
+) -> dict[str, dict[int, int]]:
+    if not participant_run_info_path.exists():
+        raise FileNotFoundError(f"participant_run_info.json not found: {participant_run_info_path}")
+
+    with participant_run_info_path.open("r", encoding="utf-8") as handle:
+        payload = json.load(handle)
+
+    if not isinstance(payload, dict):
+        raise ValueError("participant_run_info.json must contain a JSON object at top level")
+
+    requested_subjects = sorted(set(subjects))
+    requested_runs = sorted(set(int(run) for run in runs)) if runs is not None else None
+
+    missing_subjects = [subject for subject in requested_subjects if subject not in payload]
+    if missing_subjects:
+        raise KeyError(
+            "participant_run_info.json is missing subjects required for fit: "
+            f"{missing_subjects}"
+        )
+
+    subject_run_map: dict[str, dict[int, int]] = {}
+
+    for subject in requested_subjects:
+        raw_subject_map = payload[subject]
+        if not isinstance(raw_subject_map, dict):
+            raise ValueError(
+                f"participant_run_info[{subject}] must be an object of run->condition labels"
+            )
+
+        parsed: dict[int, int] = {}
+        for raw_run_key, raw_label in raw_subject_map.items():
+            run = parse_run_key(raw_run_key)
+            parsed[run] = int(resolve_canonical_run(str(raw_label)))
+
+        if requested_runs is not None:
+            missing_runs = [run for run in requested_runs if run not in parsed]
+            if missing_runs:
+                raise KeyError(
+                    "participant_run_info.json has incomplete run mapping for "
+                    f"subject={subject}. Missing runs={missing_runs}"
+                )
+            subject_run_map[subject] = {run: int(parsed[run]) for run in requested_runs}
+        else:
+            subject_run_map[subject] = {int(run): int(value) for run, value in parsed.items()}
+
+    return subject_run_map
+
+
+def resolve_subject_canonical_run(
+    participant_run_map: dict[str, dict[int, int]],
+    subject: str,
+    run: int,
+) -> int:
+    if subject not in participant_run_map:
+        raise KeyError(f"Missing participant run mapping for subject={subject}")
+
+    subject_map = participant_run_map[subject]
+    if run not in subject_map:
+        raise KeyError(f"Missing participant run mapping for subject={subject}, run={run}")
+
+    return int(subject_map[run])
+
+
+def resolve_subject_actual_run(
+    participant_run_map: dict[str, dict[int, int]],
+    subject: str,
+    canonical_run: int | str,
+    available_runs: set[int] | None = None,
+) -> int:
+    if subject not in participant_run_map:
+        raise KeyError(f"Missing participant run mapping for subject={subject}")
+
+    target_canonical_run = resolve_canonical_run(canonical_run)
+    subject_map = participant_run_map[subject]
+    matching_runs = sorted(
+        run
+        for run, canonical_value in subject_map.items()
+        if int(canonical_value) == int(target_canonical_run)
+    )
+
+    if available_runs is not None:
+        matching_runs = [run for run in matching_runs if run in available_runs]
+
+    if not matching_runs:
+        raise KeyError(
+            f"No actual run found for subject={subject}, canonical_run={target_canonical_run}"
+        )
+    if len(matching_runs) > 1:
+        raise ValueError(
+            "Expected exactly one actual run for canonical stimulus, found multiple for "
+            f"subject={subject}, canonical_run={target_canonical_run}: {matching_runs}"
+        )
+
+    return int(matching_runs[0])

code/a1_pipeline/spatial.py

@@ -0,0 +1,183 @@
+"""Spatial harmonization utilities for A1 baseline bootstrap."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+import nibabel as nib
+from nibabel.processing import resample_from_to
+import numpy as np
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class RunMaskQC:
+    """Per-run QC record used when building the analysis mask."""
+
+    subject: str
+    run: int
+    derivatives_bold_path: str
+    run_mask_method: str
+    needs_resample_to_reference: bool
+    run_mask_voxels: int
+
+
+def _make_reference_3d_from_manifest(manifest_df: pd.DataFrame) -> nib.Nifti1Image:
+    if manifest_df.empty:
+        raise ValueError("Manifest is empty; cannot create spatial reference")
+
+    first_path = Path(str(manifest_df.iloc[0]["derivatives_bold_path"]))
+    first_img = nib.load(str(first_path))
+    if len(first_img.shape) != 4:
+        raise ValueError(f"Expected 4D BOLD image but got shape={first_img.shape} for {first_path}")
+
+    shape_3d = first_img.shape[:3]
+    return nib.Nifti1Image(np.zeros(shape_3d, dtype=np.uint8), first_img.affine)
+
+
+def _same_grid(img_a: nib.Nifti1Image, img_b: nib.Nifti1Image, atol: float = 1e-5) -> bool:
+    return img_a.shape == img_b.shape and np.allclose(img_a.affine, img_b.affine, atol=atol)
+
+
+def _extract_run_mask_from_bold(
+    bold_img: nib.Nifti1Image,
+    method: str,
+    epsilon: float,
+) -> nib.Nifti1Image:
+    shape = bold_img.shape
+    if len(shape) != 4:
+        raise ValueError(f"Expected 4D BOLD image, got shape={shape}")
+
+    if method == "first_volume_nonzero":
+        volume = np.asanyarray(bold_img.dataobj[..., 0])
+        run_mask = np.abs(volume) > epsilon
+    elif method == "temporal_any_nonzero":
+        run_mask = np.zeros(shape[:3], dtype=bool)
+        for time_index in range(shape[3]):
+            volume = np.asanyarray(bold_img.dataobj[..., time_index])
+            run_mask |= np.abs(volume) > epsilon
+    else:
+        raise ValueError(f"Unsupported run mask method: {method}")
+
+    return nib.Nifti1Image(run_mask.astype(np.uint8), bold_img.affine)
+
+
+def _resample_binary_mask_to_reference(
+    binary_mask_img: nib.Nifti1Image,
+    reference_3d_img: nib.Nifti1Image,
+) -> nib.Nifti1Image:
+    resampled = resample_from_to(
+        binary_mask_img,
+        (reference_3d_img.shape, reference_3d_img.affine),
+        order=0,
+    )
+    binary_data = (resampled.get_fdata() > 0.5).astype(np.uint8)
+    return nib.Nifti1Image(binary_data, reference_3d_img.affine)
+
+
+def build_symmetric_analysis_mask(
+    manifest_df: pd.DataFrame,
+    run_mask_method: str = "first_volume_nonzero",
+    epsilon: float = 1e-6,
+) -> tuple[nib.Nifti1Image, dict[tuple[str, int], np.ndarray], pd.DataFrame, dict[str, Any]]:
+    """Build analysis mask in a canonical grid with left-right symmetry enforced.
+
+    Returns:
+        analysis_mask_img: symmetric boolean mask image in reference grid
+        run_mask_map: (subject, run) -> boolean 3D run mask in reference grid
+        run_mask_qc_df: per-run mask stats including whether resampling was needed
+        mask_qc: summary dictionary
+    """
+    if manifest_df.empty:
+        raise ValueError("Manifest is empty; cannot build analysis mask")
+
+    required_columns = {"subject", "run", "derivatives_bold_path"}
+    missing = required_columns.difference(manifest_df.columns)
+    if missing:
+        raise ValueError(f"Manifest missing required columns: {sorted(missing)}")
+
+    reference_3d_img = _make_reference_3d_from_manifest(manifest_df)
+    reference_affine = reference_3d_img.affine
+
+    run_mask_map: dict[tuple[str, int], np.ndarray] = {}
+    run_qc_rows: list[RunMaskQC] = []
+
+    intersection_mask: np.ndarray | None = None
+    n_resampled = 0
+
+    for row in manifest_df.itertuples(index=False):
+        subject = str(getattr(row, "subject"))
+        run = int(getattr(row, "run"))
+        bold_path = Path(str(getattr(row, "derivatives_bold_path")))
+
+        bold_img = nib.load(str(bold_path))
+        run_mask_img = _extract_run_mask_from_bold(
+            bold_img=bold_img,
+            method=run_mask_method,
+            epsilon=epsilon,
+        )
+
+        needs_resample = not _same_grid(run_mask_img, reference_3d_img)
+        if needs_resample:
+            n_resampled += 1
+            run_mask_img = _resample_binary_mask_to_reference(run_mask_img, reference_3d_img)
+
+        run_mask_bool = run_mask_img.get_fdata() > 0.5
+        run_key = (subject, run)
+        run_mask_map[run_key] = run_mask_bool
+
+        if intersection_mask is None:
+            intersection_mask = run_mask_bool.copy()
+        else:
+            intersection_mask &= run_mask_bool
+
+        run_qc_rows.append(
+            RunMaskQC(
+                subject=subject,
+                run=run,
+                derivatives_bold_path=str(bold_path),
+                run_mask_method=run_mask_method,
+                needs_resample_to_reference=needs_resample,
+                run_mask_voxels=int(run_mask_bool.sum()),
+            )
+        )
+
+    if intersection_mask is None:
+        raise RuntimeError("Could not compute intersection mask from manifest entries")
+
+    swapped_mask = np.flip(intersection_mask, axis=0)
+    symmetric_mask = intersection_mask & swapped_mask
+
+    analysis_mask_img = nib.Nifti1Image(symmetric_mask.astype(np.uint8), reference_affine)
+
+    shape_x = symmetric_mask.shape[0]
+    mid_x = shape_x // 2
+    left_voxels = int(symmetric_mask[:mid_x, :, :].sum())
+    right_voxels = int(symmetric_mask[-mid_x:, :, :].sum()) if mid_x > 0 else 0
+
+    run_mask_qc_df = pd.DataFrame([asdict(row) for row in run_qc_rows])
+    if not run_mask_qc_df.empty:
+        run_mask_qc_df = run_mask_qc_df.sort_values(["subject", "run"]).reset_index(drop=True)
+
+    orientation_codes = "".join(nib.aff2axcodes(reference_affine))
+
+    mask_qc: dict[str, Any] = {
+        "run_mask_method": run_mask_method,
+        "n_manifest_rows": int(len(manifest_df)),
+        "n_run_masks": int(len(run_mask_map)),
+        "n_resampled_run_masks": int(n_resampled),
+        "reference_shape": [int(dim) for dim in analysis_mask_img.shape],
+        "reference_orientation": orientation_codes,
+        "intersection_voxels": int(intersection_mask.sum()),
+        "symmetric_mask_voxels": int(symmetric_mask.sum()),
+        "left_hemisphere_voxels": left_voxels,
+        "right_hemisphere_voxels": right_voxels,
+    }
+
+    if not run_mask_qc_df.empty:
+        mask_qc["run_mask_voxels_min"] = int(run_mask_qc_df["run_mask_voxels"].min())
+        mask_qc["run_mask_voxels_max"] = int(run_mask_qc_df["run_mask_voxels"].max())
+
+    return analysis_mask_img, run_mask_map, run_mask_qc_df, mask_qc

code/a1_pipeline/splits.py

@@ -0,0 +1,237 @@
+"""Leakage-safe split builders for A1 baseline evaluation protocols."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class CrossRunFold:
+    """One leave-one-run-out fold for Protocol A."""
+
+    protocol: str
+    subject: str
+    fold_id: str
+    test_run: int
+    train_runs: str
+    n_train_runs: int
+    n_test_runs: int
+
+
+@dataclass(frozen=True)
+class WithinRunBlockedSplit:
+    """One blocked temporal split with HRF safety gap for Protocol B."""
+
+    protocol: str
+    subject: str
+    run: int
+    split_id: str
+    n_volumes: int
+    test_start_tr: int
+    test_end_tr_exclusive: int
+    gap_tr: int
+    train_left_start_tr: int
+    train_left_end_tr_exclusive: int
+    train_right_start_tr: int
+    train_right_end_tr_exclusive: int
+    n_train_volumes: int
+    n_test_volumes: int
+    n_gap_excluded_volumes: int
+
+
+@dataclass(frozen=True)
+class WithinRunSkipped:
+    """Skipped run when blocked split constraints cannot be satisfied."""
+
+    subject: str
+    run: int
+    n_volumes: int
+    reason: str
+
+
+def build_cross_run_folds(manifest_df: pd.DataFrame) -> pd.DataFrame:
+    """Build Protocol A folds (leave-one-run-out within subject)."""
+    if manifest_df.empty:
+        return pd.DataFrame()
+
+    required_columns = {"subject", "run"}
+    missing = required_columns.difference(manifest_df.columns)
+    if missing:
+        raise ValueError(f"Manifest missing required columns: {sorted(missing)}")
+
+    rows: list[CrossRunFold] = []
+
+    for subject, subject_df in manifest_df.groupby("subject"):
+        runs = sorted({int(run) for run in subject_df["run"].tolist()})
+        if len(runs) < 2:
+            continue
+
+        for test_run in runs:
+            train_runs = [run for run in runs if run != test_run]
+            rows.append(
+                CrossRunFold(
+                    protocol="A_cross_run",
+                    subject=str(subject),
+                    fold_id=f"{subject}_test_run{test_run}",
+                    test_run=int(test_run),
+                    train_runs=",".join(str(run) for run in train_runs),
+                    n_train_runs=len(train_runs),
+                    n_test_runs=1,
+                )
+            )
+
+    output_df = pd.DataFrame([asdict(row) for row in rows])
+    if not output_df.empty:
+        output_df = output_df.sort_values(["subject", "test_run"]).reset_index(drop=True)
+    return output_df
+
+
+def _compute_within_run_blocked_bounds(
+    n_volumes: int,
+    test_fraction: float,
+    gap_tr: int,
+    min_train_volumes: int,
+    min_test_volumes: int,
+) -> tuple[dict[str, int] | None, str | None]:
+    if n_volumes <= 0:
+        return None, "non_positive_volume_count"
+
+    if not (0.0 < test_fraction < 1.0):
+        return None, "invalid_test_fraction"
+
+    if gap_tr < 0:
+        return None, "negative_gap"
+
+    n_test = max(min_test_volumes, int(round(n_volumes * test_fraction)))
+    n_test = min(n_test, n_volumes)
+
+    if n_test >= n_volumes:
+        return None, "test_block_covers_entire_run"
+
+    # Center block so train windows exist on both sides when possible.
+    test_start = max(0, (n_volumes - n_test) // 2)
+    test_end = min(n_volumes, test_start + n_test)
+
+    left_train_start = 0
+    left_train_end = max(0, test_start - gap_tr)
+
+    right_train_start = min(n_volumes, test_end + gap_tr)
+    right_train_end = n_volumes
+
+    n_train = (left_train_end - left_train_start) + (right_train_end - right_train_start)
+    n_gap = (test_start - left_train_end) + (right_train_start - test_end)
+
+    if n_train < min_train_volumes:
+        return None, "insufficient_train_volumes_after_gap"
+
+    if n_test < min_test_volumes:
+        return None, "insufficient_test_volumes"
+
+    if left_train_end < left_train_start or right_train_end < right_train_start:
+        return None, "invalid_train_segment_bounds"
+
+    bounds = {
+        "test_start_tr": int(test_start),
+        "test_end_tr_exclusive": int(test_end),
+        "train_left_start_tr": int(left_train_start),
+        "train_left_end_tr_exclusive": int(left_train_end),
+        "train_right_start_tr": int(right_train_start),
+        "train_right_end_tr_exclusive": int(right_train_end),
+        "n_train_volumes": int(n_train),
+        "n_test_volumes": int(n_test),
+        "n_gap_excluded_volumes": int(n_gap),
+    }
+    return bounds, None
+
+
+def build_within_run_blocked_splits(
+    manifest_df: pd.DataFrame,
+    test_fraction: float = 0.2,
+    gap_tr: int = 8,
+    min_train_volumes: int = 40,
+    min_test_volumes: int = 20,
+) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """Build Protocol B blocked temporal splits for each subject-run."""
+    if manifest_df.empty:
+        return pd.DataFrame(), pd.DataFrame()
+
+    required_columns = {"subject", "run", "n_volumes"}
+    missing = required_columns.difference(manifest_df.columns)
+    if missing:
+        raise ValueError(f"Manifest missing required columns: {sorted(missing)}")
+
+    split_rows: list[WithinRunBlockedSplit] = []
+    skipped_rows: list[WithinRunSkipped] = []
+
+    for row in manifest_df.itertuples(index=False):
+        subject = str(getattr(row, "subject"))
+        run = int(getattr(row, "run"))
+        n_volumes = int(getattr(row, "n_volumes"))
+
+        bounds, reason = _compute_within_run_blocked_bounds(
+            n_volumes=n_volumes,
+            test_fraction=test_fraction,
+            gap_tr=gap_tr,
+            min_train_volumes=min_train_volumes,
+            min_test_volumes=min_test_volumes,
+        )
+
+        if bounds is None:
+            skipped_rows.append(
+                WithinRunSkipped(
+                    subject=subject,
+                    run=run,
+                    n_volumes=n_volumes,
+                    reason=str(reason),
+                )
+            )
+            continue
+
+        split_rows.append(
+            WithinRunBlockedSplit(
+                protocol="B_within_run_blocked",
+                subject=subject,
+                run=run,
+                split_id=f"{subject}_run{run}_blocked",
+                n_volumes=n_volumes,
+                test_start_tr=bounds["test_start_tr"],
+                test_end_tr_exclusive=bounds["test_end_tr_exclusive"],
+                gap_tr=int(gap_tr),
+                train_left_start_tr=bounds["train_left_start_tr"],
+                train_left_end_tr_exclusive=bounds["train_left_end_tr_exclusive"],
+                train_right_start_tr=bounds["train_right_start_tr"],
+                train_right_end_tr_exclusive=bounds["train_right_end_tr_exclusive"],
+                n_train_volumes=bounds["n_train_volumes"],
+                n_test_volumes=bounds["n_test_volumes"],
+                n_gap_excluded_volumes=bounds["n_gap_excluded_volumes"],
+            )
+        )
+
+    split_df = pd.DataFrame([asdict(row) for row in split_rows])
+    skipped_df = pd.DataFrame([asdict(row) for row in skipped_rows])
+
+    if not split_df.empty:
+        split_df = split_df.sort_values(["subject", "run"]).reset_index(drop=True)
+    if not skipped_df.empty:
+        skipped_df = skipped_df.sort_values(["subject", "run"]).reset_index(drop=True)
+
+    return split_df, skipped_df
+
+
+def summarize_split_counts(
+    manifest_df: pd.DataFrame,
+    cross_run_df: pd.DataFrame,
+    within_run_df: pd.DataFrame,
+    within_run_skipped_df: pd.DataFrame,
+) -> dict[str, Any]:
+    """Return compact split summary for reporting JSON outputs."""
+    return {
+        "n_manifest_rows": int(len(manifest_df)),
+        "n_subjects_manifest": int(manifest_df["subject"].nunique()) if not manifest_df.empty else 0,
+        "n_protocol_a_folds": int(len(cross_run_df)),
+        "n_protocol_b_splits": int(len(within_run_df)),
+        "n_protocol_b_skipped": int(len(within_run_skipped_df)),
+    }

code/a1_pipeline/targets.py

@@ -0,0 +1,173 @@
+"""Target-region preparation and preservation QC for core language ROIs."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+import nibabel as nib
+from nibabel.processing import resample_from_to
+import numpy as np
+import pandas as pd
+
+CORE_ROI_NAMES: tuple[str, ...] = (
+    "TP",
+    "aSTS",
+    "pSTS",
+    "BA44",
+    "BA45",
+    "BA47",
+    "AG_TPJ",
+)
+
+
+@dataclass(frozen=True)
+class CoreROICoverageRow:
+    """Coverage diagnostics for one subject-run and one core ROI."""
+
+    subject: str
+    run: int
+    roi_name: str
+    pre_mask_voxels: int
+    post_mask_voxels: int
+    retention_ratio: float
+    centroid_shift_mm: float | None
+    min_voxels_required: int
+    passed: bool
+
+
+def _resample_binary_roi_to_reference(
+    roi_img: nib.Nifti1Image,
+    reference_img: nib.Nifti1Image,
+) -> np.ndarray:
+    resampled = resample_from_to(
+        roi_img,
+        (reference_img.shape, reference_img.affine),
+        order=0,
+    )
+    return resampled.get_fdata() > 0.5
+
+
+def _compute_centroid_mm(mask_bool: np.ndarray, affine: np.ndarray) -> np.ndarray | None:
+    indices = np.argwhere(mask_bool)
+    if indices.size == 0:
+        return None
+    points_mm = nib.affines.apply_affine(affine, indices)
+    return np.mean(points_mm, axis=0)
+
+
+def load_core_roi_masks(
+    roi_mask_dir: Path,
+    reference_img: nib.Nifti1Image,
+) -> tuple[dict[str, np.ndarray], dict[str, int]]:
+    """Load and resample all core ROI masks into reference analysis grid."""
+    roi_masks: dict[str, np.ndarray] = {}
+    roi_voxel_counts: dict[str, int] = {}
+
+    for roi_name in CORE_ROI_NAMES:
+        roi_path = roi_mask_dir / f"{roi_name}.nii.gz"
+        if not roi_path.exists():
+            raise FileNotFoundError(f"Missing core ROI mask: {roi_path}")
+
+        roi_img = nib.load(str(roi_path))
+        roi_bool = _resample_binary_roi_to_reference(roi_img=roi_img, reference_img=reference_img)
+
+        roi_masks[roi_name] = roi_bool
+        roi_voxel_counts[roi_name] = int(roi_bool.sum())
+
+    return roi_masks, roi_voxel_counts
+
+
+def evaluate_core_roi_preservation(
+    manifest_df: pd.DataFrame,
+    run_mask_map: dict[tuple[str, int], np.ndarray],
+    core_roi_masks: dict[str, np.ndarray],
+    reference_affine: np.ndarray,
+    min_voxels_required: int,
+) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, Any]]:
+    """Evaluate whether each core ROI is preserved for every subject-run."""
+    rows: list[CoreROICoverageRow] = []
+
+    roi_centroids_pre: dict[str, np.ndarray | None] = {
+        roi_name: _compute_centroid_mm(mask_bool=mask_bool, affine=reference_affine)
+        for roi_name, mask_bool in core_roi_masks.items()
+    }
+
+    for row in manifest_df.itertuples(index=False):
+        subject = str(getattr(row, "subject"))
+        run = int(getattr(row, "run"))
+        run_key = (subject, run)
+
+        run_mask = run_mask_map.get(run_key)
+        if run_mask is None:
+            for roi_name, roi_mask in core_roi_masks.items():
+                rows.append(
+                    CoreROICoverageRow(
+                        subject=subject,
+                        run=run,
+                        roi_name=roi_name,
+                        pre_mask_voxels=int(roi_mask.sum()),
+                        post_mask_voxels=0,
+                        retention_ratio=0.0,
+                        centroid_shift_mm=None,
+                        min_voxels_required=min_voxels_required,
+                        passed=False,
+                    )
+                )
+            continue
+
+        for roi_name, roi_mask in core_roi_masks.items():
+            pre_count = int(roi_mask.sum())
+            post_mask = roi_mask & run_mask
+            post_count = int(post_mask.sum())
+
+            retention_ratio = float(post_count / pre_count) if pre_count > 0 else 0.0
+
+            centroid_pre = roi_centroids_pre.get(roi_name)
+            centroid_post = _compute_centroid_mm(mask_bool=post_mask, affine=reference_affine)
+            if centroid_pre is not None and centroid_post is not None:
+                centroid_shift = float(np.linalg.norm(centroid_post - centroid_pre))
+            else:
+                centroid_shift = None
+
+            passed = bool(pre_count > 0 and post_count >= min_voxels_required)
+
+            rows.append(
+                CoreROICoverageRow(
+                    subject=subject,
+                    run=run,
+                    roi_name=roi_name,
+                    pre_mask_voxels=pre_count,
+                    post_mask_voxels=post_count,
+                    retention_ratio=retention_ratio,
+                    centroid_shift_mm=centroid_shift,
+                    min_voxels_required=min_voxels_required,
+                    passed=passed,
+                )
+            )
+
+    coverage_df = pd.DataFrame([asdict(row) for row in rows])
+    if not coverage_df.empty:
+        coverage_df = coverage_df.sort_values(["subject", "run", "roi_name"]).reset_index(drop=True)
+
+    failures_df = coverage_df[coverage_df["passed"] == False].copy() if not coverage_df.empty else pd.DataFrame()
+    if not failures_df.empty:
+        failures_df = failures_df.sort_values(["subject", "run", "roi_name"]).reset_index(drop=True)
+
+    per_run_failures = 0
+    if not failures_df.empty:
+        per_run_failures = int(failures_df[["subject", "run"]].drop_duplicates().shape[0])
+
+    qc_summary: dict[str, Any] = {
+        "n_coverage_rows": int(len(coverage_df)),
+        "n_fail_rows": int(len(failures_df)),
+        "n_subject_run_failures": per_run_failures,
+        "min_voxels_required": int(min_voxels_required),
+    }
+
+    if not coverage_df.empty:
+        qc_summary["retention_ratio_min"] = float(coverage_df["retention_ratio"].min())
+        qc_summary["retention_ratio_max"] = float(coverage_df["retention_ratio"].max())
+
+    return coverage_df, failures_df, qc_summary

code/assets/participant_run_info.json

@@ -0,0 +1,28 @@
+{
+  "sub-01": {"run1": "single_m", "run2": "mixed_f", "run3": "mixed_m", "run4": "single_f"},
+  "sub-02": {"run1": "single_m", "run2": "single_f", "run3": "mixed_f", "run4": "mixed_m"},
+  "sub-03": {"run1": "single_f", "run2": "single_m", "run3": "mixed_f", "run4": "mixed_m"},
+  "sub-04": {"run1": "mixed_f", "run2": "single_f", "run3": "mixed_m", "run4": "single_m"},
+  "sub-05": {"run1": "mixed_m", "run2": "single_m", "run3": "single_f", "run4": "mixed_f"},
+  "sub-06": {"run1": "mixed_m", "run2": "single_f", "run3": "mixed_f", "run4": "single_m"},
+  "sub-07": {"run1": "single_m", "run2": "mixed_f", "run3": "mixed_m", "run4": "single_f"},
+  "sub-08": {"run1": "single_f", "run2": "mixed_f", "run3": "single_m", "run4": "mixed_m"},
+  "sub-09": {"run1": "single_m", "run2": "single_f", "run3": "mixed_f", "run4": "mixed_m"},
+  "sub-10": {"run1": "single_m", "run2": "single_f", "run3": "mixed_m", "run4": "mixed_f"},
+  "sub-11": {"run1": "mixed_m", "run2": "single_m", "run3": "mixed_f", "run4": "single_f"},
+  "sub-12": {"run1": "mixed_m", "run2": "single_m", "run3": "mixed_f", "run4": "single_f"},
+  "sub-13": {"run1": "mixed_m", "run2": "mixed_f", "run3": "single_m", "run4": "single_f"},
+  "sub-14": {"run1": "mixed_f", "run2": "mixed_m", "run3": "single_f", "run4": "single_m"},
+  "sub-15": {"run1": "single_m", "run2": "single_f", "run3": "mixed_m", "run4": "mixed_f"},
+  "sub-16": {"run1": "single_f", "run2": "single_m", "run3": "mixed_f", "run4": "mixed_m"},
+  "sub-17": {"run1": "mixed_f", "run2": "single_f", "run3": "mixed_m", "run4": "single_m"},
+  "sub-18": {"run1": "single_f", "run2": "single_m", "run3": "mixed_m", "run4": "mixed_f"},
+  "sub-19": {"run1": "mixed_f", "run2": "single_m", "run3": "mixed_m", "run4": "single_f"},
+  "sub-20": {"run1": "single_m", "run2": "mixed_f", "run3": "single_f", "run4": "mixed_m"},
+  "sub-21": {"run1": "single_f", "run2": "mixed_m", "run3": "mixed_f", "run4": "single_m"},
+  "sub-22": {"run1": "mixed_f", "run2": "mixed_m", "run3": "single_f", "run4": "single_m"},
+  "sub-23": {"run1": "mixed_f", "run2": "single_f", "run3": "single_m", "run4": "mixed_m"},
+  "sub-24": {"run1": "mixed_m", "run2": "single_m", "run3": "single_f", "run4": "mixed_f"},
+  "sub-25": {"run1": "mixed_m", "run2": "mixed_f", "run3": "single_f", "run4": "single_m"},
+  "sub-26": {"run1": "mixed_f", "run2": "mixed_m", "run3": "single_f", "run4": "single_m"}
+}

code/assets/roi_masks/README.md

@@ -0,0 +1,16 @@
+# Core ROI Mask Assets
+
+This folder contains the 7 core ROI masks used by the A1 preservation gate:
+
+- TP.nii.gz
+- aSTS.nii.gz
+- pSTS.nii.gz
+- BA44.nii.gz
+- BA45.nii.gz
+- BA47.nii.gz
+- AG_TPJ.nii.gz
+
+These masks were copied from the upstream llms_brain_lateralization repository to keep
+runtime dependencies modular and local to the code/ tree.
+
+If you need to override these masks, pass --roi-mask-dir to code/run_a1_bootstrap.py.

code/config/model_profiles.json

@@ -0,0 +1,36 @@
+{
+  "schema_version": 1,
+  "active_profile": "current",
+  "profiles": {
+    "current": {
+      "description": "Current A1 text model set (Qwen3 0.6B + Llama 3.2 1B + LLaDA 8B Instruct)",
+      "model_ids": [
+        "Qwen/Qwen3-0.6B",
+        "meta-llama/Llama-3.2-1B",
+        "GSAI-ML/LLaDA-8B-Instruct"
+      ]
+    },
+    "future_scaleup": {
+      "description": "Planned scale-up set (Qwen3 4B + Llama 3.2 3B + LLaDA 8B Instruct)",
+      "model_ids": [
+        "Qwen/Qwen3-4B",
+        "meta-llama/Llama-3.2-3B",
+        "GSAI-ML/LLaDA-8B-Instruct"
+      ]
+    }
+  },
+  "families": {
+    "qwen3": {
+      "current": "Qwen/Qwen3-0.6B",
+      "future": "Qwen/Qwen3-4B"
+    },
+    "llama32_text": {
+      "current": "meta-llama/Llama-3.2-1B",
+      "future": "meta-llama/Llama-3.2-3B"
+    },
+    "llada_text": {
+      "current": "GSAI-ML/LLaDA-8B-Instruct",
+      "future": "GSAI-ML/LLaDA-8B-Instruct"
+    }
+  }
+}

code/run_a1_visualize.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python
+"""Visualize A1 fit outputs for core ROI evaluation."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import matplotlib
+
+matplotlib.use("Agg")
+
+import matplotlib.pyplot as plt
+import pandas as pd
+import seaborn as sns
+
+from a1_pipeline.io_utils import ensure_directory
+
+
+METRIC_ALIAS_MAP: dict[str, str] = {
+    "2v2": "mean_2v2_accuracy",
+    "2v2_accuracy": "mean_2v2_accuracy",
+    "two_v_two_accuracy": "mean_2v2_accuracy",
+}
+
+
+def _resolve_metric_column(metric: str) -> str:
+    token = str(metric).strip().lower()
+    return METRIC_ALIAS_MAP.get(token, str(metric))
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Visualize A1 core ROI fit results")
+    parser.add_argument(
+        "--fit-output-dir",
+        type=str,
+        default="/home/mohith/ds005345/outputs/a1_bootstrap/fit_results/Qwen_Qwen3-0.6B",
+        help="Directory containing run_a1_fit.py outputs",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=str,
+        default=None,
+        help="Plot output directory (default: <fit-output-dir>/plots)",
+    )
+    parser.add_argument(
+        "--metric",
+        type=str,
+        default="mean_corr",
+        choices=[
+            "mean_corr",
+            "mean_r2",
+            "mean_2v2_accuracy",
+            "2v2",
+            "2v2_accuracy",
+            "two_v_two_accuracy",
+        ],
+        help="Metric used for plots",
+    )
+    return parser
+
+
+def _check_required_files(fit_output_dir: Path) -> tuple[Path, Path]:
+    layer_summary_path = fit_output_dir / "core_roi_layer_summary.csv"
+    best_summary_path = fit_output_dir / "core_roi_best_layer_summary.csv"
+
+    missing = [path for path in [layer_summary_path, best_summary_path] if not path.exists()]
+    if missing:
+        raise FileNotFoundError("Missing fit summary files: " + ", ".join(str(path) for path in missing))
+
+    return layer_summary_path, best_summary_path
+
+
+def _plot_protocol_heatmap(
+    layer_summary_df: pd.DataFrame,
+    protocol: str,
+    metric: str,
+    output_path: Path,
+) -> None:
+    protocol_df = layer_summary_df[layer_summary_df["protocol"] == protocol].copy()
+    if protocol_df.empty:
+        return
+
+    pivot_df = protocol_df.pivot(index="roi_name", columns="layer_idx", values=metric)
+    pivot_df = pivot_df.sort_index()
+
+    plt.figure(figsize=(max(8, 0.4 * len(pivot_df.columns)), 4.8))
+    sns.heatmap(pivot_df, cmap="viridis", annot=False)
+    plt.title(f"{protocol} {metric} by ROI and Layer")
+    plt.xlabel("Layer")
+    plt.ylabel("Core ROI")
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=180)
+    plt.close()
+
+
+def _plot_best_layer_bar(
+    best_df: pd.DataFrame,
+    metric: str,
+    output_path: Path,
+) -> None:
+    if best_df.empty:
+        return
+
+    chart_df = best_df.copy()
+    chart_df["label"] = chart_df["roi_name"] + "\nL" + chart_df["layer_idx"].astype(int).astype(str)
+
+    plt.figure(figsize=(11, 5))
+    sns.barplot(data=chart_df, x="label", y=metric, hue="protocol")
+    plt.title(f"Best Layer per ROI ({metric})")
+    plt.xlabel("ROI and selected layer")
+    plt.ylabel(metric)
+    plt.xticks(rotation=0)
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=180)
+    plt.close()
+
+
+def _plot_protocol_layer_curve(
+    layer_summary_df: pd.DataFrame,
+    metric: str,
+    output_path: Path,
+) -> None:
+    if layer_summary_df.empty:
+        return
+
+    curve_df = (
+        layer_summary_df.groupby(["protocol", "layer_idx"], as_index=False)[metric]
+        .mean()
+        .sort_values(["protocol", "layer_idx"])
+    )
+
+    plt.figure(figsize=(10, 4.8))
+    sns.lineplot(data=curve_df, x="layer_idx", y=metric, hue="protocol", marker="o")
+    plt.title(f"Average Core ROI {metric} by Layer")
+    plt.xlabel("Layer")
+    plt.ylabel(metric)
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=180)
+    plt.close()
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    fit_output_dir = Path(args.fit_output_dir).resolve()
+    layer_summary_path, best_summary_path = _check_required_files(fit_output_dir=fit_output_dir)
+
+    plot_output_dir = Path(args.output_dir).resolve() if args.output_dir else fit_output_dir / "plots"
+    ensure_directory(plot_output_dir)
+
+    layer_summary_df = pd.read_csv(layer_summary_path)
+    best_summary_df = pd.read_csv(best_summary_path)
+
+    metric = _resolve_metric_column(str(args.metric))
+    if metric not in layer_summary_df.columns:
+        raise ValueError(
+            f"Metric column '{metric}' not found in {layer_summary_path}. "
+            f"Available columns: {sorted(layer_summary_df.columns.tolist())}"
+        )
+    if metric not in best_summary_df.columns:
+        raise ValueError(
+            f"Metric column '{metric}' not found in {best_summary_path}. "
+            f"Available columns: {sorted(best_summary_df.columns.tolist())}"
+        )
+
+    for protocol in sorted(set(layer_summary_df["protocol"].tolist())):
+        heatmap_path = plot_output_dir / f"{protocol}_{metric}_heatmap.png"
+        _plot_protocol_heatmap(
+            layer_summary_df=layer_summary_df,
+            protocol=protocol,
+            metric=metric,
+            output_path=heatmap_path,
+        )
+
+    _plot_best_layer_bar(
+        best_df=best_summary_df,
+        metric=metric,
+        output_path=plot_output_dir / f"best_layer_{metric}_bar.png",
+    )
+
+    _plot_protocol_layer_curve(
+        layer_summary_df=layer_summary_df,
+        metric=metric,
+        output_path=plot_output_dir / f"protocol_layer_curve_{metric}.png",
+    )
+
+    print("=" * 72)
+    print("A1 visualization complete")
+    print(f"Fit output directory: {fit_output_dir}")
+    print(f"Plot output directory: {plot_output_dir}")
+    print(f"Metric: {metric}")
+    print("=" * 72)
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,13 @@
+numpy==2.2.6
+pandas==2.3.3
+scikit-learn==1.7.2
+torch==2.5.1
+torchvision==0.20.1
+torchaudio==2.5.1
+transformers==5.5.3
+matplotlib==3.10.8
+seaborn==0.13.2
+scipy==1.15.3
+nibabel==5.4.2
+tqdm==4.67.3
+requests==2.33.1