getts

  GETTS  Gets time-series data from from an EPIC style netcdf file, 
         allowing the user to grab the whole time-series, or 
         specify start and stop time.

   USAGE:
       [var,jd] = getts(cdf,var);  % gets whole series
 or
       [var,jd] = getts(cdf,var,start,stop);
 or
   [var,jd,long_name,units,lat,lon,idepth,wdepth] = getts(cdf, var,start,stop);

     outputs: var = time series vector
              jd  = julian day vector
              long_name = long_name for label
              units = data units
              lat = latitude of data 
              lon = longitude of data 
              idepth = instrument depth of data 
              wdepth = water depth of data 

     inputs:  cdf = netcdf file name
              var = netcdf variable name
              start = optional start time  [yyyy mm yy dd hr mi]
              stop = optional stop time  [yyyy mm yy dd hr mi]

 Example:
 [var,jd,l] = getts('time.cdf', 'salinity');   % get all salinity data
 or
 [var,jd,l] = getts('time.cdf', 'salinity', [1990 7 1 0 0 0],[1990 9 1 0 0 0]);

0001 function [var,jd,ln,units,lat,lon,idepth,wdepth] = getts(cdf, var,start,stop)
0002 %  GETTS  Gets time-series data from from an EPIC style netcdf file,
0003 %         allowing the user to grab the whole time-series, or
0004 %         specify start and stop time.
0005 %
0006 %   USAGE:
0007 %       [var,jd] = getts(cdf,var);  % gets whole series
0008 % or
0009 %       [var,jd] = getts(cdf,var,start,stop);
0010 % or
0011 %   [var,jd,long_name,units,lat,lon,idepth,wdepth] = getts(cdf, var,start,stop);
0012 %
0013 %     outputs: var = time series vector
0014 %              jd  = julian day vector
0015 %              long_name = long_name for label
0016 %              units = data units
0017 %              lat = latitude of data
0018 %              lon = longitude of data
0019 %              idepth = instrument depth of data
0020 %              wdepth = water depth of data
0021 %
0022 %     inputs:  cdf = netcdf file name
0023 %              var = netcdf variable name
0024 %              start = optional start time  [yyyy mm yy dd hr mi]
0025 %              stop = optional stop time  [yyyy mm yy dd hr mi]
0026 %
0027 % Example:
0028 % [var,jd,l] = getts('time.cdf', 'salinity');   % get all salinity data
0029 % or
0030 % [var,jd,l] = getts('time.cdf', 'salinity', [1990 7 1 0 0 0],[1990 9 1 0 0 0]);
0031 %
0032 
0033 %
0034 %Rich Signell               |  rsignell@crusty.er.usgs.gov
0035 %U.S. Geological Survey     |  (508) 457-2229  |  FAX (508) 457-2310
0036 %Quissett Campus            |
0037 %Woods Hole, MA  02543      |
0038 %
0039 % Show usage if too few arguments.
0040 %
0041 % needs FILL_ATTNAMES, FILL_VARNAMES, CHECK_STRING, JULIAN, THUMBFIN
0042 if nargin~=2 & nargin~=4,
0043    help getts;
0044    return;
0045 end
0046 %
0047 % Open netCDF file
0048 %
0049 % eliminate trailing blanks from name
0050 ind=find(cdf==' ');
0051 if(~isempty(ind)),cdf=cdf(1:ind-1);end
0052  
0053 [cdfid,rcode ]=mexcdf('open',cdf,'NOWRITE');
0054 if rcode < 0
0055    s = [ 'mexcdf: ncopen: rcode = ' int2str(rcode) ];
0056    disp (s)
0057    return
0058 end
0059 
0060 %
0061 %
0062 % Suppress netCDF error messages
0063 
0064 [rcode] = mexcdf('setopts', 0);
0065 %
0066 % Get variable id
0067 %
0068 [varid,rcode]=mexcdf('varid',cdfid,var);
0069 if ( rcode < 0 | varid < 0 )
0070    disp([ 'MexCDF error:  Couldn''t find variable ' var]) 
0071    return
0072 end
0073 
0074 [var_name,var_type,nvdims,var_dim,natts,rcode]=mexcdf('varinq',cdfid,varid);
0075 attstring = fill_attnames(cdfid, varid, natts);
0076 %
0077 %
0078 % time stuff
0079 %
0080 % Check for time variable
0081 [ndims, nvars, ngatts, recdim, rcode] =  mexcdf('inquire', cdfid);
0082 if rcode < 0
0083    s = [ 'mexcdf: inquire: rcode = ' int2str(rcode) ];
0084    disp (s)
0085    return
0086 end
0087 varstring = fill_varnames(cdfid, nvars);
0088 pos = check_string('time', varstring, nvars);
0089 if pos > 0
0090   [timevid,rcode] = mexcdf('varid',cdfid,'time');
0091 else
0092    disp(['file ' cdf 'does not variable named time'])
0093    return
0094 end
0095 %
0096 % Check for time2 variable (for EPIC files)
0097 pos = check_string('time2', varstring, nvars);
0098 if pos > 0
0099    [time2vid,rcode] = mexcdf('varid',cdfid,'time2');
0100    epic=1;
0101 else
0102    epic=0;
0103 end
0104 %% Find length of time variable  (time must be 1 dimensional)
0105 [timevnam,ttype,ntdims,t_dim]=mexcdf('varinq',cdfid,timevid);
0106 [timednam,n,rcode]=mexcdf('diminq',cdfid,t_dim);
0107 if (epic),
0108 % time is julian day
0109   jd=mexcdf('varget',cdfid,timevid,0,n);
0110   ms=mexcdf('varget',cdfid,time2vid,0,n);
0111   jd=jd+ms/3600/1000/24; 
0112 else,
0113   base_date=mexcdf('attget',cdfid,'GLOBAL','base_date');
0114   jd0=julian(base_date(1),base_date(2),base_date(3));
0115 % time is "units" from base_date
0116   t1=mexcdf('varget',cdfid,timevid,0,n);
0117   [units]=mexcdf('attget',cdfid,timevid,'units');
0118   if(units(1:7)=='seconds'),
0119     jd1=t1/3600/24;
0120   elseif (units(1:12)=='milliseconds'),
0121     jd1=t1/3600/24/1000;
0122   else
0123     disp('invalid time units')
0124     return
0125   end
0126   jd=jd0+jd1;
0127 end
0128 %
0129 % Automagically get all the data if slab is not specified
0130   for n=1:nvdims,
0131     dimid=var_dim(n);
0132     [dim_name,dim_size,rcode]=mexcdf('diminq',cdfid,dimid);
0133     cvid(n)=mexcdf('varid',cdfid,dim_name);  % get coordinate variable ids
0134     corner(n)=0;
0135     count(n)=dim_size;
0136   end
0137 if(nargout>2),
0138 % get lat,lon and instrument depth
0139   idepth = mexcdf('varget1',cdfid,'depth',0);
0140   lat = mexcdf('varget1',cdfid,'lat',0);
0141   lon = mexcdf('varget1',cdfid,'lon',0);
0142   lonatt=mexcdf('attget',cdfid,'lon','epic_code');
0143   if(lonatt==500),
0144     lon=-lon
0145   end
0146 end
0147 if nargin==4,
0148   start_jd=julian(start)-(5.e-9);
0149   stop_jd=julian(stop)+(5.e-9);
0150   ind=find(jd>=start_jd & jd<=stop_jd);
0151   if(isempty(ind)),
0152     return
0153   end
0154   corner(1)=(ind(1)-1);
0155   count(1)=(max(ind)-min(ind))+1;
0156   jd=jd(ind);
0157 end
0158 %
0159 % Get slab
0160 %
0161 [values,rcode] = mexcdf('varget',cdfid,varid,corner,count);
0162 var=values(:);
0163 
0164 if(nargout>2),
0165 % get long_name, units, and water depth
0166 ln=mexcdf('attget',cdfid,varid,'long_name');
0167 units=mexcdf('attget',cdfid,varid,'units');
0168 wdepth=mexcdf('attget',cdfid,'global','water_depth');
0169 end
0170 pos = check_string('valid_range', attstring, natts);
0171 if pos > 0
0172   valid_range = mexcdf('attget',cdfid,varid,'valid_range');
0173   var=thumbfin(var,valid_range(1),valid_range(2));
0174 end
0175 mexcdf('close',cdfid);