# tfile

## PURPOSE

tfile reads the data from an RDI ASCII output file and puts the

## SYNOPSIS

function [A]=tfile(fullName,screenData,ignoreBS);

## DESCRIPTION

     tfile reads the data from an RDI ASCII output file and puts the
     data in a Matlab data structure with major groups of:
     Sup - supporing data
     Wat - water data
     Nav - navigation data including GPS.
     Sensor - Sensor data
     Q - discharge related data

     The data can be screened (screenData=1) so that invalid data are set to
     nan or data reflect strictly the ASCII output file (screenData=0). If
     screenData=0 then the data reflect the ASCII file and -32768 and other
     RDI defined values are left in the data structure. If screenData=1 the
     RDI defined values are trapped and set to nan for many variables.

     WinRiver II will sometimes put a $ instead of the correct values for
     intensity of backscatter. Setting ignoreBS=1 will skip decoding the
     intensity of backscatter data to compensate for this bug in WR2.

     David S. Mueller, USGS, Office of Surface Water
     Frank L. Engel, USGS, Illinois Water Science Center

## CROSS-REFERENCE INFORMATION

This function calls:

- nansum NANSUM Sum, ignoring NaNs.

This function is called by:

- ReadFiles % Read in multiple ASCII .TXT Files
- STA_MeanProfile Compute the mean priole from stationary measurements at a point.
- STA_MeanProfileV2 Compute the mean profile from stationary measurements at a point.

## SOURCE CODE

    0001 function [A]=tfile(fullName,screenData,ignoreBS);
    0002 % tfile reads the data from an RDI ASCII output file and puts the
    0003 % data in a Matlab data structure with major groups of:
    0004 % Sup - supporing data
    0005 % Wat - water data
    0006 % Nav - navigation data including GPS.
    0007 % Sensor - Sensor data
    0008 % Q - discharge related data
    0009 %
    0010 % The data can be screened (screenData=1) so that invalid data are set to
    0011 % nan or data reflect strictly the ASCII output file (screenData=0). If
    0012 % screenData=0 then the data reflect the ASCII file and -32768 and other
    0013 % RDI defined values are left in the data structure. If screenData=1 the
    0014 % RDI defined values are trapped and set to nan for many variables.
    0015 %
    0016 % WinRiver II will sometimes put a $ instead of the correct values for
    0017 % intensity of backscatter. Setting ignoreBS=1 will skip decoding the
    0018 % intensity of backscatter data to compensate for this bug in WR2.
    0019 %
    0020 % David S. Mueller, USGS, Office of Surface Water
    0021 % Frank L. Engel, USGS, Illinois Water Science Center
    0022
    0023 %% Initial Scan of File
    0024 %  Initial scan required to preallocate arrays. All ensembles must be
    0025 %  scanned because RiverRay has variable number of bins.
    0026
    0027 % Turn off LaTex interpreter to avoid subscripts in filenames containing _
    0028 set(0, 'DefaulttextInterpreter', 'none');
    0029 fid=fopen(fullName);
    0030 % clc
    0031 % disp(['Scanning Data File: ' fullName]);
    0032 idx=find(fullName=='\',1,'last');
    0033 fileName=fullName(idx:end);
    0034
    0035 % Display waitbar
    0036 waitmessage=['Reading ' fileName];
    0037 hwait=waitbar(0,waitmessage);
    0038
    0039 % Scan Fixed Leader.
    0040 lineIn=fgetl(fid);
    0041 lineIn=fgetl(fid);
    0042 lineIn=fgetl(fid);
    0043
    0044 % Count lines in file.
    0045 k=1;
    0046 fileEnd=0;
    0047
    0048 % Loop required to determine number of variable leader lines due to bug
    0049 % in ASCII output from WinRiver II for reference set to NONE.
    0050 check=0;
    0051 linecount=0;
    0052 while check==0
    0053     lineIn=fgetl(fid);
    0054     idxBT=strfind(lineIn,'BT');
    0055     idxGGA=strfind(lineIn,'GGA');
    0056     idxVTG=strfind(lineIn,'VTG');
    0057     idxNone=strfind(lineIn,'NONE');
    0058     check=nansum([idxBT idxGGA idxVTG idxNone]);
    0059     linecount=linecount+1;
    0060 end
    0061
    0062 % Read number of bins in 1st ensemble
    0063 [bins(k),~,~,~,~,~]=strread(lineIn,'%f %s %s %s %f %f',1);
    0064
    0065 % Skip bin data
    0066 dummy=textscan(fid, '%s %*[^\n]',bins(k));
    0067
    0068 % Set number of leader lines to get to number of bins in variable
    0069 % leader
    0070 leaderlines=linecount-1;
    0071
    0072 % Begin loop to determin number of ensembles and maximum number of bins
    0073 % for preallocating arrays. Looping through the entire file is required
    0074 % because RiverRay data have variable numbers of bins in each ensemble.
    0075 while fileEnd==0
    0076     dummy=textscan(fid, '%s %*[^\n]',leaderlines);
    0077     if length(dummy{1})>1
    0078         k=k+1;
    0079         bins(k)=cell2mat(textscan(fid, '%f %*[^\n]',1));
    0080         dummy=textscan(fid, '%s %*[^\n]',bins(k));
    0081     end
    0082     fileEnd=feof(fid);
    0083 end
    0084
    0085 % Update waitbar
    0086 waitbar(0.1);
    0087 %% Complete scan of input file.
    0088 % Close input file and report that the initial scan is completed.
    0089 fclose(fid);
    0090 % disp('Scan Complete');
    0091
    0092 %% Initialize Data Structure
    0093 % Preallocates arrays based on information from initial scan.
    0094
    0095 % This is the number of ensembles actually contained in the input file.
    0096 noe=k;
    0097 bins=max(bins);
    0098
    0099 % Initialize Data Structure.
    0100 Sup=struct( 'absorption_dbpm',nan(noe,1),...
    0101     'bins',nan(noe,1),...
    0102     'binSize_cm',nan(1),...
    0103     'nBins',nan(1),...
    0104     'blank_cm',nan(1),...
    0105     'draft_cm',nan(1),...
    0106     'ensNo',nan(noe,1),...
    0107     'nPings',nan(1),...
    0108     'noEnsInSeg',nan(noe,1),...
    0109     'noe',nan(1),...
    0110     'note1',blanks(80),...
    0111     'note2',blanks(80),...
    0112     'intScaleFact_dbpcnt',nan(noe,1),...
    0113     'intUnits',repmat(blanks(5),noe,1),...
    0114     'vRef',repmat(blanks(4),noe,1),...
    0115     'wm',nan(1),...
    0116     'units',repmat(blanks(2),noe,1),...
    0117     'year',nan(noe,1),...
    0118     'month',nan(noe,1),...
    0119     'day',nan(noe,1),...
    0120     'hour',nan(noe,1),...
    0121     'minute',nan(noe,1),...
    0122     'second',nan(noe,1),...
    0123     'sec100',nan(noe,1),...
    0124     'timeElapsed_sec',nan(noe,1),...
    0125     'timeDelta_sec100',nan(1));
    0126
    0127 Wat=struct( 'binDepth',nan(bins,noe),...
    0128     'backscatter',nan(bins,noe,4),...
    0129     'vDir',nan(bins,noe),...
    0130     'vMag',nan(bins,noe),...
    0131     'vEast',nan(bins,noe),...
    0132     'vError',nan(bins,noe),...
    0133     'vNorth',nan(bins,noe),...
    0134     'vVert',nan(bins,noe),...
    0135     'percentGood',nan(bins,noe));
    0136
    0137 Nav=struct( 'bvEast',nan(noe,1),...
    0138     'bvError',nan(noe,1),...
    0139     'bvNorth',nan(noe,1),...
    0140     'bvVert',nan(noe,1),...
    0141     'depth',nan(noe,4),...
    0142     'dsDepth',nan(noe,1),...
    0143     'dmg',nan(noe,1),...
    0144     'length',nan(noe,1),...
    0145     'totDistEast',nan(noe,1),...
    0146     'totDistNorth',nan(noe,1),...
    0147     'altitude',nan(noe,1),...
    0148     'altitudeChng',nan(noe,1),...
    0149     'gpsTotDist',nan(noe,1),...
    0150     'gpsVariable',nan(noe,1),...
    0151     'gpsVeast',nan(noe,1),...
    0152     'gpsVnorth',nan(noe,1),...
    0153     'lat_deg',nan(noe,1),...
    0154     'long_deg',nan(noe,1),...
    0155     'nSats',nan(noe,1),...
    0156     'hdop',nan(noe,1));
    0157
    0158 Sensor=struct(  'pitch_deg',nan(noe,1),...
    0159     'roll_deg',nan(noe,1),...
    0160     'heading_deg',nan(noe,1),...
    0161     'temp_degC',nan(noe,1));
    0162
    0163 Q=struct(   'endDepth',nan(noe,1),...
    0164     'endDist',nan(noe,1),...
    0165     'bot',nan(noe,1),...
    0166     'end',nan(noe,1),...
    0167     'meas',nan(noe,1),...
    0168     'start',nan(noe,1),...
    0169     'top',nan(noe,1),...
    0170     'unit',nan(bins,noe),...
    0171     'startDepth',nan(noe,1),...
    0172     'startDist',nan(noe,1));
    0173
    0174 Sup.noe=noe;
    0175
    0176 %% Read File and Store Data
    0177 % All data are read and stored in preallocated data structures
    0178
    0179 % Reopen File for Reading
    0180 fid=fopen(fullName);
    0181 % disp('Reading Data File');
    0182
    0183 % Read Fixed Leader
    0184 Sup.note1=fgetl(fid);
    0185 Sup.note2=fgetl(fid);
    0186 C = textscan(fid,'%u %u %u %u %u %u %u',1);
    0187 [...
    0188     Sup.binSize_cm,...
    0189     Sup.blank_cm,...
    0190     Sup.draft_cm,...
    0191     Sup.nBins,...
    0192     Sup.nPings,...
    0193     Sup.timeDelta_sec100,...
    0194     Sup.wm] = deal(C{:});
    0195
    0196 % Read Variable Leader
    0197 waitstep = floor(noe/100);
    0198 for n = 1:noe;
    0199     % Update the waitbar only on whole percents
    0200     if ~mod(n, waitstep) || n==noe
    0201         waitbar(0.1+n/noe);
    0202     end
    0203     C = textscan(fid,'%u %u %u %u %u %f %f %u %u %f %f %f %f',1);
    0204     [...
    0205         Sup.year(n),...
    0206         Sup.month(n),...
    0207         Sup.day(n),...
    0208         Sup.hour(n),...
    0209         Sup.minute(n),...
    0210         Sup.second(n),...
    0211         Sup.sec100(n),...
    0212         Sup.ensNo(n),...
    0213         Sup.noEnsInSeg(n),...
    0214         Sensor.pitch_deg(n),...
    0215         Sensor.roll_deg(n),...
    0216         Sensor.heading_deg(n),...
    0217         Sensor.temp_degC(n)] = deal(C{:});
    0218
    0219     % Required logic to account for bug in ASCII output when the
    0220     % reference is set to NONE.
    0221     C = textscan(fid,'%f %f %f %f %f %f %f %f %f %f %f %f',1);
    0222     if sum(isnan([C{:}]))==0
    0223         [...
    0224             Nav.bvEast(n),...
    0225             Nav.bvNorth(n),...
    0226             Nav.bvVert(n),...
    0227             Nav.bvError(n),...
    0228             Nav.dsDepth(n),...
    0229             Nav.altitude(n),...
    0230             Nav.altitudeChng(n),...
    0231             Nav.gpsVariable(n),...
    0232             Nav.depth(n,1),...
    0233             Nav.depth(n,2),...
    0234             Nav.depth(n,3),...
    0235             Nav.depth(n,4)] = deal(C{:});
    0236
    0237         C = textscan(fid,'%f %f %f %f %f',1);
    0238         [...
    0239             Nav.length(n),...
    0240             Sup.timeElapsed_sec(n),...
    0241             Nav.totDistNorth(n),...
    0242             Nav.totDistEast(n),...
    0243             Nav.dmg(n)] = deal(C{:});
    0244
    0245         C = textscan(fid,'%f %f %f %f %f',1);
    0246         [...
    0247             Nav.lat_deg(n),...
    0248             Nav.long_deg(n),...
    0249             Nav.gpsVeast(n),...
    0250             Nav.gpsVnorth(n),...
    0251             Nav.gpsTotDist(n)] = deal(C{:});
    0252     else
    0253         [...
    0254             Nav.dsDepth(n),...
    0255             Nav.altitude(n),...
    0256             Nav.altitudeChng(n),...
    0257             Nav.gpsVariable(n),...
    0258             Nav.depth(n,1),...
    0259             Nav.depth(n,2),...
    0260             Nav.depth(n,3),...
    0261             Nav.depth(n,4)]=deal(C{1:8});
    0262
    0263         C = textscan(fid,'%f %f %f %f %f %f',1);
    0264         [...
    0265             dummy,...
    0266             Nav.lat_deg(n),...
    0267             Nav.long_deg(n),...
    0268             Nav.gpsVeast(n),...
    0269             Nav.gpsVnorth(n),...
    0270             Nav.gpsTotDist(n)] = deal(C{:});
    0271     end
    0272
    0273     % Extract HDOP and number of satellites from gpsVariable
    0274     if Nav.gpsVariable(n)>0
    0275         Nav.hdop(n)=floor(Nav.gpsVariable(n))./10;  %/10 added 3-12-10 by PRJ (according to TRDI WRII manual)
    0276         Nav.nSats(n)=(Nav.gpsVariable(n)-Nav.hdop(n).*10).*100;
    0277     end;
    0278
    0279     C = textscan(fid,'%f %f %f %f %f %f %f %f %f',1);
    0280     [...
    0281         Q.meas(n),...
    0282         Q.top(n),...
    0283         Q.bot(n),...
    0284         Q.start(n),...
    0285         Q.startDist(n),...
    0286         Q.end(n),...
    0287         Q.endDist(n),...
    0288         Q.startDepth(n),...
    0289         Q.endDepth(n)] = deal(C{:});
    0290
    0291     C = textscan(fid,'%f %s %s %s %f %f',1);
    0292     [...
    0293         Sup.bins(n),...
    0294         Sup.units,...
    0295         Sup.vRef,...
    0296         Sup.intUnits,...
    0297         Sup.intScaleFact_dbpcnt(n),...
    0298         Sup.absorption_dbpm(n)]= deal(C{:});
    0299
    0300     % Read Profile Data.
    0301
    0302
    0303     % Logic to account for WR2 bug that puts $ in for intensity or
    0304     % backscatter.
    0305     if ignoreBS==0
    0306         C = textscan(fid,'%f %f %f %f %f %f %f %f %f %f %f %f %f',Sup.bins(n));
    0307         [...
    0308             Wat.binDepth(1:Sup.bins(n),n),...
    0309             Wat.vMag(1:Sup.bins(n),n),...
    0310             Wat.vDir(1:Sup.bins(n),n),...
    0311             Wat.vEast(1:Sup.bins(n),n),...
    0312             Wat.vNorth(1:Sup.bins(n),n),...
    0313             Wat.vVert(1:Sup.bins(n),n),...
    0314             Wat.vError(1:Sup.bins(n),n),...
    0315             Wat.backscatter(1:Sup.bins(n),n,1),...
    0316             Wat.backscatter(1:Sup.bins(n),n,2),...
    0317             Wat.backscatter(1:Sup.bins(n),n,3),...
    0318             Wat.backscatter(1:Sup.bins(n),n,4),...
    0319             Wat.percentGood(1:Sup.bins(n),n),...
    0320             Q.unit(1:Sup.bins(n),n)] = deal(C{:});
    0321     else
    0322         C = textscan(fid,'%f %f %f %f %f %f %f %s %s %s %s %f %f',Sup.bins(n));
    0323         [...
    0324             Wat.binDepth(1:Sup.bins(n),n),...
    0325             Wat.vMag(1:Sup.bins(n),n),...
    0326             Wat.vDir(1:Sup.bins(n),n),...
    0327             Wat.vEast(1:Sup.bins(n),n),...
    0328             Wat.vNorth(1:Sup.bins(n),n),...
    0329             Wat.vVert(1:Sup.bins(n),n),...
    0330             Wat.vError(1:Sup.bins(n),n),...
    0331             dummy,...
    0332             dummy,...
    0333             dummy,...
    0334             dummy,...
    0335             Wat.percentGood(1:Sup.bins(n),n),...
    0336             Q.unit(1:Sup.bins(n),n)] = deal(C{:});
    0337     end
    0338
    0339 end % for loop through ensembles
    0340
    0341 % Close File
    0342 fclose(fid);
    0343 % disp('Data Input Complete');
    0344
    0345 %% Screen Data
    0346 % Screens invalid data replacing them with nan
    0347
    0348 % Apply data screening if requested.
    0349 if screenData==1
    0350
    0351     Wat.vNorth(Wat.vNorth==-32768)=nan;
    0352     Wat.vEast(Wat.vEast==-32768)=nan;
    0353     Wat.vError(Wat.vError==-32768)=nan;
    0354     Wat.vVert(Wat.vVert==-32768)=nan;
    0355     Wat.vMag(Wat.vMag==-32768)=nan;
    0356     Wat.vDir(Wat.vDir==-32768)=nan;
    0357     Wat.percentGood(Wat.percentGood==-32768)=nan;
    0358     Wat.backscatter(Wat.backscatter==-32768)=nan;
    0359
    0360
    0361     Nav.bvNorth(Nav.bvNorth==-32768)=nan;
    0362     Nav.bvEast(Nav.bvEast==-32768)=nan;
    0363     Nav.bvError(Wat.vError==-32768)=nan;
    0364     Nav.bvVert(Nav.bvVert==-32768)=nan;
    0365     Nav.depth(Nav.depth==0)=nan;
    0366     Nav.lat_deg(Nav.lat_deg==30000)=nan;
    0367     Nav.long_deg(Nav.long_deg==30000)=nan;
    0368     Nav.gpsVnorth(Nav.gpsVnorth==-32768)=nan;
    0369     Nav.gpsVeast(Nav.gpsVeast==-32768)=nan;
    0370     Q.unit(Q.unit==2147483647)=nan;
    0371 end;
    0372
    0373 % Assign Data to One Structure
    0374 A.Sup=Sup;
    0375 A.Wat=Wat;
    0376 A.Nav=Nav;
    0377 A.Sensor=Sensor;
    0378 A.Q=Q;
    0379
    0380 % Close waitbar
    0381 close(hwait);