Dashboard v2: research-grade rebuild

Biologically realistic synthetic data:
- HRF convolution with canonical double-gamma response
- Modality-specific ROI activation weights (visual/auditory/language/multimodal)
- Spatial smoothing, AR(1) temporal noise, scanner drift
- Controllable alignment strength for meaningful benchmark scores

Shared session state:
- Cross-page ROI carry (alignment -> temporal dynamics -> connectivity)
- File upload (.npy) and download (CSV, JSON) support
- Analysis log tracking across pages
- Data source selector (synthetic vs uploaded)

Brain Alignment (rebuilt):
- Bootstrap CI error bars on all scores
- Null distribution histograms with observed score overlay
- RDM visualization (brain vs model side-by-side)
- FDR correction for per-ROI tests
- Noise ceiling estimation (split-half reliability)
- Methodology documentation with references

Cognitive Load (rebuilt):
- Confidence bands on timeline (bootstrap across vertices)
- Dimension correlation heatmap
- Per-ROI activation breakdown within each dimension
- Comparison mode (two stimulus types side-by-side)

Temporal Dynamics (rebuilt):
- Raw ROI timecourses showing HRF shape
- Peak latency sorted by processing hierarchy
- Lag correlation with 95% null significance band
- Optimal lag summary table
- Cross-ROI lag matrix
- 3-panel sustained/transient decomposition

Connectivity (rebuilt):
- Partial correlation option
- Correlation matrix with cluster boundary lines
- Dendrogram visualization
- Modularity Q score with interpretation
- Betweenness centrality alongside degree
- Edge weight distribution histogram
- Network graph with weighted edges and sized nodes
- Cluster-to-functional-group mapping

Home.py

@@ -1,50 +1,110 @@
-"""CortexLab Dashboard - Home Page."""
+"""CortexLab Dashboard - Home Page with Data Management."""
 
 import streamlit as st
+import numpy as np
 
-st.set_page_config(
-    page_title="CortexLab Dashboard",
-    page_icon="🧠",
-    layout="wide",
-    initial_sidebar_state="expanded",
-)
+from session import init_session, data_summary_widget, show_analysis_log, upload_npy_widget
+from utils import make_roi_indices
+
+st.set_page_config(page_title="CortexLab Dashboard", page_icon="🧠", layout="wide", initial_sidebar_state="expanded")
+init_session()
 
 st.title("CortexLab Dashboard")
-st.markdown("**Interactive analysis toolkit for multimodal fMRI brain encoding**")
+st.markdown("**Research-grade analysis toolkit for multimodal fMRI brain encoding**")
 
+# --- Data Source ---
 st.divider()
+st.subheader("Data Configuration")
+
+col_src, col_params = st.columns([1, 2])
+
+with col_src:
+    source = st.radio("Data source", ["Synthetic (realistic)", "Upload your data"], index=0)
+    st.session_state["data_source"] = "synthetic" if "Synthetic" in source else "uploaded"
+
+with col_params:
+    if st.session_state["data_source"] == "synthetic":
+        c1, c2, c3, c4 = st.columns(4)
+        st.session_state["stimulus_type"] = c1.selectbox("Stimulus type", ["visual", "auditory", "language", "multimodal"])
+        st.session_state["n_timepoints"] = c2.slider("Duration (TRs)", 30, 200, 80)
+        st.session_state["tr_seconds"] = c3.slider("TR (seconds)", 0.5, 2.0, 1.0, 0.1)
+        st.session_state["seed"] = c4.number_input("Seed", value=42, min_value=0)
+
+        # Generate on config change
+        roi_indices, n_vertices = make_roi_indices()
+        st.session_state["roi_indices"] = roi_indices
+        st.session_state["n_vertices"] = n_vertices
+
+        from synthetic import generate_realistic_predictions
+        predictions = generate_realistic_predictions(
+            st.session_state["n_timepoints"], roi_indices,
+            st.session_state["stimulus_type"], st.session_state["tr_seconds"],
+            seed=st.session_state["seed"],
+        )
+        st.session_state["brain_predictions"] = predictions
+    else:
+        uploaded = upload_npy_widget("Upload brain predictions (.npy, shape: timepoints x vertices)", "upload_predictions")
+        if uploaded is not None:
+            st.session_state["brain_predictions"] = uploaded
+            roi_indices, _ = make_roi_indices()
+            st.session_state["roi_indices"] = roi_indices
+
+# --- Data Summary ---
+roi_indices = st.session_state.get("roi_indices")
+predictions = st.session_state.get("brain_predictions")
+if predictions is not None and roi_indices is not None:
+    data_summary_widget(predictions, roi_indices)
+
+    # Show HRF-convolved signal preview
+    with st.expander("Data Preview", expanded=False):
+        import plotly.graph_objects as go
+        from utils import ROI_GROUPS
 
+        fig = go.Figure()
+        t = np.arange(predictions.shape[0]) * st.session_state.get("tr_seconds", 1.0)
+        colors = {"Visual": "#00D2FF", "Auditory": "#FF6B6B", "Language": "#A29BFE", "Executive": "#FFEAA7"}
+        for group, rois in ROI_GROUPS.items():
+            vals = []
+            for roi in rois:
+                if roi in roi_indices:
+                    verts = roi_indices[roi]
+                    valid = verts[verts < predictions.shape[1]]
+                    if len(valid) > 0:
+                        vals.append(np.abs(predictions[:, valid]).mean(axis=1))
+            if vals:
+                mean_tc = np.mean(vals, axis=0)
+                fig.add_trace(go.Scatter(x=t, y=mean_tc, name=group, line=dict(color=colors.get(group, "#888"), width=2)))
+
+        fig.update_layout(
+            xaxis_title="Time (seconds)", yaxis_title="Mean |activation|",
+            height=300, template="plotly_dark",
+            legend=dict(orientation="h", yanchor="bottom", y=1.02),
+        )
+        st.plotly_chart(fig, use_container_width=True)
+        st.caption("Mean absolute activation per functional group. Note the hemodynamic response shape and modality-specific activation patterns.")
+
+# --- Navigation ---
+st.divider()
 col1, col2 = st.columns(2)
 
 with col1:
     st.subheader("Analysis Tools")
     st.page_link("pages/1_Brain_Alignment.py", label="Brain Alignment Benchmark", icon="🎯")
-    st.markdown("Score how brain-like any AI model's representations are using RSA, CKA, or Procrustes")
+    st.caption("RSA, CKA, Procrustes with permutation tests, bootstrap CIs, FDR correction, noise ceiling, and RDM visualization")
 
     st.page_link("pages/2_Cognitive_Load.py", label="Cognitive Load Scorer", icon="📊")
-    st.markdown("Predict cognitive demand across visual, auditory, language, and executive dimensions")
+    st.caption("Timeline with confidence bands, dimension correlation, per-ROI breakdown, comparison mode")
 
 with col2:
     st.subheader("Advanced Analysis")
     st.page_link("pages/3_Temporal_Dynamics.py", label="Temporal Dynamics", icon="⏱️")
-    st.markdown("Analyze peak response latency, lag correlations, and sustained vs transient components")
+    st.caption("Raw timecourses, peak latency hierarchy, optimal lag analysis, cross-ROI lag matrix")
 
     st.page_link("pages/4_Connectivity.py", label="ROI Connectivity", icon="🔗")
-    st.markdown("Compute functional connectivity matrices, cluster networks, and graph metrics")
+    st.caption("Partial correlation, modularity, betweenness centrality, dendrogram, network graph")
 
-st.divider()
+# --- Analysis Log ---
+show_analysis_log()
 
-st.subheader("About")
-st.markdown(
-    """
-CortexLab is an enhanced toolkit built on [Meta's TRIBE v2](https://github.com/facebookresearch/tribev2)
-for predicting how the human brain responds to video, audio, and text.
-
-This dashboard runs on **synthetic data** by default - no GPU or real fMRI data required.
-All analysis tools mirror the CortexLab Python API.
-
-[GitHub](https://github.com/siddhant-rajhans/cortexlab)
-&nbsp; | &nbsp;
-[HuggingFace](https://huggingface.co/SID2000/cortexlab)
-"""
-)
+st.divider()
+st.caption("[GitHub](https://github.com/siddhant-rajhans/cortexlab) | [HuggingFace](https://huggingface.co/SID2000/cortexlab) | [Dashboard Repo](https://github.com/siddhant-rajhans/cortexlab-dashboard)")

pages/1_Brain_Alignment.py

@@ -1,4 +1,4 @@
-"""Brain Alignment Benchmark page."""
+"""Brain Alignment Benchmark - Research Grade."""
 
 import streamlit as st
 import numpy as np
@@ -6,135 +6,245 @@ import pandas as pd
 import plotly.graph_objects as go
 import plotly.express as px
 
+from session import init_session, log_analysis, carry_rois, download_csv_button, show_analysis_log
 from utils import (
-    ALIGNMENT_METHODS,
-    make_roi_indices,
-    generate_brain_predictions,
-    generate_model_features,
-    permutation_test,
+    ALIGNMENT_METHODS, ROI_GROUPS, make_roi_indices,
+    permutation_test, bootstrap_ci, fdr_correction, noise_ceiling,
+    compute_rdm,
 )
+from synthetic import generate_realistic_predictions, generate_correlated_features
 
 st.set_page_config(page_title="Brain Alignment", page_icon="🎯", layout="wide")
+init_session()
+show_analysis_log()
+
 st.title("🎯 Brain Alignment Benchmark")
-st.markdown("Compare how well AI model representations align with predicted brain responses.")
+st.markdown("Score how well AI model representations align with predicted brain responses, with full statistical testing.")
 
-# --- Sidebar Controls ---
+# --- Sidebar ---
 with st.sidebar:
     st.header("Configuration")
-    n_stimuli = st.slider("Number of stimuli", 10, 200, 50)
-    seed = st.number_input("Random seed", value=42, min_value=0)
-
-    st.subheader("Models to compare")
-    models_config = {
-        "CLIP ViT-L/14": st.checkbox("CLIP ViT-L/14", value=True),
-        "DINOv2 ViT-S": st.checkbox("DINOv2 ViT-S", value=True),
-        "V-JEPA2 ViT-G": st.checkbox("V-JEPA2 ViT-G", value=True),
-        "LLaMA 3.2-3B": st.checkbox("LLaMA 3.2-3B", value=False),
-    }
-    model_dims = {
-        "CLIP ViT-L/14": 768,
-        "DINOv2 ViT-S": 384,
-        "V-JEPA2 ViT-G": 1024,
-        "LLaMA 3.2-3B": 3072,
+    stimulus = st.selectbox("Stimulus type", ["visual", "auditory", "language", "multimodal"],
+                            index=["visual", "auditory", "language", "multimodal"].index(st.session_state.get("stimulus_type", "visual")))
+    n_timepoints = st.slider("Timepoints", 30, 200, st.session_state.get("n_timepoints", 80))
+    seed = st.number_input("Seed", value=st.session_state.get("seed", 42), min_value=0)
+
+    st.subheader("Models")
+    model_configs = {
+        "CLIP ViT-L/14": {"dim": 768, "alignment": st.slider("CLIP alignment", 0.0, 1.0, 0.6, 0.05)},
+        "DINOv2 ViT-S": {"dim": 384, "alignment": st.slider("DINOv2 alignment", 0.0, 1.0, 0.3, 0.05)},
+        "V-JEPA2 ViT-G": {"dim": 1024, "alignment": st.slider("V-JEPA2 alignment", 0.0, 1.0, 0.8, 0.05)},
     }
-    selected_models = [m for m, checked in models_config.items() if checked]
 
+    st.subheader("Methods & Statistics")
     methods = st.multiselect("Methods", ["RSA", "CKA", "Procrustes"], default=["RSA", "CKA"])
-    run_stats = st.checkbox("Run permutation test", value=False)
-    n_perm = st.slider("Permutations", 50, 1000, 200) if run_stats else 0
+    n_perm = st.slider("Permutations", 50, 1000, 200)
+    n_boot = st.slider("Bootstrap samples", 100, 2000, 500)
+    apply_fdr = st.checkbox("Apply FDR correction", value=True)
 
-if not selected_models or not methods:
-    st.warning("Select at least one model and one method.")
+if not methods:
+    st.warning("Select at least one method.")
     st.stop()
 
 # --- Generate Data ---
 roi_indices, n_vertices = make_roi_indices()
-brain_pred = generate_brain_predictions(n_stimuli, n_vertices, seed)
+brain_pred = generate_realistic_predictions(n_timepoints, roi_indices, stimulus, seed=seed)
 
 model_features = {}
-for i, name in enumerate(selected_models):
-    model_features[name] = generate_model_features(n_stimuli, model_dims[name], seed + i + 1)
+for i, (name, cfg) in enumerate(model_configs.items()):
+    model_features[name] = generate_correlated_features(
+        brain_pred, cfg["alignment"], cfg["dim"], seed=seed + i + 1
+    )
 
 # --- Run Benchmark ---
-with st.spinner("Computing alignment scores..."):
+with st.spinner("Computing alignment scores with statistical testing..."):
     results = []
+    null_distributions = {}
+
     for model_name, features in model_features.items():
         for method_name in methods:
             score_fn = ALIGNMENT_METHODS[method_name]
-            score = score_fn(features, brain_pred)
-            row = {"Model": model_name, "Method": method_name, "Score": score}
-
-            if run_stats:
-                _, p_val = permutation_test(features, brain_pred, score_fn, n_perm, seed)
-                row["p-value"] = p_val
-                row["Significant"] = "Yes" if p_val < 0.05 else "No"
-
-            results.append(row)
-
-df = pd.DataFrame(results)
-
-# --- Display Results ---
-col1, col2 = st.columns([2, 1])
-
-with col1:
-    st.subheader("Alignment Scores")
-    fig = px.bar(
-        df,
-        x="Model",
-        y="Score",
-        color="Method",
-        barmode="group",
-        color_discrete_sequence=px.colors.qualitative.Set2,
-    )
+            observed, p_val, null_dist = permutation_test(features, brain_pred, score_fn, n_perm, seed)
+            point, ci_lo, ci_hi = bootstrap_ci(features, brain_pred, score_fn, n_boot, seed=seed)
+            null_distributions[f"{model_name}_{method_name}"] = null_dist
+
+            results.append({
+                "Model": model_name,
+                "Method": method_name,
+                "Score": observed,
+                "CI Lower": ci_lo,
+                "CI Upper": ci_hi,
+                "p-value": p_val,
+            })
+
+    df = pd.DataFrame(results)
+    log_analysis(f"Brain alignment: {len(model_features)} models x {len(methods)} methods")
+
+# --- Noise Ceiling ---
+ceiling_scores = {}
+for method_name in methods:
+    score_fn = ALIGNMENT_METHODS[method_name]
+    ceil_mean, ceil_std = noise_ceiling(brain_pred, score_fn, seed=seed)
+    ceiling_scores[method_name] = ceil_mean
+
+# --- Display: Alignment Scores with CIs ---
+st.subheader("Alignment Scores")
+
+col_chart, col_table = st.columns([2, 1])
+
+with col_chart:
+    fig = go.Figure()
+    method_colors = {"RSA": "#00D2FF", "CKA": "#FF6B6B", "Procrustes": "#A29BFE"}
+    x_positions = list(model_configs.keys())
+
+    for method_name in methods:
+        method_df = df[df["Method"] == method_name]
+        fig.add_trace(go.Bar(
+            name=method_name,
+            x=method_df["Model"],
+            y=method_df["Score"],
+            error_y=dict(
+                type="data",
+                symmetric=False,
+                array=(method_df["CI Upper"] - method_df["Score"]).tolist(),
+                arrayminus=(method_df["Score"] - method_df["CI Lower"]).tolist(),
+            ),
+            marker_color=method_colors.get(method_name, "#888"),
+        ))
+        # Noise ceiling line
+        if method_name in ceiling_scores:
+            fig.add_hline(
+                y=ceiling_scores[method_name],
+                line_dash="dash", line_color=method_colors.get(method_name, "#888"),
+                opacity=0.4,
+                annotation_text=f"{method_name} ceiling",
+                annotation_position="top right",
+            )
+
     fig.update_layout(
-        yaxis_title="Alignment Score",
-        height=450,
-        template="plotly_dark",
+        barmode="group", yaxis_title="Alignment Score",
+        height=450, template="plotly_dark",
+        legend=dict(orientation="h", yanchor="bottom", y=1.02),
     )
     st.plotly_chart(fig, use_container_width=True)
 
-with col2:
-    st.subheader("Results Table")
+with col_table:
+    st.subheader("Results")
     display_df = df.copy()
-    display_df["Score"] = display_df["Score"].map(lambda x: f"{x:.4f}")
-    if "p-value" in display_df.columns:
-        display_df["p-value"] = display_df["p-value"].map(lambda x: f"{x:.4f}")
+    for col in ["Score", "CI Lower", "CI Upper", "p-value"]:
+        display_df[col] = display_df[col].map(lambda x: f"{x:.4f}")
     st.dataframe(display_df, use_container_width=True, hide_index=True)
-
-# --- Per-ROI Analysis ---
+    download_csv_button(df, "brain_alignment_results.csv")
+
+# --- Null Distribution ---
+with st.expander("Null Distributions (Permutation Tests)", expanded=False):
+    st.markdown("The histogram shows the distribution of scores under the null hypothesis (no alignment). "
+                "The red line marks the observed score. If it falls far to the right, alignment is significant.")
+    cols = st.columns(min(len(null_distributions), 3))
+    for i, (key, null_dist) in enumerate(null_distributions.items()):
+        model_name, method_name = key.rsplit("_", 1)
+        row = df[(df["Model"] == model_name) & (df["Method"] == method_name)].iloc[0]
+        with cols[i % len(cols)]:
+            fig_null = go.Figure()
+            fig_null.add_trace(go.Histogram(x=null_dist, nbinsx=30, marker_color="rgba(100,100,100,0.6)", name="Null"))
+            fig_null.add_vline(x=row["Score"], line_color="red", line_width=2, annotation_text=f"Observed")
+            fig_null.update_layout(
+                title=f"{model_name} ({method_name})",
+                xaxis_title="Score", yaxis_title="Count",
+                height=250, template="plotly_dark", showlegend=False,
+                margin=dict(t=40, b=30, l=30, r=10),
+            )
+            st.plotly_chart(fig_null, use_container_width=True)
+            st.caption(f"p = {row['p-value']:.4f}")
+
+# --- RDM Visualization ---
+with st.expander("Representational Dissimilarity Matrices", expanded=False):
+    st.markdown("RDMs show pairwise dissimilarity between stimulus representations. "
+                "Similar RDM structure between model and brain indicates representational alignment.")
+    rdm_model_name = st.selectbox("Model for RDM", list(model_features.keys()))
+    col_brain, col_model = st.columns(2)
+
+    brain_rdm = compute_rdm(brain_pred)
+    model_rdm = compute_rdm(model_features[rdm_model_name])
+
+    with col_brain:
+        fig_rdm = go.Figure(go.Heatmap(z=brain_rdm, colorscale="Viridis", colorbar=dict(title="Dissimilarity")))
+        fig_rdm.update_layout(title="Brain RDM", height=350, template="plotly_dark", xaxis_title="Stimulus", yaxis_title="Stimulus")
+        st.plotly_chart(fig_rdm, use_container_width=True)
+
+    with col_model:
+        fig_rdm2 = go.Figure(go.Heatmap(z=model_rdm, colorscale="Viridis", colorbar=dict(title="Dissimilarity")))
+        fig_rdm2.update_layout(title=f"{rdm_model_name} RDM", height=350, template="plotly_dark", xaxis_title="Stimulus", yaxis_title="Stimulus")
+        st.plotly_chart(fig_rdm2, use_container_width=True)
+
+# --- Per-ROI Analysis with FDR ---
 st.divider()
-st.subheader("Per-ROI Alignment (RSA)")
-
-if "RSA" in methods and len(selected_models) >= 1:
-    from utils import ROI_GROUPS, rsa_score
-
-    roi_data = []
-    for model_name, features in model_features.items():
-        for group_name, rois in ROI_GROUPS.items():
-            group_scores = []
-            for roi in rois:
-                if roi in roi_indices:
-                    verts = roi_indices[roi]
-                    valid = verts[verts < brain_pred.shape[1]]
-                    if len(valid) >= 2:
-                        s = rsa_score(features, brain_pred[:, valid])
-                        group_scores.append(s)
-            if group_scores:
-                roi_data.append({
-                    "Model": model_name,
-                    "Region": group_name,
-                    "RSA Score": float(np.mean(group_scores)),
-                })
-
-    if roi_data:
-        roi_df = pd.DataFrame(roi_data)
-        fig2 = px.bar(
-            roi_df,
-            x="Region",
-            y="RSA Score",
-            color="Model",
-            barmode="group",
-            color_discrete_sequence=px.colors.qualitative.Pastel,
-        )
-        fig2.update_layout(height=400, template="plotly_dark")
-        st.plotly_chart(fig2, use_container_width=True)
+st.subheader("Per-ROI Alignment")
+
+roi_method = st.selectbox("Method for ROI analysis", methods, key="roi_method")
+score_fn = ALIGNMENT_METHODS[roi_method]
+
+roi_data = []
+roi_p_values = []
+top_model = df[df["Method"] == roi_method].sort_values("Score", ascending=False).iloc[0]["Model"]
+features = model_features[top_model]
+
+for group_name, rois in ROI_GROUPS.items():
+    for roi in rois:
+        if roi in roi_indices:
+            verts = roi_indices[roi]
+            valid = verts[verts < brain_pred.shape[1]]
+            if len(valid) >= 2:
+                s = score_fn(features, brain_pred[:, valid])
+                _, p, _ = permutation_test(features, brain_pred[:, valid], score_fn, n_perm=50, seed=seed)
+                roi_data.append({"ROI": roi, "Group": group_name, "Score": s, "p-value": p})
+                roi_p_values.append(p)
+
+if roi_data:
+    roi_df = pd.DataFrame(roi_data)
+    if apply_fdr and len(roi_p_values) > 1:
+        corrected_p, significant = fdr_correction(roi_p_values)
+        roi_df["FDR p-value"] = corrected_p
+        roi_df["Significant"] = significant
+        roi_df["Label"] = roi_df.apply(lambda r: f"{r['ROI']} *" if r["Significant"] else r["ROI"], axis=1)
+    else:
+        roi_df["Label"] = roi_df["ROI"]
+        roi_df["Significant"] = roi_df["p-value"] < 0.05
+
+    group_colors = {"Visual": "#00D2FF", "Auditory": "#FF6B6B", "Language": "#A29BFE", "Executive": "#FFEAA7"}
+    fig_roi = px.bar(roi_df, x="Label", y="Score", color="Group",
+                     color_discrete_map=group_colors)
+    fig_roi.update_layout(height=400, template="plotly_dark", xaxis_tickangle=45)
+    st.plotly_chart(fig_roi, use_container_width=True)
+    st.caption(f"Model: {top_model} | * = significant after FDR correction (q < 0.05)" if apply_fdr else f"Model: {top_model}")
+
+    # Carry ROIs button
+    sig_rois = roi_df[roi_df["Significant"]]["ROI"].tolist() if "Significant" in roi_df.columns else []
+    if sig_rois:
+        if st.button(f"Carry {len(sig_rois)} significant ROIs to other pages"):
+            carry_rois(sig_rois, "Temporal Dynamics / Connectivity")
+            st.success(f"Carried {len(sig_rois)} ROIs: {', '.join(sig_rois[:5])}{'...' if len(sig_rois) > 5 else ''}")
+
+# --- Methodology ---
+with st.expander("Methodology", expanded=False):
+    st.markdown("""
+**Representational Similarity Analysis (RSA)** compares the geometry of two representation
+spaces by computing pairwise dissimilarity matrices (RDMs) and correlating their upper triangles
+via Spearman rank correlation. Range: [-1, 1]. Values > 0.1 are typically meaningful.
+*Kriegeskorte et al., 2008, Frontiers in Systems Neuroscience.*
+
+**Centered Kernel Alignment (CKA)** measures similarity between representations using
+HSIC (Hilbert-Schmidt Independence Criterion) normalized by self-similarities. Invariant to
+orthogonal transformations and isotropic scaling. Range: [0, 1].
+*Kornblith et al., 2019, ICML.*
+
+**Procrustes** finds the optimal rotation mapping one space onto another and measures
+residual distance. Score = 1 - normalized Procrustes distance. Range: [0, 1].
+*Ding et al., 2021, NeurIPS.*
+
+**Noise ceiling** estimates the maximum achievable alignment score given the noise in the
+brain data, computed via split-half reliability.
+
+**FDR correction** (Benjamini-Hochberg) controls the false discovery rate when testing
+multiple ROIs simultaneously.
+""")

pages/2_Cognitive_Load.py

@@ -1,4 +1,4 @@
-"""Cognitive Load Scorer page."""
+"""Cognitive Load Scorer - Research Grade."""
 
 import streamlit as st
 import numpy as np
@@ -6,126 +6,208 @@ import pandas as pd
 import plotly.graph_objects as go
 import plotly.express as px
 
-from utils import (
-    make_roi_indices,
-    generate_brain_predictions,
-    score_cognitive_load,
-    COGNITIVE_DIMENSIONS,
-)
+from session import init_session, log_analysis, download_csv_button, show_analysis_log
+from utils import make_roi_indices, score_cognitive_load, COGNITIVE_DIMENSIONS, ROI_GROUPS
+from synthetic import generate_realistic_predictions
 
 st.set_page_config(page_title="Cognitive Load", page_icon="📊", layout="wide")
+init_session()
+show_analysis_log()
+
 st.title("📊 Cognitive Load Scorer")
-st.markdown("Predict cognitive demand of media content from brain activation patterns.")
+st.markdown("Predict cognitive demand from brain activation patterns across four neurocognitive dimensions.")
 
 # --- Sidebar ---
 with st.sidebar:
     st.header("Configuration")
-    n_timepoints = st.slider("Duration (TRs)", 20, 200, 60)
-    tr_seconds = st.slider("TR duration (seconds)", 0.5, 2.0, 1.0, 0.1)
-    seed = st.number_input("Random seed", value=42, min_value=0)
-
-    st.subheader("Simulate content type")
-    content_type = st.selectbox(
-        "Content profile",
-        ["Balanced", "Visual-heavy", "Audio-heavy", "Language-heavy", "Low engagement"],
-    )
+    n_timepoints = st.slider("Duration (TRs)", 30, 200, 80)
+    tr_seconds = st.slider("TR (seconds)", 0.5, 2.0, 1.0, 0.1)
+    seed = st.number_input("Seed", value=42, min_value=0)
 
-# --- Generate Data ---
-roi_indices, n_vertices = make_roi_indices()
-predictions = generate_brain_predictions(n_timepoints, n_vertices, seed)
+    st.subheader("Stimulus")
+    stim_type = st.selectbox("Primary stimulus", ["visual", "auditory", "language", "multimodal"])
 
-# Apply content profile by amplifying relevant ROIs
-multipliers = {"Balanced": {}, "Visual-heavy": {}, "Audio-heavy": {}, "Language-heavy": {}, "Low engagement": {}}
-if content_type == "Visual-heavy":
-    for roi in COGNITIVE_DIMENSIONS["Visual Complexity"]:
-        if roi in roi_indices:
-            predictions[:, roi_indices[roi]] *= 3.0
-elif content_type == "Audio-heavy":
-    for roi in COGNITIVE_DIMENSIONS["Auditory Demand"]:
-        if roi in roi_indices:
-            predictions[:, roi_indices[roi]] *= 3.0
-elif content_type == "Language-heavy":
-    for roi in COGNITIVE_DIMENSIONS["Language Processing"]:
-        if roi in roi_indices:
-            predictions[:, roi_indices[roi]] *= 3.0
-elif content_type == "Low engagement":
-    predictions *= 0.2
+    st.subheader("Comparison Mode")
+    compare = st.checkbox("Compare two stimulus types", value=False)
+    if compare:
+        stim_type_2 = st.selectbox("Second stimulus", [s for s in ["visual", "auditory", "language", "multimodal"] if s != stim_type])
 
-# --- Score ---
+# --- Generate Data ---
+roi_indices, n_vertices = make_roi_indices()
+predictions = generate_realistic_predictions(n_timepoints, roi_indices, stim_type, tr_seconds, seed=seed)
 averages, timeline = score_cognitive_load(predictions, roi_indices, tr_seconds)
+log_analysis(f"Cognitive load: {stim_type}, {n_timepoints} TRs")
+
+if compare:
+    predictions_2 = generate_realistic_predictions(n_timepoints, roi_indices, stim_type_2, tr_seconds, seed=seed + 100)
+    averages_2, timeline_2 = score_cognitive_load(predictions_2, roi_indices, tr_seconds)
 
-# --- Display ---
-col1, col2, col3, col4, col5 = st.columns(5)
+# --- Metric Cards ---
 dims = ["Overall", "Visual Complexity", "Auditory Demand", "Language Processing", "Executive Load"]
-cols = [col1, col2, col3, col4, col5]
+cols = st.columns(5)
 for col, dim in zip(cols, dims):
     val = averages.get(dim, 0.0)
-    col.metric(dim, f"{val:.2f}", delta=None)
+    if compare:
+        val_2 = averages_2.get(dim, 0.0)
+        delta = val - val_2
+        col.metric(dim, f"{val:.2f}", delta=f"{delta:+.2f} vs {stim_type_2}", delta_color="normal")
+    else:
+        col.metric(dim, f"{val:.2f}")
 
 st.divider()
 
-# --- Timeline ---
+# --- Timeline with Confidence Bands ---
 st.subheader("Cognitive Load Timeline")
+
+if compare:
+    st.markdown(f"**Solid lines**: {stim_type} | **Dashed lines**: {stim_type_2}")
+
 timeline_df = pd.DataFrame(timeline)
+dim_colors = {"Visual Complexity": "#00D2FF", "Auditory Demand": "#FF6B6B", "Language Processing": "#A29BFE", "Executive Load": "#FFEAA7"}
 
 fig = go.Figure()
-colors = {"Visual Complexity": "#00D2FF", "Auditory Demand": "#FF6B6B", "Language Processing": "#A29BFE", "Executive Load": "#FFEAA7"}
-for dim, color in colors.items():
-    fig.add_trace(go.Scatter(
-        x=timeline_df["time"],
-        y=timeline_df[dim],
-        name=dim,
-        line=dict(color=color, width=2),
-        mode="lines",
-    ))
+for dim, color in dim_colors.items():
+    y = timeline_df[dim].values
+
+    # Bootstrap confidence band (resample vertices within dimension ROIs)
+    rng = np.random.default_rng(seed)
+    dim_rois = COGNITIVE_DIMENSIONS.get(dim, [])
+    dim_vertices = []
+    for roi in dim_rois:
+        if roi in roi_indices:
+            valid = roi_indices[roi]
+            dim_vertices.extend(valid[valid < predictions.shape[1]])
+
+    if dim_vertices:
+        boot_scores = []
+        for _ in range(50):
+            sample_verts = rng.choice(dim_vertices, size=max(1, len(dim_vertices) // 2), replace=True)
+            boot_tc = np.abs(predictions[:, sample_verts]).mean(axis=1)
+            baseline = max(np.median(np.abs(predictions)), 1e-8)
+            boot_scores.append(np.clip(boot_tc / baseline, 0, 1))
+        boot_arr = np.array(boot_scores)
+        ci_lo = np.percentile(boot_arr, 2.5, axis=0)
+        ci_hi = np.percentile(boot_arr, 97.5, axis=0)
+        t_axis = timeline_df["time"].values
+
+        fig.add_trace(go.Scatter(x=t_axis, y=ci_hi, mode="lines", line=dict(width=0), showlegend=False))
+        fig.add_trace(go.Scatter(x=t_axis, y=ci_lo, mode="lines", line=dict(width=0),
+                                 fill="tonexty", fillcolor=color.replace(")", ",0.15)").replace("rgb", "rgba").replace("#", "rgba(") if color.startswith("#") else color,
+                                 showlegend=False))
+
+    fig.add_trace(go.Scatter(x=timeline_df["time"], y=y, name=dim, line=dict(color=color, width=2)))
+
+    if compare:
+        timeline_df_2 = pd.DataFrame(timeline_2)
+        fig.add_trace(go.Scatter(x=timeline_df_2["time"], y=timeline_df_2[dim].values,
+                                 name=f"{dim} ({stim_type_2})", line=dict(color=color, width=1.5, dash="dash")))
 
 fig.update_layout(
-    xaxis_title="Time (seconds)",
-    yaxis_title="Cognitive Load (normalized)",
-    yaxis_range=[0, 1.05],
-    height=400,
-    template="plotly_dark",
+    xaxis_title="Time (seconds)", yaxis_title="Cognitive Load (normalized)",
+    yaxis_range=[0, 1.05], height=450, template="plotly_dark",
     legend=dict(orientation="h", yanchor="bottom", y=1.02),
 )
 st.plotly_chart(fig, use_container_width=True)
 
-# --- Dimension Breakdown ---
+# --- Dimension Correlation + Radar ---
 st.divider()
 col1, col2 = st.columns(2)
 
 with col1:
-    st.subheader("Dimension Breakdown")
-    dim_data = {k: v for k, v in averages.items() if k != "Overall"}
-    fig2 = go.Figure(go.Bar(
-        x=list(dim_data.values()),
-        y=list(dim_data.keys()),
-        orientation="h",
-        marker_color=list(colors.values()),
+    st.subheader("Dimension Correlation")
+    st.markdown("How do the four cognitive dimensions co-vary over time?")
+    dim_timeseries = {}
+    for dim in dim_colors:
+        dim_timeseries[dim] = timeline_df[dim].values
+    dim_arr = np.array(list(dim_timeseries.values()))
+    corr = np.corrcoef(dim_arr)
+    dim_names = list(dim_colors.keys())
+
+    fig_corr = go.Figure(go.Heatmap(
+        z=corr, x=dim_names, y=dim_names,
+        colorscale="RdBu_r", zmid=0, zmin=-1, zmax=1,
+        colorbar=dict(title="r"),
+        text=np.round(corr, 2), texttemplate="%{text}",
     ))
-    fig2.update_layout(
-        xaxis_title="Score",
-        xaxis_range=[0, 1],
-        height=300,
-        template="plotly_dark",
-    )
-    st.plotly_chart(fig2, use_container_width=True)
+    fig_corr.update_layout(height=350, template="plotly_dark", xaxis_tickangle=30)
+    st.plotly_chart(fig_corr, use_container_width=True)
 
 with col2:
-    st.subheader("Radar Chart")
+    st.subheader("Dimension Profile")
+    dim_data = {k: v for k, v in averages.items() if k != "Overall"}
     categories = list(dim_data.keys())
-    values = list(dim_data.values()) + [list(dim_data.values())[0]]  # close the polygon
-
-    fig3 = go.Figure(go.Scatterpolar(
-        r=values,
-        theta=categories + [categories[0]],
-        fill="toself",
-        fillcolor="rgba(108, 92, 231, 0.3)",
-        line=dict(color="#6C5CE7"),
+    values = list(dim_data.values()) + [list(dim_data.values())[0]]
+
+    fig_radar = go.Figure()
+    fig_radar.add_trace(go.Scatterpolar(
+        r=values, theta=categories + [categories[0]],
+        fill="toself", fillcolor="rgba(108, 92, 231, 0.3)",
+        line=dict(color="#6C5CE7"), name=stim_type,
     ))
-    fig3.update_layout(
+    if compare:
+        dim_data_2 = {k: v for k, v in averages_2.items() if k != "Overall"}
+        values_2 = list(dim_data_2.values()) + [list(dim_data_2.values())[0]]
+        fig_radar.add_trace(go.Scatterpolar(
+            r=values_2, theta=categories + [categories[0]],
+            fill="toself", fillcolor="rgba(255,107,107,0.2)",
+            line=dict(color="#FF6B6B", dash="dash"), name=stim_type_2,
+        ))
+
+    fig_radar.update_layout(
         polar=dict(radialaxis=dict(visible=True, range=[0, 1])),
-        height=350,
-        template="plotly_dark",
-        showlegend=False,
+        height=350, template="plotly_dark",
     )
-    st.plotly_chart(fig3, use_container_width=True)
+    st.plotly_chart(fig_radar, use_container_width=True)
+
+# --- Per-ROI Activation Breakdown ---
+st.divider()
+st.subheader("Per-ROI Activation Within Each Dimension")
+selected_dim = st.selectbox("Dimension", list(dim_colors.keys()))
+dim_rois = COGNITIVE_DIMENSIONS.get(selected_dim, [])
+
+roi_activations = []
+for roi in dim_rois:
+    if roi in roi_indices:
+        verts = roi_indices[roi]
+        valid = verts[verts < predictions.shape[1]]
+        if len(valid) > 0:
+            act = float(np.abs(predictions[:, valid]).mean())
+            roi_activations.append({"ROI": roi, "Mean Activation": act})
+
+if roi_activations:
+    roi_act_df = pd.DataFrame(roi_activations).sort_values("Mean Activation", ascending=False)
+    fig_roi = go.Figure(go.Bar(
+        x=roi_act_df["Mean Activation"], y=roi_act_df["ROI"],
+        orientation="h", marker_color=dim_colors[selected_dim],
+    ))
+    fig_roi.update_layout(height=max(250, len(roi_activations) * 25), template="plotly_dark",
+                          yaxis=dict(autorange="reversed"), xaxis_title="Mean |activation|")
+    st.plotly_chart(fig_roi, use_container_width=True)
+    download_csv_button(roi_act_df, f"cognitive_load_{selected_dim}_rois.csv")
+
+# --- Methodology ---
+with st.expander("Methodology", expanded=False):
+    st.markdown("""
+**Cognitive Load Scoring** maps predicted fMRI activations onto four neurocognitive dimensions
+using HCP MMP1.0 ROI groupings:
+
+- **Visual Complexity**: V1-V4, MT, MST, FFC, VVC (ventral & dorsal visual streams)
+- **Auditory Demand**: A1, belt areas, STS (auditory cortex + association areas)
+- **Language Processing**: Areas 44/45 (Broca's), TPOJ (Wernicke's), STV, PSL (perisylvian language network)
+- **Executive Load**: dlPFC (area 46), ACC, FEF (frontoparietal control network)
+
+Each dimension score is the mean absolute activation across its ROIs, normalized by the
+median activation across all vertices (baseline). Scores are clipped to [0, 1].
+
+**Confidence bands** on the timeline are computed via bootstrap resampling of vertices
+within each dimension's ROI group (50 resamples, 95% CI).
+
+**Limitations**: The ROI-to-dimension mapping is based on established functional neuroanatomy
+but is not exhaustive. Cognitive load is a multidimensional construct that cannot be fully
+captured by fMRI activation alone. These scores should be interpreted as relative measures,
+not absolute cognitive load values.
+
+**References**:
+- Glasser et al., 2016, *Nature* (HCP MMP1.0 parcellation)
+- Sweller, 1988, *Cognitive Science* (Cognitive Load Theory)
+""")

pages/3_Temporal_Dynamics.py

@@ -1,4 +1,4 @@
-"""Temporal Dynamics page."""
+"""Temporal Dynamics - Research Grade."""
 
 import streamlit as st
 import numpy as np
@@ -6,32 +6,39 @@ import pandas as pd
 import plotly.graph_objects as go
 from plotly.subplots import make_subplots
 
-from utils import (
-    make_roi_indices,
-    generate_brain_predictions,
-    generate_model_features,
-    peak_latency,
-    temporal_correlation,
-    decompose_response,
-    ROI_GROUPS,
-    ALL_ROIS,
-)
+from session import init_session, log_analysis, get_carried_rois, download_csv_button, show_analysis_log
+from utils import make_roi_indices, peak_latency, temporal_correlation, decompose_response, ROI_GROUPS, ALL_ROIS
+from synthetic import generate_realistic_predictions, generate_correlated_features
 
 st.set_page_config(page_title="Temporal Dynamics", page_icon="⏱️", layout="wide")
+init_session()
+show_analysis_log()
+
 st.title("⏱️ Temporal Dynamics")
-st.markdown("Analyze how brain responses evolve over time.")
+st.markdown("Analyze how brain responses evolve over time, including processing hierarchy and temporal coupling with model features.")
 
 # --- Sidebar ---
 with st.sidebar:
     st.header("Configuration")
+    stim_type = st.selectbox("Stimulus type", ["visual", "auditory", "language", "multimodal"],
+                             index=["visual", "auditory", "language", "multimodal"].index(st.session_state.get("stimulus_type", "visual")))
     n_timepoints = st.slider("Duration (TRs)", 30, 200, 80)
-    tr_seconds = st.slider("TR duration (seconds)", 0.5, 2.0, 1.0, 0.1)
-    seed = st.number_input("Random seed", value=42, min_value=0)
+    tr_seconds = st.slider("TR (seconds)", 0.5, 2.0, 1.0, 0.1)
+    seed = st.number_input("Seed", value=42, min_value=0)
 
     st.subheader("ROI Selection")
-    selected_group = st.selectbox("Region group", list(ROI_GROUPS.keys()))
-    available_rois = ROI_GROUPS[selected_group]
-    selected_rois = st.multiselect("ROIs to analyze", available_rois, default=available_rois[:3])
+    carried = get_carried_rois()
+    use_carried = False
+    if carried:
+        use_carried = st.checkbox(f"Use {len(carried)} ROIs from Brain Alignment", value=True)
+
+    if use_carried and carried:
+        selected_rois = carried
+        st.caption(f"Using: {', '.join(selected_rois[:5])}{'...' if len(selected_rois) > 5 else ''}")
+    else:
+        selected_group = st.selectbox("Region group", list(ROI_GROUPS.keys()))
+        available_rois = ROI_GROUPS[selected_group]
+        selected_rois = st.multiselect("ROIs to analyze", available_rois, default=available_rois[:4])
 
     max_lag = st.slider("Max correlation lag (TRs)", 5, 30, 15)
     cutoff = st.slider("Decomposition cutoff (seconds)", 1.0, 10.0, 4.0, 0.5)
@@ -42,78 +49,209 @@ if not selected_rois:
 
 # --- Generate Data ---
 roi_indices, n_vertices = make_roi_indices()
-predictions = generate_brain_predictions(n_timepoints, n_vertices, seed)
-features = generate_model_features(n_timepoints, 64, seed + 1)
+predictions = generate_realistic_predictions(n_timepoints, roi_indices, stim_type, tr_seconds, seed=seed)
+features = generate_correlated_features(predictions, alignment_strength=0.5, feature_dim=64, seed=seed + 1)
+log_analysis(f"Temporal dynamics: {stim_type}, {len(selected_rois)} ROIs")
+
+time_axis = np.arange(n_timepoints) * tr_seconds
+colors = ["#00D2FF", "#FF6B6B", "#A29BFE", "#FFEAA7", "#55EFC4", "#FD79A8", "#74B9FF", "#E17055"]
+
+# --- Raw ROI Timecourses ---
+st.subheader("Raw ROI Timecourses")
+st.markdown("Mean absolute activation over time for each selected ROI. Note the hemodynamic response shape after stimulus events.")
+
+fig_raw = go.Figure()
+for i, roi in enumerate(selected_rois):
+    if roi in roi_indices:
+        verts = roi_indices[roi]
+        valid = verts[verts < predictions.shape[1]]
+        if len(valid) > 0:
+            tc = np.abs(predictions[:, valid]).mean(axis=1)
+            fig_raw.add_trace(go.Scatter(
+                x=time_axis, y=tc, name=roi,
+                line=dict(color=colors[i % len(colors)], width=2),
+            ))
+
+fig_raw.update_layout(
+    xaxis_title="Time (seconds)", yaxis_title="Mean |activation|",
+    height=400, template="plotly_dark",
+    legend=dict(orientation="h", yanchor="bottom", y=1.02),
+)
+st.plotly_chart(fig_raw, use_container_width=True)
+
+# --- Peak Latency (sorted = processing hierarchy) ---
+st.divider()
+st.subheader("Peak Response Latency (Processing Hierarchy)")
+st.markdown("ROIs sorted by peak latency reveal the cortical processing hierarchy: early sensory areas respond first, association cortex later.")
 
-# --- Peak Latency ---
-st.subheader("Peak Response Latency")
 latency_data = []
 for roi in selected_rois:
-    lat = peak_latency(predictions, roi_indices, roi, tr_seconds)
-    latency_data.append({"ROI": roi, "Peak Latency (s)": lat})
+    if roi in roi_indices:
+        lat = peak_latency(predictions, roi_indices, roi, tr_seconds)
+        # Determine functional group
+        group = "Other"
+        for g, rois in ROI_GROUPS.items():
+            if roi in rois:
+                group = g
+                break
+        latency_data.append({"ROI": roi, "Peak Latency (s)": lat, "Group": group})
 
-lat_df = pd.DataFrame(latency_data)
-col1, col2 = st.columns([2, 1])
+lat_df = pd.DataFrame(latency_data).sort_values("Peak Latency (s)")
+group_colors = {"Visual": "#00D2FF", "Auditory": "#FF6B6B", "Language": "#A29BFE", "Executive": "#FFEAA7", "Other": "#888"}
 
+col1, col2 = st.columns([2, 1])
 with col1:
-    fig = go.Figure(go.Bar(
-        x=lat_df["ROI"],
-        y=lat_df["Peak Latency (s)"],
-        marker_color="#6C5CE7",
+    fig_lat = go.Figure(go.Bar(
+        x=lat_df["Peak Latency (s)"], y=lat_df["ROI"],
+        orientation="h",
+        marker_color=[group_colors.get(g, "#888") for g in lat_df["Group"]],
     ))
-    fig.update_layout(
-        yaxis_title="Time to peak (seconds)",
-        height=350,
-        template="plotly_dark",
+    fig_lat.update_layout(
+        xaxis_title="Time to peak (seconds)", height=max(250, len(selected_rois) * 30),
+        template="plotly_dark", yaxis=dict(autorange="reversed"),
     )
-    st.plotly_chart(fig, use_container_width=True)
+    st.plotly_chart(fig_lat, use_container_width=True)
 
 with col2:
-    st.dataframe(lat_df, use_container_width=True, hide_index=True)
+    st.dataframe(lat_df[["ROI", "Peak Latency (s)", "Group"]], use_container_width=True, hide_index=True)
+    download_csv_button(lat_df, "peak_latencies.csv")
 
-# --- Lag Correlation ---
+# --- Lag Correlation with Significance ---
 st.divider()
 st.subheader("Temporal Correlation (Brain vs Model Features)")
+st.markdown("Pearson correlation at different time lags. The peak indicates optimal temporal alignment. "
+            "Gray band shows 95% null range from shuffled data.")
 
 lags = np.arange(-max_lag, max_lag + 1) * tr_seconds
-fig2 = go.Figure()
-colors = ["#00D2FF", "#FF6B6B", "#A29BFE", "#FFEAA7", "#55EFC4", "#FD79A8"]
+fig_corr = go.Figure()
 
+# Null band (shuffle features, compute correlation envelope)
+rng = np.random.default_rng(seed)
+null_corrs = []
+for _ in range(50):
+    shuffled = features[rng.permutation(len(features))]
+    for roi in selected_rois[:1]:  # Use first ROI for null band
+        if roi in roi_indices:
+            nc = temporal_correlation(predictions, shuffled, roi_indices, roi, max_lag)
+            null_corrs.append(nc)
+if null_corrs:
+    null_arr = np.array(null_corrs)
+    null_hi = np.percentile(null_arr, 97.5, axis=0)
+    null_lo = np.percentile(null_arr, 2.5, axis=0)
+    fig_corr.add_trace(go.Scatter(x=lags, y=null_hi, mode="lines", line=dict(width=0), showlegend=False))
+    fig_corr.add_trace(go.Scatter(x=lags, y=null_lo, mode="lines", line=dict(width=0),
+                                   fill="tonexty", fillcolor="rgba(150,150,150,0.2)",
+                                   name="95% null range"))
+
+# Actual correlations
+optimal_lags = []
 for i, roi in enumerate(selected_rois):
-    corr = temporal_correlation(predictions, features, roi_indices, roi, max_lag)
-    fig2.add_trace(go.Scatter(
-        x=lags,
-        y=corr,
-        name=roi,
-        line=dict(color=colors[i % len(colors)], width=2),
-    ))
+    if roi in roi_indices:
+        corr = temporal_correlation(predictions, features, roi_indices, roi, max_lag)
+        fig_corr.add_trace(go.Scatter(
+            x=lags, y=corr, name=roi,
+            line=dict(color=colors[i % len(colors)], width=2),
+        ))
+        opt_idx = np.argmax(np.abs(corr))
+        optimal_lags.append({"ROI": roi, "Optimal Lag (s)": lags[opt_idx], "Max |r|": float(np.abs(corr[opt_idx]))})
 
-fig2.add_vline(x=0, line_dash="dash", line_color="gray", opacity=0.5)
-fig2.update_layout(
-    xaxis_title="Lag (seconds)",
-    yaxis_title="Pearson Correlation",
-    height=400,
-    template="plotly_dark",
+fig_corr.add_vline(x=0, line_dash="dash", line_color="gray", opacity=0.5)
+fig_corr.update_layout(
+    xaxis_title="Lag (seconds)", yaxis_title="Pearson Correlation",
+    height=400, template="plotly_dark",
     legend=dict(orientation="h", yanchor="bottom", y=1.02),
 )
-st.plotly_chart(fig2, use_container_width=True)
+st.plotly_chart(fig_corr, use_container_width=True)
+
+# --- Optimal Lag Summary ---
+if optimal_lags:
+    st.subheader("Optimal Lag Summary")
+    opt_df = pd.DataFrame(optimal_lags).sort_values("Max |r|", ascending=False)
+    st.dataframe(opt_df, use_container_width=True, hide_index=True)
+    download_csv_button(opt_df, "optimal_lags.csv")
+
+# --- Cross-ROI Lag Matrix ---
+if len(selected_rois) >= 2:
+    st.divider()
+    st.subheader("Cross-ROI Lag Matrix")
+    st.markdown("Optimal lag between each pair of ROIs. Positive values mean the row ROI leads the column ROI.")
+
+    n_rois = len(selected_rois)
+    lag_matrix = np.zeros((n_rois, n_rois))
+    for i, roi_a in enumerate(selected_rois):
+        if roi_a not in roi_indices:
+            continue
+        verts_a = roi_indices[roi_a]
+        valid_a = verts_a[verts_a < predictions.shape[1]]
+        if len(valid_a) == 0:
+            continue
+        tc_a = np.abs(predictions[:, valid_a]).mean(axis=1)
+        for j, roi_b in enumerate(selected_rois):
+            if i == j or roi_b not in roi_indices:
+                continue
+            verts_b = roi_indices[roi_b]
+            valid_b = verts_b[verts_b < predictions.shape[1]]
+            if len(valid_b) == 0:
+                continue
+            tc_b = np.abs(predictions[:, valid_b]).mean(axis=1)
+            # Cross-correlation to find optimal lag
+            corrs_ab = temporal_correlation(predictions, tc_b, roi_indices, roi_a, max_lag)
+            opt_idx = np.argmax(np.abs(corrs_ab))
+            lag_matrix[i, j] = lags[opt_idx]
+
+    fig_lagmat = go.Figure(go.Heatmap(
+        z=lag_matrix, x=selected_rois, y=selected_rois,
+        colorscale="RdBu_r", zmid=0,
+        colorbar=dict(title="Lag (s)"),
+        text=np.round(lag_matrix, 1), texttemplate="%{text}",
+    ))
+    fig_lagmat.update_layout(height=400, template="plotly_dark")
+    st.plotly_chart(fig_lagmat, use_container_width=True)
 
 # --- Sustained vs Transient ---
 st.divider()
 st.subheader("Sustained vs Transient Decomposition")
+st.markdown("Moving-average filter separates slow sustained responses from fast transient spikes.")
 
 roi_for_decomp = st.selectbox("ROI for decomposition", selected_rois)
 sustained, transient = decompose_response(predictions, roi_indices, roi_for_decomp, cutoff, tr_seconds)
-time_axis = np.arange(len(sustained)) * tr_seconds
+original = sustained + transient
+
+fig_decomp = make_subplots(rows=3, cols=1, shared_xaxes=True, vertical_spacing=0.06,
+                           subplot_titles=("Original Signal", "Sustained Component", "Transient Component"))
+
+fig_decomp.add_trace(go.Scatter(x=time_axis, y=original, line=dict(color="#888", width=1.5)), row=1, col=1)
+fig_decomp.add_trace(go.Scatter(x=time_axis, y=sustained, line=dict(color="#6C5CE7", width=2)), row=2, col=1)
+fig_decomp.add_trace(go.Scatter(x=time_axis, y=transient, line=dict(color="#FF6B6B", width=1.5)), row=3, col=1)
+
+fig_decomp.update_xaxes(title_text="Time (seconds)", row=3, col=1)
+fig_decomp.update_layout(height=550, template="plotly_dark", showlegend=False)
+st.plotly_chart(fig_decomp, use_container_width=True)
+
+# --- Methodology ---
+with st.expander("Methodology", expanded=False):
+    st.markdown("""
+**Peak Latency** is the time at which mean absolute activation reaches its maximum
+within an ROI. In real fMRI, early sensory cortex (V1, A1) peaks at ~5-6s post-stimulus
+due to the hemodynamic response, while association cortex (dlPFC, angular gyrus) peaks
+~1-3s later reflecting higher-order processing.
+
+**Temporal Correlation** computes Pearson correlation between the ROI timecourse and model
+feature timecourse at each lag in ``[-max_lag, +max_lag]`` TRs. The lag at maximum absolute
+correlation reveals the temporal offset at which model and brain are best aligned.
+
+**Null significance band** is estimated by shuffling the model features 50 times and
+computing the lag correlation each time. The 95% envelope of these null correlations
+provides a significance threshold.
 
-fig3 = make_subplots(rows=2, cols=1, shared_xaxes=True, vertical_spacing=0.08,
-                     subplot_titles=("Sustained Component", "Transient Component"))
+**Sustained vs Transient Decomposition** uses a moving-average filter with the specified
+cutoff period. The sustained component captures slow, maintained responses (e.g., block
+design activations), while the transient component captures fast, event-related responses.
 
-fig3.add_trace(go.Scatter(x=time_axis, y=sustained, name="Sustained",
-                          line=dict(color="#6C5CE7", width=2)), row=1, col=1)
-fig3.add_trace(go.Scatter(x=time_axis, y=transient, name="Transient",
-                          line=dict(color="#FF6B6B", width=1.5)), row=2, col=1)
+**Cross-ROI Lag Matrix** shows the optimal temporal offset between every pair of ROIs,
+revealing directional information flow (positive lag = row ROI leads column ROI).
 
-fig3.update_xaxes(title_text="Time (seconds)", row=2, col=1)
-fig3.update_layout(height=500, template="plotly_dark", showlegend=False)
-st.plotly_chart(fig3, use_container_width=True)
+**References**:
+- Boynton et al., 1996, *J Neuroscience* (hemodynamic response function)
+- Friston et al., 1998, *NeuroImage* (temporal basis functions in fMRI)
+""")

pages/4_Connectivity.py

@@ -1,4 +1,4 @@
-"""ROI Connectivity page."""
+"""ROI Connectivity - Research Grade."""
 
 import streamlit as st
 import numpy as np
@@ -6,157 +6,278 @@ import pandas as pd
 import plotly.graph_objects as go
 import plotly.express as px
 
+from session import init_session, log_analysis, get_carried_rois, download_csv_button, show_analysis_log
 from utils import (
-    make_roi_indices,
-    generate_brain_predictions,
-    compute_connectivity,
-    cluster_rois,
-    graph_metrics,
+    make_roi_indices, compute_connectivity, cluster_rois, graph_metrics,
+    partial_correlation, betweenness_centrality, modularity_score,
     ROI_GROUPS,
 )
+from synthetic import generate_realistic_predictions
 
 st.set_page_config(page_title="ROI Connectivity", page_icon="🔗", layout="wide")
+init_session()
+show_analysis_log()
+
 st.title("🔗 ROI Connectivity Analysis")
-st.markdown("Functional connectivity between brain regions from predicted responses.")
+st.markdown("Functional connectivity between brain regions: correlation structure, network organization, and graph topology.")
 
 # --- Sidebar ---
 with st.sidebar:
     st.header("Configuration")
+    stim_type = st.selectbox("Stimulus type", ["visual", "auditory", "language", "multimodal"])
     n_timepoints = st.slider("Duration (TRs)", 30, 200, 80)
-    seed = st.number_input("Random seed", value=42, min_value=0)
+    tr_seconds = st.slider("TR (seconds)", 0.5, 2.0, 1.0, 0.1)
+    seed = st.number_input("Seed", value=42, min_value=0)
+
+    st.subheader("Analysis Parameters")
     n_clusters = st.slider("Number of clusters", 2, 8, 4)
     threshold = st.slider("Edge threshold", 0.1, 0.8, 0.3, 0.05)
+    use_partial = st.checkbox("Use partial correlation", value=False,
+                              help="Control for shared mean signal across all ROIs")
+
+    carried = get_carried_rois()
+    use_carried = False
+    if carried:
+        use_carried = st.checkbox(f"Filter to {len(carried)} carried ROIs", value=False)
 
 # --- Generate Data ---
 roi_indices, n_vertices = make_roi_indices()
-predictions = generate_brain_predictions(n_timepoints, n_vertices, seed)
-
-# --- Correlation Matrix ---
-corr_matrix, roi_names = compute_connectivity(predictions, roi_indices)
-
-st.subheader("Correlation Matrix")
-fig = go.Figure(go.Heatmap(
-    z=corr_matrix,
-    x=roi_names,
-    y=roi_names,
-    colorscale="RdBu_r",
-    zmid=0,
-    zmin=-1,
-    zmax=1,
-    colorbar=dict(title="Correlation"),
+predictions = generate_realistic_predictions(n_timepoints, roi_indices, stim_type, tr_seconds, seed=seed)
+log_analysis(f"Connectivity: {stim_type}, partial={use_partial}")
+
+# Filter ROIs if carrying from alignment
+active_indices = roi_indices
+if use_carried and carried:
+    active_indices = {k: v for k, v in roi_indices.items() if k in carried}
+
+# --- Compute Connectivity ---
+if use_partial:
+    corr_matrix, roi_names = partial_correlation(predictions, active_indices)
+    corr_label = "Partial Correlation"
+else:
+    corr_matrix, roi_names = compute_connectivity(predictions, active_indices)
+    corr_label = "Pearson Correlation"
+
+n_rois = len(roi_names)
+
+# --- Correlation Matrix with Cluster Boundaries ---
+st.subheader(f"{corr_label} Matrix")
+
+clusters, labels = cluster_rois(corr_matrix, roi_names, n_clusters)
+
+# Sort ROIs by cluster for block-diagonal structure
+sorted_idx = np.argsort(labels)
+sorted_corr = corr_matrix[np.ix_(sorted_idx, sorted_idx)]
+sorted_names = [roi_names[i] for i in sorted_idx]
+sorted_labels = labels[sorted_idx]
+
+fig_corr = go.Figure(go.Heatmap(
+    z=sorted_corr, x=sorted_names, y=sorted_names,
+    colorscale="RdBu_r", zmid=0, zmin=-1, zmax=1,
+    colorbar=dict(title="r"),
 ))
-fig.update_layout(
-    height=600,
-    width=700,
-    template="plotly_dark",
+
+# Add cluster boundary lines
+boundaries = []
+for i in range(1, len(sorted_labels)):
+    if sorted_labels[i] != sorted_labels[i - 1]:
+        boundaries.append(i - 0.5)
+
+for b in boundaries:
+    fig_corr.add_shape(type="line", x0=b, x1=b, y0=-0.5, y1=n_rois - 0.5,
+                       line=dict(color="white", width=1.5, dash="dot"))
+    fig_corr.add_shape(type="line", x0=-0.5, x1=n_rois - 0.5, y0=b, y1=b,
+                       line=dict(color="white", width=1.5, dash="dot"))
+
+fig_corr.update_layout(
+    height=550, template="plotly_dark",
     xaxis=dict(tickangle=45, tickfont=dict(size=8)),
     yaxis=dict(tickfont=dict(size=8)),
 )
-st.plotly_chart(fig, use_container_width=True)
+st.plotly_chart(fig_corr, use_container_width=True)
+st.caption(f"White dotted lines indicate cluster boundaries ({n_clusters} clusters)")
 
-# --- Network Clusters ---
+# --- Dendrogram ---
 st.divider()
-col1, col2 = st.columns(2)
+col_dendro, col_clusters = st.columns([1, 1])
+
+with col_dendro:
+    st.subheader("Hierarchical Clustering Dendrogram")
+    from scipy.cluster.hierarchy import linkage, dendrogram
+    import matplotlib.pyplot as plt
+    import matplotlib
+    matplotlib.use("Agg")
 
-with col1:
-    st.subheader("Functional Network Clusters")
-    clusters, labels = cluster_rois(corr_matrix, roi_names, n_clusters)
+    dist = 1.0 - np.abs(corr_matrix)
+    np.fill_diagonal(dist, 0.0)
+    condensed = [dist[i, j] for i in range(n_rois) for j in range(i + 1, n_rois)]
+    Z = linkage(condensed, method="average")
 
-    cluster_data = []
-    for cid, rois in sorted(clusters.items()):
+    fig_dendro, ax = plt.subplots(figsize=(8, 4))
+    ax.set_facecolor("#0E1117")
+    fig_dendro.patch.set_facecolor("#0E1117")
+    dendrogram(Z, labels=roi_names, leaf_rotation=90, leaf_font_size=7, ax=ax,
+               color_threshold=Z[-n_clusters + 1, 2] if n_clusters < n_rois else 0)
+    ax.tick_params(colors="white")
+    ax.set_ylabel("Distance (1 - |r|)", color="white")
+    for spine in ax.spines.values():
+        spine.set_color("white")
+    st.pyplot(fig_dendro)
+    plt.close()
+
+with col_clusters:
+    st.subheader("Network Clusters")
+    mod_q = modularity_score(corr_matrix, labels)
+    st.metric("Modularity (Q)", f"{mod_q:.3f}",
+              help="Newman's modularity. Higher = stronger community structure. Q > 0.3 is typically considered meaningful.")
+
+    for cid in sorted(clusters.keys()):
+        rois = clusters[cid]
+        # Identify dominant functional group
+        group_counts = {}
         for roi in rois:
-            cluster_data.append({"Cluster": f"Network {cid}", "ROI": roi})
-
-    cluster_df = pd.DataFrame(cluster_data)
-    fig2 = px.bar(
-        cluster_df.groupby("Cluster").size().reset_index(name="Count"),
-        x="Cluster",
-        y="Count",
-        color="Cluster",
-        color_discrete_sequence=px.colors.qualitative.Set2,
-    )
-    fig2.update_layout(height=350, template="plotly_dark", showlegend=False)
-    st.plotly_chart(fig2, use_container_width=True)
-
-    for cid, rois in sorted(clusters.items()):
-        st.markdown(f"**Network {cid}:** {', '.join(rois)}")
-
-with col2:
-    st.subheader("Degree Centrality")
-    degrees = graph_metrics(corr_matrix, roi_names, threshold)
-
-    # Sort by degree
-    sorted_degrees = sorted(degrees.items(), key=lambda x: x[1], reverse=True)
-    deg_df = pd.DataFrame(sorted_degrees, columns=["ROI", "Degree Centrality"])
-
-    fig3 = go.Figure(go.Bar(
-        x=deg_df["Degree Centrality"],
-        y=deg_df["ROI"],
-        orientation="h",
-        marker_color="#6C5CE7",
-    ))
-    fig3.update_layout(
-        xaxis_title="Degree Centrality",
-        xaxis_range=[0, 1],
-        height=600,
-        template="plotly_dark",
-        yaxis=dict(autorange="reversed", tickfont=dict(size=9)),
-    )
-    st.plotly_chart(fig3, use_container_width=True)
+            for g, g_rois in ROI_GROUPS.items():
+                if roi in g_rois:
+                    group_counts[g] = group_counts.get(g, 0) + 1
+        dominant = max(group_counts, key=group_counts.get) if group_counts else "Mixed"
+        st.markdown(f"**Network {cid}** ({dominant}): {', '.join(rois)}")
 
-# --- Network Graph ---
+# --- Centrality Comparison ---
+st.divider()
+st.subheader("Centrality Analysis")
+
+col_deg, col_btw = st.columns(2)
+
+degrees = graph_metrics(corr_matrix, roi_names, threshold)
+btw = betweenness_centrality(corr_matrix, roi_names, threshold)
+
+with col_deg:
+    st.markdown("**Degree Centrality** - fraction of ROIs connected to each node")
+    deg_df = pd.DataFrame(sorted(degrees.items(), key=lambda x: x[1], reverse=True), columns=["ROI", "Degree"])
+    fig_deg = go.Figure(go.Bar(x=deg_df["Degree"], y=deg_df["ROI"], orientation="h", marker_color="#6C5CE7"))
+    fig_deg.update_layout(xaxis_range=[0, 1], height=max(300, n_rois * 20), template="plotly_dark",
+                          yaxis=dict(autorange="reversed", tickfont=dict(size=9)))
+    st.plotly_chart(fig_deg, use_container_width=True)
+
+with col_btw:
+    st.markdown("**Betweenness Centrality** - how often a node lies on shortest paths between others")
+    btw_df = pd.DataFrame(sorted(btw.items(), key=lambda x: x[1], reverse=True), columns=["ROI", "Betweenness"])
+    fig_btw = go.Figure(go.Bar(x=btw_df["Betweenness"], y=btw_df["ROI"], orientation="h", marker_color="#FF6B6B"))
+    fig_btw.update_layout(height=max(300, n_rois * 20), template="plotly_dark",
+                          yaxis=dict(autorange="reversed", tickfont=dict(size=9)))
+    st.plotly_chart(fig_btw, use_container_width=True)
+
+# Combined table
+centrality_df = pd.merge(deg_df, btw_df, on="ROI")
+download_csv_button(centrality_df, "centrality_metrics.csv")
+
+# --- Edge Weight Distribution ---
 st.divider()
-st.subheader("Network Graph")
-
-try:
-    import networkx as nx
-
-    G = nx.Graph()
-    for name in roi_names:
-        G.add_node(name)
-
-    for i in range(len(roi_names)):
-        for j in range(i + 1, len(roi_names)):
-            if abs(corr_matrix[i, j]) > threshold:
-                G.add_edge(roi_names[i], roi_names[j], weight=abs(corr_matrix[i, j]))
-
-    pos = nx.spring_layout(G, seed=seed, k=2.0)
-
-    # Cluster colors
-    color_map = px.colors.qualitative.Set2
-    node_colors = [color_map[(labels[i] - 1) % len(color_map)] for i in range(len(roi_names))]
-
-    edge_x, edge_y = [], []
-    for u, v in G.edges():
-        x0, y0 = pos[u]
-        x1, y1 = pos[v]
-        edge_x.extend([x0, x1, None])
-        edge_y.extend([y0, y1, None])
-
-    node_x = [pos[n][0] for n in roi_names]
-    node_y = [pos[n][1] for n in roi_names]
-
-    fig4 = go.Figure()
-    fig4.add_trace(go.Scatter(
-        x=edge_x, y=edge_y, mode="lines",
-        line=dict(width=0.5, color="rgba(150,150,150,0.3)"),
-        hoverinfo="none",
-    ))
-    fig4.add_trace(go.Scatter(
-        x=node_x, y=node_y, mode="markers+text",
-        marker=dict(size=12, color=node_colors, line=dict(width=1, color="white")),
-        text=roi_names,
-        textposition="top center",
-        textfont=dict(size=8),
-        hoverinfo="text",
-    ))
-    fig4.update_layout(
-        height=500,
-        template="plotly_dark",
-        showlegend=False,
-        xaxis=dict(showgrid=False, zeroline=False, showticklabels=False),
-        yaxis=dict(showgrid=False, zeroline=False, showticklabels=False),
+col_dist, col_graph = st.columns([1, 2])
+
+with col_dist:
+    st.subheader("Edge Weight Distribution")
+    upper_tri = corr_matrix[np.triu_indices(n_rois, k=1)]
+    fig_hist = go.Figure(go.Histogram(x=upper_tri, nbinsx=40, marker_color="rgba(108,92,231,0.7)"))
+    fig_hist.add_vline(x=threshold, line_color="red", line_dash="dash", annotation_text="Threshold")
+    fig_hist.add_vline(x=-threshold, line_color="red", line_dash="dash")
+    fig_hist.update_layout(
+        xaxis_title="Correlation", yaxis_title="Count",
+        height=350, template="plotly_dark",
     )
-    st.plotly_chart(fig4, use_container_width=True)
-except ImportError:
-    st.info("Install `networkx` for the network graph visualization: `pip install networkx`")
+    st.plotly_chart(fig_hist, use_container_width=True)
+    n_edges = np.sum(np.abs(upper_tri) > threshold)
+    max_edges = n_rois * (n_rois - 1) // 2
+    st.caption(f"{n_edges}/{max_edges} edges above threshold ({100 * n_edges / max(max_edges, 1):.1f}% density)")
+
+# --- Network Graph ---
+with col_graph:
+    st.subheader("Network Graph")
+    try:
+        import networkx as nx
+
+        G = nx.Graph()
+        for name in roi_names:
+            G.add_node(name)
+        for i in range(n_rois):
+            for j in range(i + 1, n_rois):
+                w = abs(corr_matrix[i, j])
+                if w > threshold:
+                    G.add_edge(roi_names[i], roi_names[j], weight=w)
+
+        pos = nx.spring_layout(G, seed=seed, k=2.5)
+        color_map = px.colors.qualitative.Set2
+        node_colors = [color_map[(labels[i] - 1) % len(color_map)] for i in range(n_rois)]
+
+        # Edges with width proportional to weight
+        for u, v, data in G.edges(data=True):
+            x0, y0 = pos[u]
+            x1, y1 = pos[v]
+            fig_graph = go.Figure() if not hasattr(st, '_graph_fig') else st._graph_fig
+
+        fig_net = go.Figure()
+        for u, v, d in G.edges(data=True):
+            x0, y0 = pos[u]
+            x1, y1 = pos[v]
+            w = d.get("weight", 0.3)
+            fig_net.add_trace(go.Scatter(
+                x=[x0, x1, None], y=[y0, y1, None], mode="lines",
+                line=dict(width=w * 3, color=f"rgba(150,150,150,{min(w, 0.8)})"),
+                hoverinfo="none", showlegend=False,
+            ))
+
+        # Node sizes by degree
+        max_deg = max(degrees.values()) if degrees else 1
+        node_sizes = [8 + 20 * degrees.get(name, 0) / max(max_deg, 0.01) for name in roi_names]
+        node_x = [pos[n][0] for n in roi_names]
+        node_y = [pos[n][1] for n in roi_names]
+
+        fig_net.add_trace(go.Scatter(
+            x=node_x, y=node_y, mode="markers+text",
+            marker=dict(size=node_sizes, color=node_colors, line=dict(width=1, color="white")),
+            text=roi_names, textposition="top center", textfont=dict(size=7, color="white"),
+            hovertext=[f"{name}<br>Degree: {degrees.get(name, 0):.2f}<br>Betweenness: {btw.get(name, 0):.3f}" for name in roi_names],
+            hoverinfo="text", showlegend=False,
+        ))
+
+        fig_net.update_layout(
+            height=450, template="plotly_dark",
+            xaxis=dict(showgrid=False, zeroline=False, showticklabels=False),
+            yaxis=dict(showgrid=False, zeroline=False, showticklabels=False),
+        )
+        st.plotly_chart(fig_net, use_container_width=True)
+    except ImportError:
+        st.info("Install `networkx` for graph visualization: `pip install networkx`")
+
+# --- Methodology ---
+with st.expander("Methodology", expanded=False):
+    st.markdown("""
+**Functional Connectivity** is computed as pairwise Pearson correlation between ROI
+timecourses (mean activation across vertices within each ROI).
+
+**Partial Correlation** controls for the shared mean signal by computing the precision
+matrix (inverse covariance) and normalizing. This removes indirect correlations mediated
+by a common driver.
+
+**Hierarchical Clustering** uses agglomerative clustering with average linkage on a
+distance matrix defined as ``1 - |correlation|``. The dendrogram shows the hierarchical
+merging of ROIs into networks.
+
+**Modularity (Q)** quantifies how strongly the network divides into communities compared
+to a random network with the same degree distribution. Q > 0.3 typically indicates
+meaningful community structure. (Newman, 2006, *PNAS*)
+
+**Degree Centrality** is the fraction of other nodes each node is connected to (above
+the correlation threshold). High degree = hub region.
+
+**Betweenness Centrality** counts how often a node lies on the shortest path between
+other node pairs. High betweenness = bridge between communities.
+
+**Edge Weight Distribution** shows the histogram of all pairwise correlations. The
+threshold (red line) determines which connections are retained for graph analysis.
+
+**References**:
+- Rubinov & Sporns, 2010, *NeuroImage* (graph metrics for brain networks)
+- Newman, 2006, *PNAS* (modularity in networks)
+- Smith et al., 2011, *NeuroImage* (partial correlation for fMRI connectivity)
+""")

session.py

@@ -0,0 +1,134 @@
+"""Shared session state management and data I/O utilities.
+
+Manages cross-page state (selected ROIs, predictions, analysis log)
+and provides upload/download widgets.
+"""
+
+import io
+import json
+from datetime import datetime
+
+import numpy as np
+import pandas as pd
+import streamlit as st
+
+
+def init_session():
+    """Initialize session state with defaults. Safe to call multiple times."""
+    defaults = {
+        "brain_predictions": None,
+        "model_features": {},
+        "roi_indices": None,
+        "n_vertices": 0,
+        "selected_rois": [],
+        "data_source": "synthetic",
+        "stimulus_type": "visual",
+        "tr_seconds": 1.0,
+        "n_timepoints": 80,
+        "seed": 42,
+        "analysis_log": [],
+        "carry_rois": [],  # ROIs carried from another page
+    }
+    for key, value in defaults.items():
+        if key not in st.session_state:
+            st.session_state[key] = value
+
+
+def log_analysis(description):
+    """Append an entry to the analysis log."""
+    timestamp = datetime.now().strftime("%H:%M:%S")
+    entry = f"[{timestamp}] {description}"
+    if "analysis_log" not in st.session_state:
+        st.session_state["analysis_log"] = []
+    st.session_state["analysis_log"].append(entry)
+
+
+def carry_rois(rois, target_page=""):
+    """Store selected ROIs for cross-page workflow."""
+    st.session_state["carry_rois"] = list(rois)
+    log_analysis(f"Carried {len(rois)} ROIs to {target_page}")
+
+
+def get_carried_rois():
+    """Retrieve ROIs carried from another page."""
+    return st.session_state.get("carry_rois", [])
+
+
+def get_or_generate_data(roi_indices):
+    """Get brain predictions from session or generate new synthetic data."""
+    from synthetic import generate_realistic_predictions
+
+    params_key = (
+        st.session_state.get("n_timepoints", 80),
+        st.session_state.get("stimulus_type", "visual"),
+        st.session_state.get("seed", 42),
+    )
+
+    # Check if we need to regenerate
+    if (
+        st.session_state.get("brain_predictions") is None
+        or st.session_state.get("_data_params") != params_key
+        or st.session_state.get("data_source") == "synthetic"
+    ):
+        if st.session_state.get("data_source") == "uploaded" and st.session_state.get("brain_predictions") is not None:
+            return st.session_state["brain_predictions"]
+
+        predictions = generate_realistic_predictions(
+            n_timepoints=st.session_state["n_timepoints"],
+            roi_indices=roi_indices,
+            stimulus_type=st.session_state["stimulus_type"],
+            tr_seconds=st.session_state["tr_seconds"],
+            seed=st.session_state["seed"],
+        )
+        st.session_state["brain_predictions"] = predictions
+        st.session_state["_data_params"] = params_key
+
+    return st.session_state["brain_predictions"]
+
+
+def upload_npy_widget(label, key):
+    """File uploader for .npy arrays with validation."""
+    uploaded = st.file_uploader(label, type=["npy"], key=key)
+    if uploaded is not None:
+        try:
+            data = np.load(io.BytesIO(uploaded.read()))
+            st.success(f"Loaded: shape {data.shape}, dtype {data.dtype}")
+            return data
+        except Exception as e:
+            st.error(f"Failed to load file: {e}")
+    return None
+
+
+def download_csv_button(df, filename, label="Download CSV"):
+    """Download button for a pandas DataFrame as CSV."""
+    csv = df.to_csv(index=False)
+    st.download_button(label, csv, filename, "text/csv")
+
+
+def download_json_button(data, filename, label="Download JSON"):
+    """Download button for a dict as JSON."""
+    json_str = json.dumps(data, indent=2, default=str)
+    st.download_button(label, json_str, filename, "application/json")
+
+
+def show_analysis_log():
+    """Display the analysis log in the sidebar."""
+    log = st.session_state.get("analysis_log", [])
+    if log:
+        with st.sidebar:
+            with st.expander("Analysis Log", expanded=False):
+                for entry in reversed(log[-20:]):
+                    st.caption(entry)
+
+
+def data_summary_widget(predictions, roi_indices):
+    """Show a summary of the current data."""
+    if predictions is None:
+        st.info("No data loaded. Generate synthetic data or upload your own.")
+        return
+
+    col1, col2, col3, col4 = st.columns(4)
+    col1.metric("Timepoints", predictions.shape[0])
+    col2.metric("Vertices", predictions.shape[1])
+    col3.metric("ROIs", len(roi_indices))
+    col4.metric("Source", st.session_state.get("data_source", "synthetic").title())

synthetic.py

@@ -0,0 +1,230 @@
+"""Biologically realistic synthetic fMRI data generation.
+
+Generates data with hemodynamic response convolution, modality-specific
+activation patterns, spatial autocorrelation, temporal noise structure,
+and scanner drift - mimicking real fMRI recordings.
+"""
+
+import numpy as np
+
+# --- Hemodynamic Response Function ---
+
+def generate_hrf(tr_seconds=1.0, duration=30.0):
+    """Canonical double-gamma hemodynamic response function.
+
+    Models the BOLD signal: a positive peak at ~5-6s followed by a
+    smaller negative undershoot at ~15s.
+    """
+    t = np.arange(0, duration, tr_seconds)
+    # Double gamma parameters (SPM canonical)
+    a1, b1 = 6.0, 1.0   # positive peak
+    a2, b2 = 16.0, 1.0   # undershoot
+    c = 1.0 / 6.0        # undershoot ratio
+
+    from scipy.stats import gamma as gamma_dist
+    h = gamma_dist.pdf(t, a1, scale=b1) - c * gamma_dist.pdf(t, a2, scale=b2)
+    h = h / np.max(np.abs(h))  # normalize to [-1, 1]
+    return h
+
+
+def generate_stimulus_events(n_timepoints, tr_seconds=1.0, n_events=5, seed=42):
+    """Generate random stimulus onset times as a binary event train.
+
+    Returns a (n_timepoints,) array with 1s at stimulus onsets.
+    Events are spaced at least 8 seconds apart.
+    """
+    rng = np.random.default_rng(seed)
+    total_seconds = n_timepoints * tr_seconds
+    min_gap = 8.0  # minimum inter-stimulus interval
+
+    events = np.zeros(n_timepoints)
+    onsets = []
+    attempts = 0
+    while len(onsets) < n_events and attempts < 1000:
+        t = rng.uniform(2.0, total_seconds - 10.0)
+        if all(abs(t - o) > min_gap for o in onsets):
+            onsets.append(t)
+        attempts += 1
+
+    for onset in onsets:
+        idx = int(onset / tr_seconds)
+        if 0 <= idx < n_timepoints:
+            events[idx] = 1.0
+
+    return events
+
+
+# --- Modality-Specific Activation Weights ---
+
+# Weight for each ROI given a stimulus modality (0 = no response, 1 = maximum)
+MODALITY_WEIGHTS = {
+    "visual": {
+        # Strong visual cortex activation
+        "V1": 1.0, "V2": 0.95, "V3": 0.85, "V4": 0.8,
+        "MT": 0.75, "MST": 0.7, "FFC": 0.65, "VVC": 0.6,
+        # Weak cross-modal
+        "A1": 0.05, "LBelt": 0.04, "MBelt": 0.03, "PBelt": 0.03, "A4": 0.02, "A5": 0.02,
+        # Minimal language
+        "44": 0.08, "45": 0.07, "IFJa": 0.06, "IFJp": 0.05,
+        "TPOJ1": 0.1, "TPOJ2": 0.08, "STV": 0.07, "PSL": 0.06,
+        # Moderate executive (attention)
+        "46": 0.3, "9-46d": 0.25, "8Av": 0.35, "8Ad": 0.3,
+        "FEF": 0.4, "p32pr": 0.15, "a32pr": 0.12,
+    },
+    "auditory": {
+        "V1": 0.03, "V2": 0.03, "V3": 0.02, "V4": 0.02,
+        "MT": 0.02, "MST": 0.01, "FFC": 0.01, "VVC": 0.01,
+        "A1": 1.0, "LBelt": 0.95, "MBelt": 0.9, "PBelt": 0.85, "A4": 0.75, "A5": 0.7,
+        "44": 0.15, "45": 0.12, "IFJa": 0.1, "IFJp": 0.08,
+        "TPOJ1": 0.25, "TPOJ2": 0.2, "STV": 0.3, "PSL": 0.2,
+        "46": 0.2, "9-46d": 0.15, "8Av": 0.12, "8Ad": 0.1,
+        "FEF": 0.08, "p32pr": 0.1, "a32pr": 0.08,
+    },
+    "language": {
+        "V1": 0.05, "V2": 0.04, "V3": 0.03, "V4": 0.03,
+        "MT": 0.02, "MST": 0.02, "FFC": 0.1, "VVC": 0.08,
+        "A1": 0.3, "LBelt": 0.25, "MBelt": 0.2, "PBelt": 0.15, "A4": 0.2, "A5": 0.15,
+        "44": 1.0, "45": 0.95, "IFJa": 0.85, "IFJp": 0.8,
+        "TPOJ1": 0.9, "TPOJ2": 0.85, "STV": 0.75, "PSL": 0.7,
+        "46": 0.5, "9-46d": 0.45, "8Av": 0.3, "8Ad": 0.25,
+        "FEF": 0.15, "p32pr": 0.35, "a32pr": 0.3,
+    },
+    "multimodal": {
+        "V1": 0.7, "V2": 0.65, "V3": 0.55, "V4": 0.5,
+        "MT": 0.5, "MST": 0.45, "FFC": 0.4, "VVC": 0.35,
+        "A1": 0.7, "LBelt": 0.65, "MBelt": 0.55, "PBelt": 0.5, "A4": 0.45, "A5": 0.4,
+        "44": 0.65, "45": 0.6, "IFJa": 0.5, "IFJp": 0.45,
+        "TPOJ1": 0.6, "TPOJ2": 0.55, "STV": 0.5, "PSL": 0.45,
+        "46": 0.4, "9-46d": 0.35, "8Av": 0.3, "8Ad": 0.25,
+        "FEF": 0.3, "p32pr": 0.25, "a32pr": 0.2,
+    },
+}
+
+
+def generate_realistic_predictions(
+    n_timepoints,
+    roi_indices,
+    stimulus_type="visual",
+    tr_seconds=1.0,
+    n_events=5,
+    snr=2.0,
+    seed=42,
+):
+    """Generate biologically realistic fMRI-like predictions.
+
+    Parameters
+    ----------
+    n_timepoints : int
+        Number of TRs.
+    roi_indices : dict[str, np.ndarray]
+        ROI name -> vertex indices mapping.
+    stimulus_type : str
+        One of "visual", "auditory", "language", "multimodal".
+    tr_seconds : float
+        Repetition time in seconds.
+    n_events : int
+        Number of stimulus events.
+    snr : float
+        Signal-to-noise ratio (higher = cleaner signal).
+    seed : int
+        Random seed.
+    """
+    rng = np.random.default_rng(seed)
+    n_vertices = max(max(v) for v in roi_indices.values()) + 1
+    predictions = np.zeros((n_timepoints, n_vertices))
+
+    # 1. Generate stimulus-evoked signal
+    events = generate_stimulus_events(n_timepoints, tr_seconds, n_events, seed)
+    hrf = generate_hrf(tr_seconds)
+
+    # Convolve events with HRF
+    bold_signal = np.convolve(events, hrf)[:n_timepoints]
+
+    # 2. Apply modality-specific weights per ROI
+    weights = MODALITY_WEIGHTS.get(stimulus_type, MODALITY_WEIGHTS["multimodal"])
+    for roi_name, vertices in roi_indices.items():
+        w = weights.get(roi_name, 0.1)
+        # Add per-ROI latency jitter (higher-order areas respond later)
+        latency_shift = 0
+        if roi_name in ["44", "45", "IFJa", "IFJp", "46", "9-46d"]:
+            latency_shift = int(2.0 / tr_seconds)  # ~2s later for association cortex
+        elif roi_name in ["TPOJ1", "TPOJ2", "STV", "PSL"]:
+            latency_shift = int(1.5 / tr_seconds)
+
+        shifted = np.roll(bold_signal, latency_shift) * w
+        # Add per-vertex variation within ROI
+        for v in vertices:
+            if v < n_vertices:
+                vertex_scale = 0.8 + 0.4 * rng.random()
+                predictions[:, v] = shifted * vertex_scale
+
+    # 3. Add temporal autocorrelation (AR(1) noise)
+    ar_coeff = 0.5
+    noise = rng.standard_normal(predictions.shape)
+    for t in range(1, n_timepoints):
+        noise[t] += ar_coeff * noise[t - 1]
+
+    # 4. Add scanner drift (low-frequency sinusoidal)
+    t_axis = np.arange(n_timepoints) * tr_seconds
+    drift = 0.1 * np.sin(2 * np.pi * t_axis / (n_timepoints * tr_seconds * 0.8))
+    drift = drift[:, np.newaxis]
+
+    # 5. Combine signal + noise + drift
+    signal_power = np.std(predictions[predictions != 0]) if np.any(predictions != 0) else 1.0
+    noise_power = signal_power / max(snr, 0.1)
+    predictions = predictions + noise * noise_power + drift
+
+    # 6. Spatial smoothing (average with neighbors within same ROI)
+    for roi_name, vertices in roi_indices.items():
+        valid = vertices[vertices < n_vertices]
+        if len(valid) > 1:
+            roi_data = predictions[:, valid].copy()
+            kernel = np.ones(min(3, len(valid))) / min(3, len(valid))
+            for t in range(n_timepoints):
+                predictions[t, valid] = np.convolve(roi_data[t], kernel, mode="same")
+
+    return predictions
+
+
+def generate_correlated_features(
+    brain_predictions,
+    alignment_strength=0.5,
+    feature_dim=512,
+    seed=42,
+):
+    """Generate model features with controllable correlation to brain data.
+
+    Parameters
+    ----------
+    brain_predictions : np.ndarray
+        Brain data of shape (n_stimuli, n_vertices).
+    alignment_strength : float
+        0.0 = random features, 1.0 = perfectly correlated with brain.
+    feature_dim : int
+        Output feature dimensionality.
+    seed : int
+        Random seed.
+
+    Returns
+    -------
+    np.ndarray
+        Features of shape (n_stimuli, feature_dim).
+    """
+    rng = np.random.default_rng(seed)
+    n_stimuli = brain_predictions.shape[0]
+
+    # Project brain data to feature_dim via random projection
+    n_vertices = brain_predictions.shape[1]
+    projection = rng.standard_normal((n_vertices, feature_dim)) / np.sqrt(n_vertices)
+    brain_projected = brain_predictions @ projection
+
+    # Generate random features
+    random_features = rng.standard_normal((n_stimuli, feature_dim))
+
+    # Mix: strength controls brain-alignment vs randomness
+    strength = np.clip(alignment_strength, 0.0, 1.0)
+    features = strength * brain_projected + (1 - strength) * random_features
+
+    # Standardize
+    features = (features - features.mean(axis=0)) / (features.std(axis=0) + 1e-8)
+    return features

utils.py

@@ -79,13 +79,114 @@ ALIGNMENT_METHODS = {"RSA": rsa_score, "CKA": cka_score, "Procrustes": procruste
 
 
 def permutation_test(model_feat, brain_pred, method_fn, n_perm=500, seed=42):
+    """Returns (observed_score, p_value, null_distribution)."""
     rng = np.random.default_rng(seed)
     observed = method_fn(model_feat, brain_pred)
-    count = sum(
-        1 for _ in range(n_perm)
-        if method_fn(model_feat[rng.permutation(len(model_feat))], brain_pred) >= observed
-    )
-    return observed, (count + 1) / (n_perm + 1)
+    null_dist = []
+    for _ in range(n_perm):
+        perm_score = method_fn(model_feat[rng.permutation(len(model_feat))], brain_pred)
+        null_dist.append(perm_score)
+    null_dist = np.array(null_dist)
+    count = np.sum(null_dist >= observed)
+    p_value = (count + 1) / (n_perm + 1)
+    return observed, p_value, null_dist
+
+
+def bootstrap_ci(model_feat, brain_pred, method_fn, n_boot=500, confidence=0.95, seed=42):
+    """Returns (point_estimate, ci_lower, ci_upper)."""
+    rng = np.random.default_rng(seed)
+    n = model_feat.shape[0]
+    point = method_fn(model_feat, brain_pred)
+    scores = []
+    for _ in range(n_boot):
+        idx = rng.choice(n, size=n, replace=True)
+        scores.append(method_fn(model_feat[idx], brain_pred[idx]))
+    scores = np.array(scores)
+    alpha = 1 - confidence
+    return point, float(np.percentile(scores, 100 * alpha / 2)), float(np.percentile(scores, 100 * (1 - alpha / 2)))
+
+
+def fdr_correction(p_values, alpha=0.05):
+    """Benjamini-Hochberg FDR correction. Returns corrected p-values and significance mask."""
+    p = np.array(p_values)
+    n = len(p)
+    sorted_idx = np.argsort(p)
+    sorted_p = p[sorted_idx]
+    corrected = np.empty(n)
+    corrected[sorted_idx[-1]] = sorted_p[-1]
+    for i in range(n - 2, -1, -1):
+        corrected[sorted_idx[i]] = min(corrected[sorted_idx[i + 1]], sorted_p[i] * n / (i + 1))
+    return corrected, corrected < alpha
+
+
+def noise_ceiling(brain_pred, method_fn, n_splits=20, seed=42):
+    """Estimate noise ceiling via split-half reliability."""
+    rng = np.random.default_rng(seed)
+    n = brain_pred.shape[0]
+    scores = []
+    for _ in range(n_splits):
+        idx = rng.permutation(n)
+        half = n // 2
+        s = method_fn(brain_pred[idx[:half]], brain_pred[idx[half:half * 2]])
+        scores.append(s)
+    return float(np.mean(scores)), float(np.std(scores))
+
+
+def partial_correlation(predictions, roi_indices):
+    """Compute partial correlation matrix (correlation controlling for mean signal)."""
+    names = list(roi_indices.keys())
+    n = len(names)
+    T = predictions.shape[0]
+    timecourses = np.zeros((n, T))
+    for i, name in enumerate(names):
+        verts = roi_indices[name]
+        valid = verts[verts < predictions.shape[1]]
+        if len(valid) > 0:
+            timecourses[i] = predictions[:, valid].mean(axis=1)
+
+    # Partial correlation via precision matrix
+    cov = np.cov(timecourses)
+    try:
+        prec = np.linalg.inv(cov + 1e-6 * np.eye(n))
+        d = np.sqrt(np.diag(prec))
+        d[d == 0] = 1
+        partial = -prec / np.outer(d, d)
+        np.fill_diagonal(partial, 1.0)
+    except np.linalg.LinAlgError:
+        partial = np.eye(n)
+    return np.nan_to_num(partial, nan=0.0), names
+
+
+def betweenness_centrality(corr_matrix, roi_names, threshold=0.3):
+    """Compute betweenness centrality from thresholded connectivity."""
+    import networkx as nx
+    n = corr_matrix.shape[0]
+    G = nx.Graph()
+    for i, name in enumerate(roi_names):
+        G.add_node(name)
+    for i in range(n):
+        for j in range(i + 1, n):
+            if abs(corr_matrix[i, j]) > threshold:
+                G.add_edge(roi_names[i], roi_names[j], weight=abs(corr_matrix[i, j]))
+    bc = nx.betweenness_centrality(G)
+    return {name: bc.get(name, 0.0) for name in roi_names}
+
+
+def modularity_score(corr_matrix, labels):
+    """Compute Newman's modularity Q for a given partition."""
+    n = corr_matrix.shape[0]
+    adj = np.abs(corr_matrix).copy()
+    np.fill_diagonal(adj, 0)
+    m = adj.sum() / 2
+    if m == 0:
+        return 0.0
+    Q = 0.0
+    k = adj.sum(axis=1)
+    for i in range(n):
+        for j in range(n):
+            if labels[i] == labels[j]:
+                Q += adj[i, j] - k[i] * k[j] / (2 * m)
+    return float(Q / (2 * m))
 
 
 # --- Cognitive Load ---