added notebooks and data for ucla workshop

Author: Ramdam17

tutorial/UCLAWorkshop/.DS_Store

@@ -0,0 +1,277 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "6b3e57da-a5b2-485f-9986-6c6af4793aa3",
+   "metadata": {},
+   "source": [
+    "# Notebook 1: Introduction to Hyperscanning Analysis with HyPyP\n",
+    "\n",
+    "In this notebook, we introduce the basics of hyperscanning analysis using the HyPyP library. We will:\n",
+    "- Load epoch data for two participants.\n",
+    "- Construct a dyad (by combining the data into a single array).\n",
+    "- Compute a synchronization metric (circular correlation) using a connectivity analysis function.\n",
+    "- Visualize the resulting inter-brain synchrony connectivity matrix."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "afeec199-af57-4ae7-9f43-e37209b49810",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import mne\n",
+    "import numpy as np\n",
+    "from collections import OrderedDict\n",
+    "\n",
+    "# HyPyP modules for I/O, analyses, and visualization\n",
+    "import hypyp.io as io  # For loading and constructing dyads\n",
+    "import hypyp.analyses as analyses  # For computing synchronization metrics\n",
+    "import hypyp.prep as prep  # Preprocessing module (for ICA and other cleaning routines)\n",
+    "import hypyp.viz as viz  # For visualizing results\n",
+    "\n",
+    "# Confirm successful import of libraries\n",
+    "print(\"Libraries imported successfully.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4055eb95-0f79-4ad7-8f32-dbe3440ae2f6",
+   "metadata": {},
+   "source": [
+    "## Loading the Data\n",
+    "\n",
+    "We load the epoch files for two participants from:\n",
+    "- `./data/participant1-epo.fif`\n",
+    "- `./data/participant2-epo.fif`\n",
+    "\n",
+    "Each file contains one epoch (a single trial) for one participant. After loading, we equalize the number of epochs between participants and print summaries for verification."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1627f0e9-1e3c-4681-8db7-13c528a7b61c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Load epochs for participant 1 and participant 2\n",
+    "epo1 = mne.read_epochs(\"./data/participant1-epo.fif\", preload=True)\n",
+    "epo2 = mne.read_epochs(\"./data/participant2-epo.fif\", preload=True)\n",
+    "\n",
+    "# Equalize the number of epochs between participants to ensure consistent analysis\n",
+    "mne.epochs.equalize_epoch_counts([epo1, epo2])\n",
+    "\n",
+    "# Print summaries to verify that the epochs have been loaded correctly\n",
+    "print(\"Participant 1 Epochs:\")\n",
+    "print(epo1)\n",
+    "print(\"\\nParticipant 2 Epochs:\")\n",
+    "print(epo2)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1af0aa41-2e5e-449c-bdb6-ac8fcf51ef97",
+   "metadata": {},
+   "source": [
+    "## Preprocessing with ICA\n",
+    "\n",
+    "Before computing connectivity, we perform additional preprocessing to remove artifacts such as eye blinks.  \n",
+    "Here we apply ICA using functions from `hypyp.prep`. Adjust parameters (e.g., method, number of components) as needed."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3c7975f2-bb30-42e4-a63f-6bff7255b37b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Compute ICA for each participant with 15 components\n",
+    "icas = prep.ICA_fit([\n",
+    "    epo1, epo2\n",
+    "],\n",
+    "    n_components=15,\n",
+    "    method='infomax',\n",
+    "    fit_params=dict(extended=True),\n",
+    "    random_state=42\n",
+    ")\n",
+    "\n",
+    "# Select the relevant independent components for artefact rejection\n",
+    "cleaned_epochs_ICA = prep.ICA_choice_comp(icas, [epo1, epo2])\n",
+    "print('ICA correction completed.')\n",
+    "\n",
+    "# Apply local AutoReject on the ICA-cleaned epochs\n",
+    "cleaned_epochs_AR, dic_AR = prep.AR_local(\n",
+    "    cleaned_epochs_ICA,\n",
+    "    strategy=\"union\",\n",
+    "    threshold=50.0,\n",
+    "    verbose=True\n",
+    ")\n",
+    "print('AutoReject completed.')\n",
+    "\n",
+    "# Assign cleaned epochs to individual participant variables\n",
+    "epo1_clean = cleaned_epochs_AR[0]\n",
+    "epo2_clean = cleaned_epochs_AR[1]\n",
+    "print('Preprocessed epochs for both participants are ready.')\n",
+    "\n",
+    "# Update dyad with cleaned data for subsequent analysis\n",
+    "dyad_clean = [epo1_clean.get_data(copy=True), epo2_clean.get_data(copy=True)]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "85efe31a-f9dc-4ef3-aaa1-21ea8d243974",
+   "metadata": {},
+   "source": [
+    "## Computing the Inter-Brain Synchrony (Circular Correlation)\n",
+    "\n",
+    "In this section, we compute a synchronization metric using the circular correlation coefficient (\"ccorr\") rather than PLV. The steps are as follows:\n",
+    "\n",
+    "1. **Determine Sampling Rate:**  \n",
+    "   We extract the sampling rate from one of the epochs.\n",
+    "\n",
+    "2. **Define Frequency Bands:**  \n",
+    "   We define two frequency bands as an OrderedDict. Here, we focus on the \"Alpha-Low\" band for further analysis.\n",
+    "\n",
+    "3. **Prepare Data:**  \n",
+    "   We combine the epochs from both participants into a single 4D array with shape *(2, n_epochs, n_channels, n_times)*.\n",
+    "\n",
+    "4. **Compute Analytic Signal:**  \n",
+    "   The function `compute_freq_bands` filters the data and applies the Hilbert transform for each frequency band.\n",
+    "\n",
+    "5. **Compute Connectivity:**  \n",
+    "   Using the `compute_sync` function with mode `'ccorr'`, we compute the inter-brain connectivity and then slice out the inter-brain connectivity matrix for the Alpha-Low band.\n",
+    "\n",
+    "6. **Normalization:**  \n",
+    "   Finally, we compute a Z-score normalized connectivity matrix."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bd0c8f25-0376-4a10-9296-cfcf237727f2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Extract the sampling rate from the epoch (assumes both participants share the same sfreq)\n",
+    "sampling_rate = epo1.info['sfreq']\n",
+    "\n",
+    "# Define frequency bands as a dictionary (here two alpha sub-bands)\n",
+    "freq_bands = {\n",
+    "    'Alpha-Low': [7.5, 11],\n",
+    "    'Alpha-High': [11.5, 13]\n",
+    "}\n",
+    "# Convert to an OrderedDict to maintain the order\n",
+    "freq_bands = OrderedDict(freq_bands)\n",
+    "\n",
+    "# Prepare data for connectivity analysis by combining both participants' epochs.\n",
+    "# The resulting data_inter array will have shape: (2, n_epochs, n_channels, n_times)\n",
+    "dyad_clean = np.array([epo1_clean.get_data(copy = True), epo2_clean.get_data(copy = True)])\n",
+    "\n",
+    "# Compute the analytic signal in each frequency band using FIR filtering and Hilbert transform.\n",
+    "complex_signal = analyses.compute_freq_bands(\n",
+    "    dyad_clean,\n",
+    "    sampling_rate,\n",
+    "    freq_bands,\n",
+    "    filter_length=int(sampling_rate),  # Adjust filter length based on sampling rate\n",
+    "    l_trans_bandwidth=5.0,  # Reduced transition bandwidth for sharper filtering\n",
+    "    h_trans_bandwidth=5.0\n",
+    ")\n",
+    "\n",
+    "# Compute connectivity using the circular correlation ('ccorr') metric and average across epochs.\n",
+    "result = analyses.compute_sync(complex_signal, mode='ccorr', epochs_average=True)\n",
+    "\n",
+    "# Determine the number of channels per participant\n",
+    "n_ch = len(epo1_clean.info['ch_names'])\n",
+    "\n",
+    "# Slice the connectivity matrix to extract inter-brain connectivity.\n",
+    "# The matrix 'result' has shape (n_freq, 2*n_channels, 2*n_channels).\n",
+    "# We slice to get connectivity values between channels of participant 1 (first n_ch)\n",
+    "# and participant 2 (last n_ch) for each frequency band.\n",
+    "alpha_low, alpha_high = result[:, 0:n_ch, n_ch:2*n_ch]\n",
+    "\n",
+    "# For further analysis, choose the Alpha-Low band values.\n",
+    "values = alpha_low\n",
+    "\n",
+    "# Compute a Z-score normalized connectivity matrix for improved comparability.\n",
+    "C = (values - np.mean(values[:])) / np.std(values[:])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "db571218-40ab-4053-b2a0-5c590db04863",
+   "metadata": {},
+   "source": [
+    "## Visualizing the Results\n",
+    "\n",
+    "We now visualize the computed inter-brain connectivity using both 2D and 3D representations.  \n",
+    "- The **2D topographic plot** helps identify regions with stronger inter-brain synchrony.\n",
+    "- The **3D visualization** provides a spatial representation of the connectivity.\n",
+    "\n",
+    "The functions `viz.viz_2D_topomap_inter` and `viz.viz_3D_inter` handle the visualization."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4635da92-b7da-4c36-99b1-515702cec4bf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Plot the 2D topographic map of the normalized connectivity matrix\n",
+    "viz.viz_2D_topomap_inter(epo1_clean, epo2_clean, C, threshold='auto', steps=10, lab=True)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dea11dcc-502d-4d91-9d8b-554ec8e51b0f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Plot the 3D visualization of the inter-brain connectivity\n",
+    "viz.viz_3D_inter(epo1_clean, epo2_clean, C, threshold='auto', steps=10, lab=False)\n",
+    "print('3D inter-brain connectivity visualization completed.')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "755de848-71e5-4320-b5ec-ffd6b8aaddbe",
+   "metadata": {},
+   "source": [
+    "## Conclusion\n",
+    "\n",
+    "In this notebook, we have:\n",
+    "- Loaded epoch data for two participants.\n",
+    "- Constructed a dyad by combining the data arrays.\n",
+    "- Computed a synchronization metric (circular correlation, \"ccorr\") to assess inter-brain synchrony across defined frequency bands.\n",
+    "- Visualized the resulting connectivity matrix using both 2D and 3D plots.\n",
+    "\n",
+    "This foundational analysis prepares us for further hyperscanning investigations using HyPyP. In upcoming notebooks, we will explore more advanced preprocessing techniques, compare different synchronization metrics, and implement detailed statistical analyses."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}