cedalion.sim.synthetic_hrf

Functions for generating synthetic hemodynamic response functions.

Functions

add_hrf_to_od(od, hrfs, stim_df)

Adds Hemodynamic Response Functions (HRFs) to optical density (OD) data.

add_hrf_to_vertices(hrf_basis, num_vertices)

Adds hemodynamic response functions (HRF) for HbO and HbR to specified vertices.

build_blob(head_model, landmark[, scale, m])

Generates a blob of activity at a seed landmark.

build_stim_df(num_stims[, stim_dur, ...])

Generates a DataFrame for stimulus metadata based on provided parameters.

generate_hrf(time_axis[, stim_dur, ...])

Generates HRF basis functions for different chromophores.

get_colors(activations, vertex_colors[, ...])

Maps activations to colors for visualization.

hrf_to_long_channels(hrf_model, y, geo3d[, ...])

Add HRFs to optical density (OD) data in channel space.

hrfs_from_image_reco(blob, hrf_model, Adot)

Maps an activation blob on the brain to HRFs in channel space.

plot_blob(blob_img, brain[, seed, title, ...])

Plots a blob of activity on the brain.
cedalion.sim.synthetic_hrf.generate_hrf(time_axis: ~xarray.core.dataarray.DataArray, stim_dur: Quantity = <Quantity(10, 'second')>, params_basis: list = [0.1, 3.0, 1.8, 3.0], scale: list = [<Quantity(10, 'micromolar')>, <Quantity(-4, 'micromolar')>])[source]

Generates HRF basis functions for different chromophores.

This function calculates the HRF basis functions using gamma distributions. It supports adjusting the response scale for HbO and HbR using parameters provided in params_basis and scale.

Parameters:

  • time_axis – The time axis for the resulting HRF.

  • stim_dur – Duration of the stimulus.

  • params_basis (list of float) – Parameters for tau and sigma for the modified gamma function for each chromophore. Expected to be a flat list where pairs represent [tau, sigma] for each chromophore.

  • scale (list of float) – Scaling factors for each chromophore, typically [HbO scale, HbR scale].

Returns:

A DataArray object with dimensions “time” and “chromo”,

containing the HRF basis functions for each chromophore.

Return type:

xarray.DataArray

Initial Contributors:
cedalion.sim.synthetic_hrf.build_blob(
head_model: ~cedalion.imagereco.forward_model.TwoSurfaceHeadModel,
landmark: str,
scale: Quantity = <Quantity(1,
'centimeter')>,
m: float = 10.0,
)[source]

Generates a blob of activity at a seed landmark.

This function generates a blob of activity on the brain surface. The blob is centered at the vertex closest to the seed landmark.

Parameters:

  • head_model (cfm.TwoSurfaceHeadModel) – Head model with brain and scalp surfaces.

  • landmark (str) – Name of the seed landmark.

  • scale (Quantity) – Scale of the blob.

  • m (float) – Geodesic distance parameter. Larger values of m will smooth & regularize the distance computation. Smaller values of m will roughen and will usually increase error in the distance computation.

Returns:

Blob image with activation values for each vertex.

Return type:

xr.DataArray

Initial Contributors:
cedalion.sim.synthetic_hrf.hrfs_from_image_reco(
blob: DataArray,
hrf_model: DataArray,
Adot: DataArray,
)[source]

Maps an activation blob on the brain to HRFs in channel space.

Parameters:

  • blob (xr.DataArray) – Activation values for each vertex.

  • hrf_model (xr.DataArray) – HRF model for HbO and HbR.

  • Adot (xr.DataArray) – Sensitivity matrix for the forward model.

Returns:

HRFs in channel space.

Return type:

cdt.NDTimeseries

Initial Contributors:
cedalion.sim.synthetic_hrf.add_hrf_to_vertices(
hrf_basis: DataArray,
num_vertices: int,
scale: array = None,
)[source]

Adds hemodynamic response functions (HRF) for HbO and HbR to specified vertices.

This function applies temporal HRF profiles to vertices, optionally scaling the response by a provided amplitude scale. It generates separate images for HbO and HbR and then combines them.

Parameters:

  • hrf_basis (xarray.DataArray) – Dataset containing HRF time series for HbO and HbR.

  • num_vertices (int) – Total number of vertices in the image space.

  • scale (np.array, optional) – Array of scale factors of shape (num_vertices) to scale the amplitude of HRFs.

Returns:

Combined image of HbO and HbR responses across all vertices for

all time points.

Return type:

xr.DataArray

Initial Contributors:
cedalion.sim.synthetic_hrf.build_stim_df(num_stims: int, stim_dur: Quantity = <Quantity(10, 'second')>, trial_types: list = ['Stim'], min_interval: Quantity = <Quantity(5, 'second')>, max_interval: Quantity = <Quantity(10, 'second')>, order: str = 'alternating')[source]

Generates a DataFrame for stimulus metadata based on provided parameters.

Stimuli can be added in an ‘alternating’ or ‘random’ order, and the inter-stimulus interval (ISI) is chosen randomly between the minimum and maximum allowed intervals.

Parameters:

  • num_stims (int) – Number of stimuli to be added for each trial type.

  • stim_dur (int) – Duration of the stimulus in seconds.

  • trial_types (list) – List of trial types for the stimuli.

  • min_interval (int) – Minimum inter-stimulus interval in seconds.

  • max_interval (int) – Maximum inter-stimulus interval in seconds.

  • order (str) – Order of adding Stims; ‘alternating’ or ‘random’.

Returns:

DataFrame containing stimulus metadata.

Return type:

pd.DataFrame

Initial Contributors:
cedalion.sim.synthetic_hrf.add_hrf_to_od(
od: cdt.NDTimeSeries,
hrfs: cdt.NDTimeSeries,
stim_df: DataFrame,
)[source]

Adds Hemodynamic Response Functions (HRFs) to optical density (OD) data.

The timing of the HRFs is based on the provided stimulus dataframe (stim_df).

Parameters:

  • od (cdt.NDTimeSeries) – OD timeseries data with dimensions [“channel”, “wavelength”, “time”].

  • hrfs (cdt.NDTimeSeries) – HRFs in channel space with dimensions [“channel”, “wavelength”, “time”] + maybe [“trial_type”].

  • stim_df (pd.DataFrame) – DataFrame containing stimulus metadata.

Returns:

OD data with HRFs added based on the stimulus dataframe.

Return type:

cdt.NDTimeSeries

Initial Contributors:
cedalion.sim.synthetic_hrf.hrf_to_long_channels(
hrf_model: ~xarray.core.dataarray.DataArray,
y: cdt.NDTimeSeries,
geo3d: ~xarray.core.dataarray.DataArray,
ss_tresh: Quantity = <Quantity(1.5,
'centimeter')>,
)[source]

Add HRFs to optical density (OD) data in channel space.

Broadcasts the HRF model to long channels based on the source-detector distances. Short channel hrfs are filled with zeros.

Parameters:

  • hrf_model (xr.DataArray) – HRF model with dimensions [“time”, “wavelength”].

  • y (cdt.NDTimeSeries) – Raw amp / OD / Chromo timeseries data with dimensions [“channel”, “time”].

  • geo3d (xr.DataArray) – 3D coordinates of sources and detectors.

  • ss_tresh (Quantity) – Threshold for short/long channels.

Returns:

HRFs in channel space with dimensions

[“channel”, “time”, “wavelength”].

Return type:

xr.DataArray

Initial Contributors:
cedalion.sim.synthetic_hrf.get_colors(
activations: DataArray,
vertex_colors: array,
log_scale: bool = False,
max_scale: float = None,
)[source]

Maps activations to colors for visualization.

Parameters:

  • activations (xr.DataArray) – Activation values for each vertex.

  • vertex_colors (np.array) – Vertex color array of the brain mesh.

  • log_scale (bool) – Whether to map activations on a logarithmic scale.

  • max_scale (float) – Maximum value to scale the activations.

Returns:

New vertex color array with same shape as vertex_colors.

Return type:

np.array

cedalion.sim.synthetic_hrf.plot_blob(
blob_img: DataArray,
brain,
seed: int = None,
title: str = '',
log_scale: bool = False,
)[source]

Plots a blob of activity on the brain.

Parameters:

  • blob_img (xr.DataArray) – Activation values for each vertex.

  • brain (TrimeshSurface) – Brain Surface with brain mesh.

  • seed (int) – Seed vertex for the blob.

  • title (str) – Title for the plot.

  • log_scale (bool) – Whether to map activations on a logarithmic scale.

Returns:

None

Initial Contributors: