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

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.