Getting Started¶

Whether you are new to coding or just new to FindingFive, don't worry, we've got you covered! This page will walk you through basic data structures and syntax. Here's what you need to know:

Based on JSON¶

FindingFive's study grammar uses an interface based on something called JavaScript Object Notation (JSON). Previous experience with JSON is helpful, but absoutely not necessary. If you've never heard of JSON, that's okay! Keep reading.

Data Structures¶

Property-Value Pairs¶

At the core of defining a FindingFive study is the concept of property-value pairs, which provide instructions to FindingFive for storing and rendering the information you supply it. They are the basic building blocks of any study.

In a property-value pair, the property represents an attribute of an object. Objects in this case include things like stimuli, responses, and blocks. Attributes of those objects include things like the content of a stimulus or its duration of display, or the trials of a block. The value represents the specific value of that attribute.

You can alter the behavior of an object by changing the value for a specific property of that object (e.g., you supply text content for a stimulus, or specify the number of seconds for the stimulus to be displayed). For example, in the property-value pair "delay": 50, the property is "delay" (an attribute that delays the onset of a stimulus) and the value is 50 (the number of seconds to delay the onset).

Dictionaries¶

Property-value pairs always occur within the context of other property-value pairs, never in isolation. The next important concept is a dictionary, which is a collection of property-value pairs. So, for example, when you create a blank stimulus, you provide values, at minimum, for two separate properties ("type" and "content"), to change different attributes of the stimulus:

{
    "type": "text",
    "content": "Welcome to my Experiment :)"
}

Here, you tell FindingFive that the "type" of stimulus is "text", and the "content" of the stimulus (i.e., the text you want to display) is "Welcome to my Experiment :)". Both "type": "text" and "content": "Welcome to my Experiment :)" are property-value pairs, and the entire code snippet is a dictionary. Note that the collection of property-value pairs is placed inside of curly braces ({}). This is what defines a complete dictionary.

Types of Values¶

While the names of properties are always quoted strings (e.g., "duration"), values can be of many different data types, including:

string. Sequence of zero or more Unicode characters surrounded by quotation marks (e.g., "Welcome to my Experiment :)" )
number. Numerical characters only. No quotation marks. (e.g., 50)
boolean. True or false value. No quotation marks. For example, consider the following definition of a response:

{
  "type": "choice",
  "choices": ["A", "B", "C", "D"],
  "multi_select": true
  // Setting the property `"multi-select"` to `true` allows participants
  // to select more than one option (from "A", "B", "C", or "D").
}

list. A list of one or more items surrounded by square brackets. For example, in the above response definition, the value of the property "choices" is a list of four strings ["A", "B", "C", "D"].
dictionary. A series of property-value pairs. Using a dictionary as a value results in nested property-value pairs. For example, consider the following value of "stimuli_pattern":

"stimulus_pattern": {
  "order": "ascending",
  "attribute": "length"
}

In this case, the value of the property "stimuli_pattern" is a dictionary with two properties "order" and "attribute".

Required v. Non-required Properties¶

When defining top-level properties (which are discussed in the following section), it is possible to specify values for a number of different properties. However, in many cases, this is optional; you are required to provide values only for certain properties (e.g., "type"). If you do not specify a value for an optional property, it will take on its default value, which is designed to fit the majority of use cases. The FindingFive Grammar Documentation for each top-level property, found on the sidebar, clearly indicates which properties are optional and which are required, as well as their default values.

Top-level Properties¶

A FindingFive study consists of four top-level properies that specify the content and logic of a behavioral study: stimuli, responses, trial templates, and procedure. 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.

You build top-level properties by progressively building on lower-level properties (e.g., property-value pairs). How does this work? See the code example below.

Syntax¶

The 4 C's¶

Just like when you write in natural language, when coding an experiment on FindingFive, there are certain rules governing the structure and organization of code that you must follow. When writing the code for your experiment, keep in mind the four C's:

Colon. Properties and values are separated by a colon.
Comma. Series of property-value pairs are separated by commas, but no commas follow the final pair in the series.
Curly braces {}. Curly braces are the 'bookends' that enclose and define all objects.
Closing brackets and braces. Opening curly braces { or square brackets [ must always be followed by closing braces } or brackets ]. You could think of them as punctuation; they separate different ideas and parts of sentences, and without them, it is difficult to tell where one idea ends and another begins.

Breaking Down a Code Example¶

Note how the following definition of two trial templates ("Introduction" and "Task") adheres to the 4 C's.

{
    "Introduction": {
        "type": "instruction",
        "stimuli": ["Intro_Text"]
    },

    "Task": {
        "type": "basic",
        "stimuli": ["stim1","stim2", "stim3", "stim4","stim5"],
        "responses": ["response1"]
    }
}

What does all of this code mean? You could think of it like an outline, where information is organized at different levels.

At the highest level, there is an object, which represents all trial templates for the experiment, (implicitly) defined by the outer curly braces.
- Inside the object, there are two trial templates, "Introduction" and "Task".
- Within "Introduction", there are two property-value pairs:
  1. A property named "type" with the value "instruction"
  2. A property named "stimuli" with a list value ["Intro_Text"]
- Within "Task", there are four property-value pairs:
  1. A property named "type" with the value "basic"
  2. A property named "stimuli" with a list value ["stim1","stim2", "stim3", "stim4","stim5"]. Inside the list, there are 5 objects representing individual stimuli.
  3. A property named "responses" with a list value ["response1"]

More Information¶

For more information on the top-level properties (stimuli, responses, trial templates, and procedure), see the sidebar. The FindingFive Grammar Documentation covers each one in detail, including the types and options available for customizing each property to fit the needs of your study.

Now that you've completed the Getting Started Guide, you may want to head over to the Crash Course, for practice creating and running a study.