psychopy.session - for running a session with multiple experiments

Session

class psychopy.session.Session(root, dataDir=None, clock='iso', win=None, experiments=None, loggingLevel='info', priorityThreshold=-9, params=None, liaison=None, restMsg='Rest...')[source]

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() ```

Parameters:
  • 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) –

    How much output do you want in the log files? Should be one of the following:
    • ’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.

addAnnotation(value)[source]

Add an annotation in the data file at the current point in the experiment and to the log.

Parameters:

value (str) – Value of the annotation

Returns:

True if completed successfully

Return type:

bool

addData(name, value, row=None, priority=None)[source]

Add data in the data file at the current point in the experiment, and to the log.

Parameters:
  • 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

Returns:

True if completed successfully

Return type:

bool

addExperiment(file, key=None, folder=None)[source]

Register an experiment with this Session object, to be referred to later by a given key.

Parameters:
  • 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.

Returns:

True if the operation completed successfully

Return type:

bool or None

addKeyboardFromParams(name, params, blocking=True)[source]

Add a keyboard to this session’s inputs dict from a dict of params.

Parameters:
  • 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!

Returns:

True if the operation completed/queued successfully

Return type:

bool or None

close(blocking=True)[source]

Safely close and delete the current session.

Parameters:

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!

getAllTrials()[source]

Returns all trials (elapsed, current and upcoming) with an index indicating which trial is the current trial.

Returns:

  • list[Trial] – List of trials, in order (oldest to newest)

  • int – Index of the current trial in this list

getCurrentExpInfo()[source]

Get the expInfo dict for the currently running experiment.

Returns:

The expInfo for the currently running experiment, or False if no experiment is running.

Return type:

dict or False

getCurrentExpInfoItem(key)[source]

Get the value of a key (or set of keys) from the current expInfo dict.

Parameters:

key (str or Iterable[str]) – Key or keys to get values of fro expInfo dict

Returns:

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.

Return type:

object} or False

getCurrentTrial(asDict=False)[source]

Returns the current trial (.thisTrial)

Returns:

The current trial

Return type:

Trial

getExpInfoFromExperiment(key, sessionParams=True)[source]

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.

Parameters:
  • key (str) – Key by which the experiment is stored (see .addExperiment).

  • sessionParams (bool) – Should expInfo be extended with params from the Session, overriding experiment params where relevant (True, default)? Or return expInfo as it is in the experiment (False)?

Returns:

Experiment info dict

Return type:

dict

getFrameRate(retest=False)[source]

Get the frame rate from the window.

Parameters:

retest (bool) – If True, then will always run the frame rate test again, even if measured frame rate is already available.

Returns:

Frame rate retrieved from Session window.

Return type:

float

getFutureTrial(n=1, asDict=False)[source]

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.

Parameters:
  • n (int) – Number of places into the future to look

  • asDict (bool) – If True, convert Trial object to a dict before returning (useful for Liaison)

getFutureTrials(n=1, start=0, asDict=False)[source]

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.

Parameters:
  • n (int, optional) – How many trials into the future to look, by default 1

  • start (int, optional) – How many trials into the future to start looking at, by default 0

  • asDict (bool) – If True, convert Trial objects to a dict before returning (useful for Liaison)

Returns:

List of Trial objects n long. Any trials beyond the last trial are None.

Return type:

list[Trial or dict or None]

getRequiredDeviceNamesFromExperiment(key)[source]

Get a list of device names referenced in a given experiment.

Parameters:

key (str) – Key by which the experiment is stored (see .addExperiment).

Returns:

List of device names

Return type:

list[str]

getStatus()[source]

Get an overall status flag for this Session. Will be one of either:

Returns:

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

Return type:

int

getTime(format=<class 'str'>)[source]

Get time from this Session’s clock object.

Parameters:

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

Returns:

Time in format requested.

Return type:

str or float

onIdle()[source]

Function to be called continuously while a SessionQueue is idle.

Returns:

True if this Session was stopped safely.

Return type:

bool

pauseExperiment()[source]

Pause the currently running experiment.

Returns:

True if the operation completed successfully

Return type:

bool or None

resumeExperiment()[source]

Resume the currently paused experiment.

Returns:

True if the operation completed successfully

Return type:

bool or None

rewindTrials(n=1)[source]

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.

Parameters:

n (int) – Number of trials to skip ahead

Returns:

True if the operation completed/queued successfully

Return type:

bool or None

runExperiment(key, expInfo=None, blocking=True)[source]

Run the setupData and run methods from one of this Session’s experiments.

Parameters:
  • 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!

Returns:

True if the operation completed/queued successfully

Return type:

bool or None

saveCurrentExperimentData(blocking=True)[source]

Call .saveExperimentData on the currently running experiment - if there is one.

Parameters:

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:

True if the operation completed/queued successfully, False if there was no current experiment running

Return type:

bool or None

saveExperimentData(key, thisExp=None, blocking=True)[source]

Run the saveData method from one of this Session’s experiments, on a given ExperimentHandler.

Parameters:
  • 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!

Returns:

True if the operation completed/queued successfully

Return type:

bool or None

sendExperimentData(key=None)[source]

Send last ExperimentHandler for an experiment to liaison. If no experiment is given, sends the currently running experiment.

Parameters:

key (str or None) – Name of the experiment whose data to send, or None to send the current experiment’s data.

Returns:

True if data was sent, otherwise False

Return type:

bool

sendToLiaison(value)[source]

Send data to this Session’s Liaison object.

Parameters:

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)

Returns:

True if the operation completed successfully

Return type:

bool or None

setCurrentExpInfoItem(key, value)[source]

Set the value of a key (or set of keys) from the current expInfo dict.

Parameters:
  • key (str or Iterable[str]) – Key or list of keys whose value or values to set.

  • value (object or Iterable[str]) – Value or values to set the key to. If one value is given along with multiple keys, all keys will be set to that value. Otherwise, the number of values should match the number of keys.

Returns:

True if operation completed successfully

Return type:

bool

setupDevicesFromExperiment(key, expInfo=None, thisExp=None, blocking=True)[source]

Setup inputs for this Session via the ‘setupInputs` method from one of this Session’s experiments.

Parameters:
  • 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!

Returns:

True if the operation completed/queued successfully

Return type:

bool or None

setupInputsFromExperiment(key, expInfo=None, thisExp=None, blocking=True)[source]

Deprecated: legacy alias of setupDevicesFromExperiment

setupWindowFromExperiment(key, expInfo=None, blocking=True)[source]

Setup the window for this Session via the ‘setupWindow` method from one of this Session’s experiments.

Parameters:
  • 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!

Returns:

True if the operation completed/queued successfully

Return type:

bool or None

setupWindowFromParams(params, measureFrameRate=False, blocking=True)[source]

Create/setup a window from a dict of parameters

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!

Returns:

True if the operation completed/queued successfully

Return type:

bool or None

showExpInfoDlgFromExperiment(key, expInfo=None)[source]

Update expInfo for this Session via the ‘showExpInfoDlg` method from one of this Session’s experiments.

Parameters:
  • key (str) – Key by which the experiment is stored (see .addExperiment).

  • expInfo (dict) – Information about the experiment, created by the setupExpInfo function.

Returns:

True if the operation completed successfully

Return type:

bool or None

skipTrials(n=1)[source]

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.

Parameters:

n (int) – Number of trials to skip ahead

start()[source]

Start this Session running its queue. Not recommended unless running across multiple threads.

Returns:

True if this Session was started safely.

Return type:

bool

stop()[source]

Stop this Session running the queue. Not recommended unless running across multiple threads.

stopExperiment()[source]

Stop the currently running experiment.

Returns:

True if the operation completed successfully

Return type:

bool or None

updateCurrentExpInfo(other)[source]

Update key:value pairs in the current expInfo dict from another dict.

Parameters:

other (dict) – key:value pairs to update dict from.

Returns:

True if operation completed successfully

Return type:

bool

property win

Window associated with this Session. Defined as a property so as to be accessible from Liaison if needed.


Back to top