Directory Structure

This project directory is organized to be very modular and composable. In general, files and functions should be relatively small and self-contained, global scope should not be used and only the pieces of code needed for any given file should be imported. This keeps the code maintainable with clear lineage and purpose for each piece of code.

assets/

This folder contains any static files that are used by the app. Honeycomb starts with a few images used as icons for the installed applications.

caution

Assets that pertain to your specific task should be added to the public/assets/ folder, not here!

build/

The build scripts automatically create a build folder at the root of the repository and update it on subsequent builds. build/ should be left alone!

danger

The build folder is in Honeycomb's .gitignore and should never be added to git

emulator_data/

This folder contains starter data for the Firebase Emulators to use while developing locally. See the Firebase Scripts to use the data.

danger

emulator_data/ is written to when running npm run firebase:emulators:save and should never be manually edited.

env/

This folder contains different files used to pass environment variables (settings) into Honeycomb. Honeycomb starts with presets for common use cases and is explained in greater detail in the Environment Variables section.

node_modules/

danger

node_modules/ is written to when running npm install and should never be manually edited.

psiturkit/

The file psiturk-it inside psiturkit/ is a bash script used to instal PsiTurk locally - see PsiTurk for more information.

caution

Nothing in this folder should ever need to be manually edited.

public/

The public directory contains files that are used as assets in the built app.

• index.html is the entry point of the website
  • Changing <title>Honeycomb</title> will update the name you can see in the browser tab.
• favicon.ico is the small icon you can see in the browser tab.
• electron.js contains all of the code related to the electron app.

assets/

The public/assets/ directory contains all of the images and videos needed to run your task.

lib/

The public/lib/ directory contains the files PsiTurk needs to run. Note that index.html references these files inside the <script> tags.

danger

These files are minified versions of dependencies and should never be manually edited.

config/

The public/config/ directory contains the config files needed for the electron app. This includes the event-marker details and event codes. version.json keeps track of the current git commit, which Honeycomb uses to keep track of the version of your task used for a given experiment.

src/

This folder contains the source code for the Honeycomb application.

App/

Files relating to the React application. This is the code that runs your JsPsych task and shouldn't need to be changed.

components/

The React components that make up Honeycomb are located here.

• App.jsx initializes and maintains the state of the application. It is also where communication is set up between the electron and psiturk processes.
• Error.jsx displays a small error message. It is rendered when the App.jsx detects an issue in state.
• JsPsychExperiment.jsx initializes the JsPsych experiment
• Login.jsx handles user authentication based on the environment variables passed to Honeycomb

deployments/

Custom code used by the various deployments such as Firebase.

caution

Changes to these files will change how Honeycomb handles data and should be done with great caution.

config/

Each file in the config directory contains settings for a different part of the task.

• main.js contains the global settings (e.g. whether Honeycomb is running online or in the clinic) passed from env variables and logic for loading the appropriate language file.
• trigger.js for equipment-related settings (e.g. event markers). It uses a slightly different style of javascript as it is imported both in the React app as well as the electron process.
• config.json contains the settings for your task. Usage of the config file allows for easy updating of task settings. Common settings can be written once in the config file and re-used throughout the task.
• language.json contains the language used in your task. Usage of language json files allows for easy internationalization of the task (e.g. english and spanish) and mturk-specific language. Common phrases can be written once in a language file and re-used throughout the task.

lib/

A library of utility and markup are located here. This allows for functions and html to be re-used wherever needed.

markup/

src/lib/markup/ files contain HTML templates used throughout the task.

• stimuli.js contains a baseStimulus function that wraps some markup in a container that takes up 100% of the height and width of the viewport
• photodiode.js contains the markup for the photodiode box and spot. It is displayed in the bottom right corner of the scree.
• tags.js contains functions for wrapping language in common html tags.
  • p('Hello World') will return <p>Hello World</p>. You should always wrap your language in a tag to ensure it is displayed correctly.

tip

The tag function inside tags.js can be used to wrap language in any html tag you need.

utils.js

utils.js contains utility functions that can be used across a variety of trials. Be sure to look for functions you might be able to use in your task!

timelines/

A timeline is a collection of trials that JsPsych displays in the given order. Timelines can contain timelines themselves; you may want to break this nesting into multiple files in this folder.

• main.js contains the JsPsych options and root timeline which App.jsx uses to run the experiment.
• honeycombBlock.js contains the timeline for the Honeycomb block - the "meat" the example reaction-time task. It uses the task settings from config.json.
• honeycombTimeline.js contains the timeline for the entire Honeycomb task. This includes the block timeline from honeycombBlock.js, as well as individual trials such as the welcome screen, full screen trial, and instructions.
• preamble.js contains a base timeline for showing the name and welcome screen of an experiment, as well as automatically entering fullscreen mode. It adds the photodiode instructions to the timeline if Honeycomb is using the photodiode.

trials/

A trial is the base unit of a JsPsych experiment. Each trial should be its own file within this folder - the files in src/timelines/ will combine these trials into the full experiment.

• honeycombTrials.js contains the individual trials used in the Honeycomb task. These trials are imported into honeycombBlock.js and honeycombTimeline.js.
• adjustVolume.js prompts the user to adjust the volume on their computer.
• camera.js contains trials for beginning and ending a camera recording.
• fullscreen.js contains trials for entering and exiting fullscreen mode.
• holdUpMarker.js prompts the user to connect their event marker and hold it up to the camera.
• quizTrial.js contains trials for a quiz/survey.
• startCode.js emits a start code to a photodiode spot and audible beep

index.js

index.js is the entry point for React in our application. Note that the id 'root' corresponds with a tag in public/index.html:

<div id="root"></div>

Other Folders/Files

• .nvmrc determines which version of node that Honeycomb is designed to be run on
• .github/workflows/ contains .yaml files used to build Honeycomb on a pull request (build.yaml) and create task executables either in a single instance (package.yaml) or for a full release (release.yaml)
• package.json contains metadata about your project, a list of the dependencies needed for the project, and scripts to run tasks related to your task. The Quick Start lists which metadata should be changed.
• cli.mjs is the script used to download and delete data stored in Firestore.
• version.js is the script used to keep track of which version of the task a given experiment is using

danger

package-lock.json is written to when running npm install and should never be manually edited.

Firebase Files

• .firebaserc contains the name of the project Firebase should connect to. Be sure to update the default project to the one you created!
• firebase.json contains the Firebase settings for Honeycomb.
• firestore.indexes.json contains the Firestore index settings for Honeycomb.
• firestore.rules contains the Firestore rules for creating/editing data.

caution

firebase.json, firestore.indexes.json, and firestore.rules shouldn't need to be manually edited.

Git Files

• .gitignore lists the folders and files that should be excluded from Git.

danger

Any secrets and/or tokens must be added to .gitignore or they will be visible to anyone with access to the repository!

Eslint Files

• .eslintrc.js contains the Eslint settings for Honeycomb. We recommend it's left alone but can be adjusted for personal settings.
• .eslintignore lists the folders and files that eslint shouldn't touch, similar to .gitignore.

Prettier Files

.prettierrc.js contains the Prettier settings for Honeycomb. We recommend it's left alone but can be adjusted for personal settings.