matlab-netcdf.html~

matlacb程序包

	string or an integer. If it is a string then it should be the name
	of the variable in the netCDF file or OPeNDAP dataset. The use of an
	integer is a deprecated way of accessing netCDF file data; if used
	the integer then must be the menu number of the n dimensional
	variable as shown by a call to inqnc. 
	</P>
	<LI><P STYLE="margin-bottom: 0in"><B>bl_corner: </B>This is a vector
	of length n specifying the hyperslab corner&nbsp;with the lowest
	index values (the bottom left-hand corner in a 2-space).&nbsp; The
	corners refer to the dimensions in the same order that these
	dimensions are listed in the inqnc description of the&nbsp;variable.
	For a netCDF file this is the same order that they are&nbsp;returned
	in a call to &quot;ncdump&quot;. With an OPeNDAP dataset it is
	the&nbsp;same order as in the DDS. Note also that the
	indexing&nbsp;starts with 1 - as in matlab and fortran, NOT 0 as in
	C. A negative element means that all values in&nbsp;that direction
	will be returned.&nbsp; If a negative scalar (or an empty array) is
	used this&nbsp;means that all of the elements in the array will be
	returned. This is the default, i.e., all of the elements of varid
	will be returned. 
	</P>
	<LI><P STYLE="margin-bottom: 0in"><B>tr_corner: </B>This is a vector
	of length n specifying the hyperslab corner with the highest index
	values (the top right-hand corner in a 2-space). A negative element
	means that the returned hyperslab should run to the highest possible
	index (this is the default). Note, however, that the value of an
	element in the end_point vector will be ignored if the corresponding
	element in the corner vector is negative. 
	</P>
	<LI><P STYLE="margin-bottom: 0in"><B>stride: </B>This is a vector of
	length n specifying the interval between accessed values of the
	hyperslab (sub-sampling) in each of the n dimensions.&nbsp; A value
	of 1 accesses adjacent values in the given dimension; a value of 2
	accesses every other value; and so on. If&nbsp;no sub-sampling is
	required in any direction then it is allowable&nbsp;to just pass the
	scalar 1 (or -1 to be consistent with the corner&nbsp;and end_point
	notation). Note, however, that the value of an&nbsp;element in the
	stride vector will be ignored if the corresponding&nbsp;element in
	the corner vector is negative. 
	</P>
	<LI><P STYLE="margin-bottom: 0in"><B>order:&nbsp;</B> 
	</P>
	<UL>
		<LI><P STYLE="margin-bottom: 0in">order == -1 then the n dimensions
		of the array will be returned&nbsp;in the same order&nbsp;as
		described by a call to inqnc(file)&nbsp;or &quot;ncdump&quot;. It
		therefore corresponds to the order in which the indices are
		specified in corner, end_point and stride. This is the default. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">order == -2 will reverse the
		above order. Because&nbsp;matlab's array storage is row-dominant
		this is actually a little quicker but the difference is rarely
		significant. 
		</P>
	</UL>
	<LI><P STYLE="margin-bottom: 0in"><B>change_miss:&nbsp;</B>Missing
	data are indicated by the attributes _FillValue, missing_value,
	valid_range, valid_min and valid_max. The action to be taken with
	these data are determined by change_miss. 
	</P>
	<UL>
		<LI><P STYLE="margin-bottom: 0in">change_miss == 1 causes missing
		values to be returned unchanged. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">change_miss == 2 causes missing
		values to be changed to NaN (the default). 
		</P>
		<LI><P STYLE="margin-bottom: 0in">change_miss == 3 causes missing
		values to be changed to new_miss (after rescaling if that is
		necessary). 
		</P>
		<LI><P STYLE="margin-bottom: 0in">change_miss &lt; 0 produces the
		default (missing values to be changed to NaN). 
		</P>
	</UL>
	<LI><P STYLE="margin-bottom: 0in"><B>new_miss:&nbsp;</B>This is the
	value given to missing data if change_miss == 3. 
	</P>
	<LI><P STYLE="margin-bottom: 0in"><B>squeeze_it: </B>This specifies
	whether the matlab function &quot;squeeze&quot; should be applied to
	the returned array. This will eliminate any singleton
	array&nbsp;dimensions and possibly cause the returned array to have
	less dimensions than the full array. 
	</P>
	<UL>
		<LI><P STYLE="margin-bottom: 0in">squeeze_it ~= 0 causes the
		squeeze function to&nbsp;be applied.&nbsp; This is the default.
		Note also that a 1-d array is returned as a column vector. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">squeeze_it == 0 so that squeeze
		will not be applied. 
		</P>
	</UL>
	<LI><P STYLE="margin-bottom: 0in"><A NAME="rescale_opts"></A><B>rescale_opts:
	</B>This is a 2 element vector specifying whether or not rescaling
	is carried out on retrieved variables and certain attributes. The
	relevant attributes&nbsp;are _FillValue', 'missing_value',
	'valid_range',&nbsp;'valid_min' and 'valid_max'; they are used to
	find missing values of the relevant variable. The option was put in
	to deal with files that do not follow the <A HREF="http://www.unidata.ucar.edu/software/netcdf/docs/BestPractices.html">netCDF
	conventions</A> (usually because the creator of the file has
	misunderstood the convention). For further discussion of the problem
	see <A HREF="#Confusion">here</A>. <I><U>Only use this option if you
	are sure that you know what you are doing</U>.</I> 
	</P>
	<UL>
		<LI><P STYLE="margin-bottom: 0in">rescale_opts(1) == 1 causes a
		variable read in by getnc.m to be rescaled by 'scale_factor' and&nbsp;
		'add_offset' if these are attributes of the variable; this is the
		default. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">rescale_opts(1) == 0 disables
		rescaling of the retrieved variable. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">rescale_opts(2) == 1 causes the
		attributes '_FillValue', etc to be rescaled by 'scale_factor' and
		'add_offset'; this is the default. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">rescale_opts(2)&nbsp;== 0
		disables the rescaling of the attributes '_FillValue', etc.</P>
	</UL>
	<LI><P STYLE="margin-bottom: 0in"><B>err_opt: </B>This is an integer
	that controls the error handling in a call to getnc.</P>
	<UL>
		<LI><P STYLE="margin-bottom: 0in">err_opt == 0 on error this prints
		an error message and&nbsp;aborts. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">err_opt == 1 prints a warning
		message and then returns an empty array. This is the default. 
		</P>
		<LI><P>err_opt == 2 returns an empty array. <U><I>This is a
		dangerous option and should only be used with caution</I></U>. It
		might be used when&nbsp;getnc is called in a loop and you want to
		do your own error handling without being bothered by warning
		messages. 
		</P>
	</UL>
</OL>
<H3><A NAME="getnc_specifying_arguments"></A><B>Arguments - ways of
specifying</B></H3>
<P><BR>Specifying up to 11 arguments to getnc can be complicated and
confusing. To make the process easier getnc will accept a variety of
types of input. These are given as follows:</P>
<UL>
	<LI><P><B>Specify all 11 arguments</B>.&nbsp;Thus we could make a
	call like: 
	</P>
</UL>
<P STYLE="margin-left: 0.42in">&gt;&gt; values = getnc(file, varid,
bl_corner, tr_corner, stride, order, change_miss, new_miss,
squeeze_it, rescale_opts, err_opt);</P>
<UL>
	<LI><P><B>Use default arguments</B>. Only the first 2 arguments are
	strictly necessary as the other arguments all have defaults. The
	following call would retrieve the entire contents of the named
	variable: 
	</P>
</UL>
<PRE STYLE="margin-left: 0.42in; margin-bottom: 0.2in">&gt;&gt; values = getnc(file, varid);</PRE><P STYLE="margin-left: 0.42in">
If you want non-default behaviour for one or more of the later
arguments then you can do something like:</P>
<PRE STYLE="margin-left: 0.42in; margin-bottom: 0.2in">&gt;&gt; values = getnc(file, varid, -1, -1, -1, -1, change_miss, new_miss);</PRE><P STYLE="margin-left: 0.42in">
In this case there are 4 arguments specified and 7 with default
values used.</P>
<UL>
	<LI><P><B>Use a structure as an argument.</B> From version 3.3
	onwards it is possible to pass a structure to getnc. This is
	illustrated below: 
	</P>
</UL>
<PRE STYLE="margin-left: 0.42in">&gt;&gt; x.file = 'fred.nc';
&gt;&gt; x.varid = 'foo';
&gt;&gt; x.change_miss = 1;
&gt;&gt; values = getnc(x);</PRE><P STYLE="margin-left: 0.42in">
This specifies 3 arguments and causes defaults to be used for the
other 8.<BR>Note that it is possible to mix the usual arguments with
the passing of a structure - it is only necessary that the structure
be the last argument passed. We could achieve the same effect as
above by doing:</P>
<PRE STYLE="margin-left: 0.42in">&gt;&gt; x.change_miss = 1;
&gt;&gt; values = getnc('fred.nc', 'foo', x);</PRE><H3>
<A NAME="getnc_examples"></A><B>Examples</B></H3>
<P>In the following examples we use our standard OPeNDAP file
&quot;http://www.marine.csiro.au/dods/nph-dods/dods-data/test_data/test_1.nc&quot;
to illustrate the usage of getnc 
</P>
<UL>
	<LI><P><FONT SIZE=4><FONT FACE="Albany, sans-serif">Get an entire
	array</FONT></FONT> 
	</P>
</UL>
<P>The simplest command line call to make is the following:</P>
<PRE>&gt;&gt; file = 'http://www.marine.csiro.au/dods/nph-dods/dods-data/test_data/test_1.nc';
&gt;&gt; u = getnc(file, 'u');</PRE><P>
The first argument specified is the file name or url. The second
argument is the name of the variable - we could have found this by
using inqnc. The result is that the entire contents of the <I>u</I>
variable will be returned to the matlab session.</P>
<P>Alternatively we could have passed a structure to getnc to get the
same answer.</P>
<PRE>&gt;&gt; x.file = 'http://www.marine.csiro.au/dods/nph-dods/dods-data/test_data/test_1.nc';
&gt;&gt; x.varid = 'u';
&gt;&gt; u = getnc(x);</PRE>
<UL>
	<LI><P><FONT SIZE=4><FONT FACE="Albany, sans-serif">Get part of an
	array</FONT></FONT> 
	</P>
</UL>
<P>We may only want a part of the variable and that is what the 3
arguments (<I>bl_corner, tr_corner, stride</I>) are about. If we use
inqnc to consider the <I>u</I> variable described in our example file
we see that it has two dimensions (<I>(depth1 depth2</I>) in that
order. We say that the variable is in a 2-dimensional rectangle. We
also saw that there are 12 and 11 points in each of the directions.
Thus we can imagine extracting a subset of the data known as a
hyperslab. The argument <I>bl_corner</I> specifies the bottom left
hand corner of the hyperslab, <I>tr_corner</I> specifies the top
right-hand corner and <I>stride</I> specifies the sampling done. An
example to illustrate this is shown below.</P>
<PRE>&gt;&gt; u = getnc(file, 'u', [-1 3], [-1 9], [-1 2]);
&gt;&gt; size(u)
ans =
 12 4</PRE><P>
The 1<SUP>st</SUP> element in each of these arguments is -1 to
indicate that we want to retrieve every point in that direction.
Hence the 1<SUP>st</SUP> dimension of <I>u </I>is of length 12 &ndash;
the full number of elements in the <I>depth1</I> dimension. Now
<I>bl_corner</I>(2) = 3, <I>tr_corner</I>(2) = 9 and <I>stride</I>(2)
= 2. This means that in the <I>depth2</I> direction we want every
secondpoint from the 3<SUP>rd</SUP> to the 9<SUP>th</SUP>, i.e.,
points 3, 5, 7 and 9. Hence the 2<SUP>nd</SUP> dimension of <I>u</I>
is of length 4.</P>
<UL>
	<LI><P><FONT SIZE=4><FONT FACE="Albany, sans-serif">Changing the
	order of the dimensions in the returned array</FONT></FONT> 
	</P>
</UL>
<P>The next argument to discuss is <I>order. </I>In general it is
best not use this option and just use the default (-1). The option
allows you to reverse the dimensions in the returned value. Since
netCDF files store data in row-major order but matlab does the
opposite, it is possible, in principle, to make some efficiencies
when retrieving data from a local netCDF file. However this is rarely
significant and the option is only retained for backwards
compatibility with older versions of getnc. (For OPeNDAP files
setting <I>order</I> = -2 is always less efficient than -1.) 
</P>
<P>The following example illustrates this.</P>
<PRE>&gt;&gt; u = getnc(file, 'u'); 
&gt;&gt; size(u)
ans =
 12 11
&gt;&gt; ut = getnc(file, 'u', -1, -1, -1, -2);
&gt;&gt; size(ut) 
ans =