respyra.utils.vis.plot_session

Post-session visualization for the breath tracking task.

Generates a 6-panel summary figure from a session CSV file, helping experimenters evaluate participant performance and verify task operation.

Usage

python -m respyra.utils.vis.plot_session data/sub-01_ses-001_2026-02-24.csv python -m respyra.utils.vis.plot_session data/*.csv –no-show

The figure is saved as {csv_stem}_summary.png alongside the CSV.

respyra.utils.vis.plot_session.load_session(csv_path)

Read a session CSV, coerce column types, and add monotonic session time.

Parameters:

csv_path (str) – Path to a CSV file produced by respyra.core.data_logger.DataLogger.

Returns:

DataFrame sorted by (trial_num, phase_order, timestamp) with an additional session_time column providing monotonic elapsed time across phase boundaries.

Return type:

pd.DataFrame

respyra.utils.vis.plot_session.compute_trial_stats(df)

Compute per-trial summary statistics from the tracking phase.

Parameters:

df (pd.DataFrame) – Session dataframe as returned by load_session().

Returns:

One row per trial with columns: trial_num, condition, mae (mean absolute error in Newtons), mae_sd, rmse, and n_samples. Empty if no tracking data exists.

Return type:

pd.DataFrame

respyra.utils.vis.plot_session.compute_baseline_cal(df)

Compute per-trial baseline calibration (center and amplitude).

Parameters:

df (pd.DataFrame) – Session dataframe as returned by load_session().

Returns:

One row per trial with columns: trial_num, condition, force_min, force_max, force_mean, center (midpoint of min/max), and amplitude (half-range, minimum 0.5 N). Empty if no baseline data exists.

Return type:

pd.DataFrame

respyra.utils.vis.plot_session.plot_session(df, csv_path)

Create a 6-panel summary figure for one session.

Panels: (1) full session force trace with target overlay, (2) signed tracking error per trial, (3) per-trial MAE bar chart, (4) error distribution by condition, (5) baseline calibration stability, (6) summary statistics text.

Parameters:

• df (pd.DataFrame) – Session dataframe as returned by load_session().

• csv_path (str) – Original CSV path, used for the figure title.

Returns:

The completed figure (not yet saved or shown).

Return type:

matplotlib.figure.Figure

respyra.utils.vis.plot_session.main()

CLI entry point: parse arguments and generate summary figures.

Processes one or more session CSV files, saving each as {csv_stem}_summary.png alongside the original.

Return type:

None