1 of 4

Tags referencing files

The first and most common type of tag is a tag that directly references a file (image, audio, or video) on your computer. These tags are defined before the beginning of the first phase or step, and once defined, cannot be changed later in the protocol: they are linked to only that particular file.

LET <tag> = "<filepath>"

LET dog_image = "C:\Users\ldev\Desktop\ExampleStudy\dog.png"
LET dog_audio = "C:\Users\ldev\Desktop\ExampleStudy\look_at_the_dog.wav"
LET baby = "C:\Users\ldev\Desktop\ExampleStudy\baby.wmv"
LET checkerboard = "C:\BITTSy-Stimuli\checkerboard.wmv"

Filepaths

To easily find the complete file path for your stimuli:

Open the folder where the files are located
Right-click on a file and select Properties
The filepath is shown under "location" and can be copied directly

File paths for stimulus files used in BITTSy cannot contain any whitespace characters. (This will cause a validation error in BITTSy.) If any of the folder names within your filepath contain spaces, you will need to rename them within Windows File Explorer. If your files are stored under a particular user account that contains a space, you will also need to change the username to not include a space.

There is no requirement for stimuli files to be located in the same folder as protocol files, so if you prefer to have spaces in names for other folders (or don't want to disrupt file references for other experimental software on your computer), you can store stimuli files for BITTSy in a separate, dedicated set of folders, such as directly on the C: drive.

LET checkerboard = "C:\BITTSy-Stimuli\checkerboard.wmv"

TYPEDLET and LINKED tags

When you set up these types of tags with LET statements, BITTSy doesn't immediately store information about what kind of file it is (image, audio, or video) other than by storing the file path and extension. There is a special way to declare a tag that allows you to tie the tag name to a particular stimulus type.

TYPEDLET <type> <tag> = "<filepath>"

Here, <type> can be image, audio, or video.

Tags defined with TYPEDLET (as opposed to LET) can be used in any type of group, but only tags defined with TYPEDLET can be made into LINKED tags.

LINKED tags make it easier to reference pairs of stimuli that should be presented together. They are useful in cases where:

you will want to present particular, limited combinations of stimuli (e.g. each image stimulus goes with one or two possible audio files out of a much larger set in the study, and would never be presented with any of the others)
stimuli in the pairings are consistently of different types (image/audio/video) [no two stimuli of the same type can be LINKED together]
you want to randomize presentation order across stimulus pairs rather than randomizing across stimulus types (such as audio and image) independently of each other

TYPEDLET image dog_image = "C:\Users\ldev\Desktop\ExampleStudy\dog.png"
TYPEDLET audio dog_audio = "C:\Users\ldev\Desktop\ExampleStudy\look_at_the_dog.wav"

LINKED dog = {dog_image, dog_audio}

LINKED tags allow you to refer to their paired components by the same tag name (dog in the example above). For more, see the section on using LINKED tags in action statements.

Preferential looking (PLP) studies generally require paired audio and visual stimuli. However, when creating video files is an option, video stimuli with an embedded audio track are a better choice for PLP studies in BITTSy than using separate or LINKED audio + visual media files. When presenting a video file, the beginning of the visual display and audio tracks are wholly simultaneous, but presenting separate visual and audio files can theoretically result in a slight delay between the start of each file. This delay is not generally perceptible, but it has the potential to be a problem when timepoints (such as the onset of a target word) must be completely predictable and consistent.

Groups

Groups are tags that refer to a set of other tags. The tags within the group could refer directly to particular stimulus files, or they could be groups themselves.

LET <tag> = {<tag1>, <tag2>, <tag3>, ... <tagN>}

Tags within a group should be separated by a comma and a space, and there should be no spaces between the opening curly brace and first tag name or the last tag name and the closing curly brace.

Groups refer to tags that have been previously defined, and create a hierarchical structure.

LET dog = "C:\BITTSy-Stimuli\animals\dog.png"
LET cat = "C:\BITTSy-Stimuli\animals\cat.png"
LET snake = "C:\BITTSy-Stimuli\animals\snake.png"
LET turtle = "C:\BITTSy-Stimuli\animals\turtle.png"

LET mammals = {dog, cat}
LET reptiles = {snake, turtle}

LET animals = {mammals, reptiles}

Below is a visualization of the relationships of tags in the above example.

In this example, dog, cat, snake, and turtle refer directly to files (the tag type covered in the previous section). The tags mammals, reptiles, and animals are all groups - but while the members of mammals and reptiles are tags referring to files, animals is a group of other groups.

Groups allow for random selection from within a set of tags, which can be used iteratively to select subsets of stimuli before selecting a particular stimulus from the final subset. Ultimately, the purpose will be to present a selected stimulus using an action statement. In order to select through a consistent number of steps, no matter which tags from within groups are chosen, the tags that are contained in a single group should be at the same level in the tag hierarchy. For example, if we wanted to make a group that was the set of the above animals that have legs, we could define:

LET has_legs = {dog, cat, turtle}

But we would NOT use:

LET has_legs = {mammals, turtle}

because if mammals is selected first from the group, there is another layer of selection required before finally presenting the stimulus than if we selected turtle initially. BITTSy cannot proceed through different numbers of selection steps based on what is chosen.

The above point is especially important in protocols using loops. But if your selections from your group are not inside a loop, and are occurring in a fixed order (such that you know when you're selecting another group and when you're selecting a tag) you can construct a group with tags at different levels in the tag hierarchy - there's nothing stopping you. But the fix below always works.

In cases where you really want something more like {mammals, turtle}, you can use "dummy groups," which contain only one item, to get around this issue.

LET dog = "C:\BITTSy-Stimuli\animals\dog.png"
LET cat = "C:\BITTSy-Stimuli\animals\cat.png"
LET snake = "C:\BITTSy-Stimuli\animals\snake.png"
LET turtle = "C:\BITTSy-Stimuli\animals\turtle.png"

LET mammals = {dog, cat}
LET testudines = {turtle}

LET has_legs = {mammals, testudines}

Note: You can go back and forth between defining tags that reference files or tags that are groups as you write protocols. However, whenever a group is defined, all of its component tags must have already been defined earlier in the protocol. BITTSy validates protocols by reading line by line, and if a tag name is referenced inside a group before it is defined through a LET statement, this will cause a validation error.

Groups of SIDES

There is one special type of group that doesn't contain tags as its elements - it contains side names. This allows for random selection not just of stimulus files (like other groups), but also of presentation location.

LET <tag> = {<side1>, <side2>, ... <sideN>}

LET stim_locations = {LEFT, CENTER, RIGHT}
LET targetsides = {LEFT, RIGHT}

The side names that can be used in groups should be previously defined in the starting SIDES definition.

Dynamic tags

The tag types discussed thus far must be set up in the opening definitions section of your protocol, before the execution of the first STEP, and once they are defined, what they refer to cannot be changed. Dynamic tags are tags that can be defined later in your protocol and used to refer to the result of a selection statement when a tag is chosen from a group. They don't have a fixed identity as "meaning" any other particular tag; rather, they work as a placeholder tag that can still be reassigned to a new item later on in the execution of the protocol.

Dynamic tags are explained further in the section on randomization and selection from groups. But they are another type of tag that, once defined, work in the same way as the tags discussed thus far. They can reference a particular stimulus file or they can reference a group, and they can be used in selection statements or action statements in the same way as static tags.