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, and PyHabClassPL.

addHabBlock(makeNew=True)

Creates either a hab trial type, or a hab trial block.

Trial type dialog:

0 = Maximum duration

1 = Maximum continuous off-time

2 = Minimum on-time

[If stimulus files associated with type, these occupy 3-N]

3/-3 = Auto-advance into trial

4/-2 = Select attention-getter

5/-1 = Inter-stimulus interval (ISI)

Parameters:makeNew – Making a new or modifying
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:
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. You can make blocks of other blocks! 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

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?
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()

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.

Returns:
Return type:
condSetter(shuffleList, cond='NEW', ex=False)

One dialog per trial type. Each dialog has a list of all the movies in that type This is not intuitive under the hood. The output of this is a dict with a list of movies, in order, for each trial type. This makes it slightly more human-intelligible than the previous system, which had a list of indexes

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
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(lastSet=[], redo=False)

Dialog for settings relating to habituation criteria:

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

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

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

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

4 = habThresh (threshold for N above threshold)

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

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

7 = metCritStatic (static or moving window?)

8-N = Which trials to calculate hab over for multi-trial blocks. Hab selected by default, populated only if the block structure is used

Parameters:
  • lastSet (list) – If information entered is invalid and the dialog needs to be shown again, this allows it to remember what was previously entered.
  • redo (boolean) – Checking if redoing last setting
Returns:

Return type:

lastPalettePage()

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

loadFlow(tOrd, space, locs, overflow, 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.
  • 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, 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
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:

makeHabTypeDlg(makeNew, prevSet=[])

A function for creating a habituation trial type, rather than multi-trial block.

0: Maximum duration 1: Maximum off-time 2: Minimum on-time 3-N: Stimuli added to trial type -3: Auto-advance -2: Attention-getter -1: ISI

Parameters:makeNew (bool) – Making a new trial or revising 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

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)

Settings relating to stimulus presentation. Indexes from the dialog

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?
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 8 items in it. 0 = trial type name

1 = Maximum duration of trials of this type

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

2/-7 = Gaze-contingent trial type?

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

4/-5 = Minimum on-time to enable off-time criterion (not continuous)

5/-4 = Auto-advance into trial?

6/-3 = Attention-getter selection

7/-2 = End trial on movie end or mid-movie

8/-1 = inter-stimulus interveral (ISI) for this trial type

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 = prefLook: Whether the study is preferential-looking or single-target.

3 = nextFlash: Whether to have the coder window flash to alert the experimenter they need to manually trigger
the next trial
Returns:
Return type: