function values = getnc(file, varid, corner, end_point, stride, order, ...      change_miss, new_miss, squeeze_it, rescale_opts)%  GETNC retrieves data from a NetCDF file.%%  function values = getnc(file, varid, corner, end_point, stride, order, ...%        change_miss, new_miss, squeeze_it, rescale_opts)%% DESCRIPTION:%  getnc retrieves data from a NetCDF file.  The way getnc behaves%  depends on how many of the input arguments are passed to it.  If no%  arguments are passed then it returns this help message.  If one%  argument is passed then the user is asked questions to determine%  information necessary for the data retrieval.  If more than one%  argument is passed then getnc returns the data without needing to%  ask any questions.  The input arguments are listed below.%  % INPUT:%  file is the name of a netCDF file with or without the .cdf or .nc extent.%  varid may be an integer or a string.  If it is an integer then it%    must be the menu number of the n dimensional variable as used%    by a call to inqnc or getnc.  If it is a string then it should%    be the name of the variable.%  corner is a vector of length n specifying the hyperslab corner%    with the lowest index values (the bottom left-hand corner in a%    2-space).  The corners refer to the dimensions in the same%    order that these dimensions are listed in the relevant questions%    in getnc.m and in the inqnc.m description of the variable.  A%    negative element means that all values in that direction will be%    returned.  If a negative scalar is used this means that all of the%    elements in the array will be returned.%  end_point is a vector of length n specifying the hyperslab corner%    with the highest index values (the top right-hand corner in a%    2-space).  The corners refer to the dimensions in the same order%    that these dimensions are listed in the relevant questions in%    getnc.m and in the inqnc.m description of the variable.  An%    element in the end_point vector wil be ignored if the corresponding%    element in the corner vector is negative.%  stride is a vector of length n specifying the interval between%    accessed values of the hyperslab (sub-sampling) in each of the n%    dimensions.  A value of 1 accesses adjacent values in the given%    dimension; a value of 2 accesses every other value; and so on. If%    no sub-sampling is required in any direction then it is allowable%    to just pass the scalar 1 (or -1 to be consistent with the corner%    and end_point notation).%  order is a vector of length n specifying the order of the dimensions in%    the returned array.  order = -1 or [1 2 3 .. n] for an n dimensional%    netCDF variable will return an array with the dimensions in the same%    order  as described by a call to inqnc(file) from within matlab or%    'ncdump  -h' from the command line.  Putting order = -2 will reverse%    this order.  More general permutations are given re-arranging the%    numbers 1 to n in the vector.%  change_miss == 1 causes missing values to be returned unchanged.%    change_miss == 2 causes missing values to be changed to NaN.%    change_miss == 3 causes missing values to be changed to new_miss%    (after rescaling if that is necessary).%    change_miss < 0 produces the default (missing values to be changed to%    NaN).%  new_miss is the value given to missing data if change_miss = 3.%  squeeze_it specifies whether the returned array should be squeezed.%    That is, when squeeze_it is non-zero then the squeeze function will%    be applied to the returned array to eliminate singleton array%    dimensions.  This is the default.  Note also that a 1-d array is%    returned as a column vector.%  rescale_opts is a 2 element vector specifying whether or not rescaling is%    carried out on retrieved variables or attributes. Only use this option%    if you are sure that you know what you are doing.%    If rescale_opts(1) == 1 then a variable read in by getnc.m will be%    rescaled by 'scale_factor' and  'add_offset' if these are attributes of%    the variable; this is the default. If rescale_opts(1) == 0 then this%    rescaling will not be done.%    If rescale_opts(2) == 1 then the attributes '_FillValue', 'valid_range',%    'valid_min' and 'valid_max' read in by getnc.m (and used to find the%    missing values of the relevant variable) will be rescaled by%    'scale_factor' and 'add_offset'; this is the default. If rescale_opts(2)%    == 0 then this rescaling will not be done.%%% OUTPUT:%  values is a scalar, vector or array of values that is read in%     from the NetCDF file%% NOTES:% 1) In order for getnc to work non-interactively it is only strictly% necessary to pass the first 2 input arguments to getnc - sensible% defaults are available for the rest.% These are:% corner, end_point = [-1 ... -1], => all elements retrieved% stride = 1, => all elements retrieved% order = [1 2 3 .. n] for an n dimensional netCDF variable% change_miss = 2, => missing values replaced by NaNs% new_miss = 0;% squeeze_it = 1; => singleton dimensions will be removed% 2) It is not acceptable to pass only 3 input arguments since there is% no default in the case of the corner points being specified but the% end points not.% 3) By default the order of the dimensions of a returned array will be the% same as they appear in the relevant call to 'inqnc' (from matlab) or% 'ncdump -h' (from the command line).  (This is the opposite to what% happened in an earlier version of getnc.)  This actually involves getnc% re-arranging the returned array because the netCDF utilities follow the C% convention for data storage and matlab follows the fortran convention.%    To be more explicit, suppose that we use inqnc to examine a netCDF file.% Then 2 lines in the output might read:%% The 3 dimensions are  1) month = 12  2) lat = 90  3) lon = 180.%     ---  Information about airtemp(month lat lon )  ---%% Likewise using 'ncdump -h' from the command line would have the% corresponding line:%%        short airtemp(month, lat, lon);%% The simplest possible call to getnc will give, as you would expect,%% >> airtemp = getnc('oberhuber', 'airtemp');% >> size(airtemp) = 12    90   180%% Since the netCDF file follows the C convention this means that in the% actual storage of the data lon is the fastest changing index, followed by% lat, and then month.  However matlab (and fortran) use the opposite% convention and so month is the fastest changing index, followed by lat, and% then lon.  getnc actually used the permute function to reverse the storage% order.  If efficiency is a concern (because of using very large arrays or% a large number of small arrays) then passing order == -2 to getnc will% produce the fastest response by returning the data in its 'natural' order% (a 180x90x12 array in our example)%% 4) If the values are returned in a one-dimensional array then this will be a% column vector.  This choice provides consistency if there is an% unlimited dimension.  That is, if the length of the unlimited% dimension is n then an m x n array will be returned even for n = 1.)%% 5) A strange 'feature' of matlab 5 is that it will not tolerate a singleton% dimension as the final dimension of a multidimensional array.  Thus, if% you chose to have only one element in the final dimension this dimension% will be 'squeezed' whether you want it to be or not - this seems to be% unavoidable.%% EXAMPLES:% 1) Get all the elements of the variable, note the order of the dimensions:% >> airtemp = getnc('oberhuber', 'airtemp');% >> size(airtemp)% ans =%     12    90   180%% 2) Get a subsample of the variable, note the stride:% >> airtemp = getnc('oberhuber', 'airtemp', [-1 1 3], [-1 46 6], [1 5 1]);% >> size(airtemp)% ans =%     12    10     4%% 3) Get all the elements of the variable, but with dimensions permuted:% >> airtemp = getnc('oberhuber', 'airtemp', -1, -1, -1, [2 3 1]);% >> size(airtemp)% ans =%     90   180    12% % 4) Get all the elements of the variable, but with missing values%    replaced with 1000.  Note that the corner, end_point, stride and%    order vectors have been replaced by -1 to indicate that the whole%    range is required in the default order:% >> airtemp = getnc('oberhuber', 'airtemp', -1, -1, -1, -1, 3, 1000); % >> size(airtemp)% ans =%     12    90   180%% 5) Get a subsample of the variable, a singleton dimension is squeezed:% >> airtemp = getnc('oberhuber', 'airtemp', [-1 7 -1], [-1 7 -1]);   % >> size(airtemp)                                                         % ans =%     12   180% % 6) Get a subsample of the variable, a singleton dimension is not squeezed:% >> airtemp = getnc('oberhuber','airtemp',[-1 7 -1],[-1 7 -1],-1,-1,-1,-1,0);% >> size(airtemp)                                                            % ans =%     12     1   180%%% CALLER:   general purpose% CALLEE:   fill_att.m, check_st.m, y_rescal.m, ncmex.mex%% AUTHOR:   J. V. Mansbridge, CSIRO%---------------------------------------------------------------------%     Copyright (C), J.V. Mansbridge, 1992%     Commonwealth Scientific and Industrial Research Organisation%     Revision $Revision: 1.12 $%     Author   $Author: man133 $%     Date     $Date: 2004/11/16 04:50:30 $%     RCSfile  $RCSfile: getnc.m,v $% %--------------------------------------------------------------------% In November 1998 some code was added to deal better with byte type data. Note% that any values greater than 127 will have 256 subtracted from them. This is% because on some machines (an SGI running irix6.2 is an example) values are% returned in the range 0 to 255. Note that in the fix the values less than 128% are unaltered and so we do not have to know whether the particular problem has% occurred or not; for machines where there is no problem no values will be% altered. This is applied to byte type attributes (like _FillValue) as well as% the variable values.% Check the number of arguments.  If there are no arguments then return% the help message.  If there is more than one argument then call% getnc_s which reads the netcdf file in a non-interactive way.% If there is only one argument then drop through and find the values% interactively.if nargin == 0  help getnc  returnelseif nargin == 2  values = getnc_s(file, varid);  returnelseif nargin == 3  values = getnc_s(file, varid, corner);  returnelseif nargin == 4  values = getnc_s(file, varid, corner, end_point);  returnelseif nargin == 5  values = getnc_s(file, varid, corner, end_point, stride);    returnelseif nargin == 6  values = getnc_s(file, varid, corner, end_point, ...      stride, order);  returnelseif nargin == 7  values = getnc_s(file, varid, corner, end_point, ...      stride, order, change_miss);  returnelseif nargin == 8  values = getnc_s(file, varid, corner, end_point, ...      stride, order, change_miss, new_miss);  returnelseif nargin == 9  values = getnc_s(file, varid, corner, end_point, ...      stride, order, change_miss, new_miss, squeeze_it);  returnelseif nargin == 10  values = getnc_s(file, varid, corner, end_point, ...      stride, order, change_miss, new_miss, squeeze_it, rescale_opts);  returnelseif nargin > 10  disp('ERROR: getnc: Too many input arguments')  disp(' ')  help getnc  returnend% I make ncmex calls to find the integers that specify the attribute% typesnc_byte = ncmex('parameter', 'nc_byte'); %1nc_char = ncmex('parameter', 'nc_char'); %2nc_short = ncmex('parameter', 'nc_short'); %3nc_long = ncmex('parameter', 'nc_long'); %4nc_float = ncmex('parameter', 'nc_float'); %5nc_double = ncmex('parameter', 'nc_double'); %6% Find out whether values should be automatically rescaled or not.[rescale_var, rescale_att] = y_rescal;% Set the value of imap.  Note that this is used simply as a% placeholder in calls to vargetg - its value is never used.imap = 0;% Set some constants.blank = abs(' ');% Check that the file is accessible.  If it is then its full name will% be stored in the variable cdf.  The file may have the extent .cdf or% .nc and be in the current directory or the common data set (whose% path can be found by a call to pos_cds.m.  If a compressed form% of the file is in the current directory then the user is prompted to% uncompress it.  If, after all this, the netcdf file is not accessible% then the m file is exited with an error message.cdf_list = { '' '.nc' '.cdf'};ilim = length(cdf_list);for i = 1:ilim   cdf = [ file cdf_list{i} ];  err = check_nc(cdf);  if  (err == 0) | (err == 4)    break;  elseif err == 1    if i == ilim      error([ file ' could not be found' ])    end  elseif err == 2    path_name = pos_cds;    cdf = [ path_name cdf ];    break;  elseif err == 3    err1 = uncmp_nc(cdf);    if err1 == 0      break;    elseif err1 == 1      error([ 'exiting because you chose not to uncompress ' cdf ])    elseif err1 == 2      error([ 'exiting because ' cdf ' could not be uncompressed' ])    end  endend% Open the netcdf file.[cdfid, rcode] = ncmex('OPEN', cdf, 'NC_NOWRITE');if rcode == -1  error(['** ERROR ** ncopen: rcode = ' num2str(rcode)])end% Suppress all error messages from netCDF [rcode] = ncmex('setopts', 0);% Collect information about the cdf file.[ndims_tot, nvars, ngatts, recdim, rcode] =  ncmex('ncinquire', cdfid);if rcode == -1  error(['** ERROR ** ncinquire: rcode = ' num2str(rcode)])endvarstring = fill_var(cdfid, nvars);% Prompt the user for the name of the variable containing the hyperslab.k = -1;while k <1 | k > nvars   disp(' ')   s = [ '----- Choose the variable -----'];   disp(s)   disp(' ')   for i = 0:3:nvars-1      stri = int2str(i+1);      if length(stri) == 1         stri = [ ' ' stri];      end      [varnam, vartyp, nvdims, vdims, nvatts, rcode] = ...	  ncmex('ncvarinq', cdfid, i);      if rcode == -1	error(['** ERROR ** ncvarinq: rcode = ' num2str(rcode)])      end      s = [ '  ' stri ') ' varnam ];      addit = 26 - length(s);      for j =1:addit         s = [ s ' '];      end      if i < nvars - 1         stri = int2str(i+2);         if length(stri) == 1            stri = [ ' ' stri];         end         [varnam, vartyp, nvdims, vdims, nvatts, rcode] = ...	     ncmex('ncvarinq', cdfid, i+1);	 if rcode == -1	   error(['** ERROR ** ncvarinq: rcode = ' num2str(rcode)])