respyra.core.data_logger

Incremental CSV data logger for breath-belt experiments.

Writes one row per sample/event, flushing after every write so that data survives crashes. No pandas, no heavy abstractions – just csv.writer with immediate flush.

Usage

from respyra.core.data_logger import create_session_file, DataLogger

filepath = create_session_file(“01”) with DataLogger(filepath) as log:

log.log_sample(timestamp=0.016, frame=1, force_n=3.21) log.log_sample(timestamp=1.234, frame=74, event_type=”keypress”,

key=”space”, rt=0.456)

respyra.core.data_logger.create_session_file(participant_id, session='001', output_dir='data/')

Create an output directory (if needed) and return a unique CSV path.

Parameters:

• participant_id (str) – Participant identifier (e.g. "01"). Will be zero-padded to two digits if a bare integer string is supplied.

• session (str, optional) – Session label, default "001".

• output_dir (str, optional) – Directory for data files, default "data/".

Returns:

Absolute-ish filepath like data/sub-01_ses-001_2026-02-24_143022.csv. The embedded timestamp prevents accidental overwrites.

Return type:

str

class respyra.core.data_logger.DataLogger(filepath, columns=None)

Bases: object

Incremental CSV writer that flushes every row.

Parameters:

• filepath (str) – Path to the CSV file (created / overwritten on init).

• columns (list[str] | None) – Header column names. Falls back to DEFAULT_COLUMNS when None.

log_row(**kwargs)

Append a row using keyword arguments matched to column names.

Any column not present in kwargs is written as an empty string. This is the generic counterpart to log_sample() — use it when your experiment needs a custom column schema.

Parameters:

**kwargs – Keyword arguments whose keys must match column names passed at init (or DEFAULT_COLUMNS). Unrecognised keys are silently ignored; missing columns are written as empty strings.

Return type:

None

log_sample(timestamp, frame, force_n=None, event_type=None, key=None, rt=None)

Append a single row and flush to disk.

Parameters:

• timestamp (float) – Time in seconds (from experiment clock).

• frame (int) – Frame counter.

• force_n (float | None) – Force reading in newtons from the breath belt.

• event_type (str | None) – Event label, e.g. "keypress", "trial_start".

• key (str | None) – Key name if this row records a keypress.

• rt (float | None) – Reaction time in seconds, if applicable.

Return type:

None

close()

Flush remaining buffer and close the file handle.

Return type:

None