psychopy.clock - Clocks and timers

Created on Tue Apr 23 11:28:32 2013

Provides the high resolution timebase used by psychopy, and defines some time related utility Classes.

Moved functionality from core.py so a common code base could be used in core.py and logging.py; vs. duplicating the getTime and Clock logic.

@author: Sol @author: Jon

class psychopy.clock.Clock(format=<class 'float'>)

A convenient class to keep track of time in your experiments. You can have as many independent clocks as you like (e.g. one to time responses, one to keep track of stimuli …)

This clock is identical to the MonotonicClock except that it can also be reset to 0 or another value at any point.

add(t)

DEPRECATED: use .addTime() instead

This function adds time TO THE BASE (t0) which, counterintuitively, reduces the apparent time on the clock

addTime(t)

Add more time to the Clock/Timer

e.g.:

timer = core.Clock()
timer.addTime(5)
while timer.getTime() > 0:
    # do something

reset(newT=0.0)

Reset the time on the clock. With no args time will be set to zero. If a float is received this will be the new time on the clock

class psychopy.clock.CountdownTimer(start=0)

Similar to a Clock except that time counts down from the time of last reset.

Parameters:

start (float or int) – Starting time in seconds to countdown on.

Examples

Create a countdown clock with a 5 second duration:

timer = core.CountdownTimer(5)
while timer.getTime() > 0:  # after 5s will become negative
    # do stuff

addTime(t)

Add more time to the CountdownTimer

e.g.:

countdownTimer = core.CountdownTimer() countdownTimer.addTime(1)

while countdownTimer.getTime() > 0:

# do something

getTime()

Returns the current time left on this timer in seconds with sub-ms precision (float).

reset(t=None)

Reset the time on the clock.

Parameters:

t (float, int or None) – With no args (None), time will be set to the time used for last reset (or start time if no previous resets). If a number is received, this will be the new time on the clock.

class psychopy.clock.MonotonicClock(start_time=None, format=<class 'float'>)

A convenient class to keep track of time in your experiments using a sub-millisecond timer.

Unlike the Clock this cannot be reset to arbitrary times. For this clock t=0 always represents the time that the clock was created.

Don’t confuse this class with core.monotonicClock which is an instance of it that got created when PsychoPy.core was imported. That clock instance is deliberately designed always to return the time since the start of the study.

Version Notes: This class was added in PsychoPy 1.77.00

getLastResetTime()

Returns the current offset being applied to the high resolution timebase used by Clock.

getTime(applyZero=True, format=None)

Returns the current time on this clock in secs (sub-ms precision).

Parameters:

• applyZero (bool) –

  If applying zero then this will be the time since the clock was created (typically the beginning of the script). If not applying zero then it is whatever the underlying clock uses as its base time but that is system dependent. e.g. can be time since reboot, time since Unix Epoch etc.

  Only applies when format is float.

• format (type, str or None) – Format in which to show timestamp when converting to a string. Can be either: - 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 this clock’s format attribute

Returns:

Time with format requested.

Return type:

Timestamp

class psychopy.clock.StaticPeriod(screenHz=None, win=None, name='StaticPeriod')

A class to help insert a timing period that includes code to be run.

Parameters:

• screenHz (int or None)

• you (the frame rate of the monitor (leave as None if) – don’t want this accounted for)

• win (Window) – If a Window is given then StaticPeriod will also pause/restart frame interval recording.

• name (str) – Give this StaticPeriod a name for more informative logging messages.

Examples

Typical usage for the static period:

fixation.draw()
win.flip()
ISI = StaticPeriod(screenHz=60)
ISI.start(0.5)  # start a period of 0.5s
stim.image = 'largeFile.bmp'  # could take some time
ISI.complete()  # finish the 0.5s, taking into account one 60Hz frame

stim.draw()
win.flip()  # the period takes into account the next frame flip
# time should now be at exactly 0.5s later than when ISI.start()
# was called

complete()

Completes the period, using up whatever time is remaining with a call to wait().

Returns:

1 for success, 0 for fail (the period overran).

Return type:

float

start(duration)

Start the period. If this is called a second time, the timer will be reset and starts again

Parameters:

duration (float or int) – The duration of the period, in seconds.

psychopy.clock.getAbsTime()

Get the absolute time.

This uses the same clock-base as the other timing features, like getTime(). The time (in seconds) ignores the time-zone (like time.time() on linux). To take the timezone into account, use int(time.mktime(time.gmtime())).

Absolute times in seconds are especially useful to add to generated file names for being unique, informative (= a meaningful time stamp), and because the resulting files will always sort as expected when sorted in chronological, alphabetical, or numerical order, regardless of locale and so on.

Version Notes: This method was added in PsychoPy 1.77.00

Returns:

Absolute Unix time (i.e., whole seconds elapsed since Jan 1, 1970).

Return type:

float

psychopy.clock.getTime()

Copyright (c) 2018 Mario Kleiner. Licensed under MIT license.

For detailed help on a subfunction SUBFUNCTIONNAME, type GetSecs(‘SUBFUNCTIONNAME?’) ie. the name with a question mark appended. E.g., for detailed help on the subfunction called Version, type this: GetSecs(‘Version?’)

[GetSecsTime, WallTime, syncErrorSecs, MonotonicTime] = GetSecs(‘AllClocks’ [, maxError=0.000020]);

psychopy.clock.wait(secs, hogCPUperiod=0.2)

Wait for a given time period.

This function halts execution of the program for the specified duration.

Precision of this function is usually within 1 millisecond of the specified time, this may vary depending on factors such as system load and the Python version in use. Window events are periodically dispatched during the wait to keep the application responsive, to avoid the OS complaining that the process is unresponsive.

If secs=10 and hogCPU=0.2 then for 9.8s Python’s time.sleep function will be used, which is not especially precise, but allows the cpu to perform housekeeping. In the final hogCPUperiod the more precise method of constantly polling the clock is used for greater precision.

If you want to obtain key-presses during the wait, be sure to use pyglet and then call psychopy.event.getKeys() after calling wait()

If you want to suppress checking for pyglet events during the wait, do this once:

core.checkPygletDuringWait = False

and from then on you can do:

core.wait(sec)

This will preserve terminal-window focus during command line usage.

Parameters:

• secs (float or int) – Number of seconds to wait before continuing the program.

• hogCPUperiod (float or int) – Number of seconds to hog the CPU. This causes the thread to enter a ‘tight’ loop when the remaining wait time is less than the specified interval. This is set to 200ms (0.2s) by default. It is recommended that this interval is kept short to avoid stalling the processor for too long which may result in poorer timing.

Back to top