{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Adding Synthetic Hemodynamic Reponses to Data\n", "\n", "This example notebook illustrates the functionality in `cedalion.sim.synthetic_hrf`\n", "to create simulated datasets with added activations." ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "execution": { "iopub.execute_input": "2026-05-07T06:45:48.330140Z", "iopub.status.busy": "2026-05-07T06:45:48.329973Z", "iopub.status.idle": "2026-05-07T06:45:48.335647Z", "shell.execute_reply": "2026-05-07T06:45:48.334965Z" } }, "outputs": [], "source": [ "# This cells setups the environment when executed in Google Colab.\n", "try:\n", " import google.colab\n", " !curl -s https://raw.githubusercontent.com/ibs-lab/cedalion/dev/scripts/colab_setup.py -o colab_setup.py\n", " # Select branch with --branch \"branch name\" (default is \"dev\")\n", " %run colab_setup.py\n", "except ImportError:\n", " pass" ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "execution": { "iopub.execute_input": "2026-05-07T06:45:48.337431Z", "iopub.status.busy": "2026-05-07T06:45:48.337278Z", "iopub.status.idle": "2026-05-07T06:45:48.340213Z", "shell.execute_reply": "2026-05-07T06:45:48.339240Z" } }, "outputs": [], "source": [ "# set this flag to True to enable interactive 3D plots\n", "INTERACTIVE_PLOTS = False" ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "execution": { "iopub.execute_input": "2026-05-07T06:45:48.341667Z", "iopub.status.busy": "2026-05-07T06:45:48.341499Z", "iopub.status.idle": "2026-05-07T06:45:50.855392Z", "shell.execute_reply": "2026-05-07T06:45:50.854563Z" } }, "outputs": [], "source": [ "import os\n", "\n", "import matplotlib.pyplot as plt\n", "import numpy as np\n", "import pyvista as pv\n", "import xarray as xr\n", "\n", "import cedalion\n", "import cedalion.dataclasses as cdc\n", "import cedalion.data\n", "import cedalion.geometry.landmarks as cd_landmarks\n", "import cedalion.dot as dot\n", "import cedalion.models.glm as glm\n", "import cedalion.nirs\n", "\n", "import cedalion.vis.anatomy\n", "import cedalion.vis.blocks as vbx\n", "\n", "import cedalion.sigproc.quality as quality\n", "import cedalion.sim.synthetic_hrf as synhrf\n", "import cedalion.xrutils as xrutils\n", "from cedalion import units\n", "\n", "xr.set_options(display_expand_data=False)\n", "\n", "if INTERACTIVE_PLOTS:\n", " pv.set_jupyter_backend('server')\n", "else:\n", " pv.set_jupyter_backend('static')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Loading and preprocessing the dataset\n", "\n", "This notebook uses a high-density, whole head resting state dataset recorded with a NinjaNIRS 22." ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "execution": { "iopub.execute_input": "2026-05-07T06:45:50.857257Z", "iopub.status.busy": "2026-05-07T06:45:50.856870Z", "iopub.status.idle": "2026-05-07T06:45:53.290225Z", "shell.execute_reply": "2026-05-07T06:45:53.289417Z" } }, "outputs": [ { "data": { "text/html": [ "
<xarray.DataArray (channel: 567, wavelength: 2, time: 3310)> Size: 30MB\n",
"[V] 0.05955 0.0596 0.05969 0.0598 0.05993 ... 0.3148 0.3137 0.3136 0.3136 0.3144\n",
"Coordinates:\n",
" * time (time) float64 26kB 0.0 0.1112 0.2225 ... 367.9 368.0 368.1\n",
" samples (time) int64 26kB 0 1 2 3 4 5 ... 3304 3305 3306 3307 3308 3309\n",
" * channel (channel) object 5kB 'S10D87' 'S10D94' ... 'S47D29' 'S5D137'\n",
" source (channel) object 5kB 'S10' 'S10' 'S10' ... 'S56' 'S47' 'S5'\n",
" detector (channel) object 5kB 'D87' 'D94' 'D89' ... 'D129' 'D29' 'D137'\n",
" * wavelength (wavelength) float64 16B 760.0 850.0\n",
"Attributes:\n",
" data_type_group: unprocessed raw<xarray.DataArray (label: 73, mni: 3)> Size: 2kB\n",
"[mm] 0.0045 -118.6 -23.08 -86.08 -19.99 ... -100.4 37.02 49.81 -99.34 21.47\n",
"Coordinates:\n",
" * label (label) <U3 876B 'Iz' 'LPA' 'RPA' 'Nz' ... 'PO1' 'PO2' 'PO4' 'PO6'\n",
" type (label) object 584B PointType.LANDMARK ... PointType.LANDMARK\n",
"Dimensions without coordinates: mni<xarray.DataArray (vertex: 25000, chromo: 2)> Size: 400kB\n",
"[M] 1.303e-29 -5.211e-30 3.318e-30 -1.327e-30 9.361e-31 ... 0.0 -0.0 0.0 -0.0\n",
"Coordinates:\n",
" * chromo (chromo) <U3 24B 'HbO' 'HbR'\n",
"Dimensions without coordinates: vertex<xarray.DataArray (trial_type: 2, vertex: 25000, chromo: 2)> Size: 800kB\n",
"[M] 1.303e-29 -5.211e-30 3.318e-30 ... -3.621e-22 7.069e-35 -2.828e-35\n",
"Coordinates:\n",
" * chromo (chromo) <U3 24B 'HbO' 'HbR'\n",
" * trial_type (trial_type) <U7 56B 'Stim C3' 'Stim C4'\n",
"Dimensions without coordinates: vertex<xarray.DataArray (channel: 544, vertex: 25000, wavelength: 2)> Size: 109MB\n",
"5.947e-18 5.947e-18 2.007e-18 2.007e-18 ... 0.0 0.0 7.713e-22 7.713e-22\n",
"Coordinates:\n",
" parcel (vertex) object 200kB 'VisCent_ExStr_8_LH' ... 'VisCent_ExStr...\n",
" is_brain (vertex) bool 25kB True True True True ... True True True True\n",
" * channel (channel) object 4kB 'S10D87' 'S10D94' ... 'S47D29' 'S5D137'\n",
" detector (channel) object 4kB 'D87' 'D94' 'D89' ... 'D129' 'D29' 'D137'\n",
" source (channel) object 4kB 'S10' 'S10' 'S10' ... 'S56' 'S47' 'S5'\n",
" * wavelength (wavelength) float64 16B 760.0 850.0\n",
"Dimensions without coordinates: vertex\n",
"Attributes:\n",
" units: mm<xarray.DataArray (trial_type: 2, wavelength: 2, channel: 544)> Size: 17kB\n",
"[] -7.023e-13 -2.009e-11 -1.658e-11 -5.764e-14 ... 1.389e-06 2.452e-08 2.415e-08\n",
"Coordinates:\n",
" * wavelength (wavelength) float64 16B 760.0 850.0\n",
" * channel (channel) object 4kB 'S10D112' 'S10D133' ... 'S9D94' 'S9D96'\n",
" * trial_type (trial_type) <U7 56B 'Stim C3' 'Stim C4'\n",
" source (channel) object 4kB 'S10' 'S10' 'S10' 'S10' ... 'S9' 'S9' 'S9'\n",
" detector (channel) object 4kB 'D112' 'D133' 'D135' ... 'D92' 'D94' 'D96'<xarray.DataArray (time: 1, trial_type: 2, wavelength: 2, channel: 544)> Size: 17kB\n",
"[] -7.023e-13 -2.009e-11 -1.658e-11 -5.764e-14 ... 1.389e-06 2.452e-08 2.415e-08\n",
"Coordinates:\n",
" * wavelength (wavelength) float64 16B 760.0 850.0\n",
" * channel (channel) object 4kB 'S10D112' 'S10D133' ... 'S9D94' 'S9D96'\n",
" * trial_type (trial_type) <U7 56B 'Stim C3' 'Stim C4'\n",
" source (channel) object 4kB 'S10' 'S10' 'S10' 'S10' ... 'S9' 'S9' 'S9'\n",
" detector (channel) object 4kB 'D112' 'D133' 'D135' ... 'D92' 'D94' 'D96'\n",
" * time (time) int64 8B 0<xarray.DataArray 'concentration' ()> Size: 8B\n",
"[] 11.0"
],
"text/plain": [
"<xarray.DataArray 'time' (time: 3310)> Size: 26kB\n",
"0.0 0.1112 0.2225 0.3337 0.445 0.5562 ... 367.6 367.7 367.8 367.9 368.0 368.1\n",
"Coordinates:\n",
" * time (time) float64 26kB 0.0 0.1112 0.2225 0.3337 ... 367.9 368.0 368.1\n",
" samples (time) int64 26kB 0 1 2 3 4 5 6 ... 3304 3305 3306 3307 3308 3309\n",
"Attributes:\n",
" units: second| \n", " | onset | \n", "duration | \n", "value | \n", "trial_type | \n", "
|---|---|---|---|---|
| 0 | \n", "17.94 | \n", "10.0 | \n", "1.0 | \n", "Stim C4 | \n", "
| 1 | \n", "47.78 | \n", "10.0 | \n", "1.0 | \n", "Stim C4 | \n", "
| 2 | \n", "74.94 | \n", "10.0 | \n", "1.0 | \n", "Stim C4 | \n", "
| 3 | \n", "103.39 | \n", "10.0 | \n", "1.0 | \n", "Stim C3 | \n", "
| 4 | \n", "133.25 | \n", "10.0 | \n", "1.0 | \n", "Stim C4 | \n", "
<xarray.DataArray (trial_type: 2, wavelength: 2, channel: 544, time: 3310)> Size: 58MB\n",
"[] -0.0 -0.0 -0.0 -0.0 -0.0 -0.0 -0.0 -0.0 ... 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0\n",
"Coordinates:\n",
" * wavelength (wavelength) float64 16B 760.0 850.0\n",
" * channel (channel) object 4kB 'S10D112' 'S10D133' ... 'S9D94' 'S9D96'\n",
" * trial_type (trial_type) <U7 56B 'Stim C3' 'Stim C4'\n",
" source (channel) object 4kB 'S10' 'S10' 'S10' 'S10' ... 'S9' 'S9' 'S9'\n",
" detector (channel) object 4kB 'D112' 'D133' 'D135' ... 'D92' 'D94' 'D96'\n",
" * time (time) float64 26kB 0.0 0.1112 0.2225 ... 367.9 368.0 368.1<xarray.DataArray (wavelength: 2, channel: 544, time: 3310)> Size: 29MB\n",
"[] 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0\n",
"Coordinates:\n",
" * wavelength (wavelength) float64 16B 760.0 850.0\n",
" * channel (channel) object 4kB 'S10D112' 'S10D133' ... 'S9D94' 'S9D96'\n",
" source (channel) object 4kB 'S10' 'S10' 'S10' 'S10' ... 'S9' 'S9' 'S9'\n",
" detector (channel) object 4kB 'D112' 'D133' 'D135' ... 'D92' 'D94' 'D96'\n",
" * time (time) float64 26kB 0.0 0.1112 0.2225 ... 367.9 368.0 368.1"
],
"text/plain": [
"<xarray.DataArray (channel: 544, wavelength: 2, time: 3310)> Size: 29MB\n",
"[] -0.001577 -0.00252 -0.003411 -0.004201 ... 0.0001448 0.0007453 0.001379\n",
"Coordinates:\n",
" * time (time) float64 26kB 0.0 0.1112 0.2225 ... 367.9 368.0 368.1\n",
" * channel (channel) object 4kB 'S10D87' 'S10D94' ... 'S47D29' 'S5D137'\n",
" * wavelength (wavelength) float64 16B 760.0 850.0\n",
" samples (time) int64 26kB 0 1 2 3 4 5 ... 3304 3305 3306 3307 3308 3309\n",
" source (channel) object 4kB 'S10' 'S10' 'S10' ... 'S56' 'S47' 'S5'\n",
" detector (channel) object 4kB 'D87' 'D94' 'D89' ... 'D129' 'D29' 'D137'<xarray.DataArray (chromo: 2, vertex: 25000, trial_type: 2, reltime: 226)> Size: 181MB\n",
"[µM] -0.006118 -0.005636 -0.005106 -0.004542 ... 0.001096 0.001083 0.001069\n",
"Coordinates:\n",
" * chromo (chromo) <U3 24B 'HbO' 'HbR'\n",
" * reltime (reltime) float64 2kB -4.995 -4.884 -4.773 ... 19.76 19.87 19.98\n",
" * trial_type (trial_type) object 16B 'Stim C3' 'Stim C4'\n",
" is_brain (vertex) bool 25kB True True True True ... True True True True\n",
" parcel (vertex) object 200kB 'VisCent_ExStr_8_LH' ... 'VisCent_ExStr...\n",
"Dimensions without coordinates: vertex| [1] | Tucker2022 | cedalion.io.snirf.read_snirf | Stephen Tucker, Jay Dubb, Sreekanth Kura, Alexander von Lühmann, Robert Franke, Jörn M. Horschig, Samuel Powell, Robert Oostenveld, Michael Lührs, Édouard Delaire, Zahra M. Aghajan, Hanseok Yun, Meryem A. Yücel, Qianqian Fang, Theodore J. Huppert, Blaise deB. Frederick, Luca Pollonini, David A. Boas, and Robert Luke.\n", "Introduction to the shared near infrared spectroscopy format.\n", "Neurophotonics, 10(1):013507, 2022.\n", "doi:10.1117/1.NPh.10.1.013507. |
| [2] | Huppert2009 | cedalion.sigproc.quality.snr | Theodore J. Huppert, Solomon G. Diamond, Maria A. Franceschini, and David A. Boas.\n", "Homer: a review of time-series analysis methods for near-infrared spectroscopy of the brain.\n", "Appl. Opt., 48(10):D280–D298, Apr 2009.\n", "doi:https://doi.org/10.1364/AO.48.00D280. |
| [3] | Delpy1988 | cedalion.nirs.cw.int2od, cedalion.nirs.cw.od2conc | D. T. Delpy, M. Cope, P. van der Zee, S. Arridge, S. Wray, and J. Wyatt.\n", "Estimation of optical pathlength through tissue from direct time of flight measurement.\n", "Physics in Medicine and Biology, 33(12):1433–1442, 1988.\n", "doi:10.1088/0031-9155/33/12/008. |
| [4] | Villringer1997 | cedalion.nirs.cw.int2od, cedalion.nirs.cw.od2conc | Arno Villringer and Britton Chance.\n", "Non-invasive optical spectroscopy and imaging of human brain function.\n", "Trends in Neurosciences, 20(10):435–442, 1997.\n", "doi:10.1016/S0166-2236(97)01132-6. |
| [5] | Holmes1998 | cedalion.data.get_colin27_headmodel_files | Colin J. Holmes, Rick Hoge, Louis Collins, Roger Woods, Arthur W. Toga, and Alan C. Evans.\n", "Enhancement of mr images using registration for signal averaging.\n", "Journal of Computer Assisted Tomography, 22(2):324–333, March 1998.\n", "doi:10.1097/00004728-199803000-00032. |
| [6] | Fischl2012 | cedalion.data.get_colin27_headmodel_files | Bruce Fischl.\n", "FreeSurfer.\n", "NeuroImage, 62(2):774–781, 2012.\n", "doi:10.1016/j.neuroimage.2012.01.021. |
| [7] | Schaefer2018 | cedalion.data.get_colin27_headmodel_files | Alexander Schaefer, Ru Kong, Evan M Gordon, Timothy O Laumann, Xi-Nian Zuo, Avram J Holmes, Simon B Eickhoff, and BT Thomas Yeo.\n", "Local-global parcellation of the human cerebral cortex from intrinsic functional connectivity mri.\n", "Cerebral cortex, 28(9):3095–3114, 2018.\n", "doi:10.1093/cercor/bhx179. |
| [8] | Gao2015 | cedalion.dataclasses.geometry.PycortexSurface.__init__ | James S. Gao, Alexander G. Huth, Mark D. Lescroart, and Jack L. Gallant.\n", "Pycortex: an interactive surface visualizer for fmri.\n", "Frontiers in Neuroinformatics, 2015.\n", "doi:10.3389/fninf.2015.00023. |
| [9] | Fang2009 | cedalion.data.get_precomputed_sensitivity | Qianqian Fang and David A Boas.\n", "Monte carlo simulation of photon migration in 3d turbid media accelerated by graphics processing units.\n", "Optics express, 17(22):20178–20190, 2009.\n", "doi:10.1364/OE.17.020178. |
| [10] | Yu2018 | cedalion.data.get_precomputed_sensitivity | Leiming Yu, Fanny Nina-Paravecino, David Kaeli, and Qianqian Fang.\n", "Scalable and massively parallel monte carlo photon transport simulations for heterogeneous computing platforms.\n", "Journal of biomedical optics, 23(1):010504–010504, 2018.\n", "doi:10.1117/1.JBO.23.1.010504. |
| [11] | Yan2020 | cedalion.data.get_precomputed_sensitivity | Shijie Yan and Qianqian Fang.\n", "Hybrid mesh and voxel based monte carlo algorithm for accurate and efficient photon transport modeling in complex bio-tissues.\n", "Biomedical Optics Express, 11(11):6262–6270, 2020.\n", "doi:10.1364/BOE.409468. |
| [12] | Prahl1998 | cedalion.nirs.common.get_extinction_coefficients | Scott A. Prahl.\n", "Optical absorption of hemoglobin.\n", "Oregon Medical Laser Center, online resource, 1998.\n", "URL: https://omlc.org/spectra/hemoglobin/. |
| [13] | Strangman2002 | cedalion.models.glm.basis_functions.Gamma.__call__ | Gary Strangman, Joseph P. Culver, John H. Thompson, and David A. Boas.\n", "A quantitative comparison of simultaneous BOLD fMRI and NIRS recordings during functional brain activation.\n", "NeuroImage, 17(2):719–731, 2002.\n", "doi:10.1006/nimg.2002.1227. |
| [14] | Carlton2026 | cedalion.dot.image_recon.GaussianSpatialBasisFunctions.__init__, cedalion.dot.image_recon.ImageRecon.__init__ | Laura B. Carlton, Miray Altınkaynak, Shannon Kelley, Bernhard B. Zimmermann, Sreekanth Kura, Eike Middell, Alexander von Lühmann, Emily P. Stephen, Meryem A. Yücel, and David A. Boas.\n", "Surface-based image reconstruction optimization for high-density functional near-infrared spectroscopy.\n", "Neurophotonics, 13(2):025001, 2026.\n", "doi:10.1117/1.NPh.13.2.025001. |
| [15] | Markow2025 | cedalion.dot.image_recon.ImageRecon.__init__ | Zachary E. Markow, Jason W. Trobaugh, Edward J. Richter, Kalyan Tripathy, Sean M. Rafferty, Alexandra M. Svoboda, Mariel L. Schroeder, Tracy M. Burns-Yocum, Karla M. Bergonzi, Mark A. Chevillet, Emily M. Mugler, Adam T. Eggebrecht, and Joseph P. Culver.\n", "Ultra high density imaging arrays in diffuse optical tomography for human brain mapping improve image quality and decoding performance.\n", "Scientific Reports, 15(1):3175, January 2025.\n", "doi:10.1038/s41598-025-85858-7. |