Upload brain_virality_predictor/signals.py with huggingface_hub

brain_virality_predictor/signals.py

@@ -0,0 +1,79 @@
+"""
+Brain-response → 8 UX-relevant signals.
+
+Signal design is grounded in published neuroscience:
+  aesthetic_appeal   → Vessel & Rubin 2019 (Visual network + Default mode)
+  visual_fluency     → Reber et al. 2004 (Visual clarity → fluency → preference)
+  cognitive_load     → frontoparietal + dorsal attention engagement
+  trust_affinity     → Limbic / Default mode emotional resonance
+  reward_anticipation → Knutson et al. 2007 (Nucleus accumbens / ventral striatum)
+  motor_readiness     → Somatomotor cortex activation (mirror-neuron prep)
+  surprise_novelty   → Ventral attention / salience detection
+  friction_anxiety   → Frontoparietal conflict signal (effort / aversion)
+
+Each signal is a linear (or nonlinear) blend of Yeo7 network time series.
+"""
+
+import numpy as np
+from typing import Dict
+
+# ── blending weights per UX signal ───────────────────────────────────
+# Positive weights = network drives signal up. Negative = drives down.
+SIGNAL_BLEND = {
+    "aesthetic_appeal": {
+        "Visual": 0.40,
+        "Default": 0.35,
+        "Limbic": 0.25,
+    },
+    "visual_fluency": {
+        "Visual": 0.50,
+        "Dorsal_Attention": 0.30,
+        "Ventral_Attention": 0.20,
+    },
+    "cognitive_load": {
+        "Frontoparietal": 0.45,
+        "Dorsal_Attention": 0.35,
+        "Default": -0.20,          # DMN suppression under load
+    },
+    "trust_affinity": {
+        "Limbic": 0.40,
+        "Default": 0.35,
+        "Somatomotor": 0.10,
+        "Frontoparietal": -0.15,   # trust should feel easy, not effortful
+    },
+    "reward_anticipation": {
+        "Limbic": 0.50,
+        "Ventral_Attention": 0.25,
+        "Default": 0.25,
+    },
+    "motor_readiness": {
+        "Somatomotor": 0.60,
+        "Frontoparietal": 0.25,
+        "Dorsal_Attention": 0.15,
+    },
+    "surprise_novelty": {
+        "Ventral_Attention": 0.50,
+        "Dorsal_Attention": 0.30,
+        "Frontoparietal": 0.20,
+    },
+    "friction_anxiety": {
+        "Frontoparietal": 0.45,
+        "Dorsal_Attention": 0.30,
+        "Visual": -0.25,          # anxiety kills visual fluency
+    },
+}
+
+
+def network_to_ux_signals(network_ts: Dict[str, np.ndarray]) -> Dict[str, np.ndarray]:
+    """
+    network_ts: {Yeo_network_name: (n_timesteps,) array}
+    Returns: {signal_name: (n_timesteps,) array}
+    """
+    n = next(iter(network_ts.values())).shape[0]
+    signals = {}
+    for sig_name, weights in SIGNAL_BLEND.items():
+        vec = np.zeros(n, dtype=np.float32)
+        for net_name, w in weights.items():
+            vec += w * network_ts.get(net_name, np.zeros(n))
+        signals[sig_name] = vec
+    return signals