cedalion.sim.synthetic_hrf

Functions for generating synthetic hemodynamic response functions.

Functions

build_spatial_activation(surface, seed_vertices)

Generates a spatial activation at one or multiple seed vertices.

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.

Classes

RandomGaussianSum(t_start, t_end, t_delta, t_std)

A single HRF composed of Gaussians with time-dependent random weights.
cedalion.sim.synthetic_hrf.build_spatial_activation(
surface: cdg.TrimeshSurface,
seed_vertices: list[int] | 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 one or multiple seed vertices.

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:

  • surface (cdg.TrimeshSurface) – Brain or scalp surface.

  • seed_vertices (list[int] | int) – Indices of the seed vertices.

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

  • m (float) – Geodesic distance parameter.

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:
class cedalion.sim.synthetic_hrf.RandomGaussianSum(
t_start: cdt.QTime,
t_end: cdt.QTime,
t_delta: cdt.QTime,
t_std: cdt.QTime,
weight_std_max: float = 0.5,
weight_std_min: float = 0.05,
weight_mean: float = 0.7,
seed: int | None = None,
)[source]

Bases: TemporalBasisFunction

A single HRF composed of Gaussians with time-dependent random weights.