[Master Index] [Index for Toolbox]

# readRaw

## (Toolbox/readRaw.m in BrainStorm 2.0 (Alpha))

### Function Synopsis

    [header, eegData, eventData, outputLog, outputLog2, outputLog3] = readRaw(fileName, eventText);

### Help Text

    READRAW - Reads an EGI epoch-marked simple binary format (epoch-marked raw format) file.
     function [header, eegData, eventData, outputLog, outputLog2, outputLog3] = readRaw(fileName, eventText);
     Reads an EGI epoch-marked simple binary format (epoch-marked raw format) file.

     Epoch-marked raw format: Unsegmented simple binary format (raw format,
                              version # 2, 4 or 6) with event codes <epoc> and <tim0>.

     The single sample records (SSR) are extracted to form the eegData matrix, where
     each column of the matrix (array) is one SSR.
     The  corresponding event records, one per SSR, are extracted to form the
     eventData matrix, where each column of the matrix (array) is one event record.

     Input Arguments: fileName - Name of the EGI epoch-marked simple binary format
                                 file, without the .raw extension.
                                 It must be a MATLAB string.

     Output Arguments: header - MATLAB structure array containing the header info.

                       eegData - m1 by n array containing the continuous EEG data.
                                 m1 = # of channels, n = # of time samples.

                       eventData - m2 by n array containing the corresponding event info.
                                   m2 = # of event types, n = # of time samples

                       outputLog - Character array of header information.

                       outputLog2 - Reports back on the # of data elements
                                    succesfully read.

### Cross-Reference Information

This function is called by

    eeg2bs                             C:\BrainStorm_2001\Toolbox\eeg2bs.m

### Listing of function C:\BrainStorm_2001\Toolbox\readRaw.m

    function [header, eegData, eventData, outputLog, outputLog2, outputLog3] = readRaw(fileName, eventText);
    %READRAW - Reads an EGI epoch-marked simple binary format (epoch-marked raw format) file.
    % function [header, eegData, eventData, outputLog, outputLog2, outputLog3] = readRaw(fileName, eventText);
    % Reads an EGI epoch-marked simple binary format (epoch-marked raw format) file.
    %
    % Epoch-marked raw format: Unsegmented simple binary format (raw format,
    %                          version # 2, 4 or 6) with event codes <epoc> and <tim0>.
    %
    % The single sample records (SSR) are extracted to form the eegData matrix, where
    % each column of the matrix (array) is one SSR.
    % The  corresponding event records, one per SSR, are extracted to form the
    % eventData matrix, where each column of the matrix (array) is one event record.
    %
    % Input Arguments: fileName - Name of the EGI epoch-marked simple binary format
    %                             file, without the .raw extension.
    %                             It must be a MATLAB string.
    %
    % Output Arguments: header - MATLAB structure array containing the header info.
    %
    %                   eegData - m1 by n array containing the continuous EEG data.
    %                             m1 = # of channels, n = # of time samples.
    %
    %                   eventData - m2 by n array containing the corresponding event info.
    %                               m2 = # of event types, n = # of time samples
    %
    %                   outputLog - Character array of header information.
    %
    %                   outputLog2 - Reports back on the # of data elements
    %                                succesfully read.

    %<autobegin> ---------------------- 12-Oct-2004 12:02:46 -----------------------
    % --------- Automatically Generated Comments Block Using AUTO_COMMENTS ---------
    %
    % CATEGORY: Utility - General
    %
    % At Check-in: $Author: Mosher $  $Revision: 2 $  $Date: 10/12/04 10:24a $
    %
    % This software is part of BrainStorm Toolbox Version 2.0 (Alpha) 12-Oct-2004
    %
    % Principal Investigators and Developers:
    % ** Richard M. Leahy, PhD, Signal & Image Processing Institute,
    %    University of Southern California, Los Angeles, CA
    % ** John C. Mosher, PhD, Biophysics Group,
    %    Los Alamos National Laboratory, Los Alamos, NM
    % ** Sylvain Baillet, PhD, Cognitive Neuroscience & Brain Imaging Laboratory,
    %    CNRS, Hopital de la Salpetriere, Paris, France
    %
    % See BrainStorm website at http://neuroimage.usc.edu for further information.
    %
    % Copyright (c) 2004 BrainStorm by the University of Southern California
    % This software distributed  under the terms of the GNU General Public License
    % as published by the Free Software Foundation. Further details on the GPL
    % license can be found at http://www.gnu.org/copyleft/gpl.html .
    %
    % FOR RESEARCH PURPOSES ONLY. THE SOFTWARE IS PROVIDED "AS IS," AND THE
    % UNIVERSITY OF SOUTHERN CALIFORNIA AND ITS COLLABORATORS DO NOT MAKE ANY
    % WARRANTY, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
    % MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, NOR DO THEY ASSUME ANY
    % LIABILITY OR RESPONSIBILITY FOR THE USE OF THIS SOFTWARE.
    %<autoend> ------------------------ 12-Oct-2004 12:02:46 -----------------------

    % ----------------------------- Script History ---------------------------------
    % JCM 11-Oct-2004 Commenting header
    % ----------------------------- Script History ---------------------------------

    %fid = fopen([fileName '.raw'],'r','b');
    fid = fopen([fileName],'r','b'); %Dimitrios change; file already has extension

    if (fid == -1)  % File not found.

        errorMsg = sprintf('\n!!! File %s.raw Not Found !!!\n', fileName);
        error(errorMsg);

    end

    outputLog = ['inputFile = <' fileName '.raw>'];  % Seed the outputLog.

    % ----------------- Read the header info into the structure variable 'header'. -----------------

    header.versionNumber = fread(fid, 1, 'integer*4');
    outputLog = strvcat(outputLog, ['versionNumber = ' int2str(header.versionNumber)]);

    switch header.versionNumber
       case {3, 5, 7}
           errorMsg = sprintf...
               ('\n!!! The File %s.raw Must Contain Unsegmented EEG Data !!!\n', fileName);
           error(errorMsg);
    end

    header.recordingTimeYear = fread(fid, 1, 'integer*2');
    outputLog = strvcat(outputLog, ['recordingTimeYear = ' int2str(header.recordingTimeYear)]);

    header.recordingTimeMonth = fread(fid, 1, 'integer*2');
    outputLog = strvcat(outputLog, ['recordingTimeMonth = ' int2str(header.recordingTimeMonth)]);

    header.recordingTimeDay = fread(fid, 1, 'integer*2');
    outputLog = strvcat(outputLog, ['recordingTimeDay = ' int2str(header.recordingTimeDay)]);

    header.recordingTimeHour = fread(fid, 1, 'integer*2');
    outputLog = strvcat(outputLog, ['recordingTimeHour = ' int2str(header.recordingTimeHour)]);

    header.recordingTimeMinute = fread(fid, 1, 'integer*2');
    outputLog = strvcat(outputLog, ['recordingTimeMinute = ' int2str(header.recordingTimeMinute)]);

    header.recordingTimeSecond = fread(fid, 1, 'integer*2');
    outputLog = strvcat(outputLog, ['recordingTimeSecond = ' int2str(header.recordingTimeSecond)]);

    header.recordingTimeMillisec = fread(fid, 1, 'integer*4');
    outputLog = strvcat(outputLog, ['recordingTimeMillisec = ' int2str(header.recordingTimeMillisec)]);

    header.samplingRate = fread(fid, 1, 'integer*2');
    outputLog = strvcat(outputLog, ['samplingRate = ' int2str(header.samplingRate)]);

    header.numChans = fread(fid, 1, 'integer*2');
    outputLog = strvcat(outputLog, ['numChans = ' int2str(header.numChans)]);

    header.boardGain = fread(fid, 1, 'integer*2');
    outputLog = strvcat(outputLog, ['boardGain = ' int2str(header.boardGain)]);

    header.numConvBits = fread(fid, 1, 'integer*2');
    outputLog = strvcat(outputLog, ['numConvBits = ' int2str(header.numConvBits)]);

    header.ampRange = fread(fid, 1, 'integer*2');
    outputLog = strvcat(outputLog, ['ampRange = ' int2str(header.ampRange)]);

    header.numSamples = fread(fid, 1, 'integer*4');
    outputLog = strvcat(outputLog, ['numSamples = ' int2str(header.numSamples)]);

    header.numEvents = fread(fid, 1, 'integer*2');
    outputLog = strvcat(outputLog, ['numEvents = ' int2str(header.numEvents)]);

    if (header.numEvents ~= 0)  % File contains event info.

        for i = 1:header.numEvents

            header.eventCodes(i) = {fread(fid, [1 4], 'uchar')};
            ithEventCode = char(header.eventCodes{i});
            outputLog = strvcat(outputLog, ['eventCode # ' int2str(i) ' = ' ithEventCode]);

        end

    else  % File does not contain event info.

        usrMsg = sprintf...
           ('\nThe file %s.raw does not contain event information.', fileName);
        disp(usrMsg); outputLog = strvcat(outputLog, usrMsg);

    end

    % ----------------------------- Finished reading the header. -----------------------------------

    switch header.versionNumber
       case 2
           precision = 'integer*2';  % Integer
       case 4
           precision = 'real*4';  % Single Precision Real
       case 6
           precision = 'real*8';  % Double Precision Real
    end

    % -------- Read SSRs into array eegData and corresponding events into array eventData. --------

    eegDataCount = 0; eventDataCount = 0;
    eegData = zeros(header.numChans, header.numSamples);

    if (header.numEvents ~= 0)  % File contains event info.

        eventData = zeros(header.numEvents, header.numSamples);

        for j = 1:header.numSamples

            [eegData(:,j), eegTempCount] = fread(fid, header.numChans, precision);
            [eventData(:,j), eventTempCount] = fread(fid, header.numEvents, precision);
            eegDataCount = eegDataCount + eegTempCount;
            eventDataCount = eventDataCount + eventTempCount;

        end

    else  % File does not contain event info.

        eventData = [];

        [eegData, eegDataCount] = fread(fid, [header.numChans, header.numSamples], precision);

    end

    % ---------------------- Finished reading SSRs and event data. ------------------------

    % Verify that all the data was read.

    if (header.numEvents ~= 0)  % File contains event info.

        if ((eegDataCount ~= header.numChans * header.numSamples) | ...
              (eventDataCount ~= header.numEvents * header.numSamples))

           errorMsg = sprintf...
              ('\n!!! The Data Read Failed.  Could Not Fill EEG & Event Data Arrays !!!\n');
           error(errorMsg);

        end

    else  % File does not contain event info.

        if (eegDataCount ~= header.numChans * header.numSamples)
            errorMsg = sprintf...
                ('\n!!! The Data Read Failed.  Could Not Fill EEG Data Array !!!\n');
        end

    end

    outputLog2 = ['# of eeg data values read = ' int2str(eegDataCount)];  % Seed outputLog2.
    outputLog2 = strvcat...
        (outputLog2,['Array eegData: ' int2str(header.numChans) ' x ' int2str(header.numSamples)]);

    if (header.numEvents ~= 0)  % File contains event info.

        outputLog2 = strvcat(outputLog2,['# of event markers read = ' int2str(eventDataCount)]);
        outputLog2 = strvcat...
            (outputLog2,['Array eventData: ' int2str(header.numEvents) ' x ' int2str(header.numSamples)]);

    end

    fclose(fid);

    if (header.numEvents ~= 0)
        if nargin == 1
            eventText = 'N';
        end
        %eventText = input('\nOutput events to NetStation compatible text file (Y/N)? ', 's');
        if (eventText == 'Y') | (eventText == 'y')
            [outputLog3] = writeEvents(fileName, header, eventData);
        else
            outputLog3 = [];
        end
    else
        outputLog3 = [];
    end

    % That's All Folks.

Produced by color_mat2html, a customized BrainStorm 2.0 (Alpha) version of mat2html on Tue Nov 2 16:17:59 2004
Cross-Directory links are: ON