function fo paradigm documentation

[drmowinckels]

There was a twitter exchange regarding what would be great to have regarding paradigm documentation.

The general concept would be to have a (or a set of) function that could be used on the project folder for a paradigm, and that would create a markdown report about key-features of the paradigm.

There are several good suggestions from Matt Crump
1. Default output to be like a README

2. output and display mock data returned by the paradigm
(this could also be useful as a function to test the paradigm output is as expected, without having to run through the experiment manually your self).

2a. with the dataframe in hand (I guess which could also be obtained from real data or pilot data), some function could be applied to document or provide meta-data for the dataframe...something similar to how data is documented in R help files

3. a function that summarizes the content of the jsPsych experiment, and returns a description of factors, leves, stimuli, and datatype etc.

I have a fourth lofty suggestion, which I am unsure even is possible, is to mock run the paradigm and get screen shots (png's) of a standard trial, to make those awesome figures we all love and hate.

twitter thread here

[CrumpLab]

Mock running the experiment to get screen shots is a neat idea. I wonder if there is a way to automate screen shots with a function?

Related to 3. it would be really neat to simulate a jsPsych experiment, which could return say a data object with null values as placeholders, or even simulated data. This isn't a part of jsPsych, but there has been some recent interest in making this happen.

jspsych/jsPsych#647

I could see simulation data being helpful both for documenting the experiment, debugging the experiment, and conceptually useful for thinking about what might actually happen in the experiment (if you take it a step further and start an analyzing the simulated data).

[drmowinckels]

plotly in R uses orca to capture images, and I'm kind of hoping there is a way to apply that here too? I'm not sure exactly how orca works, but I think it's worth investigating.

https://github.com/plotly/orca

[CrumpLab]

Thought I'd mention a few related things that could help out with these suggestions.

I've been slowly adding new functions to a forked copy of xprmntr https://github.com/CrumpLab/xprmntr. In the process of doing that, I made an R markdown template for generating jsPsych experiments https://github.com/CrumpLab/jsPsychR, with some examples here https://github.com/CrumpLab/jsPsychRexamples.

I think the xprmntr approach of generating the file structure for an experiment from an .R script, and the R markdown template approach, where R code chunks and js code chunks are embedded into a html by knitr (and the supporting files are returned by the template) are complementary approaches, and could be put together (e.g., the R markdown template could be put into the inst folder and packaged with xprmntr).

I bring all of this up because the template approach could be expanded to include template files for documentation.

Also, when you compile a jspsych experiment through knitr, it can be viewed in the viewer pane. So, if there is a function to grab screen shots from the viewer pane in R-studio, that could be useful.

I haven't looked too hard yet for screen-shot grabbing, but I came across this on stack overflow