matlab-netcdf.html

读取Network Common Data Form (netCDF)数据

<DT>
stride</DT>

<DD>
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).</DD>

<DT>
order</DT>

<DD>
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.</DD>

<DT>
change_miss</DT>

<DD>
== 1 causes missing values to be returned unchanged.</DD>

<BR>== 2 causes missing values to be changed to NaN.
<BR>== 3 causes missing values to be changed to new_miss (after rescaling
if that is necessary).
<BR>&lt; 0 produces the default (missing values to be changed to NaN).
<DT>
new_miss</DT>

<DD>
is the value given to missing data if change_miss = 3.</DD>

<DT>
squeeze_it</DT>

<DD>
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.</DD>

<dt>rescale_opts</dt>

<dd>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.</dd>
</DL>
OUTPUT:
<DL>
<DT>
values</DT>

<DD>
is a scalar, vector or array of values that is read in from the NetCDF
file</DD>
</DL>
NOTES:
<OL>
<LI>
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.</LI>

<BR>These are:
<BR>corner, end_point = [-1 ... -1], => all elements retrieved
<BR>stride = 1, => all elements retrieved
<BR>order = [1 2 3 .. n] for an n dimensional netCDF variable
<BR>change_miss = 2, => missing values replaced by NaNs
<BR>new_miss = 0;
<BR>squeeze_it = 1; => singleton dimensions will be removed
<LI>
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.</LI>

<LI>
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.</LI>


<P>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)
<LI>
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.)</LI>

<LI>
A strange 'feature' of matlab 5 (and later versions) is that it will not tolerate a singleton
dimension as the final dimension. 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.</LI>
</OL>
EXAMPLES:

<P>To be more explicit, suppose that we use inqnc to examine a netCDF file.
Then 2 lines in the output might read:

<P>The 3 dimensions are 1) month = 12 2) lat = 90 3) lon = 180.
<BR>--- Information about airtemp(month lat lon ) ---

<P>Likewise using 'ncdump -h' from the command line would have the corresponding
line:

<P>short airtemp(month, lat, lon);

<P>1) The simplest possible call to getnc will get all the elements of
the variable (note the order of the dimensions):

<P>>> airtemp = getnc('oberhuber', 'airtemp');
<BR>>> size(airtemp) = 12 90 180

<P>2) Get a subsample of the variable, note the stride:

<P>&nbsp;>> airtemp = getnc('oberhuber', 'airtemp', [-1 1 3], [-1 46 6],
[1 5 1]);
<BR>>> size(airtemp)
<BR>ans = 12 10 4

<P>3) Get all the elements of the variable, but with dimensions permuted:

<P>&nbsp;>> airtemp = getnc('oberhuber', 'airtemp', -1, -1, -1, [2 3 1]);
<BR>>> size(airtemp)
<BR>ans = 90 180 12

<P>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:
<BR>>> airtemp = getnc('oberhuber', 'airtemp', -1, -1, -1, -1, 3, 1000);

<P>>> size(airtemp)
<BR>ans = 12 90 180

<P>5) Get a subsample of the variable, a singleton dimension is squeezed:

<P>&nbsp;>> airtemp = getnc('oberhuber', 'airtemp', [-1 7 -1], [-1 7 -1]);
<BR>>> size(airtemp)
<BR>ans = 12 180

<P>6) Get a subsample of the variable, a singleton dimension is not squeezed:

<P>&nbsp;>> airtemp = getnc('oberhuber','airtemp',[-1 7 -1],[-1 7 -1],-1,-1,-1,-1,0);
<BR>>> size(airtemp)
<BR>ans = 12 1 180

<P>
<HR ALIGN=LEFT width = 100%><A NAME="further_documentation"></A>
<H4>
Further documentation</H4>
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 - attnc, getnc, inqnc, timenc and whatnc.

<P>
<HR ALIGN=LEFT width = 100%><A NAME="backwards_compatibility"></A>
<H4>
Backwards compatibility issues</H4>
Earlier versions of these m-files had names like getcdf, whatcdf, etc and
were used for matlab versions 3.5 and 4.2. If you have a lot of legacy
code that you don't wish to change then you should download and install
matlab-netcdf-4.2-5.0.tar.Z. This runs under matlab 5 and mimics the older
matlab/netCDF interface.

<P>
<HR ALIGN=LEFT width = 100%><A NAME="latest_changes"></A>
<H4>
Latest changes</H4>

<UL>
<LI>

<I>July 3 2000: </I>timenc was generalised so that it could handle
dates before the introduction of the Gregorian calendar on October 15,
1582; it now works back to the year -4712. The earlier version could
give incorrect dates for files which used the pre-Gregorian calendar in
either the time vector values or in its 'units' attribute.

<LI>
<I>April 22 1998: </I>timenc was generalised so that when requested it
will return only part of the time vector. It can also return the length
of the time vector as a separate variable.</LI>

<LI>
<I>December 12 1997:</I> attnc was generalised so that when the user does
not specify the name of the variable's attribute then all of the attributes
(and their names) will be returned in cells.</LI>
</UL>


<P>
<HR ALIGN=LEFT width = 100%><A NAME="disclaimer"></A>
<H4>
Disclaimer</H4>
This software is provided "as is" without warranty of any kind. It is covered
by a general CSIRO <A HREF="http://www.csiro.au/legalnotices/disclaimer.html">Legal
Notice and Disclaimer</A>.

<P>
<HR ALIGN=LEFT width = 100%><A NAME="development_people"></A>
<H4>
People involved in the development of the matlab/netCDF interface</H4>
Julie Allen: <A HREF="mailto:[e-mail]">[e-mail]</A>
<BR>Chuck Denham: <A HREF="mailto:[e-mail]">[e-mail]</A>
<BR>Jim Mansbridge: <img SRC="jmaddress1.gif">
<BR>Rich Signell: <A HREF="mailto:[e-mail]">[e-mail]</A>

<P>
<HR ALIGN=LEFT width = 100%><A NAME="contact"></A>
<H4>
Contact details</H4>


<P>This web page is maintained by Jim Mansbridge, CSIRO Division of Marine
Research

<P><B>Postal address:</B> GPO Box 1538, Hobart, Tasmania 7001, Australia&nbsp;<!--CHANGE NEXT LINE TO YOUR PHONE NUMBERS -->
<BR><B>Phone:</B> [phone]
<BR><B>Fax:</B> [phone]&nbsp;<!--CHANGE NEXT LINES TO YOUR EMAIL ADDRESS -->
<BR><img SRC="jmaddress1.gif">

<P>
<HR ALIGN=LEFT width = 100%><A NAME="links"></A>
<H4>
Matlab links</H4>

<table width=180 border=0 cellpadding=0 cellspacing=0><tr><td align=center>
<font size=-1><a href="http://www.links2go.com/topic/MATLAB">
<img alt="Key Resource" src=http://www.marine.csiro.au/~mansbrid/key.gif width=121 height=121 border=0><br>
<b><i>Links<sup><small>2</small></sup>Go</i> Key Resource</b><br>
MATLAB Topic</a></font></td></tr></table>

<P>
<HR ALIGN=LEFT width = 100%>This page is <A HREF="http://www.marine.csiro.au/sw/matlab-netcdf.html">http://www.marine.csiro.au/sw/matlab-netcdf.html</A>.
<BR>It was last revised $Date: 2003/04/29 03:08:02 $.&nbsp;<!--START OF FOOTER  PLEASE DON'T CHANGE-->
<BR><BR<FONT SIZE="2">
<HR>Further details on the research of the CSIRO Division of Marine Research
are available through the Division's Home Page.
<CENTER></CENTER>

<CENTER><IMG SRC="http://www.marine.csiro.au/dmrimages/home.gif" ALT="CSIRO Marine Home Page" ALIGN=BOTTOM
BORDER="1"></A>

<P>For more information contact [e-mail] or telephone
[phone]. Unless otherwise indicated all contents in these web documents
are copyright &copy; 1997 CSIRO. Use of this web site and information available
from it is subject to our <A HREF="http://www.csiro.au/legalnotices/legalnotices/disclaimer.html">Legal
Notice and Disclaimer</A></BLOCKQUOTE>

</BODY>
</HTML>