Overview

A study specification is a document that describes the content and logic of a behavioral study. Here we provide an introductory overview of the grammar underlying a study specification, especially for researchers who haven’t had much experiences with programming.

If you are absolutely a programming guru, the following sentence will summarize most of the content on this page:

A study sepcification is a JSON representation describing a study, with certain properties recognized as keywords, and additional human-friendly features such as commenting.

Basic concepts

A study specification consists of nested property-value pairs that describe the content and runtime logic of a study. For example, when you create a study using a blank template on FindingFive, it consists of four property-value pairs with values to be defined by the researcher:

{
    "stimuli": {
        // define stimuli here
    },
    "responses": {
        // define responses here
    },
    "trial_templates": {
        // define how stimuli and responses comprise different trials
    },
    "procedure": {
        // define how trials are organized into blocks or using other procedures
    }
}

Note the use of double quotation marks in an study specification.

Top-level properties

A study specification requires four top-level properties stimuli, responses, trial templates, and procedure (click on the names to see detailed documentation of each property). These four components form an intuitive hierarchy: stimuli and responses are the basic elements in a study, trial templates define which and how stimuli and responses are used in each trial, and finally, the procedure defines how trials are organized in a study.

Property-value pair

A property-value pair is an object that specifies some value for some property. For example, in the above study specification, we have defined four different properties, stimuli, responses, trial_templates, and procedure.

Dictionary

A set of property-value pairs, separated by a comma , and enclosed by brackets {}, is a dictionary. For example, a study specification is just one big dictionary.

Types of values

The names of properties are always quoted strings (e.g., "stimuli"). The value of a property, however, can be of many different data types, including:

  • dictionary, which results in the case of nested property-value pairs. For example, consider the following value of "stimuli":

    "stimuli": {
        "training-prompt": {
            "type": "text",
            "content": "Please listen carefully to the next sentence"
        }
    }
    

    In this case, the value of the property stimuli is a dictionary with only one property named training-prompt.


  • string. For example, in the code snippet above, the stimulus training-prompt has a property named type, whose value is a simple string text (i.e., "type": "text").

  • boolean, true or false, without quotation marks. For example, consider the following definition of a response:

    "response1FB": {
        "type": "choice",
        "choices": ["Correct", "Wrong"],
        "feedback": true
    }
    

    Setting the property "feedback" to true turns on trial-by-trial feedback.


  • list. For example, in the above response definition, the value of the property "choices" is a list of two strings, representing the options on a two-alternative forced choice trial.