matlab-netcdf.html

matlacb程序包

	<LI><P><B>Installation</B>: Look at the web page you will need
	suitable copies of the mex and binary files from the <A HREF="http://www.opendap.org/download/ml-cmdln.html">Matlab
	Command Line Tool</A> package. There are two versions of this
	package and the CSIRO/netCDF interface will automatically detect
	whether you have installed the latest or earlier version. For the
	newest version the interface calls a mex file named <I>loaddap</I>
	which in turn calls a binary executable named <I>writedap </I>under
	linux or <I>writedap.exe </I>under Windows. In the older version
	these files are named <I>loaddods</I> and <I>writeval</I> but do
	essentially the same thing. There are other differences between the
	linux and Windows versions and these are described below.</P>
</UL>
<P STYLE="margin-left: 0.79in"><B>Unix users</B></P>
<P STYLE="margin-left: 0.79in">Simply put the appropriate loaddap
mexfile (e.g., <I>loaddap.mexglx</I>) in a directory seen from your
matlab path. The binary file <I>writedap</I> should also be put in
the same directory. (The earlier versions are called <I>loaddods.mex*</I>
and <I>writeval</I>.)</P>
<P STYLE="margin-left: 0.79in"><B>Windows users</B></P>
<P STYLE="margin-left: 0.79in">For Windows things are more
complicated. From <A HREF="http://www.opendap.org/download/ml-cmdln.html">Matlab
Command Line Tool</A> you will need both the Matlab Structs Tool
package (with a name like ml-structs3.5.2-win32.zip) and the libdap
library (with a name like libdap-prerequisites3.7.3.zip). To make
things work we took loaddap.dll and writedap.exe from the first
package and put them into a folder in the matlab search path. We then
copied the dll files from the libdap prerequisite file to the same
folder as the dll's. Earlier versions ofthe Matlab Structs Tool
package had things arranged differently and you needed loaddods.dll
and writeval.exe. Note that there may be a <A HREF="#bug1">bug in the
OPeNDAP interface.</A></P>
<HR>
<H1><A NAME="Portability"></A>Portability and known problems</H1>
<P STYLE="margin-top: 0.17in; page-break-after: avoid"><FONT FACE="Albany, sans-serif"><FONT SIZE=4>Portability</FONT></FONT></P>
<P>The software in this package is entirely made up of matlab script
files and works for all versions of matlab later than and including
matlab 6.1 (R12). Portability problems can arise with the binary
files mexnc, loaddap and writedap which must be downloaded from
elsewhere.</P>
<P STYLE="margin-top: 0.17in; page-break-after: avoid"><FONT FACE="Albany, sans-serif"><FONT SIZE=4>Bugs</FONT></FONT></P>
<P>There are no known bugs.</P>
<P><A NAME="bug1"></A>(Before version 3.22 there was be a problem on
Windows PCs and some linux boxes when using OPeNDAP . The package
could give the wrong result when reading variables which are
character arrays. The problem is with the loaddap (loaddods) mex file
and will presumably be fixed sometime in the future. At present there
is a workaround in the timenc and getnc_s functions.)</P>
<P STYLE="margin-top: 0.17in; page-break-after: avoid"><FONT FACE="Albany, sans-serif"><FONT SIZE=4>Confusion
with missing values</FONT></FONT></P>
<P>When reading some netCDF files getnc will return a missing value
indicator (by default a NaN) in some places where there shouldn't be
one. This is not due to a bug in getnc but occurs when the netCDF
file is not following the attribute conventions (see
<A HREF="http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Attribute-Conventions">http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Attribute-Conventions</A>).
Two relevant quotes from the documentation are:</P>
<PRE STYLE="margin-bottom: 0.2in">The type of each valid_range, valid_min and valid_max attribute should match the type of its variable
(except that for byte data, these can be of a signed integral type to specify the intended range).</PRE><P>
and</P>
<PRE STYLE="margin-bottom: 0.2in">If _FillValue is defined then it should be scalar and of the same type as the variable.</PRE><P>
To illustrate what this means and how a problem can occur consider
the following extract from an example cdl file.</P>
<PRE>short airtemp(time, lat, lon) ;
 airtemp:long_name = &quot;Air temperature at surface&quot; ;
 airtemp:valid_range = -10000s, 10000s ;
 airtemp:units = &quot;degC&quot; ;
 airtemp:scale_factor = 0.01f ;
 airtemp:_FillValue = 32766s ;</PRE><P>
What has happened here is that the creator of the netCDF file has
chosen to save space by storing the data as shorts (2 byte integers).
The software reading the data will then multiply the add_offset of
0.01 by the integer values to produce the floating point value of the
air temperature. Since the integers can take values between -32768
and 32767 then this can represent temperatures of between -327.68 and
327.67 degrees with a resolution of 0.01 degrees.</P>
<P>Note, however, that the valid_range goes from -10000 to 10000.
Generic software interprets values outside of this range as faulty in
some way and the default behaviour of getnc is to replace such values
with a NaN. The creator of the file can use this to mark missing or
contaminated data. Since the temperatures implied by these limits are
-100 and 100 Celsius then the limits are &ldquo;safe&rdquo; since
they represent physically unreasonable data.</P>
<P>This way of defining the valid_range is what is specified in the
earlier quote.</P>
<P>A problem arises when the creator of the netCDF file
misunderstands the attribute convention. They choose an &ldquo;intuitive&rdquo;
definition of the attribute like:</P>
<PRE STYLE="margin-bottom: 0.2in">airtemp:valid_range = -100.0f, 100.0f ;</PRE><P>
Here they are thinking in terms of the true air temperature rather
than the scaled version stored as integers. When getnc reads the
valid_range attribute it then multiplies it by 0.01 and concludes
that any temperatures outside the range of -1.0 to 1.0 are to be
replaced by NaNs. Note that the same problem&nbsp;occurs when the
file's creator makes the same error with other attributes &ndash;
valid_min, valid_max, _<SPAN STYLE="text-decoration: none">FillValue
and missing_value.</SPAN></P>
<P>There are several workarounds for this problem. The simplest is to
pass getnc the argument <I>change_miss</I> = 1. This will cause all
values to be passed unchanged (apart from the rescaling implied by
the scale_factor attribute). The disadvantage is that when very large
values were used to indicate faulty data these will also be returned
- in the example above you might end up with some temperatures
greater than 100C.</P>
<P>The trickier, but more satisfactory option, it to use the
<I>rescale_opts </I>option in getnc. It was designed to deal with
errant netCDF files and is described <A HREF="#rescale_opts">here</A>.</P>
<HR>
<H1><A NAME="Revision"></A>Revision history</H1>
<P>The following is a partial history of revisions. I intend to keep
it more up-to-date from version 3.0 onwards. In particular, bug fixes
will be recorded.</P>
<UL>
	<LI><P><A NAME="toolsUI2"></A><I><B>Version 4.03 : </B>October 17
	2007:</I> Made the way err_opt is handled consistent with the
	documentation. Changed the default setup for reading OpeNDAP files
	to work around a matlab bug with javaaddpath (see ).</P>
	<LI><P><A NAME="toolsUI21"></A><I><B>Version 4.02 : </B>September 7
	2007:</I> Things now behave more gracefully if you run matlab with
	the -nojvm option but have things set to use toolsUi.jar to read
	OpeNDAP files.</P>
	<LI><P><I><B>Version 4.01 : </B>September 3 2007:</I> A minor bug in
	the getnc bounds checking was corrected.</P>
	<LI><P><I><B>Version 4.0 : </B>August 20 2007:</I> Can now use the
	toolsUI.jar package to read both netCDF and OpeNDAP files. inqnc and
	the interactive version of getnc had major re-writes.</P>
	<LI><P><I><B>Version 3.33 : </B>January 12 2007:</I> Handles the
	latest version of the Matlab Struct Tools under Windows
	(loaddap.dll, etc).</P>
	<LI><P><I><B>Version 3.32 : </B>December 4 2006:</I> get_dods_dds
	can now deal with spaces in directory names under windows.</P>
</UL>
<UL>
	<LI><P><B><I>Version 3.31</I></B> : November 29 <I>2006</I>: timenc
	can handle more calendar types.</P>
	<LI><P><B><I>Version 3.30</I></B> : June 30 <I>2006</I>: getnc error
	handling and input method made more versatile.</P>
	<LI><P STYLE="margin-bottom: 0in"><B><I>Version 3.22</I></B> : April
	<I>24 2006</I>: Minor changes to timenc and getnc_s to work around a
	bug in loaddods (and maybe loaddap) which cause errors when
	retrieving an array of characters. 
	</P>
	<LI><P><B><I>Version 3.21</I></B> : <I>January 27 2006</I>: Minor
	changes were made to enable it the work properly on matlab 6.1
	(R12).</P>
	<LI><P><B><I>Version 3.2</I></B> : <I>December 19 2</I>005: The new
	function ddsnc was added to the interface.</P>
	<LI><P><B><I>Version 3.1</I></B> : <I>December 6 2</I>005: Handles
	OPeNDAP files other than those that are native netCDF files; works
	(mostly) on windows boxes.</P>
	<LI><P><B><I>Version 3.01</I></B> : <I>October 27</I> 2005: Bug fix;
	it caused attnc to fall over when 3 input arguments were passed for
	an OPeNDAP file.</P>
</UL>
<UL>
	<LI><P><I><B>Version 3.0</B> : October 24</I> 2005: Able to access
	OPeNDAP data sets as well as netCDF ones. Calls mexnc. Minor bug fix
	in fill_var.m.</P>
	<LI><P><I><B>Version 2.4</B> : 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. 
	</P>
	<LI><P STYLE="margin-bottom: 0in"><I><B>Version 2.3 </B>: 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. 
	</P>
	<LI><P><I><B>Version 2.2</B> : 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. 
	</P>
	<LI><P><I><B>Version 2.1</B> : September 24 1997: </I>Explanatory
	web page first made public.</P>
	<LI><P STYLE="font-style: normal"><I><B>Version 2.0</B> : April 28
	1997: </I>Functions renamed to getnc, timenc, etc.</P>
	<LI><P STYLE="font-style: normal"><I><B>Version 1.0</B>: June 1
	1993: </I>Initial release.</P>
</UL>
<HR>
<H1><A NAME="Alternative"></A>Alternative ways of accessing netCDF
and OPeNDAP data</H1>
<P>There are a number of alternative ways of reading netCDF and
OPeNDAP data into matlab. In most cases the time and computer
resources taken to retrieve data will depend mostly on external
factors such as internet bandwidth and disk access speed. Hence it
would be surprising if one of these methods was significantly more
efficient than any of the others.</P>
<P STYLE="margin-top: 0.17in; page-break-after: avoid"><FONT FACE="Albany, sans-serif"><FONT SIZE=4>netCDF</FONT></FONT></P>
<UL>
	<LI><P><A HREF="http://mexcdf.sourceforge.net/snctools_overview.html">snctools</A>
	is a set of matlab functions that lets you read and write netCDF
	files. It uses mexnc for basic access to netCDF libraries.</P>
</UL>
<UL>
	<LI><P><A HREF="http://mexcdf.sourceforge.net/netcdf_toolbox.html">netCDF
	toolbox</A> is an object-oriented way to read and write netCDF files
	and is neat to use once you figure out what is going on. It is being
	maintained but no longer developed.</P>
</UL>
<P STYLE="margin-top: 0.17in; page-break-after: avoid"><FONT FACE="Albany, sans-serif"><FONT SIZE=4>OPeNDAP</FONT></FONT></P>
<UL>
	<LI><P><A HREF="http://www.opendap.org/download/ml-cmdln.html">Matlab
	Command Line Tool </A>is a low-level interface to OPeNDAP data.</P>
</UL>
<UL>
	<LI><P><A HREF="http://opendap.org/user/mgui-html/index.html">OPeNDAP
	Matlab Graphical User Interface</A> is a friendly GUI for reading
	OPeNDAP data.</P>
</UL>
<HR>
<H1><A NAME="Disclaimer"></A>Disclaimer</H1>
<P>This software is provided &quot;as is&quot; without warranty of
any kind. It is covered by a general <A HREF="http://www.csiro.au/legalnotices/disclaimer.html">CSIRO
Legal Notice and Disclaimer</A>.</P>
<HR>
<H1><A NAME="People"></A>People involved in the development of the
interface</H1>
<P>The CSIRO matlab interface has been mostly written by Jim
Mansbridge with some input from Peter McIntosh and Rose O'Connor (all
of CSIRO).</P>
<P>Early versions of a mex file interface to netCDF (called xnetcdf)
were worked on by Peter McIntosh and Jim Mansbridge. A series of much
improved versions were created by Chuck Denham (USGS); these had
names like mexcdf, mexcdf53 and ncmex. John Evans (Rutgers) has then
developed the code further as mexnc and now maintains the project.</P>
<P>The Matlab Command Line Tool (from which loaddap and writedap are
taken) was written by Glenn Flierl (MIT) and James Gallagher (URI).</P>
<HR>
<H1><A NAME="Contact"></A>Contact details</H1>
<P>This web page is maintained by Jim Mansbridge, CSIRO Marine and
Atmospheric Research.</P>
<P><B>Postal address:</B> GPO Box 1538, Hobart, Tasmania 7001,
Australia<BR><B>Phone:</B> [phone] <BR><B>Fax:</B> +61-3-62
32 5123</P>
<P ALIGN=LEFT><IMG SRC="http://www.marine.csiro.au/%7Emansbrid/jmaddress1.gif" NAME="graphics1" ALIGN=BOTTOM WIDTH=287 HEIGHT=29 BORDER=0></P>
<HR>
<P STYLE="margin-bottom: 0in">This page is
<A HREF="http://www.marine.csiro.au/sw/matlab-netcdf.html">http://www.marine.csiro.au/sw/matlab-netcdf.html</A>.
</P>
<HR>
<P STYLE="margin-bottom: 0in">Visitors since 27 October 2005:&nbsp;<!--#include virtual="/cgi-bin/hits"-->
</P>
<HR>
<P ALIGN=LEFT>Further details on the research of the CSIRO Marine and
Atmospheric Research are available through the <A HREF="http://www.cmar.csiro.au/">CMAR
Home Page</A>.</P>
<P ALIGN=LEFT>For more information contact [e-mail]
or telephone [phone]. Unless otherwise indicated all contents
in these web documents are copyright &copy; 1997 CSIRO. 
</P>
</BODY>
</HTML>