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={})

Changelist from 0.4:

MaxOff and minOn are now trial-type-specific

Now supports dynamic peak habituation criteiron and moving vs. fixed-window habituation evaluation.

Now supports different types of stimuli - Movies, images, audio, and images with audio.

Changed how stimuli are added to experiment - you now create a “stim library” and separately associate items in it with different trial types.

TODO: Add the ability to remove stimuli once added. Nonessential. TODO: Option for habituation over whole meta-trials not just the “hab” portion

addHabBlock(makeNew=True)

Creates a hab trial type, which consists of a hab trial plus, now, some other number of trials It essentially needs to create a sub-flow.

0 = Maximum duration

1 = Maximum continuous off-time

2 = Minimum on-time

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

3/-5 = Auto-advance into trial

4/-4 = Select attention-getter

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

6/-2 = Use sub-block structure?

7/-1 = Number of trial types in sub-block, including hab

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:
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
condMaker(rep=False, currPage=1)

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

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:

loadFlow()

This creates the array of objects in the study flow display

Returns:
Return type:
loadTypes()

This function creates the trial types palette

Returns:
Return type:
mainLoop()

Main loop of the whole program.

Returns:
Return type:
moveTrialInFlow(flowIndex)

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

Parameters:flowIndex (int) – The index in the flowArray of the trial being modified
Returns:
Return type:
quitFunc()

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

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:
setHabSubTrials(numHab)

Groups trial types into hab blocks. Hab blocks can have multiple trial types, but one must always be Hab. This function doesn’t care if you’ve made a hab block before, it just overwrites whatever exists. This is under the assumption that hab blocks will have few trials.

Parameters:numHab (int) – Number of trials in a hab block
Returns:
Return type:
showMainUI()

Main draw loop of the primary builder interface

Returns:
Return type:
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 = screenIndex: Which screen to display the stim window on.

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

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: