psychopy.session - for running a session with multiple experiments¶Session
A Session is from which you can run multiple PsychoPy experiments, so long as they are stored within the same folder. Session uses a persistent Window and inputs across experiments, meaning that you don’t have to keep closing and reopening windows to run multiple experiments.
Through the use of multithreading, an experiment running via a Session can be sent commands and have variables changed while running. Methods of Session can be called from a second thread, meaning they don’t have to wait for runExperiment to return on the main thread. For example, you could pause an experiment after 10s like so:
``` # define a function to run in a second thread def stopAfter10s(thisSession):
# wait 10s time.sleep(10) # pause thisSession.pauseExperiment()
# create a second thread thread = threading.Thread(
target=stopAfter10s, args=(thisSession,)
) # start the second thread thread.start() # run the experiment (in main thread) thisSession.runExperiment(“testExperiment”) ```
When calling methods of Session which have the parameter blocking from outside of the main thread, you can use blocking=False to force them to return immediately and, instead of executing, add themselves to a queue to be executed in the main thread by a while loop within the start function. This is important for methods like runExperiment or setupWindowFromParams which use OpenGL and so need to be run in the main thread. For example, you could alternatively run the code above like this:
``` # define a function to run in a second thread def stopAfter10s(thisSession):
# start the experiment in the main thread thisSession.runExperiment(“testExperiment”, blocking=False) # wait 10s time.sleep(10) # pause thisSession.pauseExperiment()
# create a second thread thread = threading.Thread(
target=stopAfter10s, args=(thisSession,)
) # start the second thread thread.start() # start the Session so that non-blocking methods are executed thisSession.start() ```
root (str or pathlib.Path) – Root folder for this session - should contain all of the experiments to be run.
liaison (liaison.WebSocketServer) – Liaison server from which to receive run commands, if running via a liaison setup.
loggingLevel (str) –
’error’
’warning’
’data’
’exp’
’info’
’debug’
(‘error’ is fewest messages, ‘debug’ is most)
inputs (dict, str or None) – Dictionary of input objects for this session. Leave as None for a blank dict, or supply the name of an experiment to use the setupInputs method from that experiment.
win (psychopy.visual.Window, str or None) – Window in which to run experiments this session. Supply a dict of parameters to make a Window from them, or supply the name of an experiment to use the setupWindow method from that experiment.
experiments (dict or None) – Dict of name:experiment pairs which this Session can run. Each should be the file path of a .psyexp file, contained somewhere within the folder supplied for root. Paths can be absolute or relative to the root folder. Leave as None for a blank dict, experiments can be added later on via addExperiment().
restMsg (str) – Message to display inbetween experiments.
Add an annotation in the data file at the current point in the experiment and to the log.
Add data in the data file at the current point in the experiment, and to the log.
name (str) – Name of the column to add data as.
value (any) – Value to add
row (int or None) – Row in which to add this data. Leave as None to add to the current entry.
priority (int) – Priority value to set the column to - higher priority columns appear nearer to the start of the data file. Use values from constants.priority as landmark values: - CRITICAL: Always at the start of the data file, generally reserved for Routine start times - HIGH: Important columns which are near the front of the data file - MEDIUM: Possibly important columns which are around the middle of the data file - LOW: Columns unlikely to be important which are at the end of the data file - EXCLUDE: Always at the end of the data file, actively marked as unimportant
True if completed successfully
Register an experiment with this Session object, to be referred to later by a given key.
file (str, Path) – Path to the experiment (psyexp) file or script (py) of a Python experiment.
key (str) – Key to refer to this experiment by once added. Leave as None to use file path relative to session root.
folder (str, Path) – Folder for this project, if adding from outside of the root folder this entire folder will be moved. Leave as None to use the parent folder of file.
True if the operation completed successfully
bool or None
Add a keyboard to this session’s inputs dict from a dict of params.
name (str) – Name of this input, what to store it under in the inputs dict.
params (dict) – Dict of parameters to create the keyboard from, keys should be from the addKeyboard function in hardware.DeviceManager
blocking (bool) –
Should calling this method block the current thread?
If True (default), the method runs as normal and won’t return until completed. If False, the method is added to a queue and will be run by the while loop within Session.start. This will block the main thread, but won’t block the thread this method was called from.
If not using multithreading, this value is ignored. If you don’t know what multithreading is, you probably aren’t using it - it’s difficult to do by accident!
True if the operation completed/queued successfully
bool or None
Safely close and delete the current session.
blocking (bool) –
Should calling this method block the current thread?
If True (default), the method runs as normal and won’t return until completed. If False, the method is added to a queue and will be run by the while loop within Session.start. This will block the main thread, but won’t block the thread this method was called from.
If not using multithreading, this value is ignored. If you don’t know what multithreading is, you probably aren’t using it - it’s difficult to do by accident!
Returns all trials (elapsed, current and upcoming) with an index indicating which trial is the current trial.
list[Trial] – List of trials, in order (oldest to newest)
int – Index of the current trial in this list
Get the expInfo dict for the currently running experiment.
The expInfo for the currently running experiment, or False if no experiment is running.
dict or False
Get the value of a key (or set of keys) from the current expInfo dict.
key (str or Iterable[str]) – Key or keys to get values of fro expInfo dict
object, dict{str – If key was a string, the value of this key in expInfo. If key was a list of strings, a dict of key:value pairs for each key in the list. If no experiment is running or the process can’t complete, False.
object} or False
Returns the current trial (.thisTrial)
The current trial
Trial
Get the global-level expInfo object from one of this Session’s experiments. This will contain all of the keys needed for this experiment, alongside their default values.
Experiment info dict
Returns the condition for n trials into the future, without advancing the trials. Returns ‘None’ if attempting to go beyond the last trial in the current loop, if there is no current loop or if there is no current experiment.
Returns Trial objects for a given range in the future. Will start looking at start trials in the future and will return n trials from then, so e.g. to get all trials from 2 in the future to 5 in the future you would use start=2 and n=3.
List of Trial objects n long. Any trials beyond the last trial are None.
Get a list of device names referenced in a given experiment.
Get an overall status flag for this Session. Will be one of either:
A value psychopy.constants, either: - NOT_STARTED: If no experiment is running - STARTED: If an experiment is running - PAUSED: If an experiment is paused - FINISHED: If an experiment is in the process of terminating
Get time from this Session’s clock object.
format (type, str or None) – Can be either: - float: Time will return as a float as number of seconds - time format codes: Time will return as a string in that format, as in time.strftime - str: Time will return as a string in ISO 8601 (YYYY-MM-DD_HH:MM:SS.mmmmmmZZZZ) - None: Will use the Session clock object’s defaultStyle attribute
Time in format requested.
Function to be called continuously while a SessionQueue is idle.
True if this Session was stopped safely.
Pause the currently running experiment.
True if the operation completed successfully
bool or None
Resume the currently paused experiment.
True if the operation completed successfully
bool or None
Skip ahead n trials - the trials inbetween will be marked as “skipped”. If you try to skip past the last trial, will log a warning and skip to the last trial.
Run the setupData and run methods from one of this Session’s experiments.
key (str) – Key by which the experiment is stored (see .addExperiment).
expInfo (dict) – Information about the experiment, created by the setupExpInfo function.
blocking (bool) –
Should calling this method block the current thread?
If True (default), the method runs as normal and won’t return until completed. If False, the method is added to a queue and will be run by the while loop within Session.start. This will block the main thread, but won’t block the thread this method was called from.
If not using multithreading, this value is ignored. If you don’t know what multithreading is, you probably aren’t using it - it’s difficult to do by accident!
True if the operation completed/queued successfully
bool or None
Call .saveExperimentData on the currently running experiment - if there is one.
blocking (bool) –
Should calling this method block the current thread?
If True (default), the method runs as normal and won’t return until completed. If False, the method is added to a queue and will be run by the while loop within Session.start. This will block the main thread, but won’t block the thread this method was called from.
If not using multithreading, this value is ignored. If you don’t know what multithreading is, you probably aren’t using it - it’s difficult to do by accident!
True if the operation completed/queued successfully, False if there was no current experiment running
bool or None
Run the saveData method from one of this Session’s experiments, on a given ExperimentHandler.
key (str) – Key by which the experiment is stored (see .addExperiment).
thisExp (psychopy.data.ExperimentHandler) – ExperimentHandler object to save the data from. If None, save the last run of the given experiment.
blocking (bool) –
Should calling this method block the current thread?
If True (default), the method runs as normal and won’t return until completed. If False, the method is added to a queue and will be run by the while loop within Session.start. This will block the main thread, but won’t block the thread this method was called from.
If not using multithreading, this value is ignored. If you don’t know what multithreading is, you probably aren’t using it - it’s difficult to do by accident!
True if the operation completed/queued successfully
bool or None
Send last ExperimentHandler for an experiment to liaison. If no experiment is given, sends the currently running experiment.
Send data to this Session’s Liaison object.
value (str, dict, psychopy.data.ExperimentHandler) – Data to send - this can either be a single string, a dict of strings, or an ExperimentHandler (whose data will be sent)
True if the operation completed successfully
bool or None
Set the value of a key (or set of keys) from the current expInfo dict.
True if operation completed successfully
Setup inputs for this Session via the ‘setupInputs` method from one of this Session’s experiments.
key (str) – Key by which the experiment is stored (see .addExperiment).
expInfo (dict) – Information about the experiment, created by the setupExpInfo function.
thisExp (psychopy.data.ExperimentHandler) – Handler object for this experiment, contains the data to save and information about where to save it to.
blocking (bool) –
Should calling this method block the current thread?
If True (default), the method runs as normal and won’t return until completed. If False, the method is added to a queue and will be run by the while loop within Session.start. This will block the main thread, but won’t block the thread this method was called from.
If not using multithreading, this value is ignored. If you don’t know what multithreading is, you probably aren’t using it - it’s difficult to do by accident!
True if the operation completed/queued successfully
bool or None
Deprecated: legacy alias of setupDevicesFromExperiment
Setup the window for this Session via the ‘setupWindow` method from one of this Session’s experiments.
key (str) – Key by which the experiment is stored (see .addExperiment).
expInfo (dict) – Information about the experiment, created by the setupExpInfo function.
blocking (bool) –
Should calling this method block the current thread?
If True (default), the method runs as normal and won’t return until completed. If False, the method is added to a queue and will be run by the while loop within Session.start. This will block the main thread, but won’t block the thread this method was called from.
If not using multithreading, this value is ignored. If you don’t know what multithreading is, you probably aren’t using it - it’s difficult to do by accident!
True if the operation completed/queued successfully
bool or None
Create/setup a window from a dict of parameters
params (dict) – Dict of parameters to create the window from, keys should be from the __init__ signature of psychopy.visual.Window
measureFrameRate (bool) – If True, will measure frame rate upon window creation.
blocking (bool) –
Should calling this method block the current thread?
If True (default), the method runs as normal and won’t return until completed. If False, the method is added to a queue and will be run by the while loop within Session.start. This will block the main thread, but won’t block the thread this method was called from.
If not using multithreading, this value is ignored. If you don’t know what multithreading is, you probably aren’t using it - it’s difficult to do by accident!
True if the operation completed/queued successfully
bool or None
Update expInfo for this Session via the ‘showExpInfoDlg` method from one of this Session’s experiments.
Skip ahead n trials - the trials inbetween will be marked as “skipped”. If you try to skip past the last trial, will log a warning and skip to the last trial.
n (int) – Number of trials to skip ahead
Start this Session running its queue. Not recommended unless running across multiple threads.
True if this Session was started safely.
Stop this Session running the queue. Not recommended unless running across multiple threads.
Stop the currently running experiment.
True if the operation completed successfully
bool or None
Update key:value pairs in the current expInfo dict from another dict.
Window associated with this Session. Defined as a property so as to be accessible from Liaison if needed.