RunRats, A dispatcher frontend
RunRats is a simplified GUI to streamline and manage the process of running a rig and large numbers of rats. Runrats reads a MySQL-based schedule of rat IDs, rig IDs, and timeslots, and uses that to offer the person running the rig a simplified GUI to start up a protocol and run the appropriate rat. RunRats makes extensive use of the Brody Lab MySQL database system and therefore will not work in its current form outside the lab.
For the technician or researcher running a rat:
In a lab, Runrats would generally be started by a startup script when launching MATLAB. It can be run by typing
at the matlab command line. The list of experimenters and rats is populated from the Rat Registry while the schedule is populated from the schedule. These are both MySQL based tables.
For a quick tutorial on using RunRats see the RunRats section in our Lab Technician Standard Operating Procedure page: Animal Tech SOP: RunRats
A brief list of steps is as follows:
- Before running the first rat for the day click "Flush Valves" to flush the water valves in the rig.
- Pick an experimenter
- Pick a rat
- Press LOAD
- Perform the Manual Test
- When ready, press RUN
- When the experiment is over, press END SESSION
- All done for this rat, go to step 2 for the next rat
For the researcher writing a protocol that will be under the control of Runrats:
When the technician clicks LOAD, an ExperimenterName/RatName combination will already have been selected. Runrats will then take the following steps:
- Run cvs update on the Settings directory for the ExperimenterName/Ratname combination, thus downloading the latest settings files from the cvs server.
- Find the latest settings file with a date not in the future.
- Use the name of that file to determine the protocol to start up. See Protocol Settings for a description of settings filenames and how the protocol is encoded in them.
- Before opening the protocol, runs the Manual Test, which forces the technician to test lights, sounds, pokes, and water delivery.
- After the Manual Test is concluded, open the chosen protocol.
- Once the protocol is open, load the settings file.
- Enable the RUN button, and wait for the technician to click RUN.
- Choice of settings file example: suppose that for rat Carlos/C181 there are settings files 'settings_@Classical_Carlos_C181_111015a.mat', and 'settings_@DelayedOrientation_Carlos_C181_111016a.mat'. Then, for rat Carlos/C181, on the 15-Oct-2011, the @Classical protocol will be started, and the settings file ending in 15a.mat will be loaded for it before the protocol starts running. The next day, on the 16-Oct-2011, the @DelayedOrientation protocol will be started, and the settings file ending in 16a.mat will be loaded for it before the protocol starts running.
When the technician clicks END SESSION, RunRats will then take the following steps:
- RunRats calls dispatcher with a 'Stop' action -- as a protocol writer, you don't need to worry about this, it simply means that the state machine is halted.
- RunRats calls the protocol with an 'end_session' action.
- RunRats saves the session data. It assumes that all protocols have an @saveload plugin. It uses that to save the data from the session. More specifically, RunRats calls the @saveload/SavingSection with action='savedata' and 'interactive'=0.
- RunRats calls the protocol with a 'pre_saving_settings' action.
- RunRats saves the settings for the next day by calling @saveload/SavingSection with action='savesettings' and 'interactive'=0
- RunRats asks dispatcher to close the protocol
Inside your protocol, within 'end_session' you might typically do things like compile summary statistics for today, etc. While within 'pre_saving_settings' you might typically do things like changes to the settings based on what you want the rat to do tomorrow.
RunRats handling of crashes
When a protocol is running the code is kept in a while loop in the RunLoop case in RunningSection.m of dispatcher. Within that while loop is a try/catch designed to catch any errors thrown by the active protocol. When an error is thrown RunRats enters a Crashed state. The large button turns black and reads crashed, and an email with a crash report is sent to the owner(s) of the rat (this is determined using the MySQL based Rat Registry). To resume running rats simply click the CRASHED button and proceed to step 2 for running a rat discussed above.
Any failures in CVS updates of the rat's settings folder will generate an email to the rat's owner(s). Any failures in SVN updates of either the ExperPort or Protocols folders will generate an email to the Brody Lab computer technician.
RunRats Live Mode
The new version of RunRats comes with a live mode that makes use of numerous MySQL based tables to determine which session in the schedule the technician is currently training. It no longer assumes the sessions are tied to the current time, i.e. session 1 8am-10am, session 2 10am-noon... If a rig is not training a rat in the current session, as the end of the session approaches RunRats will automatically update itself to display the rat that is to run in that rig in the next session. If one selects a different rat from the one automatically selected by RunRats the live update will be paused and RunRats will turn red. To resume live update click the "Update Paused / Live Update On" button.
Test Implant Button
This button only appears if the rig has DIO lines specified in the Settings_Custom.conf file with "stim" in their name, e.g. stim1, stim2... Clicking the button will toggle all "stim" lines on and off sequentially. This is designed to serve as a manual test for these lines.
Notes to Technicians
The experimenter can leave a brief note to the technician for a particular rat by entering it in the "Tech Instructions" field in the MySQL based schedule. RunRats only reads the field for that rat on the current day, so different notes can be scheduled for different days in advance. The note appears in the center of the RunRats window just below the Schedule pulldown menu.