7 New protocols and tasks

There are a number of elements the tasks need to work well with jsPsychR, so we recommend to use one of the systems we have developed.

For example, with jsPsychMaker::create_protocol(), you can use tasks we already developed, and/or create new tasks defining their parameters in csv/excel files. The tasks will be part of a fully working protocol. You will need R 4.2 or higher to use it.

create_protocol() can:

Loop through the subfolders in folder_tasks to create one task per subfolder
Copy canonical_protocol_clean to folder_output
Include in the protocol any tasks in canonical_tasks
Modify config.js to add all the tasks created and selected
Modify index.html to inlude only the plugins those tasks will use
Modify index.html to add the media those task will use
Check task names are OK: no spaces, -, _, do not start by a number, …
Check names of all trialid’s are OK (NAMETASK_NUMBER, e.g. MYTASK_001)
Check only one csv or xls/xlsx file per folder
Check plugins used exist in jsPsych-6/plugins
Check we have the necessary parameters (WIP)
Delete files of plugins not used

create_protocol() cannot yet:

Modify config.js to adapt all_conditions to the experimental tasks added
Use shiny app to edit the local config.js

7.1 New protocols

You can create a new protocol in seconds, choosing from the tasks we already have available.

Make sure you have the last version of jsPsychMaker, installing from Github:

if (!require('pak')) install.packages('pak'); pak::pkg_install("gorkang/jsPsychMaker")

Check if there are new tasks available in a new version of the Github package:

jsPsychMaker::check_NEW_tasks_Github()

7.1.1 List available tasks

You can list available tasks to choose from. You have more details in the section available-tasks. You can choose between available tasks for jsPsych 6.3 and jsPsych 7.3 with jsPsych_version.

  jsPsychMaker::list_available_tasks(jsPsych_version = 6)

$tasks
  [1] "ACE"                 "AIM"                 "AntiBots"           
  [4] "APrioriDiagnostic"   "APrioriScreening"    "Bank"               
  [7] "BART"                "BDI"                 "BNT"                
 [10] "bRCOPE"              "CAMIR"               "CAS"                
 [13] "CDRISC10"            "CEL"                 "CIT"                
 [16] "CMApost"             "CMApre"              "Consent"            
 [19] "ConsentAudio"        "ConsentHTML"         "Cov19Q"             
 [22] "COVIDCONTROL"        "CRQ"                 "CRS"                
 [25] "CRT7"                "CRTMCQ4"             "CRTv"               
 [28] "CS"                  "CTS2"                "CTT"                
 [31] "DASS21"              "DEBRIEF"             "DEMOGR"             
 [34] "DES"                 "DGLS"                "DMW"                
 [37] "EAR"                 "ECRRS"               "EmpaTom"            
 [40] "EQ"                  "ERQ"                 "ESM"                
 [43] "ESV"                 "ESZ"                 "fauxPasEv"          
 [46] "FDMQ"                "FKEA"                "GASP"               
 [49] "GBS"                 "GHQ12"               "Goodbye"            
 [52] "HRPVB"               "HRPVBpost"           "IBT"                
 [55] "ICvsID"              "IDQ"                 "IEC"                
 [58] "INFCONS"             "IRI"                 "IRS"                
 [61] "ITQ"                 "LoB"                 "LOT"                
 [64] "LSNS"                "MAIA"                "MAIAY"              
 [67] "MCQ30"               "MDDF"                "MDMQ"               
 [70] "MIS"                 "NARS"                "OBJNUM"             
 [73] "OTRASRELIG"          "PBSr"                "PERMA"              
 [76] "PPD"                 "PRFBM"               "PRFBMpost"          
 [79] "PSC"                 "PSETPP"              "PSPPC"              
 [82] "PSS"                 "PVC"                 "PWb"                
 [85] "REI40"               "Report"              "RMET"               
 [88] "RobToM"              "RSS"                 "RTS"                
 [91] "SASS"                "SBS"                 "SCGT"               
 [94] "SCSORF"              "SDG"                 "SDQ20"              
 [97] "SILS"                "SPM2"                "sProQOL"            
[100] "SRA"                 "SRBQP"               "SRSav"              
[103] "STAI"                "STAIC"               "SWBQ"               
[106] "UCLA"                "WaisMatrices"        "WaisMatricesES"     
[109] "WaisWorkingMemory"   "WaisWorkingMemoryES" "WEBEXEC"            

$tasks_js
  [1] "ACE.js"                 "AIM.js"                 "AntiBots.js"           
  [4] "APrioriDiagnostic.js"   "APrioriScreening.js"    "Bank.js"               
  [7] "BART.js"                "BDI.js"                 "BNT.js"                
 [10] "bRCOPE.js"              "CAMIR.js"               "CAS.js"                
 [13] "CDRISC10.js"            "CEL.js"                 "CIT.js"                
 [16] "CMApost.js"             "CMApre.js"              "Consent.js"            
 [19] "ConsentAudio.js"        "ConsentHTML.js"         "Cov19Q.js"             
 [22] "COVIDCONTROL.js"        "CRQ.js"                 "CRS.js"                
 [25] "CRT7.js"                "CRTMCQ4.js"             "CRTv.js"               
 [28] "CS.js"                  "CTS2.js"                "CTT.js"                
 [31] "DASS21.js"              "DEBRIEF.js"             "DEMOGR.js"             
 [34] "DES.js"                 "DGLS.js"                "DMW.js"                
 [37] "EAR.js"                 "ECRRS.js"               "EmpaTom.js"            
 [40] "EQ.js"                  "ERQ.js"                 "ESM.js"                
 [43] "ESV.js"                 "ESZ.js"                 "fauxPasEv.js"          
 [46] "FDMQ.js"                "FKEA.js"                "GASP.js"               
 [49] "GBS.js"                 "GHQ12.js"               "Goodbye.js"            
 [52] "HRPVB.js"               "HRPVBpost.js"           "IBT.js"                
 [55] "ICvsID.js"              "IDQ.js"                 "IEC.js"                
 [58] "INFCONS.js"             "IRI.js"                 "IRS.js"                
 [61] "ITQ.js"                 "LoB.js"                 "LOT.js"                
 [64] "LSNS.js"                "MAIA.js"                "MAIAY.js"              
 [67] "MCQ30.js"               "MDDF.js"                "MDMQ.js"               
 [70] "MIS.js"                 "NARS.js"                "OBJNUM.js"             
 [73] "OTRASRELIG.js"          "PBSr.js"                "PERMA.js"              
 [76] "PPD.js"                 "PRFBM.js"               "PRFBMpost.js"          
 [79] "PSC.js"                 "PSETPP.js"              "PSPPC.js"              
 [82] "PSS.js"                 "PVC.js"                 "PWb.js"                
 [85] "REI40.js"               "Report.js"              "RMET.js"               
 [88] "RobToM.js"              "RSS.js"                 "RTS.js"                
 [91] "SASS.js"                "SBS.js"                 "SCGT.js"               
 [94] "SCSORF.js"              "SDG.js"                 "SDQ20.js"              
 [97] "SILS.js"                "SPM2.js"                "sProQOL.js"            
[100] "SRA.js"                 "SRBQP.js"               "SRSav.js"              
[103] "STAI.js"                "STAIC.js"               "SWBQ.js"               
[106] "UCLA.js"                "WaisMatrices.js"        "WaisMatricesES.js"     
[109] "WaisWorkingMemory.js"   "WaisWorkingMemoryES.js" "WEBEXEC.js"

7.1.2 Create a protocol

This will create a fully working protocol in folder_output. You can edit config.js to adapt the protocol to your needs. See experiment configuration for more details.

  jsPsychMaker::create_protocol(canonical_tasks = c("AIM", "EAR", "IRI"),
                                folder_output = "~/Downloads/protocol999", 
                                launch_browser = TRUE,
                                jsPsych_version = 6)

7.2 New tasks

7.2.1 Create tasks

You can create new tasks with create_task() using csv or xls/xlxs files for the items, and html files for the instructions. But we recommend you use create_protocol() instead, so the tasks will be part of a fully working protocol, and testing them will be a breeze.

There are some things to take into account:

folder_tasks expects a folder with sub-folders with the ShortName of tasks (ShortName is an example of the ShortName of a task, for example, MyTask). Inside, they need to have one ShortName.csv or ShortName.xls/xlxs file and *_instructions.html files. Use jsPsychMaker::copy_example_tasks(destination_folder = "~/Downloads/TEST") to see a working example
The csv or xls/xlsx file (ShortName.csv or Shortname.xls/xlsx) needs to have an ID and plugin columns, and then columns by the name of parameters used in the plugin (e.g. if using the survey-text plugin, you will need the prompt parameter). If you need help with the plugins parameters, see the jsPsych 6.3 list of plugins
For each html file ending with _instructions.html or instructions#.html (# is a number), an instructions page will be created (e.g. ShortName_instructions.html, ShortName_instructions2.html, etc). If there is no html, a default page will be used.
For key questions (e.g. present this question only if participants responded “3”), you need to create a column named if_question and include a logical condition. For example:
- 1 != 25: Response to item 1 is NOT 25
- 3 == 20: Response to item 3 is 20
- 15 == yes: Response to item 3 is yes
If you use tasks with images, video or audio, make sure to include the files in a media/ folder, inside a subfolder with the name of the task. So, if your task name is ALL:
- Images: media/images/ALL
- Videos: media/videos/ALL
- Audio: media/audios/ALL
If you use a plugin with different options or alternatives (e.g. survey-multi-choice-vertical), the different response options will be the words or sentences separated by semi-colons (e.g. Yes, I am; No, I am not). If your options have semi-colons, you can to use the options_separator parameter to change the default.

You can run the fully reproducible example included in jsPsychMaker:

Install jsPsychMaker from Github and load library

if (!require('pak')) install.packages('pak'); pak::pkg_install("gorkang/jsPsychMaker")

Copy example tasks

This will copy a few example tasks that you use to adapt your tasks. For example, MultiChoice and Slider tasks, a key questions mini-task (IfQuestion), and an ImageButtonResponse task.

  jsPsychMaker::copy_example_tasks(destination_folder = "~/Downloads/ExampleTasks")

Create your protocol

  # Create protocol
  jsPsychMaker::create_protocol(folder_tasks = "~/Downloads/ExampleTasks/", 
                                folder_output = "~/Downloads/protocol999", 
                                launch_browser = TRUE)

7.3 HELP with new tasks

If you need help developing new tasks, you can open a new Issue in the jsPsychMaker Github.

We will ask you to add the details about the task in the NEW tasks document.

Once the task is implemented, our goal is to always end up having a sister task preparation script in jsPsychHelpeR. You can try to create the preparation script and do a Pull request, or ask for help opening a new Issue in the jsPsychHelpeR Github.

7.3.1 How to fill the NEW tasks document

NEW tasks document

First of all, you will need the original paper where the task was validated/translated to have all the details at hand. Please, send us a link to the paper.

The best way to fill the NEW tasks document is:

Find a task similar to yours in the document Tareas jsPsychR where we have information about all the available tasks.
Copy/paste the information from all the tabs to the NEW tasks document and adapt it.

Try to be as consistent as possible. For example, when entering the information about numeric conversion in the Puntajes_items tab:

All the cells must be:  
1 = Mucho  
2 = Poco  
...

DO NOT do things like:

1: Mucho  
1 Mucho  
1 pto = Mucho  
Mucho 1

Please, make sure you fill out all the details in all the tabs.