cedalion.sim package

Submodules

cedalion.sim.synthetic_artifact module

Functions for generating synthetic artifacts in fNIRS data.

class cedalion.sim.synthetic_artifact.ArtifactFunction(*args, **kwargs)[source]

Bases: Protocol

cedalion.sim.synthetic_artifact.gen_spike(
time: DataArray,
onset_time: float,
duration: float,
) → DataArray[source]

Generate a basic spike artifact.

Shape is a Gaussian centered at onset_time with amplitude = 1 and standard deviation = duration.

Parameters:

  • time – Time axis to which the spike will be added.

  • onset_time – Center of the spike.

  • duration – Standard deviation of the spike.

Returns:

DataFrame with event timing data (columns onset_time, duration, trial_type, value, channel).

cedalion.sim.synthetic_artifact.gen_bl_shift(
time: DataArray,
onset_time: float,
duration: float = 0,
) → DataArray[source]

Generate a baseline shift artifact.

Parameters:

  • time – Time axis to which the baseline shift will be added.

  • onset_time – Onset of the baseline shift.

  • duration – Duration of the baseline shift (has no effect).

Returns:

DataFrame with event timing data (columns onset_time, duration, trial_type, value, channel).

cedalion.sim.synthetic_artifact.add_event_timing(
events: list[tuple[float, float]],
type: str,
channels: list[str] | None = None,
timing: DataFrame | None = None,
) → DataFrame[source]

Add event data to the timing DataFrame, or creates a new one if not provided.

Parameters:

  • events – List of tuples in format (onset, duration)

  • type – Type of the event batch.

  • channels – List of channels to which the event batch applies.

  • timing – DataFrame of events.

Returns:

Updated timing DataFrame.

cedalion.sim.synthetic_artifact.sel_chans_by_opt(optodes: list[str], ts: cdt.NDTimeSeries) → list[str][source]

Returns list of channels involving selected optodes.

cedalion.sim.synthetic_artifact.random_events_num(
time: DataArray,
num_events: int,
types: list[str],
channels: list[str] | None = None,
)[source]

Generates timing data for random events.

Events are randomly selected from the types list and assigned random onset/duration within the time series.

Parameters:

  • time – Time series to which the events are added.

  • num_events – Number of events to generate.

  • types – List of event types.

  • channels – List of channels to which the events apply.

Returns:

DataFrame with event timing data (columns onset_time, duration, trial_type, value, channel).

cedalion.sim.synthetic_artifact.random_events_perc(
time: DataArray,
perc_events: float,
types: list[str],
channels: list[str] | None = None,
min_dur: float = 0.1,
max_dur: float = 0.4,
timing: DataFrame | None = None,
) → DataFrame[source]

Generates timing data for random events. Mainly intended for spike artifacts.

Events are randomly selected from the types list and assigned random onset/duration within the time series.

Parameters:

  • time – Time series to which the events are added.

  • perc_events – Percentage of time series to cover with events.

  • types – List of event types.

  • channels – List of channels to which the events apply.

  • min_dur – Minimum duration of the events.

  • max_dur – Maximum duration of the events.

  • timing (optional) – DataFrame with existing event timing data.

Returns:

DataFrame with event timing data (columns onset_time, duration, trial_type, value, channel).

cedalion.sim.synthetic_artifact.add_artifact_direct(
ts: cdt.NDTimeSeries,
timing: tuple[float, float],
artifact_func,
scale: float = 1.0,
)[source]

Add a single artifact to a timeseries with direct scaling (mainly for testing).

Parameters:

  • ts – timeseries data

  • timing – Tuple with onset time, duration of the artifact.

  • artifact_func – Artifact function. Artifact function must take args (time).

  • scale – scale for artifact.

Returns:

Timeseries data with added artifact.

cedalion.sim.synthetic_artifact.add_artifacts(
ts: cdt.NDTimeSeries,
timing: DataFrame,
artifacts: dict[str, ArtifactFunction],
mode: str = 'auto',
scale: float = 1.0,
window_size: float = 120,
) → cdt.NDTimeSeries[source]

Add scaled artifacts to timeseries data.

Supports timeseries with channel and either wavelength or chromophore dimension. Currently assumes that artifacts affect both wavelengths/chromophores equally.

Parameters:

  • ts – fNIRS timeseries data (i.e. amp or OD).

  • timing – DataFrame with event timing data (columns onset_time, duration, trial_type, value, channel).

  • artifacts – Dictionary of artifact functions. Artifact functions must take args (time, onset_time, duration). Keys correspond to the trial_type in the timing DataFrame.

  • mode – ‘auto’ or ‘manual’. If ‘auto’, artifacts are scaled using the alpha parameter (median of median of sliding windows) AND the scale parameter. If ‘manual’, artifacts are scaled only by the scale parameter.

  • scale – scaling parameter for artifacts

  • window_size – size of sliding window for alpha computation

Returns:

Amplitude data with added artifacts.

cedalion.sim.synthetic_artifact.add_chromo_artifacts_2_od(
od: cdt.NDTimeSeries,
timing: DataFrame,
artifacts,
geo3d,
dpf,
scale: float = 1.0,
window_size: float = 120,
)[source]

Scale artifacts by chromo amplitudes and add to OD data.

cedalion.sim.synthetic_hrf module

Functions for generating synthetic hemodynamic response functions.

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:

cedalion.sim.synthetic_utils module

cedalion.sim.synthetic_utils.add_event_timing(
events: list[tuple[float, float]] | list[tuple[float, float, float]],
type: str,
channels: list[str] | None = None,
timing: DataFrame | None = None,
) → DataFrame[source]

Add event data to the timing DataFrame, or creates a new one if not provided.

Parameters:

  • events – List of tuples in format (onset, duration) or (onset, duration, value).

  • type – Type of the event batch.

  • channels – List of channels to which the event batch applies.

  • timing – DataFrame of events.

Returns:

Updated timing DataFrame.

cedalion.sim.synthetic_utils.build_event_df(time_axis: ~xarray.core.dataarray.DataArray, trial_types: ~typing.List[str], num_events: int | None = None, perc_events: float | None = None, min_dur: ~pint.Annotated[~pint.Quantity, '[time]'] = <Quantity(10, 'second')>, max_dur: ~pint.Annotated[~pint.Quantity, '[time]'] = <Quantity(10, 'second')>, min_interval: ~pint.Annotated[~pint.Quantity, '[time]'] = None, min_value: float = 1.0, max_value: float = 1.0, order: str = 'random', channels: ~typing.List[str] | None = None, max_attempts: int = 10000) → DataFrame[source]

Build a DataFrame of events given a time axis and event generation parameters.

This function generalizes event generation for both HRF-like and artifact-like scenarios.

Parameters:

  • time_axis (xr.DataArray) – The time axis of the data.

  • trial_types (List[str]) – List of trial types to draw from.

  • num_events (int, optional) – Number of events to generate.

  • perc_events (float, optional) – Percentage of total time to cover with events.

  • min_dur (Quantity) – Minimum event duration.

  • max_dur (Quantity) – Maximum event duration.

  • min_interval (Quantity) – Minimum interval between events.

  • min_value (float) – Minimum event amplitude.

  • max_value (float) – Maximum event amplitude.

  • order (str) – Order of types (‘alternating’, ‘random’, or ‘random balanced’). Alternating will cycle through trial types. Random will randomly assign trial types. Random balanced will randomly assign trial types, but each type will be assigned the same number of times (if possible).

  • channels (List[str], optional) – List of channel names to add events to.

  • max_attempts (int) – Maximum number of attempts to place events.

Returns:

DataFrame containing stimulus metadata. Columns are:

  • onset: Event onset time.

  • duration: Event duration.

  • value: Event amplitude.

  • trial_type: Event trial type.

  • channel: Event channel (if provided).

Return type:

df (pd.DataFrame)

cedalion.sim.synthetic_utils.overlaps(onset, dur, min_interval, existing_events)[source]
cedalion.sim.synthetic_utils.pick_trial_types(
df: DataFrame,
trial_types: list[str],
order: str,
) → list[str][source]

Module contents

Tools for creating synthetic data.