Home Reference Source

Developing New Conditions

For Researchers

If you are planning to add a new condition that uses the base experiments already supported, please provide the following information.

To see what identifiers are supported, refer to the page here.

Example

Let us say you want to make a new condition for a JND Design experiment that changes point size on each grouping of the Design trial structure. This is what your information would look like:

For Developers

(1) Add to config

name_of_new_condition: {
    experiment: [],
    graph_type: [],
    trial_structure: [],
    balancing: "",
    display_name: "New condition name",
    display_info: {
        description: "",
        researcher: "",
        developer: ""
    }
}

If we use the example from above, the JS object looks like this:

small_point_sizes: {
    experiment: ["jnd"],
    graph_type: ["scatter"],
    trial_structure: ["design"],
    balancing: "latin_square",
    display_name: "Small Point Sizes",
    display_info: {
        description: "Standard JND scatter plot condition, except point sizes vary between" +  
                     "5 - 13 pixels for each 0.3, 0.6, 0.9 base correlation grouping.",
        researcher: "Caitlin Coyiuto",
        developer: "Caitlin Coyiuto"
    }
}

(2) Add subconditions

An example of a new object holding all subconditions should look something like this:

name_of_new_condition:
[
    {attribute1: ___, attribute2: ____}, //first subcondition

    {attribute1: ___, attribute2: ____}, //second subcondition

    {attribute1: ___, attribute2: ____}, //third...

    {attribute1: ___, attribute2: ____},

    .....                                //Number of rows = number of rows or subconditions in trial structure
]

Using the example from above, we are just changing point_size, so we need to define each of the sizes on every subcondition. Note that the subconditions for a JND Design already has point_size (look at JND_BASE["design"]). By re-defining the point_size attribute here, you are OVERRIDING the point_size variable in the base. Also note that the number of rows below are equal to the number of rows in JND_BASE["design"].

small_point_sizes:
    [
    {point_size: 5},

    {point_size: 5},

    {point_size: 5},

    {point_size: 7},

    {point_size: 7},

    {point_size: 7},

    {point_size: 9},

    {point_size: 9},

    {point_size: 9},

    {point_size: 11},

    {point_size: 11},

    {point_size: 11},

    {point_size: 13},

    {point_size: 13},

    {point_size: 13},
    ]

Again, depending on your trial structure, the application will merge the constants you define in CONDITIONS with any that are defined in the BASE to get all attributes for the subconditions. So for this example, all the subconditions for small_point_sizes is whatever is listed in the JND_BASE["design"], plus whatever is defined in the CONDITIONS variable. 

[
    {distribution_type: "gaussian", base_correlation: 0.3, error: 0.0001, max_step_size: 0.01, 
    converge_from_above: true, initial_difference: 0.1, num_points: 100, mean: 0.5, SD: 0.2, 
    num_SD: 2.5, point_color: 'BLACK', axis_color: 'BLACK', text_color: 'BLACK', 
    feedback_background_color: 'WHITE', background_color: 'WHITE', point_size: 5}, // <-- point_size is now   
                                                                                   // overriden (usually for JND 
                                                                                   // design, point_size = 6)

    {distribution_type: "gaussian", base_correlation: 0.6, error: 0.0001, max_step_size: 0.01, 
    converge_from_above: true, initial_difference: 0.1, num_points: 100, mean: 0.5, SD: 0.2, 
    num_SD: 2.5, point_color: 'BLACK', axis_color: 'BLACK', text_color: 'BLACK', 
    feedback_background_color: 'WHITE', background_color: 'WHITE', point_size: 5},
    .....
]

(3) Update instructions

Automatically, the application will use the default instructions specified for each experiment in experiments-config.js if no instructions are specified for the condition. For example, for JND:

  jnd : {
    .....
    instructions: {
      default_images: ["scatter_1.png", "scatter_2.png"],
      default_html: `
        <div align = 'center' style='display: block' > 
          <p>In this experiment, two graphs will appear side-by-side.
                <br> Indicate which graph is more correlated by pressing the Z or M key. 
                <br> Press any key to continue.
                </p>
                <div style='float: left; margin-right: 5vw'>
                  <img style= 'width: 20vw' src='${ADDRESS}/img/instructions/jnd/image1.png'></img>
                  <p class='small'><strong>Press the Z key</strong></p>
                </div>
                <div style='float:right; margin-left: 5vw'>
                  <img style= 'width: 20vw' src='${ADDRESS}/img/instructions/jnd/image2.png'></img>
                  <p class='small'><strong>Press the M key</strong></p>
                </div>
              </div> 
            `    
    },
    ......

The default images are scatter_1.png and scatter_2.png, which replace image1.png and image2.png.

If you do not want to use the default images or default html, you will need to tack on an additional instructions key to the conditions object in conditions-config.js.

name_of_new_condition: {
  experiment: [],
  graph_type: [],
  trial_structure: [],
  balancing: "",
  display_name: "New condition name",
  display_info: {
    description: "",
    researcher: "",
    developer: ""
  },
  instructions: {
    name_of_experiment: {
      custom_html: ``
      // OR 
      custom_images: ['image1.png', 'image2.png' ... ]
    }
  }
}

Inside the instructions object, you must supply either:

Using the small_point_sizes example:

small_point_sizes: {
  experiment: ["jnd"],
  graph_type: ["scatter"],
  trial_structure: ["design"],
  balancing: "latin_square",
  display_name: "Small Point Sizes",
  display_info: {
    description: "Standard JND scatter plot condition, except point sizes vary between" +  
           "5 - 13 pixels for each 0.3, 0.6, 0.9 base correlation grouping.",
    researcher: "Caitlin Coyiuto",
    developer: "Caitlin Coyiuto"
  },
  instructions: {
    jnd: {
      custom_images: ['small_point_1.png', 'small_point_2.png']
    }
  }
}

(4) Update docs

The docs dynamically gets all the condition data specified in the config files. However, it needs to be compiled to be re-updated.

Run this in the command line:

./node_modules/.bin/esdoc

And check that your condition exists in the Conditions tab.