cardioception.PAT.parameters.getParameters

cardioception.PAT.parameters.getParameters(participant='SubjectTest', session='001', recorder=None, mode='relative', nTrials=28, nPractice=8, startPhases=(0, 90, 180, 270), device='keyboard', screenNb=0, fullscr=True, resultPath=None, overwrite=False, seed=None, language='english', extero=False, exteroPeriod='simulated', latencyBias=0.05, audioLead=0.05, toneFreq=1000.0, toneDuration=0.03, toneVolume=0.5, vibrationVolume=0.0, dialGainDeg=10.0, dialGainMs=25.0, wheelDirection=1, showDial=True, minToneGap=0.3, confidenceScale=None, markerStream='PAT', triggers=None, autopilot=None, beat_source=None, tone_player=None, engine=None)

Create Phase Adjustment Task parameters.

Parameters

participantstr

Participant ID.

sessionstr

Session label.

recordercardioception.devices.LSLRecorder | None

The ECG stream. Required unless extero=True. The task reads its inlet through the beat detector, so do not read from it yourself.

modestr

“relative”: the dial is a phase of the anticipated heart period, in degrees, and wraps at 360. “absolute”: the dial is a delay in ms after the R-wave, and wraps at the anticipated period.

nTrialsint

Number of main trials. The paper used 28.

nPracticeint

Number of practice trials before the main trials. The paper used 8.

startPhasessequence of float

Start phases of the dial, in degrees. Each trial starts at one of them, in blocks of a random permutation (see startPhaseSequence()).

devicestr

Confidence rating with the arrow keys (“keyboard”) or the mouse (“mouse”). The dial is the mouse wheel either way.

screenNbint

Screen number, passed to psychopy.visual.Window.

fullscrbool

If True, the window is full screen.

resultPathstr | None

Root directory holding every participant; results go to <resultPath>/sub-<participant>/ses-<session>/run-<timestamp>/. Defaults to <cwd>/data.

overwritebool

Allow writing into a run directory that already holds results.

seedint | None

Seeds the session generator, which draws the start phases, the simulated heart of the exteroceptive task, the tutorial start phase and the starting position of the confidence marker. Drawn from entropy when None, and recorded either way.

languagestr

A language in cardioception/PAT/texts, “english” or “danish” so far (cardioception.PAT.languages.available() lists them).

exterobool

If True, run the exteroceptive control task: a vibration on the hand takes the place of the heartbeat, and no ECG is needed.

exteroPeriodstr | float | sequence of float

Period of the vibration in the extero task: “simulated” (a heart period series with realistic variability, as in the PAT-ECG firmware), a fixed period in seconds, or a sequence of periods in seconds to replay.

latencyBiasfloat

Seconds subtracted from every tone target, for the delay between the R-wave and its LSL timestamp plus the speaker’s delay after the reported onset. Neither shows in the recording.

audioLeadfloat

Minimum time between scheduling a tone and its target, in seconds. A tone that cannot be scheduled that far ahead is anchored on the predicted next R-wave instead.

toneFreq, toneDuration, toneVolumefloat

The tone: frequency (Hz), duration (s) and volume (0 to 1).

vibrationVolumefloat

Volume (0 to 1) of the 50 Hz burst on the right audio channel that marks each beat of the exteroceptive task, for an amplifier and tactor on that channel. Default is 0, silent, so headphones or speakers never carry it by accident.

dialGainDegfloat

Degrees per wheel notch in relative mode.

dialGainMsfloat

Milliseconds per wheel notch in absolute mode.

wheelDirectionint

1 or -1. With 1, rolling the wheel away from you (a positive wheel step in PsychoPy, which is Windows’ forward rotation) moves the beeps later. Use -1 for a mouse or driver that reverses the wheel.

showDialbool

If True, a ring with a pointer around the fixation cross shows how far the wheel has turned since the trial began (never the phase itself), and the pointer flashes with each beep.

minToneGapfloat

A tone is skipped when its target is less than this many seconds after the previous target, so the participant never hears two tones in quick succession while turning the dial. At least toneDuration plus 0.05 s, or a tone could play late.

confidenceScaleConfidenceScale | None

How confidence is collected. None takes cardioception.scales.DISCRETE_1_10, the 1 to 10 of the paper, with the end labels of the language. A scale passed in keeps its own labels. Its ends are the numbers the instructions name.

markerStreamstr | None

Name of the LSL marker stream the task opens. Every beat, tone, dial move, press and rating is pushed to it as one JSON string, so a LabRecorder file holds the ECG and the task together. None falls back on the recorder’s own marker outlet, if it has one.

triggersdict | None

{event: callable} for the events in EVENTS, for a parallel port or another marker of your own. Checked here, so a misspelt event fails before the window opens.

autopilotPATAutopilot | None

A simulated participant (cardioception.PAT._autopilot.PATAutopilot), for headless runs. It can also be set as parameters[“autopilot”] afterwards, built on parameters[“rng”].

beat_source, tone_player

Replace the beat source (the ECG, or the virtual heart with extero=True) and the PsychPortAudio tone player, for tests and headless runs. Both must report times on the LSL clock. With beat_source no recorder is needed.

Returns

parametersdict

The settings above, plus:

• win: the PsychoPy window.

• texts: the instructions, from cardioception.PAT.languages.

• engine: the cardioception.PAT.engine.PhaseEngine that turns beats and dial moves into tones.

• outlet: the LSL marker outlet, or None.

• startPhasePractice, startPhaseMain: the start phase of each trial.

• results_df: the trial results, filled during the task.

• tones: the tone rows, filled during the task.

• rng, seed: the session generator and its seed.

• paths: the cardioception.output.SessionPaths of the run.

• path, resultPath: working and run directories.

Notes

manifest.json (the session’s settings) and session.log are written to the run directory at once. Three tab-separated files follow, each named sub-<participant>_ses-<session>_run-<timestamp>_<kind>.txt: final (one row per trial) and tones (one row per tone), rewritten after every trial, and parameters (the settings), written when the task starts. All times are LSL seconds (pylsl.local_clock), except WallTime in final, which is time.time() at the press.