From 78400ceaedf8113b4fcc6f923f4ba6cc02ad44a7 Mon Sep 17 00:00:00 2001 From: Jai Bhagat Date: Sun, 8 Mar 2020 22:17:05 +0000 Subject: [PATCH] updated docs --- CHANGELOG.md | 6 +- CONTRIBUTING.md | 4 +- README.md | 73 +++++++------------ docs/README.md | 29 +++----- docs/html/Parameters.html | 4 + docs/html/hardware_config.html | 44 +++++------ docs/maintainers/Maintainer_Guidelines.md | 16 ++-- docs/maintainers/README.md | 3 +- docs/{scripts => maintainers}/fixFiles.m | 0 docs/{scripts => setup}/Burgess_setup.m | 0 docs/setup/README.md | 7 ++ docs/{scripts => setup}/glossary.m | 0 docs/{scripts => setup}/hardware_config.m | 0 docs/{scripts => setup}/id_index.m | 0 docs/{scripts => setup}/index.m | 0 docs/{scripts => setup}/install.m | 0 docs/{scripts => setup}/packages.m | 0 docs/{scripts => setup}/paths_config.m | 0 docs/{scripts => setup}/paths_template.m | 0 .../troubleshooting_and_faq.m} | 0 docs/{scripts => setup}/websocket_config.m | 0 docs/{scripts => usage}/Parameters.m | 0 docs/usage/README.md | 10 +++ docs/{scripts => usage}/Timeline.m | 0 docs/usage/running_experiments.m | 29 ++++++++ docs/{scripts => usage}/using_ExpPanel.m | 0 docs/{scripts => usage}/using_dat_package.m | 0 docs/{scripts => usage}/using_services.m | 0 docs/{scripts => usage}/using_single_rig.m | 0 docs/{scripts => usage}/using_test_gui.m | 0 .../{scripts => usage}/using_visual_stimuli.m | 0 docs/{scripts => usage}/using_wheel.m | 0 32 files changed, 119 insertions(+), 106 deletions(-) rename docs/{scripts => maintainers}/fixFiles.m (100%) rename docs/{scripts => setup}/Burgess_setup.m (100%) create mode 100644 docs/setup/README.md rename docs/{scripts => setup}/glossary.m (100%) rename docs/{scripts => setup}/hardware_config.m (100%) rename docs/{scripts => setup}/id_index.m (100%) rename docs/{scripts => setup}/index.m (100%) rename docs/{scripts => setup}/install.m (100%) rename docs/{scripts => setup}/packages.m (100%) rename docs/{scripts => setup}/paths_config.m (100%) rename docs/{scripts => setup}/paths_template.m (100%) rename docs/{scripts/troubleshooting.m => setup/troubleshooting_and_faq.m} (100%) rename docs/{scripts => setup}/websocket_config.m (100%) rename docs/{scripts => usage}/Parameters.m (100%) create mode 100644 docs/usage/README.md rename docs/{scripts => usage}/Timeline.m (100%) create mode 100644 docs/usage/running_experiments.m rename docs/{scripts => usage}/using_ExpPanel.m (100%) rename docs/{scripts => usage}/using_dat_package.m (100%) rename docs/{scripts => usage}/using_services.m (100%) rename docs/{scripts => usage}/using_single_rig.m (100%) rename docs/{scripts => usage}/using_test_gui.m (100%) rename docs/{scripts => usage}/using_visual_stimuli.m (100%) rename docs/{scripts => usage}/using_wheel.m (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 960e2454..dfc084ac 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 37e85493..c7e9cc66 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index b8d00952..58384f7a 100644 --- a/README.md +++ b/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 exploring Rigbox's features and running test experiments, Rigbox only needs to be installed on a single computer. -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) +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. ### Software -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. +Below are the **minimum** computer software dependencies that must be installed before installing Rigbox: * 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: 2017b or later, including the Data Acquisition Toolbox +* 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 -Before starting, ensure you have read and followed the above [requirements section](#requirements). +Before starting, ensure you have read and installed the above [requirements](#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. 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: ``` 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). -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. +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. We strongly recommend regularly updating Rigbox and its submodules by running the following git commands (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 ``` ## 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/master/CONTRIBUTING.md) for details on how to contribute code to this repository 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 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 (miles.wells@ucl.ac.uk), Jai Bhagat (j.bhagat@ucl.ac.uk) 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 diff --git a/docs/README.md b/docs/README.md index 6f9fcafa..5ded1d3c 100644 --- a/docs/README.md +++ b/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. \ No newline at end of file diff --git a/docs/html/Parameters.html b/docs/html/Parameters.html index e31e4ebf..d3357926 100644 --- a/docs/html/Parameters.html +++ b/docs/html/Parameters.html @@ -405,6 +405,8 @@ % % v1.1.1 +% INTERNAL: +% ln209 ParamEditor.png %#ok<*NOPTS,*ASGLU,*NASGU>


Published with MATLAB® R2019a