openNEVTracking

  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.
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
  Use OUTPUT = openNEV(fname, 'noread', 'report', 'noparse', 'nowarning', 
                              'nosave', 'nomat', 'uV', 'overwrite').

  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.

    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
    kian@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.

  4.4.3.2: 21 June 2014
    - Fixed a bug where Application name wasn't being read properly.

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