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

 tfile accepts RioGrande, RiverRay, or StreamPro WinRiver II produced
 ASCII files. 
 
 NOTE: With the edition of RiverRay functionality (March 2014), tfile was
 modified to output binSize and binDepth as matrices (because the RiverRay
 ADCP can vary bin sizes from ensemble to ensemble, and near surface bins
 are pulse-coherent (WM3), and thus can be smaller than deeper bins).
 Although this shouldn't change previous software that uses tfile, it may
 cause errors if not accounted for.
 
 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
 Justin A. Boldt, USGS, Kentucky Water Science Center

 Last Modified: 03-26-2014

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

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 % tfile accepts RioGrande, RiverRay, or StreamPro WinRiver II produced
0011 % ASCII files.
0012 %
0013 % NOTE: With the edition of RiverRay functionality (March 2014), tfile was
0014 % modified to output binSize and binDepth as matrices (because the RiverRay
0015 % ADCP can vary bin sizes from ensemble to ensemble, and near surface bins
0016 % are pulse-coherent (WM3), and thus can be smaller than deeper bins).
0017 % Although this shouldn't change previous software that uses tfile, it may
0018 % cause errors if not accounted for.
0019 %
0020 % The data can be screened (screenData=1) so that invalid data are set to
0021 % nan or data reflect strictly the ASCII output file (screenData=0). If
0022 % screenData=0 then the data reflect the ASCII file and -32768 and other
0023 % RDI defined values are left in the data structure. If screenData=1 the
0024 % RDI defined values are trapped and set to nan for many variables.
0025 %
0026 % WinRiver II will sometimes put a $ instead of the correct values for
0027 % intensity of backscatter. Setting ignoreBS=1 will skip decoding the
0028 % intensity of backscatter data to compensate for this bug in WR2.
0029 %
0030 % David S. Mueller, USGS, Office of Surface Water
0031 % Frank L. Engel, USGS, Illinois Water Science Center
0032 % Justin A. Boldt, USGS, Kentucky Water Science Center
0033 %
0034 % Last Modified: 03-26-2014
0035 
0036 
0037 %% Initial Scan of File
0038 %  Initial scan required to preallocate arrays. All ensembles must be
0039 %  scanned because RiverRay has variable number of bins.
0040 
0041 % Turn off LaTex interpreter to avoid subscripts in filenames containing _
0042 set(0, 'DefaulttextInterpreter', 'none');
0043 fid=fopen(fullName);
0044 % clc
0045 % disp(['Scanning Data File: ' fullName]);
0046 idx=find(fullName=='\',1,'last');
0047 fileName=fullName(idx:end);
0048 
0049 % Display waitbar
0050 waitmessage=['Reading ' fileName];
0051 hwait=waitbar(0,waitmessage);
0052 
0053 % Scan Fixed Leader.
0054 lineIn=fgetl(fid);
0055 lineIn=fgetl(fid);
0056 lineIn=fgetl(fid);
0057 
0058 % Count lines in file.
0059 k=1;
0060 fileEnd=0;
0061 
0062 % Loop required to determine number of variable leader lines due to bug
0063 % in ASCII output from WinRiver II for reference set to NONE.
0064 check=0;
0065 linecount=0;
0066 while check==0
0067     lineIn=fgetl(fid);
0068     idxBT=strfind(lineIn,'BT');
0069     idxGGA=strfind(lineIn,'GGA');
0070     idxVTG=strfind(lineIn,'VTG');
0071     idxNone=strfind(lineIn,'NONE');
0072     check=nansum([idxBT idxGGA idxVTG idxNone]);
0073     linecount=linecount+1;
0074 end
0075 
0076 % Read number of bins in 1st ensemble
0077 [bins(k),~,~,~,~,~]=strread(lineIn,'%f %s %s %s %f %f',1);
0078 
0079 % Skip bin data
0080 dummy=textscan(fid, '%s %*[^\n]',bins(k));
0081 
0082 % Set number of leader lines to get to number of bins in variable
0083 % leader
0084 leaderlines=linecount-1;
0085 
0086 % Begin loop to determine number of ensembles and maximum number of bins
0087 % for preallocating arrays. Looping through the entire file is required
0088 % because RiverRay data have variable numbers of bins in each ensemble.
0089 while fileEnd==0
0090     dummy=textscan(fid, '%s %*[^\n]',leaderlines);
0091     if length(dummy{1})>1
0092         k=k+1;
0093         bins(k)=cell2mat(textscan(fid, '%f %*[^\n]',1));
0094         dummy=textscan(fid, '%s %*[^\n]',bins(k));
0095     end
0096     fileEnd=feof(fid);
0097 end
0098 
0099 % Update waitbar
0100 waitbar(0.1);
0101 %% Complete scan of input file.
0102 % Close input file and report that the initial scan is completed.
0103 fclose(fid);
0104 % disp('Scan Complete');
0105 
0106 %% Initialize Data Structure
0107 % Preallocates arrays based on information from initial scan.
0108 
0109 % This is the number of ensembles actually contained in the input file.
0110 noe=k;
0111 bins=max(bins);
0112 
0113 % Initialize Data Structure.
0114 Sup=struct( 'absorption_dbpm',nan(noe,1),...
0115     'bins',nan(noe,1),...
0116     'binSize_cm',nan(bins,noe),... % Now a matrix to handle RR variable bins (Mar 2014)
0117     'nBins',nan(1),...   % nan(noe,1)
0118     'blank_cm',nan(1),...
0119     'draft_cm',nan(1),...
0120     'ensNo',nan(noe,1),...
0121     'nPings',nan(1),...
0122     'noEnsInSeg',nan(noe,1),...
0123     'noe',nan(1),...
0124     'note1',blanks(80),...
0125     'note2',blanks(80),...
0126     'intScaleFact_dbpcnt',nan(noe,1),...
0127     'intUnits',repmat(blanks(5),noe,1),...
0128     'vRef',repmat(blanks(4),noe,1),...
0129     'wm',nan(1),...
0130     'units',repmat(blanks(2),noe,1),...
0131     'year',nan(noe,1),...
0132     'month',nan(noe,1),...
0133     'day',nan(noe,1),...
0134     'hour',nan(noe,1),...
0135     'minute',nan(noe,1),...
0136     'second',nan(noe,1),...
0137     'sec100',nan(noe,1),...
0138     'timeElapsed_sec',nan(noe,1),...
0139     'timeDelta_sec100',nan(1));
0140 
0141 Wat=struct( 'binDepth',nan(bins,noe),...
0142     'backscatter',nan(bins,noe,4),...
0143     'vDir',nan(bins,noe),...
0144     'vMag',nan(bins,noe),...
0145     'vEast',nan(bins,noe),...
0146     'vError',nan(bins,noe),...
0147     'vNorth',nan(bins,noe),...
0148     'vVert',nan(bins,noe),...
0149     'percentGood',nan(bins,noe));
0150 
0151 Nav=struct( 'bvEast',nan(noe,1),...
0152     'bvError',nan(noe,1),...
0153     'bvNorth',nan(noe,1),...
0154     'bvVert',nan(noe,1),...
0155     'depth',nan(noe,4),...
0156     'dsDepth',nan(noe,1),...
0157     'dmg',nan(noe,1),...
0158     'length',nan(noe,1),...
0159     'totDistEast',nan(noe,1),...
0160     'totDistNorth',nan(noe,1),...
0161     'altitude',nan(noe,1),...
0162     'altitudeChng',nan(noe,1),...
0163     'gpsTotDist',nan(noe,1),...
0164     'gpsVariable',nan(noe,1),...
0165     'gpsVeast',nan(noe,1),...
0166     'gpsVnorth',nan(noe,1),...
0167     'lat_deg',nan(noe,1),...
0168     'long_deg',nan(noe,1),...
0169     'nSats',nan(noe,1),...
0170     'hdop',nan(noe,1));
0171 
0172 Sensor=struct(  'pitch_deg',nan(noe,1),...
0173     'roll_deg',nan(noe,1),...
0174     'heading_deg',nan(noe,1),...
0175     'temp_degC',nan(noe,1));
0176 
0177 Q=struct(   'endDepth',nan(noe,1),...
0178     'endDist',nan(noe,1),...
0179     'bot',nan(noe,1),...
0180     'end',nan(noe,1),...
0181     'meas',nan(noe,1),...
0182     'start',nan(noe,1),...
0183     'top',nan(noe,1),...
0184     'unit',nan(bins,noe),...
0185     'startDepth',nan(noe,1),...
0186     'startDist',nan(noe,1));
0187 
0188 Sup.noe=noe;
0189 
0190 %% Read File and Store Data
0191 % All data are read and stored in preallocated data structures
0192 
0193 % Reopen File for Reading
0194 fid=fopen(fullName);
0195 % disp('Reading Data File');
0196 
0197 % Read Fixed Leader
0198 Sup.note1=fgetl(fid);
0199 Sup.note2=fgetl(fid);
0200 C = textscan(fid,'%u %u %u %u %u %u %u',1);
0201 [...
0202     dummy,... % binSize is now computed for each ensemble (Mar 2014)
0203     ...Sup.binSize_cm,... % This was the original (for RGs)
0204     Sup.blank_cm,...
0205     Sup.draft_cm,...
0206     Sup.nBins,...
0207     Sup.nPings,...
0208     Sup.timeDelta_sec100,...
0209     Sup.wm] = deal(C{:});
0210 
0211 % Adjustment needed to correctly read Sup.nBins for RiverRay files. The
0212 % fixed header line in the ASCII output from WinRiverII is not correct for
0213 % RiverRay files because it just uses the number of bins in the first
0214 % ensemble. This assumption was fine for Rio Grandes but not for RiverRays.
0215 % Instead, need to use the max(bins) value from the initial scan.
0216 % Use the max(bins) value from the initial scan for RiverRay files.
0217 % (added 2/20/2014 jab)
0218 if Sup.nBins ~= bins
0219     Sup.nBins = bins;
0220 end
0221 
0222 % Read Variable Leader
0223 waitstep = floor(noe/100);
0224 for n = 1:noe;
0225     % Update the waitbar only on whole percents
0226     if ~mod(n, waitstep) || n==noe
0227         waitbar(0.1+n/noe);
0228     end
0229     C = textscan(fid,'%u %u %u %u %u %f %f %u %u %f %f %f %f',1);
0230     [...
0231         Sup.year(n),...
0232         Sup.month(n),...
0233         Sup.day(n),...
0234         Sup.hour(n),...
0235         Sup.minute(n),...
0236         Sup.second(n),...
0237         Sup.sec100(n),...
0238         Sup.ensNo(n),...
0239         Sup.noEnsInSeg(n),...
0240         Sensor.pitch_deg(n),...
0241         Sensor.roll_deg(n),...
0242         Sensor.heading_deg(n),...
0243         Sensor.temp_degC(n)] = deal(C{:});
0244     
0245     % Required logic to account for bug in ASCII output when the
0246     % reference is set to NONE.
0247     C = textscan(fid,'%f %f %f %f %f %f %f %f %f %f %f %f',1);
0248     if sum(isnan([C{:}]))==0
0249         [...
0250             Nav.bvEast(n),...
0251             Nav.bvNorth(n),...
0252             Nav.bvVert(n),...
0253             Nav.bvError(n),...
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{:});
0262         
0263         C = textscan(fid,'%f %f %f %f %f',1);
0264         [...
0265             Nav.length(n),...
0266             Sup.timeElapsed_sec(n),...
0267             Nav.totDistNorth(n),...
0268             Nav.totDistEast(n),...
0269             Nav.dmg(n)] = deal(C{:});
0270         
0271         C = textscan(fid,'%f %f %f %f %f',1);
0272         [...
0273             Nav.lat_deg(n),...
0274             Nav.long_deg(n),...
0275             Nav.gpsVeast(n),...
0276             Nav.gpsVnorth(n),...
0277             Nav.gpsTotDist(n)] = deal(C{:});
0278     else
0279         [...
0280             Nav.dsDepth(n),...
0281             Nav.altitude(n),...
0282             Nav.altitudeChng(n),...
0283             Nav.gpsVariable(n),...
0284             Nav.depth(n,1),...
0285             Nav.depth(n,2),...
0286             Nav.depth(n,3),...
0287             Nav.depth(n,4)]=deal(C{1:8});
0288         
0289         C = textscan(fid,'%f %f %f %f %f %f',1);
0290         [...
0291             dummy,...
0292             Nav.lat_deg(n),...
0293             Nav.long_deg(n),...
0294             Nav.gpsVeast(n),...
0295             Nav.gpsVnorth(n),...
0296             Nav.gpsTotDist(n)] = deal(C{:});
0297     end
0298     
0299     % Extract HDOP and number of satellites from gpsVariable
0300     if Nav.gpsVariable(n)>0
0301         Nav.hdop(n)=floor(Nav.gpsVariable(n))./10;  %/10 added 3-12-10 by PRJ (according to TRDI WRII manual)
0302         Nav.nSats(n)=(Nav.gpsVariable(n)-Nav.hdop(n).*10).*100;
0303     end;
0304     
0305     C = textscan(fid,'%f %f %f %f %f %f %f %f %f',1);
0306     [...
0307         Q.meas(n),...
0308         Q.top(n),...
0309         Q.bot(n),...
0310         Q.start(n),...
0311         Q.startDist(n),...
0312         Q.end(n),...
0313         Q.endDist(n),...
0314         Q.startDepth(n),...
0315         Q.endDepth(n)] = deal(C{:});
0316     
0317     C = textscan(fid,'%f %s %s %s %f %f',1);
0318     [...
0319         Sup.bins(n),...
0320         Sup.units,...
0321         Sup.vRef,...
0322         Sup.intUnits,...
0323         Sup.intScaleFact_dbpcnt(n),...
0324         Sup.absorption_dbpm(n)]= deal(C{:});
0325     
0326     % Read Profile Data.
0327     
0328     
0329     % Logic to account for WR2 bug that puts $ in for intensity or
0330     % backscatter.
0331     if ignoreBS==0
0332         C = textscan(fid,'%f %f %f %f %f %f %f %f %f %f %f %f %f',Sup.bins(n));
0333         [...
0334             Wat.binDepth(1:Sup.bins(n),n),...
0335             Wat.vMag(1:Sup.bins(n),n),...
0336             Wat.vDir(1:Sup.bins(n),n),...
0337             Wat.vEast(1:Sup.bins(n),n),...
0338             Wat.vNorth(1:Sup.bins(n),n),...
0339             Wat.vVert(1:Sup.bins(n),n),...
0340             Wat.vError(1:Sup.bins(n),n),...
0341             Wat.backscatter(1:Sup.bins(n),n,1),...
0342             Wat.backscatter(1:Sup.bins(n),n,2),...
0343             Wat.backscatter(1:Sup.bins(n),n,3),...
0344             Wat.backscatter(1:Sup.bins(n),n,4),...
0345             Wat.percentGood(1:Sup.bins(n),n),...
0346             Q.unit(1:Sup.bins(n),n)] = deal(C{:});
0347     else
0348         C = textscan(fid,'%f %f %f %f %f %f %f %s %s %s %s %f %f',Sup.bins(n));
0349         [...
0350             Wat.binDepth(1:Sup.bins(n),n),...
0351             Wat.vMag(1:Sup.bins(n),n),...
0352             Wat.vDir(1:Sup.bins(n),n),...
0353             Wat.vEast(1:Sup.bins(n),n),...
0354             Wat.vNorth(1:Sup.bins(n),n),...
0355             Wat.vVert(1:Sup.bins(n),n),...
0356             Wat.vError(1:Sup.bins(n),n),...
0357             dummy,...
0358             dummy,...
0359             dummy,...
0360             dummy,...
0361             Wat.percentGood(1:Sup.bins(n),n),...
0362             Q.unit(1:Sup.bins(n),n)] = deal(C{:});
0363     end
0364     
0365 end % for loop through ensembles
0366 
0367 % Close File
0368 fclose(fid);
0369 % disp('Data Input Complete');
0370 
0371 %% Screen Data
0372 % Screens invalid data replacing them with nan
0373 
0374 % Apply data screening if requested.
0375 if screenData==1
0376     
0377     Wat.vNorth(Wat.vNorth==-32768)=nan;
0378     Wat.vEast(Wat.vEast==-32768)=nan;
0379     Wat.vError(Wat.vError==-32768)=nan;
0380     Wat.vVert(Wat.vVert==-32768)=nan;
0381     Wat.vMag(Wat.vMag==-32768)=nan;
0382     Wat.vDir(Wat.vDir==-32768)=nan;
0383     Wat.percentGood(Wat.percentGood==-32768)=nan;
0384     Wat.backscatter(Wat.backscatter==-32768)=nan;
0385     
0386     
0387     Nav.bvNorth(Nav.bvNorth==-32768)=nan;
0388     Nav.bvEast(Nav.bvEast==-32768)=nan;
0389     Nav.bvError(Wat.vError==-32768)=nan;
0390     Nav.bvVert(Nav.bvVert==-32768)=nan;
0391     Nav.depth(Nav.depth==0)=nan;
0392     Nav.lat_deg(Nav.lat_deg==30000)=nan;
0393     Nav.long_deg(Nav.long_deg==30000)=nan;
0394     Nav.gpsVnorth(Nav.gpsVnorth==-32768)=nan;
0395     Nav.gpsVeast(Nav.gpsVeast==-32768)=nan;
0396     Q.unit(Q.unit==2147483647)=nan;
0397 end;
0398 
0399 
0400 % Set min & max bin size for RiverRay
0401 % -----------------------------------
0402 if strcmp(Sup.units(1,1),'f')
0403     rrMinBinSize=0.328083;
0404 else
0405     rrMinBinSize=0.10;
0406 end
0407 
0408 % Compute the bin sizes (all probes)
0409 % ----------------------------------
0410 binDepth=Wat.binDepth;
0411 nBins=Sup.bins;
0412 idx=~isnan(binDepth);
0413 for i=1:noe;
0414     if nBins(i)>1
0415         maxBinSize=binDepth(nBins(i),i)-binDepth(nBins(i)-1,i);
0416     else
0417         maxBinSize=binDepth(nBins(i));
0418     end
0419     difBinDepth=diff(binDepth(:,i));
0420     binSize(:,i)=repmat(maxBinSize,size(binDepth,1),1);
0421     
0422     % Enforce min binSize for RiverRay
0423     if Sup.wm==3 
0424         binSize((difBinDepth-maxBinSize)<-0.03,i)=rrMinBinSize;
0425     end
0426 end
0427 % Write result to structure as a matrix
0428 Sup.binSize_cm = binSize.*100;
0429 
0430 
0431 % Assign Data to One Structure
0432 A.Sup=Sup;
0433 A.Wat=Wat;
0434 A.Nav=Nav;
0435 A.Sensor=Sensor;
0436 A.Q=Q;
0437 
0438 % Close waitbar
0439 close(hwait);

Generated on Thu 21-Aug-2014 10:40:31 by m2html © 2005