Function Help

This reference provides detailed documentation for all the functions in Psychopy Tools.

psychopy_tools.presentation: Presentation Functions

Functions typically used when running the presentation script.

psychopy_tools.presentation.clean_up(window, serial=None, labjack=None, data_files=None)[source]

Safer close function on premature experiment quit designed to gracefully close datafiles and devices. Minimum requires a window to close, but can also close: a serial object (typically one created to collect fMRI triggers), a labjack object (typically one created to trigger biopac/psychophys trigger), and a list of data_files (typically opened with Python’s ‘open’).

Note: Sometimes psychopy will issue a crash message when prematurely quitting. This is nothing to worry about.

Parameters:
  • window – window handle from psychopy script
  • serial – scanner trigger serial object instance
  • labjack – labjack (psychophys) object instance
  • data_files – list of data files

Examples

This function is designed to be used as Psychopy global key function for example:

>>> from psychopy_tools.presentation import clean_up

Then later in your script after window creation:

>>> # Close window only
>>> event.globalKeys.add(key='q',func=clean_up, name='shutdown',func_args=(window))

Or embedded within a while loop:

>>> while True:
>>>    # do something
>>>
>>>    # But be able to quit while in the loop
>>>    if len(event.getKeys(['q'])):
>>>        # Close window, devices and data files
>>>        clean_up(window,scanner,biopac,data_files)
psychopy_tools.presentation.draw_scale_only(self)[source]

DEPRECATED Use psychopy_tools.rating.RatingScale which has this method built-in.

Convenience method to only draw a visual.RatingScale scale, but not collect a rating.

Examples

Use this by augmenting an already existing Psychopy visual.RatingScale instance:

>>> # First we need a Python function to make this "method-able"
>>> from types import MethodType
>>>
>>> # Then create your scale as you normally would
>>> myScale = visual.RatingScale(...)
>>>
>>> # Then add this as a new method to the instance
>>> myScale.draw_only = MethodType(draw_scale_only,myScale)
>>>
>>> # Use it just like you would have used .draw()
>>> myScale.draw_only()
psychopy_tools.presentation.wait_for_click(self)[source]

Similar to event.waitKeys(), but waits for a mouse click. Specifically waits for the press and release of a mouse click. Agnostic to which mouse button was clicked.

Examples

Use this by augmenting an already existing Psychopy event.Mouse instance:

>>> # First we need a Python function to make this "method-able"
>>> from types import MethodType
>>>
>>> # Then create your scale as you normally would
>>> myMouse = event.Mouse(...)
>>>
>>> # Then add this as a new method to the instance
>>> myMouse.wait_for_click = MethodType(wait_for_click,myMouse)
>>>
>>> # Use it just like you would have used any other method
>>> myMouse.wait_for_click()
psychopy_tools.presentation.wait_time(self, duration, func=None, func_args=None)[source]

Convenience method to augment core.Clock with non-slip timing. Can just wait a specific duration and do nothing, or run some function (e.g. get a rating)

Parameters:
  • duration (int/float) – time to wait in seconds
  • func (function handle) – function to execute for the duration

Examples

Use this by augmenting an already existing Psychopy core.Clock instance:

>>> # First we need a Python function to make this "method-able"
>>> from types import MethodType
>>>
>>> # Then create your clock as your normally would
>>> timer = core.Clock()
>>>
>>> # Then add this as a new method to the instance
>>> timer.wait_time = MethodType(wait_time,timer)
>>>
>>> # Use just like you would use any other timer method
>>> timer.wait_time(5) # just wait 5 seconds
>>>
>>> # You can also present something for a specific amount of time or run any arbitrary function
>>>
>>> time.wait_time(5,my_func,func_args) #run my_func(func_args) in a while loop for 5 seconds

psychopy_tools.stim_gen: Stimulus Generation Functions

Functions associated with stimulus generation and randomization.

psychopy_tools.stim_gen.random_jitter(num_trials, desired_mean=6, iti_min=1, iti_max=None, discrete=True, tolerance=0.05, nsim=20000, plot=True)[source]

Create a series of ITIs (in seconds) with a given mean, number of trials and optionally minimum and maximum. ITIs follow either a discrete geometric distribution or a continuous exponential based on user settings. Either way produces a sequence with more shorter ITIs and fewer longer ITIs.

Perhaps better for fast event-related designs where a mean ITI is desired that comes from a skewed distribution with many shorter ITIs and a few long ITIs.

NOTE: The min ITI is guaranteed, but the max ITI is an upper bound. This means the generated maximum may actually be lower than the desired max. Setting the maximum too low will result in harder/no solutions and will cause the distribution to be less well behaved.

Parameters:
  • num_trials (int) – number of trials (number of ITIs to create)
  • desired_mean (float) – desired mean ITI; default 6
  • iti_min (int/float) – minimum ITI length; guaranteed; default 1
  • iti_max (int/float) – maximum ITI length; only guaranteed that ITIs will not be longer than this; default None
  • discrete (bool) – should ITIs be integers only (discrete geometric) or floats (continuous exponential); default discrete
  • tolerance (float) – acceptable difference from desired mean; default 0.05
  • nsim (int) – number of search iterations; default 10,000
  • plot (bool) – plot the distribution for visual inspection; default True
Returns:

sequence

Return type:

seq (np.ndarray)

psychopy_tools.stim_gen.random_uniform_jitter(num_trials, desired_mean=6, iti_min=2, iti_max=None, discrete=True, tolerance=0.05, nsim=20000, plot=True)[source]

Create a series of ITIs (in seconds) from a uniform distribution. You must provid any two of the following three inputs: desired_mean, iti_min, iti_max. This is because for uniform sampling, the third parameter is necessarily constrained by the first two.

Perhaps useful for slow event related designs, where a longish mean ITI is desired with some variability around that mean.

ITIs follow either a discrete or continuous uniform distribution. If a small amount of variability is desired around a particular mean, simply provide a desired_mean, and a iti_min (or iti_max) that is very close to desired_mean.

Parameters:
  • num_trials (int) – number of trials (number of ITIs to create)
  • desired_mean (float) – desired mean ITI; default 6
  • iti_min (int/float) – minimum ITI length; guaranteed; default 1
  • iti_max (int/float) – maximum ITI length; guaranteed; default 10 (computed)
  • discrete (bool) – should ITIs be integers only (discrete) or floats (continuous); default discrete
  • tolerance (float) – acceptable difference from desired mean; default 0.05
  • nsim (int) – number of search iterations; default 20,000
  • plot (bool) – plot the distribution for visual inspection; default True
Returns:

sequence

Return type:

seq (np.ndarray)

psychopy_tools.rating: Visual Rating Scale

psychopy_tools.rating.RatingScale