Merge branch 'documentation' into dev

+eui/SignalsTest.m

@@ -118,6 +118,16 @@
         'signals:test:copyPaths',...
         'No paths file found. A template can be found in %s.', ...
         fullfile(fileparts(which('addRigboxPaths')), 'docs', 'setup'))
+
+      % Check that the Psychophisics Toolbox is installed
+      toolboxes = ver;
+      isInstalled = strcmp('Psychtoolbox', {toolboxes.Name});
+      if ~any(isInstalled) || str2double(toolboxes(isInstalled).Version(1)) < 3
+        error('signals:test:toolboxRequired',...
+          ['Requires Psychtoolbox v3.0 or higher to be installed. '...
+          'Follow the steps in the <a href="matlab:web(''%s'',''-browser'')">README</a> to install.'],...
+          'https://github.com/cortex-lab/Rigbox/tree/master#installing-psychtoolbox')
+      end
 
       obj.LastDir = getOr(dat.paths, 'expDefinitions');
       if nargin > 0 % called with experiment function to run

+exp/Parameters.m

@@ -38,6 +38,28 @@
     end
 
     function set(obj, name, value, description, units)
+      % SET Set a named parameter value
+      %  SET(OBJ, NAME, VALUE[, DESCRIPTION, UNITS]) sets the value of a
+      %  parameter.  If the parameter doesn't already exist, a new one is
+      %  added.  
+      %
+      %  Inputs:
+      %    name (char): The parameter name to set
+      %    value: The value of the parameter.  The number of columns must
+      %      be 1 or equal to numTrialConditions (or for chars the number
+      %      of rows)
+      %    description (char): Optional.  A description of the parameter
+      %    units (char): Optional.  The parameter units
+      %
+      %  Example 1: Add a new parameter called targetAltitude
+      %    description = 'Visual angle of target centre above horizon';
+      %    P.set('targetAltitude', 90, description,  '°')
+      %
+      %  Example 2: Set the values for a trial condition
+      %    values = randsample(0:45:135, P.numTrialConditions, true);
+      %    P.set('orientation', values)
+      %
+      % See also DESCRIPTION, NUMTRIALCONDITIONS
 
 %       if size(value, 2) > 1
 %         % Attempting to set a conditional parameter so it should match the 

README.md

@@ -3,27 +3,40 @@
 ![Coverage badge](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fsilent-zebra-36.tunnel.datahub.at%2Fcoverage%2Frigbox%2Fmaster)
 ![Build status badge](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fsilent-zebra-36.tunnel.datahub.at%2Fstatus%2Frigbox%2Fmaster)
 
-Rigbox is a high-performance, open-source MATLAB toolbox for managing behavioral neuroscience experiments. 
-Rigbox's main goals are to simplify hardware/software interfacing, behavioral task design, and visual and auditory stimuli presentation. Additionally, Rigbox can time-align datastreams from multiple sources and communicate with a remote database to manage experiment data. Rigbox is mostly object-oriented and highly modular, which simplifies the process of designing experiments.
+Rigbox is a high-performance, open-source MATLAB toolbox for managing behavioral neuroscience experiments. Initially developed to probe mouse behavior for the [Steering Wheel Setup](https://www.ucl.ac.uk/cortexlab/tools/wheel),  Rigbox simplifies hardware/software interfacing and creates a runtime environment in which an experiment's parameters can be easily monitored and manipulated.  Its many features include synchronizing recordings, managing experimental data and a viewing model for visual stimuli.  Rigbox is mostly object-oriented and highly modular, making designing and extending experiments much simpler.
 
 ## Requirements
 
 For exploring Rigbox's features and running test experiments, Rigbox only needs to be installed on a single computer.
 
-For running experiments, we recommend installing Rigbox on two computers: one computer (which we refer to as the "Stimulus Computer" or "SC") communicates with an experiment rig's hardware and presents stimuli, and the other computer (which we refer to as the "Master Computer" or "MC") runs a GUI that the experimenter can use to start, monitor, parameterize, and stop the experiment.
+Rigbox has the following software dependencies:
+* **OS:** Windows 7 or later, 64-bit
+* **MATLAB:** 2018b (v9.5) or later, with the Data Acquisition Toolbox
+* **Libraries**: [Visual C++ Redistributable Packages for Visual Studio 2013](https://www.microsoft.com/en-us/download/details.aspx?id=40784) & [2015-2019](https://github.com/Psychtoolbox-3/Psychtoolbox-3/raw/master/Psychtoolbox/PsychContributed/vcredist_x64_2015-2019.exe)
+* **MATLAB community toolboxes:**
+    * [GUI Layout Toolbox](https://uk.mathworks.com/matlabcentral/fileexchange/47982-gui-layout-toolbox) (v2 or later)
+    * [Psychophysics Toolbox](http://psychtoolbox.org/download.html) (v3 or later)
+    * [NI-DAQmx support package](https://uk.mathworks.com/hardware-support/nidaqmx.html) (Required if using an NI DAQ)
+
+Additionally, Rigbox works with a number of extra submodules (included with Rigbox):
+* [signals](https://github.com/cortex-lab/signals) (for designing bespoke experiments in Signals)
+* [alyx-matlab](https://github.com/cortex-lab/alyx-matlab) (for registering data to, and retrieving from, an [Alyx database](https://alyx.readthedocs.io/en/latest/))
+* [npy-matlab](https://github.com/kwikteam/npy-matlab) (for saving data in binary NPY format)
+* [wheelAnalysis](https://github.com/cortex-lab/wheelAnalysis) (for analyzing data from the steering wheel task) 
 
 ### Hardware
 
-Below are the **minimum** computer hardware specs:
-* CPU: 4 logical processors @ 3.0 GHz base speed (e.g. Intel Core i5-6500)
-* RAM: DDR4 16 GB @ 2133 MHz (e.g. Corsair Vengeance 16 GB)
-* GPU: 2 GB @ 1000 MHz base and memory speed (e.g. NVIDIA Quadro P400)
+Below are a few minimum hardware requirements for both PCs.  Precise requirements depend on the type of experiments you wish to run, however most contemporary PC with a dedicated graphics card should suffice. 
 
-For most experiments, typical, contemporary, factory-built desktops running Windows 10 with dedicated graphics cards should suffice. Specific requirements of a SC will depend on the complexity of the experiment. For example, running an audio-visual integration task on multiple screens will require quality graphics and sound cards. SCs may additionally require an i/o device to communicate with external rig hardware, of which only National Instruments Data Acquisition Devices (NI-DAQs, e.g. NI-DAQ USB 6211) are currently supported.
+**Processor:** Intel Core i5-6500 @ 3.0 GHz (or similar)  
+**Graphics:** NVIDIA Quadro P400 (or similar)  
+**Memory:** DDR4 16 GB @ 2133 MHz (e.g. Corsair Vengeance 16 GB)   
 
 ### Software
 
-Below are the **minimum** computer software dependencies that must be installed before installing Rigbox:
+Below are short instructions for installing Rigbox for users familiar with Git and MATLAB.  For detailed instructions, please see the [installation guide](https://cortex-lab.github.io/Rigbox/install.html).
+
+Before starting, ensure the above toolboxes and packages are installed.  PsychToobox can not be installed via the MATLAB AddOns browser.  See [Installing PsychToobox](#Installing-PsychToolbox) for install instructions.  
 
 * OS: 64 Bit Windows 7 or later
 * Libraries: Visual C++ Redistributable Packages for Visual Studio [2013](https://www.microsoft.com/en-us/download/details.aspx?id=40784) & [2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145)
@@ -32,30 +45,40 @@ Below are the **minimum** computer software dependencies that must be installed
 	* [GUI Layout Toolbox](https://uk.mathworks.com/matlabcentral/fileexchange/47982-gui-layout-toolbox) (v2 or later)
 	* [Psychophysics Toolbox](http://psychtoolbox.org/download.html#Windows) (v3 or later)
 
-Similar to the hardware requirements, software requirements for a SC will depend on the experiment: if acquiring data through a NI-DAQ, the SC will require the MATLAB Data Acquisition Toolbox and MATLAB [NI-DAQmx support package](https://uk.mathworks.com/hardware-support/nidaqmx.html) 
+1. To install Rigbox, run the following commands in the Git Bash terminal to clone the repository from GitHub to your local machine.
+```
+git clone --recurse-submodules https://github.com/cortex-lab/Rigbox
+```
+2. Run the `addRigboxPaths.m` function in MATLAB (found in the Rigbox directory) then restart the program.  This adds all required folders and functions to your MATLAB path**.  __NB__: Do __not__ manually add all Rigbox folders and subfolders to the paths
 
-## Installation
+\* Accepting all installer defaults will suffice.  
+** To add the paths temporarily for testing, run `addRigboxPaths('SavePaths', false, 'Strict', false)`
 
 Before starting, ensure you have read and followed the above [requirements section](#requirements).
 
 Below we provide brief instructions for installing Rigbox via Git. For a detailed installation guide, including installing Rigbox's software dependencies, see [here](https://cortex-lab.github.io/Rigbox/detailed_installation.html).
 
-1. Clone the repository from GitHub. In your git terminal, run:
+1. Download and install a Subversion client.  [SilkSVN](https://sliksvn.com/download/) is recommended.
+2. Download and install the [64-Bit GStreamer-1.16.0 MSVC runtime](https://gstreamer.freedesktop.org/data/pkg/windows/1.16.0/gstreamer-1.0-msvc-x86_64-1.16.0.msi).  Make sure all offered packages are installed.
+3. Download the MATLAB [installer function](https://raw.githubusercontent.com/Psychtoolbox-3/Psychtoolbox-3/master/Psychtoolbox/DownloadPsychtoolbox.m) from the PsychToolbox GitHub page.
+4. Call the function in MATLAB with the target install location (folder must exist) and follow the instructions:
 ```
 git clone --recurse-submodules https://github.com/cortex-lab/Rigbox
 ```
 
-2. Add all required Rigbox folders and functions to your MATLAB path. In MATLAB, navigate to the Rigbox root directory (where Rigbox was cloned), and run:
-`addRigboxPaths()`, OR `addRigboxPaths('SavePaths', false)` if you don't want to save the paths for future MATLAB sessions. 
-(*Note*: Do **not** manually add all Rigbox folders and subfolders to the paths.)
-
 ## Getting started
+After following the installation instructions you can start playing around with Rigbox and Signals.  To run one of the example experiments, open MATLAB and run `eui.SignalsTest();`, then select 'advancedChoiceWorld.m'.  
+
+![](https://github.com/cortex-lab/Rigbox/blob/master/docs/html/images/SignalsTest%20GUI%20Example.gif)  
+
+Full Rigbox documentation can be found at [cortex-lab.github.io/Rigbox](https://cortex-lab.github.io/Rigbox/).  
+
+To run the example experiments from the Rigbox paper, see [Running Paper Examples](https://cortex-lab.github.io/Rigbox/paper_examples.html).  
 
-Rigbox uses the *Signals* framework for programatically designing and running behavioral tasks. 
-See the *Signals* [docs](https://github.com/cortex-lab/signals/tree/master/docs) for more information on *Signals* and how to run example test experiments on a single computer via Rigbox's `+eui/SignalsTest.m` GUI.
+For more infomation on using the Signals Test GUI see [this guide](https://cortex-lab.github.io/Rigbox/using_test_gui.html).  
 
-![](https://github.com/cortex-lab/Rigbox/blob/master/docs/html/SignalsTest%20GUI%20Example.gif)
-(The above is an example of running the `signals/docs/examples/exp defs/advancedChoiceWorld.m` file in the `+eui/SignalsTest.m` GUI)
+### Running an experiment
+For running full experiments see the [Setting up experiments](https://cortex-lab.github.io/Rigbox/index.html#2) guide.  This will guide you through configuring a visual viewing model, configuring audio devices and setting up hardware that requires a DAQ.  
 
 For information on running experiments via MC and SC, see Rigbox's [index page](https://github.com/cortex-lab/Rigbox/blob/dev/docs/html/index.html). This page also contains information on setting up Rigbox (see also [`docs/setup`](https://github.com/cortex-lab/Rigbox/tree/master/docs/setup)) and using certain Rigbox features (see also [`docs/usage`](https://github.com/cortex-lab/Rigbox/tree/master/docs/setup)) after an MC and SC installation. Furthermore, this page gives an overview of the repository's organization.
 
@@ -82,5 +105,4 @@ For further information, see [our publication](https://www.biorxiv.org/content/1
 * [Psychophsics Toolbox](http://psychtoolbox.org) for code pertaining to visual stimulus presentation
 * [NI-DAQmx](https://uk.mathworks.com/hardware-support/nidaqmx.html) for code pertaining to inerfacing with a NI-DAQ device
 * [TooTallNate](https://github.com/TooTallNate/Java-WebSocket) for code pertaining to using Java Websockets
-* [Andrew Janke](https://github.com/apjanke) for the `isWindowsAdmin` function
-* [Timothy E. Holy](http://holylab.wustl.edu/) for the `distinguishable_colors` function
+* [Timothy E. Holy](http://holylab.wustl.edu/) for the `distinguishable_colors` function

addRigboxPaths.m

@@ -1,11 +1,10 @@
 function addRigboxPaths(varargin)
 %ADDRIGBOXPATHS Adds the required paths for using Rigbox
-%  addRigboxPaths([savePaths, interactive, strict]) or 
-%  addRigboxPaths('SavePaths', true, 'Interactive', true, 'Strict', true)
+%  addRigboxPaths([savePaths, strict]) or 
+%  addRigboxPaths('SavePaths', true, 'Strict', true)
 %
 %   Inputs (Optional):
 %     savePaths (logical): If true, added paths are saved between sessions
-%     interactive (logical): If true, user may be prompted for input
 %     strict (logical): Assert toolbox & system requirments are all met
 %
 % Part of the Rigging toolbox
@@ -17,7 +16,6 @@ function addRigboxPaths(varargin)
 % Allow positional or Name-Value pairs
 p = inputParser;
 p.addOptional('savePaths', true)
-p.addOptional('interactive', true)
 p.addOptional('strict', true)
 p.parse(varargin{:});
 p = p.Results;
@@ -47,8 +45,15 @@ function addRigboxPaths(varargin)
     'Click <a href="matlab:web(''%s'',''-browser'')">here</a> to install.'],...
     'https://www.microsoft.com/en-us/download/details.aspx?id=48145')
 
+  % Microsoft Visual C++ Redistributable for Visual Studio 2013 must be
+  % installed, check for runtime dll file in system32 folder
+  assert(any(strcmpi('msvcr120.dll',{sys32.name})), 'Rigbox:setup:libraryRequired',...
+    ['Requires Microsoft Visual C++ Redistributable for Visual Studio 2013. ',...
+    'Click <a href="matlab:web(''%s'',''-browser'')">here</a> to install.'],...
+    'https://www.microsoft.com/en-us/download/details.aspx?id=40784')
+
   % Check MATLAB 2017b is running
-  assert(~verLessThan('matlab', '9.3'), 'Requires MATLAB 2017b or later')
+  assert(~verLessThan('matlab', '9.5'), 'Requires MATLAB 2018b or later')
 
   % Check essential toolboxes are installed (common to both master and
   % stimulus computers)
@@ -74,7 +79,8 @@ function addRigboxPaths(varargin)
   info = matlabshared.supportpkg.getInstalled;
   if isempty(info) || ~any(contains({info.Name}, 'NI-DAQmx'))
     warning('Rigbox:setup:toolboxRequired',...
-      ['The stimulus computer requires the National Instruments support package to be installed. '...
+      ['To run full experiments, the stimulus computer requires '...
+      'the National Instruments support package to be installed. '...
       'Click <a href="matlab:web(''%s'',''-browser'')">here</a> to install.'],...
       'https://www.mathworks.com/hardware-support/nidaqmx.html')
   end
@@ -133,7 +139,7 @@ function addRigboxPaths(varargin)
 
 %%% Remind user to copy paths file %%%
 if ~exist('+dat/paths','file')
-  template_paths = fullfile(root, 'docs', 'setup', 'paths_template.m');
+  template_paths = fullfile(root, 'docs', 'scripts', 'paths_template.m');
   new_loc = fullfile(root, '+dat', 'paths.m');
   copied = copyfile(template_paths, new_loc);
   % Check that the file was copied
@@ -157,42 +163,4 @@ function addRigboxPaths(varargin)
   warning('Rigbox:setup:javaNotSetup',...
     'Cannot use java classes without saving new classpath');
 end
-
-%%% Attempt to move dll file for signals %%%
-MSVSC2013URL = 'https://www.microsoft.com/en-us/download/details.aspx?id=40784';
-fileName = fullfile(root, 'signals', 'msvcr120.dll');
-fileExists = any(strcmp('msvcr120.dll',{sys32.name}));
-copied = false;
-if isWindowsAdmin % If user has admin privileges, attempt to copy dll file
-  if fileExists && p.interactive % If there's already a dll file there prompt use to make backup
-    prompt = sprintf(['For signals to work propery, it is nessisary to copy ',...
-      'the file \n<strong>', strrep(fileName, '\', '\\\\'), '</strong> to ',...
-       '<strong>C:\\\\Windows\\\\System32</strong>.\n',...
-      'You may want to make a backup of your existing dll file before continuing.\n\n',...
-      'Alternatively this file is installed with ',...
-      '<a href="matlab:web(''%s'',''-browser'')">',...
-      'Visual C++ Redistributable Packages for Visual Studio 2013</a>\n\n',...
-      'Do you want to proceed with copying? Y/N [Y]: '], MSVSC2013URL);
-    str = input(prompt,'s'); if isempty(str); str = 'y'; end
-    if strcmpi(str, 'n'); return; end % Return without copying
-  end
-  copied = copyfile(fileName, 'C:\Windows\System32');
-end
-% Check that the file was copied
-if ~copied
-  warning('Rigbox:setup:libraryRequired', ['Please copy the file ',...
-    '<strong>%s</strong> to <strong>C:\\Windows\\System32</strong> ',...
-    '\nor install <a href="matlab:web(''%s'',''-browser'')">',...
-    'Visual C++ Redistributable Packages for Visual Studio 2013</a>'], ...
-    fileName, MSVSC2013URL)
-end
-
-function out = isWindowsAdmin()
-%ISWINDOWSADMIN True if this user is in admin role.
-% 2011 Andrew Janke (https://github.com/apjanke)
-if ~NET.isNETSupported; out = false; return; end
-wi = System.Security.Principal.WindowsIdentity.GetCurrent();
-wp = System.Security.Principal.WindowsPrincipal(wi);
-out = wp.IsInRole(System.Security.Principal.WindowsBuiltInRole.Administrator);
-end
 end