Welcome to FindingFive's Getting Started Guide!
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:
FindingFive's study grammar uses a JavaScript Object Notation (JSON) based interface, so previous experience with JSON is helpful, but not necessary. If you've never heard of JSON, that's okay! Keep reading.
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 (e.g., the content, duration of display) of a digital object (e.g., a stimulus). You alter the behavior of the digital object by changing the value for that property (e.g., you supply text content or specify the number of seconds for the object to be displayed). For example, in the property-value pair ("delay": 50), delay is an attribute that delays the onset of a stimulus, according to the value supplied (50 seconds).
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 composed of collections 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, 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.
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".
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.
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.
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:
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.
"Introduction" and "Task".
Within "Introduction", there are two property-value pairs:
"type" with the value "instruction""stimuli" with a list value ["Intro_Text"]Within "Task", there are four property-value pairs:
"type" with the value "basic""stimuli" with a list value ["stim1","stim2", "stim3", "stim4","stim5"]. Inside the list, there are 5 objects representing individual stimuli."responses" with a list value ["response1"]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.