openNEV

  openNEV

  Opens an .nev file for reading, returns all file information in a NEV
  structure. Works with File Spec 2.1 & 2.2 & 2.3 & 3.0.
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
  Use OUTPUT = openNEV(fname, 'noread', 'report', 'noparse', 'nowarning', 
                              'nosave', 'nomat', 'uV', 'overwrite', 'direct').

  NOTE: All input arguments are optional. Input arguments may be in any order.

    fname:        Name of the file to be opened. If the fname is omitted
                  the user will be prompted to select a file using an open 
                  file user interface. 
                  DEFAULT: Will open Open File UI.

    'noread':     Will not read the spike waveforms if user passes this argument.
                  DEFAULT: will read spike waveform.

    'report':     Will show a summary report if user passes this argument.
                  DEFAULT: will not show report.

    'parse':    The code will not parse the experimental parameters in digital I/O.
                  See below for guidelines on how to format your parameters.
                  DEFAULT: will not parse the parameters.

    'nowarning':  The code will not give a warning if there is an error in
                  parsing.
                  DEFAULT: will give warning message.

    'nosave':     The code will not save a copy of the NEV structure as a
                  MAT file. By default the code will save a copy in the same
                  folder as the NEV file for easy future access.
                  DEFAULT: will save the MAT file.

    'nomat':      Will not look for a MAT file. This option will force
                  openNEV to open a NEV file instead of any available MAT
                  files.
                  DEFAULT: will load the MAT file if available.

    'uV':         Will read the spike waveforms in unit of uV instead of
                  raw values. Note that this conversion may lead to loss of
                  information (e.g. 15/4 = 4) since the waveforms type will
                  stay in int16. It's recommended to read raw spike
                  waveforms and then perform the conversion at a later
                  time.
                  DEFAULT: will read waveform information in raw.

    '8bits':      Indicates that 8 bits on the digital IO port was used
                  instead of 16 bits.
                  DEFAULT: will assumes that 16 bits of digital IO were used.

    't:':         Indicats the time window of the NEV file to be read. For
                  example, if t: is set to 2 (i.e. 't:0.6')
                  then only the first 2 seconds of the file is to be read. If set
                  to 2-50 (i.e. 't:2:50) then the time between 2 seconds
                  and 50 seconds will be read.
                  DEFAULT: the entire file will be read if 't:xx:xx' is not
                  passed to the function.

    'overwrite':  If MATLAB loads a NEV file using 'nomat' and a MAT file
                  already exists, by default it will prompt the user to
                  allow for overwriting the old MAT. Passing the
                  'overwrite' flag will automatically overwrite the newly
                  opened NEV file ont the old MAT file.
                  DEFAULT: will ask the user whether to overwrite the old
                  MAT.

    'direct':     Use this if you are using a CerePlex Direct system
                  without the typical strobe mode. This will treat the 16th
                  bit of the digital input as a strobe signal and report
                  the remaining 15 bits as the digital input value. 

    OUTPUT:       Contains the NEV structure.

 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    USAGE EXAMPLE: 

    openNEV('report','read');

    In the example above, the file dialogue will prompt for a file. A
    report of the file contents will be shown. The digital data will not be
    parsed. The data needs to be in the proper format (refer below). The 
    spike waveforms are in raw units and not in uV.

 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    DIGITAL PARAMETERS/MARKERS FORMAT:

    In order for this function to parse your experimental parameters they 
    need to be in the following format:

    *ParamLabel:Parameter1=value1;Parameter2=value2;Parameter3=value3;#

    TWO EXAMPLES:
    *ExpParameter:Intensity=1.02;Duration=400;Trials=1;PageSegment=14;#

    *Stimulation:StimCount=5;Duration=10;#

    In the first example, the parameter is of type "ExpParameter". The 
    parameters are, "Intensity, Duration, Trials, and PageSement." The 
    values of those parameters are, "1.02, 400, 1, and 14," respectively.
    The second example is of type "Stimulation". The name of the parameters
    are "StimCount" and "Duration" and the values are "5" and "10" 
    respectively.
    -----------------------------------------------------------------------
    It can also read single value markers that follow the following format.

    *MarkerName=Value;#

    EXAMPLES:  *WaitSeconds=10;# OR  *JuiceStatus=ON;#

    The above line is a "Marker". The marker value is 10 in the first 
    and it's ON in the second example.
    -----------------------------------------------------------------------
    Moreover, the marker could be a single value:

    *MarkerValue#

    EXAMPLES: *JuiceOff#  OR  *HandsOnSwitches#
    -----------------------------------------------------------------------
    The label, parameter name, and values are flexible and can be anything.
    The only required formatting is that the user needs to have a label
    followed by a colon ':', followed by a field name 'MarkerVal', followed
    by an equal sign '=', followed by the parameter value '10', and end
    with a semi-colon ';'.

    NOTE:
    Every line requires a pound-sign '#' at the very end. 
    Every line requires a star sign '*' at the very beginning. If you
    use LabVIEW SendtoCerebus.vi by Kian Torab then there is no need for 
    a '*' in the beginning.

 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    Kian Torab
    support@blackrockmicro.com
    Blackrock Microsystems
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  Version History

  4.4.0.0:
    - Major performance boost in reading NEV files when tracking data is 
    stored in the file.

  4.4.0.2:
    - Updated documentation.

  4.4.0.3: 5 January 2014
    - Fixed the way DayOfWeek is read in MetaTags.
    - Fixed 'noread' argument, so when passed, openNEV will not read the
    spike waveforms.

  4.4.1.0: 25 January 2014
    - Fixed a bug that resulted from passing 'read' to openNEV.

  4.4.2.0: 28 February 2014
    - Fixed bug related to loading data with t:XX:XX argument.

  4.4.3.0: 12 June 2014
    - Fixed a typo in the help.

  4.4.3.1: 13 June 2014
    - Updated the version numbers in the help and in the function itself.

  5.0.0.0: 02 December 2014
    - Fixed a bug where Application name wasn't being read properly.
    - Warnings now don't show up in more places when "nowarning" is used.
    - Added field FileExt to MetaTags.
    - Added 512 synchronized reading capability.
    - Fixed the date in NSx.MetaTags.DateTime.

  5.1.0.0: 28 March 2015
    - Added the ability to read from networked drives in Windows.
    - Fixed the DateTime variable in MetaTags.
    - Fixed the date in NSx.MetaTags.DateTime (again).
    - Fixed a bug related to >512-ch data loading.

  5.1.1.0: 1 April 2015
    - Fixed a bug with NeuroMotive when spike window is changed from the
      original length.

  5.1.2.0: June 30 2015
    - Fixed a bug regarding the number of packages when 'no read' is used.

  5.1.3.0: July 10 2015
    - Fixed a bug with NeuroMotive data reading when both objects and
      markers were being recorded.

  5.2.0.0: June 11 2016
    - Added support for CerePlex Direct strobe mode on digital input.
    - Fixed a bug with reading NeuroMotive data that resulted in a crash.

  5.3.0.0: June 13 2016
    - Fixed a bug with reading NeuroMotive data that resulted in a crash.
    - Improved and more detailed parsing of NeuroMotive events.
    - Added parsing of comment start time and comment committ time (time
      that a comment is entered.

  5.3.1.0: September 1, 2017
    - Fixed a bug with file path and whent this was passed to the function.

  5.4.0.0: September 13, 2017
    - Checks to see if there's a newer version of NPMK is available.
    - Properly reads the comment colors.

  5.4.0.1: January 10, 2018
    - Fixed a NeuroMotive bug when AllMarkers was being recorded.

  5.4.1.0: April 25, 2018
    - Now all comments open in order.
    - Fixed a bug with path of file if both NEV and MAT were moved to a new
      location.

  6.0.0.0: January 27, 2020
    - Added support for 64-bit timestamps in NEV and NSx.
    - Removed dependency on MATLAB R2016b by removing function 'contains'.

  6.1.0.0: April 16, 2020
    - Some bug fixes. (David Kluger)

  6.2.0.0: April 29, 2020
    - Added ability to read all types of recording event types.


 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%