cedalion.sim.synthetic_hrf

Functions for generating synthetic hemodynamic response functions.

Functions

build_spatial_activation(head_model, seed_vertex)

Generates a spatial activation at a seed vertex.

build_stim_df(max_time[, max_num_stims, ...])

Generates a DataFrame for stimulus metadata based on provided parameters.

build_synthetic_hrf_timeseries(ts, stim_df, ...)

Builds a synthetic HRF timeseries based on the provided data.

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

Maps activations to colors for visualization.

plot_spatial_activation(spatial_img, brain)

Plots a spatial activation pattern on the brain surface.
cedalion.sim.synthetic_hrf.build_spatial_activation(
head_model: cfm.TwoSurfaceHeadModel,
seed_vertex: int,
spatial_scale: cdt.QLength = <Quantity(1,
'centimeter')>,
intensity_scale: cdt.QConcentration = <Quantity(1,
'micromolar')>,
hbr_scale: float = None,
m: float = 10.0,
)[source]

Generates a spatial activation at a seed vertex.

This function generates a blob of activity on the brain surface. The blob is centered at the seed vertex. Geodesic distances, and therefore also the blob, can be distorded due to mesh decimation or unsuitable m value.

Parameters:

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

  • seed_vertex (int) – Index of the seed vertex.

  • spatial_scale (Quantity) – Scale of the spatial size.

  • intensity_scale (Quantity) – Scaling factor for the intensity of the blob.

  • hbr_scale (float) – Scaling factor for HbR relative to HbO. If None, the blob will have no concentration dimension and only represent HbO.

  • 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:

Spatial image with activation values for each vertex.

Return type:

xr.DataArray

Initial Contributors:
cedalion.sim.synthetic_hrf.build_stim_df(max_time: cdt.QTime, max_num_stims: int | None = None, trial_types: list[str] = ['Stim'], min_stim_dur: cdt.QTime = <Quantity(10, 'second')>, max_stim_dur: cdt.QTime = <Quantity(10, 'second')>, min_interval: cdt.QTime = <Quantity(10, 'second')>, max_interval: cdt.QTime = <Quantity(30, 'second')>, min_stim_value: float = 1.0, max_stim_value: float = 1.0, 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:

  • max_time (Quantity) – Maximum total duration for the stimuli.

  • max_num_stims (int) – Maximum number of stimuli to be added for each trial type.

  • trial_types (list) – List of different trial types.

  • min_stim_dur (Quantity) – Minimum duration of the stimulus.

  • max_stim_dur (Quantity) – Maximum duration of the stimulus.

  • min_interval (Quantity) – Minimum inter-stimulus interval.

  • max_interval (Quantity) – Maximum inter-stimulus interval.

  • min_stim_value (float) – Minimum amplitude-value of the stimulus.

  • max_stim_value (float) – Maximum amplitude-value of the stimulus.

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

Returns:

DataFrame containing stimulus metadata.

Return type:

pd.DataFrame

Initial Contributors:
cedalion.sim.synthetic_hrf.build_synthetic_hrf_timeseries(
ts: cdt.NDTimeSeries,
stim_df: DataFrame,
basis_fct: TemporalBasisFunction,
spatial_pattern: DataArray,
)[source]

Builds a synthetic HRF timeseries based on the provided data.

Parameters:

  • ts (cdt.NDTimeSeries) – Timeseries data.

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

  • basis_fct (TemporalBasisFunction) – Temporal basis function defining the HRF.

  • spatial_pattern (xr.DataArray) – Spatial activation pattern (intensity scaling for each vertex/channel and trial type).

Returns:

Synthetic HRF timeseries.

Return type:

cdt.NDTimeSeries

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_spatial_activation(
spatial_img: DataArray,
brain: TrimeshSurface,
seed: int = None,
title: str = '',
log_scale: bool = False,
)[source]

Plots a spatial activation pattern on the brain surface.

Parameters:

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

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

  • seed (int) – Seed vertex for the activation pattern.

  • title (str) – Title for the plot.

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

Returns:

None

Initial Contributors: