NIMSread.m

% NIMSread.m - a program to read raw NIMS data files such as DATA.BIN
%
% NB: J.Booker's fortran program nimsread.f90 performs all sorts of checks
%     which this code at present is not capable of.
%
% Currently this program only saves the data as Matlab variables but does
% not write out a *.bin or an *.sp file. This is done in order to give the
% user a chance to correct any inaccuracies in the meta data.
%
% NOTE: This program renames the raw NIMS format binary file DATA.BIN
%       to fname.nim, where fname = metaData.runID
getOS;
[dataFile, dataPath] = uigetfile('*.bin; *.bnn; *.BIN; *.nim; *.NIM; *.raw');
fileRoot = dataFile(1:find(dataFile=='.')-1);

% N_HOURS = 24*60; % 2 months
% N_DAYS = N_HOURS/24;
% disp(['The maximum of ' int2str(N_HOURS) ' hours (' num2str(N_DAYS) ' days) of 1 Hz data will be read.']);

% start of data in hex: 01 19 (1 HZ) or 01 83 (8 HZ)
% usually safe to assume that 01 + integer <= 255 starts that data stream;
% but sometimes the header contains some hex garbage in GPS INFO.
index = [hex2dec('19') hex2dec('83')];

%  open file and read header; close file
[Header,nHeader,HZ] = NIMSreadHeader([dataPath dataFile],index);

% 1 Mb of 1 Hz data contains roughly 12 hours
rawfile = dir([dataPath dataFile]);
rawlen = ceil(12*rawfile.bytes/1024/1024);

if HZ == 4
	rawlen = 1.5*ceil(rawlen/4); % 1.5 needed to avoid cutting off files
    disp(['The file appears to contain approximately ' int2str(rawlen) ' hours of 4 Hz data.']);
elseif HZ == 8
	rawlen = 1.5*ceil(rawlen/8); % 1.5 needed to avoid cutting off files
    disp(['The file appears to contain approximately ' int2str(rawlen) ' hours of 8 Hz data.']);
else
    disp(['The file appears to contain approximately ' int2str(rawlen) ' hours of 1 Hz data.']);
end
    
% This estimate is good enough to use it for reading: 1.03 * nsec for 1 Hz (tested)

N_HOURS = rawlen;

% open file and seek to the start of data, then read N_HOURS of data
[Data,GPS,seq,stat,iERR,tBox,tHead,HZ] = NIMSreadBlocks([dataPath dataFile],HZ,nHeader,N_HOURS);

% delete duplicate data blocks, if present
[dupl,seq,Data,GPS,tBox,tHead,stat,duplData] = removeDuplicates(seq,Data,GPS,tBox,tHead,stat,HZ);

% delete spiky data blocks, if present (and not removed earlier)
[spike,seq,Data,GPS,tBox,tHead,stat,spikeData] = removeSpikes(seq,Data,GPS,tBox,tHead,stat,HZ);

% create and initialize the metaData structure
metaData = initMetaData(Header,GPS,seq,stat,dupl,HZ) %#ok<NOPTS,NOPRT>

% rename the original binary file to runID.nim
if ~isempty(metaData.runID)
    cd (dataPath);
    status = system([cmd 'mv ' dataFile ' ' metaData.runID '.nim']);
    if status==0 % if rename successful
        disp(['System call successful: ' ...
            'mv ' dataFile ' ' metaData.runID '.nim']);
        dataFile = [metaData.runID '.nim'];
    end
end

README = ['Data(nch,npts) is data                                ';...
    'GPS,seq, are raw strings of GPS and sequence bytes    ';...
    'stat is a raw string of status bytes for each block   ';...
    'tBox,tHead, are measured temperature variations       ';...
    'iERR gives block numbers where errors were encountered';...
    'Header is the ascii header from the binary file       ';...
    'metaData structure is extracted from GPS and Header   ';...
    'dupl,duplData are duplicate blocks found and deleted  ';...
    'spike,spikeData are spiky double gaps found & deleted '];