matlab-netcdf.html

matlacb程序包

<P STYLE="margin-top: 0.17in"><FONT FACE="Albany, sans-serif"><FONT SIZE=4><FONT SIZE=3><FONT FACE="Thorndale AMT">By
not giving a variable or attribute name we get information about all
of the global attributes.</FONT></FONT> </FONT></FONT>
</P>
<PRE>&gt;&gt; file = 'http://www.marine.csiro.au/dods/nph-dods/dods-data/test_data/test_1.nc';
&gt;&gt; att_name_list
att_name_list = 
 'source'
&gt;&gt; att_val
att_val = 
 'Test program'</PRE><P>
In this case there is only one global attribute named source and it
is a string containing Test program.</P>
<UL>
	<LI><P><FONT SIZE=4><FONT FACE="Albany, sans-serif">Get just one
	attribute of a variable</FONT></FONT> 
	</P>
</UL>
<P STYLE="margin-top: 0.17in"><FONT FACE="Thorndale AMT"><FONT SIZE=3>By
giving the variable and attribute names we can get simply the value
of the attribute.</FONT></FONT></P>
<PRE>&gt;&gt; [att_val, att_name_list] = attnc(file, 'u', '_FillValue');
&gt;&gt; att_val
att_val =
 1.0000e+16</PRE>
<UL>
	<LI><P><FONT SIZE=4><FONT FACE="Albany, sans-serif">Get just one
	global attribute</FONT></FONT> 
	</P>
</UL>
<P>A single global attribute can be retrieved by using the name
'global' in the call to attnc as below.</P>
<PRE>&gt;&gt; [att_val, att_name_list] = attnc(file, 'global', 'source'); 
&gt;&gt; att_val 
att_val =
Test program</PRE>
<HR>
<H1><A NAME="ddsnc"></A>ddsnc</H1>
<P>ddsnc returns information about a netcdf file or DODS/OPEnDAP
dataset. The general form of a ddsnc call is:</P>
<P>desc = ddsnc(file)</P>
<P>desc is a matlab structure. For an OPEnDAP data set desc will
contain all of the information in the DDS (<A HREF="http://www.opendap.org/user/guide-html/guide_65.html#id1">Dataset
Description Structure</A>). For a netCDF file desc will be almost
identical. (It cannot be exactly the same since netCDF files are not
identical to OPeNDAP data sets.)</P>
<P><FONT FACE="Albany, sans-serif"><FONT SIZE=5>Examples</FONT></FONT></P>
<P>Information about the Reynolds data set can be found as follows:</P>
<PRE>&gt;&gt; file = 'http://www.marine.csiro.au/dods/nph-dods/dods-data/test_data/test_1.nc';
&gt;&gt; desc = ddsnc(file
desc = 
 variable: [1x14 struct]
 dimension: [1x5 struct]</PRE><P>
desc has 2 fields - variable and dimension. Looking at one element we
see</P>
<PRE>&gt;&gt; desc.variable(2)
ans = 
 type: 'Float32'
 name: 'u'
 dim_statement: {'depth1 = 12' 'depth2 = 11'}
 dim_idents: [2x1 double]</PRE><P>
The first 2 fields tell us that the variable is named 'u' and is a 32
byte float (single precision real). The dim_statement field tells us
that the u variable has 2 dimensions in the order given. For
dim_idents we see</P>
<PRE STYLE="margin-bottom: 0.2in">&gt;&gt; desc.variable(2).dim_idents
ans =
 2
 3</PRE><P>
These integers refer to the dimensions of the u array. Looking at
desc.dimension(2) and&nbsp;desc.dimension(3) we see 
</P>
<PRE>&gt;&gt; desc.dimension(2)
ans = 
 name: 'depth1'
 length: 12
&gt;&gt; desc.dimension(3) 
ans = 
 name: 'depth2'
 length: 11</PRE><P STYLE="margin-bottom: 0in">
That is index 2 points us to the 2nd dimension, depth1 and it has
length 12. (We saw the same information in the dim_statement field
earlier.) A generic program could then retrieve the information by
setting:</P>
<PRE STYLE="margin-bottom: 0.2in">&gt;&gt; ii = desc.variable(2).dim_idents(1);</PRE><P STYLE="margin-bottom: 0in">
and then referring to desc.dimension(ii).</P>
<HR>
<H1><A NAME="whatnc"></A>whatnc</H1>
<P>whatnc lists all of the netCDF files (including compressed ones)
in the current directory. It also lists all of the netCDF files in
the common data set.</P>
<P STYLE="margin-top: 0.17in; page-break-after: avoid"><FONT FACE="Albany, sans-serif"><FONT SIZE=5>Example</FONT></FONT></P>
<P>Below is a possible listing returned by whatnc.</P>
<PRE>&gt;&gt; whatnc
----- current directory netCDF files -----
bar.cdf foo.cdf mycdf.cdf test_1.nc test_timenc.nc
----- current directory compressed netCDF files -----
EMPTY
----- common data set of netCDF files -----
bath_agso_2002.nc soc_climatology.nc
bath_agso_98.nc sst.mnmean.1981-present.nc</PRE><P>
The list under the 1<SUP>st</SUP> heading shows all of the files in
the current directory that seem to be netCDF files. This is based
simply on whether they end in .cdf or .nc. Note that the .cdf suffix
was used in the past to indicate a netCDF file but is no longet
reccommended.</P>
<P>The list under the 2nd heading shows all of the files that end in
nc.gz, nc.Z, cdf.gz or cdf.Z. These are presumed to be compressed
netCDF files.</P>
<P>The 3<SUP>rd</SUP> list shows netCDF files in the area referred to
as the common data directory. This directory will be searched by the
inqnc, attnc and getnc commands and is set by the local system
manager. This is done by simply editing the pos_cds.m file.</P>
<HR>
<H1><A NAME="Installation"></A>Installation</H1>
<P>The CSIRO interface has been installed on both unix and Windows pc
systems. Installation is mostly a matter of copying the appropriate
files to directories and then making them visible to matlab.
Accordingly the experience should easily translate to other operating
systems.</P>
<OL>
	<LI><P>Download either <A HREF="ftp://ftp.marine.csiro.au/pub/mansbrid/matlab_netCDF_OPeNDAP.tar.gz">matlab_netCDF_OPeNDAP.tar.gz</A>
	or <A HREF="ftp://ftp.marine.csiro.au/pub/mansbrid/matlab_netCDF_OPeNDAP.zip">matlab_netCDF_OPeNDAP.zip</A>
	(the files in each are identical).</P>
	<LI><P>Copy the file to a chosen directory and expand it using
	either gunzip and tar or unzip as appropriate. Note that this
	directory needs to be visible to matlab. You may need to use the
	matlab command addpath in your startup.m file to ensure this.
	Alternatively, a system administrator may set this up.</P>
	<LI><P>To be able to read local netCDF files you need to install one
	or more drivers &ndash; they are described <A HREF="#Drivers">here</A>.</P>
	<LI><P>The CSIRO interface needs to be told which driver to use to
	read a given type of file. It can get this information from the file
	CSIRO_get_globals.m. A documented example is included with the
	interface and you should edit it to fit your local requirements.</P>
</OL>
<OL START=5>
	<LI><P>If you have a local data set of netCDF files that you want to
	be accessible to matlab without the user having to specify the path
	name then you can edit the file pos_cds.m. This matlab function will
	be used by getnc, attnc, timenc, inqnc, ddsnc and whatnc when it is
	trying to find a given netCDF file.</P>
	<LI><P>whatnc can print a message that is specific to a given site.
	Simply create a matlab script named message_for_whatnc.m and put it
	in the same directory as whatnc.m. After whatnc has printed its
	primary information it will print the local message that it gets
	from message_for_whatnc.m. A documented example script is included
	with the interface and you should edit it to fit your local
	requirements.</P>
	<LI><P>When the directory structure was expanded in step 1 a
	subdirectory named test was created. To test the installation go to
	this subdirectory, start matlab and type test_all. This gives you
	options to test both the netCDF and the OPeNDAP installations. It
	does that by reading some data from a supplied netCDF file or from
	an OPeNDAP server. The data are compared to those in a supplied
	mat-file. The most common error is setting up the matlab paths
	incorrectly so that part of the interface is not visible to matlab.
	The testing of the OPeNDAP installation <SPAN STYLE="text-decoration: none">may</SPAN>
	fail sometimes because of dropouts in the internet somewhere.</P>
	<P>If you get to the end successfully then test_all will give you a
	timing message. It is interesting to see how much slower it can be
	to access the data remotely via the OPeNDAP interface. 
	</P>
</OL>
<P STYLE="margin-left: 0.79in"><B>Note that when testing the OPeNDAP
installation on a Windows PC there may be a number of warning
messages. These can be because of an old </B><A HREF="#bug1"><B>bug
described here</B></A><B>. If you get to the timing message then
things have worked except for the known bug.</B></P>
<HR>
<H1><A NAME="Drivers"></A>Drivers</H1>
<P>The CSIRO interface is only a wrapper that makes it easier to get
data. The actual retrieval of the data is carried out by drivers that
must be obtained from elsewhere and you will need to install one or
more of these separately. They each have different strengths and
weaknesses which are described below.</P>
<H3><A NAME="toolsUI"></A>toolsUi.jar</H3>
<UL>
	<LI><P><B>Brief description</B>: toolsUI.jar enables access to the
	netCDF and OpeNDAP libraries via the java virtual machine that comes
	included with matlab.</P>
	<LI><P><B>Advantages</B>: This can retrieve both netCDF files and
	data from an OPeNDAP server. It is supported by Unidata (who
	maintain both netCDF and OPeNDAP) and so it is likely to be
	up-to-date. This may be of special importance as later version of
	netCDF files become more popular.</P>
	<LI><P><B>Disadvantages</B>: It may be slower to read netCDF files
	than the mex driver, ncmex. It has lower memory limits than the
	mexnc driver &ndash; on a machine with 3 gB of memory it produced
	&quot;Java.lang.OutOfMemory error &quot; messages retrieving files
	larger than 147 mB. Someone has to edit the file classpath.txt.</P>
	<LI><P><B>Installation</B>:</P>
</UL>
<OL>
	<LI><P>toolsUI.jar is a single jar file that is available from
	<A HREF="http://www.unidata.ucar.edu/software/netcdf-java/">http://www.unidata.ucar.edu/software/netcdf-java/</A>.</P>
	<LI><P>The file classpath.txt needs to be edited. It is necessary to
	comment out the line that contains &quot;mwucarunits.jar&quot;. 
	Then a line pointing to toolsUI.jar should be added so that the jar
	file will be in the static class path. 
	</P>
</OL>
<UL>
	<LI><P>The default classpath.txt file resides in the toolbox/local
	subdirectory of your MATLAB root directory.</P>
	<LI><P>Reference to the &quot;mwucarunits.jar&quot; file is
	eliminated because the file contains an old implementation of the
	Unidata udunits package that conflicts with the more recent version
	that NetCDF-Java uses. (&quot;mwucarunits.jar&quot; is only used by
	the Mathworks &quot;Model-Based Calibration Toolbox&quot;.)</P>
	<LI><P>In the past it was not necessary for the user to add to add
	toolsUI.jar to the static path because the m-file
	&ldquo;CSIRO_add_jar_file_maybe.m&rdquo; added the file to the
	dynamic path. This action was discontinued because it was found that
	the required call to javaaddpath also cleared all global variables
	and could thus interfere with the user's other code. It is not clear
	when (or if) the Mathworks will correct the problem.</P>
</UL>
<H3><A NAME="toolsUI1"></A>mexnc</H3>
<UL>
	<LI><P><B>Brief description</B>: mexnc enables access to the netCDF
	libraries via a mex file. In some cases the OpeNDAP libraries are
	also accessible.</P>
	<LI><P><B>Advantages</B>: Compared to the java driver it is usually
	quicker to read a local netCDF file and has less restrictions on
	memory usage.</P>
	<LI><P><B>Disadvantages</B>: You may need to build the mex file
	yourself on Unix-type systems as it may not be possible to find
	suitable pre-built binaries.</P>
	<LI><P><B>Installation</B>:</P>
</UL>
<OL>
	<LI><P>Look at the web page <A HREF="http://sourceforge.net/projects/mexcdf/">http://sourceforge.net/projects/mexcdf/</A>
	and check the download area. The name of the driver has changed over
	the years and it may be mexnc, mexcdf or mexcdf53. These are all
	essentially the same thing &ndash; the CSIRO interface expects to
	find a mex file named mexnc.mex* on linux boxes and mexnc.dll on
	windows boxes.</P>
	<LI><P>If you find a binary suitable for your machine and matlab
	version download and try this. Otherwise you will need to download
	the source code and make the mex file yourself. (For windows this
	will be a dll.)</P>
	<LI><P>When you finally have the mexfile (or dll) you need to put it
	in the same directory as getnc.m, etc.</P>
	<LI><P>Note that the download page can be a bit confusing because it
	describes other packages that are necessary to install the snctools
	and netCDF toolbox (which are well worth looking at in themselves -
	see <A HREF="#Alternative">Alternative ways of accessing netCDF and
	OPeNDAP data</A>).</P>
</OL>
<H3>Matlab Command Line Tool</H3>
<UL>
	<LI><P><B>Brief description</B>: This package enables access to the
	OpeNDAP libraries.</P>
	<LI><P><B>Advantages</B>: Available as precompiled, standalone
	binaries and mexfiles.</P>
	<LI><P><B>Disadvantages</B>: You will still need to install one of
	the other packages to read local netCDF files.</P>