This is the repository created by Bradley C. Smith (BCS) to document one method of running an online experiment like this one: https://smithbradleyc.github.io/jsPsych_Online_Experiments/. This method uses jsPsych (a JavaScript library for running behavioural experiments in a web browser) to create the experiment, GitHub Pages to host the experiment, and a real-time FireBase database to collect participant's responses. All of these services can be used completely for free (as of April 2020). Anything written by someone other than BCS will be clearly tagged to that person with either a hyperlink to that person's GitHub account or with one of the tags below:
- Matt Cook: #MC
- Jackie Spear: #JS
- Matt Crump: #MJC
Below you will find a step-by-step explanation of how you can host your own experiment. It will not describe how to program your own experiment except as it pertains to collecting data (and granted credit through the SONA system) but all of the examples will use the jsPsych JavaScript library. In theory, you should be able to switch this library out for your personal favourite and this guide should still work for you; but I have not tested this.
I wrote this (April 2020) as a PhD student in Psychology at the University of Manitoba working in The Cognitive Science Laboratory.
At that time, I programmed an experiment for the class "Open and Collaborative Science" taught by Dr. Melanie Soderstrom (GitHub). That experiment can be found on the Open Science Framework (GitHub Repo). That project's GitHub repository includes a step-by-step guide for reproducing the experiment that will look a lot like the one included here. That's because I wrote that one and then adapted it here to be a somewhat more generalizable.
The goal of this repository is to document the method I used (and plan to continue using for the foreseeable future) to run online experiments. I hope to offer this explanation at a level so that even a novice GitHub user and/or novice programmer could run their own experiment (unfortunately I must leave creating the actual experiment for another tutorial). It is also a way to promote open science because this method facilitates open and collaborative science practices (using GitHub pages requires that the repository is made public).
I'm indebted to the creators of the jsPysch Library and countless others have posted their experiments using the jsPsych library online. In particular, I used code from The Experiment Factory (GitHub Pages), and Matt Crump's jspsychrexamples to help me learn how to structure and run my own jsPsych experiments. Thanks are also due to Danielle Navarro's xprmntr package and Matt Crump's vertical package. Although I didn't end up using either of these packages, they greatly informed the method I describe here (in fact, the instructions for using Google's FireBase is almost directly lifted from Crump's FirebaseDemo)
First, I'll give a conceptual overview of what this guide will cover in the Overall Summary section. Then, I'll give a detailed explanation of how to host your own experiments online in the Step-by-Step Guide.
The Step-by-Step Guide will walk you through:
- Downloading important software:
- Copying this example experiment:
- Running this example experiment:
- General Tips:
Keep in mind that there are many methods to accomplish any one of these steps and I have only described one. Just because you do it differently does not make it wrong, as long as it works.
Dependencies/things needed to for any step to work (packages/libraries/etc) will be described in the first section that they are important for. So, although I encourage you to skip to the sections relevant to you, if you skip a section it may include dependencies required for future steps. If it seems like you are missing something to get your experiment working I suggest backing up to make sure you have all of the software needed. In the future I may spend the time to include dependencies in all steps they are required for.
Here are several examples of experiments hosted on GitHub. These experiment's are officially "dead" meaning that you are free to test out the experiment without causing problems for the researchers hosting these experiments. Those that I know have used FireBase to save data are flagged with #FIREBASE. The host account of each example will be tagged:
- Contingency Practice Phase #BCS #FIREBASE
- What can we percieve in infant vocalizations?(Hosted by melsod written by #BCS) #FIREBASE
- Matt Crump's jsPsychrExamples #MJC
- Flanker Demo #MJC
- Stroop Demo #MJC
- Stroop Demo (multiple responses) #MJC
- Recognition Memory #MJC
- Stroop Demo with FireBase Demo #MJC #FIREBASE
- Jackie's Distinctiveness Experiment
- The Experiment Factory (They have their own system that looks like it would work well if you dived into it)
- LiveCode Example Experiment (See the Livecode Folder for an explanation of this experiment) #BCS #FIREBASE
- MORE EXAMPLES #HELP HERE
If you already have R and rStudio then skip to Other Code Editors. If not then follow the instructions below. My goal is to make all of the instructions so that you can follow them with no-exposure/minimal-exposure to R or programming in general. However, if you want to learn programming in R (and you should) I can recommend a couple free resources to get you going:
- The Pirate's Guide to R (Yes ... seriously, it is a good resource)
- Programming for Psychologists #MJC
-
In the first paragraph click download R
-
Choose a CRAN mirror geographically close to you (For Manitoba choose Manitoba Unix user Group)
-
Click on the Download link near the top of the page for your operating system
- Windows:
- Click on the link to "install R for the first time"
- Click on "Download R ... for Windows"
- Once the file is downloaded, open it and go through the installation process
- Mac: #JS
- Click on "Download R for (Mac) OS X"
- Click on the .pkg link, this will start the download
- Once the .pkg file is downloaded, open it, click continue, and follow the instructions
- When finished, move the installer to the trash
- Linux:
- #HELP HERE
- Windows:
-
You will not need or want to open this base program. Instead proceed to Downloading rStudio
-
Go to https://rstudio.com/
-
Near the top right hand side of the page, click download
-
Under the RStudio Desktop Open Source License option, click "Download"
-
Download the appropriate software for your operating system. Normally the website will recognize the appropriate choice and offer it under "Recommended for your system:"
-
Once the file is downloaded, open it and go through the installation process
-
Opening rStudio gives you access the R programming language, but in a nicer format than just opening the basic R program
-
However, if you are just following through this Step-by-Step then you will not need to open rStudio yet.
Personally, I use rStudio as a code editor for R, HTML, rMarkdown (including Latex and/or HTML), Javascript, Python, and even a little bit of C++. It is generally accepted as the best editor for R, but nothing else. So none of these extra code editors are needed for editing/coding your experiments or getting them online. However, some people will find them useful as code editors that are "better" than rStudio:
- Visual Studio
- NetBeans
- BBEdit #JS
- #HELP HERE
The easiest way copy this experiment is to fork this repository into your own GitHub account, and then clone it (so that it is saved locally on your machine). If you understand these instructions then you can skip to the section Running This Example Experiment, otherwise I'll explain how to do that:
If you already have a GitHub Account then skip to Fork the Repository, otherwise:
- Go to www.github.com
- Click the "Sign Up" button in the top right hand side of the site (or click here)
- Create a Username and provide the requested information
- Click "Select a Plan"
- Click "Choose Free" unless you have a reason to get the paid service
- Provide whatever level of information you want to GitHub and then scroll down and click "Complete setup"
- Verify your email address
- There is no need to "Create a new repository" if you do not want to
- Go to https://github.com/SmithBradleyC/jsPsych_Online_Experiments (but you're already here)
- Click on the "Fork" button near the top, right hand side of the page
- Wait for the repository to complete it's fork
- You now own your very own copy of this repository!
If you already have the GitHub Desktop Client then skip to Clone the Repository
-
Go to https://desktop.github.com/ and download the application
-
Install the application
-
Open application that you just installed
-
Sign in with your GitHub account
-
(Optional) you can learn about Git and GitHub with this tutorial
-
You can also avoid using the GitHub Desktop client by using the Git command line functions by downloading the program here https://git-scm.com/downloads, I will leave it up to you and Google to work through how to do it that way. It is too difficult to explain in this tutorial.
- Make a folder on your computer where you would like to save the repository
- In the GitHub Desktop program, click on the File menu (in the top, left hand corner)
- Click on Clone Repository
- Select the "GitHub.com" tab if it is not already selected
- Your repositories should be visible, assuming that you successfully signed into GitHub on the Desktop Client
- Select the YourGitHubUsername/jsPsych_Online_Experiments option
- Choose the local path where you want to save the repository (just below the repository options)
- Click the "Clone" button
- This saves a local copy of the repository on your device
Now that you have a local copy of the example experiment on your machine you can begin to make and save your own edits. When you save the edits they will only be saved on your local machine until you push them back to GitHub. You can use any code editing software that you like, even Notepad, but I'll be describing how I use rStudio. This helps keep the experiment/repository tidy.
The best way to keep organized in rStudio is to use R Projects. When you create an R Project in rStudio it creates a folder with the project name and every new file that you create and save within that rStudio session will be saved to the folder. The R Project also creates a .Rproj file. This is the core of the R Project. It will save data between sessions and is the pointer for your "working directory" (meaning that calls to other files will be in reference to the .Rproj file). For more information on R Projects see here or one of the R resources I pointed out in the Download Important Software section. Many of the functions/files I have in my example repository rely on being run inside an R Project.
The next section will walk you through opening the local repository, describing the files within the repository, making a small change to the experiment and testing the experiment locally.
-
Open the local repository folder (there should be a button in the middle of the screen in the GitHub Desktop application)
-
Open jsPsych_Online_Experiments.Rproj with rStudio
-
You will/may have 4 sections/quadrants to your screen when you open rStudio:
- Top left: file open in rStudio (this may not open your first time meaning the console will take up the whole left side)
- Top right: the Environment/History/Connections tabs (Environment shows what data you have loaded, should be blank for now)
- Bottom left: the Console/Terminal/Jobs tabs (console is the most important)
- Bottom right: the Files/Plots/Package/Help/Viewer tabs (open the files tab)
-
Critically you should see "jsPsych_Online_Experiments" in the top right hand corner of the screen, meaning that you have opened the R Project
-
In the Files tab (bottom right quadrant), you should see a list of file/folder from .gitattributes to a folder called stimuli (if you're organizing alphabetically)
-
These are all of the files/folders in the repository. Here's a quick explanation for all of them (steps will continue below):
- .gitattributes: does some work for your git repository. Probably not needed for this repository but don't edit unless you know what you're doing
- .gitignore: does some work for your git repository. This specifies files/folders that your repository should ignore. These files are made by rStudio and I didn't need/want them backed up to GitHub
- .Rhistory: this file tracks what you do in rStudio. It is also ignored by Git because that file type is included in .gitignore
- data: this is the folder where data is saved by default when you pull it from FireBase
- data.csv: this is the .csv version the the datafile pulled from FireBase. It is created by R/analysis/pull_firedata.R
- data.json: this is the raw data file for 3 'participants' in the experiment. It is the file pulled straight from FireBase. Unless you rename this file it will be overwritten when you pull data from FireBase (R/analysis/pull_firedata.R)
- summarized_data.csv: this is a .csv with data summarized to a percent correct for each participant (and with extracted survey data)
- forms: this is where I store the HTML code for the consent and debriefing forms
- consent.html: the code for the consent form. It is called by the index.html file
- no_consent_deb.html: this is the debriefing form for those who decline to participate in the experiment. It is called by the index.html file
- img: this is where I expect images that are important to the experiment would be saved
- UM_Logo.png: this is the University of Manitoba Logo. It is called by the consent and debriefing forms
- index.html: this is the main part of the experiment. It will be explained in greater detail
- jspsych-6-2: this is the jsPsych Library
- css: the folder containing the default jspsych .css file
- examples: the folder containing examples of all the default jsPsych plugins. Open any of them in a web browser to see how it works, or open them in rStudio/code editor to see how they are programmed. Good for learning how to program your own experiments
- jspsych.js: the main file for the jsPsych library. Needs to be called in index.html
- license.txt: the license relevant to the jsPsych library
- plugins: the folder containing the jsPsych library plugins. Examples of how to use these are in the examples folder. These files will need to be called by the index.html file if you want to use those plugins
- jsPsych_Online_Experiments.Rproj: the R project file to keep everything organized
- LiveCode: the folder containing the files to run the LiveCode Example Experiment. This experiment saves data using #FIREBASE and redirects people to #SONA. The method is a little unconventional but is explained here
- R: the folder containing all of my R code
- analysis: the folder containing all of the code used in analyzing the data
- data_analysis.R: the file where the data analysis is done. The example summarizes the data and saves the summarized data #MC
- figures: the folder where I save my figures (empty in this repository)
- pull_firedata.R: the file used to download the data from FireBase and save a .csv version of the data
- pre_experiment: the folder containing all the R code used in setting up the experiment
- create_stimuli.R: the file used to create all of the stimuli used in the example experiment
- functions_to_create_stimuli.R: a file containing the functions used in create_stimuli.R
- README.md: the file that GitHub uses to create the ReadMe (the document you are currently reading)
- stimuli: the folder containing all of the experimental stimuli
- exp_text.js: a javascript file that sets up all of the text that will be presented by the experiment. This file is called by the index.html file
- practice_stimuli.js: a javascript file that defines the stimuli used in the example experiment. This file is created by create_stimuli.R and called by index.html
- uManitoba_Server: the folder containing the files to run the Example Experiment on the uManitoba Servers. This experiment saves data directly onto the uManitoba server and redirects people to #SONA. The method is explained here
-
Open the index.html file by clicking on it and choosing "Open in Editor". This is the file that runs the experiment. It calls all the necessary packages and files
-
I hope that the index.html file (and all files) are commented well enough that people can follow what they do
-
There are some "tags" that I've added into the index.html file. You can find them by hitting ctrl+f and searching for the tags below:
- #FIREBASE - These lines of code are needed to make data save to the FireBase database that I've set up
- #SONA - These lines of code are needed to automatically credit SONA participants
- #TESTING - These lines of code may need to be commented out in order to test the experiment locally (your web browser may raise security issues)
- Everything else is important for actually running the experiment and you can see my comments to understand what that code is doing
-
First off lets make sure that you can run the experiment locally:
- Try to open the experiment by opening index.html in rStudio and the clicking the "Preview" button near the top of the screen
- This should open a window that will run the experiment
- Next try to open the experiment in your preferred web browser (Safari will not enter fullscreen mode I think) by going to the repository in your file explorer and opening the index.html file directly
- If either method fails to load the experiment, try commenting out the lines of code tagged with #TESTING by adding "//" (without the quotation marks) at the beginning of the line
- You may be able to further diagnose problems in your web browser by opening up the developer tools (hot keys = ctrl+shift+i) for Windwows, or (command+option+j) for Mac). This console will be useful for testing and debugging. It will also display the errors that are generated by your code
-
Once you can run the experiment locally lets explore some edits to the experiment that you could make:
- You can change how long participants have to respond to the stimuli by going to the index.html file, finding "var practice_trials", and changing the line of code that is described as forcing the trial to end after 2 seconds (in the comments). You can change the number value from 2000 to any number that you want. This will be the length of time that participants have to respond in milliseconds
- You can change the text presented in any of the instructions by opening the folder "stimuli", then opening exp_text.js (in rStudio). This file contains almost all of the text presented in the experiment. If you change it in this file, and save the file, the text in the experiment will change to match.
- You can change the stimuli presented by going to the folder "stimuli", then opening practice_stimuli.js (in rStudio). This file defines the stimuli that are presented in this experiment. Think of this as a list of stimuli. What is listed after "stimulus": is HTML code that causes the stimuli the be presented. What is listed after "word": or "cor_response": are saved to the dataframe but don't control what is actually presented. You could manually change each line that you wanted to but there is a better way in this case.
- Go to the folder "R", then the folder "pre_experiment", then open both create_stimuli.R
- This file uses the custom functions defined in functions_to_create_stimuli.R to create the practice_stimuli.js file you were just looking at
- Try changing the words (e.g., MONTH) to any other words that you want (e.g., HERB) and then running the whole .R file
- You run the whole .R file by selecting all of the code (hot keys = ctrl+a) and then clicking the "Run" button near the top middle of the screen (hot keys to Run = ctrl+enter)
- If you then open the folder "stimuli", then open practice_stimuli.js (in rStudio) then you should see that it has been changed to reflect the new word that you chose
- You can change the contents of the ReadME file by opening README.md and editing any of the text that you want and saving it. Once you push this change to your GitHub repository (explained below) the changes will be reflected on your GitHub page ReadMe documentation. Note that you can use Markdown to format it and make it look pretty.
-
If you learn how to use jsPsych then you can make any edits you want or program entirely different experiments (see above for examples)
-
For now, try rerunning the experiment with your new edits
-
If you run it in your web browser and complete the experiment then the data will be saved to my FireBase database (you can change this as described later)
To save them to GitHub you will first need to commit the changes to your local git repository (automatically created when you cloned the repository). You can do this through the GitHub Desktop Client. When you commit to your local git repository it saves it as a form of version control (essentially it keeps a record of all the changes you make and allows you to revert to a previous iteration of the experiment if you want). Once you have committed changes to your local repository you can then push those changes to your GitHub repository (think of "pushing" as saving your edits to the "cloud"). Once changes are on your online GitHub repository, others can see your work and contribute to it. If you understand this then you can probably safely skip to Hosting the Experiment).
- Confirm that you have saved all the files that you opened/made changes to in previous instructions. If you open files in rStudio you can tell which are unsaved because they will have an asterisks (*) by their name.
- Open the GitHub Desktop Application and confirm it is open to the correct repository (jsPsych_Online_Experiments in the top left hand corner)
- You should see a list of files changed on the left hand side of the application
- If you click on a particular file, it will show you what has been changed (unless there are too many changes)
- At this point you may want to go back and uncomment the #TESTING lines of code unless you want to exclude them from the online version of your experiment
- You can "commit" all changes by giving them a name and description in the boxes just below the list of changed files (name/summary is required)
- I recommend making a summary like "edit_experiment_words" and then describing the major changes you made to the experiment
- Once you press the commit button, you have saved all of those file changes to you Git repository. You can revert back to any commit that you want but I'll leave it up to you to Google how.
- After pressing the commit button and allowing the program to finish saving, there should be a tab at the top of the screen that says "Push origin". This means to save all the changes you just made locally onto your GitHub repository. Click on that tab and wait for the repository to be backed-up to GitHub
With your forked copy of the repository it should be a simple matter of turning on GitHub pages in order to host the experiment. To do so do the following:
- Navigate to your repository (github.com/YourYourGitHubUsername/jsPsych_Online_Experiments)
- Click on the "Settings" tab near the top of the screen (github.com/YourGitHubUsername/jsPsych_Online_Experiments/settings)
- Ensure your repository is public (select the "Manage access" tab on the left)
- Return to the "Settings" page
- Scroll down to the GitHub Pages section of the page
- Enable GitHub Pages by changing the source to the master branch
- You do not need to select a theme
- In a few minutes the pages site should be published. The URL will appear at the top of the GitHub Pages section (https://YourGitHubUsername.github.io/jsPsych_Online_Experiments)
- Going to this URL will begin the experiment as it is hosted on your GitHub repository
- Any changes to files in your GitHub repository will affect the experiment, but it may take a few minutes for those changes to be reflected on the Pages URL (it is not instantaneous)
Unfortunately GitHub pages is only for static websites so we can't directly save the data on your repository. Instead we will save the data to Google's FireBase servers. I will explain how to do this with this particular experiment but I learned this process from the instructions found on Matt Crump's FirebaseDemo.
- Create an account with FireBase https://firebase.google.com/ (free unless you need lots of data or other options). You may or may not want this associated with your "personal" google account.
- Create a new project:
- Go to Console (top, right hand side of the screen)
- "Create a project"
- Give the project a name (probably the same as your GitHub Repo)
- I disabled Google Analytics but it doesn't make a difference
- Wait for your project to be ready
- Click on the Develop tab on the left hand side of the screen, then select "Database"
- Scroll down to find the Realtime Database and create that type of database
- Choose "Start in test mode" and "Enable". This will enable you to read and write to the database. It will also allow anyone else with credentials to read and write to the database. These credentials will be publicly posted on your GitHub repo so there is a security concern if you are saving any private data. These security settings can be changed later (under the "Rules" tab).
- Now you have a live database. You just need the configuration codes to interact with the database.
- Click on the gear symbol next to "Project Overview"
- Select "Project settings"
- In the first tab, "General", you will need to register an app. Add a web app (symbol looks like this </>).
- You do not need to turn on hosting unless you decide to host your experiment here instead of GitHub Pages.
- Give the app a nickname and click "Register app"
- FireBase will give you some html code that will look something like this:
var firebaseConfig = {
apiKey: " stuff here",
authDomain: "stuff here ",
databaseURL: "stuff here ",
projectId: "stuff here ",
storageBucket: "",
messagingSenderId: "stuff here ",
appId: "stuff here "
-
Copy this portion of the code, go to the index.html file in your local repository, scroll down until you find similar code (about line 80), and replace my FireBase configuration with yours.
-
You may notice that I have included three lines of source code (e.g., <script src="https://www.gstatic.com/firebasejs/6.3.4/firebase-app.js"></script>) rather than FireBase's one in the code that they provide you. All three of these are needed for my procedure. Do not delete or overwrite them. You may update the version number (e.g., from 6.3.4 to 7.13.2) but this is probably not needed.
-
Now go back to your Browser and "Continue to console" (Go back to "Project settings")
-
In the left hand menu, under Develop, select "Authentication"
-
Select "Sign-in method" or "Set up sign-in method"
-
Select "Anonymous" and change the settings so that it is enabled and save
-
Your database is now fully set up and ready to accept anonymous data. However, to remotely pull off the data we will need to find your "secret key"
- Go back to your "Project settings"
- Go to the "Service accounts" tabs
- Click on "Database secrets"
- Under your projects database, click to show the secret key. Copy and paste this somewhere you can use it later. The only place you'll probably use it is in the R/analysis/pull_firedata.R file to pull off the data. You will also need your projectURL (found in the code provided by firebase).
The rest of the references to firebase should be explained well enough in the comments of the index.html file. To more easily find this code I have tagged those lines with "#FIREBASE". Now when someone finishes the experiment their data should be saved to your FireBase realtime database.
The University of Manitoba uses the SONA system to credit participants with course credit. SONA allows online experiments and automatic crediting for those experiments. To do this:
- Set up a SONA online experiment
- Go to your SONA experiment's "Change Study Information" page
- Set the SONA Study URL to your experiments URL with "?id=%SURVEY_CODE%" added onto the end of the URL (without the quotation marks). For example, you might set the Study URL to: https://YourGitHubUsername.github.io/jsPsych_Online_Experiments/?id=%SURVEY_CODE%
- Then go back to the Study Information page and find the "Completion URLs:"
- Copy the client-side Completion URL, this will be important to include as a redirect at the end of your study
- There is then some important code to include in the index.html file (including the client-side URL) in order to automatically grant the participants credit. These will be tagged with "#SONA" so that they are easier to find. The most vital one will look something like this:
- window.location.href = "https://umanitobapsych.sona-systems.com/webstudy_credit.aspx?experiment_id=XXXX&credit_token=11X11X111X1X1X1XX1X11111111XX11X&survey_code="+SONA_ID;
- This code uses the client-side_URL that you have copied from your SONA experiment page, except that you need to replace the end of the client-side_URL (the end looks like this: survey_code=XXXX) with this code: survey_code="+SONA_ID
- You are replacing the default XXXX at the end of the code with +SONA_ID because SONA_ID is a variable that contains the correct information so that participants can be granted their credit
- So long as you include the code in the index.html tagged with "#SONA", and change the client-side URL to the one provided by your study, then it should automatically grant credit at the completion of the experiment
- You will also need to put the client-side_URL into the debriefing form for those participants who decline to participate during the consent phase of the experiment
If you've followed these instructions, your data is saved to your realtime data base on Google FireBase. You can view the data and download it straight from the FireBase website. However, I've found it much easier to download it through an R package.
-
In your local repository, open the R folder, then open the analysis folder, then open the pull_firedata.R file
-
If you haven't already, replace the projectURL and secretKey with the one for your project
-
Assuming you have cloned this repository and opened the R Project you should be able to run the code found in pull_firedata.R (select all code and press "Run")
-
It will download a .json file with all the data to the repositories data folder
-
Then it will unpack that .json file (not completely unpack it, but most of the way) and save it as a .csv file in the data folder
-
It will also tell you how many participants have completed the experiment
-
To further unpack the data, open the data_analysis.R file (in the R/analysis folder)
-
This file is more personalized to the example experiment, It will completely unpack the data and summarize it into one line per participant
-
Then save that dataframe as "summarized_data.csv" in the data folder of the repository
-
The additional unpacking is to pull out all of the survey data (see comments in the .R file for an explanation)
This section will probably not be useful to those who have no coding experience, but of the most use for those who have a little bit of coding experience. I also expect that this section will have more contributions from others than most sections. This may cause there to be contradictory advice, in that case choose which direction you want, it obviously doesn't matter (more than one way to skin a cat and all).
#HELP HERE
#HELP HERE
Coding experimental stimuli can be a tedious processes. In a simple word recognition experiment, the code for one word can end up being quite long, to include all the appropriate HTML and stimuli attributes. An example of one such line may be: #JS
{
"stimulus":"<p style='font-size: 48px;'>SOUND</p>",
"data":{
"type":"old",
"category":"music",
"word":"SOUND"
}
},The inclusion of specific data attributes for your stimuli will make your life much easier at the data anlysis stage. However, this makes the coding of each word quite lengthy and repetitve, where attempting to do this by hand would be an invitation to introduce errors into your code. For those who do not want to or know how to write code to automate this process, BBEdit is an extremely useful and powerful tool. Under the "Text" menu in BBEdit, utilizing the "Prefix/Suffix Lines" option is quite useful, where as much or as little text can be added to each option, to code each word as you see fit. This can be done for multiple lines at once, by highlighting all desired lines and then completing this process. #JS
#HELP HERE
#HELP HERE
Give meaningful names, but:
- Be concise
- However favour readability over brevity
- Avoid names that are too similar to one another; variable names should be easily distinguishable
- Be consistent with your naming conventions
- Avoid using identifiers that conflict with keywords that are widely used in other programming languages
- To easily differentiate words in a variable name, capitalize the first letter of each word (instead of using underscores)
In general, it is advised that function names be verbs if they change the state of a program, and nouns if they are used to return a particular value.
Another issue that is inherently tied to naming conventions and programming best practices is having well documented and commented code. A good example of this can be seen in the index.html file in this repository. Here, all of the code that has to do with Google's Firebase, is tagged #FIREBASE, all of the code that has to do with automatically granting credit for SONA participants is tagged #SONA, and so forth. This has been purposely done so that people learning how to construct experiments in the method explained here can easily distinguish what each code block is used for. Beyond that, having appropriately named variables and well documented code will not only help others read your code, but yourself as well, especially in the case that you have to read or reuse your code after a long period of time.
In sum, having appropriately named variables improves the readability of your code, which should reduce the effort needed to read and understand the code. The goal should be to reduce ambiguity, while promoting clarity.
Documenting here ideas I have to improve this example repo:
- Make a folder for writing a paper and give an rMarkdown example
- "Teach" how to use jsPsych
- Work from a LiveCode experiment, host it and collect data
- Show how to work from a PsychoPy experiment, host it, and collect data
- Demonstrate different ways to organize the experiment
- Demonstrate different ways to organize the repo
- Think of and write down a standardized way to fully extract data (from any experiment hosted this way)
- More to come...