Merge branch 'dev' into 'master'

CHANGELOG.md

@@ -1,8 +1,8 @@
 # Changelog
 
-Starting after Rigbox 2.2.0, this file contains a curated, chronologically ordered list of notable changes made to the master branch. Each bullet point in the list is followed by the accompanying commit hash, and the date of the commit. This changelog is based on [keep a changelog](https://keepachangelog.com)
+This file contains a curated, chronologically ordered list of notable changes made to the master branch since the release of Rigbox 2.2.0. Each bullet point in the list is followed by the accompanying commit hash, and the date of the commit. The versioning numbering used is [SemVer](http://semver.org/). This changelog is based on [keep a changelog](https://keepachangelog.com).
 
-## [Most Recent Commits](https://github.com/cortex-lab/Rigbox/commits/master) 2.5.0
+## [Most Recent Commits](https://github.com/cortex-lab/Rigbox/commits/master)
 
 - new alyx instance now requested robustly when not logged in during SignalsExp
 - expStop event now logged has missing value when last trial over, even when expStop defined in def fun
@@ -28,7 +28,7 @@ Starting after Rigbox 2.2.0, this file contains a curated, chronologically order
 - added FormatLabels flag to eui.SignalsExpPanel `c5794a8` 2020-02-03
 - HOTFIX Bugfix in signals for versions >2016b & <2018b
 
-## [2.4.1]
+## [2.4.0](https://github.com/cortex-lab/Rigbox/releases/tag/2.4.0)
 
 - patch to readme linking to most up-to-date documentation `4ff1a21` 2019-09-16
 - updates to `+git` package and its tests `5841dd6` 2019-09-24

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-When contributing to this repository, please first discuss the change you wish to make via creation of a [github issue](https://github.com/cortex-lab/Rigbox/issues) (preferred), or email with the [project maintainers](#project-maintainers). Thereafter, contributors should create a new "feature" branch for any changes/additions they wish to make, and then create a pull request for this feature branch. If making a change to a submodule, a pull request should be sent to that submodule's repository. (e.g. if a user is making a change to a file within the signals repository, a pull request should be made to the [signals repository](https://github.com/cortex-lab/signals/pulls), not to the Rigbox repository.) **All pull requests should be made to the `dev` branch of the appropriate repository.**
+When contributing to this repository, please first discuss the change you wish to make via creation of a [github issue](https://github.com/cortex-lab/Rigbox/issues). Thereafter, contributors should create a new 'feature' branch (branched off of the 'dev' branch) for any changes/additions they wish to make, and then create a pull request for merging this feature branch into 'dev'. If making a change to a submodule, a pull request should be sent to that submodule's repository. (e.g. if a user is making a change to a file within the signals repository, a pull request should be made to the [signals repository](https://github.com/cortex-lab/signals/pulls), not to the Rigbox repository.) **TLDR: All feature branches should be branched off of 'dev', and pull requests should be made to 'dev'. If making a change to a submodule, send the pull request to the 'dev' branch of that submodule's repository.** 
 
-Detailed information on the guidelines the project maintainers follow when developing code and reviewing pull requests can be found [here](https://github.com/cortex-lab/Rigbox/tree/master/docs/maintainers/Maintainer_Guidelines.md).
+All pull requests will be reviewed by the project maintainers. Detailed information on the guidelines the project maintainers follow when developing code and reviewing pull requests can be found [here](https://github.com/cortex-lab/Rigbox/tree/master/docs/maintainers/Maintainer_Guidelines.md).
 
 ## Project Maintainers
 

README.md

@@ -3,101 +3,78 @@
 ![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. 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.
+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. For detailed information, see [the publication](https://www.biorxiv.org/content/10.1101/672204v3). 
 
 ## Requirements
 
-For running full experiments Rigbox requires two PCs: one for presenting stimuli and one for monitoring the experiment.  Currently only National Instruments DAQs are supported for acquiring data from hardware devices.  For testing, the toolbox can be run on a single machine.  
+For exploring Rigbox's features and running test experiments, Rigbox only needs to be installed on a single computer.
 
-### Software
-
-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) 
+For running experiments, Rigbox should be installed 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.
 
 ### Hardware
 
-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. 
+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)
 
-**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)   
-
-## Installation
+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 currently only National Instruments Data Acquisition Devices (NI-DAQs, e.g. NI-DAQ USB 6211) are supported.
 
-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).
+### Software
 
-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.  
+Below are the **minimum** computer software dependencies that must be installed before installing Rigbox:
 
-It is highly recommended to install Rigbox via the [Git Bash](https://git-scm.com/download/win) terminal*. 
+* 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)
+* MATLAB: [2018b or later](mathworks.com/downloads/), including the Data Acquisition Toolbox
+* Community MATLAB toolboxes:
+	* [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)
 
-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
+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 additionally require the MATLAB [NI-DAQmx support package](https://uk.mathworks.com/hardware-support/nidaqmx.html).
 
-\* Accepting all installer defaults will suffice.  
-** To add the paths temporarily for testing, run `addRigboxPaths('SavePaths', false, 'Strict', false)`
+## Installation
 
-### Installing PsychToolbox
+Before starting, ensure you have read and installed the above [requirements](#requirements).
 
-PsychToolbox-3 is required for visual and auditory stimulus presentation.  Below are some simple steps for installing PsychToolbox.  For full details see [their documentation](http://psychtoolbox.org/download.html#Windows).
+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. 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:
+1. Clone the repository from GitHub. In your git terminal, run:
 ```
-DownloadPsychtoolbox('C:\') % Install to C drive
+git clone --recurse-submodules https://github.com/cortex-lab/Rigbox
 ```
 
-## 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)  
+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.)
 
-Full Rigbox documentation can be found at [cortex-lab.github.io/Rigbox](https://cortex-lab.github.io/Rigbox/).  
+## Getting started
 
-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*](https://github.com/cortex-lab/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/images/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.  
+To run the example experiments from the Rigbox paper, see [Running Paper Examples](https://cortex-lab.github.io/Rigbox/paper_examples.html).
 
-Information specific to the steering wheel task can be found on the [CortexLab website](https://www.ucl.ac.uk/cortexlab/tools/wheel).
+Online documentation, including detailed set-up and usage guides for running experiments on a MC and SC, can be found at [cortex-lab.github.io/Rigbox](https://cortex-lab.github.io/Rigbox/). 
 
 ## Updating the code
-With Git it's very easy to keep the code up-to-date.  To update Rigbox and all submodules at the same time, run the following in the Git Bash terminal (within the Rigbox directory):
+
+With Git it's very easy to keep the code up-to-date. We strongly recommend regularly updating Rigbox and its submodules by running the following git command (within the Rigbox directory):
 ```
 git pull --recurse-submodules
 ```
 
-When calling `srv.expServer` and `mc`, the code is automatically updated if a new stable release is available.  This behvaiour can be configured with the 'updateSchedule' field in your `+dat/paths.m` file.
-
 ## Contributing
 
-If you experience a bug or have a feature request, please report them on the [GitHub Issues page](https://github.com/cortex-lab/Rigbox/issues).  To contribute code we encourage anyone to open up a pull request into the dev branch of Rigbox or one of its submodules.  Ideally you should include documentation and a test with your feature.
-
-Please read [CONTRIBUTING.md](https://github.com/cortex-lab/Rigbox/blob/dev/CONTRIBUTING.md) for further details on how to contribute, as well as maintainer guidelines and our code of conduct.
+If you experience a bug or have a feature request, please report it via [github Issues](https://github.com/cortex-lab/Rigbox/issues). For details on contributing code and our code of conduct, please see our [contributing page](https://github.com/cortex-lab/Rigbox/blob/master/CONTRIBUTING.md).
 
 ## Authors & Accreditation
 
-Rigbox was started by [Chris Burgess](https://github.com/dendritic/) in 2013. It is now maintained and developed by Miles Wells ([email protected]), Jai Bhagat ([email protected]) and a number of others at [CortexLab](https://www.ucl.ac.uk/cortexlab). See also the full list of [contributors](https://github.com/cortex-lab/Rigbox/graphs/contributors).
+Rigbox was created by [Chris Burgess](https://github.com/dendritic/) in 2013, initially developed to probe mouse behavior for the [Steering Wheel Setup](https://www.ucl.ac.uk/cortexlab/tools/wheel). It is now maintained and developed by Miles Wells ([email protected]), Jai Bhagat ([email protected]) and a number of others at [CortexLab](https://www.ucl.ac.uk/cortexlab). See also the full list of [contributors](https://github.com/cortex-lab/Rigbox/graphs/contributors).
 
-For further information, see [our publication](https://www.biorxiv.org/content/10.1101/672204v3). Please cite this source appropriately in publications which use Rigbox to acquire data.
+Please cite [the Rigbox publication](https://www.biorxiv.org/content/10.1101/672204v3) appropriately in publications which use Rigbox to run behavioral tasks and/or acquire data.
 
 ## Acknowledgements
 

docs/README.md

@@ -1,24 +1,17 @@
 # Documentation:
-This 'docs' folder contains files that are useful for learning how to use and set up Rigbox. To view the docs in HTML open `docs/html/index.html` in the MATLAB browser or visit [cortex-lab.github.io/Rigbox](https://cortex-lab.github.io/Rigbox/):
-```matlab
-root = fileparts(which('addRigboxPaths'));
-url = ['file:///', fullfile(root, 'docs', 'html', 'index.html')];
-web(url)
-```
+This `docs` folder contains information on setting up and using Rigbox, as well as information on the organization of the repository. After installation, we recommend viewing Rigbox's [online documentation], which serves as an easy way to navigate through the information contained in this folder for setting-up and using Rigbox, via your web browser. Alternatively, you can view the `README` files in the `setup` and `usage` folders for instructions on the order in which to view the `.m` guides within these folders in MATLAB.
 
 ## Contents:
-The docs directory contains three things:
 
+- `setup/` - information on how to set up Rigbox on a new rig after installation.
+- `usage/` - information on how to use certain Rigbox features after setup and when running experiments.
+- `html/` - .html files that correspond to the .m files in `setup/` and `usage/`
+- `maintainers/` - files for maintainers which specify design and style choices and how to standardize maintenance and development of Rigbox.
+- `Rigbox UML.pdf` - a UML diagram of Rigbox.
+
+- `index.m` - Rigbox's documentation index page as a .m file. Corresponds to the `html/index.html` file.
+- `Troubleshooting_and_FAQ.m` - information on troubleshooting errors which arise in Rigbox, and frequently asked questions.
 - `scripts/` - The scripts used to generate the html files.  These are useful if you wish to run some of the code in the docs, particularly `hardware_config.m`.
 - `html/` - The html docs and source images.
-- 'maintainers/' - Guidelines for code maintainers.
-- `Rigbox UML.pdf` - A UML diagram of the Rigbox class structure.
-
-
-## Contributing
-If you wish to make changes to the documentation, please follow the below steps:
-1. Make your changes to the documentation scripts on the `documentation` branch.  
-2. Export all changed files to html using MATLAB's 'Publish' feature.  Code execution can be disabled in the Publish Options.
-3. Copy the files from `docs/scripts/html` to `docs/html`.
-4. Run the `fixFiles` script to perform any post processing on the html files.
-5. Once committed to the `documentation` branch, merge this branch onto the `gh-pages` branch and copy the files from `docs/scripts/html` to the repository's root directory.  Commit these changes to the `gh-pages` branch.  They will now show up on the documentation Website.
+- `maintainers/` - Guidelines for code maintainers.
+- `Rigbox UML.pdf` - A UML diagram of the Rigbox class structure.