Builder

The builder code uses PsychoPy’s visual library to create a rudimentary GUI for creating PyHab studies. The GUI itself mostly consists of clickable shapes that open dialog boxes. The only notable exception is the system for creating conditions, which creates an entire new UI in the window.

When the builder’s save functions are called, they create a complete, self-contained folder which includes the experiment setitngs file (a csv), a launcher script, the PyHab module folder with PyHabClass, PyHabClassPL, and PyHabBuilder, and copies of all of the stimuli and attention-getters to a stimuli folder.

class PyHab.PyHabBuilder.PyHabBuilder(loadedSaved=False, settingsDict={})

Graphical interface for constructing PyHab experiments. Runs mostly on a Pyglet window and qtGUI dialogs. Saves a settings file in .csv form which can then be read by PyHab Launcher, PyHabClass, PyHabClassPL, and PyHabClassHPP.

HPP_stimSettingsDlg()

A dialog box for the stimulus settings unique to head-turn preference procedures. Just selects the screen to then open the stimulus dialog window for.

Returns:
Return type:
addStimToLibraryDlg()

A series of dialog boxes which allows you to build a “library” of stimulus files for your experiment, which you can then assign to trial types in a separate dialog.

Works a bit like the attention-getter construction dialogs, but different in that it allows audio or images alone. The image/audio pairs are complicated, but not worth splitting into their own function at this time.

Returns:
Return type:
addStimToTypesDlg()

A series dialog boxes, the first selecting a trial type and the number of stimuli to add to it, a second allowing you to add stimuli from the stimulus library that is stimList in the settings. Also used for adding beginning and end of experiment images

Returns:
Return type:
advTrialDlg(trialType)

A dialog for advanced trial settings mostly having to do with attention-getters and stimulus presentation

0/-8 = cutoff attention-getter on gaze-on? T/F [if trial has an AG - not always present]

1/-7 = cutoff on-time: How long do they have to look to cut off presentation? [if trial has an AG - not always present]

2/-6 = Pause stimulus presentation when infant is not looking at screen?

3/-5 = Mid-trial AG: Play an attention-getter if infant looks away mid-trial?

4/-4 = mid-trial AG trigger: Minimum time to trigger mid-trial AG

5/-3 = mid-trial AG cutoff: Stop mid-trial AG on gaze-on?

6/-2 = mid-trial AG cutoff ontime

7/-1 = HPP ONLY: Only count gaze-on to stimulus-presenting screen? T/F, casts to hppStimScrOnly

Parameters:trialType (str) – The trial type being modified.
Returns:
Return type:
advTrialSetup()

A function for selecting the trials you want to access the advanced settings of. Spawns a panel with all the trial types. Reuses code from the block interface. Doesn’t need to check existence of trials because

Returns:
Return type:
attnGetterAudioDlg()

A modular dialog for setting the options for an audio-based attention-getter

Returns:A dictionary containing all the info required for an audio attention-getter
Return type:dict
attnGetterDlg()

The dialog window for customizing the attention-getters available to use for different trials. Two-stage: Modify existing attngetter or make new, then what do you do with ether of those. Allows audio with PsychoPy-produced looming shape or just a video file.

Returns:
Return type:
attnGetterMovieAudioDlg()

A modular dialog for finding an audio file and a video file and titling them appropriately.

Returns:A dictionary containing all the info required for a video/audio attngetter.
Return type:
attnGetterVideoDlg()

A modular dialog for setting the options for a video-based attention-getter

Returns:A dictionary containing all the info required for a video attention-getter
Return type:dict
autoCond(genTrials, genBlocks, counters)

The function that actually creates conditions automatically, given what it is generating conditions for, and how many items from each trial/block it should have in each condition. Simply sets condDict and condList.

Parameters:
  • genTrials (bool) – Are we generating conditions for movies within trial types?
  • genBlocks (bool) – Are we generating conditions for trials within blocks?
  • counters (dict) – A dictionary of each block or trial type that needs to be randomized and the number of items that thing should have in each condition
Returns:
Return type:
autoCondSetup()

Function for getting the parameters for automatically generating conditions. A series of dialogs. The first one, whatGenDlg, determines whether we are doing stim within trials, trials within blocks, or both. It also determines whether we are keeping all items, which shortcuts the second dialog. whatGenDlg: 0 (if blocks): Randomize order of stimuli in trials y/n 1 (if blocks): Randomize order of trials in blocks y/n -1: Keep all items in all conditions y/n

A second dialog then asks whether there are any trial/block types the user does not want to randomize.

If not keeping all items in all conditions, another dialog is needed to determine size of subset for each trial/block. This produces a dictionary that tracks how many items will be in each condition. :return: :rtype:

blockDataDlg()

A dialog for determining whether you save a block data file, and if so which blocks to compress.

Procedurally constructs a set of options such that, for any nested blocks, they are mutually exclusive, but any blocks that are not part of other blocks and other blocks are not part of them are just check-boxes.

Excludes hab because habituation data files are saved by default.

Returns:
Return type:
blockMaker(blockName, new=True, hab=False)

For making multi-trial blocks. Or multi-block-blocks. Blocks are necessary for habituation.

Creates a kind of sub-UI that overlays over the main UI. Because it’s just for blocks, we can ditch some things. We can actually completely overlay the regular UI. Problem is, if the regular UI continues to draw, the mouse detection will still work, even if a shape is behind another shape. So, like with conditions, we need a totally parallel UI

Hab blocks cannot be embedded in other blocks.

Parameters:
  • blockName (str) – Name of new block
  • new (bool) – Is this a new block or a modification of an existing one?
  • hab (bool) – Is this for a habituation meta-trial? # TODO: No longer needs to be an argument?
Returns:
Return type:
condMaker(rep=False, currPage=1, bc=False, trialMode=True, resetDict={})

A whole separate interface for managing condition creation.

Outputs settings condList (labels of each condition), condFile (save conditions to this file) and makes new structure condDict (mapping of each label to actual condition it applies to)

Parameters:
  • rep (bool) – Basically whether we are recursing while editing conditions
  • currPage (int) – The current page number
  • bc (bool) – Are we displaying the raw conditions, or the ‘base’ (pre-randomization) conditions?
  • trialMode (bool) – A toggle between ‘trial mode’ (use conditions for order of stimuli in trial types) and ‘block mode’ (use conditions to change order of trials within blocks)
Returns:
Return type:
condRandomizer(bcReset=False)

This is based on other scripts I’ve made. Basically, say you have four conditions, and you want four participants to be assigned to each one, but you want to be totally blind to which condition a given participant is in. Here, once you have made your four conditions, you can tell it to create a condition list that it never shows you that has each condition X times, and that becomes the new condition file/list/etc.

Parameters:bcReset (bool) – For the edge case where someone re-loads the base conditions and wants to re-randomize them.
Returns:
Return type:
condSetter(shuffleList, cond='NEW', ex=False, blockmode=False)

A new interface for ordering stimuli within a trial type or trials within a block for a specific condition. Increases flexibility and usability. Uses an overlay like the block-constructor interface

ST/PL output: {trialType:[stim1, stim2]} HPP output: {trialType:[{‘L’:0,’C’:stim1,’R’:0},{}]}

Parameters:
  • shuffleList (dict) – Either the stimNames dict or the blockList dict. Defines which one we are modifying.
  • cond (str) – Condition name
  • ex (bool) – Whether the condition already exists
  • blockmode (bool) – Are we reordering a block or a trial? Matters because even in HPP need to be blocks
Returns:
Return type:
condSettingsDlg()

The dialog window for “condition settings”, not to be confused with the condition interface created by self.condMaker(). This determines whether condition randomization is used at all, a separate interface is used to define the conditions themselves.

Returns:
Return type:
dataSettingsDlg()

Which columns of data are recorded. Resets if the experiment type is switched to or from preferential looking.

Returns:
Return type:
delCond()

Present list of existing conditions. Choose one to remove.

delTrialTypeDlg()

Dialog for deleting a trial type, and all instances of that trial type in the study flow

Returns:
Return type:
deleteType(dType)

Performs the actual deletion of a trial or block type. TODO: More sophisticated handling of conditions.

Parameters:dType (str) – String indicating the name of the trial or block to be deleted
Returns:
Return type:
habSettingsDlg(trialList, lastSet, redo=False)

Dialog for settings relating to habituation criteria:

0 = habituation (Active/not active)

1 = maxHabTrials (maximum possible hab trials if criterion not met)

2 = setCritWindow (# trials summed over when creating criterion)

3 = setCritDivisor (denominator of criterion calculation . e.g., sum of first 3 trials
divided by 2 would have 3 for setCritWindow and 2 for this.)

4 = setCritType (peak window, max trials, first N, last N, or first N above threshold)

5 = habThresh (threshold for N above threshold)

6 = metCritWindow (# trials summed over when evaluating whether criterion has been met)

7 = metCritDivisor (denominator of sum calculated when determining if criterion has been met)

8 = metCritStatic (static or moving window?)

9 = habByDuration (habituation by duration or by on-time)

10-N = Which trials to calculate hab over for multi-trial blocks.

Parameters:
  • trialList (list) – List of available trials in the block, since this follows from block settings.
  • lastSet (dict) – If information entered is invalid and the dialog needs to be shown again, this allows it to remember what was previously entered. Also pulls from existing block settings.
  • redo (boolean) – Checking if redoing last setting
Returns:

A dictionary of settings fed back into the block-maker UI.
Return type:

dict
lastPalettePage()

Simple function for moving to the previous page of the trial type palette :return: :rtype:

loadFlow(tOrd, space, locs, overflow, types, conlines=True, trials=True, specNumItems=0)

Creates the array of objects to be drawn for a study flow or block flow.

Flow dictionary components: ‘lines’: Lines that go between items in the flow, drawn first ‘shapes’: visual.Rect objects ‘text’: visual.textStim objects ‘labels’: Strings that label each trial. Shapes and text are indexted to these, so you can do easy lookup. ‘extras’: Special category for trial pips for blocks.

Parameters:
  • tOrd (list) – Extant order of trials, either the overall trial order or the block order
  • space (list) – The dimensions of the flow part of the UI, typically self.flowArea
  • locs (list) – List of locations to draw the items in the flow, if less than 21 items to be drawn
  • overflow (list) – List of locations to use when there are more than 21 items, which compacts the rendering.
  • types (list) – List of items being put into this flow. Typically the list of trial types, except when making conditions.
  • conlines – A special boolean added for cases where we might not want connecting lines between items in the flow, e.g. conditions.
  • trials (bool) – A special bool added for cases where we might not be dealing with trial types, to avoid certain pitfalls in conditional logic.
  • specNumItems (int) – A special argument for cases where there are weird line overlaps that change the length of things. Defaults to 0, only used when calling recursively.
Returns:

A dictionary of all of the entities to draw into the block or study flow
Return type:

dict
loadTypes(typeLocations, typeList, page=1)

This function creates the trial types palette.

Type pallette dictionary components: ‘shapes’: visual.Rect objects ‘text’: visual.TextStim objects ‘labels’: A sort of index for the other two, a plain string labeling the trial or block type.

Parameters:
  • typeLocations (list) – The array of coordinates on which buttons can be placed. Usually self.typeLocs
  • typeList (list) – A list of what is being populated into the array. Usually self.settings[‘trialTypes’]
  • page (int) – Page number for when there are more types than fit on one page, in order to render the correct one.
Returns:
Return type:
mainLoop()

Main loop of the whole program.

Returns:
Return type:
makeBlockDlg(name='', new=True)

Creates a new ‘block’ structure, which basically masquerades as a trial type in most regards, but consists of several sub-trials, much like how habituation blocks work.

Parameters:
  • name (str) – Name of existing trial type. ‘’ by default
  • new (bool) – Making a new block, or modifying an existing one?
Returns:
Return type:
moveTrialInFlow(flowIndex, tOrd, flowSpace, UI, flow, types)

A function for when a trial is clicked in a trial flow, allowing you to either swap it or remove it.

Parameters:
  • flowIndex (int) – The index in the flowArray of the trial being modified
  • tOrd (list) – The trial order being modified, either the main one or a block order
  • flowSpace (visual.Rect object) – The shape that makes up the flow UI, which varies from typical usage to block construction
  • UI (dict) – A dictionary containing the currently active UI
  • flow (dict) – A dictionary containing the currently active trial flow
  • types (dict) – A dictionary containing the currently active trial pallette (mostly for showMainUI)
Returns:

The modified trial order
Return type:

list
nextPalettePage()

Simple function for moving to the next page of the trial type palette. :return: :rtype:

quitFunc()

Simple function for quitting, checks if you want to save first (if there’s anything to save).

Returns:
Return type:
removeStimFromLibrary()

Presents a dialog listing every item of stimuli in the study library. Allows you to remove any number at once, removes from all trial types at same time. Deletes from stimuli folder on save if extant.

Returns:
Return type:
run()

Exists exclusively to be called to start the main loop.

Returns:
Return type:
saveDlg()

Opens a save dialog allowing you to choose where to save your project. Essentially sets self.folderPath

Returns:
Return type:
saveEverything()

Saves a PyHab project to a set of folders dictated by self.folderPath

todo: Add psychopy_tobii_infant to this. Saved in the code folder.

Returns:
Return type:
showMainUI(UI, flow, types)

A simple function that draws everything and flips the display. Generalized to work for block mode and general mode.

Parameters:UI – a dictionary of everything to be drawn in the new UI. Contains a list, ‘bg’ (background), and a dict,

‘buttons’, that has itself ‘shapes’ and ‘text’ (and usually ‘functions’ but this doesn’t need to know that) :type UI: dict :param flow: A dict of everything in the block flow. Contains five lists, ‘lines’, ‘shapes’, ‘text’, ‘labels’, and ‘extra’ :type flow: dict :param types: A dict of the trial type buttons for this block. Contains three lists: ‘shapes’, ‘text’, and ‘labels’ :type types: dict :return: :rtype:

stimSettingsDlg(lastSet=[], redo=False, screen='all')

Settings relating to stimulus presentation. Indexes from the dialog (non-HPP version):

0 = screenWidth: Width of stim window

1 = screenHeight: Height of stim window

2 = Background color of stim window

3 = movieWidth: Width of movieStim3 object inside stim window. Future: Allows for movie default resolution?

4 = movieWidth: Height of movieStim3 object inside stim window

5 = freezeFrame: If the attention-getter is used (for a given trial type), this is the minimum time the first frame of the movie will be displayed after the attention-getter finishes.

6 = screenIndex: Which screen to display the stim window on.

7 = expScreenIndex: Which screen to display the experimenter window on

Parameters:
  • lastSet (list) – Optional. Last entered settings, in case dialog needs to be presented again to fix bad entries.
  • redo (boolean) – Are we doing this again to fix bad entries?
  • screen (string) – Optional. For HPP, lets you set for just the individual screen the settings apply to.
Returns:
Return type:
toHPP()

A function that converts ST or PL experiments to HPP. Always a little complicated.

Returns:
Return type:
toPL()

A function that converts ST or HPP to preferential looking. ST to PL is NBD. HPP is more of a challenge. :return: :rtype:

toST()

A function that converts PL or HPP to single-target. PL to ST is NBD. HPP is more of a challenge.

Returns:
Return type:
trialTypeDlg(trialType='TrialTypeNew', makeNew=True, prevInfo=[])

Dialog for creating OR modifying a trial type. Allows you to set the maximum duration of that trial type as well as remove movies from it, and also set whether the trial type is gaze contingent. Now also sets whether the study should auto-advance into this trial and whether the built-in attention-getter should be used.

The dialog by default outputs a list with 12 items in it. 0 = trial type name

1 = Maximum duration of trials of this type

2 = Gaze-contingent trial type?

3 = Maximum continuous looking-away to end trial of type

4 = Minimum on-time (cumulative)

5 = auto-redo trial if minimum on-time not met?

6 = on-time deadline

7 = duration criterion rather than on-time

8 = Auto-advance into trial?

9 = Attention-getter selection

10 = End trial on movie end or mid-movie

11 = inter-stimulus interveral (ISI) for this trial type

12 = Maximum on-time (single use case, for new gaze contingent trial type mode).

[if movies assigned to trial type already, they occupy 13 - N]

Parameters:
  • trialType (str) – Name of the trial type
  • makeNew (bool) – Making a new trial type or modifying an existing one?
  • prevInfo (list) – If user attempts to create an invalid trial type, the dialog is re-opened with the previously entered information stored and restored
Returns:
Return type:
univSettingsDlg()

Settings that apply to every PyHab study regardless of anything else.

0 = prefix: The prefix of the launcher and all data files.

1 = blindPres: Level of experimenter blinding, 0 (none), 1 (no trial type info), or
2 (only info is whether a trial is currently active.
2 = nextFlash: Whether to have the coder window flash to alert the experimenter they need to manually trigger
the next trial

3 = durationInclude: Trial duration calculations include last gaze-off or not

4 = loadSeparate: New setting in 0.9.4, movie playback issues have created a situation where some (but not all)
experiments might benefit from going back to the old ways of loading one movie file for each individual instance of a trial, rather than trying to load one movie file and load it once. This setting controls whether that happens.
5 = eyetracker: New in 0.10.4, Tobii integration (which is much more seamless than alternatives). Can be set
to simply record eye-tracking info OR to control the experiment as a replacement for a human coder. (0/1/2)
Returns:
Return type: