cedalion.sim.synthetic_artifact

Functions for generating synthetic artifacts in fNIRS data.

Functions

`add_artifact_direct`(ts, timing, artifact_func)	Add a single artifact to a timeseries with direct scaling (mainly for testing).
`add_artifacts`(ts, timing, artifacts[, mode, ...])	Add scaled artifacts to timeseries data.
`add_chromo_artifacts_2_od`(od, timing, ...[, ...])	Scale artifacts by chromo amplitudes and add to OD data.
`add_event_timing`(events, type[, channels, ...])	Add event data to the timing DataFrame, or creates a new one if not provided.
`gen_bl_shift`(time, onset_time[, duration])	Generate a baseline shift artifact.
`gen_spike`(time, onset_time, duration)	Generate a basic spike artifact.
`random_events_num`(time, num_events, types[, ...])	Generates timing data for random events.
`random_events_perc`(time, perc_events, types)	Generates timing data for random events.
`sel_chans_by_opt`(optodes, ts)	Returns list of channels involving selected optodes.

Classes

ArtifactFunction(*args, **kwargs)

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.