matlab-netcdf.html

matlacb程序包

>> x.varid = 'u';
>> x.order = -2;
>> ut = getnc(x); 
>> size(ut)
ans =
 11 12</PRE>
<UL>
	<LI><P><FONT SIZE=4><FONT FACE="Albany, sans-serif">Missing Values</FONT></FONT>
		</P>
</UL>
<P>The default behaviour of getnc is to replace missing values in the
data with NaNs. (By missing values we mean those values equal to the
<I>_FillValue</I> or <I>missing_value</I> attribute or outside the
range determined by the <I>valid_min</I>, <I>valid_max</I> or
<I>valid_range</I> attribute. This is discussed in the netCDF user's
guide at
<A HREF="http://www.unidata.ucar.edu/software/netcdf/docs/netcdf/Attribute-Conventions.html#Attribute-Conventions">http://www.unidata.ucar.edu/software/netcdf/docs/netcdf/Attribute-Conventions.html#Attribute-Conventions</A>.)
The pair of arguments <I>change_miss</I> and <I>new_miss</I> can
change this. If <I>change_miss</I> = 1 then any missing values are
returned unchanged. If <I>change_miss</I> = 2 then they are changed
to a NaN (the default, also available as <I>change_miss</I> = -1). If
<I>change_miss</I> = 3 then any missing values are replaced by
<I>new_miss.</I></P>
<P STYLE="font-style: normal">This is illustrated in the following
example &ndash; note that we pass a structure, x, here and have made
sure that x is empty at the start.</P>
<PRE>&gt;&gt; x = [];
&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; x.bl_corner = [12 11];
&gt;&gt; x.tr_corner = [12 11];
&gt;&gt; u = getnc(x)
u =
 NaN</PRE><P>
We use the simplest version of <I>getnc</I> to retrieve the last
value of the array &ndash; we get a NaN because the value actually
stored in the dataset is marked as a missing value. Next we
try&nbsp;<I>change_miss</I> = 1,</P>
<PRE>&gt;&gt; x.change_miss = 1;
&gt;&gt; u = getnc(x) 
u =
 3.0000e+16</PRE><P>
Now, 3.0000e+16, the value actually stored in the file, is returned.
Finally, we use <I>change_miss</I> = 3 to cause the missing value to
be replaced by 1.5 in our matlab array.</P>
<PRE>&gt;&gt; x.change_miss = 3;
&gt;&gt; x.new_miss = 1.5;
&gt;&gt; u = getnc(x) 
u =
 1.5000</PRE>
<UL>
	<LI><P><FONT SIZE=4><FONT FACE="Albany, sans-serif">Singleton
	dimensions</FONT></FONT> 
	</P>
</UL>
<P>The next argument, <I>squeeze_it</I>, deals with singleton
dimensions (i.e., those of length 1). If <I>squeeze_it</I> = 1 (the
default behaviour) then any singleton dimension will be eliminated as
if the matlab function squeeze had been applied. If <I>squeeze_it</I>
= 0 then the singleton dimensions will remain. This is illustrated in
the following examples. 
</P>
<PRE>&gt;&gt; big_var = getnc(file, 'big_var', [-1 2 2 5 -1], [-1 2 2 5 -1]);
&gt;&gt; size(big_var)
ans =
 12 3
&gt;&gt; big_var = getnc(file, 'big_var', [-1 2 2 5 -1], [-1 2 2 5 -1], -1, -1, -1, -1, 0);
&gt;&gt; size(big_var)
ans =
 3 1 1 1 12</PRE><P>
This option is not really necessary any more because matlab has the
squeeze function. It was originally put in to enable backwards
compatibility with earlier versions of <I>getnc </I>written before
matlab dealt with multi-dimensional arrays and so we are stuck with
it.</P>
<UL>
	<LI><P><FONT SIZE=4><FONT FACE="Albany, sans-serif">Error handling</FONT></FONT>
		</P>
</UL>
<P>From version 3.3 onwards getnc has given the user some control
over error handling. In the examples below we ask for a non-existent
variable. The default behaviour (err_opt == 2) returns an empty array
and prints a warning message as below.</P>
<PRE>&gt;&gt; junk = getnc(file, 'junk')
WARNING: junk is not a variable in http://www.marine.csiro.au/dods/nph-dods/dods-data/test_data/test_1.nc
junk =
 []</PRE><P>
Setting err_opt == 1 causes getnc to be aborted due to the
non-existent variable as seen below.</P>
<PRE>&gt;&gt; x = []; 
&gt;&gt; x.err_opt = 1; 
&gt;&gt; junk = getnc(file, 'junk', x)
??? Error using ==&gt; getnc_s&gt;error_handle
ERROR: junk is not a variable in http://www.marine.csiro.au/dods/nph-dods/dods-data/test_data/test_1.nc
Error in ==&gt; getnc_s at 872
 values = error_handle([], mess_str, [], err_opt);
Error in ==&gt; getnc at 211
 values = getnc_s(varargin);</PRE><P>
Finally, can see the dangerous option err_opt == 3 which causes an
empty array to be returned and no error message.</P>
<PRE>&gt;&gt; x.err_opt = 3; 
&gt;&gt; junk = getnc(file, 'junk', x)
junk =
 []</PRE><P STYLE="margin-bottom: 0in">
This might be used when getnc is called in a loop and you don't want
to get a large number of error messages. Of course you should be
careful to handle the returned values properly.</P>
<HR>
<H1><A NAME="timenc"></A>timenc</H1>
<P>timenc finds the time vector and the corresponding base date for a
netCDF file or DODS/OPeNDAP dataset that follows the <A HREF="http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html">COARDS
conventions</A>. In practice this means that time-like variable
should have a units attribute of a certain form. An example is: 
</P>
<P><B>'seconds since 1992-10-8 15:15:42.5 -6:00'.</B></P>
<P STYLE="font-style: normal">This indicates seconds since October
8th, 1992 at 3 hours, 15 minutes and 42.5 seconds in the afternoon in
the time zone which is six hours to the west of Coordinated Universal
Time (i.e. Mountain Daylight Time). The time zone specification can
also be written without a colon using one or two-digits (indicating
hours) or three or four digits (indicating hours and minutes).
Instead of 'seconds' the string may contain 'minutes', 'hours',
'days' and 'weeks' and all of these may be singular or plural and
have capital first letters. The letters 'UTC' or 'UT' are allowed at
the end of the string, but these are ignored.</P>
<P>It is possible to have many different types of calendars but
timenc only implements five at present.</P>
<P>These are necessary because there is some confusion with dates
before October 15 1582 when the <A HREF="http://en.wikipedia.org/wiki/Gregorian_calendar">Gregorian
calendar</A> was introduced. A problem also arises when the reference
date in the units attribute is before this. timenc deals with this by
recognising some of the <A HREF="http://www.cgd.ucar.edu/cms/eaton/cf-metadata/index.html">CF
conventions</A> and returns different answers depending on the value
of the calendar attribute of the time-like variable. Also, some
numerical models like to pretend that every year has the same number
of days - 365, 366 and 360 are all used.</P>
<OL>
	<LI><P>calendar = 'standard', 'gregorian' or is not specified. In
	this case the relevant calculations are done for the true Gregorian
	calendar as decreed by Pope Gregory XIII. This has a discontinuity
	<SPAN STYLE="text-decoration: none">so</SPAN> that the day after 4
	October 1582 is 15 October 1582. This is the calendar almost
	universally used today and what udunits works with today. timenc has
	worked this way since revision 1.10 in 2000.</P>
	<LI><P>calendar = 'proleptic_gregorian'. In this case the relevant
	calculations are done using the matlab functions datenum and datevec
	which simply extend the way our present calendar works backwards
	into the past. This is called the <A HREF="http://en.wikipedia.org/wiki/Proleptic_Gregorian_Calendar">proleptic
	Gregorian calendar</A>. Accordingly, dates are continuous, i.e., the
	day after 4 October 1582 is 5 October 1582, but does NOT correspond
	to historical time anywhere. As well there is a year zero. timenc
	used to work this way before revision 1.10 in the year 2000 and I
	believe that udunits also did at some stage in the past.</P>
	<LI><P>calendar == 'noleap', '365_day'. Here it is assumed that
	every year has 365 days.</P>
	<LI><P>calendar == 'all_leap', '366_day'. Here it is assumed that
	every year has 366 days.</P>
	<LI><P>calendar == '360_day'. Here it is assumed that every year has
	360 days and every month has 30 days.</P>
</OL>
<P>Note that other values of the calendar attribute produce an error
message. This can usually be avoided by the user specifying the
calendar explicitly in the call to timenc.</P>
<P>The general form of a timenc call is:</P>
<P>[gregorian_time, serial_time, gregorian_base, serial_base, sizem,
serial_time_jd, serial_base_jd] = timenc(file, time_var, corner,
end_point);</P>
<P STYLE="margin-bottom: 0in">A full description of the options can
be found by typing help timenc in matlab.</P>
<P STYLE="margin-top: 0.17in; page-break-after: avoid"><FONT FACE="Albany, sans-serif"><FONT SIZE=5>Examples</FONT></FONT></P>
<P>In the following examples we use our standard OPeNDAP file
sst_cac_recon_ltm.nc.</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; [gregorian_time, serial_time] = timenc(file);</PRE><P>
Note that since the time-like variable is named 'time' we did not
even have to put in its name. We now look at the matrix that contains
the gregorian time.</P>
<PRE>&gt;&gt; gregorian_time(1, :)
ans =
 1.0e+03 *
 1.9900 0.0010 0.0010 0 0 0.0000
&gt;&gt; gregorian_time
ans =
 1990 1 1 0 0 0
 1990 1 2 0 0 0
 1990 2 10 12 0 0</PRE><P>
Each row of the the matrix gregorian_time contains a time in year,
month, day, minute, hour, second format. Thus the last date is for
noon, 10 February, 1990. We can see the same thing by looking at the
vector serial_time.</P>
<PRE>&gt;&gt; size(serial_time)
ans =
 3 1
&gt;&gt; datestr(serial_time)
ans =
01-Jan-1990 00:00:00
02-Jan-1990 00:00:00
10-Feb-1990 12:00:00</PRE><P>
serial_time gives the time in the format used by matlab's functions
datenum, datevec and datestr. Thus we can use datestr to print out
the last date.</P>
<UL>
	<LI><P><FONT SIZE=4><FONT FACE="Albany, sans-serif">Get part of an
	array</FONT></FONT> 
	</P>
</UL>
<P>Here we get the 1<SUP>st</SUP> and 2<SUP>nd</SUP> dates.</P>
<PRE>&gt;&gt; [gregorian_time, serial_time] = timenc(file, 'time', 1, 2);
&gt;&gt; datestr(serial_time) 
ans =
01-Jan-1990 00:00:00
02-Jan-1990 00:00:00</PRE>
<HR>
<H1><A NAME="attnc"></A>attnc</H1>
<P>attnc returns selected attributes of a netcdf file or DODS/OPeNDAP
dataset. The first form of an attnc call is:</P>
<P><B>att_val = attnc(file, var_name, att_name);</B></P>
<P>In this case it simply returns the value of a named attribute. You
can use the var_name 'global' to retrieve a global attribute.</P>
<P>The second form of the call is:</P>
<P><B>[att_val, att_name_list] = attnc(file, var_name, att_name);</B></P>
<P>In this case all of the attributes and their names are returned in
cells named att_val and att_name_list.</P>
<P><FONT FACE="Albany, sans-serif"><FONT SIZE=5>Examples</FONT></FONT></P>
<P>In the following examples we use our standard OPeNDAP file
test_1.nc.</P>
<UL>
	<LI><P><FONT SIZE=4><FONT FACE="Albany, sans-serif">Get all the
	attributes of a variable</FONT></FONT> 
	</P>
</UL>
<PRE>&gt;&gt; file = 'http://www.marine.csiro.au/dods/nph-dods/dods-data/test_data/test_1.nc';
&gt;&gt; [att_val, att_name_list] = attnc(file, 'u');
&gt;&gt; length(att_val)
ans =
 10
&gt;&gt; att_val{1}
ans =
u,5_januarys
&gt;&gt; att_name_list{1}
ans =
long_name</PRE><P STYLE="margin-top: 0.17in; page-break-after: avoid">
<FONT FACE="Thorndale AMT"><FONT SIZE=3>Here we retrieve all of the
attributes for the variable <I>u. </I>We see that there are 10
elements in each cell and that the first attribute has name <I>long_name</I>
and is a string containing <I>u,5_januarys.</I> </FONT></FONT>
</P>
<UL>
	<LI><P><FONT SIZE=4><FONT FACE="Albany, sans-serif">Get all of the
	global attributes</FONT></FONT> 
	</P>
</UL>