Signals pong doc

docs/README.md

@@ -1,32 +1,50 @@
 ## Description:
 
-This `docs` folder contains files that are useful for learning how to use *Signals*.  Experiment definition (exp def) functions are run within the Rigbox Experiment framework and require [Rigbox](https://github.com/cortex-lab/Rigbox).  These functions can be run by calling `eui.SignalsTest`.  The files in this folder are not on the paths, so cd into the folder before running.
+This `docs` folder contains files that are useful for learning how to use *Signals*. This folder contains `tutorials` and `examples` folders, and the `examples` folder contains `scripts` and `exp defs` folders. The `scripts` folder contains *Signals* examples that can be run by just calling the filename within MATLAB (e.g. `ringach98`). The `exp defs` folder contains *Signals* experiment definition functions that are run in [Rigbox's](https://github.com/cortex-lab/Rigbox) Experiment framework. These exp defs can be run in Rigbox's SignalsTest GUI, which can be launched by calling `eui.SignalsTest`.
+
+All files in this folder should not be added directly to MATLAB's path, so we recommend, within MATLAB, to change into the folder containing the file you wish to run before running.
 
 
 ## Contents:
 
-### Tutorials folder
+### `tutorials` folder
 
-Contains files that are useful for learning how to use *Signals*:
+Contains files that are useful for learning about and how to use *Signals*:
 
-- 'GettingStartedWithSignals': Those new to *Signals* should start here. This script contains information on how *Signals* works, and how to create signals in a *Signals* network using common MATLAB and *Signals* specific methods.
+- 'GettingStartedWithSignals': Those new to Signals should start here. This script contains information on how Signals works, and how to create signals in a Signals network using common MATLAB and Signals specific methods.
 
-- 'signalsExpDefTutorial': This file is a tutorial for creating a *Signals* Experiment definition.  This tutorial walks through setting up and running different versions of a *Signals* Experiment based on the [Burgess Steering Wheel Task](https://www.biorxiv.org/content/biorxiv/early/2017/07/25/051912.full.pdf). To run, call `eui.SignalsTest(@signalsExpDefTutorial)`.
+- `signalsExpDefTutorial.m` - A tutorial for creating a *Signals* experiment definition.  This tutorial walks through setting up and running different versions of a *Signals* Experiment based on the [Burgess Steering Wheel Task](https://www.biorxiv.org/content/biorxiv/early/2017/07/25/051912.full.pdf). To run, call `eui.SignalsTest(@signalsExpDefTutorial)`.
 
-- 'SignalsPrimer': An in-depth walkthrough of *Signals*.
+- `SignalsPrimer.m` - An in-depth walkthrough of *Signals*.
 
-### Examples folder
+- `using_visual_stimuli.m` - A guide for learning how *Signals* interacts with Psychtoolbox and OpenGL to create visual stimuli.
 
-Contains example exp defs and standalone experiment scripts:
+- `using_test_gui.m` - A guide for using Rigbox's `eui.SignalsTest` GUI for running Signals exp defs.
 
-- 'advancedChoiceWorld': This exp def runs a 2 Alternate Unforced Choice version of the Burgess Steering Wheel Task.  To run, call `eui.SignalsTest(@advancedChoiceWorld)`.
+### `examples/scripts` folder
 
-- 'imageWorld': This demonstrates a passive image presentation experiment.  The original image dataset is not included.  To run, call `eui.SignalsTest(@imageWorld)`.
+Contains example standalone *Signals* experiments that can be run as scripts.
 
-- 'mouseTheremin': This function maps the current horizontal cursor position to a given
+- `mouseTheremin` - Maps the current horizontal cursor position to a given
 frequency, and as the mouse is moved the frequency changes much like a
 theremin. To run, call `mouseTheremin`.
 
-- 'ringach98': This script launches an orientation detection/discrimination task based on a [task created by Dario Ringach](https://www.sciencedirect.com/science/article/pii/S0042698997003222?via%3Dihub).  To run, call `mouseTheremin`.
+- `ringach98` - Launches an orientation detection/discrimination task based on a [task created by Dario Ringach](https://www.sciencedirect.com/science/article/pii/S0042698997003222?via%3Dihub). To run, call `ringach98`.
+
+- `screenImage` - Produces Gabor grating image data based on specified parameters. To run, call `screenImage`.
+
+### `examples/exp defs` folder
+
+Contains example exp defs that can be run via Rigbox's SignalsTestGUI(`eui.SignalsTest`).
+
+- `advancedChoiceWorld.m` - A 2 Alternate Unforced Choice version of the Burgess Steering Wheel Task. To run, call `eui.SignalsTest(@advancedChoiceWorld)`.
+
+- `advancedChoiceWorldExpPanel.m` - An ExpPanel class to accompany `advancedChoiceWorld`. *Note: this is not an exp def, it is called automatically when the `advancedChoiceWorld` exp def is run to create psychometric plots that display realtime performance.
+
+- `choiceWorld.m` - A 2 Alternate Unforced Choice version of the Burgess Steering Wheel Task.  To run, call `eui.SignalsTest(@choiceWorld)`.
+
+- `choiceWorldExpPanel.m` - An ExpPanel class to accompany `choiceWorld`. *Note: this is not an exp def, it is called automatically when the `choiceWorld` exp def is run to create psychometric plots that display realtime performance.
+
+- `imageWorld` - A demonstration of a passive image presentation experiment. The original image dataset is not included. To run, call `eui.SignalsTest(@imageWorld)`.
 
-- 'signalsPong': This exp def runs the classic computer game, Pong.  To run, call `eui.SignalsTest(@signalsPong)`.
+- `signalsPong` - This exp def runs the classic computer game, Pong. To run, call `eui.SignalsTest(@signalsPong)`.

docs/examples/signalsPong.m → docs/examples/exp defs/signalsPong.m

@@ -1,22 +1,21 @@
-function signalsPong(t, events, p, visStim, inputs, outputs, audio)
+function signalsPong(t, events, p, visStim, inputs, outputs, ~)
 % SIGNALSPONG runs a simple version of the classic game, pong, in Signals
+%   This exp def runs a fairly simple one-player version of pong. The game
+%   pits the player against a CPU - the first to reach a target score wins.
+%   The target score is 5 by default, but is treated as a Signals
+%   parameter, and so can be adjusted within the GUI from which this exp
+%   def is launched. During gameplay, the ball's velocity is constant, and
+%   the ball's trajectory changes randomly upon contact with a paddle or
+%   the wall.
 %
-% This exp def runs a fairly simple one-player version of pong. The game
-% pits the experimenter against a CPU player - the first to reach a 
-% target score wins. The target score is 5 by default, but is treated as 
-% a Signals parameter, and so can be adjusted within the GUI from which
-% this exp def is launched. During gameplay, the ball's velocity is
-% constant, and the ball's trajectory changes randomly upon contact with a
-% paddle or the wall.
-%
-% This exp def should be run via the ExpTestPanel GUI (exp.ExpTest)
+%   This exp def should be run via the SignalsTest GUI (`eui.SignalsTest`)
 % 
-% Example: 
-%  expTestPanel = exp.ExpTest('signalsPong');
+%   Example: 
+%    eui.SignalsTest('signalsPong');
 %
 % Author: Jai Bhagat - adapted from Andy Peters
 %
-% *Note: The parameters the experimenter can play with are defined and 
+% Note: The parameters the experimenter can play with are defined and 
 % explained at the bottom of this exp def
 
 %% World set-up (points of control)
@@ -169,7 +168,7 @@ function signalsPong(t, events, p, visStim, inputs, outputs, audio)
     if cpuScored, gameData.cpuScore = gameData.cpuScore + 1; end
 
     contactOrScore = wallContact || playerContact || cpuContact... 
-      || playerScored || cpuScored;
+                     || playerScored || cpuScored;
 
     if contactOrScore % update ball angle and ball velocity
 
@@ -252,16 +251,16 @@ function signalsPong(t, events, p, visStim, inputs, outputs, audio)
 endGame = (playerScore == targetScore) | (cpuScore == targetScore);
 events.expStop = endGame.then(1).delay(0.1);
 
-% output to the 'ExpTestPanel' logging display on a score and at game end
-outputs.playerScore = cond(playerScore>0, playerScore.map(@(x)...
-  sprintf('Player 1 Scores! Player 1: %d cpu: %d',...
-  x, cpuScore.Node.CurrValue)));
-outputs.cpuScore = cond(cpuScore>0, cpuScore.map(@(x)...
-  sprintf('cpu Scores! Player 1: %d cpu: %d',...
-  playerScore.Node.CurrValue, x)));
-outputs.gameOver =... 
-  endGame.then(cond(playerScore > cpuScore, sprintf('Game Over! Player 1 Wins!'),... 
-  cpuScore > playerScore, sprintf('Game Over. cpu Wins :('))).delay(0.01);
+% output to the logging display on a score and at game end
+scorerName = merge(playerScore.then("Player 1"), cpuScore.then("CPU"));
+scoreMsg = @(nm,a,b) sprintf('%s Scores! Player 1: %d CPU: %d', nm, a, b);
+outputs.scorecard = anyScored.then(...
+  scorerName.mapn(playerScore, cpuScore, scoreMsg));
+
+gameOverMsg = cond(...
+  playerScore > cpuScore, 'Game Over! Player 1 Wins!',... 
+  cpuScore > playerScore, 'Game Over. cpu Wins :(');
+outputs.gameOver = gameOverMsg.at(endGame);
 
 %% Define the visual elements and the experiment parameters