read_NCEP_wind

 Reads in two NCEP wind vector files (U and V) and outputs four arrays of
 longitude, latitude, u10 and v10 velocity components.
 
 function read_NCEP_wind()
 
 DESCRIPTION:
   Read a pair of NCEP NetCDF files (U10 and V10 vectors) and output to
   four arrays of longitude, latitude, u10 and v10.
 
 INPUT:
   NCEP NetCDF U10 filename (and path)
   NCEP NetCDF V10 filename (and path)
 
 OUTPUT:
   ncep - struct with the time, latitude, longitude, u10 and v10 arrays in
   it. Time is in Modified Julian Days.
 
 Author(s)
   Pierre Cazenave (Plymouth Marine Laboratory)
 
 Revision history:
   2012-10-16 First version based on parts of ncep2fvcom_U10V10.m in the
   fvcom-toolbox.
 
==========================================================================

0001 function ncep = read_NCEP_wind(ncep_u10_file, ncep_v10_file)
0002 % Reads in two NCEP wind vector files (U and V) and outputs four arrays of
0003 % longitude, latitude, u10 and v10 velocity components.
0004 %
0005 % function read_NCEP_wind()
0006 %
0007 % DESCRIPTION:
0008 %   Read a pair of NCEP NetCDF files (U10 and V10 vectors) and output to
0009 %   four arrays of longitude, latitude, u10 and v10.
0010 %
0011 % INPUT:
0012 %   NCEP NetCDF U10 filename (and path)
0013 %   NCEP NetCDF V10 filename (and path)
0014 %
0015 % OUTPUT:
0016 %   ncep - struct with the time, latitude, longitude, u10 and v10 arrays in
0017 %   it. Time is in Modified Julian Days.
0018 %
0019 % Author(s)
0020 %   Pierre Cazenave (Plymouth Marine Laboratory)
0021 %
0022 % Revision history:
0023 %   2012-10-16 First version based on parts of ncep2fvcom_U10V10.m in the
0024 %   fvcom-toolbox.
0025 %
0026 %==========================================================================
0027 
0028 %warning off
0029 
0030 if nargin ~= 2
0031     error('Incorrect number of arguments')
0032 end
0033 
0034 subname = 'read_NCEP_wind';
0035 
0036 global ftbverbose;
0037 if(ftbverbose);
0038   fprintf('\n')
0039   fprintf(['begin : ' subname '\n'])
0040 end;
0041 
0042 if exist(ncep_u10_file, 'file') ~= 2
0043    error(['file: ' ncep_u10_file ' does not exist']);
0044 end
0045 if exist(ncep_v10_file, 'file') ~= 2
0046     error(['file: ' ncep_v10_file ' does not exist']);
0047 end
0048 
0049 %--------------------------------------------------------------------------
0050 % Open NCEP data and check for time range
0051 %--------------------------------------------------------------------------
0052 
0053 % Get the year from the NCEP file name
0054 ncep_u10_year = get_NCEP_year(ncep_u10_file);
0055 ncep_v10_year = get_NCEP_year(ncep_v10_file);
0056 % Check both files are from the same year
0057 if (ncep_u10_year - ncep_v10_year) ~= 0
0058     error('Input U and V wind data files are from different years')
0059 end
0060 
0061 % Get the time. It's stored relative to the 1st January for the given year.
0062 % We're assuming that since both files are for the same year, we don't have
0063 % to pull the 'time' variable out from both (they should be identical).
0064 nc_u10 = netcdf.open(ncep_u10_file, 'NOWRITE');
0065 nc_v10 = netcdf.open(ncep_v10_file, 'NOWRITE');
0066 time_varid = netcdf.inqVarID(nc_u10, 'time');
0067 nceptimehours = netcdf.getVar(nc_u10, time_varid);
0068 
0069 % NCEP dates are relative to 0001/01/01 00:00:00 and stored in hours.
0070 % MATLAB's dates are relative to 0000/00/00 00:00:00 and stored in days.
0071 % Need to add a year and a day to the NCEP time when converting.
0072 nceptimedays = datevec((nceptimehours/24) + datenum(1, 0, -1));
0073 ncep.time = greg2mjulian(nceptimedays(:,1), nceptimedays(:,2),...
0074     nceptimedays(:,3), nceptimedays(:,4), nceptimedays(:,5),...
0075     nceptimedays(:,6));
0076 
0077 if(ftbverbose);
0078     fprintf('beg time of NCEP data %04i/%02i/%02i %02i:%02i:%02i\n',nceptimedays(1,:));
0079     fprintf('end time of NCEP data %04i/%02i/%02i %02i:%02i:%02i\n',nceptimedays(end,:));
0080 end
0081 
0082 % Get the geographical information from the NCEP data. Again, use the U10
0083 % file only (we're assuming they're both global).
0084 lat_varid = netcdf.inqVarID(nc_u10, 'lat');
0085 lon_varid = netcdf.inqVarID(nc_u10, 'lon');
0086 nceplatvector = netcdf.getVar(nc_u10, lat_varid);
0087 nceplonvector = netcdf.getVar(nc_u10, lon_varid);
0088 
0089 [ncep.lon, ncep.lat] = meshgrid(nceplonvector, nceplatvector);
0090 
0091 % Find the necessary variables
0092 u10_varid_NCEP = netcdf.inqVarID(nc_u10, 'uwnd');
0093 v10_varid_NCEP = netcdf.inqVarID(nc_v10, 'vwnd');
0094 
0095 % Get the U10 and V10 data
0096 U10 = netcdf.getVar(nc_u10, u10_varid_NCEP, 'single');
0097 V10 = netcdf.getVar(nc_v10, v10_varid_NCEP, 'single');
0098 
0099 % The NCEP data are packed as integers. The following equation describes
0100 % how to unpack them:
0101 %     unpacked value = add_offset + ( (packed value) * scale_factor )
0102 % (from http://www.esrl.noaa.gov/psd/data/gridded/faq.html#2).
0103 % Keep them as singles for now to avoid horrible rounding errors.
0104 scale_factor = netcdf.getAtt(nc_u10,u10_varid_NCEP,'scale_factor','single');
0105 add_offset = netcdf.getAtt(nc_u10,u10_varid_NCEP,'add_offset','single');
0106 
0107 % Unpack the values. U10 and V10 must be doubles for griddata to work. Fix
0108 % the order of the dimensions to match the coordinates in nceplon and
0109 % nceplat.
0110 ncep.uwnd = permute(double(add_offset + (U10.*scale_factor)), [2,1,3]);
0111 ncep.vwnd = permute(double(add_offset + (V10.*scale_factor)), [2,1,3]);
0112 
0113 netcdf.close(nc_u10)
0114 netcdf.close(nc_v10)