WaveSurfer

An application for acquiring neurophysiology data in Matlab

screenshot

Please note that WaveSurfer is currently pre-release software. There will almost certainly be changes to file formats, etc. before version 1.0 is released (in 2017), and we make no promises about backward compatibility.

Key Features

System Requirements

Download

Download the .zip file for the latest release here. Older versions are here.

Version 0.913 and earlier have a bug where they don't record the ADC calibration data from the NI board, leading to 5-7% errors in the signals when read back in with ws.loadDataFile(). Because of this, these versions should not be used, and we no longer make them available here. If you have data files recorded with one of these versions, download the latest version of WaveSurfer and use the ws.addScalingToHDF5FilesRecursively() tool to read the calibration data off your board and append it to your data files.

Installation

  1. In Matlab, check your path for any directories that contain older versions of WaveSurfer, and delete these directories from the path.
  2. Extract the .zip file contents to a convenient location.
  3. In Matlab, cd to this just-created directory.
  4. At the Matlab command line, execute "installWavesurfer". This will permanently modify your Matlab path so that all components needed by WaveSurfer are on it. (If you don't want to permanently modify the path, execute "installWavesurferForNow" instead of the above. This modifies the path only for the current Matlab session.)
  5. At the Matlab command line, execute "wavesurfer". You should now be presented with the WaveSurfer user interface.
  6. Go to Tools > Device & Channels... to specify what DAQ board you want to use, what channels you want to use, and to set channel units and scales, if desired.
  7. In the main window, click the Stimulation > Enabled checkbox to turn on stmulation. Click the Display > Enabled checkbox to show the "oscilloscope" windows where acquired data will be displayed.
  8. In the main window, click the play button (the one with the black righward-pointing arrow) to acquire data without saving to disk. Click the record button (the one with the red circle) to acquire data and save it to disk.
  9. To save your device settings, channel settings, and window positions, go to File > Save Protocol. These can then be loaded in a new WaveSurfer sessions by going to File > Open Protocol...
  10. If you have questions, please contact the WaveSurfer developers.

Important Note about Older Versions of WaveSurfer

Versions 0.913 and earlier have a bug where they don't record the ADC calibration data from the NI board, leading to 5-7% errors in the signals when read back in with ws.loadDataFile(). This bug was fixed in version 0.914. Because of this bug, version 0.913 and earlier should not be used, and we no longer make them available here. If you have data files recorded with one of these versions, download the latest version of WaveSurfer and use the ws.addScalingToHDF5FilesRecursively() tool to read the calibration data off your board and append it to your existing data files. The help for ws.addScalingToHDF5FilesRecursively() provides more details.

Documentation

The user manual for the current version of WaveSurfer is here. An FAQ is here. Manuals for older versions are here. And please do e-mail us if you have questions!

Copyright

Except where noted, all code, documentation, images, and anything else in WaveSurfer is copyright 2013–2017 by the Howard Hughes Medical Institute.

License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Support

WaveSurfer is developed at the HHMI Janelia Research Campus. It is supported by the Svoboda Lab, who initiated the project, and by the Magee, Spruston, Jayaraman, Lee, Hantman, and Koyama Labs. The project is coordinated by Janelia's Scientific Computing Software group.

History

WaveSurfer supplants an earlier application, Ephus, for electrophysiology and similar data-acquisition tasks. WaveSurfer is a from-scratch rewrite of Ephus developed by Janelia's Scientific Computing group, and shares no code with Ephus. Vijay Iyer specified the original design and is the primary author of the Dabs and Most library packages. Patrick Edson was a co-developer of the earliest versions of WaveSurfer. WaveSurfer borrows design features from DataPro, an electrophysiological acquisition and analysis system for Wavemetrics Igor Pro, originally written by Nelson Spruston and later rewritten by Adam L. Taylor.

Current Developers

Adam L. Taylor, taylora [at] hhmi [dot] org
Ben J. Arthur, arthurb [at] hhmi [dot] org
David Ackerman, ackermand [at] hhmi [dot] org
Scientific Computing
Janelia Research Campus
Howard Hughes Medical Institute

Version History

0.74 Feb 26, 2015 Added Axon Multiclamp support. Now store stimulus metadata in the data file header. Now save data as int16 instead of double-precision floating point. Improved ScanImage integration.
0.75 Mar 9, 2015 Fixed bug with scope x-span.
0.76 Mar 11, 2015 Fixed bug with README(!).
0.77 Mar 17, 2015 Now supports timed digital outputs.
0.771 Mar 18, 2015 Updated README to reflect true NI DAQmx driver requirements.
0.772 Mar 18, 2015 Can now change scope y limits during ongoing acquisition.
0.773 March 23, 2015 Fixed bug with trial duration setting not getting propagated to DAQ board on .cfg file load.
0.774 March 25, 2015 Fixed a few more bugs.
0.775 March 25, 2015 Fixed bug that prevented acquisition if some AI channels specified in MDF were marked as inactive.
0.776 April 2, 2015 Added ability to playback arbitrary stimuli from .wav file. Fixed bugs with multiple DO lines and long-duration stimuli, and with stimuli not being generated properly after 1st stimulus episode when externally triggered.
0.777 April 3, 2015 Fixed issue that prevented acquisition if Matlab was installed on a drive other than the C drive.
0.778 April 14, 2015 Now have toggle-able autoscaling of y-axis limits for both scope windows and the test pulse window. Added per-trialset and per-trial (approximate) timestamps to data file. No longer rely upon DABS callbacks during data acquisition, but poll instead. All internally-generated triggers are now themselves triggered off a common "master" trigger on PFI8.
0.779 April 14, 2015 Fixed bug where couldn't test pulse after acquiring data.
0.78 April 15, 2015 Data files for continuous recordings now use the same file naming scheme as trial-based recordings. Fixed bug with fast protocols not getting cleared when you click that button. Added a very simple example user function .m file.
0.781 April 20, 2015 Added more options for data file naming. Fixed several small bugs.
0.782 April 22, 2015 Added a two-pulse stimulus.
0.783 April 22, 2015 Added a generic Matlab expression stimulus.
0.784 April 29, 2015 Test pulser now uses sampling rate of acquisition system.
0.785 May 11, 2015 Inactived AI channels are now really and truly inactivated.
0.786 May 12, 2015 Fixed bug with TestPulser model not getting persisted to disk properly.
0.787 May 12, 2015 Commented out debugging fprintf. Doh!
0.8 May 19, 2015 Added support for digital inputs, untimed digital outputs. Changed user hook function infrastructure to more powerful object-based scheme. Added example user hook classes that implement treadmill- and VR-triggered spike rasters. Many other small tweaks and improvements. Note that version 0.8 will not generally read protocol files from earlier versions.
0.801 June 4, 2015 Made electrodes window narrower, so that it fits on a 1280x1024 screen. Added zoom in/out, scroll up/down buttons to scope windows, got rid of green-on-black color scheme. Test pulser now shows resistance in units tailored to the scale of the resistance value. Protocol and user settings file formats were not changed from release 0.8.
0.802 June 12, 2015 Fixed error on MDF load under R2013b. Added ability to turn on/off scope grids. Protocol and user settings files from release 0.8+ will still work with this release.
0.803 June 29, 2015 Fixed bug in ws.loadDataFile() that made it error if any channels were not active. Protocol and user settings files from release 0.8+ will still work with this release.
0.804 July 3, 2015 Fixed bug that caused warnings on .cfg load if the acquisition sample rate had been changed. Restored green-on-black theme for scope windows as an option. Scope window buttons are now hidden if the window is not tall enough. Added option to always hide scope window buttons. Protocol and user settings files from release 0.8+ will still work with this release.
0.805 July 23, 2015 Fixed bug that made it impossible to record if a user class was in use.
0.9-b-1 Oct 12, 2015 (Beta release) Major redesign of WaveSurfer to support low-latency (< 5 ms) real-time feedback loops. WaveSurfer now spawns two additional Matlab processes when you lauch it: one to aquire data and run real-time feedback loop code, and another to ensure that the sweep-based output buffer is refilled properly. Also some streamlining of the triggering settings, and changes in terminology (e.g. "trials" are now sweeps, an "experiment" is now a run). Note that this is a beta release, so is likely somewhat buggier than a regular release.Fixed bug that made it impossible to record if a user class was in use.
0.9-b-2 Oct 12, 2015 (Beta release) Fixed several bugs.
0.9-b-3 Oct 15, 2015 (Beta release) Fixed capitalization issues in the README.
0.9-b-3 Oct 15, 2015 (Beta release) Fixed capitalization issues in the README.
0.9-b-3 Oct 15, 2015 (Beta release) Fixed capitalization issues in the README.
0.9-b-3 Oct 15, 2015 (Beta release) Fixed capitalization issues in the README.
0.9-b-4 Oct 17, 2015 (Beta release) Fixed another silly cosmetic bug.
0.9-b-5 Oct 29, 2015 (Beta release) Added missing DLL.
0.9-b-6 Oct 30, 2015 (Beta release) Fixed bug where satellite processes didn't have proper search path.
0.9-b-7 Nov 3, 2015 (Beta release) Fixed bug where zero digital inputs caused eventual error during acquisition.
0.9-b-8 Nov 9, 2015 (Beta release) Fixed several bugs.
0.9-b-9 Nov 9, 2015 (Beta release) Cosmetic fix.
0.9-b-10 Nov 11, 2015 (Beta release) Test Pulser now reports resistance in VC mode, instead of conductance. Minor improvements to ws.example.RasterTreadMill.
0.9-b-11 Nov 13, 2015 (Beta release) Fixes to WS-SI coordination code.
0.9-b-12 Nov 18, 2015 (Beta release) Fixed bug with triggering schemes, fixed bug with loading older WS data files.
0.9-b-13 Nov 18, 2015 (Beta release) Fixed bug with mimic()'ing cell arrays.
0.9-b-14 Nov 20, 2015 (Beta release) Fixed bug where didn't work if no input channels were defined.
0.9 Dec 1, 2015 Rechristened 0.9-beta-14 as 0.9. Note that protocol files for WS 0.8x will not work with this version.
0.901 Jan 7, 2016 Added support for DAQmx 15.1.x. Fixed bug in error dialog message if the installed version of DAQmx is not supported by WaveSurfer.
0.91 Feb 12, 2016 All things previously-settable in machine data files (MDFs) are now settable in the normal WaveSurfer user interface. This means users no longer need to create an MDF before using WaveSurfer to acquire data. (Protocol files for previous versions of WS will not work with this version.)
0.912 Mar 1, 2016 Fixed bug in README.
0.913 Mar 2, 2016 Fixed bug which resulted in actual sampling rate being slightly different from nominal sampling rate for sampling rates (in Hz) that do not evenly divide 100 MHz.
0.914 Mar 15, 2016 Fixed bug where data was saved without scaling coefficients. Added code to ws.loadDataFile() convert nominal sampling rate for pre-0.913 data files to correct sampling rate. Added code to ws.loadDataFile() to error if asked to return floating-point (scaled) data when the data file lacks scaling coefficients, as a safeguard.
0.915 Mar 22, 2016 Added tool, ws.addScalingToHDF5FilesRecursively(), to automatically append device scaling information to .h5 data files that currently lack it.
0.916 Apr 14, 2016 All AI channels now explicitly set to differential terminal configuration. Stability and UI improvements.
0.917 Apr 15, 2016 Fixed bug in UI display of AO channel scale units. Verified bug went no deeper.
0.918 May 8, 2016 Fixed many small bugs, changed TemplateUserClass to ExampleUserClass, cleaned up ws.examples package.
0.919 Jun 1, 2016 Can now set test pulse y limits manually. Satellite Matlab windows are now hidden. Fixed issue with sweep timestamps being somewhat off. Improved speed of loading protocol files. Improved handling of old protocol files. Added ability to duplicate stimulus maps. Fixed issue with adding scaling coefficients to data files from WS v0.8.
0.9191 Jun 3, 2016 Fixed bug with listing device AI terminals when device has more than 16 (single-ended) AI terminals.
0.9192 Jun 3, 2016 Fixed bug with adding calibration coefficients to old files taken with devices with more than 16 (single-ended) AI terminals.
0.92 Jun 27, 2016 Added support for more recent versions of DAQmx. Can now duplicate stimuli, maps, sequences. Better support for old protocol files. Fixed bug causing errors on stimulus deletion in some cases. Can now write calibration data to disk, use that file to add calibration to data files. Fixed bug with electrode AO scaling. Added debugging mode which shows satellite windows running in full-JVM Matlab sessions. Added checkbox to optionally turn off electrode gain reading before a run or a test pulse. Added tooltips to fast protocol buttons. Improved speed of protocol file loading. Improvements to display and data scaling speed, especially for long sweeps. Fixed bug where stopping a run at an unlucky moment would put WS into a weird, unusable state.
0.921 Jul 26, 2016 Fixed another bug with manual stopping.
0.93 Aug 12, 2016 New chart-recorder-like display of traces. Improvements to user class handling. Includes two more custom user classes.
0.931 Aug 23, 2016 Fixed bug with loading protocol file with fewer input channels after taking data.
0.932 Sep 6, 2016 Fixed bug where outputs didn't get zeroed after a user-initiated stop.
0.933 Sep 6, 2016 README bug fix.
0.94 Oct 6, 2016 Changes to triggering to make it more flexible. Also made satellite processes leaner, and made changes to the stimulus library go through the main WavesurferModel.
0.941 Oct 14, 2016 Run will now continue past end of acquisition if stimulation is ongoing. Also fixed hangs in some situations.
0.942 Jan 11, 2017 User classes now print debug info to terminal. Updated and streamlined Bias user code. Also fixed bug with map durations loaded from protocol files. Added fix for MultiClamp 700A support provided by Niraj Desai.
0.943 Feb 22, 2017 Fixes to BIAS-WS interface, incorporating our own version of JSONLab.
0.945 Mar 10, 2017 Bug fix for MultiClamp 700A support.

updated March 10, 2017