README.md 9.42 KB
Newer Older
Augustin Burchell's avatar
Augustin Burchell committed
1
# EasyEyes Threshold
Peiling Jiang's avatar
Peiling Jiang committed
2

Peiling Jiang's avatar
Peiling Jiang committed
3 4
📖 [**Read the Manual**](https://docs.google.com/spreadsheets/d/1x65NjykMm-XUOz98Eu_oo6ON2xspm_h0Q0M2u6UGtug/edit?usp=sharing) (shared via Google Sheets)

5
A PsychoJS-based experiment generator for the measuring various psychometric thresholds, e.g., crowding.
Peiling Jiang's avatar
Peiling Jiang committed
6

Denis Pelli's avatar
Denis Pelli committed
7
## UPDATE
Peiling Jiang's avatar
Peiling Jiang committed
8

Denis Pelli's avatar
Denis Pelli committed
9
What's below is out of date in some ways. It mentions that we replaced the Python preprocessor.py by javascript code,
Peiling Jiang's avatar
Peiling Jiang committed
10 11
but the instructions still use the Python version. Instructions below explain how to put files on a server and run them.
This will soon be done for us by the https://easyeyes.app/threshold web page, which also allows uploading of fonts and consent forms directly to the Fonts and ConsentForms folders in EasyEyesResources/ on the scientist's Pavlovia account.
Denis Pelli's avatar
Denis Pelli committed
12 13
The manual is up to date.
https://docs.google.com/spreadsheets/d/1x65NjykMm-XUOz98Eu_oo6ON2xspm_h0Q0M2u6UGtug/edit#gid=2021552264
Peiling Jiang's avatar
Peiling Jiang committed
14

Denis Pelli's avatar
Denis Pelli committed
15 16
- Denis, Sept 23, 2021.

17
## Installation Instructions
18

Peiling Jiang's avatar
Peiling Jiang committed
19 20
Note: We've moved `preprocessor.py` to `lib/legacy/` and future updates of the preprocessor will happen in the [control-panel](https://github.com/EasyEyes/control-panel) repository.

21
1. Clone this repository.
22

Peiling Jiang's avatar
Peiling Jiang committed
23
You will need a copy of the files locally to work with.
24
Running `git clone https://github.com/EasyEyes/threshold.git` in a
25
terminal window should do the trick.
26

27
2. Run `preprocessor.py` on your experiment's csv file.
28

29
Assume we have a csv configuration file for our experiment called `myExperiment.csv`,
30
which we've placed in the same directory as `preprocessor.py` and `threshold.js`.
31 32
From a shell open in the same directory, run `python preprocessor.py myExperiment.csv`.
If successful, this will create a `/conditions` directory, which contains
33
the properly formatted csv files needed (_ie_ by `threshold.js`) to create your experiment.
34

Peiling Jiang's avatar
Peiling Jiang committed
35
- If you don't have python available on your computer, [install it](https://www.python.org/downloads/).
36 37 38

3. Run `index.html` to run the experiment\*.

39
`index.html` is the entrypoint to the actually experiment.
Peiling Jiang's avatar
Peiling Jiang committed
40
From here the necessary [psychojs modules](https://github.com/psychopy/psychojs),
41
the EasyEyes Threshold experiment (_ie_ threshold.js),
Peiling Jiang's avatar
Peiling Jiang committed
42 43
and the parameters specific to your experiment
(_ie_ the files in `/conditions` you just produced by running `preprocessor.py`)
44

Peiling Jiang's avatar
Peiling Jiang committed
45
In this case, "run index.html" means "host index.html from a server, and visit the page from a web-browser".
46 47
While you could just double-click `index.html` to open it, this will result in experiment-breaking
errors.
Peiling Jiang's avatar
Peiling Jiang committed
48 49
In short, browsers only trusts resources drawn from a single source. This mechanism is a vital safety feature, but in this case means that if we try to run our experiment’s index.html file by double clicking on it, the browser will prevent the experiment from loading the resources it needs as it treats other files on our computer as separate sources.
To get around this, we can either start our own local server instance,
50 51
or use a hosting service like Pavlovia.

52 53 54
For testing your experiment while developing it, use the first solution below;
when your experiment is tested and ready to be run by participants, use the second.

Peiling Jiang's avatar
Peiling Jiang committed
55
- A. Start a server for testing locally.
56

Peiling Jiang's avatar
Peiling Jiang committed
57 58 59 60
  We need to [start up a local server](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/set_up_a_local_testing_server).
  In essence, this is a program running on
  our computer which properly sends all the required files for our experiment
  to the web-browser when we run the experiment.
61

62
  From a shell open in the same directory as `threshold.js` and `index.html`, simply run
Peiling Jiang's avatar
Peiling Jiang committed
63 64 65 66 67 68 69
  `python3 -m http.server`.
  This is a quick, one-line way to start a server instance in the current
  directory, which is built-in to python.
  (Note: Other servers, such as with [Node.js](https://stackoverflow.com/questions/6084360/using-node-js-as-a-simple-web-server)
  or [PHP](https://stackoverflow.com/questions/1678010/php-server-on-local-machine),
  would also work for this purpose, though we recommend
  using the Python server, as Python is already a dependency of the preprocessor.)
70

Peiling Jiang's avatar
Peiling Jiang committed
71 72 73 74
  We can then open the experiment by visiting
  the URL which the program provides, eg
  [http://0.0.0.0:8000/](http://0.0.0.0:8000/),
  from a web-browser on the same computer.
75

Peiling Jiang's avatar
Peiling Jiang committed
76
- B. Deploy your experiment by uploading to an experiment hosting service.
77

Peiling Jiang's avatar
Peiling Jiang committed
78 79 80 81 82
  Once your experiment is ready for participants, it should be hosted online.
  We recommend doing this safely and quickly by using a hosting service,
  such as [Pavlovia](https://pavlovia.org). In the case of Pavlovia,
  this looks like
  [importing your directory to a new project on Pavlovia's Gitlab.](https://gitlab.pavlovia.org/projects/new).
83

Peiling Jiang's avatar
Peiling Jiang committed
84 85
  Alternatively, you can manage your own server, running a program such as [JATOS](jatos.org),
  to host your experiment online.
86

87
4. Developers: Edit `threshold.js` to extend functionality
Peiling Jiang's avatar
Peiling Jiang committed
88
   Interested developers can expand upon the currently supported parameters by directly
89
   editing the `threshold.js` or `preprocessor.py` files.
Peiling Jiang's avatar
Peiling Jiang committed
90 91 92
   If you have a contribution that you think would be valuable for other EasyEyes Crowding users, consider
   [creating a pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
   to share your work.
93

Peiling Jiang's avatar
Peiling Jiang committed
94 95 96
## Example CSV File

```
Peiling Jiang's avatar
Peiling Jiang committed
97 98 99 100 101
about,Effect of font on crowding.,Effect of font on crowding.,Effect of font on crowding.,Effect of font on crowding.
aboutDateCreated,8/1/21,8/1/21,8/1/21,8/1/21
aboutDateModified,8/15/21,8/15/21,8/15/21,8/15/21
author,Denis Pelli,Denis Pelli,Denis Pelli,Denis Pelli
authorEmail,dp3@nyu.edu,dp3@nyu.edu,dp3@nyu.edu,dp3@nyu.edu
Peiling Jiang's avatar
Peiling Jiang committed
102 103 104
blockOrder,1,1,2,2
conditionName,crowding,crowding,crowding,crowding
conditionTrials,40,40,40,40
Peiling Jiang's avatar
Peiling Jiang committed
105 106 107
markingFixationStrokeLengthDeg,1,1,1,1
markingFixationStrokeThicknessDeg,0.03,0.03,0.03,0.03
markTheFixationYes,TRUE,TRUE,TRUE,TRUE
Peiling Jiang's avatar
Peiling Jiang committed
108
showAlphabetWhere,bottom,bottom,bottom,bottom
Peiling Jiang's avatar
Peiling Jiang committed
109 110
showCounterWhere,bottomRight,bottomRight,bottomRight,bottomRight
showInstructionsWhere,topLeft,topLeft,topLeft,topLeft
Peiling Jiang's avatar
Peiling Jiang committed
111
simulateParticipantYes,FALSE,FALSE,FALSE,FALSE
Peiling Jiang's avatar
Peiling Jiang committed
112
simulationModel,blind,blind,blind,blind
Peiling Jiang's avatar
Peiling Jiang committed
113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133
spacingDirection,radial,radial,radial,radial
spacingOverSizeRatio,1.4,1.4,1.4,1.4
targetAlphabet,DHKNORSVZ,DHKNORSVZ,acenorsuvxz,acenorsuvxz
targetDurationSec,0.15,0.15,0.15,0.15
targetEccentricityXDeg,10,-10,10,-10
targetEccentricityYDeg,0,0,0,0
targetFont,Sloan,Sloan,Verdana,Verdana
targetFontStyle,,,,
targetKind,letter,letter,letter,letter
targetMinimumPix,8,8,8,8
targetTask,identify,identify,identify,identify
thresholdBeta,2.3,2.3,2.3,2.3
thresholdDelta,0.01,0.01,0.01,0.01
thresholdGuess,2,2,2,2
thresholdGuessLogSd,3,3,3,3
thresholdParameter,spacing,spacing,spacing,spacing
thresholdProbability,0.7,0.7,0.7,0.7
trackGazeYes,TRUE,TRUE,TRUE,TRUE
trackHeadYes,TRUE,TRUE,TRUE,TRUE
viewingDistanceDesiredCm,40,40,40,40
wirelessKeyboardNeededYes,FALSE,FALSE,FALSE,FALSE
Peiling Jiang's avatar
Peiling Jiang committed
134 135
```

Peiling Jiang's avatar
Peiling Jiang committed
136 137
A **CSV file** named `experiment.csv` must be placed at the same directory as the PsychoPy file. The program will take care of the rest. We use a transposed CSV as the input file so that it's easier to read and edit. The program is designed to handle this transposed style and will help you transpose back for PsychoPy to use.

138
## Using custom fonts
Peiling Jiang's avatar
Peiling Jiang committed
139 140

[Some fonts](https://www.w3schools.com/cssref/css_websafe_fonts.asp) are natively supported by web-browsers;
141 142 143
these can be used in an experiment without
having to include any addition font files with your experiment.

Peiling Jiang's avatar
Peiling Jiang committed
144 145
To use other fonts, such as one you created or purchased from a third-party, start
by creating a /fonts folder in your local copy of this repo. Inside this folder you
146 147
can include any .woff font files that you would like to make accessible to to your
study.
Peiling Jiang's avatar
Peiling Jiang committed
148 149 150 151 152
Within your experiment csv file, simply use the same string for the targetFont
parameter as the name of the corresponding .woff file.
For example, given Pelli-EyeChart.woff in your /fonts folder, use
"Pelli-EyeChart" as the value for targetFont.
During the development process, open the javascript console in your browser to
153 154
monitor any failures to load assets like font files.

Peiling Jiang's avatar
Peiling Jiang committed
155
By default, PsychoJS also supports using finding fonts from [Google Fonts](https://fonts.google.com). Searching Google Fonts for a font of the requested name will therefore be the
156 157 158
fallback behavior of an experiment, if a `targetFont` parameter does not correspond to
a default web font, or a `.woff` file your `./fonts` directory.

Peiling Jiang's avatar
Peiling Jiang committed
159
Most importantly,
160 161
**always test your experiment, and verify for yourself that stimuli are being presented correctly**.

Peiling Jiang's avatar
Peiling Jiang committed
162 163 164
🚨 Things worth noting:

1. Due to a PsychoPy limitation, `conditionTrials` must be the same for each condition within one block.
Peiling Jiang's avatar
Peiling Jiang committed
165 166 167

## PsychoPy Version

Peiling Jiang's avatar
Peiling Jiang committed
168 169 170 171 172 173 174 175
`2021.3.0`.

## TODO

- [ ] Check parameter spelling and give fatal error when detect any.

Working parameters:

Peiling Jiang's avatar
Peiling Jiang committed
176 177
(Needs to be updated!)

Peiling Jiang's avatar
Peiling Jiang committed
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211
```
x   blockOrder
    conditionName
x   conditionTrials
    fixationStrokeLengthDeg
    fixationStrokeThicknessDeg
x   fixationYes
    showAlphabetWhere
    showCounterWhere
    showInstructionsWhere
    simulateParticipantYes
    simulationModel
x   spacingDirection
x   spacingOverSizeRatio
!   targetAlphabet => (Allowed keys) not supported when export to JS
x   targetDurationSec
x   targetEccentricityXDeg
x   targetEccentricityYDeg
x   targetFont
    targetFontStyle
    targetKind
x   targetMinimumPix
    targetTask
x   thresholdBeta
x   thresholdDelta
x   thresholdGuess
x   thresholdGuessLogSd
    thresholdParameter
x   thresholdProbability
    trackGazeYes
    trackHeadYes
x   viewingDistanceDesiredCm
    wirelessKeyboardNeededYes
```
Peiling Jiang's avatar
Peiling Jiang committed
212 213

`x` means working.