PyPsyExp Documentation

Experiment

class pypsyexp.Experiment(nofullscreen, screenres, experimentname, **useroptions)

The experiment class is a general purpose class.

Required Arguments:

• nofullscreen (bool):

  • If nofullscreen is True, the display created will be windowed.
  • If False (the default), the display will be fullscreen.

• screenres (tuple of ints): 2-value tuple or list representing pixel dimensions.

• experimentname (str): string that will be displayed as the title of the new window.

Keyword Arguments:

• experimentversion (str): The version name for the experiment.
• fontname (str): Name of default font.
• fontsize (int): Size of default font.
• bgcolor (str or tuple): Backgound color. Default is white. String or rgb tuple.
• fgcolor (str or tuple): Foreground color. Default is black. String or rgb tuple
• patterncode (str): Name of patterncode file. Defaults to patterncode.txt but is only loaded if it is passed in.
• imagedir (str): Directory images are in. Defaults to images, but they are only loaded if it is passed in.
• sounddir (str): Directory sounds are in. Defaults to sounds, but they are only loaded if it is passed in.
• datadir (str): Folder the datafiles will be stored in. Defaults to data
• ftphost (str): FTP host name
• ftpuser (str): FTP user name
• ftppassword (str): FTP password
• verbose (bool): Print extra messages? Default is true.
• framerate (int): Polling rate in fps.
• suppresspygame (bool): Try not to use any pygame UI functions.

sets:

• self.options (dict): All keyword arguments
• self.trial (dict): Signifies trial number. Initialized at 0.
• ...and all possible keyword arguments are assigned their own self. names.

check_for_exit()

Checks for the exit sequence: left shift plus ~. Override this function to use a different exit keystroke.

clear_screen(color=None, rewrite_background=True)

Creates a Surface with the dimensions of the display screen, fills it with a given color, and returns the Surface.

Keyword Arguments:

• color (str of tuple): Color to draw on screen (name or rgb). Defaults to self.bgcolor.
• rewrite_background (bool): Whether the surface is written to self.background. Defaults to True.

draw_gabor(freq, angle, scale)

This is a demo for using gabor patches. Call setup_gabor to set initial values for the gabor patch, then draw_gabor to actually draw it to a surface. They are thin wrappers to the GaborPatch class.

Draws the gabor patch set by ‘setup_gabor’

Required Arguments:

• freq (int): the frequency of the gabor patch
• angle (int): value to determine rotation on the patch. WARNING: units are degrees/2
• scale (int) - enlarges the gabor patch by a given factor

Warning

Due to a bug in pygame, angle is in units of degrees/2.

Note

For faster blitting it is recommended to set the grid_w and grid_h in setup_gabor to be smaller than the actual patch desired. To offset this, use the scale value to blow up the image.

Due to the nature of rotating a surface, the size of the surface the gabor patch changes based on the value of the rotation angle. This function re-centers the patch after each rotation, but it should be noted as it will make the area of the surface larger.

draw_on_screen_example(background=None, color=None, break_key=32, radius=3)

This is an example of how to allow participants to draw on the screen with a mouse. They can draw by clicking and dragging the mouse. Pressing the break_key exits the drawing environment.

Keyword Arguments:

• background (pygame.surface): The surface to draw to. Defaults to self.background.
• color (str or tuple): The maker color. Defaults to self.fgcolor.
• break_key (int (from pygame.locals): Pressing this key terminates drawing.
• radius (int): The radius of the drawing brush.

draw_square(surf=None, color=None, x=0, y=0, width=10, height=10, thick=0)

Draws a square of the size and coordinates requested to the background, and returns the result.

Keyword Arguments:

• surf (pygame.surface): Surface to draw to. Defaults to self.background.
• color (str of tuple): Color of rectangle (name or rgb).
• x (int): The coordinate of the left side of the rectangle.
• y (int): The coordinate of the top of the rectangle.
• width (int): The width of the rectangle. Defaults to 10.
• height (int): The height of the rectangle. Defaults to 10.
• thick (int): The thickness of the rectangle border. If thick is 0 (the default), the rectangle is filled and has no border. Otherwise it is not filled.

escapable_sleep(pause=1000, esckey=None)

Pauses the program for ‘pause’-number of milliseconds. Can be exited via the default keystroke in``check_for_exit``.

Keyword Arguments:

• pause (int): (in milliseconds) Amount of time to sleep for.
• esckey (int; from pygame.locals): A key that, if pressed, will end the pause.

get_cond_and_subj_number(filename='')

Reads a patterncode file that must contain the following three values on its first three lines:

1. Condition current subject will be in.
2. Number of conditions.
3. Current subject number (automatically updated).

After reading the text file, the condition number and subject number are automatically updated and written back into the file for subsequent runnings.

Keyword Arguments:

• filename (str): Path to the patterncode file. Defaults to patterncode.txt

Returns:

A list of the items in the file, in int form.

get_cond_and_subj_number_ftp(host='', username='', password='', filename='')

Similar functionallity to get_cond_and_subj_number. Reads data from a remote ftp client in order to set up participant numbers and conditions. The host, username, and password can be set during the initialization of the Experiment object.

Keyword Arguments:

• host (str): web address of file hosting site
• username (str): account name on the host site
• password (str): password for the account
• filename (str): name of patterncode file, defaults to patterncode.txt

Returns:

A list containing the lines in the file, converted to ints.

get_keystroke()

Waits for a key to be pressed, then Returns the key mapping for a single pressed letter, ignoring modifier keys. Actual key mappings are found in libSDL source, in: $SDLROOT/src/events/SDL_keyboard.c.

get_response()

Legacy function name. Deprecated.

get_response_and_rt(keys=['p', 'q'], val=None)

Monitors keyboard Events for the given set of keys (default Q and ‘P’). Case insensitive. Returns the time it took from the call to the function to the end of the function (reaction time; rt) and the coded version of the response (given in ‘val’).

Keyword Arguments:

• keys (list or tuple of strings) where the keys are the names of the keys that will be pressed. Defaults to [q, p]. Keypad numbers == keyboard numbers (although this could change) For a full list of valid key names, see the libSDL source, under $SDLroot/src/events/SDL_keyboard.c.
• val (list or tuple) with coded values, e.g. ['Left', 'Right'] or (0, 1). Defaults to be the same as keys.

Returns:

( reactiontime, resultvalue )

get_response_and_rt_pq(val=None)

Monitors keyboard Events for the Q and P keys. Returns the time it took from the call to the function to the end of the function (reaction time; rt) and the response made (res).

Keyword Arguments:

• val (list or tuple) with coded values, e.g. ['Left', 'Right'] or (0, 1)

Returns:

A list with reaction time and the value code for the response made.

get_text_image(font=None, prompt='', txtcolor=None, bgcolor=None)

Creates a Surface with anti-aliased text written on it, and returns it.

Keyword Arguments:

• font (pygame.font): The font to use for the text.
• prompt (str): String to be displayed
• txtcolor (str or tuple): Color for text (RGB or name)
• bgcolor (str or tuple): Color for the background (RGB or name)

Returns:

The surface with text written to it.

load_all_images(directory='')

Loads images and places their corresponding objects into self.resources. Filters out Thumbs.db files (in the case of Macs) and hidden system files. The function filters out Thumbs.db files (in the case of Macs) and UNIX system files (starting with .). All images are placed in a list called self.resources. All images must be referenced by name, e.g. self.resources['image1.gif'].

Keyword Arguments:

• directory (str): Path to the folder containing images.

Modifies:

self.resources

load_all_resources(img_directory='', snd_directory='')

Loads images and sounds by calling load_all_images and load_all_sounds.

Keyword Arguments:

• img_directory (str): Path to the folder containing images.
• snd_directory (str): Path to the folder containing sounds.

load_all_sounds(directory='')

load_all_sounds takes one value, the path to the folder containing sound files. The function filters out Thumbs.db files (in the case of Macs) and UNIX system files (starting with .). All sounds are placed in a list called self.resources. All sounds must be referenced by name, i.e. self.resources['sound1.wav'].play()

Keyword Arguments:

• directory (str): Path to the folder containing images.

Updates:

self.resources

load_image(filename, colorkey=None)

Attempts to load an image given its filename.

It has two means of determining which color will be made transparent:

1. If colorkey is not None, then the color passed will be made transparent. If colorkey is -1, then the RGB value in the top left-most pixel of the image will be set as the colorkey.
2. If the filename is of the format *-transp-x-y.EXT, where EXT is the file e``x``tension, then x and y are the x and y coordinates of the pixel that will be made transparent.

If neither of these conditions are met, the image will not have transparency.

Required Arguments:

• filename (str): path to image file.

Keyword Arguments:

• colorkey (tuple of ints): path to image file.

Returns:

The resulting image object.

Raises:

pygame.error

on_exit(msg='', exception=<type 'exceptions.SystemExit'>)

Clears all data that remains on queue and closes self.datafile.

Keyword Arguments:

• msg (str): Exit message.

output_trial(myline, echo=False)

Writes a list of data to a file as a line in which each value seperated by a space.

Required Arguments:

• myline (iterable): Iterable of items to be written to the line

Keyword Arguments:

• echo (bool): If True, prints the line to the screen.

place_text_image(prompt='', size=None, xoff=0, yoff=0, txtcolor=None, bgcolor=None, font=None, fontname=None, mysurf=None)

Blits a Text object to the surface passed.

Keyword Arguments:

• prompt (str): String to be displayed
• size (int): text size
• xoff (int): Horizontal offset from center.
• yoff (int): Vertical offset from center.
• txtcolor (str or tuple): Color of the test (name or RGB).
• bgcolor (str or tuple): Color of the background (name or RGB).
• font (pygame.font): Font object to use for text rendering. Overrides other font values.
• fontname (str): Name of font to use.
• mysurf (pygame.surface): Surface object to be blitted to.

Returns:

A pygame surface object with the text placed on it.

placing_rect(bkgd_surf=None, inner_surf=None, xoff=0, yoff=0)

Creates a Rect from Surface inner_surf and places it onto Surface bkgd_surf.

Keyword Arguments:

• bkgd_surf (pygame.surface): Surface to write to.
• inner_surf (pygame.surface): Surface to write to the other surface.
• xoff (int): Horizontal offset from center.
• yoff (int): Vertical offset from center.

Returns:

The surface created.

play_sound(sndname, pause=0)

Plays a sound file for its length plus and length ‘pause’ in milliseconds. This function works with .wav files only. It pauses the timer.

Required Arguments:

• sndname (str): The sound name (omit the .wav extension)

Keyword Arguments:

• pause (int): Time in milliseconds to pause the pygame timer

Returns:

The sound duration plus pause.

prompt_text(background=None, x=0, y=0, timelimit=None, prompt='', fontsize=None, maxlength=40, fgcolor=None, centered=False)

Makes an onscreen prompt for users to enter a single line of text.

Keyword Arguments:

• background (pygame.surface): the surface that will be refreshed; defaults to self.background.
• x (int): The horizontal coordinate, determining the left side of the prompt, or the center if centered is True.
• y (int): The vertical coordinate, determining the top of the prompt, or the center if centered is True.
• timelimit (int): (in milliseconds). Default is None.
• prompt (str): To be printed in front of the typed text. Default is a null string.
• fontsize (int): Size of text printed on screen. Default is 32.
• maxlength (int): Maximum number of characters allowed to be typed. Default is 40. 0 means unlimited.
• fgcolor (str or tuple): Color of text; name or rgb tuple. Default is self.fgcolor
• centered (bool): Maintain a centered alignment. x and y become offset of center if True. Default is False.

Returns:

The typed text as it appeared on the screen.

Possible future options:

Restrictions on possible characters. Control over typeface.

read_patterncode_lines(lines)

Reads lines taken from a patterncode file. File should consists of 3 lines, as follows:

1. Condition current subject will be in
2. Number of conditions
3. Current subject number (automatically updated)

Writes values to self.cond, self.ncond, and self.subj. Returns the new lines to be written back to the file.

Required Arguments:

• lines (list of strs): Lines read in from patterncode file.

Returns:

A list of the strings’ new lines.

set_filename(name=None)

Sets and opens file to be written. If the name field is not passed, the datafile opened is named the current subject number.

Keyword Arguments:

• name (str): The filename.

Sets:

• self.filename
• self.datafile

setup_gabor(grid_w, grid_h, windowsd)

This is a demo for using gabor patches. Call setup_gabor to set initial values for the gabor patch, then draw_gabor to actually draw it to a surface. They are thin wrappers to the GaborPatch class.

Arguments:

• grid_w (int): width
• grid_h (int): height
• windowsd (float): standard deviation

show_centered_image(imagename, bgcolor=None, alpha=None)

Centers an image in the screen with a given bgcolor.

Required Arguments:

• imagename (str): Name of image.

Keyword Arguments:

• bgcolor (str or tuple): Background color (name or RGB)

Returns:

A surface with the image blitted over a field of bgcolor.

show_centered_image_add(mysurf=None, imagename=None, alpha=None)

Centers an image in the surface passed. Default surface is self.background.

Note

This REQUIRES a Surface object to be passed, whereas show_image creates a Surface to be blitted on

Keyword Arguments:

• mysurf (pygame.surface): Surface to blit to. Defaults to self.background
• imagename (str): Mandatory. Name of image (must be in self.resources).
• xoff (int): Horizontal offset from center.
• yoff (int): Vertical offset from center.
• alpha (float): Amount of opacity. Defaults to fully opaque.

Returns:

A surface with the image added.

show_image(imagename, bgcolor=None, xoff=0, yoff=0, alpha=None, rewrite_background=True)

Creates a surface object with the dimensions of the display screen. Then blits an image to the center of the surface plus any offseting height/width. The surface is then returned.

Note

This creates a Surface object, whereas show_image_add is passed a surface to be blitted on.

Required Arguments:

• imagename (str): Name of image (must be in self.resources).

Keyword Arguments:

• bgcolor (str or tuple): Background color (name or RGB)
• xoff (int): Horizontal offset from center.
• yoff (int): Vertical offset from center.
• alpha (float): Amount of opacity. Defaults to fully opaque.
• rewrite_background (bool): Whether the surface is written to self.background. Defaults to True.

Returns:

A surface with the image blitted over a field of bgcolor.

Raises:

• KeyError: Image not found.

show_image_add(mysurf=None, imagename=None, xoffset=0, yoffset=0, alpha=None)

Places an image onto a passed Surface with given offsets relative to the center of the Surface. Returns the drawn-on Surface.

mysurf - Surface to be blitted to imagename - name of the image file loaded by load_image (or load_all_images) xoffset/offset - offsets relative to the center of the Surface alpha - alpha value of the image

Note

This REQUIRES a Surface object to be passed, whereas show_image creates a Surface to be blitted on

tick()

Waits until a given time based on self.framerate. Useful while in a loop to limit the rate at which it loops.

update_display(mysurf=None)

Blits the surface passed to the default display screen created by the experiment class. Then flips it.

Keyword Arguments:

• mysurf (pygame.surface): The surface to be written to the screen.

upload_data(host='', username='', password='', filename='', netfilename='')

Uploads data to a file storage site. FTP credentials can be set during the initialization of the Experiment object.

Keyword Arguments:

• host (str): Hostname of ftp server.
• username (str): Username on server.
• password (str): Password to server.
• filename (str): Local file that will be uploaded. Defaults to self.filename.
• netfilename (str): Name of file to be written to server. Defaults to filename.

TextPrompt

class pypsyexp.TextPrompt(screen, background, **useroptions)

A text input prompt. Allows the on-screen editing of a single line of text.

TextPrompt accepts the following keyword arguments when it starts up:

x, y, font, fgcolor, restricted, maxlength, prompt.

center(offset=0)

draw()

Draw the text input to the screen

get_text_line(centered=False, timelimit=None)

Prompts the user for a line of text, updating it as they type.

The escape sequence here is to press both shift keys and tilde (this is to prevent subjects from accidentally quitting the experiment using tilde).

set_font(font)

Set the font for the input

set_pos(x, y)

Set the position to x, y

update(events)

Update the input based on a list of events passed in. Returns true if enter is pressed.

MouseButton

class pypsyexp.MouseButton(x, y, w, h)

Button class based on the template method pattern.

containsPoint(x, y)

do()

GaborPatch

class pypsyexp.GaborPatch(grid_w=10, grid_h=10, windowsd=1)

The GaborPatch object initializes the gabor patch when it is called. It can then be drawn by callind draw_gabor.

Sets up initial values for a gabor patch.

Arguments:

• grid_w (int): width
• grid_h (int): height
• windowsd (float): standard deviation

bivariate_normpdf(x, y, sigma_x, sigma_y, mu_x, mu_y, mul)

Formula used to set the gaussion blur. Covariance is fixed at 0.

Required Arguments:

• x - current position in the grid
• y - current position in the grid
• sigma_y - variance in each plane of the grid
• sigma_x - variance in each plane of the grid
• mu_x - mean on the x dimension.
• mu_y - mean on the y dimension.
• mul - scales by this amplitude factor

Returns:

The pdf for the given distribution at the given coordinates.

draw_gabor(freq, angle, scale)

Draws the gabor patch.

Required Arguments:

• freq (int): the frequency of the gabor patch.
• angle (int): value to determine rotation on the patch. WARNING: units are degrees/2.
• scale (int) - enlarges the gabor patch by a given factor.

Warning

Due to a bug in pygame, angle is in units of degrees/2.

Note

For faster blitting it is recommended to set the grid_w and grid_h in ‘setup_gabor’ to be smaller than the actual patch desired. To offset this, use the scale value to blow up the image.

Due to the nature of rotating a surface, the size of the surface the gabor patch changes based on the value of the rotation angle. This function re-centers the patch after each rotation, but it should be noted as it will make the area of the surface larger.

Ancillary functions

pypsyexp.pgColor(colorid)

Converts either an RGB tuple or a string into a valid rgb tuple.

Required Arguments:

• colorid (tuple or str): Color name or rgb tuple

Returns:

If colorid is a tuple, this simply checks for validity. If it is a string, looks it up pygame’s built-in color dictionary, and returns an rgb tuple corresponding to the name.