rtcog.viz package

Submodules

rtcog.viz.esam_streaming module

class rtcog.viz.esam_streaming.ESAMStreamer(config: StreamingConfig, sync_events: SyncEvents, action_onsets: ListProxy, action_offsets: ListProxy, responses: DictProxy)

Bases: object

Streamer for realtime fMRI data visualization.

This class receives shared memory updates and streams the data live using a Panel server. It streams three plots:

• ScorePlotter (match scores)

• MapPlotter (activation maps)

• ResponsePlotter (behavioral responses)

Parameters:

• config (StreamingConfig) – Configuration object containing information about the fMRI session.

• sync_events (SyncEvents) – Object that handles interprocess synchronization flags and signals.

• action_onsets (ListProxy) – Shared list storing the TR indices of action onsets (trial starts).

• action_offsets (ListProxy) – Shared list storing the TR indices of action offsets (trial ends).

• responses (DictProxy) – Shared dictionary containing responses collected during the experiment.

property action_state: ActionState

Construct and return the current ActionState.

Returns:

An object encapsulating current trial timing state.

Return type:

ActionState

property in_cooldown: bool

Check whether the streamer is currently in a post-trial cooldown period.

Returns:

True if in cooldown, False otherwise.

Return type:

bool

run() → None

Start the background update thread and launch the Panel visualization server.

update() → None

Method run in a background thread to stream new data.

Waits for new TRs and passes the appropriate data to each plotter.

rtcog.viz.esam_streaming.run_streamer(streamer_config, sync_events, action_onsets, action_offsets, responses) → None

Instantiate streamer object and start thread.

rtcog.viz.map_plotter module

class rtcog.viz.map_plotter.MapPlotter(config: StreamingConfig)

Bases: Plotter

Plot brain activation maps when each ‘hit’ occurs.

This class generates brain plots using data masked by a mask image. It updates the plot only when a new action onset is detected.

close()

Close the matplotlib figure to release resources.

data_key: str = 'tr_data'

should_update(t: int, action_state: ActionState) → bool

True if a hit occured at the current t.

update(t: int, data: numpy.ndarray, action_state: ActionState) → None

Update the brain plot if a new action onset (hit) is detected.

rtcog.viz.plotter module

class rtcog.viz.plotter.Plotter(config: StreamingConfig)

Bases: ABC

Abstract base class for real-time fMRI plotters.

Subclasses should implement specific plotting behavior using the update() method, and may optionally override close() for cleanup at the end of the experiment.

data_key

Identifier for the type of data this plotter displays.

Type:

str

close()

Optional cleanup at the end of the experiment.

Subclasses can override this method to release resources or finalize output.

data_key: str = None

should_update(t: int, action_state: ActionState) → bool

Whether or not the plot should be updated. By default, it will always update.

Parameters:

• t (int) – Current TR.

• action_state (ActionState) – The current state of an action block during the experiment.

Returns:

Whether the plot should be updated.

Return type:

bool

abstract update(t: int, data: numpy.ndarray, action_state: ActionState) → None

Update the plot with new data for the current time repetition (TR).

Parameters:

• t (int) – Current TR.

• data (np.ndarray) – Data to be visualized (format depends on subclass).

• action_state (ActionState) – The current state of an action block during the experiment.

rtcog.viz.response_plotter module

class rtcog.viz.response_plotter.ResponsePlotter(config: StreamingConfig, responses: DictProxy)

Bases: Plotter

Display participant responses over time in a dynamic DataFrame panel.

This class extends the Plotter base class to visualize responses collected during an fMRI scan.

data_key: str = 'responses'

should_update(t, action_state)

True if the current t is the end of a question/response block.

update(t: int, data: numpy.ndarray, action_state: ActionState) → None

Update the response DataFrame with the latest responses.

rtcog.viz.score_plotter module

class rtcog.viz.score_plotter.ScorePlotter(config: StreamingConfig, streaming=True)

Bases: Plotter

Live and post-hoc visualization of template matching scores.

This plotter receives template matching scores over time and visualizes them as streaming line plots. It overlays action-related annotations including hit thresholds, action windows, cooldown periods, and hit markers indicating the strongest-matching template at action onset times.

The plot can be rendered dynamically during acquisition or saved as a static HTML report at the end of the experiment.

close()

Save the final state of the plot to an HTML file.

data_key: str = 'scores'

render_static(df: pandas.DataFrame, action_state: ActionState) → holoviews.Overlay

Render a static score plot after the experiment has completed.

Parameters:

• df (pd.DataFrame) – Full score DataFrame indexed by time and template.

• action_state (ActionState) – Final action state containing all action intervals.

Returns:

Rendered plot overlay.

Return type:

hv.Overlay

update(t: int, data: numpy.ndarray, action_state: ActionState) → None

Update the plot with new score data at a given time point.

Parameters:

• t (int) – TR corresponding to the incoming scores.

• data (np.ndarray) – Array of template matching scores at time t. Must align with the template label order.

• action_state (ActionState) – Current action state containing action onsets, offsets, and cooldown info.

rtcog.viz.streaming_config module

class rtcog.viz.streaming_config.StreamingConfig(Nt: int, template_labels: List[str], hit_thr: float, matching_opts: MatchingOpts, mask_img: nibabel.nifti1.Nifti1Image, Nv: int, out_dir: str, out_prefix: str)

Bases: object

Configuration container for real-time fMRI data streaming and matching.

Nt: int

Nv: int

hit_thr: float

mask_img: nibabel.nifti1.Nifti1Image

matching_opts: MatchingOpts

out_dir: str

out_prefix: str

template_labels: List[str]

Module contents