The GUI during an experiment was refurbished and improved. Two major

features were added: the possibility to pause and stop a recording. The
code has been extensively tested in our lab over several months and
no bugs have been detected so far.

CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing to the Control Software of our Experimental Setups
+
+First of all (and **most importantly**), we only want to have code contributions that follow basic coding guidelines. There is no specific guideline for this repository chosen yet, the current ones should become pretty obvious when browsing the existing code.
+
+* Lines should be no longer than **80 characters**
+* All names (even local variables) must reflect the meaning of its entity
+* All methods/functions need a docstring describing its purpose, arguments and return values
+* If possible, program object-oriented. Example classes (to compare coding guidelines) are [DesignIterator](misc/experiment_design/DesignIterator.m) and [RecordingDesign](misc/experiment_design/RecordingDesign.m)
+* All changes should be well documented
+
+## What can be pushed to the *master* branch?
+
+Only code, that is general for all kinds of supported experimental setups may be pushed to the [control](control) folder. Supported experimental setups are only restricted by the capabilities of a NIDAQ board.
+
+Whenever you have to develope code, that is specific to a certain experiment, you are obligated to **create a new branch**. Otherwise, you would render the software potentially unusable for future experiments.
+
+If you intend to push code specific to a certain experiment type (such as an evaluation pipeline for *active-avoidance* experiments), then you have to make sure, that the code is as general as possible with respect to all possibilities covered by this experimental type (if not possible, documented these cases well). If you cannot go through this effort, you have to develope your program in a separate branch.

README.md

@@ -1,16 +1,16 @@
 # Conducting sophisticated Fear Conditioning, Active Avoidance and other Experiments with a Single Software 
 
-This repository is meant to control fear conditioning (FC), active avoidance (AA) or other experimental setups. The software was developed in the lab of [Benjamin Grewe](https://www.ini.uzh.ch/people/bgrewe). The code allows a simple way to design and run complex experiments and record for multiple subjects in parallel; all controlled and aligned with a single computer. It also contains an expressive evaluation pipeline for FC experiments to automatically evaluate the outcome of an experiment once the data is acquired.
+This repository is meant to control fear conditioning (FC), active avoidance (AA) or other experimental setups. The software was developed in the lab of [Benjamin Grewe](https://www.ini.uzh.ch/people/bgrewe). The code allows a simple way to design and run complex real-time experiments and record for multiple subjects in parallel; all controlled and aligned with a single computer. It also contains an expressive evaluation pipeline for FC experiments to automatically evaluate the outcome of an experiment once the data is acquired.
 
 ## Installation
 
 The software is developed in Matlab (tested with Matlab R2017b). It makes use of several toolboxes, such as the [Image Acquisition Toolbox](https://ch.mathworks.com/products/imaq.html) and the [Data Acquisition Toolbox](https://ch.mathworks.com/products/daq.html).
 
-Before running the programs, make sure that all the **required libraries** are downloaded and stored in the folder `lib`. A list of all required libraries and their download links are provided in the `lib` folder.
+Before running the programs, make sure that all the **required libraries** are downloaded and stored in the folder [lib](lib). A list of all required libraries and their download links are provided in the [lib](lib) folder.
 
 ## Documentation
 
-More documentation is provided in the folder `docs`. The code is well documented and should be straight-forward to use by users, that are familiar with Matlab. After reading the documentation, one should start by exploring the repository (just opening files and reading their docstrings). Additional documentation can be requested from <[email protected]>.
+More documentation is provided in the folder [docs](docs). The code is well documented and should be straight-forward to use by users, that are familiar with Matlab. After reading the documentation, one should start by exploring the repository (just opening files and reading their docstrings). Additional documentation can be requested from <[email protected]>.
 
 ## Experimental Setup
 
@@ -41,7 +41,11 @@ We now provide a detailed explanation for some of the above folders.
 
 ### Control
 
-The fear conditioning or active-avoidance setup is controlled by the `run_experiment` script in the folder `control`. An experiment is configured via `params.m` in the same folder. Recordings can either be controlled by a design file or generated ad-hoc (note, automatically generated design files only allow very simplistic designs).
+The setup is controlled by the [run_experiment](control/run_experiment.m) script in the folder [control](control). The control software provides a user-friendly way to conduct an experiment. Its focus lays on **ensuring the correct timing of all stimuli, such that they can be precisely aligned with neural recordings**.
+
+![A screenshot of the control software during a recording. Note, the content is blurred.](docs/imgs/recording_view_screenshot.PNG)
+
+An experiment is configured via [params.m](control/params.m) in the same folder. Recordings can either be controlled by a design file or generated ad-hoc (note, automatically generated design files only allow very simplistic designs).
 
 Here is a short summary of the main features currently implemented (June 24th, 2018):
 * Capability to run multiple recordings in parallel
@@ -51,12 +55,13 @@ Here is a short summary of the main features currently implemented (June 24th, 2
 * Sounds can be played via the NIDAQ board or via the soundcard (in which case one can record them to correct timing afterwards)
 * Recordings can be started via an external trigger
 * Arbitrary trigger signals can be generated
+* Sessions can be paused and terminated
 
 ### Experiments
-All experiment related scripts should be in the folder `experiments`. The subfolders contain code specific to an experiment, including how to generate the design file. Note, that some experiments may use outdated design file formats. One can always check the design file format via the script `misc/experiment_design/check_design_file.m`. In the folder `experiments/examples` are examples specifically designed to make new users familiar with the design file programming. 
+All experiment related scripts should be in the folder [experiments](experiments). The subfolders contain code specific to an experiment, including how to generate the design file. Note, that some experiments may use outdated design file formats. One can always check the design file format via the script [check_design_file](misc/experiment_design/check_design_file.m). In the folder [experiments/examples](experiments/examples) are examples specifically designed to make new users familiar with the design file programming. 
 
 ### Evaluation
-Preliminary evaluation scripts are available in the folder `evaluation`. **Note**, we currently provide only code for FC experiments. The provided evaluation pipeline only looks at the animals behavior.
+Preliminary evaluation scripts are available in the folder [evaluation](evaluation). **Note**, we currently provide only code for FC experiments. The provided evaluation pipeline only looks at the animals behavior.
 
 The evaluation code requires that freezing traces have been extracted beforehand. The freezing detection software is currently hosted in another repository *FreezingDetection*. To get access to our freezing detection pipeline, please contact <[email protected]> or <[email protected]>.
 
@@ -76,10 +81,10 @@ The design file is one of the most important aspects, as it completely defines t
 
 The design file itself is a file named `experiment.mat`, that contains a variable `experiment`.
 
-The design file is the only piece that a user has to contribute to control its experiment with this software collection. It adheres a certain format that can be checked via the script `misc/experiment_design/check_design_file.m`.
+The design file is the only piece that a user has to contribute to control its experiment with this software collection. It adheres a certain format that can be checked via the script [check_design_file](misc/experiment_design/check_design_file.m).
 
 The design file is contained in the design folder (which may incorparate other files that are referenced in the design file via relative paths (e.g., sound files)). The experiment is designed in a tree structure (where edges may be multi-edges). The first level are *cohorts*, which themselves split into *groups* (one may also think of groups and subgroups). These are divided into *sessions*, which are split into *subjects*.
 
-Please run the script `experiments/examples/fear_conditioning/generate_fc_design_file.m` to generate an example design folder. The script expects an output folder name as argument. Please explore the resulting `experiment.mat` file (it also generates a JSON file with the same content, in case this is easier to read).
+Please run the script [experiments/examples/fear_conditioning/generate_fc_design_file.m](experiments/examples/fear_conditioning/generate_fc_design_file.m) to generate an example design folder. The script expects an output folder name as argument. Please explore the resulting `experiment.mat` file (it also generates a JSON file with the same content, in case this is easier to read).
 
-A detailed explanantion of design file format can be found in the `docs` folder.
+A detailed explanantion of design file format can be found in the [docs](docs) folder.

TODO.md

@@ -6,10 +6,11 @@
 
 ## Setup Control
 * Add plots, that show output design of all channels.
-* Allow cancelling the recording while it is running (delete cameras, reset nidaq, write 0 to all used NIDAQ channels).
 * Replace assertions by meaningful error messages.
-* Add more visualizations (feedback) during a recording (e.g., state if an event is pushed to the NIDQAQ). TODO, what to do, during bulkmode? -> Solution, decouple output from data pushed to the NIDAQ (just use the NIDQQ start time timestamp to align events from the design file with the OS time) 
-* Add a few example `params.m` files.
+* Add a few example [params](control/params.m) files.
+* Log events at correct time. When data is send to the event logger (`RecViewCtrl.logEvent`), we should also pass a time stamp. Then we put these events into a queue (sorted by their time stamp). We can then log the events at the right time by clearing the queue inside the function `updateTime` (there doesn't seem to be a good priority queue implementation in Matlab).
+* Tool [take_reference_frame](control/tools/take_reference_frame.m): Ensure that ROIs close to a boundary are pushed to the boundary.
+* When a pause (or continue) request is scheduled in [queueOutputDesign](control/experiment_design/queueOutputDesign.m), then set a session variable indicating when the scheduled window will start. This can be used in the GUI as a static text field, that shows how many seconds are left until the session actually pauses/continues.
 
 ## Evaluation
 * For memory efficiency, traces are currently stored as event lists. However, to extract information from them we convert them to binary traces over time. Instead, we should add function that allows to condition and compare event-lists.
@@ -22,10 +23,11 @@
 * One could redo it from scratch, where the design itself is decomposed into objects (shocks (inherited from digital events), sounds (inherited from analog events), analog and digital itself inherited from events ...), that can be serialized and written to a file.
 * Write a GUI that visualizes an experimental design (plot single subject designs, play tones, ...).
 * Maybe we write some classes that give an interface to read and manipulate designs, this could be used to create designs, control them and to evaluate an experiment.
-* Enrich the method `getRelFolder` of class `DesignIterator`, such that singletons are not part of the path (e.g., an experiment that only contains a single cohort, doesn't need *Cohort1* in its path). How to ensure downwards compatibility? We could check whether the `p.rootDir` already exists and what path is used there? Note, that an auto-generated design would still require the full path.
+* Enrich the method `getRelFolder` of class [DesignIterator](misc/experiment_design/DesignIterator.m), such that singletons are not part of the path (e.g., an experiment that only contains a single cohort, doesn't need *Cohort1* in its path). How to ensure downwards compatibility? We could check whether the `p.rootDir` already exists and what path is used there? Note, that an auto-generated design would still require the full path.
 
 ## Postprocessing
 * There should be a common postprocessing for all recordings independent of the experiment type. Possible tasks are listed below. The goal is, that the user doesn't have to care about recording issues when evaluating the data
 * Correct sound onset timing if sound card has been used
 * Handle dropped camera frames
 * If miniscope recording has been triggered via NIDAQ, then align all timestamps
+* If the user has stopped a recording, then the written data (inputs, outputs and video) have inconsistent timestamps. That should be corrected.