% Copyright J. V. Mansbridge, CSIRO, january 30 1992
%      Revision $Revision: 1.1 $
%      Author   $Author: mansbrid $
%      Date     $Date: 1997/09/24 02:08:10 $
%      Source   ftp.marine.csiro.au/software/mansbrid/matlab_netcdf_4x5.tar.Z
%               or ftp.marine.csiro.au/software/mansbrid/matlab_netcdf_4x5.p
% 
% DISCLAIMER
%   This software is provided "as is" without warranty of any kind.
% 
% DESCRIPTION
%   This software is a toolkit of MATLAB routines that enable some
% simple manipulation of netcdf files within matlab version 5.  The
% routines provide a simple (but limited) interface to Chuck Denham's
% (cdenham@nobska.er.usgs.gov) netcdf toolbox.  The main use for the
% routines is to read hyperslabs of data into matlab variables.  This
% package contains some routines which enable some backwards
% compatibility with earlier versions of the package.  If backwards
% compatibility is not an issue then you should obtain and install
% matlab-netcdf-5.0.tar.Z.
% 
% INSTALLATION
%   It is assumed that users have already installed one of Chuck
% Denham's (cdenham@nobska.er.usgs.gov) matlab/netcdf interfaces.  These
% can be found from the mexcdf homepage at
% 'http://crusty.er.usgs.gov/mexcdf.html'.  There are versions suitable
% for matlab 5, 4 and 3.5.
% 
% The installation of the m-files in this tarfile is easy.
% 
% 1) Simply untarring this file has put all of the required m-files in a
% single directory.
% 
% 2) Put the directory (called something like matlab-netcdf-4.2-5.0) into
% matlab's path - perhaps by using the 'path' command.  It is possible
% to store the m-files in the directory containing Chuck's files (this
% would usually be $TOOLBOX/local/netcdf).  The only trouble with this
% is that matlab will then see a conflict between the Contents.m file is
% this distribution and chuck's netcdf help file.
% 
% 3) Edit the m-file pos_cds.m; it returns the path to the common data
% set directory.  pos_cds.m is called by whatnc, inqnc and getnc and so
% any netcdf file in the common data set will be accessible to users
% without them needing to specify path names.
% 
% 4) On dos systems there may be a problem of name conflict between the
% files getcdf_b.m and getcdf_batch.m.  These files are actually
% identical and included for backwards compatability - you can simply
% delete getcdf_batch.m.
% 
% 5) You may edit the the function y_rescale.m although this is strongly
% advised against.  The function y_rescale determines whether getnc,
% getcdf and getcdf_batch apply the attributes scale_factor and
% add_offset to relevant variables and attributes.  The default is that
% any variable will be automatically rescaled; if a variable has
% attributes valid_range, valid_min, valid_max or _FillValue then these
% will be automatically rescaled also.  This behaviour can be changed by
% editing y_rescale.m but you should be very cautious in doing so.  In
% particular, if the variable is rescaled and its attributes not, or
% vice versa, then the options to replace 'invalid' data will not work
% in the way expected in the netcdf standard.
% 
% 6) The system should now be ready to go.
% 
% 	Summary of functions
% 
% ==========================================================================
% The following commands are available (use help for further
% information) and will be supported in the future.
% 
% ==========================================================================
% attnc         - imports attributes of a netCDF file
% getnc         - imports variables from a netCDF file
% inqnc         - interactive inquiry of netCDF file
% netcdf toolbox- direct calls to netcdf functions - use 'help netcdf'
%                   for a detailed description 
% timenc        - finds the time vector and the corresponding base date for a
%                   netcdf file that meets COARDS standards
% whatnc        - lists netCDF files in current directory
% ==========================================================================
% 
% Three of the above routines (getnc, netcdf toolbox and timenc)
% will only work under matlab 5.  All of the above routines supercede
% the following (less powerful) routines which work under matlab 3.5, 4
% and 5.  The older  routines are only included for backwards compatibility:
% ==========================================================================
% attcdf        - imports attributes of a netCDF file
% getcdf        - imports variables from a netCDF file
% get_time      - finds the time vector and the corresponding base date for a
%                    netcdf file that meets COARDS standards.
% inqcdf        - interactive inquiry of netCDF file
% mexcdf        - direct calls to netcdf functions - (matlab 4 experts only)
% whatcdf       - lists netCDF files in current directory
% ==========================================================================
% 
% 	Documentation
% 
% There used to be a user manual in latex and postscript form.  I have
% not yet updated the manual and so have not put it in this distribution.
% 
% In fact it should not be necessary for an experienced matlab and netcdf
% user to read the manual at all.  Simply do a help on the 5 m-files
% that would be commonly used - attcdf, getnc, inqcdf, timecdf and
% whatnc.
% 
% 	Backwards compatibility issues
% 
% This latest version should be completely compatible with the previous
% matlab 4 version.
% 
% However some people will have used an even earlier version of this
% package under matlab 3.5 (possibly with a fortran derived mex-file
% named xnetcdf.mex4).  It is probably time to make slight changes to
% your code rather keep an old version of the mex files for
% compatibility.  Some compatibility issues are:
%
% Various improvements have resulted in some changes to inqcdf,
% getcdf and getcdf_batch.  We can study the changes by comparing the
% different versions of getcdf_batch.  Listed  below are the general calling
% sequence and an example for each of the 3 versions of getcdf_batch.  Later
% versions enable the interactive script (getcdf and then getnc) to be
% called non-interactively. 
% 
% * Version 1: used under matlab3.5:
% 
% values = getcdf_batch(file, varid, corner, end_point,
%                      order, rescale, change_miss, new_miss)
% 
% us = getcdf_batch('uvd', 1, [1 1 1], [720 1 151], 2, 0, 3, 1000);
% 
%   
% * Version 2: used under matlab4.1:
% 
% values = getcdf_batch(file, varid, corner, end_point,
%                      order, change_miss, new_miss)
%  
% us = getcdf_batch('uvd', 1, [1 1 1], [720 1 151], 2, 3, 1000);
% 
% 
% * Version 3: used under matlab4.1:
% 
% values = getcdf_batch(file, varid, corner, end_point,
%                      stride, order, change_miss, new_miss)
%  
% us = getcdf_batch('uvd', 1, [1 1 1], [720 1 151], [2 1 3], 2, 3, 1000);
% 
% 
% * Version 4: used under matlab4.1:
% 
% values = getcdf(file, varid, corner, end_point,
%                      stride, order, change_miss, new_miss)
%  
% us = getcdf('uvd', 1, [1 1 1], [720 1 151], [2 1 3], 2, 3, 1000);
% 
% 
% * Version 5: used under matlab5.0:
% 
% values = getcnc(file, varid, corner, end_point,
%                      stride, order, change_miss, new_miss, squeeze_it)
%  
% us = getnc('uvd', 1, [1 1 1], [720 1 151], [2 1 3], 1, 3, 1000, 1);
% 
% 
% In going from version 1 to version 2 the "rescale" argument was
% dropped (improvement 4) because everyone always wanted their data to
% be rescaled.  This meant that the number of arguments passed to
% getcdf_batch dropped from 8 to 7.  The number of arguments was
% increased back to 8 when the stride vector was added to version 4
% (improvement 7).
% 
% When the latest version of getcdf_batch is run it counts the number of
% input arguments; if there are only 7 then it assumes that the "stride"
% vector has been omitted and a stride of 1 is required in each
% direction.  Thus, code written assuming version 2 can be run without
% change.  However, it is strongly recommended that all new code should
% have the full 8 arguments.
% 
% Code written to run under the old version (which uses matlab3.5) will
% fail since the "order" variable will be mistaken for the "stride"
% vector and the "rescale" variable will be mistaken for the "order"
% variable.  getcdf_batch will detect this error when it checks that
% corner, end_point and stride are vectors of the same length except in
% the case where the the chosen variable is one dimensional.  In that
% case you will not get the answer that you expect.
% 
% 	KNOWN BUGS:
% 
% None.
% 
%          Jim Mansbridge (mansbrid@ml.csiro.au)

help Readme_4x5
