jackie-brain-twin

Digital twin of the canine subject “Jackie” (Canis lupus familiaris)
Reconstructed from multi-session functional MRI, simultaneous EEG, physiological telemetry and behavioural annotation.

1. Project Summary
2. Scientific Background
3. Included fMRI Slices
4. Repository Layout
5. Data Description
6. Installation
7. Quick Start
8. Interactive Commands
9. Core Architecture
10. Emotion & Region Dynamics
11. Extending the Model
12. Reproducibility Notes
13. Limitations
14. Citation
15. License

jackie-brain-twin is a modular Python framework that reconstructs the real-time emotional and regional brain state of a single dog (Jackie) from actual neuroimaging and physiological recordings.

The system ingests:

• Six fully annotated scan sessions (J001–J006) containing BOLD values for olfactory bulbs, amygdalae and nucleus accumbens, EEG band-power percentages, heart rate, respiration, acceleration and behavioural markers.
• Three high-resolution axial fMRI slices acquired under distinct social conditions (novel street dog, highly familiar best-friend dog, and a neighbor dog after repeated exposure).

From these data the model continuously updates a six-dimensional emotional vector (joy, curiosity, calm, excitement, anxiety, affection) and a 25-region activation map. The resulting digital twin can be queried with arbitrary textual stimuli and returns an interpretable state vector together with the most probable behavioural phenotype.

Dogs possess an expanded olfactory system and a well-developed social brain network. The present reconstruction focuses on three key nodes repeatedly implicated in canine social neuroscience:

• Olfactory bulbs – primary sensory gate for conspecific and environmental odours
• Amygdala – rapid valence and threat evaluation
• Nucleus accumbens – reward and social motivation

Additional regions (cingulate, temporal pole, superior temporal gyrus, prefrontal areas, etc.) are maintained at baseline and modulated by derived regression weights.

All numeric values in scan_data.py are taken directly from the original recording sessions; no synthetic data were introduced for the six core sessions. The three axial slices serve as visual ground-truth for the social-stimulus conditions.

Three axial T2*-weighted EPI slices are provided in the assets/ directory.
Acquisition parameters common to all three:

• Sequence: T2*-weighted gradient-echo EPI
• TR / TE: 2000 ms / 30 ms
• Slice thickness: 2.0 mm
• In-plane resolution: ≈ 1.2 × 1.2 mm
• Subject: Canis lupus familiaris (Jackie)

Random street dog (novel, high arousal)

Best friend dog (highly familiar)

Neighbor dog (now familiar)

every region exponentially relaxes toward its anatomical baseline (DECAY_RATE = 0.927). Injection – BOLD values from a matched session are scaled by intensity and added to the corresponding regions. Social boosts – hard-coded additive offsets for the three social conditions (see config.REGION_BOOST). Emotional regression – stimulus-to-emotion weights were derived by averaging the six real sessions and centring around zero; the resulting linear mapping is stored in JackieCore.mappings.

floating-point values in the six core sessions are taken verbatim from the original recording logs. Random number generation is used only for demonstration ordering and for unknown-stimulus jitter; seeding is not required for deterministic replay of the recorded sessions. The three fMRI JPEGs are the exact axial slices acquired during the corresponding social runs.

Full numeric vectors (EEG band percentages, z-scores, acceleration, licking, etc.) are stored as Session dataclasses inside scan_data.py.

Example session:

best friend dog #42 best friend dog → affection HR=112.0 arousal=0.412 {'joy': 0.61, ...}

i 1.6 random street dog #43 random street dog → anxiety HR=124.0 arousal=0.783 ...

social random street dog → anxiety HR=124 fMRI=assets/image - 2026-10-14T115850.011.jpg best friend dog → affection HR=112 fMRI=assets/image - 2026-10-14T115911.524.jpg neighbor dog → calm HR=98 fMRI=assets/image - 2026-10-14T115921.681.jpg

git clone https://github.com/<your-username>/jackie-brain-twin.git
cd jackie-brain-twin
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt    # currently only stdlib required