kelpy Documentation¶

initialize_kelpy()¶

This sets up the kelpy screen based on the given dimensions and background color. All the stimuli are displayed within this window. For example, this function can be called like so:

screen, spots = initialize_kelpy( dimensions=(1024,768), bg=(250,250,250) )

Where screen is the reference to the screen object and spots is a reference to the StandardLocations object (see StandardLocations ).

Alternatively, you can also set the kelpy screen to fullscreen:

screen, spots = initialize_kelpy( fullscreen=True, bg=(250,250,250) )

OrderedUpdates¶

OrderedUpdates takes a list of kelpy sprites (e.g., CommandableImageSprite) and uses the list order as the order to draw/update the sprites. This order is important when stimuli overlap, such as when needing an occluder to hide an image:

# create your kelpy sprites
occluder = CommandableImageSprite(screen, start_position, image_paths[0])
reward = CommandableImageSprite(screen, start_position, image_paths[1])

# add sprites to a list
stimuli = [reward, occluder]

# store the order that we will draw and update things in this variable 'dos'
dos = OrderedUpdates(stimuli)

In this example, reward is drawn first since it is at [0]. occluder is then drawn second – since the two sprites share the same location (start_position), occluder is drawn on top of reward.

For the kelpy screen to recognize this OrderedUpdates list, the dos object must be passed to the kelpy_standard_event_loop (see kelpy_standard_event_loop()).

DisplayQueue¶

The DisplayQueue stores the order of stimulus events that will occur during the kelpy_standard_event_loop. Kelpy sprites have certain actions they can perform, such as moving or rotating, which can be executed in the order specified in the DisplayQueue:

# create the DisplayQueue
Q = DisplayQueue()

# add the sprite events to the queue:
# first the occluder moves to the north position off-screen (taking 1.5 seconds)
Q.append(obj=occluder, action='move', pos=spots.north, duration=1.5)
# once the occluder is finished, the the reward sprite wiggles for 2 seconds
Q.append(obj=reward, action='wiggle', duration=2, amount=45, cycles=5)

You can also set actions to occur simultaneously by using append_simultaneous():

# create the DisplayQueue
Q = DisplayQueue()

# have the occluder move while the reward wiggles
Q.append(obj=occluder, action='move', pos=spots.north, duration=1.5)
Q.append_simultaneous(obj=reward, action='wiggle', duration=2, amount=45, cycles=5)

Like OrderedUpdates, a DisplayQueue must be passed to the kelpy_standard_event_loop. For a list of specific actions for the different types of kelpy sprites, see Stimulus Types.

kelpy_standard_event_loop()¶

With your kelpy screen, OrderedUpdates object, and DisplayQueue object, you can now run an event loop:

# pass your 3 objects to the event loop.
# the loop will run indefinitely while processing interactions,
# unless you tell it otherwise within the for loop.
for event in kelpy_standard_event_loop(screen, Q, dos):
# in this example, once the reward is clicked, a sound is played
# and then it breaks out of the event loop
        if is_click(event):
                # check what was clicked
                who = who_was_clicked(dos)
                if who is reward:
                        play_sound(sound_file, wait=True, volume=0.7)
                        break

Within the for loop, you can detect user events (such as clicking on objects, dragging objects), add additional sprite actions to the DisplayQueue, play sounds, and whatever else necessary for the flow of your experiment.

StandardLocations¶

Once a kelpy screen is created, a StandardLocations object is returned along with a reference to the screen object itself. StandardLocations has several pre-defined properties that refer to spots both on and off the screen, based on the dimensions of the kelpy window. These spots can be used for image placement. Description of available positions:

Off-screen locations

• north
• northeast
• east
• southeast
• south
• southwest
• west
• northwest

On-screen locations

Default on-screen locations are based on a 4x4 grid pattern, with rows as letters a-d and columns as numbers 1-4. For example, a1 is the top left corner, while d1 is the bottom left corner. There is also a row of 4 positions at the middle height of the screen (midrow1, midrow2, etc.) and a column of 4 positions at the middle width (midcol1, midcol2, etc.). The center position of the screen is center.

who_was_clicked()¶

During the kelpy_standard_event_loop, if you make a call to who_was_clicked() and pass your DisplayQueue as an argument, the function will return what kelpy sprite was clicked on, if any.

who = who_was_clicked(dos)
if who is correct_sprite:
        #return something positive
elif who is wrong_sprite:
        #return something negative?
else:
        #possibly do nothing since no sprite was clicked

kstimulus()¶

This function simplifies calling stimuli files that are included with kelpy, located in the kelpy/stimuli directory. For example, if you wanted to use the Beep.wav sound file:

beep = kstimulus('sounds/Beep.wav')
play_sound(beep)

There are many images and sounds in the stimuli library, so take some time to browse through them!

filename()¶

As the function name implies, this returns just the filename (e.g., image.png) of the filepath that is passed to it (e.g., /home/user/kelpy-master/kelpy/stimuli/image.png). This is useful when outputting either to the command window or to a data file what stimuli were displayed/played.

Q.is_empty()¶

This is a call to the DisplayQueue to check if it still has anything in its queue. If it does, it returns False. Otherwise, it returns True. This is potentially useful when determining when to move on during a task.

CommandableImageSprite¶

A CommandableImageSprite displays an image that can be manipulated by translation, rotation, and scaling.

sprite = CommandableImageSprite(screen, init_position, imagepath, rotation=0, scale=1.0, brightness=1.0)

Arguments:

• screen

  A reference to the kelpy screen object.

• init_position

  A tuple that contains the (x,y) coordinates for the initial position of the sprite.

• imagepath

  The filepath of the image to be displayed.

• rotation

  The value of the initial rotation of the sprite. Default is 0.

• scale

  The scale of the image to be used, from 0 to 1 (or beyond to enlarge, beware pixelation!). Default is 1.

• brightness

  Initial brightness of the image. Default is 1.

Returns:

• sprite

  A reference to the created CommandableImageSprite object

DragSprite¶

DragSprite is a subtype of CommandableImageSprite. It can be dragged by the user when it is clicked/touched. It is created with the same arguments as a CommandableImageSprite and also inherits the same command actions. In order to use a DragSprite, you must also call process_dragndrop() in your kelpy event loop:

# create the DragSprite
draggy = DragSprite(screen, init_position, imagepath)

# add the sprite to an OrderedUpdates object
dos = OrderedUpdates(draggy)

# make the DisplayQueue (no need to add any actions)
Q = DisplayQueue()

# run the kelpy event loop
for event in kelpy_standard_event_loop(screen, Q, dos):
        #check for any drag events and update the sprite's position
        draggy.process_dragndrop(event)

When using other sprites with a DragSprite, it is useful to employ bring_clicked_to_top(). This ensures the currently dragged sprite will be drawn on top of other sprites.

draggy1 = DragSprite(screen, init_position[0], imagepath[0])
draggy2 = DragSprite(screen, init_position[1], imagepath[1])
draggy3 = DragSprite(screen, init_position[2], imagepath[2])

# create a list of the sprites for easy reference later
sprites = [draggy1, draggy2, draggy3]
dos = OrderedUpdates(sprites)
Q = DisplayQueue()

for event in kelpy_standard_event_loop(screen, Q, dos):
        # use reversed() in order to get the sprite on top
        # (objects first in the array are drawn first,
        # and thus under the other objects)
        for sprite in reversed(sprites):
                if sprite.process_dragndrop(event):
                        bring_clicked_to_top(sprite, sprites, dos)
                        break

DropSprite¶

DropSprite is also a subtype of CommandableImageSprite and should be used in conjunction with DragSprite. They can detect when DragSprites are dropped on top of them.

Like a DragSprite, a DropSprite is created with the same arguments as a CommandableImageSprite. To use DropSprites, you must also call register_drop_zone() for your DragSprites in addition to was_dropped_into_zone() in the kelpy event loop. Check which sprite is on a DropSprite with who_was_dropped().

draggy1 = DragSprite(screen, init_position[0], imagepath[0])
draggy2 = DragSprite(screen, init_position[1], imagepath[1])
drop_zone = DropSprite(screen, init_position[2], imagepath[2])

# register drop zone for the DragSprites
draggy1.register_drop_zone(drop_zone)
draggy2.register_drop_zone(drop_zone)

sprites = [draggy1, draggy2, drop_zone]
dos = OrderedUpdates(sprites)
Q = DisplayQueue()

for event in kelpy_standard_event_loop(screen, Q, dos):
        for sprite in reversed(sprites):
                if sprite.process_dragndrop(event):
                        bring_clicked_to_top(sprite, sprites, dos)
                        break

        # check if a sprite was dropped into a registered drop zone
        if was_dropped_into_zone(event):
                # optionally can check who was dropped
                who = who_was_dropped(event)
                if who is draggy1:
                        # do something
                else:
                        # do something else

TextSprite¶

TextSprite is for displaying text in the kelpy screen. It only inherits actions from CommandableSprite.

text = TextSprite(text, screen, init_position)

Arguments:

• text

  The string of text to be displayed.

• screen

  A reference to the kelpy screen object.

• init_position

  A tuple that contains the (x,y) coordinates for the initial position of the text (the text is automatically centered at this point).

AttentionGetter¶

An AttentionGetter displays an animated .gif image and optionally plays sound simultaneously. This is particularly useful when running infant studies in order to get the participant’s attention back to the screen. Unlike the kelpy sprites, AttentionGetters are not manipulated within the kelpy event loop.

#just call the function and you're done!
gif_attention_getter(screen, position, images, sounds=None, keypress=None, stop_music=True, background_color=(255,255,255), duration=4.0)

Arguments:

• screen

  A reference to the kelpy screen object.

• position

  A tuple that contains the (x,y) coordinates for the initial position of the text (the text is automatically centered at this point).

• images

  Can either be one .gif image filepath or a list of .gif image filepaths to use for the attention getter. If it is a list, the .gif used is selected randomly.

• sounds

  Can either be one sound filepath or a list of sound filepaths. If it is a list, then the sound used is selected randomly. Default is no sound.

• keypress

  A pygame keypress code that triggers the attention getter to stop and disappear. Default is no keypress reaction. See the list of key code constants: http://www.pygame.org/docs/ref/key.html

• stop_music

  If True, the music stops after the .gif is played. Otherwise if False, the music continues to play even after the .gif ends. Default is True.

• background_color

  RGB color of the background that the .gif is displayed on. Default is white.

• duration

  The duration in seconds the .gif plays for (unless there is a keypress which stops it earlier). Default is 4 seconds.